AIコーディングエージェント実践完全ガイド — 指示・分割・レビューの型

この講義では、AIコーディングエージェントへの指示の出し方、大きな作業の分割方法、コードベースの調査、テストとレビューによる検証、そしてセキュリティとデバッグの実践までを、全5章で扱います。全12週のカリキュラムの各週で扱う内容を横断的に整理する位置づけです。

「AIに任せる」ことと「AIの出力を鵜呑みにしない」ことは両立します。その具体的なやり方を、この講義を通して身につけていきましょう。

まずは、AIコーディングエージェントへの一回一回の指示（プロンプト）をどう組み立てるかから始めます。

プロンプトの基本構造

AIエージェントへの指示は、曖昧な一文よりも要素を分けて伝えたほうが精度が上がりやすくなります。基本的な構成要素は次の通りです。

• 目的（何を作りたいか、何を解決したいか）
• 前提条件（使用する言語、既存ファイルの状況など）
• 期待する出力の形式や範囲

最初から完璧な指示を書こうとせず、短い指示から始めて応答を見ながら追加情報を伝えていくやり方でも構いません。

目的だけを伝えて前提条件を省略すると、AIは既存のコードの流儀を無視した実装を提案することがあります。プロジェクト固有のルールがある場合は、最初の依頼に必ず含めるようにしましょう。

AIが何を読み書きしたかを確認する

AIコーディングエージェントは、ファイルの読み込み・書き込み・検索といったツールを介してコードベースを操作します。どのファイルを読んだか、どのファイルを変更したかをログで確認する習慣をつけましょう。意図しないファイルへの変更が提案されていないかを確認することも欠かせません。

差分レビューという人間の役割

AIが生成・変更したコードは、そのまま適用する前に差分（変更前後の比較）を確認します。差分レビューは人間側の重要な役割であり、AIの提案を鵜呑みにしないための基本動作です。

• 変更差分を一行ずつ確認し、意図と一致しているかを見る
• 一つのコミットには一つの意味のある変更をまとめる
• コミットメッセージには「何を」「なぜ」変更したかを簡潔に書く

差分を読む習慣がついてくると、AIが提案するコードの「癖」や「傾向」も見えてきます。同じ間違いを繰り返す提案には、依頼文の側に共通する曖昧さが潜んでいることが多いです。

小さく依頼して確認するサイクル

目的を明確に伝えて初回のコードを生成させ、動作確認をして期待通りでない場合は追加の指示で修正させる——このサイクルを繰り返すことが基本になります。動かないコードが出てくることも珍しくありません。エラーメッセージを共有しながら対話的に直していくプロセスも、学びの一部です。

第1章のまとめ

目的・前提条件・期待する出力を分けて伝え、AIの読み書きと差分を確認しながら小さく進める——これが指示出しの基本形です。次章では、より規模の大きい作業をどう分割するかを扱います。

複数ファイルにまたがる変更や、大きなタスクをどう分解してAIに依頼するかを扱います。

マルチファイル編集の指示の出し方

複数のファイルにまたがる変更を依頼する際は、影響範囲を先に伝えることで精度が上がりやすくなります。

• 変更したい機能と、関係しそうなファイルやディレクトリを事前に共有する
• 命名変更や仕様変更など、影響が広がりやすい作業ほど具体的な範囲を指定する
• 一度に大量のファイルを変更させず、段階的に進める

影響範囲の共有が不十分だと、関係のないファイルまで巻き込んだ変更が返ってくることがあります。事前に「触ってよい範囲」と「触ってほしくない範囲」の両方を伝えておくと、意図しない変更を防ぎやすくなります。

コンテキスト管理という考え方

AIエージェントが一度に把握できる情報量には限りがあります。大きすぎるタスクは、意味のある単位に分割して依頼するほうが結果が安定しやすくなります。一つの依頼が大きくなりすぎたら、区切りの良い時点で会話や作業をリセットすることも有効です。

会話をリセットする際は、それまでの決定事項や残タスクを短いメモとして残しておくと、次の会話でAIに再度説明する手間を減らせます。

分割タスク化の具体的な手順

大きな作業を「調査」「設計方針の確認」「実装」「確認」のような段階に分けます。途中経過を差分やメモとして残し、次の作業に引き継げるようにしておくと、会話をリセットしても作業を継続しやすくなります。

タスクを分割すると何が変わるか

