---
name: documentation-management
description: 管理工程中的文档资产与长期上下文。当用户要求新建、更新、整理、合并、压缩、归档或删除 README、运行手册、公共接口文档、架构文档、ADR、变更日志、代码注释、AGENTS.md 或项目规则，代码变化造成文档事实漂移，长期文档出现过程流水账，arch-design 的已确认决定需要长期沉淀，或需要为工程师与 Agent 分别维护可发现、低冗余的项目上下文时使用。
---

# 工程文档管理

文档是代码之外最重要的工程上下文。目标不是写更多文档，而是让正确的读者在需要时拿到准确、最小、可维护的信息。

## 核心约束

1. **默认不新增。** 先搜索现有资产，再从更新、删除、合并、压缩、归档、晋升和新建中选择长期维护成本最低的动作。
2. **文档债是技术债。** 漂移、重复、过长或无人消费的文档不是中性存在：它们随每次会话进入上下文，消耗 token 并误导 Agent。持续维护不是可选项；接触某文档时，在不扩大当前任务范围的前提下顺手完成确定、低风险的更新、合并、压缩或删除。
3. **一个事实只有一个当前信息源。** 其他入口只导航，不复制正文。代码、schema、配置或生成物已经能可靠表达的事实，不再手工维护第二份。
4. **先确定消费者。** 新文档必须明确服务人类、Agent，还是双方共同消费。命名即信号：`README.md`、`ONBOARDING.md` 等传统人类入口默认面向人类，其余 markdown 默认按 Agent 文档标准维护。共享不是默认答案；只有 schema、ADR 等共同事实或决策记录确实被双方使用时才采用共享资产，并分别设计发现入口。
5. **纯人类文档不挂到 `AGENTS.md`。** README、教程、背景叙事和只面向人的运行说明不因“Agent 也许有用”而进入 Agent 指令入口。Agent 真正需要的当前约束，应提炼成简短的 Agent 文档；Agent 确实需要阅读的共享事实或决策记录可以由对应作用域索引。
6. **区分 Agent 资料与 Agent 指令。** Agent 阅读的架构文档、接口契约、ADR 等工程资料沿用各自的文档结构；只有提示词、项目规则或标准操作流程（SOP）等直接控制 Agent 行为的指令，才按目标、成功标准、约束、权限边界、工具路由、输出契约和停止条件组织。
7. **长期文档不记过程流水账。** `AGENTS.md`、`docs/rules/`、README、运行手册、当前架构文档和 ADR 等长期资产只保存能脱离当前任务独立成立的当前事实或正式决定。未经用户明确授权，不记录本次实施、评审、修订、提交或上线经过；过程证据放在计划、worklog、拉取请求或问题记录。ADR 保留决定的背景、真实备选、取舍和后果，不保存方案如何逐轮收敛的转录。
8. **归档记录保存当时事实。** 归档是治理动作，不是直接移动文件：迁移前先评估其中是否有应晋升为 ADR 或稳定文档的长期决定，迁移时同步修复或移除指向旧路径的活文档链接。worklog 和已被取代的决策记录通常不追赶当前实现；当前入口应指向新的有效事实。
9. **从证据写文档。** 读取当前代码、配置、接口和测试后再修改文档，不用旧文档互相证明。

## 流程

### 1. 建立文档上下文

- 用 `git rev-parse --show-toplevel` 确认仓库根，读取适用的 `AGENTS.md`、`CLAUDE.md` 和仓库文档目录约定。
- 说明本次变化的事实、消费者、消费场景、当前信息源和预期寿命。
- 搜索同主题的活文档、代码注释、schema、示例和归档记录；区分当前事实与历史快照。

### 2. 选择资产与动作

| 需要承载的上下文 | 首选资产 |
|---|---|
| 人类安装、理解和日常开发入口 | `README` 或开发指南 |
| 人类执行生产操作、排障和恢复 | 运行手册 |
| 公共接口契约 | 类型、schema、OpenAPI 或接口参考 |
| 当前稳定架构、模块关系和数据流 | `docs/architecture/` 下的架构文档 |
| 昂贵、长期且难以逆转的已确认技术决定 | ADR |
| 代码附近才看得懂的不明显原因或约束 | 内联注释 |
| Agent 的项目约束与导航 | `AGENTS.md`、兼容入口和 `docs/rules/` |
| 当前拉取请求的临时设计与规划 | `docs/specs/`，就绪前晋升、归档或删除 |
| 跨多个拉取请求的共同契约和状态 | `docs/long-running-specs/` |
| 当时过程与决定的历史证据 | `docs/worklog/` |

若现有资产已承担相同职责，先通读相关段落，再按以下顺序收敛，而不是默认在列表末尾追加一行：

1. 删除失效、重复、无人消费或只描述本次过程的内容。
2. 将零散但仍有效的内容合并、抽象为当前规则或事实。
3. 重写原有段落，使结构和措辞与当前状态一致。
4. 只有新的独立长期事实无法被现有结构吸收时才新增内容。

