Cm Doc Syncer

cm-doc-syncer — 文档同步器

在所有开发任务完成后，自动同步更新项目文档。确保文档和代码保持一致。

触发条件

由 /cm-ai 在最后任务的独立审查前调用；收口阶段只核验已审文档。

输入

• specs 文件夹路径
• 代码项目路径（可多个）
• LESSONS.md 中积累的架构决策
• 本 specs 批次全部 feature/task 的原始改动证据、开工快照和最后任务的批准文档写范围

执行步骤

1. 扫描变更

对每个代码项目，先读其 CLAUDE.md「版本控制」字段，按值选变更识别方式（显式分支，不得自行发明）：

• remote / local → git diff {基线}..HEAD 获取已提交候选；基线先取上一份 CHANGELOG 的 base-commit，无则取已确认的 scaffold/初始 commit。无法确认时记录基线缺口，改用下述本批次任务证据，不把全量文件当变更集
• none 或项目无 .git → 用本批次 handoff/diff 和开工快照定位文件，再核实当前内容；tasks 只确定任务清单，不能仅凭勾选项推断真实改动
• 字段缺失但有 .git → 按 local 处理

本轮范围是当前 specs 批次的全部 feature/task，恢复后仍按同一批次；不等于最后一个任务。 从有效批准清单、tasks 和各任务已有 handoff/diff 记录汇总变更路径；旧任务只读已绑定记录， 最后任务使用正在定稿的真实 diff。不能只凭 checkbox、时间、文件名或任意旧 Review 认定归属。

将本轮已提交差异与所有任务尚未提交的 staged、unstaged、新建/删除文件合并，按当前代码净变化去重。 早期任务已完成却仍未提交的改动属于本轮，不能因它出现在最后任务的开工快照里就当作用户原改动排除。 对照各任务开工快照和实际 diff 按片段排除用户原有改动；同文件混有他人修改、来源或批次不明时只报告缺口，不猜归属。

汇总仅用于读取；最后任务仍只写事先批准的文档范围，不重新修改旧任务源码、状态或凭证。 没有可信证据时明确“同步范围待确认”，不得按全量文件清单替代变更归属证明或宣称全部同步。

随后（与版本控制方式无关）：

• 识别新增的目录、模块、API、数据模型
• 从 specs 的 requirements.md 获取功能描述；requirements.md 缺失 → 该 feature 跳过描述提取并在最终输出中上报「specs 不完整」，不得凭 tasks.md 猜功能描述
• 从 LESSONS.md 获取架构决策和踩坑记录；文件不存在 → 按 0 条处理，不报错不中断

1.5 增量同步业务地图

按 ../codebase-context/references/writeback.md 复用本次变更证据：更新相关章节， 没有地图时创建最小局部地图，项目指定文档优先。不得因目录不存在直接跳过， 不得触发全量 scan；所需文档必须在本任务批准范围内，结果进入同一 handoff 与 Review。

2. 更新 README.md

对每个代码项目的 README 进行精炼更新：

必须覆盖：

• 项目简介 — 一句话说清楚是什么
• 架构概览 — 技术栈、目录结构、核心模块关系
• 快速开始 — 安装、配置环境变量、运行的最少步骤
• 功能模块 — 各模块简述，本次新增的功能标注
• API/接口 — 关键接口说明（如有后端）
• 合约地址 — 部署的合约信息（如有合约）
• 部署 — 构建命令、部署方式、环境要求

原则：

• 精炼，开发者能在 2 分钟内理解项目全貌
• 已有的 README 合理内容保留，只更新/补充变更涉及的部分
• 如项目没有 README → 新建完整版
• 不写废话，不放过时信息

3. 更新 .claude/CLAUDE.md

检查变更是否影响项目结构，保持 ≤150 行：

• 新增了目录 → 更新「目录结构」
• 新增了常用命令 → 更新「常用命令」
• 引入了新技术栈 → 更新「技术栈」
• 新增了 rules 文件 → 更新引用列表

4. 更新 .claude/rules/

