菜单
发布后文档同步。当代码已合并需要同步更新项目文档，或提到"文档同步""CHANGELOG""README 更新"
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| name | ship-workflow-doc-sync |
| description | 发布后文档同步。当代码已合并需要同步更新项目文档，或提到"文档同步""CHANGELOG""README 更新" |
reflect-team-documentation（可选）或回到项目工作ship-workflow-ship区分事实性更新（路径、版本号、数量、命令）和叙事性变更（功能描述、架构理由、迁移指南）。事实直接改；叙事必须问 human partner。
执行规则：
收集合并 commit 涉及的文件：git diff-tree --no-commit-id --name-only -r <merge-sha>
分类变更：代码文件 → 影响 README/ARCHITECTURE/API 文档；配置文件 → 影响部署章节；依赖文件 → 影响安装文档；CI/CD 文件 → 影响 CONTRIBUTING。
交叉引用变更文件与项目文档。检查维度：
| 文档 | 检查内容 |
|---|---|
| README.md | 项目描述、安装步骤、快速开始、特性列表 |
| CLAUDE.md | 命令映射、技能列表、项目结构 |
| AGENTS.md | 入口合同、激活门、命令映射 |
| docs/contracts/*.md | 运行时详细规则（按需加载） |
| ARCHITECTURE.md | 组件关系、数据流、技术栈 |
| CHANGELOG.md | 版本条目、变更类型 |
| CONTRIBUTING.md | 开发流程、PR 规则、CI 说明 |
对事实性不一致直接修复。每处修改记录到文档一致性报告。不修改叙事性内容，不添加新章节。数量变更必须先验证实际数量。
对叙事性不一致逐条询问 human partner，每次一个问题。每个问题包含：文件路径 + 具体位置 + 当前内容 + 变更原因。human partner 提供新内容或选择跳过。不替 human partner 写叙事性内容。
检查 CHANGELOG.md 最新条目。绝不覆盖或删除历史条目。只润色最新条目措辞（更清晰、更一致），保持与已有格式一致。变更类型：Added / Changed / Fixed / Deprecated / Removed / Security，每条以动词开头。
验证同一事实在所有文档中表述一致：版本号、特性列表、组件列表、命令列表、API 端点。不一致时以代码为真实来源更新文档。
确认每个文档都能从入口点（README.md 或 CLAUDE.md）通过链接到达。孤立文档需添加引用。
输出或记录必须包含：输入/来源、执行动作、验证结果、阻塞/回退。
| 说辞 | 现实 | 后果 |
|---|---|---|
| "文档以后再更新" | "以后"永远不会来。代码变更时同步更新成本最低。 | 事后补文档耗时 ×3-5；新人按旧文档操作 = 环境 +2h |
| "CHANGELOG 自己写就行" | AI 润色措辞，变更的业务意义只有 human partner 知道。 | 叙事不准确 → 用户误解变更影响 → 升级决策失误 |
| "README 不需要那么详细" | README 是新人的第一个文件。少一个步骤 = 新人多花一小时。 | 每个新人多花 1h × 10 人 = 10h 团队浪费 |
| "这个文档没人看" | 没人看是因为过时了。保持准确的文档会被发现和使用。 | 过时 → 信任崩塌 → 团队不再参考任何文档 |
| "自动更新就行，不用问" | 事实自动更新。叙事、判断、理由不能。 | 自动写叙事 → 措辞不符真实意图 → 文档变成谎言 |
| 验证项 | 失败表现 | 处理方式 |
|---|---|---|
| 变更文件识别不全 | 部分合并文件未被发现 | 扩展 diff 范围；检查 submodule 和生成文件 |
| 事实性更新未执行 | 路径/版本/数量仍不一致 | 立即修正；事实性更新不停顿 |
| 叙事性变更未询问 | AI 替 human partner 写了描述 | 回滚叙事性修改；逐条询问 |
| CHANGELOG 历史被修改 | 旧条目被删除或重写 | 恢复历史条目；只允许润色最新条目 |
| 跨文档数量不一致 | README 与代码不符 | 以代码为真实来源，验证后更新所有文档 |
文档同步完成：
事实性更新（已自动执行）:
- [文件]: [变更描述] (old → new)
叙事性更新（已询问 human partner）:
- [文件] [位置]: 已更新 (user provided) / 跳过 (user declined)
CHANGELOG:
- 最新条目措辞已润色
- 历史条目: 未修改
一致性检查:
- 版本号: 一致 / 不一致 → 已修复
- 特性列表: 一致 / 不一致 → 已修复
- 组件列表: 一致 / 不一致 → 已修复
- 命令列表: 一致 / 不一致 → 已修复
- API 端点: 一致 / 不一致 → 已修复
可发现性:
- 所有文档可从入口点到达 / [孤立文档] → 已添加引用
结构化脑暴——发散探索 + 收敛评估。当想法模糊、面临开放性问题或需要方案对比，或提到"脑暴""想法""方案对比""怎么办"
恢复保存的工作上下文。当新 session 需要继续之前的工作，或提到"恢复""restore""继续上次"
保存工作上下文。当需要保存当前工作状态供后续 session 恢复，或提到"保存""save""checkpoint""挂起"
架构决策记录（ADR）。当面临技术选型、架构决策、方案取舍需要记录，或提到"ADR""决策记录""为什么这样做"
发布或导出检查 → Go/No-Go → 归档。当审查通过后需要上线或交付最终产物，或提到"发布""上线""ship""Go/No-Go"
合并 PR → 等待 CI → 验证生产。当 PR 已创建需要合并到主分支并验证部署，或提到"合并""merge""PR""land"