Doc update

核心目标

下次换一个全新 Agent 进来，只读现有文档就能顺畅理解上下文、接手并完成工作。

每步更新都以此为检验标准：如果现在换一个 Agent，它不看本次会话、只读这些文档，能顺利干活吗？

与 memory 的边界

• 本 skill 只更新对应 skill 文件或当前项目文档，不读取或写入任何 memory。
• 项目规则禁用 memory 时，本 skill 仍可正常执行；禁止把"禁用 memory"误判为"禁用复盘与文档更新"。

Step 0：判定是否需要执行

跳过条件（任一命中则直接告知用户"本次无需更新"并结束）：

• 纯问答/闲聊，无代码、配置、流程、规则变动
• 所有发现已存在于现有文档（先搜再判断）
• 信息仅对当前会话有用，未来会话不会重现
• 项目规则明确禁止修改 skill / docs

Step 1：回顾会话，提取可复用发现

召回（先扫全）：把本次会话当作即将被永久删除——任何没落进文档的信息都会随之消失。带着这个前提扫一遍会话，重点回放两类不留 artifact 的信息源（代码变动会留在 diff 里，它们只在对话上下文里，最容易漏召回）：

• 逐条回放用户的每一次插话（纠正、要求、否决、建议）。
• 逐段回放自己的试错弯路：反复尝试多轮才走通、中途被否决 / 失败的方案。最终产出只体现正确答案，看不出中间排除过什么；记录时必须带"哪些路走不通 + 根因 + 最终解法"，不只记现象或只记结论。

判据（再筛准）：核心问题——换一个全新 Agent 只读文档，它能顺畅接手吗？ 让它少踩坑、少重新摸索的 → 记；能从代码 / git / 现有文档直接拿到的 → 不记。下列是这条判据的常见命中：

• 新发现的业务规则、设计机制、架构约束
• 踩过的坑（含根因和解法）
• 验证有效的模式或工作流
• 用户给出的偏好/反馈/纠正——判别一次性 vs 长期：话里含「以后 / 每次 / 都 / 不要再」，或是对你已做出动作的纠正 / 否决 / 返工要求 → 默认按长期偏好落盘；纯描述本次任务范围的（如「这次只改 X」）才算仅对当前会话有用
• 代码变动导致的文档失效点
• 本会话曾因索引描述没覆盖任务而找不到 / 找错文档（路由失败）——记下你当时带着什么动作来找（查看 / 优化 / 排查 / 新建 / 改配置…），Step 3c 据此补进索引描述

不记录：

• 代码本身能表达的信息（函数签名、类结构、import 关系）
• git log/blame 能查到的信息（谁改了什么、何时合并）
• 临时调试过程（断点位置、临时日志）
• 已在 AGENTS.md 中记录的规则

Step 2：按决策树分类

信息类型	目标位置	示例
跨项目通用模式/脚本/检查清单	对应 skill 的文件	迁移检查清单、通用审查脚本
项目级行为规范/约束/强制要求	项目根 AGENTS.md	验证流程要求、收工检查清单、启动命令、curl 判断标准
项目业务规则/架构/领域知识	项目 docs/ 下对应子目录	支付回调规则、分账逻辑
用户偏好/反馈/纠正（项目范围）	项目 AGENTS.md 或 docs/	工作流约定、审查规范
项目进度/里程碑	项目 docs/ 下对应子目录	模块迁移完成记录
代码变动 → 已有文档失效	同步更新对应 docs/ 文件	改了回调路由 → 更新回调文档

何时写 AGENTS.md vs docs/：

• AGENTS.md：每次会话都需要遵守的规则、约束、操作规范（AI 行为指令）
• docs/：参考性知识、历史记录、模块细节（人读的文档）

Step 3：执行更新

3a. 更新 skill（仅跨项目通用信息）

• 禁止写入项目特有的类名、表名、配置路径、业务规则
• 如果有可脚本化的重复工作 → 在 skill 的 scripts/ 目录创建脚本，并在 skill 文档中引用说明用途
• 更新 skill 文档时保持现有结构，增量补充

3b. 更新项目文档 / AGENTS.md

1. 先读 AGENTS.md：确认文档语言、索引、目录、命名和模块级覆盖规则。
2. 是否属于 AI 行为规范（强制流程、收工要求、操作约束）→ 写入 AGENTS.md 对应章节。
3. 先按项目文档类型归类，再决定目标文件：
   • 项目规范 / agent 指令 → <项目根>/AGENTS.md
   • 模块规范（按需，仅模块有独立约定时）→ <module>/AGENTS.md
   • 任务域二级索引（按需，仅大项目触发时建）→ docs/<domain>/<DOMAIN>_INDEX.md；判定触发条件见 $doc-compact；根 AGENTS.md 是唯一一级入口，禁止裸 INDEX.md/OVERVIEW.md 与根竞争
   • 领域知识库 → docs/<DOMAIN>_KNOWLEDGE_BASE.md
   • 操作指南 / 使用手册 → docs/<TOPIC>_GUIDE.md
   • 设计方案、重构方案 → docs/design/<TOPIC>_DESIGN.md 或 docs/design/<kebab-case>.md
   • 故障排查记录 → docs/troubleshooting/YYYY-MM-DD-<kebab-case>.md
   • 草稿 / 临时分析 → 不入库，使用 DRAFT_*.md 或 *-draft.md
