2025年12月26日·1 分
ドキュメントドリフト対策に Claude Code：ドキュメントをコードと整合させ続ける
Claude Code を使って README、API ドキュメント、ランブックをコードと比較し、差分と矛盾を洗い出してドキュメントのズレを防ぐ方法を学びます。
Claude Code を使って README、API ドキュメント、ランブックをコードと比較し、差分と矛盾を洗い出してドキュメントのズレを防ぐ方法を学びます。
ドキュメントドリフトは、ドキュメントの記述とコードの実際の挙動が徐々にずれていく現象です。最初は小さな不一致から始まり、やがて「先月は動いたはずだ」という混乱に発展します。
実際のチームではこう見えます：README ではサービスを1つのコマンドで起動できると書かれているのに、新しい環境変数が必須になっている。API ドキュメントではフィールド名が古いまま。ランブックにはオンコールに「worker-a を再起動せよ」と書かれているが、プロセスは二つのサービスに分かれている。
ドリフトは意図が悪いから起きるのではなく、ソフトウェアの変更速度がドキュメントの更新習慣を上回るために起きます。人はプレッシャーの下で修正を出し、古い例をコピペし、誰かが後で更新するだろうと仮定します。また、README、API リファレンス、社内 Wiki、チケット、口伝といった「真実の源」が多すぎると成長しやすくなります。
コストは具体的です：
文章を磨くだけでは、事実が間違っている限りドリフトは直りません。役立つのはドキュメントを検証可能なものとして扱うことです：現在のコード、設定、実際の出力と比較して矛盾を指摘し、ドキュメントが約束している挙動がコードにないときはそれを明示します。
ドリフトは通常「クイックリファレンス」として扱われるドキュメントに現れます。これらは一度だけ更新されて、その後コードが進み続けます。まずは次の三つから始めましょう。これらは検証可能な具体的な約束を含んでいるからです。
日常のコマンドが変わると README はドリフトします。新しいフラグが追加されたり、古いフラグが削除されたり、環境変数名が変わっているのにセットアップ欄は古い現実を示したままです。新しいチームメンバーが指示をコピペしてエラーに遭遇し、プロジェクトが壊れていると考えます。
最悪なのは「ほとんど合っている」バージョンです。1つの不足した環境変数が、完全に時代遅れの README よりも多くの時間を無駄にすることがあります。人は小さなバリエーションを試し続け、ドキュメント自体を疑わないからです。
リクエストやレスポンスのフィールドが変わると API ドキュメントはドリフトします。小さな変化（キーの名前変更、デフォルトの変更、新しい必須ヘッダ）でもクライアントを壊します。しばしばエンドポイント一覧は正しい一方で、例が古く、それをユーザーがコピペします。
典型的な兆候：
デプロイ、ロールバック、運用手順が変わるとランブックはドリフトします。1つの古いコマンド、間違ったサービス名、欠けた前提条件がルーチンの修正をダウンタイムに変えます。
「正しいが不完全」なこともあります：手順は動くが新しいマイグレーション、キャッシュクリア、機能フラグの切り替えを飛ばしている。そうすると対応者はランブック通りに動いても驚かされます。
ドキュメントドリフトに対する Claude Code は、ドキュメントをコードのように扱うときに最も効果を発揮します：小さくレビュアブルなパッチを提案し、その理由を説明する。単に「README を更新して」と頼むのではなく、特定のファイルに対する差分を生成するように依頼してください。レビュアーは変更前後が明確に見えるので意図しない変更に気づきやすくなります。
良いドリフトチェックは次の二つを生成します：
プロンプトでは、リポジトリからの証拠を必須にしてください：ファイルパスやルート、設定値、テストなど、現在の挙動を示す詳細。
以下のようなプロンプトパターンは現実に根ざしたチェックを保ちます：
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 出力と設定デフォルトと比較して、パッチを生成して」といった形です。
実行前に出力形式を合意しておくと、何が変わったかとその理由が見やすくなります。混合フォーマットは何が変わったかをわかりにくくします。
簡単なルールセット：
実務習慣の例：各ドキュメント PR に「Source of truth checked: routes + tests」のような注を付けて、レビュアーが何と照合したかすぐわかるようにします。これでドキュメント更新は「見た目良し」から「何かに照らして検証済み」になります。
各コード変更を小さなドキュメント調査として扱ってください。目的は矛盾を早期に発見し、レビュアーが信頼できる最小パッチを作ることです。
まずチェックするファイルと明確なドリフト質問を選びます。例：「環境変数、CLI フラグ、HTTP ルート、エラーコードの変更がドキュメントに残っていないか？」と具体的に問うと、モデルが全体を書き換えるのを防げます。
次に Claude Code にコードからハードファクトを抽出させます。リストは具体的に：ユーザーが実行するコマンド、エンドポイントとメソッド、リクエストとレスポンスのフィールド、設定キー、必須環境変数、スクリプトや設定で参照される運用手順。コードに見つからないものは「not found」と答えさせ、推測を避けます。
その後、比較表（ドキュメントの主張、コードの示すもの、状態（match, mismatch, missing, unclear））を出させます。これが議論を地に足のついたものにします。
最後に最小限の unified diff を要求してください。必要な行だけを変え、ドキュメントの既存スタイルを保ち、コードで裏付けられない約束を追加しないよう指示します。
締めとしてレビュアー向けの短いサマリを付けます：何が変わったか、なぜ変わったか、二重チェックすべき点（リネームされた環境変数や新しい必須ヘッダなど）。
API ドキュメントはコードが静かに変わったときにドリフトします：ルートがリネームされる、フィールドが必須になる、エラー形式が変わるなど。結果としてクライアントの統合が壊れ、デバッグに無駄な時間がかかります。
Claude Code を使ったドリフト検査では、リポジトリから API の挙動を証明し、ドキュメントの不一致を指摘することが仕事です。ルーティングとハンドラからインベントリを抽出し（パス、メソッド、リクエスト/レスポンスモデル）、API リファレンスと比較させてください。
人がコピペするものに注目します：curl コマンド、ヘッダ、サンプルペイロード、ステータスコード、フィールド名。単一のプロンプトで以下をチェックさせます：
不一致を見つけたら、コード（正確なルート定義、ハンドラ挙動、スキーマ）に由来する証拠を引用できる差分だけを受け入れてください。そうすることでパッチは小さくレビュー可能になります。
例：コードが POST /widgets で 201 を返し、name フィールドを必須にしたのに、ドキュメントはまだ 200 を示し name を省略している。良い出力は両方の矛盾を指摘し、そのエンドポイントのステータスコードと例の JSON だけを更新します。
ランブックは最も高コストな方法で失敗します：見た目は完全でも手順が今のシステムと合っていないためです。環境変数のリネームやデプロイコマンドの変更が、インシデント中に対応者を誤った方向に導きます。
ランブックをコードとして扱い、リポジトリに対する差分と矛盾指摘を要求してください。比較対象は現在使っているスクリプト、設定デフォルト、ツールです。
インシデント時に最もスラッシュ（無駄なやり直し）を生む失敗点に注目します：
また、対応者が進捗を確認できる簡単な事前チェックと期待される出力（ステータスライン、バージョン文字列、ヘルスチェック応答など）を追加してください。「動くことを検証せよ」だけでは不十分です。
もし Koder.ai などのプラットフォームでアプリをビルド／デプロイしているなら、スナップショットとロールバックはランブックが正しいアクションを命名しているときにのみ有効です。
ドキュメントを「読み物」として扱い、コードと一致させる主張のセットとして扱わないことが最短でドリフトを生む道です。
まず書き換えを求めることです。矛盾チェックを飛ばすと、より滑らかな文章になっても挙動が間違ったままになることがあります。必ず最初に「ドキュメントは何を主張しているか」「コードは何をしているか」「どこが違うか」を問うてください。
モデルに推測させるのも危険です。挙動がコードやテスト、設定に見えないなら、それは不明として扱ってください。「おそらく」は README の約束が生まれる方法であり、ランブックが作り話になるきっかけです。
日常の更新でよく見られる問題：
ハンドラが期限切れトークンに対して 401 ではなく 403 を返すように変わり、ヘッダ名が X-Token から Authorization に変わったとします。認証セクションだけを書き換えると、API ドキュメントの例は古いヘッダのまま、ランブックは 401 の急増を探せと指示しているかもしれません。
差分を生成するときは、次のような決定行を添えてください：
"Auth failures now return 403 to distinguish invalid vs missing credentials."
こう書くことで、次の人がドキュメントを古い挙動に戻すのを防げます。
すべてのドキュメント更新を小さな監査として扱ってください。目的は、来週誰かが手順に従ったときの驚きを減らすことです。
マージ前に README、API ドキュメント、ランブックを見返し、具体的な主張を一つずつ検証します：
同じドキュメントに unknown な主張が 2 個以上見つかったらマージを止めてください。証拠（ファイルパスや関数名）を追加するか、確実な部分だけに文を削るべきです。
小さなチームが認証を更新しました：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 を使って小さな差分と短い矛盾リストを生成し、ドキュメントを正しくするための最小変更を適用します。
軽量なルーティン例：
これらの差分サマリを後で見つけやすくしておきます。短い注記（例：「Docs updated to match new /v2 endpoint, removed deprecated header, updated example response」）があると、数ヶ月後に誰かが変更理由を問うときに役立ちます。
ドキュメントにも「スナップショットとロールバック」の考え方を適用してください。不確かな指示は一箇所で変更してすばやく検証し、確認できたバージョンを他へコピーします。
高速に構築する場合、Koder.ai でアプリと初期ドキュメントを一緒に生成し（Koder.ai）、ソースをエクスポートして通常のワークフローでレビューできるようにすると役立ちます。目標は完璧な文章ではなく、人が行う操作（コマンド、エンドポイント、手順）をコードの挙動と一致させることです。
ドキュメントとコードの内容が徐々にずれていくことを指します。通常は小さな変更（環境変数の名前変更、必須項目の追加、ステータスコードの変更など）から始まり、README、API サンプル、ランブックに反映されません。
コードはプレッシャーの下で素早く変わる一方、ドキュメントは同じレベルで更新されないからです。
よくある原因:
人が実際に実行するドキュメントから始めてください。優先順位の一例:
これらを先に直すと、コストの高い失敗を減らせます。
きれいな文章にしても事実が間違っていれば解決になりません。ドリフトは主に「誤った主張」の問題です。
より良い方法は、ドキュメントをテスト可能な主張として扱うことです：「このコマンドを実行する」「このエンドポイントを呼ぶ」「この変数を設定する」。それらを現在のリポジトリ、設定、実際の出力と照合して検証します。
次の二つを要求してください:
また、リポジトリに証拠が見つからない場合は「not found（見つからない）」と明示するようにします。推測させないことが重要です。
差分はレビュアーが素早く検証できるからです。差分は何が変わったかをはっきり示し、「親切な」書き換えが新しい約束を導入するのを防ぎます。
良いデフォルト:
証拠を必ず示すことをルールにしてください。
実用的なルール:
人がコピーして使う部分をチェックしてください:
エンドポイント一覧が正しくても例が古ければユーザーは失敗します。例は優先度高めに扱ってください。
ランブックは現場の実態が変わると最も高コストで失敗します。
高インパクトなチェック:
進捗が検証できないとインシデント対応で時間を浪費します。
ドキュメント種類ごとに「真実の源」を決めるシンプルなルールを使ってください:
それをワークフローに組み込み、PR ごとに影響を受けるドキュメントでドリフトチェックを実行し、編集は小さくレビューしやすく保ちます。