代码变更后文档自动维护

要解决的问题

在一个迭代周期里，代码改动往往比文档更新快得多。参数调整、接口签名变更、行为细节修改之后，README 或 docs/ 目录下的说明就悄悄过期了。团队依赖有人"记得"回头去改，但这份记忆通常是不可靠的：审查 PR 的人专注于逻辑正确性，文档漂移被反复推迟，直到新人照着旧文档操作踩坑，问题才浮出水面。

这个技能要替代的正是那种"等下次有人想起来"的维护方式。它不假设任何人会主动跟进文档，而是在代码变更发生后自动把文档维护拉进流程里。

如何工作

核心设计是不直接改文档，而是生成一个可审查的 PR。具体路径如下：

• 代码发生变更后，Agent 先分析改动范围，判断哪些文档路径受到影响。
• 根据分析结果生成缺失的文档更新内容，而不是对整个文档做无差别重写。
• 将更新整理成一个可审查的 pull request，让团队成员在合并前看到差异并确认。
• 整个流程基于 GitHub Next 的 update-docs workflow，配合 gh-aw 扩展执行。

附加能力包括：

• Cost Tracker：从 gh-aw 防火墙生成的 token-usage.jsonl 中提取每次运行的 token 开销，并在 PR 上发布摘要，让文档维护的成本可见。
• Markdown Linter：对所有文档文件运行 Markdown 质量检查，输出按优先级排列的违规问题报告，避免格式问题混入文档更新。

适用边界与注意点

这个技能针对的是代码变更驱动的文档更新，适合行为、接口、配置项发生实质性变化的场景。如果改动只涉及内部重构且对外行为不变，生成的文档更新可能没有实际内容。此外，文档质量的最终判断仍依赖审查 PR 的人——Agent 生成的是候选更新，不是不可质疑的终稿。