检查变更中是否出现了新的模式或约定，按下表判据决定（满足才建，不满足不建，无中间态）：

新建 rules 一律从当前 Skill 向上解析 workflow root，使用 {CM_WORKFLOW_ROOT}/templates/rules/{名称}.md 骨架（frontmatter 含 description + globs），模板不存在则参照项目内既有 rules 的格式。

本步完成后回到步骤 3 回填 CLAUDE.md 的 rules 引用列表（步骤 3 执行时 rules 尚未定稿，引用列表以本步结果为准）。

4.5 LESSONS.md 归档（防膨胀深井）

LESSONS.md 超过 50 条时执行归档：

• 归档判据（按序适用）：① 条目带 feature 标签且标签不属于当前活跃 feature → 归档；② 横切/全局决策（不属于任何单一 feature 的约定，如"统一用 pnpm"）→ 豁免，留在主文件；③ 无标签且无法判断归属 → 留在主文件（宁留勿丢）
• 归档条目移入 {SPECS_DIR}/LESSONS-archive.md（全文保留）
• 主文件索引按 feature 聚合为一行（- {feature名} {N} 条 → archive），不逐条留行——逐条索引会让主文件列表项总数不降，归档失去防膨胀意义
• N1/N7 只加载主文件——上下文轮换的成本因此有上界；archive 仍在审计链内随时可查

5. 生成 specs CHANGELOG

在 specs 文件夹下创建 CHANGELOG 文件，文件名日期取执行同步的当日（不是 feature 提交日），如 CHANGELOG-2026-04-12.md；同日重复执行则覆盖更新同名文件：

# 变更日志 — 2026-04-12

> base-commit: {本次同步时的 HEAD hash；版本控制 none 的项目写 none}   # 下次同步的 diff 基线，步骤 1 读取

## Feature 1: {feature名}

### 新增
- {功能描述}

### 关键文件
- `{path}` — {说明}

### 架构决策
- {从 LESSONS.md 中提取的相关决策}

## Feature 2: {feature名}

...

多次开发产生多个日期文件，形成完整的变更历史。

6. 验证文档一致性

最后检查：

• CLAUDE.md 中引用的 rules 文件都存在
• rules 中的 globs 与实际目录匹配
• README 中的命令与 package.json / Makefile 一致
• 环境变量文档与 .env.example 一致

发现不一致时按两态处理（修复方向一律以代码/配置为准改文档，不得反向改代码）：

• 只改文档就能一致（如 README 写错命令、CLAUDE.md 引用了不存在的 rules）→ 修复并计数
• 需要改代码/配置/新建非文档文件才能一致（如 .env.example 缺失、脚本指向不存在的文件）→ 不修，在输出「一致性」行报「发现 N 处待人工」——doc-syncer 无权创建或修改文档之外的任何文件

禁止（红线，违反任何一条即任务失败）

• 不得虚构：接口、命令、合约地址、环境变量只写代码或 specs 中实际存在的；桩实现/空函数按 specs 口径描述时必须注明「以 specs 为准，实现未完成」
• 不得删除用户手写内容：README 中无法从代码/specs 再生的段落（徽章、致谢、许可、手写背景说明）一律原样保留，更新只增改与变更相关的部分
• 不得触碰文档之外的文件：代码、配置、.env*、CI 一律只读；发现问题只上报「待人工」，不代修
• 归档不得丢条目：归档前后条目总数必须守恒（主文件活跃条数 + archive 条数 = 原总数），执行后自查一次
• 代码与 specs 不符时不得按 specs 想象功能：以代码实际行为为准描述，差异作为「待人工」写入 CHANGELOG 上报

输出

📝 文档同步完成

README: {更新/新建} {N} 个项目
CLAUDE.md: {更新/无变化}
Rules: {新增 N 个 / 更新 N 个 / 无变化}
CHANGELOG: {N} 个 feature
业务地图: {已更新/已建局部地图/无需更新/项目规则豁免/待同步} {路径或原因}
一致性: {PASSED / 有 N 处已修复 / 发现 N 处待人工}   # 三态可并存，如「2 处已修复,1 处待人工」