doc-sync

name	doc-sync
description	コードの現状を説明したドキュメント（仕様書・設計メモなど）を、その後に入ったコード変更へ追従させて最新化するスキル。次の場合に必ず使う：(1)「このドキュメントを最新の仕様に合わせて」「前回更新以降の変更を取り込んで」「仕様変更をドキュメントに反映して」のような依頼、(2) コードを変更したあとに対応するドキュメントが古くなっていそうなとき、(3) 既存のドキュメントを開いて「これ古くなってない？」という文脈になったとき。ドキュメントの最終更新コミットを起点に、それ以降のコード差分のうちその対象に関わるものだけを抽出して反映する。軽微な文言修正ではなく、ドキュメントとコードの乖離を埋めるのが目的。
license	MIT

ドキュメントをコード変更に同期する

「コードの現状を説明したドキュメント」は、コードが変わると静かに古くなる。このスキルは、ドキュメントが最後に更新された時点を起点に、それ以降のコード変更のうちそのドキュメントが扱う対象に関わるものだけを拾って反映する手順。

このスキルの肝

1. 差分の起点を正しく取る。起点がずれると、反映済みの変更を二重に書いたり取りこぼしたりする。ドキュメント自身のコミット履歴が最も確実な起点になる。

2. 対象に関係する変更だけに絞る。起点以降のリポジトリ全体の差分には、依存更新・別機能・設定など無関係な変更が大量に混ざる。「このドキュメントは何を説明しているか」を最初に押さえ、その対象に触れた変更だけを選り分ける。全差分を舐めると時間も精度も落ちる。

3. ドキュメントは文章なので機械的な置換では壊れる。用語が変わった・概念が廃止された、といった変更は、本文・図・表・手順など複数箇所に波及する。1箇所直して終わりにせず、「その変更がどこに効くか」の観点で全体を見渡す。

進め方

1. 対象ドキュメントと、それが説明している対象を把握する

会話の文脈や開いているファイルから対象ドキュメントを特定する。不明ならユーザーに確認する。

通読して何を・どの粒度で説明しているかを掴む。特に拾うべきは:

• 中心となる概念・用語
• 言及されているコード上の固有名（クラス・関数・パス・画面・API など）
• 実装に依存して書かれた「現状の決め打ち」「制約」の記述

これらが「コードのどの変更がドキュメントのどこに効くか」をマッピングする手がかりになる。

2. 差分の起点（ドキュメントの最終更新コミット）を特定する

ドキュメント自身のコミット履歴の先頭が原則の起点 <BASE>:

git log --oneline -- <ドキュメントのパス> | head -5

例外・確認:

• ユーザーが起点（コミットSHA・タグ・日付・「このPR以降」など）を明示したらそちらを優先。
• 直近のドキュメント更新が誤字修正など中身を伴わないものなら、その手前の実質的な更新コミットを起点にすべきこともある。コミットメッセージで判断し、迷ったら確認する。

3. 起点以降の差分から、対象に関わる変更だけを抽出する

git log --oneline <BASE>..HEAD
git diff --stat <BASE>..HEAD

手順1で掴んだ固有名・概念をキーに、コミットメッセージやファイルパスで対象に関係する変更だけを選り分ける:

git log --oneline <BASE>..HEAD -- <対象に関わるディレクトリやファイルのglob>

選んだ変更の中身を読み、何がどう変わったかを一文で言えるレベルまで理解する。仕様の挙動に効かない純粋なリファクタやテストだけの変更は本文に影響しないことが多い（ただしドキュメントがコード上の固有名に言及していれば、その名前の変更は反映が要る）。

調査範囲が広く不確実なときは Explore エージェントに「このドキュメントが説明する対象に、起点以降で入った変更」を調べさせると速い。ただし最終的な取捨選択は自分で行う。

4. 変更 → ドキュメント該当箇所のマッピングを作る

抽出した各変更について「ドキュメントのどの記述に効くか」を対応づける。これが反映作業の設計図になる。観点:

• 用語・概念の変更/廃止: 用語の定義、本文、図のラベル、状態・遷移、制約、手順 ── 波及範囲が広い。全箇所を洗い出す。
• 操作・インターフェースの追加/変更: フロー、手順、確認方法、コード上の固有名の記述。
• 挙動の変更: 制約、現状の決め打ち、副作用や通知の一覧。
• 実装の置き換え: コード上の固有名への言及。本文の概念説明には影響しないこともある。

5. 反映方針をユーザーに確認する

機械的に決められない判断が出たら、反映前に AskUserQuestion で確認する。典型例:

• 廃止された用語を完全に消すか / 「廃止された」と経緯を残すか。
• 抽出した変更をすべて反映するか / 一部に絞るか。
• 「今後の検討」的な未解決セクションがあり方針が決まっている場合、未解決のままにするか / 決定事項に書き換えるか。

明確な変更だけなら確認を省いて進めてよい。

6. ドキュメントに反映する

マッピングに沿って順に直す。注意:

• 図のラベル変更はコードブロック内の記法（ノードID・矢印など）を壊さないこと。対象ラベルだけ差し替える。
• 用語の置換は本文・表・図・手順すべてに及ぶ。一括置換に頼らず、文脈ごとに自然な文になるよう前後も整える。
• 追記は既存の同種記述と同じ粒度・文体に合わせ、浮かないようにする。
• 経緯を残す場合は「以前は○○だったが△△に変わった」と一文で簡潔に。

7. 取りこぼし・壊れをチェックする

反映後、旧記述が残っていないか確認する:

grep -n '<廃止した用語>\|<旧仕様の値>' <ドキュメントのパス>

残ってよいのは「廃止された」「以前は」という経緯説明の文脈だけ。図を変更した場合は変更後のブロックを目視で確認し、記法の整合を取る。

最後に反映した変更の一覧をユーザーに報告する。

注意

• このスキルはドキュメントの同期だけを行う。コードは変更しない。
• 起点の特定を間違えると全体が狂う。最初に git log -- <doc> で確実に押さえる。
• 「全差分を読む」のではなく「対象の差分に絞る」。無関係な変更に時間を使わない。
• 新しく足す記述は近くの同種記述に文体・粒度を合わせ、浮かないようにする。