15 · 迁移到你的项目

迁移到你的项目

dsh 的体系很完整，但不需要一次全部搬走。以下是按投入顺序排列的最小子集，每一步都能单独起作用。

1. 写一个短的根 AGENTS.md。只放每次都要遵守的规则，每条一到三行，并让 CLAUDE.md 指向它。
2. 加入推理泄漏与 slop 清单。把第 04 章的八类和"HEAD 读者测试"写进规则或一个 prose skill。
3. 开启严格类型和关键 lint：strict、no-explicit-any、no-floating-promises、ban-ts-comment 带说明长度。
4. 对存量多的坏模式用棘轮基线。记录现有位置，只允许减少。
5. 加入重复检测（jscpd 或 sonarjs 的重复规则）。
6. 规定测试证据：验证外部状态，不断言模型自述；新规则附一个会失败的反例；PR 模板加 Proof 区。
7. 规定推送前只跑覆盖改动的检查，汇报只列实际运行的命令。
8. 统一提交格式：Conventional Commits 加包名 scope，正文写原因和 Validation:；合并时保留测试和评审修复提交。
9. 为决策建一个 notes 目录，只记录持久的理由。
10. 出事故后写复盘，再把规则提炼进规范或门禁。这是整个体系持续生长的方式。

起步模板

下面是按以上原则写的一份根 AGENTS.md 起步稿，可以直接复制后修改：

# AGENTS.md

<一句话说明项目>。改动 src/ 之前先读 docs/architecture.md。

## Commands
pnpm test              # 单元测试
pnpm run lint
pnpm run check:docs    # 文档检查

## Conventions
- 文档和注释写当前状态：不写 "used to / no longer"，不引用会话里的决策编号或未提交的草稿（[规则](docs/prose.md)）。
- 注释只写非显然的契约：行为、失败、所有权、时机；不复述代码，不为自己辩护。
- 每个抽象、配置项、兼容路径都要有当前的消费者；没有就删除。
- 默认值在显式的 resolve 步骤里给出，不在执行函数里写隐藏的 `?? default`。
- 禁止新增 `as unknown` 和没有理由的 `any`；存量只减不增。
- 空 catch 写明吞掉的错误和原因，try 只包一条语句。
- 进入模型请求的输入必须能从日志重建。
- 每条事实只有一个归属，其他地方放链接。

## Evidence
- 测试验证外部状态，不断言模型的自述。
- 新增的检查规则附一个会被它拒绝的非法用例。
- 推送前只跑覆盖本次改动的检查；汇报时只列实际运行过的命令。

## Git
- 提交信息用 `type(scope): 动词开头的行为描述`，scope 写包名。
- 正文写原因；末尾用 `Validation:` 列出实际运行的检查、结果和负向对照。
- 破坏性变更在类型后加 `!`，并附升级说明。
- 改写远端历史只用 `--force-with-lease`；测试和评审修复保留为独立提交。