---
name: sync-docs
description: コミット前にエージェントチームで全ドキュメント (CLAUDE.md / README / CHANGELOG / docs/) を監査し、コード変更に応じて自動更新します。大規模変更時の documentation drift を予防。
argument-hint: "[commit-range]"
disable-model-invocation: true
allowed-tools: Agent Bash(git diff *) Bash(git log *) Bash(git status *) Read Glob Grep Edit Write
---

# ドキュメント同期 (エージェントチーム並列監査)

コード変更に対して **CLAUDE.md / README / CHANGELOG / docs/features / docstring** を一括で監査し、更新が必要な箇所を検出して自動適用します。

## 前提

このスキルは **コミット前** に使うことを想定しています。コミット済みの変更と未ステージ変更の両方を対象にします。

## 入力

- `$ARGUMENTS` が空: `dev..HEAD` (現在のブランチの全変更) + 未コミット変更
- `$ARGUMENTS` = `staged`: ステージ済み変更のみ (`git diff --cached`)
- `$ARGUMENTS` = `HEAD~3..HEAD`: 特定のコミット範囲
- `$ARGUMENTS` = ファイルパス: そのファイルの変更のみ

## 現在の状態

- ブランチ: !`git rev-parse --abbrev-ref HEAD`
- dev との差分ファイル数: !`git diff --name-only dev..HEAD 2>/dev/null | wc -l | tr -d ' '`
- 未コミット変更: !`git status --short 2>/dev/null | wc -l | tr -d ' '`

## フェーズ 1: 変更サマリ収集

1. `git diff --name-only` で変更ファイルをカテゴリ分類:
   - **実装** (`src/python_run/piper_plus/*.py`, `src/python/g2p/**`, `src/rust/piper-core/**`, `src/cpp/*.cpp`, `src/csharp/**`, `src/go/**`, `src/wasm/openjtalk-web/src/*.js`)
   - **テスト** (`*/tests/**`, `*/test/**`)
   - **ビルド** (`*.toml`, `*.json`, `CMakeLists.txt`, `*.yml`)
   - **ドキュメント** (`*.md`, `docs/**`)

2. 各カテゴリのファイル数と代表ファイルを記録

## フェーズ 2: 並列ドキュメント監査 (エージェントチーム)

以下の 7 エージェントを **1 メッセージで並列起動** します:

### Agent 1: CLAUDE.md 監査

**subagent_type**: `Explore`
**task**: CLAUDE.md の「実装済み機能」「重要なファイルパス」「OpenAI 互換 API」セクションを確認し、実装変更に対する追加・修正が必要か判定。新規モジュール/クラス/HTTP エンドポイント/テストファイルが未記載なら、具体的な diff を提案。

### Agent 2: ルート README 監査

**subagent_type**: `Explore`
**task**: `README.md`, `README_EN.md`, `README.*.md` (他言語) の Features / Interfaces / Feature Support Matrix を確認。新機能が各ランタイムで利用可能になった場合、対応 runtime 行を更新。

### Agent 3: ランタイム別 README 監査

**subagent_type**: `Explore`
**task**: `src/python_run/README.md`, `src/python_run/README_http.md`, `src/wasm/openjtalk-web/README.md`, `src/wasm/openjtalk-web/README.npm.md`, `src/rust/piper-cli/README.md`, `src/go/README.md` を確認。API 例・CLI フラグ・HTTP エンドポイントが最新か判定。

### Agent 4: CHANGELOG 監査

**subagent_type**: `Explore`
**task**: `CHANGELOG.md` と `src/wasm/openjtalk-web/CHANGELOG.md` の `[Unreleased]` セクションが、コード変更 (新機能/バグ修正/破壊的変更) を反映しているか確認。未反映なら具体的な markdown を提案。

### Agent 5: docs/features・docs/spec 監査

**subagent_type**: `Explore`
**task**: `docs/features/*.md` と `docs/spec/*.toml` / `*.md` を確認。新機能の専用ドキュメントが必要か、既存の仕様ファイル (ort-session-contract.toml, short-text-contract.toml, phoneme-timing-contract.toml など) の更新が必要か判定。

### Agent 6: docstring / JSDoc 整合性監査

**subagent_type**: `Explore`
**task**: 変更された公開 API (関数・クラス・メソッド) に docstring / JSDoc / TypeScript 型定義があるか確認。新規 public API に docstring がない、または既存の docstring が実装と齟齬している箇所を検出。

### Agent 7: Version Drift 監査 (release-versions.toml canonical)

**subagent_type**: `Explore`
**task**: 以下の 3 段階で version-drift を検出する。