タスクを分割することの最大の利点は、問題が起きたときにどの単位が原因かを特定しやすくなることです。一度に大きな変更を依頼すると、意図しない変更が紛れ込んでも気づきにくくなります。小さな単位で依頼と確認を繰り返すことが、結果的に最短ルートになります。

第2章のまとめ

影響範囲を事前に共有し、大きな作業は段階に分けて依頼する。これがコンテキスト管理と分割タスク化の基本です。次章では、既存のコードベースを読み解き、失敗パターンを見分ける方法を扱います。

初めて触るコードベースの調査方法と、AIコーディングエージェントの提案に潜む失敗パターンの見分け方を扱います。

既存コードベースの調査をAIに任せる

初めて触るコードベースでは、AIに構造の調査や要約を依頼するとキャッチアップが早まります。ディレクトリ構成や主要な処理の流れを説明させたり、特定の機能がどのファイルに実装されているかを検索・要約させたりできます。

要約結果は鵜呑みにせず、実際のコードと照らし合わせて確認することが重要です。

調査を依頼する際は、知りたいことを一つに絞ると精度が上がります。「全体を説明して」より、「この機能はどこで処理されているか」のように具体的に聞くほうが、実コードとの答え合わせもしやすくなります。

失敗パターンその1：曖昧な指示による過剰な変更

AIコーディングエージェントの提案は常に正しいとは限りません。特に注意したい失敗パターンの一つが、指示が曖昧で、意図と異なる箇所まで変更してしまうケースです。命名変更などの影響が広い作業ほど、この失敗が起きやすくなります。

「ついでにここも直しておいて」のような追加依頼は便利な一方、影響範囲の見積もりが甘くなりやすい依頼でもあります。ついで作業は、可能であれば別の依頼として切り分けましょう。

失敗パターンその2：破壊的な変更

もう一つの注意すべき失敗パターンは、既存の設定ファイルやデータを削除・上書きする破壊的な変更が含まれるケースです。テストや動作確認をせずに変更を適用してしまうケースも同様にリスクが高くなります。

差分レビューと動作確認を欠かさないこと、不安がある変更は小さく分けて適用することが、失敗を早期に見つける基本の対策になります。

調査結果を実コードで裏取りする習慣

AIによる要約や説明は便利ですが、あくまで一次情報ではなく整理された二次情報として扱うべきです。重要な判断をする前には、要約された内容を実際のコードと突き合わせて確認する一手間を惜しまないようにしましょう。

第3章のまとめ

コードベースの調査はAIに任せつつ、実コードでの裏取りを欠かさない。過剰な変更や破壊的な変更という失敗パターンを知っておくことが、安全にAIを使いこなす鍵になります。次章では、テストとレビューによる検証の型を扱います。

テストファーストの進め方と、カバレッジ・AIレビューコメントの読み方を扱います。

AIによるテスト生成とテストファースト

AIコーディングエージェントにテストコードの生成を依頼する際は、対象の関数やコンポーネントの仕様（入力・出力・エラー時の振る舞い）を明確に伝えることが前提になります。仕様書に書いた受け入れ基準は、そのままテストケースの元ネタとして使えます。

仕様が曖昧なままテスト生成を依頼すると、AIは実装のコードから逆算してテストを書いてしまい、本来検出すべきバグを見逃すテストになることがあります。先に期待する振る舞いを言葉で伝えることが欠かせません。

RED→GREEN→REFACTORの手順

テストファーストは、実装より先にテストを書く進め方です。

• RED：失敗するテストを書き、実際に失敗を確認する
• GREEN：テストが通る最小限の実装をする
• REFACTOR：テストを通したまま整理する

この順序を守ると、テストが「後付けの言い訳」にならず、仕様を満たしているかどうかの判定基準として機能します。

GREENの段階では、きれいなコードよりもテストを通すことを優先して構いません。整理はREFACTORの段階でまとめて行うと、手を動かす順序に迷いがなくなります。

カバレッジの読み方

カバレッジは、コードのどの行・分岐がテストによって実行されたかを示す指標です。数値が高いほど良いとは限りませんが、極端に低い箇所は見落としの可能性が高いと考えられます。カバレッジを埋めること自体を目的化せず、受け入れ基準に沿った意味のあるテストを優先しましょう。

AIレビューコメントの取捨選択

