documentation

文档技能

目标

让文档与项目状态保持同步。将过时文档视为项目缺陷，但不要因不影响用户、运营人员、贡献者、架构或未来 Agent 的纯内部变更而造成文档频繁变动。

默认工作流

1. 编辑文档前，以及在文档可能影响实现时进行代码变更前，检查相关的现有文档。
2. 判断任务是否会改变接口、结构或项目信息。
3. 完成代码或项目变更。
4. 通过阅读修改后的文件或运行 git diff 验证实际变更。不要依赖对刚完成工作的记忆。
5. 根据步骤 4 揭示的内容，仅更新受影响的文档。
6. 检查代码、README、文档、变更日志和 Agent 指引之间是否存在矛盾。
7. 在最终回复中总结文档工作。

判断是否更新文档

始终检查是否会影响文档。只有至少一个答案为“是”时，才更新文档：

• 接口： 公共行为、API、路由、命令行命令、配置、环境变量、架构、文件格式、安装或用法是否发生变化？
• 结构： 架构、模块职责、依赖边界、部署、运维或贡献者工作流是否发生变化？
• 知识： 是否作出了重要决策、接受了长期权衡、发现了限制，或明确了技术债务？

对于纯内部重构、测试、格式调整、没有可见行为变化的小型实现修复，或机械式清理，通常不要更新文档；但如果现有文档因此会产生误导，则应更新。

编辑前的依据

文档内容必须严格基于可验证的项目依据。不要概述或转述 Agent 对刚完成工作的理解——应阅读文件或差异输出的实际当前状态：

• git diff 或修改后的文件本身——变更的权威记录
• README、现有文档、AGENTS.md、CLAUDE.md 或包级 README
• 包脚本、Makefile、任务文件、CI 配置、Docker 文件、部署清单
• 源代码导出、路由定义、命令行解析器、配置架构、环境变量验证、数据库迁移
• 测试、夹具、示例、示例配置、发布元数据
• 明确的用户指示

不要编造命令、支持状态、API、性能声明、兼容性承诺或部署步骤。无法验证的内容应写成待确认问题，或直接省略。

生产守则

• 文档变更应与项目变更相称。
• 优先进行精准修改，避免大范围重写、重新组织或仅为统一风格而造成的变更。
• 除非经核实的项目变更使相关内容过时，否则保留警告、限制、合规说明、安全指引和运维手册。
• 不要记录机密、私有凭据、内部令牌或敏感客户数据。
• 不要重复生成内容或权威事实来源；如果 OpenAPI 规范、架构定义、包元数据或生成的参考文档是权威来源，应链接到这些内容。
• 不要创建空文件、占位章节、空白表格或推测性的路线图条目。
• 除非用户提出要求，或现有结构明显有问题，否则不要重命名或移动已确立的文档。

常见借口

过时的文档和文档无谓变动都是缺陷。下面的每个借口都会导致其中一种；「实际情况」列说明了应遵循的规则。

借口	实际情况
“文档可以等等——我会开个后续任务。”	“以后再说”通常意味着永远不做。命令、环境变量、必需步骤或公开行为发生变化时，文档应与改动一同发布。
“代码、架构或错误消息已经能自我说明。”	运维人员和贡献者看的是文档，不是你的验证器。如果设置方式或公开行为发生变化，就要记录下来。
“评审或 CI 会发现文档缺失。”	这意味着之后还要返工，而且在那之前主分支上的文档会一直过时。一次性完整交付改动。
“改动很小、时间很晚，或者负责人说只发布代码就行。”	规模、时机和“直接发布”都不会降低严重性。缺少必需步骤依然属于严重问题。
“既然我在这里，不如顺便重组或重写，让内容更清晰。”	超出范围的改动会掩盖真正的变更，还可能引入回归。编辑应精准克制；清理工作另行提交。
“措辞过时了，干脆顺便更新一下。”	“没有错”就不需要编辑。只修复当前改动导致内容产生误导的文档。
“添加 CHANGELOG 条目或 ADR 会更全面。”	仅影响内部、对用户不可见且没有留下持久决策的改动，两者都不需要。全面意味着记录发生了什么变化，而不是记录所有内容。

危险信号

发现自己准备少写文档时，请停下来重新检查：

