用途
doc-sync 用于审计项目文档与代码库实际状态之间的偏差，并在需要时修复这些偏差。它解决的是文档过时、与代码不一致的问题，例如架构图过时、文件路径错误、测试数量过期、路线图未反映已完成工作等。
主要能力
该技能能够检测四类文档偏差：
- 结构偏差：目录树、插件/中间件链顺序等。检测信号为文件系统，误报风险低。
- 路径腐烂：文档中不再存在的文件路径。检测信号为文件路径，误报风险低，可使用 check-doc-paths.js 脚本。
- 计数偏差：测试数量、权限数量、路由数量等。检测信号为从实际文件重新计数，误报风险中等。
- 路线图滞后：已完成工作未反映在文档中。检测信号为 git log 意图，误报风险高。
审计范围包括：
- 架构文档：插件/中间件链顺序、路由模块列表、monorepo 包列表、目录结构树。
- 安全文档：列出的安全插件与实际注册的对比、权限数量、自上次文档更新以来的安全相关提交（使用 git log 命令）。
- 测试文档：实际测试文件数量与文档记录数量的对比、通过/失败数量（运行测试套件获取当前数字）。
- 路线图/变更日志：检查 git log 中已完成但未反映在任何阶段的工作。标记最后路线图更新之后带有 feat: 或 fix: 前缀的提交。
- CLAUDE.md / 智能体指令：命名约定是否匹配实际模式、文档中的文件路径是否存在、反模式部分是否最新。
使用方式
该技能通过参数控制模式：
$ARGUMENTS为空或为audit：仅报告，不编辑。$ARGUMENTS为fix：报告后应用针对性编辑并提交。
修复时，只做最小编辑以纠正偏差，不重写文本、不重构章节、不添加新内容——这是同步，不是创作。
提供的脚本：
bash scripts/list-doc-targets.sh
node scripts/check-doc-paths.js README.md docs/ARCHITECTURE.md
报告格式为表格：
| Doc | Section | Issue | Severity |
|---|
严重程度分为：Critical（损坏的路径、缺失的安全文档）、Warning（过时的计数、缺失的路由）、Info（轻微措辞偏差、过时的路线图阶段）。
修复模式下的提交信息：
docs: sync documentation with codebase [doc-sync]
适用场景
- 当需要审计或修复项目文档与代码库之间的偏差时。
- 当文档中的架构图、文件路径、测试数量、路线图或智能体指令可能过时时。
- 当需要确保文档只反映代码当前实际状态，而非期望状态时。
限制
该技能明确禁止以下行为：
- 绝不基于代码“应该”是什么样来更新文档——只同步到代码当前实际状态。
- 绝不修复未审计部分的文档——部分修复会造成虚假信心。
- 绝不仅凭代码存在就标记路线图项完成——需检查 git log 中的故意完成提交。
- 绝不跳过审计 CLAUDE.md / 智能体指令——过时的智能体指令会在未来会话中导致级联错误。
其他限制暂未提供。