1. **Canonical 抽出**: `docs/spec/release-versions.toml` を読み、各ランタイム (`python`, `rust`, `dotnet.core`, `dotnet.cli`, `npm.synthesis`, `npm.g2p`, `swift.synthesis`, `swift.g2p`, `kotlin.android_g2p`) の `expected_prefix` を取得 (例: `"1.12."`, `"0.4."`)。これを canonical truth とする。

2. **CLAUDE.md ランタイム別パッケージ表との照合**: CLAUDE.md の「ランタイム別パッケージ」表 (現在 L177-186 付近、 `| ランタイム | パッケージ | バージョン |` を含む table) を grep で抽出し、各ランタイムの記載バージョンが `expected_prefix` で始まるかを確認。不一致なら drift 報告。

3. **`docs/spec/*.toml` 内 version comment 監査**: 全 `docs/spec/*.toml` を grep で `# v1\.|# v0\.` 等の version reference comment を抽出し、`release-versions.toml` の expected_prefix とずれていないか確認 (例: `audio-format-contract.toml` の `# v1.12.0 で HiFi-GAN は削除` が canonical と矛盾していないか)。

4. **CHANGELOG.md unreleased 重複検査**: `CHANGELOG.md` の `[Unreleased]` セクションに、既に release tag が付いた version (`release-versions.toml::expected_prefix` で始まる version) への reference が残っていないか確認。残っていれば「release 後の cleanup 漏れ」として報告。

5. **README ランタイム matrix 整合性**: `README.md` および `README_EN.md` の Feature Support Matrix / ランタイム表に書かれたバージョン番号が canonical と一致するか確認。

報告形式は他の Agent と同じく markdown diff。 drift が見つからなければ「全 N ランタイム version 整合」と報告。

各エージェントには以下を渡します:

- 変更ファイル一覧 (フェーズ 1 の出力)
- 対象ディレクトリ
- 「読み取りのみ、変更提案は markdown diff 形式で報告」という指示

## フェーズ 3: 更新提案の統合

6 エージェントの結果を収集し、以下の形式で **統合レポート** を作成:

```text
## ドキュメント監査結果

### 🔴 更新必須 (機能との不整合)
| ファイル | 問題 | 提案 |
|---------|------|------|
| CLAUDE.md | 新機能 X が未記載 | 「## 実装済み機能」に新セクション追加 |
| ... | ... | ... |

### 🟠 更新推奨 (品質向上)
| ファイル | 問題 | 提案 |
|---------|------|------|
| README.md | Feature matrix 未更新 | ... |

### 🟢 更新不要
(問題なしのファイル一覧)
```

## フェーズ 4: ユーザー確認 → 自動適用

1. 統合レポートをユーザーに提示
2. ユーザーの承認を得る (「適用してください」等)
3. 承認後、各エージェントが提案した変更を Edit tool で適用
4. 変更後、`git diff` で最終確認

## フェーズ 5: コミット準備

適用が完了したら、以下を表示:

- 更新されたファイルのリスト
- `/commit` skill を呼び出してコミットするよう促す
- または、ドキュメント更新を別コミットに分ける提案

## 注意事項

- **ユーザーの承認なしに勝手に適用しない** (フェーズ 3 → 4 の間で確認を取る)
- **既存の正しい記述を破壊しない** (削除・書き換えは最小限)
- **監査のみ要求された場合** (例: `/sync-docs --audit-only`) は フェーズ 4 をスキップ
- 大規模変更 (>500 行) では特に CLAUDE.md / CHANGELOG の更新を重点確認
- 新規 test ファイルが追加された場合、CLAUDE.md の「テスト」項目に件数を追記することを検討

## 実行例

```text
/sync-docs
→ フェーズ 1-3 を実行し、監査レポートを提示
→ ユーザー承認後、フェーズ 4-5 を実行

/sync-docs staged
→ ステージ済み変更のみを監査

/sync-docs HEAD~3..HEAD
→ 直近 3 コミットを監査
```

## 期待効果

PR #349 で発生した「ドキュメント更新を一括で後付けする」パターンを、**コミット単位で小さく防止** します。エージェントチームを並列で動かすことで、7 観点の監査を短時間で完了できます。

Agent 7 (Version Drift 監査) により、`release-versions.toml` を canonical とした以下の drift を一括検出:

- CLAUDE.md ランタイム別パッケージ表のバージョン番号
- `docs/spec/*.toml` 内に埋め込まれた version comment (`# v1.12.0 で削除` 等)
- CHANGELOG.md `[Unreleased]` の release 済み version reference 残留
- README Feature Support Matrix のランタイム version

memory `feedback_data_asset_distribution.md` で記録された「新規データファイル追加時 7 箇所の package metadata 更新」を補強する観点。