# CLAUDE.md

1. 先想清楚再动手——不臆测；不确定就问；存在多种解读时摆到台面上，不默默选；权衡讲清楚

2. 简单优先——解决问题所需的最少代码；不做预判性设计；不加未被要求的灵活性；不为不可能发生的场景写错误处理

3. 外科手术式改动——只碰必须碰的；不"顺手优化"周边；匹配现有风格；只清理本次改动制造的孤儿（import / 变量 / 函数），不静默删改动前就存在的死代码

4. 以目标驱动执行——把任务转为可验证目标（"修 bug" = "写复现测试 → 让它通过"）；多步任务先给简短计划（步骤 → 验证点）

5. 改动入 changelog——每次落地的项目改动都追加到 `CHANGELOG.md`；新条目置顶；按日期分组，正文分 `新增 / 变更 / 修复 / 移除`；纯实验、被回滚、未提交的尝试不写

6. 改动同步文档——代码落地时,同步更新对应规格文档(与 changelog 一样属"收尾动作");按下表对照,改了哪类就检查哪份,过期即改:

   | 改了什么 | 必须检查/同步 |
   |---|---|
   | 接口/契约(端点、字段、校验) | `docs/02 §5`、`docs/06`、`apps/api/README`、`apps/web/src/api/types.ts`(+ `packages/api-types`) |
   | 取数/口径/表结构 | `docs/02 §6`、`docs/03` |
   | IA/导航/产品范围 | `docs/01`、`README` 能力域表 |
   | UI 控件/文案/视觉/交互 | `docs/04` |
   | 目录/模块/运行/部署架构 | `docs/07`、`docs/02 §10`、`README`、`infra` |

   纯内部实现细节(不改契约/口径/IA/视觉/结构)无需动文档。定期或发版前可跑 `/docs-check` 审计漂移。

7. 新模块 PRD 先行——开一个新的分析模块 / L3 报表(垂直切片)前,**先**在 `docs/01` §4 状态表登记 + 写模块级 PRD(`docs/prd/<模块>.md`:定义/口径/时间能力/页面/验收)并对齐,**再**写代码;不"边做边补"。小改/修复不受此限(照规则 6 收尾即可)。迭代与发布流程见 `docs/08`。