| name | project-sync-docs |
| description | 根据本次工作内容,同步更新项目文档,保持文档与代码实现一致。当用户说"更新文档"、"同步文档"、"文档过时了"、"更新 CLAUDE.md"、"更新 AGENTS.md"、"更新 README"或输入 /sync-docs 时触发。完成功能开发、bug 修复、架构调整后也应主动提示使用。 |
根据本次工作内容,识别哪些文档需要更新,并精准同步,避免文档与实现脱节。
需要维护的文档
| 文档 | 职责 |
|---|
CLAUDE.md | 项目架构、约束规范、常用命令 — 给 AI Agent 看的 |
packages/*/AGENTS.md | 各子包的关键工作点、踩坑记录、设计决策 — 接力必读 |
README.md | 用户视角的功能说明、CLI 命令、快速开始 |
docs/TODO.md | 待办事项状态(进行中 / 已完成) |
docs/*.md | 专项技术文档(构建问题、踩坑记录等) |
步骤
-
回顾本次工作:梳理刚完成的变更——新增了什么功能、修复了什么 bug、改了哪些架构决策、踩了哪些坑
-
识别需要更新的文档:对照上表,判断哪些文档的内容与当前实现不符或缺失
-
逐一更新,每个文档遵循以下原则:
- CLAUDE.md:更新架构描述、约束规范、命令列表;删除已过时的内容
- AGENTS.md:在"关键工作点(接力必读)"章节追加新踩的坑、设计决策、非显而易见的约束
- README.md:更新功能列表、CLI 命令表、使用示例
- docs/TODO.md:将已完成项标记为
[x],新增待办项
- docs/*.md:补充新的技术问题记录
-
只改有变化的部分,不要重写整个文档,不要添加没有发生的内容
原则
- 写"为什么"而非"是什么"——读者能看代码,但看不到决策背后的原因
- AGENTS.md 的踩坑记录要具体:症状 → 原因 → 解决方案
- 不确定某个内容是否过时时,先读对应源码再决定
- 更新完后告知用户修改了哪些文档、改了什么