# Sync Docs

> コードベースの現状に合わせてドキュメントを同期・更新する。 README、コンセプト、構文仕様、要求など実装とともに変遷したドキュメントを見直し、 差分があれば更新 PR を作成する。 Trigger when the user says: "ドキュメント同期", "docs sync", "sync docs", "ドキュメントを更新", "仕様を反映", "ドキュメントが古い", "stale docs", or similar phrases requesting documentation synchronization.

- Skill: `kompiro/sync-docs` (Agent Skill)
- Install (CLI): `npx skillmds@latest add kompiro/sync-docs`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kompiro/sync-docs/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: kompiro (https://skillmd.com/u/kompiro)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kompiro/sync-docs

---


# Sync Docs Skill

コードベースの現状を読み取り、陳腐化した参照用ドキュメントを更新する。

## 対象ドキュメントの決定

ホスト repo の **`CLAUDE.md`** に記載されたドキュメント表（または同等のパス一覧）を読み、対象ファイルを動的に決定する。典型的には以下のような項目が含まれる:

- README（`README.md` など）
- コアコンセプト・アーキテクチャ概要
- 構文・仕様リファレンス
- 要求・要件（requirements）
- API リファレンス

設計記録（ADR・Design Doc）や受け入れテスト記録は **対象外**（変更不可な履歴記録のため）。`CLAUDE.md` が無い repo では、ユーザーに対象ドキュメントを確認する。

## アーキテクチャ

2つの Explore エージェントを並列起動して差分を収集し、メインエージェントが更新案を生成する。

```
/sync-docs（メインエージェント）
├── Explore エージェント A: コードベース現状調査（並列起動）
├── Explore エージェント B: 対象ドキュメント読み込み（並列起動）
└── メインエージェント: 差分分析 → 更新案生成 → ユーザー確認 → PR 作成
```

## 手順

### 0. 対象ドキュメントの収集

`CLAUDE.md` のドキュメント表をパースし、対象ファイル一覧を生成する。`CLAUDE.md` が存在しない / ドキュメント表が無い場合は、ユーザーに対象を確認する。

加えて、**リポジトリルート直下の `README*.md` 全件**（`README.md`, `README.ja.md`, `README.zh-CN.md` 等）も自動的に対象に含める（`CLAUDE.md` 表で言及が無くても）。サブディレクトリの `README*.md` は再帰しない。`README.md` を **canonical（source of truth）** として扱い、それ以外は localized variant とみなす。

### 1. サブエージェントを並列起動する

以下の2つの Explore エージェントを **同時に（1メッセージで）** 起動する。

---

#### サブエージェント A — コードベース現状調査

**プロンプト（要旨）**:

> ホスト repo のソースルート（host の `package.json` の `workspaces` / `main` / `module` フィールドや、典型的な `src/` `packages/*/src/` 等から検出）を調査し、現在実装されている機能を網羅的に把握せよ。
>
> `CLAUDE.md` のドキュメント表で挙がっている各ドキュメントが扱うトピックに対応する実装観点で調べ、結果を報告せよ。例えば「構文リファレンス」が表にあるなら lexer / parser を見て対応するキーワード・ブロック・プロパティを抽出し、「要求・要件」が表にあるなら主要な機能・UI コンポーネントを抽出する。
>
> 結果は以下の形式で返せ（カテゴリは対象ドキュメントに応じて適宜追加せよ）:
> ```
> CATEGORY|サブキー|説明
> ```
>
> 例:
> ```
> SYNTAX_KEYWORD|キーワード名|説明
> SYNTAX_BLOCK|ブロック名|説明
> FEATURE|機能名|説明
> CORE_TYPE|型名|説明
> ```

---

#### サブエージェント B — 対象ドキュメント読み込み

**プロンプト（要旨）**:

> 以下のドキュメントをすべて読み込み、各ドキュメントが何を記述しているかを把握せよ。
> 陳腐化している可能性のある記述（「将来的に」「未実装」「検討中」等）を特に注意して抽出せよ。
>
> 対象ファイル: <ステップ 0 で収集した一覧をここに展開>
>
> ローカライズされた README（`README.<locale>.md` 形式）は canonical の `README.md` と並べて読み、両者の **セクション構成の差**（片方にしか無い見出し）も検出して報告せよ。
>
> 結果は以下の形式で返せ:
> ```
> DOC_ITEM|ファイルパス|行番号|内容の要約|状態（current/stale_candidate/unknown）
> README_LOCALE_GAP|ファイルパス|該当セクション|状態（missing_in_locale/missing_in_canonical/diverged）
> ```
> `stale_candidate` は「コードと食い違っている可能性がある」と判断した記述。
> 確実に古いとは言い切れないものは `unknown` とする。
> `README_LOCALE_GAP` は localized README と canonical の構造差分（`README.ja.md` には無いが `README.md` にあるセクション、または逆）を表す。

---

### 2. 差分分析と更新案の生成

両エージェントの結果を突き合わせ、以下の観点で差分を分析する:

- **実装済みだがドキュメント未記載**: コードに存在するが仕様書に載っていない機能・構文
- **ドキュメントにあるが未実装**: 仕様書に記載があるが実装されていない機能（「将来実装」等）
- **記述が古い**: 現在の実装と食い違っている記述
- **README localized 追従漏れ**: `README.md`（canonical）にあるが `README.<locale>.md` で対応する記述が古い・欠落・存在しない

更新すべき箇所を特定したら、各ファイルへの具体的な変更案を作成する。Localized README については以下に従う:

- `README.md` を真として、対応する箇所を `README.<locale>.md` 側でも更新する案を作成する
- 翻訳トーンは既存の localized README の語彙・文体に揃える（直訳ではなく追従）
- localized README に欠けているセクションは **draft 翻訳付きの追記案**として提示し、ユーザー確認を得てから適用する
- 逆方向（localized → canonical）の自動上書きは行わない

### 3. ユーザーへの確認

更新案をユーザーに提示する。提示形式:

```
## 更新候補

### README.md
- Line N: 「...（古い記述）...」→ 「...（新しい記述）...」

### README.ja.md（localized — 上記 README.md 変更への追従）
- Line N: 「...（古い記述）...」→ 「...（新しい記述、ja トーン）...」
- 欠落セクション「<heading>」: draft 翻訳付きで追記提案

### docs/spec/<...>.md
- 未記載の構文要素: <要素名>
  → セクション XX に追記提案

（更新不要と判断したドキュメントは「変更なし」と明記）
```

ファイル別に独立して提示し、ユーザーがファイル単位で承認・却下できるようにする（例: 「README.md は OK、README.ja.md は次回」）。

ユーザーが承認した変更のみを次のステップで適用する。

### 4. 変更の適用と PR 作成

1. `git worktree` が作成済みかを確認する（`/sync-docs` は worktree 内で実行されることを前提とする）
2. 承認された変更をファイルに適用する
3. `/commit` スキルで変更をコミットする
4. `/ship` スキルで PR を作成する

## 注意事項

- **ADR・Design Doc・AT は変更しない**: これらは設計判断の記録であり、後から変更するべきでない
- **削除より追記を優先**: 「将来実装」等の記述は削除せず、実装済みであれば「実装済み」に変更する
- **一度に全更新しない**: 変更範囲が大きい場合は、ファイルごとに分けて PR を作成することを提案する
- **コードが正の源泉**: ドキュメントとコードが食い違う場合、コードの実装を正とする
- **`README.md` が localized 版の正の源泉**: `README.md` と `README.<locale>.md` が食い違う場合、`README.md` を正として localized 版を追従させる。逆方向の自動上書きはしない（言語の表現差は意図的な可能性があるため）