devdocs-sync
開発後のドキュメント更新、コードとドキュメントの整合性確認、実装進捗の把握といったニーズに対し、「sync docs」などのキーワードをトリガーに、ドキュメントと実装の進捗を同期させるSkill。
📜 元の英語説明(参考)
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", "同步文档", "更新进度".
🇯🇵 日本人クリエイター向け解説
開発後のドキュメント更新、コードとドキュメントの整合性確認、実装進捗の把握といったニーズに対し、「sync docs」などのキーワードをトリガーに、ドキュメントと実装の進捗を同期させるSkill。
※ jpskill.com 編集部が日本のビジネス現場向けに補足した解説です。Skill本体の挙動とは独立した参考情報です。
下記のコマンドをコピーしてターミナル(Mac/Linux)または PowerShell(Windows)に貼り付けてください。 ダウンロード → 解凍 → 配置まで全自動。
mkdir -p ~/.claude/skills && cd ~/.claude/skills && curl -L -o devdocs-sync.zip https://jpskill.com/download/8776.zip && unzip -o devdocs-sync.zip && rm devdocs-sync.zip$d = "$env:USERPROFILE\.claude\skills"; ni -Force -ItemType Directory $d | Out-Null; iwr https://jpskill.com/download/8776.zip -OutFile "$d\devdocs-sync.zip"; Expand-Archive "$d\devdocs-sync.zip" -DestinationPath $d -Force; ri "$d\devdocs-sync.zip"完了後、Claude Code を再起動 → 普通に「動画プロンプト作って」のように話しかけるだけで自動発動します。
💾 手動でダウンロードしたい(コマンドが難しい人向け)
- 1. 下の青いボタンを押して
devdocs-sync.zipをダウンロード - 2. ZIPファイルをダブルクリックで解凍 →
devdocs-syncフォルダができる - 3. そのフォルダを
C:\Users\あなたの名前\.claude\skills\(Win)または~/.claude/skills/(Mac)へ移動 - 4. Claude Code を再起動
⚠️ ダウンロード・利用は自己責任でお願いします。当サイトは内容・動作・安全性について責任を負いません。
🎯 このSkillでできること
下記の説明文を読むと、このSkillがあなたに何をしてくれるかが分かります。Claudeにこの分野の依頼をすると、自動で発動します。
📦 インストール方法 (3ステップ)
- 1. 上の「ダウンロード」ボタンを押して .skill ファイルを取得
- 2. ファイル名の拡張子を .skill から .zip に変えて展開(macは自動展開可)
- 3. 展開してできたフォルダを、ホームフォルダの
.claude/skills/に置く- · macOS / Linux:
~/.claude/skills/ - · Windows:
%USERPROFILE%\.claude\skills\
- · macOS / Linux:
Claude Code を再起動すれば完了。「このSkillを使って…」と話しかけなくても、関連する依頼で自動的に呼び出されます。
詳しい使い方ガイドを見る →- 最終更新
- 2026-05-18
- 取得日時
- 2026-05-18
- 同梱ファイル
- 1
📖 Skill本文(日本語訳)
※ 原文(英語/中国語)を Gemini で日本語化したものです。Claude 自身は原文を読みます。誤訳がある場合は原文をご確認ください。
ドキュメント同期
DevDocs ドキュメントを実際の実現進捗と一致させ、偏差を検出し、状態を更新します。
言語規則
- 中国語と英語での質問をサポート
- 中国語での回答に統一
- 中国語を使用してドキュメントを生成
トリガー条件
- ユーザーが1つまたは複数の開発タスクを完了した後
- ユーザーがドキュメントとコードの一貫性を確認する必要がある場合
- ユーザーがドキュメントの進捗状況を更新する必要がある場合
- 定期的な同期（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 |
改造後に全量同期 |
参考資料
- absorb-mode.md - 吸収モード詳細
- audit-mode.md - 追跡健全性チェック
- trace-mode.md - コード追跡スキャン
- archive.md - タスクアーカイブ機能
- examples.md - 使用例と偏差タイプ
偏差修正ルーティング（スケジューラ機能）
偏差が検出された場合、報告書に次の修正 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 を実行します。
📜 原文 SKILL.md(Claudeが読む英語/中国語)を展開
文档同步
保持 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/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 |
改造后全量同步 |
参考资料
- absorb-mode.md - 吸收模式详解
- audit-mode.md - 追溯健康度检查
- trace-mode.md - 代码追溯扫描
- archive.md - 任务归档功能
- examples.md - 使用示例与偏差类型
偏差修复路由（调度器功能）
当检测到偏差时，必须在报告中指派下一步修复 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。