当文档和代码"吵架"了:一个自动化文档同步方案的诞生
目标读者:前端/全栈开发者,尤其是维护中大型模块的团队成员
核心价值:理解自动化文档同步的思路,学会用一条指令让 README 与代码保持一致
阅读时间:5 分钟
最好的文档维护,是你感觉不到在维护文档。

你的 README,多久没更新了?
你是否也有过这样的时刻?
打开一个同事维护的模块,想快速了解它的结构和 API。翻开 README,上面写着"状态管理使用 Redux"。你打开代码一看–早就迁移到 Zustand 了。路由配置里列了 5 个页面,实际代码里已经有 8 个。
README 和代码,不知从什么时候开始,活成了两个互不认识的人。
这不是某个人的过错。在快速迭代的前端项目中,文档"腐烂"的速度远超我们的想象。一次小小的路由调整、一个 API 字段的变更、一个组件的拆分–每一次代码改动都在让文档的保质期缩短。
而手动维护?说实话,在紧张的排期面前,更新 README 永远排在 todo list 的最后一位。
问题的根源:信息散落,同步成本高
让我们来分析这个问题为什么这么顽固。
一个典型的前端模块,信息分散在至少 5 个维度:
| 维度 | 散落位置 | 示例 |
|---|---|---|
| 路由配置 | router/config/ | 路径常量、注册逻辑 |
| 状态管理 | store/ 或 context/ | 状态字段、action 定义 |
| API 接口 | services/ | 接口地址、参数结构、错误处理 |
| 组件关系 | 各 .tsx 文件 | 父子嵌套、弹窗挂载、条件渲染 |
| 类型定义 | types/ | 枚举值、数据模型 |
要写一份准确的 README,你需要把这 5 个维度的信息全部收集、理解、组织。这就是手动维护成本高的根本原因–不是写不出来,而是收集信息的过程太耗精力。
更致命的是,代码改动时,开发者往往只关注"代码能不能跑",很难同时顾及"文档还准不准"。日积月累,文档和代码的距离越拉越大。
文档不是写出来就完了,它需要和代码一起"活着"。

解决方案:让 AI 来做信息收集和文档同步
既然问题的核心是"信息收集成本高",那解决思路就很明确:把信息收集交给擅长扫描代码的 AI,把人类从繁琐的文档维护中解放出来。
这就是 readme-sync 指令的设计出发点。
一条指令,完成整个流程
/readme-sync <target_dir> [reference_readme_path] [extra_requirements]
只需指定目标模块的路径,指令会自动完成三件事:
- 深度扫描代码目录,收集路由、状态、API、组件、类型等全维度信息
- 对齐参考模板的文档风格,确保输出格式统一
- 智能判断是创建还是更新 README,做出最小必要改动
设计背后的三个关键决策
决策一:固定 14 章节结构。 不同开发者写出的文档结构千差万别。readme-sync 定义了从"模块概述"到"完整调用链总结图"的 14 个标准章节,确保每个模块的文档都有一致的信息密度。这对团队协作的意义是–任何人打开任何模块的 README,都知道去哪个章节找自己需要的信息。
决策二:以代码为准,不以文档为准。 当代码和已有文档存在冲突时,readme-sync 始终以代码实现为事实来源。这避免了"文档里说的和代码不一样"的信任危机。
决策三:一致性校验清单。 在生成文档前,指令会对以下要素进行交叉验证:
- 路由路径与常量名是否匹配
- API 名称和调用时机是否正确
- 状态分支优先级是否与代码中的 if/else 顺序一致
- 按钮文案、交互行为是否与组件实现吻合
这不只是"生成文档",而是一次带有自动化 Code Review 性质的文档校验。

两种模式应对不同场景
readme-sync 的行为会根据目标目录是否已有 README 自动切换:
| 场景 | 行为 | 策略 |
|---|---|---|
| README 不存在 | 全量创建 | 生成完整 14 章节文档 |
| README 已存在 | 增量更新 | 结合 git diff 定位变更,仅修正过时内容 |
增量更新模式是这个方案的精华。它不是每次都重写文档,而是:
- 读取现有 README 内容
- 通过
git diff分析代码变更范围 - 仅更新受影响的章节
- 保持原有文档的主体风格不变
这意味着你可以在每次 MR 合并后跑一次 readme-sync,它只会精准修改需要更新的部分,不会破坏你手动补充的额外说明。
与其花 30 分钟人工比对代码变更和文档差异,不如一条指令搞定。
实践建议:把文档同步嵌入工作流
工具再好,不融入流程也发挥不了作用。以下是我推荐的三种集成方式:
1. MR 触发同步。 每次代码合并到主分支后,运行 /readme-sync 刷新模块文档。这是成本最低、效果最稳定的方式。
2. 新模块初始化。 创建新模块时,先搭好代码骨架,再跑一次 readme-sync 生成初始文档。比从零写 README 节省大量时间。
3. 周期性校验。 对于核心模块,每两周跑一次 readme-sync 做"体检"。即使没有代码变更,也能发现历史遗留的文档错误。

