documentation-management

工程文档管理

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

核心约束

1. 默认不新增。 先搜索现有资产，再从更新、删除、合并、压缩、归档、晋升和新建中选择长期维护成本最低的动作。
2. 一个事实只有一个当前信息源。 其他入口只导航，不复制正文。代码、schema、配置或生成物已经能可靠表达的事实，不再手工维护第二份。
3. 先确定消费者。 新文档必须明确服务人类、Agent，还是双方共同消费。共享不是默认答案；只有 schema、ADR 等共同事实或决策记录确实被双方使用时才采用共享资产，并分别设计发现入口。
4. 纯人类文档不挂到 AGENTS.md。 README、教程、背景叙事和只面向人的运行说明不因“Agent 也许有用”而进入 Agent 指令入口。Agent 真正需要的当前约束，应提炼成简短的 Agent 文档；Agent 确实需要阅读的共享事实或决策记录可以由对应作用域索引。
5. 区分 Agent 资料与 Agent 指令。 Agent 阅读的架构文档、接口契约、ADR 等工程资料沿用各自的文档结构；只有提示词、项目规则或标准操作流程（SOP）等直接控制 Agent 行为的指令，才按目标、成功标准、约束、权限边界、工具路由、输出契约和停止条件组织。
6. 归档记录保存当时事实。 worklog 和已被取代的决策记录通常不追赶当前实现；当前入口应指向新的有效事实。
7. 从证据写文档。 读取当前代码、配置、接口和测试后再修改文档，不用旧文档互相证明。

流程

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/

若现有资产已承担相同职责，优先更新它。内容重复、过期或无人消费时，合并、压缩或删除；只有没有合适信息源时才新建。

3. 按主要读者写作

面向人类

• 以任务和认知路径组织内容，提供足够背景、示例和导航，但不复制可由工具生成的完整事实。
• 命令、路径、默认值、截图和操作步骤必须能从当前工程验证。
• 只保留项目实际采用的章节，不为套模板制造空内容。

面向 Agent

• 先判断资产是供 Agent 查询的工程资料，还是直接约束 Agent 行为的指令。前者遵循架构文档、接口文档、ADR 等对应规范，不强行改写成提示词结构。
• 提示词、项目规则和标准操作流程使用结果优先的短指令：按需写清目标、成功标准、真实不变量、证据要求、授权范围、工具路由、输出契约和停止条件，让模型自行选择高效路径；同一规则只写一次。
• 把稳定、通用的前缀保持精简；任务特定信息放在更近的目录规则、技能或当前任务中，避免污染所有会话。
• 用决策规则代替关键词表和宽泛绝对命令；必须、禁止、仅只用于真正的不变量。
• 分层维护 AGENTS.md：仓库根只放全局规则与导航；具有独立职责、命令或约束的子包在自己的根目录维护 AGENTS.md。子级只补充或收窄祖先规则，不复制继承内容；每层保持 CLAUDE.md -> AGENTS.md 兼容软链。
• Agent 子文档由最近的适用作用域的 AGENTS.md 建立索引，并说明何时读取。多个子包共同使用时，提升到最近公共祖先；不要把局部上下文全部挂到仓库根。
• 不链接只服务人类阅读的材料。若其中有 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 独立审查；本技能不代替审查者。