用途
doc-sync 用于在代码仓库中同步文档，维护 CLAUDE.md 导航层级和 README.md 隐形知识文档。当用户要求“sync docs”或“update documentation”时使用。该技能自包含，直接执行全部文档工作。
主要能力
- 确定作用范围：根据用户请求判断是全仓库、指定目录及其子目录，还是单个文件所在目录。全仓库范围执行完整审计，较窄范围仅在指定边界内操作。
- 发现：映射需要验证 CLAUDE.md 的目录，使用 find 命令排除 .git、node_modules、pycache、.venv、target、dist、build 等目录，并记录每个目录是否已有 CLAUDE.md、是否具备表格索引结构、有哪些文件或子目录需要索引。
- 审计：检查每个目录的漂移和错位内容，包括 CLAUDE.md 是否存在、是否有表格索引、目录文件与索引条目的差异、缺失或过期的索引项、触发条件是否面向任务、是否包含应属于 README.md 的架构或设计文档、README.md 是否存在及是否有必要存在。
- 内容迁移：将 CLAUDE.md 中不属于索引的内容迁移到 README.md，包括架构说明或图、设计决策文档、组件交互描述、超过一句话的概述、不变量或规则文档、超出简单触发条件的“为什么”解释、关键不变量章节、依赖说明章节、约束章节、带说明的目的章节、解释理由的要点列表。可保留在 CLAUDE.md 的操作性内容包括：该目录特定的构建命令、测试命令、重新生成或同步命令（如 protobuf 重新生成）、部署命令、其他可复制粘贴的过程性命令。判断标准是“这是在解释为什么，还是在说明怎么做”：解释性内容（架构、决策、理由）归 README.md，操作性内容（命令、流程）留在 CLAUDE.md。
- 索引更新：为需要处理的目录创建或更新 CLAUDE.md，使用 ROOT 或 SUBDIRECTORY 模板，填充文件与子目录表格，“What”列写事实性内容描述，“When to read”列写面向动作的触发条件；若存在 README.md 则纳入 Files 表。在存在隐形知识时创建 README.md，记录架构、设计决策、不变量、权衡，应用内容测试移除代码中可见的内容，保持简洁且自包含，不引用外部权威来源。
- 验证：确认范围内每个目录都有 CLAUDE.md、所有 CLAUDE.md 使用表格索引格式、无漂移、无错位内容、README.md 已在父级 CLAUDE.md 中索引、CLAUDE.md 仅包含一句话概述加表格索引加操作性章节、README.md 在识别出隐形知识处存在且自包含。
使用方式
该技能通过自然语言请求触发，例如“sync docs”“update documentation”或指定路径如“sync docs in src/validator/”“update CLAUDE.md for parser.py”。执行后按发现、审计、内容迁移、索引更新、验证五个阶段推进，并输出 Doc Sync Report，包含作用范围、变更列表（创建、更新、迁移、标记）和验证统计（审计目录数、CLAUDE.md 覆盖率、格式、漂移修复数、内容迁移数、README.md 数量、是否自包含）。
适用场景
- 需要批量整理仓库文档结构，确保每个目录都有 CLAUDE.md 导航索引。
- 需要消除文档漂移，使索引条目与实际文件保持一致。
- 需要区分解释性内容与操作性内容，把架构、设计决策、不变量等“为什么”内容迁移到 README.md。
- 需要为存在隐形知识的目录创建自包含的 README.md。
限制
- 不适用于单文件文档（内联注释、docstring）或代码注释，这些应直接处理。
- 该技能专门用于 CLAUDE.md 与 README.md 的同步。
- 不创建 CLAUDE.md 的目录包括：生成文件目录（dist/、build/、编译输出）、第三方依赖（node_modules/、vendor/、third_party/）、Git 内部（.git/）、IDE 或编辑器配置（.idea/、.vscode/，除非项目特定设置）、仅含 .gitkeep 或无代码文件的占位目录。
- 不索引生成文件（.generated.、编译输出）和第三方依赖文件；应索引影响开发的隐藏配置文件（.eslintrc、.env.example、.gitignore）、测试文件与测试目录、文档文件（含 README.md）。
- 索引反模式包括：过于笼统（如“Configuration / Working with configuration”）、用内容描述代替触发条件、缺少动作动词。正确示例：
cache.rs描述为“LRU cache with O(1) get/set”，触发条件为“Implementing caching, debugging misses, tuning eviction”。 - 更多触发模式示例见 references/trigger-patterns.md。