同步文档
文档在悄然漂移。当一个 README 中引用的一个文件被移动时，没有任何失败。在每个堆叠式 PR 阶段或完成的功能之后、PR 打开之前运行此技能。
此技能的定义包括提交。 它可能在不询问的情况下进行提交，始终提交到当前分支，绝不提交到 main。
何时跳过
- 文档引用的内容没有变化（纯内部逻辑）。仍然在 PR 的“测试”部分写上“文档已检查，无漂移”，以便审查者知道它已经运行过。
- 用户明确表示暂时不想提交文档更改。
清单：docs/DOCS.md
范围内的文档列表存放在 docs/DOCS.md 中，而不是在 AGENTS.md 中，这样常驻上下文不会随着每次同步而增长。
# 文档清单
| 路径 | 归属 | 生成方式 |
|---|---|---|
| README.md | 定位、设置、环境变量、布局 | |
| AGENTS.md | 代理规则 + 项目门禁 | |
| packages/api/README.md | 端点、脚本、环境变量 | |
| docs/api/openapi.json | API 参考 | `pnpm generate:openapi` |
## 冻结（同步时绝不编辑）
- docs/plans/
## 漂移检查
<!-- 每行 grep 对应一个实际发生过的问题，并附上为什么这样做的注释 -->
首次运行： 构建它。扫描根目录和每个包中的 README.md / AGENTS.md / CLAUDE.md、贡献者文档、API 文档（OpenAPI 描述、llms.txt）、技能和规则目录以及环境变量引用（.env.example、配置模式）。记录每个文档涵盖的内容。
每次运行： 你找到的但未列出的文档将被添加，并在同一次提交中完成。
流程
- 审计。 将分支与其基础版本进行差异比较（
git diff <base>...HEAD --stat），并列出文档可能提及的变更：路径、包名、路由、命令和脚本、环境变量、导出的 API、行为、约定。 - 验证。 对于清单中的每个文档，对照代码检查每一个具体声明：每个命名的文件是否存在于该路径，每个命令是否存在于清单中，每个环境变量是否实际被读取，每个路由和导出是否如描述那样存在。阅读代码；不要相信描述文本，包括你之前写的描述。
- 编辑。 修复漂移。描述代码实际做了什么，切勿为了让文档看起来更好而发明行为。如果代码和文档不一致且你无法判断哪个是错误的，则将其标记出来，而不是猜测。
- 重新生成。 运行清单中列出的每个生成器命令。切勿手动编辑生成的文档。
- 运行
docs/DOCS.md中列出的漂移检查。 当同步发现一个可能再次发生的错误（例如旧路径、重命名的命令）时，为此添加一个 grep，并附上解释原因。 - 提交。 按路径暂存文件，切勿使用
git add -A。创建一个原子提交，格式为docs(<scope>): sync <what> with <change>，在当前分支上。 - 如果分支已跟踪远程仓库，则推送（先执行
git pull --rebase）。 切勿推送到main。
规则
- 冻结的历史：
docs/plans/中的设计、计划和工作交接是当时决策的快照。它们在 grep 中会出现；这是预期的，不是漂移。切勿在同步期间编辑它们。 - 探索和技术方案一旦其方向发布或被放弃，就会被删除， 不会作为参考保留。一旦产品知识更深入，探索的结论就是仓库中最不可靠的文本。任何仍然值得了解的内容都会移动到已发布代码的文档中。
- 大小预算： 文档行数计入 PR 预算。如果同步将某个阶段推向超过 500 行，则将其作为堆栈顶部的纯文档阶段落地（参见
stacked-prs）。 - 指针文件保持简短。 一个仅指向
AGENTS.md的CLAUDE.md或GEMINI.md应该保持这种方式。不要将内容复制进去。