devdocs-sync

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

文档同步

Documentation Sync

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

Keep DevDocs documentation aligned with actual implementation progress, detect discrepancies, and update statuses.

语言规则

Language Rules

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

Supports questions in both Chinese and English
Provides unified Chinese responses
Generates documentation in Chinese

触发条件

Trigger Conditions

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

After users complete one or more development tasks
When users request to check doc-code consistency
When users need to update documentation progress
Regular synchronization (e.g., at the end of a Sprint)

运行模式

Operation Modes

/devdocs-sync                    → 完整同步（检查 + 确认 + 更新）
/devdocs-sync --check            → 仅检查，不更新文档
/devdocs-sync --absorb           → 吸收模式（自动 + 智能补齐）
/devdocs-sync --trace            → 代码追溯扫描（更新矩阵代码位置）
/devdocs-sync --archive          → 全量归档检查（所有文档类型）
/devdocs-sync --archive requirements  → 仅归档需求文档
/devdocs-sync --archive design        → 仅归档设计文档
/devdocs-sync --archive tests         → 仅归档测试用例
/devdocs-sync --archive tasks         → 仅归档开发任务
/devdocs-sync --archive --release v1.0.0  → 创建版本快照
/devdocs-sync --audit            → 追溯健康度检查
/devdocs-sync T-01 T-02          → 指定范围同步

/devdocs-sync                    → Full sync (check + confirmation + update)
/devdocs-sync --check            → Check only, no documentation update
/devdocs-sync --absorb           → Absorb mode (automatic + intelligent completion)
/devdocs-sync --trace            → Code trace scan (update matrix code locations)
/devdocs-sync --archive          → Full archive check (all documentation types)
/devdocs-sync --archive requirements  → Archive requirement docs only
/devdocs-sync --archive design        → Archive design docs only
/devdocs-sync --archive tests         → Archive test cases only
/devdocs-sync --archive tasks         → Archive development tasks only
/devdocs-sync --archive --release v1.0.0  → Create version snapshot
/devdocs-sync --audit            → Trace health check
/devdocs-sync T-01 T-02          → Sync specified scope

模式对比

Mode Comparison

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

Mode	Check	Auto Update	Intelligent Completion	User Confirmation
check	✅	❌	❌	❌
sync (default)	✅	✅	❌	✅ All
absorb	✅	✅	✅	✅ High-risk only
trace	✅ Code scan	✅ Matrix	❌	❌
archive	✅ Archive conditions	✅ Archive files	❌	✅ All
audit	✅ Trace	❌	❌	❌

核心理念

Core Concepts

文档与代码的关系

Relationship Between Documentation and Code

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

核心原则：

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

Documentation Definition (Plan)          Code Implementation (Actual)
     │                        │
     ├── F-XXX Feature Points    ←→   ├── Feature Modules
     ├── AC-XXX Acceptance Criteria ←→   ├── Business Logic
     ├── T-XX Development Tasks   ←→   ├── Code Commits
     └── UT/IT/E2E Tests  ←→   └── Test Files

Core Principles:

Documentation is the plan, code is the implementation
Discrepancies are normal; the key is timely synchronization
Synchronization should be bidirectional: Documentation → Code (guidance), Code → Documentation (recording)

同步时机

Synchronization Timing

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

Timing	Sync Content
After task completion	Update task status, test results
End of Sprint	Full check, progress report
After requirement change	Update requirement docs, impact analysis
After code review	Record design decision changes

工作流程

Workflow

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

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

1. Read DevDocs documentation
   │
   ▼
2. Scan code repository (workspace status)
   ├── Check file existence (Glob)
   ├── Run tests (get real-time results)
   ├── Check uncommitted changes (git status)
   └── Reference commit history (git log, auxiliary)
   │
   ▼
3. Comparative Analysis
   ├── Task completion status
   ├── Test coverage
   └── Feature implementation status
   │
   ▼
4. Generate discrepancy report
   │
   ▼
5. Request user confirmation for updates
   │
   ▼
6. Update documentation

Important: Checks are based on current workspace status, not just git commit history.

模式详解

Mode Details

吸收模式 (--absorb)

Absorb Mode (--absorb)

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

详见 absorb-mode.md

Evolve from "inspector" to "recorder", supporting code-first development paths. Low-risk discrepancies are automatically absorbed; high-risk ones require confirmation.

See absorb-mode.md

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

Trace Health Check (--audit)

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

详见 audit-mode.md

Detects completeness of the numbering system to prevent documentation maintenance debt accumulation. Checks AC coverage, F task closure, INS conversion, and isolated numbers.

See audit-mode.md

代码追溯扫描 (--trace)

Code Trace Scan (--trace)

扫描代码中的

@satisfies

@verifies

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

详见 trace-mode.md

Scans for

@satisfies

@verifies

annotations in code, cross-validates with documentation, and updates the code location column in the trace matrix.

See trace-mode.md

文档归档 (--archive)

Documentation Archive (--archive)

支持所有文档类型的归档，控制文档膨胀，同时保留历史记录便于追溯：

