ドキュメントドリフト対策に Claude Code：ドキュメントをコードと整合させ続ける

ドキュメントドリフトとは（なぜ繰り返し起きるのか）

ドキュメントドリフトは、ドキュメントの記述とコードの実際の挙動が徐々にずれていく現象です。最初は小さな不一致から始まり、やがて「先月は動いたはずだ」という混乱に発展します。

実際のチームではこう見えます：README ではサービスを1つのコマンドで起動できると書かれているのに、新しい環境変数が必須になっている。API ドキュメントではフィールド名が古いまま。ランブックにはオンコールに「worker-a を再起動せよ」と書かれているが、プロセスは二つのサービスに分かれている。

ドリフトは意図が悪いから起きるのではなく、ソフトウェアの変更速度がドキュメントの更新習慣を上回るために起きます。人はプレッシャーの下で修正を出し、古い例をコピペし、誰かが後で更新するだろうと仮定します。また、README、API リファレンス、社内 Wiki、チケット、口伝といった「真実の源」が多すぎると成長しやすくなります。

コストは具体的です：

• オンボーディングが壊れる（新入者がセットアップで何日も停滞する）
• デプロイが失敗する（手順が現在の設定と合っていない）
• サポートの負荷が増す（ユーザーが古い手順に従う）
• インシデントが長引く（ランブックが誤った方向に導く）

文章を磨くだけでは、事実が間違っている限りドリフトは直りません。役立つのはドキュメントを検証可能なものとして扱うことです：現在のコード、設定、実際の出力と比較して矛盾を指摘し、ドキュメントが約束している挙動がコードにないときはそれを明示します。

ドリフトが現れる場所：README、API ドキュメント、ランブック

ドリフトは通常「クイックリファレンス」として扱われるドキュメントに現れます。これらは一度だけ更新されて、その後コードが進み続けます。まずは次の三つから始めましょう。これらは検証可能な具体的な約束を含んでいるからです。

README：ユーザーが最初に痛みを感じる場所

日常のコマンドが変わると README はドリフトします。新しいフラグが追加されたり、古いフラグが削除されたり、環境変数名が変わっているのにセットアップ欄は古い現実を示したままです。新しいチームメンバーが指示をコピペしてエラーに遭遇し、プロジェクトが壊れていると考えます。

最悪なのは「ほとんど合っている」バージョンです。1つの不足した環境変数が、完全に時代遅れの README よりも多くの時間を無駄にすることがあります。人は小さなバリエーションを試し続け、ドキュメント自体を疑わないからです。

API ドキュメント：型や例がずれる

リクエストやレスポンスのフィールドが変わると API ドキュメントはドリフトします。小さな変化（キーの名前変更、デフォルトの変更、新しい必須ヘッダ）でもクライアントを壊します。しばしばエンドポイント一覧は正しい一方で、例が古く、それをユーザーがコピペします。

典型的な兆候：

• サンプルペイロードにサーバが受け取らないフィールドが含まれている。
• レスポンス例が古いエラーフォーマットやステータスコードを示している。
• パラメータ表で必須になったフィールドが任意のままになっている。
• 認証の注意書きが現在は機能しないヘッダやスコープを記している。
• ページネーション、ソート、フィルタのルールが実際と合っていない。

ランブック：静かなドリフトが大きなインシデントを招く

デプロイ、ロールバック、運用手順が変わるとランブックはドリフトします。1つの古いコマンド、間違ったサービス名、欠けた前提条件がルーチンの修正をダウンタイムに変えます。

「正しいが不完全」なこともあります：手順は動くが新しいマイグレーション、キャッシュクリア、機能フラグの切り替えを飛ばしている。そうすると対応者はランブック通りに動いても驚かされます。

Claude Code の使い方：差分と矛盾の指摘

ドキュメントドリフトに対する Claude Code は、ドキュメントをコードのように扱うときに最も効果を発揮します：小さくレビュアブルなパッチを提案し、その理由を説明する。単に「README を更新して」と頼むのではなく、特定のファイルに対する差分を生成するように依頼してください。レビュアーは変更前後が明確に見えるので意図しない変更に気づきやすくなります。

良いドリフトチェックは次の二つを生成します：

1. 最小限の差分
2. はっきり具体的な矛盾レポート：「ドキュメントは X と言うが、リポジトリは Y を示す。」

意見ではなく証拠を求める

プロンプトでは、リポジトリからの証拠を必須にしてください：ファイルパスやルート、設定値、テストなど、現在の挙動を示す詳細。

