doc-sync

name	doc-sync
description	リポジトリ内のドキュメントを実際の実装と比較し、乖離している箇所を検出して更新するSkill。 検出した全乖離を確認なしで一括更新し、`--dry-run`指定時は更新せず差分のみ報告する。 ユーザーが「ドキュメントを更新」「READMEが古いので直して」のように依頼したら必ずこのSkillを使うこと。
allowed-tools	Read, Edit, Write, Glob, Grep, Bash(find:*), Bash(rg:*), Bash(grep:*), Bash(git:*), Bash(ls:*), Bash(cat:*), Bash(head:*), Bash(tail:*), Bash(wc:*), Bash(oxfmt:*)

doc-sync

目的

リポジトリ内のドキュメントが実装からズレていく問題を解消するためのSkillです。 ドキュメントを読み、コードと突き合わせて古い記述・抜け落ちた変更を検出し、 実装に沿った内容に更新します。

Arguments

• --dry-run: 検出のみ行い、ファイルは更新しない（差分プレビュー）
• <path>: 対象を絞り込むパス（任意。例: docs/ や README.md。指定しない場合はリポジトリ全体）
• language: 更新時の文章言語（任意。指定しない場合は既存ドキュメントの言語を維持する）

例:

• /doc-sync → リポジトリ全体を一括自動更新
• /doc-sync --dry-run → 差分検出のみ、更新はしない
• /doc-sync docs/api/ → 特定ディレクトリのみ自動更新
• /doc-sync README.md --dry-run → 単一ファイルの差分プレビュー

対象ドキュメント

以下4種類を対象にする。

種別	検出パターン
Markdown	*.md（README.md, CLAUDE.md, docs/**/*.md など）
docstring/コメント	コード内の関数・クラスのdocstring、ファイル冒頭のheaderコメント
OpenAPI/Swagger	openapi.{yaml,yml,json}, swagger.{yaml,yml,json}
設定ファイル例	.env.example, *.example.{yaml,toml,json,ini}, config.example.*

node_modules/, .git/, dist/, build/, vendor/, .venv/ は常に除外する。

作業手順

1. ドキュメント探索

対象パス（引数指定があればそれ、なければカレントディレクトリ）から、上記4種別のドキュメントを列挙する。 具体的な探索手段（Glob, Grep, find, rg など）は問わない — 効率の良い方法で網羅すること。

探索のポイント:

• 除外パスを必ず守る（node_modules/, .git/, dist/, build/, vendor/, .venv/）
• docstring/コメントは全件スキャンせず、最近変更があったコードファイルを起点にする方が効率的（git log で直近のコード変更を眺めるなど）
• リポジトリが大きい場合は、ドキュメントが集中するパス（README.md, docs/, CLAUDE.md など）を先に処理する

対象ドキュメントが1件も見つからない場合は「対象ドキュメントなし」と報告して終了する。

2. 乖離検出

各ドキュメントについて、実装と照合して古い記述を見つける。 よくある乖離パターン:

パターン	例
関数・クラス名の変更	docにはfooBar()、コードはfoo_bar()または削除済み
シグネチャの変更	doc記載の引数と実装の引数が異なる
ファイル/ディレクトリ移動	doc記載のパスにファイルが存在しない
CLIフラグ・コマンド変更	doc記載の--old-flagがCLIに存在しない
API endpointの変更	OpenAPIの/api/v1/fooが実装には無い、または逆
設定キーの変更	.env.exampleに古いキーが残っている
削除済み機能の残存記述	docに「機能X」の説明があるがコードには無い
新機能の未記載	コードに「機能Y」があるがdocに記載が無い
古いバージョン/依存関係	docの「Python 3.9以上」がpyproject.tomlでは3.11以上
古いインストール手順	doc記載の手順が現在のpackage.json/Makefileと不一致

照合方法のヒント:

• ファイルパス・関数名がdocに出てきたら、実際にそのファイル・関数が存在するかコード側で確認する
• CLIフラグなら、CLIエントリポイント（argparse/clap など）の定義と照合する
• 設定キーなら、設定ファイルを実際に読み込むコードを見つけ、参照されているキーを抽出する

具体的にどのtool（Read/Grep/Glob/Bash等）で確認するかはAIに任せる。

注意: 文体・言い回しの好みは乖離ではない。事実が間違っている箇所のみを対象にする。

3. 乖離リストの整理

検出した乖離を以下の形式でユーザーに提示する。 ファイル単位 → セクション単位で階層化する。

検出した乖離:

1. README.md
   - "## インストール" セクション
       現状: `npm install foo-cli`
       実装: `package.json`の`name`は`bar-cli`に変更されている
   - "## 使い方" セクション
       現状: `--old-flag`オプションの説明
       実装: `src/cli.ts`では`--new-flag`に改名されている

2. docs/api.md
   - "## ユーザー作成" セクション
       現状: POST `/api/v1/users`、必須フィールドは`name, email`
       実装: `src/routes/users.ts`では`name, email, role`が必須

4. 更新の適用

--dry-run が指定されていない限り、検出した全ての乖離を Edit で書き換える。 適用時は以下のセーフティを守る:

• 元の文体・言語は維持する（既存docが日本語なら日本語のまま、英語なら英語のまま）
• 無関係な書き換え（typo修正、スタイル変更、節構成の改変）は行わない
• 判断に迷う乖離（実装の意図が不明確、複数の解釈がある）は更新せずスキップし、最後に「スキップ一覧」として報告する
• 既存セクションの範囲を最小限にして書き換える（隣接セクションを巻き込まない）
• Markdownのヘッダレベル・箇条書きスタイル・コードブロック言語指定は元に揃える
• docstringはそのファイルが採用しているスタイル（Google/NumPy/reStructuredText等）に合わせる
• 表は表のまま、リストはリストのまま更新する（不必要に形式を変えない）

--dry-run が指定された場合は Edit / Write を一切呼ばず、検出した乖離リストと「もし更新するならどう書き換えるか」のbefore/afterだけを報告する。

5. 結果の報告

更新後、以下を要約して表示する。

更新済み: 5セクション (3ファイル)
- README.md: インストール, 使い方
- docs/api.md: ユーザー作成, ユーザー更新
- src/cli.ts: parseArgs() docstring

スキップ: 1セクション
- docs/internal.md: "## 構成図" — 該当する実装が見つからず判断保留

--dry-run の場合は「更新済み」を「更新予定」に置き換え、ファイル変更が無いことを明示する。

重要な原則

推測で書かない

ドキュメントを更新するときは、必ず実装の該当箇所を読んで確認してから書く。 コードを見ずにdocの文面だけで「こうだろう」と推測した内容を書かない。 判断材料が不足する場合はスキップして報告する。

過剰な変更をしない

依頼は「実装に沿わせる」であって「ドキュメントの全面リライト」ではない。 事実が古い箇所だけをピンポイントで直す。文体・構成・語彙の好みには手を出さない。

言語を維持する

既存ドキュメントが日本語なら日本語、英語なら英語のまま更新する。 language引数で明示指定された場合のみ翻訳する。

コミットしない

このSkillは更新までで終わる。git add/git commit は行わない。

制約と既知の限界

• OpenAPI/Swaggerの自動同期は範囲が広いため、実装由来のスキーマ生成ツール（zod-to-openapi等）が使われている場合は更新を控え、ユーザーに通知する
• 大規模リポジトリではドキュメント数が多くなるため、<path>引数で対象を絞ることを推奨
• モノレポでは各パッケージのドキュメントが独立している場合がある。<path>で個別パッケージに絞ること