zeroz-lab Doc Sync — 发布后文档同步
入口/出口
- 入口: 已合并到主分支的变更
- 出口: 文档一致性报告
- 指向: 完成后进入
reflect-team-documentation（可选）或回到项目工作 - 前置加载: CANON.md
- 输出路径: 完成后进入
ship-workflow-ship
何时不使用
- 代码或产物尚未合并，文档同步会基于不稳定事实
- 只是写新功能文档，不是发布后修正项目真相
- 变更没有影响 README、架构说明、命令、路径、版本或用户文档
核心锚点
Fact vs Narrative Dichotomy
区分事实性更新（路径、版本号、数量、命令）和叙事性变更（功能描述、架构理由、迁移指南）。事实直接改；叙事必须问 human partner。
执行规则：
- 事实性更新（路径/版本/数量/命令/配置字段/链接/拼写）→ 直接执行，不询问
- 叙事性变更（新功能描述/架构理由/新增章节/迁移指南/弃用通知/项目定位）→ 逐条询问 human partner
- 混淆两者 = 文档失去人的视角 = 文档变成谎言
流程
Step 1：Diff 分析
收集合并 commit 涉及的文件：git diff-tree --no-commit-id --name-only -r <merge-sha>
分类变更：代码文件 → 影响 README/ARCHITECTURE/API 文档；配置文件 → 影响部署章节；依赖文件 → 影响安装文档；CI/CD 文件 → 影响 CONTRIBUTING。
Step 2：逐文档审计
交叉引用变更文件与项目文档。检查维度：
| 文档 | 检查内容 |
|---|---|
| README.md | 项目描述、安装步骤、快速开始、特性列表 |
| CLAUDE.md | 命令映射、技能列表、项目结构 |
| AGENTS.md | 入口合同、激活门、命令映射 |
| docs/contracts/*.md | 运行时详细规则（按需加载） |
| ARCHITECTURE.md | 组件关系、数据流、技术栈 |
| CHANGELOG.md | 版本条目、变更类型 |
| CONTRIBUTING.md | 开发流程、PR 规则、CI 说明 |
Step 3：自动更新事实性内容
对事实性不一致直接修复。每处修改记录到文档一致性报告。不修改叙事性内容，不添加新章节。数量变更必须先验证实际数量。
Step 4：询问叙事性变更
对叙事性不一致逐条询问 human partner，每次一个问题。每个问题包含：文件路径 + 具体位置 + 当前内容 + 变更原因。human partner 提供新内容或选择跳过。不替 human partner 写叙事性内容。
Step 5：CHANGELOG 润色
检查 CHANGELOG.md 最新条目。绝不覆盖或删除历史条目。只润色最新条目措辞（更清晰、更一致），保持与已有格式一致。变更类型：Added / Changed / Fixed / Deprecated / Removed / Security，每条以动词开头。
Step 6：跨文档一致性检查
验证同一事实在所有文档中表述一致：版本号、特性列表、组件列表、命令列表、API 端点。不一致时以代码为真实来源更新文档。
Step 7：可发现性检查
确认每个文档都能从入口点（README.md 或 CLAUDE.md）通过链接到达。孤立文档需添加引用。
验证证据
输出或记录必须包含：输入/来源、执行动作、验证结果、阻塞/回退。
常见说辞
| 说辞 | 现实 | 后果 |
|---|---|---|
| "文档以后再更新" | "以后"永远不会来。代码变更时同步更新成本最低。 | 事后补文档耗时 ×3-5；新人按旧文档操作 = 环境 +2h |
| "CHANGELOG 自己写就行" | AI 润色措辞，变更的业务意义只有 human partner 知道。 | 叙事不准确 → 用户误解变更影响 → 升级决策失误 |
| "README 不需要那么详细" | README 是新人的第一个文件。少一个步骤 = 新人多花一小时。 | 每个新人多花 1h × 10 人 = 10h 团队浪费 |
| "这个文档没人看" | 没人看是因为过时了。保持准确的文档会被发现和使用。 | 过时 → 信任崩塌 → 团队不再参考任何文档 |
| "自动更新就行，不用问" | 事实自动更新。叙事、判断、理由不能。 | 自动写叙事 → 措辞不符真实意图 → 文档变成谎言 |
红旗
- 不区分事实性更新和叙事性变更，全部自动修改
- 修改或删除 CHANGELOG 中的历史条目
- 不验证实际数量就更新文档中的数字
- 添加 human partner 不知道的新章节
- 跳过跨文档一致性检查
- 文档中有无法从入口点到达的孤立页面
- 以"文档不重要"为由跳过整个同步流程
- 一次列出多个问题让 human partner 批量回答
验证失败处理
| 验证项 | 失败表现 | 处理方式 |
|---|---|---|
| 变更文件识别不全 | 部分合并文件未被发现 | 扩展 diff 范围；检查 submodule 和生成文件 |
| 事实性更新未执行 | 路径/版本/数量仍不一致 | 立即修正；事实性更新不停顿 |
| 叙事性变更未询问 | AI 替 human partner 写了描述 | 回滚叙事性修改；逐条询问 |
| CHANGELOG 历史被修改 | 旧条目被删除或重写 | 恢复历史条目；只允许润色最新条目 |
| 跨文档数量不一致 | README 与代码不符 | 以代码为真实来源，验证后更新所有文档 |
输出模板
文档同步完成：
事实性更新（已自动执行）:
- [文件]: [变更描述] (old → new)
叙事性更新（已询问 human partner）:
- [文件] [位置]: 已更新 (user provided) / 跳过 (user declined)
CHANGELOG:
- 最新条目措辞已润色
- 历史条目: 未修改
一致性检查:
- 版本号: 一致 / 不一致 → 已修复
- 特性列表: 一致 / 不一致 → 已修复
- 组件列表: 一致 / 不一致 → 已修复
- 命令列表: 一致 / 不一致 → 已修复
- API 端点: 一致 / 不一致 → 已修复
可发现性:
- 所有文档可从入口点到达 / [孤立文档] → 已添加引用
验证清单
- 所有变更文件已识别并分类
- 事实性更新已自动执行并记录
- 叙事性变更已逐条询问 human partner
- CHANGELOG 仅润色最新条目，历史未动
- 版本号跨文档一致
- 特性列表跨文档一致
- 组件列表跨文档一致
- 所有文档可从入口点到达
- 文档一致性报告已输出