以下のようなプロンプトパターンは現実に根ざしたチェックを保ちます：

Check these docs for drift: README.md, docs/api.md, runbooks/deploy.md.
Compare them to the current repo.
Output:
1) Contradictions list (doc claim -> repo evidence with file path and line range)
2) Unified diffs for the smallest safe edits
Rules: do not rewrite sections that are still accurate.

もし Claude が「API は /v2 を使う」と言うなら、それをルーター、OpenAPI スペック、あるいは統合テストで裏付けるように要求してください。証拠が見つからないなら、その旨を明確に伝えるべきです。

編集する前に影響範囲を決める

ドリフトは通常、1つのコード変更が複数のドキュメントに静かに影響することから始まります。まず Claude に影響範囲を特定させてください：何が変わったか、どこが変わったか、どのドキュメントに影響がありそうか、どのユーザー操作が影響を受けるか。

例：環境変数名を API_KEY から SERVICE_TOKEN に変えたとします。有用なレポートは古い名前が現れるすべての箇所（README のセットアップ、API 例、ランブックのシークレット欄）を見つけ、該当する行と、今なら失敗するであろう例コマンドだけを最小限に更新する差分を作ります。

何かをプロンプトする前にシンプルなワークフローを整える

「すべてのドキュメント」を無秩序にモデルに投げると、事実が間違ったまま滑らかな書き換えがされがちです。シンプルなワークフローは変更を小さく、繰り返し可能で、レビューしやすく保ちます。

まず 1 つのドキュメントセットから始めてください：README、API リファレンス、あるいは人が実際に使う単一のランブック。1つの領域を端から端まで直すことで、信頼できるシグナルが何かを学び、それをスケールできます。

真実の源を決める

そのドキュメントセットにとって事実がどこから来るべきかを平易に書き出します。

• README の場合：CLI のヘルプ出力と動作するサンプルアプリ
• API ドキュメント：ルーター定義と統合テスト
• ランブック：デプロイ設定とその手順を起動するアラート

ソースを定めるとプロンプトが鋭くなります：「README を現在の CLI 出力と設定デフォルトと比較して、パッチを生成して」といった形です。

レビュアーが速く検証できる出力形式を選ぶ

実行前に出力形式を合意しておくと、何が変わったかとその理由が見やすくなります。混合フォーマットは何が変わったかをわかりにくくします。

簡単なルールセット：

• すべてのドキュメント変更に diff を要求し、1 文の理由を添える。
• ツールが安全に言い換えできない場合のみ短い矛盾一覧を許す。
• 可能なら差分は 1 ファイルに絞る。
• 失敗する例（コマンド、リクエスト、コードスニペット）は一般的な文言より優先度高。

実務習慣の例：各ドキュメント PR に「Source of truth checked: routes + tests」のような注を付けて、レビュアーが何と照合したかすぐわかるようにします。これでドキュメント更新は「見た目良し」から「何かに照らして検証済み」になります。

ステップバイステップ：変更ごとにドキュメントをコードと揃える

各コード変更を小さなドキュメント調査として扱ってください。目的は矛盾を早期に発見し、レビュアーが信頼できる最小パッチを作ることです。

まずチェックするファイルと明確なドリフト質問を選びます。例：「環境変数、CLI フラグ、HTTP ルート、エラーコードの変更がドキュメントに残っていないか？」と具体的に問うと、モデルが全体を書き換えるのを防げます。

次に Claude Code にコードからハードファクトを抽出させます。リストは具体的に：ユーザーが実行するコマンド、エンドポイントとメソッド、リクエストとレスポンスのフィールド、設定キー、必須環境変数、スクリプトや設定で参照される運用手順。コードに見つからないものは「not found」と答えさせ、推測を避けます。

その後、比較表（ドキュメントの主張、コードの示すもの、状態（match, mismatch, missing, unclear））を出させます。これが議論を地に足のついたものにします。

最後に最小限の unified diff を要求してください。必要な行だけを変え、ドキュメントの既存スタイルを保ち、コードで裏付けられない約束を追加しないよう指示します。

締めとしてレビュアー向けの短いサマリを付けます：何が変わったか、なぜ変わったか、二重チェックすべき点（リネームされた環境変数や新しい必須ヘッダなど）。

API ドキュメント：エンドポイントと例を検証する実務的な方法