若差异只有新增、没有删除、合并或重写，先重新判断新增内容是否应替换旧表述、抽象已有内容，或留在临时过程记录中。单行新增不是绝对禁止，但不能成为修改已有长期文档的默认动作。

### 3. 按主要读者写作

#### 面向人类

- 以 overview 为主，配图（如 mermaid）帮助读者建立心智模型；细节交给代码、接口定义和 Agent 文档。
- 以任务和认知路径组织内容，提供足够背景、示例和导航，但不复制可由工具生成的完整事实。
- 命令、路径、默认值、截图和操作步骤必须能从当前工程验证。
- 只保留项目实际采用的章节，不为套模板制造空内容。

#### 面向 Agent

- 先判断资产是供 Agent 查询的工程资料，还是直接约束 Agent 行为的指令。前者遵循架构文档、接口文档、ADR 等对应规范，不强行改写成提示词结构。
- Agent 文档优先承载代码推不出来的事实：外部系统行为、第三方约束、运维事实、领域知识，以及决策的为什么与真实备选。复述代码细节是坏味道，处理动作是下沉为行内注释或删除，不是维护第二份。
- 提示词、项目规则和标准操作流程使用结果优先的短指令：按需写清目标、成功标准、真实不变量、证据要求、授权范围、工具路由、输出契约和停止条件，让模型自行选择高效路径；同一规则只写一次。
- 把稳定、通用的前缀保持精简；任务特定信息放在更近的目录规则、技能或当前任务中，避免污染所有会话。
- 用决策规则代替关键词表和宽泛绝对命令；`必须`、`禁止`、`仅`只用于真正的不变量。
- 分层维护 `AGENTS.md`：仓库根只放全局规则与导航；具有独立职责、命令或约束的子包在自己的根目录维护 `AGENTS.md`。子级只补充或收窄祖先规则，不复制继承内容；每层保持 `CLAUDE.md -> AGENTS.md` 兼容软链。
- 子作用域 `AGENTS.md` 必须由父级 `AGENTS.md` 用单行指针指向：运行时对子作用域的自动加载并不一致，缺少指针的规则等于不存在。这是加载机制的兜底，不是索引目录。
- 其余文档索引是可选优化，不是义务：只索引 Agent 工作真正承重的文档并写明读取条件，说不出读取条件的条目删掉。索引本身也进入上下文，过长的索引清单就是反渐进式披露。多个子包共同使用的文档提升到最近公共祖先，不把局部上下文全部挂到仓库根。
- 不链接只服务人类阅读的材料。若其中有 Agent 必须遵守的当前事实，提炼成独立、短小、可执行的 Agent 规则，并让人类文档按需指向该事实源。

#### 双方共同消费

- schema、公共契约、稳定架构事实和 ADR 可以同时服务人类与 Agent；不要因内容可读就把它们一律归为人类文档。
- 共同资产保持事实或决策中心，不混入只服务某一类读者的冗长教学。若 Agent 工作确实需要它，由最近作用域的 `AGENTS.md` 索引，并写清读取条件。

### 4. 处理架构决策记录

- 只记录已经确认、长期有效且未来可能被重新争论的昂贵决定。普通实现细节、易逆选择、需求行为和临时计划不写 ADR。
- 价值排序是为什么 > 是什么：背景、约束和真实备选与取舍才是长期价值，结论本身只需要一句话；不记录初稿、评审轮次、修订提交或上线经过。
- 从已确认的 `arch_design.md` 提炼决定，不复制整份设计，不重新打开已经完成的方案评审。
- 遵循项目已有 ADR 约定；没有约定时写入 `docs/architecture/ADR-<连续序号>-<标题>.md`。
- 已接受的 ADR 不静默改写历史理由。决定变化时新增 ADR，并把旧记录标为被取代或已废弃；草稿、重复或从未生效的记录可以按仓库规则删除。

各类文档的最小内容规范见 `references/document-standards.md`。只读取本次涉及的部分。

### 5. 验证与交接

- 验证文档中的命令、链接、路径、版本、接口和示例；无法执行时说明证据缺口。
- 反向搜索旧名称、旧路径、旧默认值和重复正文，确认当前信息源没有漂移或分叉。
- 检查长期文档是否混入未经授权的过程流水账；修改已有资产时，确认漂移内容已优先删除、合并或抽象。若差异只有新增，说明为什么它无法被现有结构吸收。
- Agent 上下文额外检查：资料是否沿用正确的文档类型，指令是否由正确作用域的 `AGENTS.md` 发现、无冲突、无重复并按需明确成功与停止条件，以及是否把纯人类叙事误挂到 Agent 上下文。
- 报告本次新增、更新、合并、压缩、归档或删除的资产，以及剩余风险。文档变更仍由 `deep-review` 的 `docs-sync` 独立审查；本技能不代替审查者。