OpenSkillIndex← back to search
claude-codedevelopment

Claude-skill-registry devdocs-sync

Sync documentation with implementation progress. Use when users need to update docs after development, verify doc-code consistency, or track implementation progress. Triggers on keywords like "sync docs", "update progress", "doc consistency", "同步文档", "更新进度".

install
source · Clone the upstream repo
git clone https://github.com/majiayu000/claude-skill-registry
Claude Code · Install into ~/.claude/skills/
T=$(mktemp -d) && git clone --depth=1 https://github.com/majiayu000/claude-skill-registry "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/data/devdocs-sync" ~/.claude/skills/majiayu000-claude-skill-registry-devdocs-sync && rm -rf "$T"
manifest: skills/data/devdocs-sync/SKILL.md
tags
#doc-code-sync#dev-docs#implementation-tracking#code-docs#progress-sync
source content

文档同步

保持 DevDocs 文档与实际实现进度一致，检测偏差并更新状态。

语言规则

  • 支持中英文提问
  • 统一中文回复
  • 使用中文生成文档

触发条件

  • 用户完成一个或多个开发任务后
  • 用户要求检查文档与代码一致性
  • 用户需要更新文档进度
  • 定期同步（如 Sprint 结束时）

运行模式

/devdocs-sync                    → 完整同步（检查 + 确认 + 更新）
/devdocs-sync --check            → 仅检查，不更新文档
/devdocs-sync --absorb           → 吸收模式（自动 + 智能补齐）
/devdocs-sync --trace            → 代码追溯扫描（更新矩阵代码位置）
/devdocs-sync --archive          → 强制归档已完成任务
/devdocs-sync --audit            → 追溯健康度检查
/devdocs-sync T-01 T-02          → 指定范围同步

模式对比

模式检查自动更新智能补齐用户确认
check✅❌❌❌
sync（默认）✅✅❌✅ 全部
absorb✅✅✅✅ 仅高风险
trace✅ 代码扫描✅ 矩阵❌❌
audit✅ 追溯❌❌❌

核心理念

文档与代码的关系

文档定义（计划）          代码实现（实际）
     │                        │
     ├── F-XXX 功能点    ←→   ├── 功能模块
     ├── AC-XXX 验收标准 ←→   ├── 业务逻辑
     ├── T-XX 开发任务   ←→   ├── 代码提交
     └── UT/IT/E2E 测试  ←→   └── 测试文件

核心原则：

  • 文档是计划，代码是实现
  • 偏差是正常的，关键是及时同步
  • 同步应该双向：文档→代码（指导）、代码→文档（记录）

同步时机

时机同步内容
任务完成后更新任务状态、测试结果
Sprint 结束全量检查、进度报告
需求变更后更新需求文档、影响分析
代码审查后记录设计决策变更

工作流程

1. 读取 DevDocs 文档
   │
   ▼
2. 扫描代码库（工作区状态）
   ├── 检查文件是否存在（Glob）
   ├── 运行测试（获取实时结果）
   ├── 检查未提交变更（git status）
   └── 参考提交记录（git log，辅助）
   │
   ▼
3. 对比分析
   ├── 任务完成状态
   ├── 测试覆盖情况
   └── 功能实现状态
   │
   ▼
4. 生成偏差报告
   │
   ▼
5. 询问用户确认更新
   │
   ▼
6. 更新文档

重要：检查基于当前工作区状态，而非仅依赖 git 提交历史。

模式详解

吸收模式 (--absorb)

从"检查员"进化为"记录员"，支持代码优先开发路径。低风险偏差自动吸收，高风险需确认。

详见 absorb-mode.md

追溯健康度检查 (--audit)

检测编号体系完整性，防止文档维护债积累。检查 AC 覆盖、F 任务闭环、INS 转化、孤立编号。

详见 audit-mode.md

代码追溯扫描 (--trace)

扫描代码中的 

@satisfies
/
@verifies
标注，与文档交叉验证，更新追溯矩阵代码位置列。

详见 trace-mode.md

任务归档

当已完成任务过多时自动建议归档，保持主文档简洁。

详见 archive.md

同步命令

快速检查

/devdocs-sync --check
# 输出: 偏差报告（仅显示，不写入）

完整同步

/devdocs-sync
# 流程: 检查 → 显示报告 → 确认 → 更新文档

吸收模式

/devdocs-sync --absorb
# 流程: 检查 → 自动吸收低风险 → 确认高风险 → 生成报告

指定范围

/devdocs-sync T-01 T-02
# 只同步特定任务

输出文件

进度报告

生成 

docs/devdocs/00-progress-report.md
，包含总体进度、偏差汇总、下一步建议。

文档更新

文档更新内容
04-dev-tasks.md
任务完成状态、执行检查清单
03-test-cases.md
追溯矩阵状态、测试通过状态
01-requirements.md
功能点实现状态（如有状态列）

约束

检查约束

  • 必须读取所有 DevDocs 文档后再进行检查
  • 必须生成偏差报告
  • 更新文档前必须询问用户确认（吸收模式低风险除外）
  • 检查结果必须可追溯（显示检查方法）

更新约束

  • 不自动删除文档内容，只标记状态
  • 不自动修改代码，只更新文档
  • 保留原有文档结构
  • 更新时记录时间戳

吸收模式约束

  • 低风险吸收仅限状态字段更新
  • 高风险吸收必须用户确认
  • 新增内容必须指定关联编号（AC/F/US）
  • 无法确定关联的内容标记为"待手动处理"
  • 吸收操作必须生成吸收报告

安全约束

  • 不执行未知的 shell 命令
  • 测试命令使用项目配置的命令
  • 大规模更新前必须确认

Skill 协作

场景协作 Skill说明
开发完成
/devdocs-dev-workflow
被调用：任务完成后触发 --trace
任务完成后
/devdocs-dev-tasks
执行任务后触发同步
测试追溯
/devdocs-test-cases
协作：更新追溯矩阵代码位置
需求变更
/devdocs-feature
新功能添加后同步
Bug 修复
/devdocs-bugfix
Bug 修复后更新文档
洞察确认
/devdocs-insights
改进建议确认后同步
项目改造
/devdocs-retrofit
改造后全量同步

参考资料

偏差修复路由（调度器功能）

当检测到偏差时，必须在报告中指派下一步修复 Skill：

偏差类型修复 Skill说明
设计缺失/漂移
/devdocs-system-design
代码有新接口但文档未记录
AC 缺测试
/devdocs-test-cases
验收标准无对应测试用例
F 缺任务闭环
/devdocs-dev-tasks
功能点无关联开发任务
代码已实现文档落后
/devdocs-sync --absorb
状态未更新、新内容未登记
追溯矩阵代码位置缺失
/devdocs-sync --trace
代码标注未扫描到矩阵

调度器原则：偏差报告不能只列出问题，必须给出明确的修复路由。

调用顺序建议

任务完成后的推荐顺序：

/devdocs-sync --trace    # 1. 先更新追溯矩阵代码位置
        │
        ▼
/devdocs-sync            # 2. 再检查整体状态并更新
  或 --absorb            #    （absorb 自动包含 trace 步骤）


--trace
专注于代码标注扫描，
--absorb
专注于状态吸收。两者可独立使用，也可组合使用。

下一步

同步完成后，根据进度报告中的偏差修复路由执行对应 Skill。