API ドキュメントはコードが静かに変わったときにドリフトします：ルートがリネームされる、フィールドが必須になる、エラー形式が変わるなど。結果としてクライアントの統合が壊れ、デバッグに無駄な時間がかかります。

Claude Code を使ったドリフト検査では、リポジトリから API の挙動を証明し、ドキュメントの不一致を指摘することが仕事です。ルーティングとハンドラからインベントリを抽出し（パス、メソッド、リクエスト/レスポンスモデル）、API リファレンスと比較させてください。

人がコピペするものに注目します：curl コマンド、ヘッダ、サンプルペイロード、ステータスコード、フィールド名。単一のプロンプトで以下をチェックさせます：

• 認証要件（ヘッダ、トークン種別、公開エンドポイント）
• ページネーションパラメータとデフォルト
• エラーステータスコードと JSON 形式
• バージョニングの挙動（v1 と v2）
• サンプルが現在のバリデーションルールに合っているか

不一致を見つけたら、コード（正確なルート定義、ハンドラ挙動、スキーマ）に由来する証拠を引用できる差分だけを受け入れてください。そうすることでパッチは小さくレビュー可能になります。

例：コードが POST /widgets で 201 を返し、name フィールドを必須にしたのに、ドキュメントはまだ 200 を示し name を省略している。良い出力は両方の矛盾を指摘し、そのエンドポイントのステータスコードと例の JSON だけを更新します。

ランブック：古くなった手順での障害を減らす

ランブックは最も高コストな方法で失敗します：見た目は完全でも手順が今のシステムと合っていないためです。環境変数のリネームやデプロイコマンドの変更が、インシデント中に対応者を誤った方向に導きます。

ランブックをコードとして扱い、リポジトリに対する差分と矛盾指摘を要求してください。比較対象は現在使っているスクリプト、設定デフォルト、ツールです。

インシデント時に最もスラッシュ（無駄なやり直し）を生む失敗点に注目します：

• 記載されているコマンドは現在のスクリプトとフラグに一致しているか？
• 「デフォルト」設定値は現在のアプリと一致しているか？
• 必要な環境変数やシークレットはコードとデプロイ設定で参照されているか？
• デプロイとロールバック手順は現在のリリースツールと名前付けに合っているか？
• 「既知の良い」値（ポート、リージョン、タイムアウト）は現実と一致しているか？

また、対応者が進捗を確認できる簡単な事前チェックと期待される出力（ステータスライン、バージョン文字列、ヘルスチェック応答など）を追加してください。「動くことを検証せよ」だけでは不十分です。

もし Koder.ai などのプラットフォームでアプリをビルド／デプロイしているなら、スナップショットとロールバックはランブックが正しいアクションを命名しているときにのみ有効です。

ドリフトを悪化させる一般的なミス

ドキュメントを「読み物」として扱い、コードと一致させる主張のセットとして扱わないことが最短でドリフトを生む道です。

整合性を壊すよくあるミス

まず書き換えを求めることです。矛盾チェックを飛ばすと、より滑らかな文章になっても挙動が間違ったままになることがあります。必ず最初に「ドキュメントは何を主張しているか」「コードは何をしているか」「どこが違うか」を問うてください。

モデルに推測させるのも危険です。挙動がコードやテスト、設定に見えないなら、それは不明として扱ってください。「おそらく」は README の約束が生まれる方法であり、ランブックが作り話になるきっかけです。

日常の更新でよく見られる問題：

• セクションを更新しても、例やエラーメッセージ、エッジケースをそのままにしてしまう。
• 概念を一箇所でリネームして（README）他の場所（API ドキュメント、設定キー、ランブック）を忘れる。
• エンドポイント説明を直してもリクエスト／レスポンスのサンプルを忘れる。
• 挙動を変えたのにデフォルトや制約の注記を更新しない。
• 差分に「なぜ変えたか」を短く書かずにマージしてしまう。

小さな例

ハンドラが期限切れトークンに対して 401 ではなく 403 を返すように変わり、ヘッダ名が X-Token から Authorization に変わったとします。認証セクションだけを書き換えると、API ドキュメントの例は古いヘッダのまま、ランブックは 401 の急増を探せと指示しているかもしれません。

差分を生成するときは、次のような決定行を添えてください：

"Auth failures now return 403 to distinguish invalid vs missing credentials."

こう書くことで、次の人がドキュメントを古い挙動に戻すのを防げます。

マージ前の簡単チェックリスト

すべてのドキュメント更新を小さな監査として扱ってください。目的は、来週誰かが手順に従ったときの驚きを減らすことです。

