# 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.

## 5. 功能重叠领域只用Superpowers
- 设计/头脑风暴 → superpowers:brainstorming
- 编写/执行计划 → superpowers:writing-plans/executing-plans
- TDD → superpowers:test-driven-development
- 代码审查 → superpowers:requesting-code-review
- 调试 → superpowers:systematic-debugging
- 验证 → superpowers:verification-before-completion

## 6. 特定技术审查用ECC
- Go代码审查 → everything-claude-code:go-review
- Python审查 → everything-claude-code:python-review
- 安全审计 → everything-claude-code:security-review
- 数据库审查 → everything-claude-code:database-review

## 7. 项目特定规则
- **端口**: 服务使用 9600 端口（不是 8000）
- **LLM**: 使用 ANTHROPIC_API_KEY / ANTHROPIC_BASE_URL / ANTHROPIC_MODEL 配置
- **Gateway**: 多通道架构，新增通道继承 `BaseGateway`（见 `src/butler/gateway/base.py`）
- **消息处理**: 统一通过 `_process_message()` 处理，不要在各 Gateway 中重复逻辑