doc-update

把对话里得到的可复用约定沉淀进文档。这些文档的首要读者是模型，每一句都要能改变模型的行为。

1. 列候选

回顾对话，找出以下事件：

类型	信号
纠正	用户否决了做法，根源是文档缺失或写错
新约定	用户给出了从代码推断不出的规则
文档矛盾	文档写的路径、字段、规则与代码对不上
流程发现	某个 skill 的步骤或触发条件在实际使用中需要调整

只收下次对话还会用到的约束。代码能直接读出的模式归代码，本次进度归 issue，调试过程和修复配方归 commit。

完成条件：对话中每一次纠正、每一条新约定都已归入候选，或写明了排除理由。

2. 定位单一真相源

去处按 .claude/CLAUDE.md「文档自维护规范」的表就近选；README 与 CLAUDE.md 的分界见同文件「设计文档位置」末段。

每条规则只有一个单一真相源。落笔前用关键词和同义表述全仓库搜这条规则的旧口径，给每处命中标注：

• 真相源：在原条目上改，写全
• 指针：同一含义的其他副本（常见于 CLAUDE.md、SKILL.md、references/ 各抄一份），改成一句「见 X」或删掉
• 无关：只是字面相似

完成条件：搜索命中的每一处都有标注。

3. 确认

用户已在对话中明确说出规则内容时，直接进入第 4 步。

由 Claude 推断出的候选，逐条用 AskUserQuestion 确认：发现了什么、拟写入的内容（不超过 3 行）、目标位置。选项至少含「写入」「跳过」，每次最多 4 条并列。

4. 起草

逐句按以下原则写：

• 写目标行为：用正向句说该怎么做。禁止句只留给无法正向表述的硬护栏，并紧跟该怎么做
• 过 no-op 检验：逐句问「删掉这句，模型会做错吗」，不会就删整句
• 用关键词收拢：同一意思在几处换着说法出现时，换成一个模型本来就懂的词（如「单一真相源」「就近」）统一表达
• 同一概念放一起：一条规则的定义、例外、例子放在同一标题下
• 步骤带完成条件（SKILL.md）：每步以可检查的完成条件收尾，能写成「每一处都……」就不写成「给出一份……」
• 按分支分层（SKILL.md）：每次运行都用到的留在 SKILL.md；只有部分分支用到的细则放 references/，在 SKILL.md 里用一句话写明何时去读
• description 只写触发分支（SKILL.md）：一个分支一种说法，同义说法合并；skill 做什么留给正文

5. 实施并修剪

在语义最近的位置做最小修改，同时修剪改动所在段落：被新规则覆盖或推翻的旧句、与代码现实矛盾的句子一并删除，让每个段落只剩一种口径。

完成条件：第 2 步标注的每一处都已处理，改动段落内没有与新规则冲突的句子。