# Ship Workflow Doc Sync

> 发布后文档同步。当代码已合并需要同步更新项目文档，或提到"文档同步""CHANGELOG""README 更新"

- Skill: `zeroz-lab/ship-workflow-doc-sync` (Agent Skill)
- Install (CLI): `npx skillmds@latest add zeroz-lab/ship-workflow-doc-sync`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zeroz-lab/ship-workflow-doc-sync/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: zeroz-lab (https://skillmd.com/u/zeroz-lab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zeroz-lab/ship-workflow-doc-sync

---


# 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 仅润色最新条目，历史未动
- [ ] 版本号跨文档一致
- [ ] 特性列表跨文档一致
- [ ] 组件列表跨文档一致
- [ ] 所有文档可从入口点到达
- [ ] 文档一致性报告已输出