• 对于已更改的命令、环境变量、设置步骤或公开行为，想着“文档可以等等／开个后续任务”
• 对于接口或设置方式的变更，想着“代码已经能自我说明”
• 合并值得更新文档的改动，却让文档继续过时

如果没有任何用户可见、结构性或持久性的变化，却准备多写文档，也请停下来重新检查：

• 想着“既然我在这里，不如顺便重组、重写或润色”无关的文档
• 为没有持久决策的内部改动添加 CHANGELOG 条目或 ADR
• 编辑虽已过时但没有错误或误导性的措辞

不确定时，只做能让文档如实反映当前改动的最小修改——不多不少。

更新对照表

应用所有符合条件的行，但编辑幅度应尽可能小，与改动规模相称。

改动	更新内容
新增公开功能	README 或使用文档；如果涉及命令、API、配置或架构，还需更新参考文档
公开 API、路由、CLI、配置、环境变量或文件格式变更	参考文档；如果常见用法发生变化，还需更新 README
重大变更或弃用	README 迁移说明；如果有 CHANGELOG，也要更新；同时更新参考文档
设置、安装或开发工作流变更	README；入门或开发文档；如果有 AGENTS.md，也要更新
部署、运维或事件响应变更	运维文档或操作手册；只有在用户需要入口时才更新 README
架构或依赖边界变更	架构文档；只有在决策持久且存在重要权衡时，才编写 ADR
重要限制或后续事项	路线图、docs/known-issues.md、决策文档或最接近的现有规划文档
发布准备	CHANGELOG 或发行说明；只有当前状态或用法发生变化时才更新 README
文档结构变更（重组、重命名、拆分、合并文档）	更新所有内部链接；如果 README 的 Documentation 部分列出了移动的文件，也要更新；除非用户要求或当前位置明显有问题，否则不要移动已确立的文件

如需了解详细结构和示例，请阅读 references/document-map.md。

创建架构文档、参考文档或操作手册时，请从 references/templates.md 中的填空模板开始。

引导规则

当文档缺失或几乎为空时，根据项目规模创建最小但有用的文档集：

• 微型脚本：README.md；仅在现有 Agent 指南存在时更新它。
• 小型库或 CLI：README.md、可选的 CHANGELOG.md，以及一个聚焦的文档文件（仅当 README 会变得过于庞大时）。
• 应用、服务、基础设施项目或 monorepo：README.md，再加上目前可以用真实信息填充的文档。

不要创建空的占位文档。宁可使用简短准确的 README，也不要使用留有空白的大型模板。

有关引导模板，请阅读 references/bootstrap.md。

决策记录

仅当决策长期有效、难以撤销、跨越模块或运维边界、引入重要依赖，或包含未来 Agent 必须了解的权衡时，才记录 ADR。

不要为常规实现选择、局部清理、小型错误修复，或代码中已有明显依据的选择创建 ADR。

有关 ADR 模板，请阅读 references/adr.md。

现有项目规则

• 如果项目当前的文档风格和文件组织合理，请予以保留。
• 优先更新现有文档，而不是引入新文件。
• 对于大型文档集，仅检查并更新与变更相关的文档，除非存在矛盾，需要进行更广泛的清理。
• 如果项目已有 AGENTS.md、CLAUDE.md、.github/copilot-instructions.md 或包级 Agent 指南，请更新负责该规则的现有文件。
• 仅在引导文档时，或用户要求提供 Agent 指南时，才创建新的 AGENTS.md。
• 在 monorepo 中，将工作区级文档保留在根目录，并将包专属的用法/API 文档放在包内。

新鲜度检查

完成前，按以下严重程度顺序修复文档问题：

1. 严重 — 描述已移除的行为、命令、文件、配置项、路由或设置步骤；遗漏新要求的步骤、环境变量、迁移或运维流程
2. 高 — 与源代码、示例、测试或包元数据相矛盾
3. 低 — 包含无法核实的说法；包含如今已错误或过时的 TODO

最终回复

以简短的文档摘要结束：

Documentation updated:
- README.md: updated usage for the new import command
- docs/reference.md: added API parameters

如果没有更改文档，请说明：

Documentation checked; no updates were needed because behavior, APIs, setup, and architecture did not change.