文档同步
代码和其文档应在同一个提交中一同变更。错误的文档比没有文档更糟糕。
文档出错的三种方式
- 过时。 文档仍描述旧的行为、名称或命令。
- 缺失。 新行为、新命令或新设置没有文档。
- 重复。 同一事实位于两个地方。后来一个副本变更而另一个没有。
步骤
- 查看变更内容。
git diff --cached --stat git diff --stat - 查找仓库自身的规则。 阅读
CLAUDE.md、CONTRIBUTING.md和docs/README.md。如果它们规定了哪个文档负责哪个主题，请遵循它们。这些规则优先于第3步。 - 将每个变更路由到其所属文档。 使用
resources/doc-routing.md。每个事实只有一个归属地。其他文档链接到该归属地。 - 查找过时引用。 对于您重命名或移除的每个名称（函数、标志、端点、设置、文件路径、命令）：
git grep -n '<旧名称>' - 编辑。 仅修改因代码变更而变得错误或不完整的内容。不要重写不相关的章节。如需清晰措辞，如果已安装
simple-english技能，可以使用它。 - 一同提交。 将文档变更与代码一同暂存。不要将它们放在后续的 PR 中。
- 报告。 列出您修改的文档。如果没有任何文档需要变更，请用一行说明原因。例如：“无文档变更：内部重构，未改变行为、命令或设置。”
当所属文档不明确时
询问用户。不要为了回避问题而创建新文档。
一个有用的判断标准：这是一个关于当前状态的事实（设置、版本、状态）吗？如果是，放在参考或状态文档中。这是一个流程（某人遵循的步骤）吗？如果是，放在拥有该流程的指南、运行手册或技能中。
规格说明优先
如果仓库中有 SPEC.md（参见 engineering:spec-writing）或 .gener8v/specifications/ 下的 gener8v 规格说明，它们定义了预期行为。
- 如果您的变更符合规格说明所述，则规格说明无需编辑。
- 如果您的变更与规格说明矛盾，请停止。告知用户。首先通过其拥有者修改规格说明：
SPEC.md由engineering:spec-writing管理，管道规格说明由gener8v:specification管理。不要静默地修改规格说明以匹配代码。
管道文档
不要手动编辑 .gener8v/ 下的文件。gener8v 管道技能会编写和更新它们。
相关技能
engineering:documentation-bootstrap：当整个文档缺失（而不仅仅是一个段落）时使用。engineering:github-pr-merge：在 PR 前运行此检查。engineering:github-release：读取本技能保持最新的 CHANGELOGUnreleased章节。