AIコーディングエージェントにコードレビューを依頼すると、命名・重複・エラー処理・潜在的な不具合などについてコメントが返ってきます。すべてを機械的に反映するのではなく、指摘の根拠を確認し、仕様や設計意図に照らして妥当かを判断します。特にセキュリティや入力値検証に関する指摘は優先度が高くなります。

第4章のまとめ

テストファーストで実装し、カバレッジは意味のある形で読み、AIのレビューコメントは根拠を確認してから取捨選択する。これが検証の型です。最終章では、セキュリティレビューとデバッグの実践を扱います。

入力検証・秘密情報管理のレビュー、E2Eテストの設計、そしてバグの原因切り分けまでを扱います。

セキュリティ観点のAIレビュー活用

入力検証と秘密情報管理の2点をAIエージェントにレビューさせる方法があります。フォーム入力やAPIパラメータなど外部から渡る値をコードがどう扱っているか、AIに一覧化させたうえで、検証漏れがないかを確認します。

APIキーやパスワードなどの秘密情報がソースコードやログに直接書かれていないかも重点的にチェックします。AIの指摘はあくまで一次情報であり、最終判断は人間が行う点を忘れないようにしましょう。

レビューの対象範囲を絞り込み、何を確認してほしいかを具体的に伝えると、指摘の精度が上がります。曖昧な依頼では見落としが増えるため、フォームの入力欄やAPIの受け口など、対象を明示して依頼しましょう。

E2Eテストの基本設計

E2E（エンドツーエンド）テストは、ユーザーが実際に操作する一連の流れを再現して確認するテストです。代表的な1つのシナリオを選び、「操作」と「期待される結果」の対で手順を明確に記述するところから始めます。

• 正常系だけでなく、入力を誤った場合の異常系も1つ含める
• 画面遷移の各段階で、何が表示されていれば成功と言えるかを言語化する

シナリオが長くなりすぎると、どこで失敗したのかが分かりづらくなります。最初は3〜5ステップ程度の短いシナリオから始め、慣れてきたら別のシナリオを追加していく進め方がおすすめです。

バグ発生時の原因切り分け

バグが発生した際は、再現手順・エラーメッセージ・関連コードをAIエージェントに渡し、原因の候補を複数挙げてもらいます。ここで重要なのは、AIの最初の回答をそのまま信じずに、実際にログや動作を確認しながら候補を絞り込む姿勢です。

候補が複数出た場合は、可能性の高いものから1つずつ検証し、当てはまらなければ次の候補に移ります。

指摘への対応と再検証のサイクル

AIや講師からのレビュー指摘は、重大度（致命的・重要・軽微）で分類してから対応します。修正後は必ず再度テストを実行し、直したはずの問題が解消しているか、別の問題を生んでいないかを確認します。「指摘→修正→再検証」のサイクルを回すことが、品質を保つ上での基本動作になります。

第5章のまとめ

セキュリティレビュー、E2Eテスト、バグの原因切り分け、そして指摘への再検証サイクル。これらすべてに共通するのは、AIの一次回答をそのまま信じず、人間が確認するステップを挟むという姿勢です。

この講義では、指示の基本形、大きな作業の分割、既存コードの調査と失敗パターンの見分け方、テストとレビューによる検証、そしてセキュリティとデバッグの実践までを、5つの章に分けて扱いました。共通するのは、AIに任せる範囲と人間が確認する範囲を、意識的に切り分けるという姿勢です。

指示・分割・レビューの型は、一度身につければ、扱うツールが変わっても応用が利く考え方です。

この講義で扱った内容は、コーディング向けプロンプト実践、AIと読む他人のコード、AIとテスト駆動開発、エラーをAIに直させる手順、リファクタリングの頼み方、AIへのレビュー依頼文例集など、記事メディアの各記事でもより詳しく解説しています。あわせてご覧ください。

実際に手を動かしながら学ぶ演習は、全12週のシラバスで扱います（無料で読めます。成果や収益をお約束するものではありません）。

講義で扱ったテーマを、公式ドキュメントや公的機関の資料で確かめたいときの入口です。

• Google Engineering Practices：コードレビュー：レビューで何を見るかを整理したGoogleの公開ガイド
• OWASP Top 10 for LLM Applications：LLMを組み込んだアプリで起きやすいセキュリティリスクの一覧

この特別講義は無料で視聴できる総集編です。関連する内容を実際に手を動かしながら学びたい方は、全12週のシラバスで学習の全体像を確認できます（無料で読めます。成果や収益をお約束するものではありません）。先行案内はこちら。