文档类型	归档条件	归档文件
需求	功能已完成/已废弃	`archive/01-requirements-archive.md`
设计	关联功能已归档	`archive/02-system-design-archive.md`
测试	关联 AC 已归档	`archive/03-test-cases-archive.md`
任务	已完成 > 15 个	`archive/04-dev-tasks-archive.md`

归档时支持级联：归档 F-001 时可同时归档关联的设计/测试/任务。

详见 archive.md

Supports archiving of all documentation types, controls documentation bloat, while preserving historical records for traceability:

Documentation Type	Archive Condition	Archive File
Requirements	Feature completed/obsolete	`archive/01-requirements-archive.md`
Design	Associated feature archived	`archive/02-system-design-archive.md`
Tests	Associated AC archived	`archive/03-test-cases-archive.md`
Tasks	>15 completed	`archive/04-dev-tasks-archive.md`

Cascading archiving is supported: Archiving F-001 can simultaneously archive associated design/test/task docs.

See archive.md

同步命令

Sync Commands

快速检查

Quick Check

bash

/devdocs-sync --check

bash

/devdocs-sync --check

输出: 偏差报告（仅显示，不写入）

Output: Discrepancy report (display only, no write)

undefined

undefined

完整同步

Full Sync

bash

/devdocs-sync

bash

/devdocs-sync

流程: 检查 → 显示报告 → 确认 → 更新文档

Flow: Check → Display report → Confirm → Update documentation

undefined

undefined

吸收模式

Absorb Mode

bash

/devdocs-sync --absorb

bash

/devdocs-sync --absorb

流程: 检查 → 自动吸收低风险 → 确认高风险 → 生成报告

Flow: Check → Auto-absorb low-risk → Confirm high-risk → Generate report

undefined

undefined

指定范围

Specified Scope

bash

/devdocs-sync T-01 T-02

bash

/devdocs-sync T-01 T-02

只同步特定任务

Sync only specific tasks

undefined

undefined

输出文件

Output Files

进度报告

Progress Report

生成

docs/devdocs/00-progress-report.md

，包含总体进度、偏差汇总、下一步建议。

Generates

docs/devdocs/00-progress-report.md

, including overall progress, discrepancy summary, and next-step recommendations.

文档更新

Documentation Updates

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

Documentation	Update Content
`04-dev-tasks.md`	Task completion status, execution checklists
`03-test-cases.md`	Trace matrix status, test pass status
`01-requirements.md`	Feature implementation status (if status column exists)

约束

Constraints

检查约束

Check Constraints

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

Must read all DevDocs documentation before performing checks
Must generate a discrepancy report
Must request user confirmation before updating documentation (except low-risk in absorb mode)
Check results must be traceable (display check methods)

更新约束

Update Constraints

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

Do not automatically delete documentation content, only mark statuses
Do not automatically modify code, only update documentation
Preserve original documentation structure
Record timestamp during updates

吸收模式约束

Absorb Mode Constraints

安全约束

Security Constraints

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

Do not execute unknown shell commands
Use project-configured commands for test execution
Must confirm before large-scale updates

Skill 协作

Skill Collaboration

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

Scenario	Collaborating Skill	Description
Development completed	`/devdocs-dev-workflow`	Called: Trigger --trace after task completion
After task completion	`/devdocs-dev-tasks`	Trigger sync after task execution
Test traceability	`/devdocs-test-cases`	Collaboration: Update trace matrix code locations
Requirement change	`/devdocs-feature`	Sync after new feature addition
Bug fix	`/devdocs-bugfix`	Update documentation after bug fix
Insight confirmation	`/devdocs-insights`	Sync after improvement suggestion confirmation
Project refactoring	`/devdocs-retrofit`	Full sync after refactoring

参考资料

Deviation Fix Routing (Scheduler Function)

absorb-mode.md - 吸收模式详解
audit-mode.md - 追溯健康度检查
trace-mode.md - 代码追溯扫描
archive.md - 任务归档功能
examples.md - 使用示例与偏差类型

When discrepancies are detected, the report must assign clear fix routes to corresponding Skills:

Discrepancy Type	Fix Skill	Description
Missing/drifting design	`/devdocs-system-design`	Code has new interfaces but documentation not updated
AC without tests	`/devdocs-test-cases`	Acceptance criteria have no corresponding test cases
F without closed tasks	`/devdocs-dev-tasks`	Feature points have no associated development tasks
Code implemented but documentation lagging	`/devdocs-sync --absorb`	Status not updated, new content not recorded
Missing code locations in trace matrix	`/devdocs-sync --trace`	Annotations not scanned into matrix

Scheduler Principle: Discrepancy reports must not only list issues but also provide clear fix routes.

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

Recommended Call Sequence

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

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

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

Recommended sequence after task completion:

/devdocs-sync --trace    # 1. First update trace matrix code locations
        │
        ▼
/devdocs-sync            # 2. Then check overall status and update
  or --absorb            #    (absorb automatically includes trace step)

--trace
focuses on code annotation scanning,
--absorb
focuses on status absorption. They can be used independently or in combination.

调用顺序建议

Next Steps

任务完成后的推荐顺序：

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

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

After synchronization, execute the corresponding Skill according to the deviation fix routes in the progress report.

下一步

—

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

—