4. 已有对应文档 → 增量更新，补充新发现。同步检查：若代码变动涉及目录结构变化（新增/迁移包）→ 更新 KB 中 §2.5 物理路径速查；若新增重要类（Service/Component/Builder/Handler）→ 检查 §2.5 文件数/代表类名；若类或方法重命名 → grep KB 中旧方法名锚定引用并替换（方法名锚定形如 ClassName.method()）；若代码/目录被删除 → 从 §2.5 移除已不存在的路径行、从 §3/§5 移除对应入口。
5. 无对应文档 → 按分类、路径和命名规则新建，并在根 AGENTS.md 的「文档导航」加一条（一行、带「何时该读」的一句话用途）；该文档支撑某条具体规则时，在那条规则旁就近补一个 inline 指针。如果是以前从未出现过的新文档类型，同步更新根 AGENTS.md 的文档类型说明。
   • 预置折叠类型的特殊处理：新建的是故障排查或 Review 台账文档时，先数该类现有文档总数——不足 3 篇则在根里直链（正常流程）；达到 3 篇则改为折叠：建对应 <DOMAIN>_INDEX.md（若不存在）、把根里的同类平铺条目全部替换为一条强路由（含「何时跳过 / 是否权威源」）、新文档条目落进 <DOMAIN>_INDEX.md。强路由范例见全局规范「两级索引」节。
6. 删除、迁移或重命名文档 → 搜索全仓引用，同步更新根 AGENTS.md 文档导航与相对链接。
7. 禁止在项目根、源码目录或随机位置随意创建文档，一律按第 3 步的类型归位。
8. 若发现项目文档已大面积失序（索引失效、AGENTS.md 膨胀、CLAUDE.md 被污染、残留 OVERVIEW.md/INDEX.md），不要在复盘里顺手大改，转用 $doc-compact 做整体重整。

3c. 文档索引校对与修复（增量，仅本次触及 / 暴露的条目）

何时做：满足以下任一条件：

• 本次复盘新增 / 迁移 / 重命名了文档
• 本会话曾因索引路由失败而找不到 / 找错文档（Step 1 最后一条信号命中）
• 向现有文档追加了新章节或新领域内容（即使没有新建文档，只要文档覆盖的任务范围变宽了，索引描述就必须同步更新）

范围只限本次触及或本次暴露问题的条目；若发现根 AGENTS.md 索引大面积失序，转 $doc-compact（见 Step 3b 第 8 条），别在复盘里顺手大改。

对每个涉及的文档，逐项校对根 AGENTS.md「文档导航」里它的条目：

1. 存在且唯一：该文档有且仅有一条导航条目；迁移 / 重命名后旧链接已全仓搜索同步、无死链。（死链 / 孤儿 / 唯一性这类机械项可借 $doc-compact 的 scripts/audit.py 跑一遍。）

2. 描述覆盖任务（关键，最易漏）：条目描述必须是「何时该读」句式，且覆盖本会话实际带着的任务触发词，以及该领域天然可能出现的全部任务类型（修改/新建/评审/分析/排查/优化）。自测两句——

   • 回想这次我带着什么动作来找它（查看 / 优化 / 排查 / 评审 / 分析 / 新建 / 改某配置…），描述里有没有那个触发场景？
   • 这次往文档里新加的章节或领域，索引描述有没有覆盖？（向已有文档追加内容是最容易漏更新索引描述的场景）

   本会话只要发生过路由失败 或 文档内容被扩展，就要检查并补全：把缺的触发键补进描述（只增量加，不删原有触发场景）。

3. inline 指针：文档支撑某条具体规则 / 不变量时，那条规则旁有就近 inline 指针（底部导航表只作兜底）。

反模式（命中即改）：

• 描述写成「它讲了什么」（罗列文档内容）而非「带着什么任务该读它」——只列内容的描述路由不了。
• 一个故障 / 单一框架的描述（如只写「排查 X 故障」），却要承接同一文档的其他任务（如「优化 / 查看 X 配置」）——补全任务维度，别只留排查框架。

3d. 修正与本次真相冲突的旧文档（有界）

何时做：本会话确立或纠正了某个逻辑或名词（用户纠正、多方确认后定下的结论），且现有文档里有跟它矛盾的旧结论 / 旧叫法。范围只限本会话实际碰过的概念 / 领域，不全量普查所有文档找矛盾——那是 $doc-compact 的整体体检，不塞进收工复盘。

按全局规范「§5 单一来源」就地改对，不允许把矛盾留成两份文档各执一词：

• 裁定：默认回权威源（产品 / 需求文档、代码）核实再定；用户看过源头后明确推翻源头、坚持按最新认知来的，经确认以用户为准，并在对应文档写一条带日期和理由的【裁定】记录防止下次翻案（格式见 $doc-init 的 references/document-templates.md §6）。
• 传播：裁定后自动改齐、不二次确认。改名（主称谓）在本会话涉及的文档里全量替换、保留实现别名；改逻辑含删 / 大改文档也自动执行，事后在 Step 4 摘要里详列改了 / 删了什么。

Step 4：输出摘要

收工自测：想象一个全新 Agent 现在进来，不看本次会话、只读更新后的文档——它能顺畅接手吗？能 → 输出摘要结束；不能 → 先补完缺失信息，再报完成。

用一句话告知用户更新了什么、在哪里。格式：

已更新：[目标文件路径] — [一句话说明变更内容]