# Documentation Management

> 当用户要求维护工程文档、项目指令或长期事实，文档与代码或部署状态漂移，或需要整理、归档和沉淀已确认决定时使用。

- Skill: `ben2pc/documentation-management` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add ben2pc/documentation-management`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ben2pc/documentation-management/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: ben2pc (https://skillmd.com/u/ben2pc)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ben2pc/documentation-management

---


# 工程文档管理

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

## 核心约束

1. **默认不新增。** 先搜索现有资产，再从更新、删除、合并、压缩、归档、晋升和新建中选择长期维护成本最低的动作。
2. **文档债是技术债。** 遇到漂移、重复、过长或无人消费的文档，或进行指令优化时，在当前任务范围内优先替换、合并或删除旧内容；指令尤其要清理针对旧模型的重复约束和过时补丁，避免只追加例外、越写越多。保留有效事实与行为边界，不为减字削弱契约。
3. **一个事实只有一个当前信息源。** 其他入口只导航，不复制正文。代码、schema、配置或生成物已经能可靠表达的事实，不再手工维护第二份。
4. **先确定消费者。** 用户未明确指定读者时，默认面向 Agent；工程指令优先维护适用作用域的 `AGENTS.md`，工程资料按类型维护，不默认新建 `README.md`。用户明确指定人类或共同读者时按其用途组织；同一事实保持唯一来源，提供必要的发现入口。
5. **按使用条件建立引用。** `AGENTS.md` 只索引当前工作确实需要的资料并说明读取条件。人类指南包含唯一权威安装步骤或约束时，可以直接引用对应章节，不为隔离读者复制事实；只提供背景或叙事、不会影响执行的材料不挂进入口。
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/` |

`validation-results.md` 是交付证据，不是长期设计文档；按 `spec-design` 的结果生命周期归档，保留当次交付范围、验收来源及证据引用。删除或迁移契约时修复结果引用，必要时保留当时要求的简短快照；不把结果晋升为架构文档，也不因规格已归档而丢失后续复验入口。

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

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

内部自检新增内容是否应替换、合并到旧结构，或留在过程记录；真实新增事实可以直接添加，不为让差异好看删除有效内容，也不逐次向用户解释为何只有新增。

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

#### 面向人类

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

#### 面向 Agent

- 先判断资产是供 Agent 查询的工程资料，还是直接约束 Agent 行为的指令。前者遵循架构文档、接口文档、ADR 等对应规范，不强行改写成提示词结构。
- Agent 文档优先承载代码推不出来的事实：外部系统行为、第三方约束、运维事实、领域知识，以及决策的为什么与真实备选。复述代码细节是坏味道，处理动作是下沉为行内注释或删除，不是维护第二份。
- 提示词、项目规则和标准操作流程使用结果优先的短指令：按需写清目标、成功标准、真实不变量、证据要求、授权范围、工具路由、输出契约和停止条件，让模型自行选择高效路径；同一规则只写一次。
- 把稳定、通用的前缀保持精简；任务特定信息放在更近的目录规则、技能或当前任务中，避免污染所有会话。
- 用决策规则代替关键词表和宽泛绝对命令；`必须`、`禁止`、`仅`只用于真正的不变量。
- 分层维护 `AGENTS.md`：仓库根只放全局规则与导航；具有独立职责、命令或约束的子包在自己的根目录维护 `AGENTS.md`。子级只补充或收窄祖先规则，不复制继承内容；每层保持 `CLAUDE.md -> AGENTS.md` 兼容软链。
- 子作用域 `AGENTS.md` 必须由父级单行指针提供发现入口；已发现的适用规则不因缺少指针而失效。
- 其余文档索引是可选优化，不是义务：只索引 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` 发现、无冲突、无重复并按需明确成功与停止条件，以及引用是否有实际消费场景、是否复制了已有权威事实。
- 报告本次新增、更新、合并、压缩、归档或删除的资产，以及剩余风险。文档变更仍由 `deep-review` 的 `docs-sync` 独立审查；本技能不代替审查者。