ドリフトを防ぐ五つのチェック

マージ前に README、API ドキュメント、ランブックを見返し、具体的な主張を一つずつ検証します：

• コマンド、エンドポイント、設定キー、環境変数、ポート、サンプルペイロードなど、主張をハイライトする。
• 各主張について、それを証明する正確なファイル（ソース、設定、スキーマ、マイグレーション、テスト、CLI ヘルプ出力）を記す。証拠がすぐに見つからなければ推測せずに unknown とする。
• 証拠がある箇所だけ最小差分を要求する。主張が unknown な場合、その変更は質問や TODO に変える。
• 例の整合性を確認する：入力が現在コードで受け入れられるものと一致しているか（パラメータ名、必須フィールド、ヘッダ、デフォルト値）。長い例はドリフトの温床。
• ランブックなら手順が起こり得る故障、セーフなロールバック、回復の検証方法をカバーしているかを確認する。

早期停止ルール

同じドキュメントに unknown な主張が 2 個以上見つかったらマージを止めてください。証拠（ファイルパスや関数名）を追加するか、確実な部分だけに文を削るべきです。

例シナリオ：1つの機能変更が三つのドキュメントに波及する

小さなチームが認証を更新しました：API キーを X-API-Key に送る代わりに、クライアントは短命トークンを Authorization: Bearer <token> として送ります。コードは出荷され、テストは通り、チームはそのまま進みます。

二日後、新しい開発者が README に従います。そこにはまだ「環境変数に X-API-Key を設定して」と書かれていて、curl の例も古いヘッダのままです。ローカルで動作しないと、サービスが落ちていると思ってしまいます。

同時に API ドキュメントも古いままです。古いヘッダを説明し、まだ user_id というフィールド名を示しているが、実際の API は userId を返します。文章に問題はないがコードと矛盾しているため、読者は誤ったものをコピペします。

その後インシデントが発生します。オンコールはランブックの「API キーを回転してワーカーを再起動」手順に従いますが、問題はトークン検証の失敗であり、ランブックは 20 分間間違った方向に対応者を導きます。

ここで Claude Code が有用なのは、差分と矛盾指摘を出すときです。フルリライトではなく、認証ミドルウェアとルートハンドラを README スニペット、API 例、ランブックステップと比較して、最小パッチを提案させます：

- Header: X-API-Key: <key>
+ Header: Authorization: Bearer <token>

- { "user_id": "..." }
+ { "userId": "..." }

重要なのは、矛盾をフラグし、正確な箇所を示し、リポジトリが古くなったことを証明した部分だけを変更する点です。

次のステップ：ドリフトチェックをルーティン化する

ドキュメントが正確であり続けるためには、チェックを退屈で繰り返し可能な作業にすることです。変更の危険度に合わせた頻度を選んでください。頻繁に動くコードなら PR ごとにチェックを。安定したサービスなら週次のスイープとリリース前チェックで十分なことが多いです。

ドキュメントドリフトをテスト失敗のように扱ってください。Claude Code を使って小さな差分と短い矛盾リストを生成し、ドキュメントを正しくするための最小変更を適用します。

軽量なルーティン例：

• PR ごと：変更が影響するドキュメント（README、API、ランブック）に対してドリフトチェックを実行。
• 差分サマリを PR 説明やレビュー注に保存し、レビュアーが何をどう比較したか見られるようにする。
• 大きなリライトよりも簡単に戻せる小さな編集を好む。
• リリース前：ユーザーがコピペする可能性のある箇所（curl 例、env 変数、デプロイ手順）を再チェック。
• 週次：古いランブックを一つか二つサンプリングして、現在のコマンドやダッシュボードと一致しているか確認する。

これらの差分サマリを後で見つけやすくしておきます。短い注記（例：「Docs updated to match new /v2 endpoint, removed deprecated header, updated example response」）があると、数ヶ月後に誰かが変更理由を問うときに役立ちます。

ドキュメントにも「スナップショットとロールバック」の考え方を適用してください。不確かな指示は一箇所で変更してすばやく検証し、確認できたバージョンを他へコピーします。

高速に構築する場合、Koder.ai でアプリと初期ドキュメントを一緒に生成し（Koder.ai）、ソースをエクスポートして通常のワークフローでレビューできるようにすると役立ちます。目標は完璧な文章ではなく、人が行う操作（コマンド、エンドポイント、手順）をコードの挙動と一致させることです。