# 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`。
- **安全**：不要在终端输出 API key 或密钥。
- **上下文**：不要读取 `venv/`、`node_modules/` 或大数据文件。

## TDD 工作流

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

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

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

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

## 工作规则

- 一次只做一个功能。
- 不要仅因为添加了代码就标记功能完成。
- 保持变更在所选功能范围内，除非阻塞迫使进行窄范围的支持性修复。
- 不要在实现过程中悄悄更改验证规则。
- 优先使用持久化仓库制品而非聊天摘要。

## 架构约束

项目遵循 `docs/ARCHITECTURE.md` 中定义的层级模型和依赖规则。
修改代码前，确认你了解当前模块属于哪个层级。

提交前运行 `bash scripts/check-architecture.sh` 检查架构违规。

## 运行时可观测性

如果项目有结构化日志，调试时检查：
- 服务初始化事件
- API 调用及其参数
- 关键路径执行记录
- 错误和异常详情

## 技能引用

### 功能重叠领域只用 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

## 路由地图

- `docs/ARCHITECTURE.md`：模块地图、层级模型、依赖规则
- `quality-document.md`：各领域和层级的健康评分
- `feature_list.json`：功能状态的唯一真实来源
- `claude-progress.md`：会话日志和当前验证状态
- `clean-state-checklist.md`：提交前仓库健康检查
- `evaluator-rubric.md`：工作质量评估标准

## 自定义命令

- `/check`：运行完整验证（pytest + mypy + ruff）
- `/status`：查看项目当前状态摘要
- `/handoff`：生成会话交接文档

## 必需制品

- `feature_list.json`：功能状态的唯一真实来源
- `claude-progress.md`：会话日志和当前验证状态
- `init.sh`：标准启动和验证路径
- `session-handoff.md`：大型会话的紧凑交接
- `clean-state-checklist.md`：提交前仓库健康检查

## 完成定义

一个功能只有在以下条件全部满足时才算完成：

- 目标行为已实现
- 必需的验证实际运行了
- 证据记录在 `feature_list.json` 或 `claude-progress.md` 中
- 仓库可从标准启动路径重新启动
- `scripts/check-architecture.sh` 无违规

## 会话结束前

1. 更新 `claude-progress.md`。
2. 更新 `feature_list.json`。
3. 记录任何未解决的风险或阻塞。
4. 运行 `bash scripts/check-architecture.sh`。
5. 如果任何领域或层级有显著变化，更新 `quality-document.md`。
6. 在工作处于安全状态时提交，附带描述性消息。
7. 使仓库足够干净，下一个会话可以直接运行 `./init.sh`。