# CLAUDE.md

你正在一个为长期实现工作而设计的仓库中工作。
优先考虑可靠的完成、跨会话的连续性和明确的验证，而不是速度。

## 启动循环

每次会话开始时：

1. 运行 `pwd` 确认在正确的仓库根目录。
2. 读取 `claude-progress.md`。
3. 读取 `feature_list.json`。
4. 运行 `git log --oneline -5` 查看最近提交。
5. 运行 `./init.sh`。
6. 检查基线验证是否已经失败。

然后选择恰好一个未完成的功能，只做该功能直到验证通过或记录为何被阻塞。

## Python 标准

- **类型注解**：所有函数参数和返回值必须有类型注解。
- **数据校验**：使用 Pydantic 模型，不使用裸字典。
- **文档字符串**：Google 风格，简洁。
- **文件路径**：使用 `pathlib`，不使用 `os.path`。
- **依赖管理**：`requirements.txt` 或 `pyproject.toml`。

## TDD 工作流

- 实现任何逻辑之前，先写或确认失败的测试用例。
- 使用 `pytest` 作为默认测试框架。
- 测试文件放在 `tests/` 目录，与 `src/` 结构对应。
- 运行 `python -m pytest --tb=short -q` 验证。

## Human-in-the-Loop 协议（强制）

生成超过 20 行或修改核心逻辑的代码后，必须自动执行：

1. **自我解释**：简要说明改了什么、为什么改。
2. **结构检查**：是否引入了新依赖？是否改变了函数签名？
3. **风险评估**：这个变更最可能破坏什么？
4. **验证计划**：告诉用户应该运行哪个命令来验证。

## 工作规则

- 一次只做一个功能。
- 不要在没有可运行证据的情况下声称完成。
- 不要重写功能列表来隐藏未完成的工作。
- 不要删除或弱化测试来让任务看起来完成了。
- 使用仓库文件作为记录系统。

## 技能引用

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

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

## 必需文件

- `feature_list.json`
- `claude-progress.md`
- `init.sh`

## 完成门控

一个功能只有在以下条件全部满足时才能标记为 `passing`：

- 目标行为已实现
- 必需的验证实际运行了
- 证据记录在 `feature_list.json` 或 `claude-progress.md` 中

## 会话结束前

1. 更新 `claude-progress.md`。
2. 更新 `feature_list.json`。
3. 记录仍然有问题或未验证的内容。
4. 在仓库处于安全状态时提交。
5. 为下一个会话留下干净的重启路径。