AIが書いた開発ドキュメントを検証する｜実行できる手順だけを残す

AIが生成したREADMEは、コマンド、設定例、注意書きが整っているだけでは受け入れられません。既に依存関係が入った開発者の端末なら、記載漏れがあっても偶然動きます。実装を知る担当者なら、曖昧な記述を頭の中で補えます。その状態での「読んで問題なかった」は、初回導入の再現性を確かめたことになりません。

受入結果を二つに分けます。一つは、対象OSの初期条件を記録した新規環境で、リポジトリ取得後にREADMEの記載順だけで期待した終了状態へ着けること。もう一つは、設定例に載る各キーについて、実装の読込箇所、既定値、未設定時の挙動を説明できることです。文章への採点を、実行結果とコード上の対応という観察可能な判定へ置き換えます。

2026-09-21時点の[NIST Secure Software Development Framework](https://csrc.nist.gov/Projects/ssdf)は、実務を成果ベースで捉え、現在の成果と比較してギャップを明らかにできると説明しています。同時に、SSDFの実務、タスク、実装例は、変更、個別化、継続的な更新を前提にした出発点と位置づけられています。ここで示す受入条件は公式の分類や義務に含まれません。この一般原則をREADMEレビューへ移した独自の実務提案です。

ローカル端末を片づけても、過去に入れたツールや設定を見落とすおそれがあります。そこで、毎回捨てられる環境を使います。2026-09-21時点の[GitHub-hosted runnerの公式ドキュメント](https://docs.github.com/en/actions/how-tos/manage-runners/github-hosted-runners/use-github-hosted-runners)は、VM上のジョブの開始時に新しい仮想マシンが自動で用意され、終了時に廃棄されると説明しています。ジョブを処理するrunnerの種類は`runs-on`で指定でき、公式例には`ubuntu-latest`、`windows-latest`、`macos-latest`が示されています。

ただし、新規VMをそのまま「空の環境」とは呼べません。[runnerの構成を説明する公式資料](https://docs.github.com/en/actions/concepts/runners/github-hosted-runners)では、単一CPU runnerは共有VM上のコンテナ、それ以外は新規VMです。いずれにもツールやパッケージがプリインストールされています。新規VMを使う検証では単一CPU runnerを除き、実際に使ったimageとIncluded Softwareをworkflowログから記録します。READMEが前提にしてよいツールと、手順で導入する依存関係を分ければ、既存ツールが記載漏れを隠していないか確かめられます。

この製品仕様を受入方法へ利用します。READMEの対象OSを曖昧にせず、検証するrunnerを明記します。その上で、リポジトリを取得し、READMEに現れる順番を変えずに導入コマンドと確認コマンドを実行します。書かれていないパッケージを担当者の判断で足す、先に別のコマンドを打つ、失敗した行を飛ばす、といった補完はしません。補完が必要になった事実はREADMEの不足として記録します。

完了の印も先に決めます。「インストールできた」という感想では判定が割れます。README自身に確認コマンドと期待する終了状態を持たせてください。指定したコマンドがエラーなく終わる、アプリケーションが記載された方法で起動する、必要な検証コマンドが完了する、といった対象リポジトリで観察できる状態です。どれを採るかは実装に合わせて選び、確認できない成功条件は置きません。

検証担当者は、作業中に詰まった場所をそのまま記録します。記録欄は「READMEの記述」「実行した操作」「観察した結果」「判定」「文書へ戻す修正」で足ります。判定は、記載どおり完了したなら合格、手順の追記や順序変更が必要なら修正、外部条件がなく確認できないなら保留とします。点数は付けません。何が再現でき、何が未確認かを残す非数値の台帳です。

たとえばREADMEが外部サービスへの接続を求めたところで止まった場合、検証者が私物の認証情報で先へ進めば、手順の欠落が隠れます。接続先の準備方法、秘密情報を渡す経路、検証用と本番用の境界が文書にあるかを確認し、なければ保留にします。秘密の値はREADMEやPull Requestへ転記せず、準備方法と責任者が分かる表現へ直します。外部サービスの自動準備を一律に求めているわけではありません。初期条件を記録した新規環境からどこまで自動で進み、どこから組織の準備事項になるかを分ける判断です。

実行中に必要だと分かった前提はREADMEへ戻し、検証端末だけに残さないようにします。現在の実装では不要だった古い操作は削除候補です。最終的に必要なのは、次の新しい環境でも同じ順番で試せる手順と、保留条件が明示された箇所です。検証者が工夫して成功した経緯を手順の代わりにはできません。AIへ修正文を作らせても、再実行による合否判定は人とCIの側に残します。

READMEの導入が通っても、設定例が実装と一致するとは限りません。設定ファイルにもっともらしいキーが並んでいると、レビューは名称の自然さだけで終わりがちです。設定例をキーごとに分け、それぞれを実装へ結びつけます。

台帳の列は「設定キー」「READMEでの説明」「実装の読込箇所」「既定値」「未設定時の状態」「検証方法」「結果」とします。キーを一つ選んだら、READMEの表記でコードを検索し、別名への変換があれば変換先を追い、値を使う分岐まで確認します。その後、例示値を新規環境へ設定し、READMEの確認コマンドで観察した結果を同じ行へ記録します。説明と実装と実行結果が一致すれば合格、キーが読まれていない、名称が異なる、既定値の説明が実装と違う場合は修正、外部サービスがなく挙動を確認できない場合は保留です。読込箇所を見つけられないキーを「将来使うかもしれない」で残さず、残す理由を別途判断します。

この台帳は、出典の一般原則を基にした実務上の提案であり、NISTやGitHubが定めた分類・義務ではありません。文書の主張と実装上の根拠を同じレビュー面に置くために使います。既定値が存在しないなら「なし」、未確認なら「未確認」と書き、推測した値で空欄を埋めません。

設定例の確認では、値の妥当性とキーの存在を混同しないことも重要です。コードがキーを読むだけでは、例示値で目的の動作になるとは確定しません。まず読込箇所と未設定時の分岐を静的に確認し、次に初期条件を記録した新規環境で例示どおり設定して確認コマンドを実行します。静的な一致と実行結果の両方が揃わない項目は、その状態が分かる判定を残します。

2026-09-21時点の[GitHub Pull Request公式ドキュメント](https://docs.github.com/en/pull-requests/reference/pull-requests)では、`Files changed`タブにレビュー対象の差分が、`Checks`タブに自動テスト、ビルド、そのほかの検証が表示されると説明されています。ここまではGitHubの製品仕様です。文書と実装の対応台帳をPull Requestへ置き、差分と実行結果を分けて確認するのは、その仕様を利用した記事独自の運用提案です。

`Files changed`では、READMEの修正に加え、設定例のキーが実装の読込処理と同じ変更内で食い違っていないかを見ます。Pull Requestの説明には台帳を置き、各キーの判定から該当差分へたどれるようにします。`Checks`では、対象OSを指定した新しいrunner上で導入手順と確認コマンドが実行されたか、その結果が成功か失敗かを見ます。画面が分かれているからこそ、「説明は直ったが実行は失敗」「チェックは通ったが設定キーの根拠がない」という別種の問題を一つの承認へ丸めません。

AI生成の文書にも、ほかの変更と同じレビュー経路を使えます。ただし、自然な説明を承認の根拠にはしません。Pull Requestには検証対象のOS、外部サービスの要否、秘密情報の準備方法、実行した確認コマンド、期待する終了状態、設定台帳の保留項目を残します。レビュー、テスト、CIを開発フロー全体へどう置くかは、AI駆動開発の開発フロー｜レビュー・テスト・CIで人の判断を残すも参照できます。

すべてのREADMEを同じ条件では判定できません。対象OSが違えばrunnerも変わり、外部サービスが必須なら新規VMだけでは完了しません。2026-09-21時点のNIST SSDFも、個別化と継続的な更新を前提とする出発点に位置づけ、固定チェックリストとして従うものではないとしています。実現可能性と適用可能性を見ながら条件を選ぶ必要があります。

チームが明記するのは、対象OS、必要な外部サービス、秘密情報の準備方法、確認コマンド、期待する終了状態です。全チーム共通の公式基準ではありません。出典の一般原則とrunner選択の仕様を基にした実務上の提案です。複数OSを公式に支えるなら対象ごとに確認し、特定OSだけを対象にするならREADMEに範囲を明記します。外部サービスをCIで用意できないなら、何を自動確認し、何を担当者が確認するかを分けます。

秘密情報を扱う検証では、再現性を理由にアクセス範囲を広げないことも条件に含めます。どの値を誰がどの経路で用意するかを決め、文書へ値そのものを残さない。AIツールを使う開発環境の権限やデータ境界まで整理するときは、Claude Codeのセキュリティ｜法人導入前に決める権限とデータ管理が補助線になります。

合否は、完了した範囲と人の判断が必要な範囲を説明できるかで決めます。全工程の自動化を前提にはしません。保留が残るなら、担当者と確認方法を決めるまでマージしないのか、対象外としてREADMEへ明記するのかを選びます。曖昧なまま合格へ寄せないことが、チーム固有の条件を置く意味です。

受入時に残す証拠は簡潔です。初期条件を記録した新規環境を指定するrunner、READMEどおりに実行したコマンド、観察した終了状態、設定キーごとの実装上の対応、そして保留理由です。これらがPull Requestの差分とChecksの結果から追えれば、後のレビュー担当者は再実行可能な根拠で判断できます。文章の説得力だけに頼る必要はありません。

READMEの手順は、対象OSを明記した新しいVMで記載順に完了したものだけを受け入れる。設定例は、読込箇所、既定値、未設定時の状態、検証結果を台帳で説明できるものだけを残す。外部サービスや秘密情報のために完了できない箇所は、準備方法と人が確認する境界を明記する。この条件により、「何をもって完了とするか」を各チームが観察可能な終了状態として具体化できます。

AIが下書きを速く作れても、生成したという事実からドキュメントの正しさは決まりません。実装と初期条件を記録した新規環境へ問い直し、通らなかった操作を修正へ戻します。その反復を受入条件にすれば、READMEに残るのは次の担当者が実行できる手順です。