# Claude Code Guidelines & Rules

## 1. Core Workflow
- **TDD Strictly:** ALWAYS write or ask for a failing test case before implementing logic.
- **Spec-First:** Follow \`PLAN.md\` or \`SPEC.md\`. Do not guess requirements.
- **Plain English:** Explain logic in simple Subject-Verb-Object sentences.

## 2. Python Standards
- **Type Hints:** MANDATORY for all function arguments and returns.
- **Data Validation:** Use \`Pydantic\` models, not raw dictionaries.
- **Docstrings:** Google-style, concise.
- **No 'os.path':** Use \`pathlib\` for file handling.

## 3. Interaction Rules
- **No Hallucinations:** If unsure about a library, ask to check docs.
- **Context:** Do NOT read \`venv/\`, \`node_modules/\`, or large data files.
- **Security:** Never output API keys or secrets in the terminal.
  
## 4. Human-in-the-Loop Protocol (MANDATORY)

After generating any significant code (more than 20 lines or modifying core logic), you MUST automatically perform the following steps BEFORE asking me to proceed:

1.  **Self-Explanation:** Briefly explain *what* you changed and *why*, in Plain English.
2.  **Structural Check:** Did you introduce any new dependencies? Did you change any function signatures?
3.  **Risk Assessment:** What is the most likely thing to break with this change?
4.  **Verification Plan:** Tell me exactly which test command to run to verify this specific change.