- name
- devdocs-sync
- description
- DevDocs 文档同步专家。保持 DevDocs 文档与实际实现进度一致，检测偏差并更新状态。支持代码追溯、文档代码一致性验证和进度跟踪。
- allowed-tools
- Read, Write, Glob, Grep, Bash(git:*)
文档同步
保持 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)
从"检查员"进化为"记录员"，支持代码优先开发路径。低风险偏差自动吸收，高风险需确认。
追溯健康度检查 (--audit)
检测编号体系完整性，防止文档维护债积累。检查 AC 覆盖、F 任务闭环、INS 转化、孤立编号。
代码追溯扫描 (--trace)
扫描代码中的 @satisfies/@verifies 标注，与文档交叉验证，更新追溯矩阵代码位置列。
任务归档
当已完成任务过多时自动建议归档，保持主文档简洁。
详见 archive.md
同步命令
快速检查
/devdocs-sync --check
# 输出: 偏差报告（仅显示，不写入）完整同步
/devdocs-sync
# 流程: 检查 → 显示报告 → 确认 → 更新文档吸收模式
/devdocs-sync --absorb
# 流程: 检查 → 自动吸收低风险 → 确认高风险 → 生成报告指定范围
/devdocs-sync T-01 T-02
# 只同步特定任务输出文件
进度报告
生成 docs/devdocs/progress-report.md，包含总体进度、偏差汇总、下一步建议。
文档更新
| 文档 | 更新内容 |
|---|---|
04-dev-tasks.md | 任务完成状态、执行检查清单 |
03-test-cases.md | 追溯矩阵状态、测试通过状态 |
01-requirements.md | 功能点实现状态（如有状态列） |
约束
检查约束
- [ ] 必须读取所有 DevDocs 文档后再进行检查
- [ ] 必须生成偏差报告
- [ ] 更新文档前必须询问用户确认（吸收模式低风险除外）
- [ ] 检查结果必须可追溯（显示检查方法）
更新约束
- [ ] 不自动删除文档内容，只标记状态
- [ ] 不自动修改代码，只更新文档
- [ ] 保留原有文档结构
- [ ] 更新时记录时间戳
吸收模式约束
- [ ] 低风险吸收仅限状态字段更新
- [ ] 高风险吸收必须用户确认
- [ ] 新增内容必须指定关联编号（AC/F/US）
- [ ] 无法确定关联的内容标记为"待手动处理"
- [ ] 吸收操作必须生成吸收报告
安全约束
- [ ] 不执行未知的 shell 命令
- [ ] 测试命令使用项目配置的命令
- [ ] 大规模更新前必须确认
Skill 协作
| 场景 | 协作 Skill | 说明 |
|---|---|---|
| 任务完成后 | /devdocs-dev-tasks | 执行任务后触发同步 |
| 需求变更 | /devdocs-feature | 新功能添加后同步 |
| Bug 修复 | /devdocs-bugfix | Bug 修复后更新文档 |
| 项目改造 | /devdocs-retrofit | 改造后全量同步 |
参考资料
- absorb-mode.md - 吸收模式详解
- audit-mode.md - 追溯健康度检查
- trace-mode.md - 代码追溯扫描
- archive.md - 任务归档功能
- examples.md - 使用示例与偏差类型
下一步
同步完成后，可根据进度报告：
- 继续开发未完成任务
- 补充缺失的文档记录
- 修正不一致的设计