总结
文档和代码的同步问题,本质上是一个信息收集和校验的成本问题。readme-sync 的思路很简单:把 AI 擅长的事(扫描、收集、比对)交给 AI,把人类擅长的事(补充业务洞察、添加注意事项)留给人类。
不是消灭手动文档,而是让手动维护的起点更高、范围更小。
下次当你打开一份 README,发现它和代码对不上的时候,不必叹气。一条指令,就能让它们重新"和好"。
好的文档不是写出来的,是和代码一起长出来的。
参考来源
- 方案实现:
commands/readme-sync.md– readme-sync 指令完整定义 - 设计理念:前端模块文档自动化维护实践
附录
readme-sync.md
---
description: 深度分析目标模块并创建/更新 README,文档风格对齐参考模板
argument-hint: "<target_dir> [reference_readme_path] [extra_requirements]"
allowed-tools: Read, Write, Bash, Grep, Glob
---
# readme-sync
用于快速维护前端模块 README:当目标目录没有 README.md 时自动创建;当已存在 README.md 时根据代码变更或用户新增需求进行增量更新。
## 使用方式
`/readme-sync <target_dir> [reference_readme_path] [extra_requirements]`
参数说明:
- `target_dir` (必需): 要分析的模块目录(如 `v6/src/views/SomeModule`)
- `reference_readme_path` (可选): 参考格式 README 路径,默认 `v6/src/views/RealNameSupplement/README.md`
- `extra_requirements` (可选): 用户追加要求(例如强调某些场景、补充某类流程)
## 目标与约束
1. 只操作目标 README:`<target_dir>/README.md`。
2. 不创建任何额外 markdown 报告文件。
3. 文档必须基于真实代码,不臆测。
4. 章节结构、写作粒度、术语风格对齐参考 README。
5. 若代码和 README 有冲突,以代码为准并修正文档。
## 固定输出结构(必须按顺序)
1. 模块概述
2. 目录结构
3. 组件层级关系
4. 路由配置
5. 状态管理
6. API 接口清单
7. 枚举定义
8. 完整执行时序图(mermaid)
9. 核心逻辑详解
10. 各组件详细说明
11. 数据模型
12. 外部依赖
13. 修改指南(常见场景 + 注意事项)
14. 完整调用链总结图(mermaid)
## 执行流程
### 1) 参数解析与预检查
- 解析 `target_dir`,若缺失则提示用户补充。
- 解析 `reference_readme_path`,默认 `v6/src/views/RealNameSupplement/README.md`。
- 检查目标目录是否存在。
- 检查 `target_readme = <target_dir>/README.md` 是否存在。
### 2) 代码扫描与事实收集
对目标目录进行完整扫描,至少覆盖:
- 页面入口、路由常量、路由注册
- store/context、状态字段、状态流
- services/api(接口、参数、错误处理、网关)
- 关键组件和分支逻辑
- 弹窗与命令式挂载(如 ReactDOM.render/unmount)
- 跳转与回调路径(`window.location`、路由常量)
- types 枚举与数据模型
同时扫描关联文件:
- 路由常量文件(如 `router/config/constants`)
- 路由注册文件(如 `router/config/index`)
### 3) 分支策略
#### A. `README.md` 不存在(创建)
- 直接生成完整 README。
- 内容必须覆盖固定 14 章节。
- 所有流程图与关键逻辑都以代码实现为准。
#### B. `README.md` 已存在(更新)
- 先读取现有 README。
- 结合 `git diff`(优先 target_dir + 关联路由/常量文件)定位变更影响。
- 执行“最小必要改动”:仅修正过时、错误、遗漏内容。
- 保持原有章节顺序与主体风格,不做无关重写。
- 如果用户提供 `extra_requirements`,在不违背代码事实前提下纳入更新。
## 一致性校验清单(写入前必须通过)
- 路由路径与常量名一致。
- API 名称、调用时机、参数字段、错误处理一致。
- 状态分支优先级与真实 if/else 顺序一致。
- 回调地址、跳转地址与代码一致(避免历史硬编码残留)。
- README 中“按钮文案/交互行为/终态”与组件实现一致。
- 命令式弹窗的挂载与销毁方式描述正确。
- 未覆盖分支(如返回 null)必须在注意事项说明。
## 写作规范
- 中文输出,语义准确,避免空话。
- 表格字段命名统一,流程叙述使用可验证术语。
- Mermaid 图保持可读性,命名与代码实体一致。
- 涉及“推断”必须显式标注“基于调用点推断”。
## 交付要求
- 最终直接落盘到 `<target_dir>/README.md`。
- 回复中仅包含:
1. 已创建/已更新的文件路径
2. 本次关键同步点(4-8条)
3. 若存在仍待确认项,单独列出
463



被折叠的 条评论
为什么被折叠?



