GitHub Copilot・Claude Code・Codexでよくある失敗「コードが壊れた・確認が追いつかない・意図がズレる」を防ぐ3本柱 ～Gitで守る・差分で見る・mdで考える～
AI活用編です。プログラミングでAIエージェント（例：GitHub Copilot・Claude Code・Codex）を使い始めたものの、
- 「壊れた、でも戻せない」
- 「変更が多すぎて確認が追いつかない」
- 「何度指示してもAIが意図と違うことをする」
という経験はありませんか？
本記事では、特定のAIエージェントに依存しない、どのツールでも使える3つの習慣（3本柱）を解説します。
以下のような方に役立つ内容となっています。
- AIエージェントを導入したい、または使い始めたけれどうまく活用できていない方
- AIに修正を任せたら意図しない変更が入り、元に戻せなくなった経験がある方
- AIの変更ファイルが多すぎてレビューが追いつかない、どこを確認すればいいかわからない方
- GitHub Copilot・Claude Code・Codexなど複数のAIエージェントを試している、または使い方を整理したい方
AIエージェントを最初に導入するときに私自身課題に思った点や、導入を試している方から聞いた悩みに基づいてまとめた記事です。
今回紹介する3本柱はどのAIエージェントでも同様に使えます。一緒に習得していきましょう！
AIエージェントの使い方の基本については以下の記事もぜひ参考にしてください。
AIエージェントを使い始めたときにつまずく3つの問題
プログラミングで、AIエージェントを最初に導入したときの失敗パターンはほぼ共通しています。
多くの場合、「壊れた、でも戻せない」「確認が追いつかない」「意図が伝わらない」という3つの問題に集約されます。
- 壊れた、でも戻せない：AIが複数ファイルを一括変更し、動かなくなった。いつ・何が変わったかわからず、元の状態に戻す方法がわからない
- 確認が追いつかない：変更されたファイルが多すぎて、どこをどう確認すればいいかわからない
- 意図が伝わらない：何度指示しても、AIが自分の意図と違う範囲・方向で実装してくる
これらの問題は、AIへの指示の仕方・使い方の構造的な問題です。
GitHub CopilotでもClaude CodeでもCodexでも、同じ使い方をすれば同じ失敗が起きます。逆に言えば、使い方を変えるだけでどのツールでも改善できます。
ツールの問題じゃなくて、使い方の問題なんだ！
そうです。壊れても戻せる・確認する範囲に絞り込む・実装前に意識合わせをするという仕組みを作ることが大切なんです。
AIエージェント活用の「3本柱」：全体像
3つの問題に対応する形で、AIエージェント活用の3本柱を整理します。これらはそれぞれ独自の役割を持ちつつ、組み合わせると相乗効果がでます。
- Gitで守る：小さいコミット・ブランチ管理で「いつでも戻せる」状態を作る
- 差分で見る：AIの出力は全文ではなく「差分（diff）」だけを確認する
- mdで考える：コードより先にMarkdownで要件・設計・方針を整理する
以降の各セクションで、それぞれの柱を具体的なAIエージェントの使用例とともに解説します。
GitHub Copilot（Visual Studio）・Claude Code（VSCode）・Codex（VSCode）の3つを使いますが、重要なのは「どのツールにも共通するやり方がある」という点です。
第1の柱：Gitで守る
「壊れた、でも戻せない」の正体は、AIが複数ファイルを一括で書き換え、変更前の状態を手動で復元できなくなることにあります。
課題：複数ファイルが一括変更されると「戻せない」状態になる
AIにコーディングを任せると、意図しない変更が入り込むリスクがあります。
人間が1ファイルずつ慎重に変更するときと違い、AIエージェントは複数ファイルを一括で書き換えることがあります。
また、何度修正してもビルドエラーが解消できずAIが途中であきらめる（もしくは人が中断させる）ことで、コード全体が中途半端な状態になってしまうこともあるでしょう。
一部のAIエージェントにはチェックポイントや復元機能が組み込まれているものもあります。
ただし、ツールによって使い勝手や成熟度にばらつきがあり、まだ発展途上です。
Gitで解決：「いつでも戻せる状態」を作る
Gitを使えば、ゲームでうまくいかなかったらリセットするような感覚で、AIの変更を丸ごとなかったことにしてやり直せます。
使い始めのうちコードを壊すことへの恐れは大きくなりがちですが、気軽にリセットして指示しなおせると思えると、ぐっと使いやすくなります。
覚えておくのは2点だけです。
- 作業を始める前にコミットしておく
- おかしくなったら
git reset --hard && git clean -fdで作業前の状態に戻す
git reset --hard はコミット済みの状態まで変更ファイルをすべて元に戻し、git clean -fd はAIが新規作成したファイルやフォルダを削除します。
2つ合わせるとAIの作業を完全にリセットできます。ただしコミットしていない変更はAIの作業もろとも消えるため、必ず作業前にコミットしておきましょう。
Gitってそもそもどう使うの？という方は、以下の記事も参考にしてください。
Gitって、AIエージェントを使わなくても開発で必要なやつだよね？
そうですね。ただAIエージェントを使うと、壊す頻度も規模も一気に増えるので、Gitの重要度がさらに上がります。
今までGitなしで済ませていた方も、これを機に学ぶ価値が大きいですよ。
具体例：MentorAppでリセットを試す
GitHub Copilot（Visual Studio）のエージェントモードで、Webアプリ（MentorApp）に機能追加する場面を考えます。
MentorAppは、C#/Blazor実務Webアプリ開発編で題材としているメンタリングアプリです。
たとえば「TopicにPriority（優先度）フィールドを追加して。」という指示を出すとします。このとき、作業前に必ずコミットを入れておくのが鉄則です。
- 作業開始前に
git add . && git commit -m "Before AI changes" - GitHub Copilotのエージェントモードで「TopicにPriority（優先度）フィールドを追加して。」と指示
- AIが複数ファイルを変更 → 差分を確認（→ 第2の柱「差分で見る」につながる）
- 問題なければコミット。途中で理解できなくなってきた・結果に違和感があれば
git reset --hard && git clean -fdで完全リセット
AIに指示をして作業を開始させます。
AIに作業を続けさせたら、以下のように自分が想定したよりもかなり多くのコードが修正され、よくわからなくなってしまったしましょう。
これはAIの動作が誤っているわけではなく、「フィールドを1つ追加するだけ」という人の感覚と、関連箇所まで踏み込むAIの動作とのギャップです。
指示の出し方で減らせますが（第2・第3の柱の例で扱います）、まずは「想定とズレることがある」という前提に立ちましょう。
もし途中でAIの作業を打ち切りたければ、停止ボタン（■）を押してAIの作業をとめます。
AIが作業をしてあちこちのファイルが修正され、コードがよくわからない状態になってしまいました。ここで「リセット」の出番です。
以下のようにGitのコマンドを使ってAIが作業を行う前の状態に戻します。
D:\data\projects\MentorApp> git reset --hard && git clean -fd
HEAD is now at fa405ca Save before AI agent work
Removing .github/
Removing src/MentorApp.Domain/Models/Topics/TopicPriority.cs
D:\data\projects\MentorApp>Removing として表示されるのは、AIが新規作成したファイルだけです。既存ファイルへの変更（Topic.cs などの修正）は git reset --hard が静かに元に戻しています。
出力が少なく見えても、変更されたファイルはすべて元に戻っています。これで、コード全体がAI作業前の状態に戻っています。
このようなGitを使ったリセット方法を覚えておけば、どのようなAIエージェントを使う場合でも応用できます。
私はAIエージェントを使う開発になってから、「git reset --hard && git clean -fd 」をかなり多用するようになりました。
よくわからなくなってきたり、アプリが壊れてしまったら、リセットをして心を落ち着かせてから「仕切り直し」で再度チャレンジしてみましょう！
第2の柱：差分で見る
「確認が追いつかない」という問題の正体は、AIが変更するファイル数が人間の想定をはるかに超えることにあります。
課題：変更の「どこを・どう」変えたかを把握するのが難しい
AIエージェントが複数ファイルを書き換えたとき、それぞれのファイルのどこが変わったのかを目視で探すのは大変です。
10ファイル以上を変更することも珍しくなく、変更箇所を1つずつ追いかけているうちに、何が変わって何が変わっていないのかわからなくなります。
また、変更後のコードだけ読んでも「元はどう書かれていたか」がわからないと、その変更が意図通りかを判断できません。
差分で解決：見るべきは「変更箇所だけ」
AIの出力レビューで重要なのは「どこをどう変えたか」だけです。
変更前の全体コードをもう一度読む必要はありません。差分（diff）に絞ることで、確認の効率が大幅に上がります。
差分についてはGitを利用するのがよいでしょう。Visual Studio/VS Codeに統合された差分ビューアで効率よく確認可能です。
具体例：MentorAppで差分ビューを使う
第1の柱と同じ「TopicにPriority（優先度）を追加する」例を使います。VSCode上のClaude Codeを使ってみましょう。
今回、「Domain層のデータ定義だけ変えて」とスコープを絞った指示をします。
- Claude Codeに「TopicにPriority（優先度）プロパティを追加して。Domain層のデータ定義だけ変えればよい。ServiceやUIは変更不要。」と指示
- AIが変更 → VSCodeのソース管理パネル（Ctrl+Shift+G）で変更ファイル一覧を確認
- 各ファイルをクリックして差分ビューで確認（＋が追加、－が削除）
AIへ機能追加の指示を行います。
MentorAppは多くのファイルで構成されていますが、変更ファイルは以下の2つだけです。
差分ビューで「TopicPriority.csのenum値は意図通りか」「Topic.csへのプロパティ追加は正しいか」を確認するだけで済みます。
変更箇所が少なければ、確認も少なく終わります。
全部読もうとすると途中で諦めちゃうから、差分だけって言ってもらえると助かる！
「AIがどこをどう変えたのかわからない」という課題が一気に解消されますね。AIが多くのファイルを変更しても、見るのは常に「差分だけ」です。
またこの差分が小さくなるように、「指示する作業をなるべく小さく分割し、スコープを絞る」ことも重要ですね。
第3の柱：mdで考える
「意図が伝わらない」という問題の正体は、実装に着手する前の要件・設計の認識合わせを欠いたままAIが書き始めることにあります。
課題：認識合わせなしにAIがコードを書き始める
AIにいきなりコードを書くように指示を出すと、要件の解釈がずれた状態で大量のコードが生成されてしまいます。後から気づいても、手戻りが大きくなりがちです。
第1の柱の例では、「TopicにPriority（優先度）フィールドを追加して。」と指示した結果、AIはServiceやUIまで広範囲に変更しました。
あれは「AIが自分なりに解釈して実装を進めた」結果ってことだね…。
mdで解決：コードより先に実装計画を文書化する
コードを書かせる前に、まずAIに実装計画をMarkdownファイルとしてまとめてもらいます。
計画を読むことで、AIが何をしようとしているか・どこまで変更が及ぶかを、コードに手を付ける前に把握できます。
覚えておくのは「まずmdに計画を書かせてから、コードに進む」という順序だけです。
具体例：MentorAppでmdに計画を書かせる
今度はVSCode上のCodexを使ってみましょう。第1の柱における例と同じ指示（TopicへのPriority追加）について、mdファイルにまとめさせてから実装を行います。
- Codexに「TopicにPriority（優先度）フィールドを追加したい。まず実装計画を
docs/tasks/add-priority.mdにまとめて。コードはまだ変更しない。」と指示 - AIが実装計画mdを作成 →
docs/tasks/add-priority.mdを開いて内容を確認 - 変更予定ファイル・懸念点・確認事項を読み、疑問点をチャットで聞く
- mdがブラッシュアップできたら、改めて実装を依頼する
いきなり実装をはじめずmdへ計画をまとめるよう指示をすると、AIがmdファイルを作成してくれます。
内容は以下のようにまとめてくれます。
以下のように変更予定ファイルや確認事項も書いてくれていますね。多くのファイルを修正予定であることがあらかじめわかりました。
ここで、もし自分の想定と違うこと・不明な点があれば聞いて確認したり、計画を修正してもらったりしましょう。
計画をmdにまとめてもらうだけで、第1の柱で起きたような「気づいたら広範囲に変更されていた」を未然に防げます。
特に要件が詰め切れていない・実装イメージがつかめないという機能追加・修正については「まずmd、次にコード」という順序がおすすめです。
こういう実装前の設計議論って、mdにまとめなくても、チャットで行えばよいのでは？
チャット議論も有効です。短いやり取りで決まる話ならチャットで十分ですね。
一方、議論が長引きそうなときや、検討を一時中断してあとで再開したいときは、ストック情報として残るmdが便利ですよ。
まとめ
今回紹介した3本柱は、GitHub Copilot・Claude Code・Codexといった個別のツールに依存したものではなく、どれにも同じ原則が適用できます。
- Gitで守る：AIを信用するのではなく、壊れても戻せる構造で使う
- 差分で見る：レビュー対象を”全文”ではなく”差分”に圧縮する
- mdで考える：コードを書く前にmdで実装計画を整理し、意図のズレを防ぐ
この3本柱が取り組んでいる課題は、実はAIエージェントに限ったものではありません。
「Gitで変更を管理する」「差分でレビューする」「設計を先に整える」は、通常の開発でも重要な習慣です。
では、なぜAIエージェントを使うとこれらが特に大切になるのでしょうか。それは、AIエージェントが持つ本質的な難しさにあります。
人間が開発するときは、変更は少しずつ自分（やチーム）のペースで進みます。
しかしAIエージェントは、簡潔な一言の指示で大量のコードを一気に書き換えます。この「少ない入力→大きな変更」というギャップが、認知負荷を急激に高めます。
3本柱は、ある意味この認知負荷をコントロールするための基本的な方法です。
- 「Gitで守る」は”いざとなれば戻せる”という安心感で精神的な負荷を下げる
- 「差分で見る」は確認すべき情報量を圧縮する
- 「mdで考える」は変更が起きる前に頭の中を整理して認識のズレを防ぐ
AIエージェントは今後も多様なツールが登場し続けます。しかし「壊れても戻せる・差分で確認できる・設計を先に整える」という原則は変わりません。
AIエージェントを使ってみようと思ったけど、なかなか馴染めないという方は、ぜひ自分のワークフローの中核にこの3本柱を置いてみてください。
引き続き、AIエージェントを安全・効率的に活用する方法を一緒に学んでいきましょう！
