AIと一緒にデバッグする ── エラーを怖がらなくなる方法

そもそもデバッグとは何か

「デバッグ（debug）」とは、プログラムに含まれるバグ（不具合・エラー）を見つけて修正する作業のこと。名前の由来は1940年代、実際にコンピュータの中に虫（bug）が入り込んで誤作動を起こしたエピソードに遡ります。

プログラミングにおいて、バグはゼロにはなりません。プロのエンジニアでも1日に何十回とエラーに遭遇します。初心者のうちはエラーが表示されると「壊してしまった」と焦りがちですが、実はエラーメッセージはコンピュータからの親切なヒント。「ここがおかしいよ」と教えてくれているのです。

バイブコーディングの世界では、このデバッグ作業をAIに任せることができます。AIはエラーパターンを膨大に学習しているため、エラーメッセージを見せるだけで原因を特定し、修正コードを提案してくれます。

---

デバッグはAIの最も得意な仕事

実はバイブコーディングでAIが最も力を発揮するのは「新しいコードを書く」ことではなく「バグを直す」ことです。

理由はシンプルです。

観点	新規コード作成	デバッグ（バグ修正）
情報の明確さ	ゴールが曖昧なことが多い	エラーメッセージが原因を示す
AIの学習量	多い	非常に多い（StackOverflow等）
回答の精度	解釈次第でブレる	修正箇所が明確で高精度
フィードバック	合ってるか判断しにくい	直ったかすぐ分かる

つまり、デバッグはAIにとって「問題が明確で、答えが検証しやすい」理想的なタスクなのです。

---

AIデバッグの流れ

エラーに遭遇してから解決するまでの典型的な流れを見てみましょう。

---

エラーメッセージの読み方 ── 5つの主要エラータイプ

エラーメッセージは大きく5つのカテゴリに分類できます。すべてを暗記する必要はありませんが、種類を知っておくとAIへの報告がスムーズになります。

1. SyntaxError（構文エラー）

コードの書き方が文法的に間違っているときに発生します。人間の文章でいう「てにをはの間違い」のようなものです。

SyntaxError: Unexpected token '}'
    at file:///src/pages/index.astro:15:1

要素	意味
エラー名	SyntaxError（構文ミス）
メッセージ	Unexpected token ’}’ → 予期しない } がある
ファイル	src/pages/index.astro の15行目

よくある原因: 括弧 (), {}, [] の閉じ忘れ・余分な閉じ括弧、セミコロンの漏れ、引用符の閉じ忘れ

AIへの伝え方: エラーメッセージ + 該当ファイルの内容をそのまま貼る

2. TypeError（型エラー）

変数や値の「型」が期待と違うときに発生します。最も頻繁に出会うエラーの1つです。

TypeError: Cannot read properties of undefined (reading 'map')
    at renderCards (src/components/CardGrid.astro:12:15)
    at renderPage (src/pages/index.astro:25:3)

要素	意味
エラー名	TypeError（型の不一致）
メッセージ	undefined に対して .map しようとした
スタックトレース	CardGrid.astro の12行目で発生

よくある原因: データがまだ読み込まれていない（undefined）、APIの戻り値が想定と異なる、変数名のタイプミス

AIへの伝え方: エラーメッセージ + データの取得部分のコード

3. ReferenceError（参照エラー）

存在しない変数や関数を使おうとしたときに発生します。

ReferenceError: posts is not defined
    at src/pages/blog.astro:8:12

よくある原因: 変数名のスペルミス、import文の忘れ、変数のスコープ外からのアクセス

AIへの伝え方: エラーメッセージ + ファイル冒頭のimport部分を含むコード

4. NetworkError / FetchError（ネットワークエラー）

APIやサーバーとの通信で問題が起きたときに発生します。

FetchError: request to https://api.example.com/data failed, 
reason: getaddrinfo ENOTFOUND api.example.com

よくある原因: URLの間違い、APIキーの未設定、ネットワーク接続の問題、CORSポリシー違反

AIへの伝え方: エラーメッセージ + 使用しているAPI/URLの情報 + ネットワーク状況

5. BuildError / CompileError（ビルドエラー）

プロジェクトのビルド（本番用ファイルの生成）で失敗したときに発生します。

[ERROR] [vite] Could not resolve import "./components/Header" 
from "src/layouts/Layout.astro"

よくある原因: ファイルパスの間違い、ファイル名の大文字小文字の不一致、拡張子の省略

AIへの伝え方: エラーメッセージ + プロジェクトのフォルダ構成（ls の結果など）

---

ブラウザの開発者ツール（DevTools）の使い方

Webアプリを作っているとき、ブラウザのDevToolsはデバッグの必須ツールです。AIに情報を伝えるためにも、基本的な使い方を覚えておきましょう。

DevToolsの開き方

ブラウザ	ショートカット（Mac）	ショートカット（Windows）
Chrome	Cmd + Option + I	Ctrl + Shift + I
Firefox	Cmd + Option + I	Ctrl + Shift + I
Safari	Cmd + Option + I（要設定）	-
Edge	Cmd + Option + I	Ctrl + Shift + I

または、ページ上で**右クリック → 「検証」**でも開けます。

よく使うタブ

Console（コンソール）タブ

JavaScriptのエラーや console.log() の出力が表示される場所です。赤い文字で表示されるのがエラー。AIに報告するときは、このコンソールに表示されたエラーメッセージをコピーしましょう。

Elements（要素）タブ

HTMLの構造とCSSスタイルを確認できます。「レイアウトが崩れる」「色が変わらない」といったCSS問題のデバッグに使います。要素をクリックすると、適用されているCSSが右側に表示されます。

Network（ネットワーク）タブ

API通信の成功・失敗を確認できます。赤くなっている行は通信エラー。ステータスコード（404, 500など）も確認できます。

Sources（ソース）タブ

読み込まれたファイルを確認したり、ブレークポイント（一時停止ポイント）を設定できます。上級者向けですが、AIに「Sourcesタブで変数の値を確認して」と言われることがあります。

DevToolsの情報をAIに伝える方法

1. Consoleタブを開く
2. 赤いエラーメッセージを右クリック → 「コピー」（または全選択してコピー）
3. AIチャットに貼り付ける
4. 必要に応じてNetworkタブのエラー情報も追加する

---

AIへのエラー報告テンプレート ── 3段階

状況に応じて報告の詳しさを調整しましょう。

レベル1: 最低限（これだけで8割解決）

エラーが出ました。直してください：

[エラーメッセージ全文を貼る]

シンプルなエラーならこれで十分AIが解決してくれます。

レベル2: 標準（より正確な回答）

【やりたいこと】
トップページに記事一覧をカード形式で表示したい

【やったこと】
npm run dev を実行した

【起きたこと】
ブラウザに何も表示されず、ターミナルに以下のエラーが出た

【エラーメッセージ】
[全文を貼る]

【環境】
Mac, Node.js v22, Astro v6

レベル3: 詳細（複雑な問題・何度もやり取りしているとき）

【やりたいこと】
Markdownファイルから記事データを取得し、日付順にソートして表示したい

【やったこと】
1. src/content/posts/ にMDXファイルを5つ作成
2. src/pages/index.astro でgetCollection('posts')を呼び出し
3. npm run dev を実行

【起きたこと】
ブラウザの画面は真っ白、ターミナルに型エラーが出た

【エラーメッセージ】
[ターミナルのエラー全文]

【Consoleのエラー】
[ブラウザDevToolsのエラー全文]

【関連コード】
[該当ファイルの内容]

【環境】
- OS: macOS Ventura
- Node.js: v22.1.0
- パッケージマネージャ: npm 10.x
- フレームワーク: Astro 5.x
- デプロイ先: Cloudflare Pages

【すでに試したこと】
- npm install をやり直した → 変化なし
- node_modules を削除して再インストール → 変化なし

---

よくあるエラーパターン15選と対処法

バイブコーディングで頻繁に遭遇するエラーを、カテゴリ別に整理しました。

npm / パッケージ関連

1. Module not found

Error: Cannot find module 'xxx'

原因: パッケージがインストールされていない 解決: npm install xxx を実行

2. npm ERR! ERESOLVE

npm ERR! ERESOLVE could not resolve
npm ERR! peer dependency conflict

原因: パッケージ間のバージョンが競合している 解決: npm install --legacy-peer-deps を試す。または package.json でバージョンを調整

3. npm ERR! ENOENT / package.json not found

npm ERR! enoent ENOENT: no such file or directory, open 'package.json'

原因: プロジェクトフォルダの外で npm install を実行している 解決: cd でプロジェクトフォルダに移動してから再実行

ビルド / コンパイル関連

4. SyntaxError: Unexpected token

SyntaxError: Unexpected token '<'

原因: コードの書き方が間違っている（括弧の閉じ忘れ、JSXの構文ミスなど） 解決: AIにエラー箇所のファイルを丸ごと見てもらう

5. Import / Resolve エラー

Could not resolve import "./components/Header" from "src/layouts/Layout.astro"

原因: ファイルパスの間違い、拡張子の省略、大文字小文字の不一致 解決: ファイルの存在確認。ls でフォルダ内容を確認してAIに共有

6. TypeScript型エラー

Type 'string' is not assignable to type 'number'

原因: 変数に期待と異なる型の値を代入しようとしている 解決: エラーメッセージと該当コードをAIに見せる。型定義を修正するか as でキャストする

ランタイム（実行時）関連

7. TypeError: Cannot read properties of undefined

TypeError: Cannot read properties of undefined (reading 'map')

原因: データが undefined（未定義）なのに、その中身にアクセスしようとしている 解決: データの取得元を確認。?.（オプショナルチェーン）や初期値の設定

8. EADDRINUSE（ポート使用中）

Error: listen EADDRINUSE: address already in use :::4321

原因: 同じポートで別のプロセスが動いている 解決: 別のターミナルで起動しているサーバーを停止。または --port 4322 でポートを変更

9. RangeError: Maximum call stack size exceeded

RangeError: Maximum call stack size exceeded

原因: 関数が無限に自分自身を呼び出している（無限再帰） 解決: 再帰処理の終了条件を確認。コードをAIに見せて無限ループの原因を特定

デプロイ関連

10. Build failed（デプロイ時ビルド失敗）

Error: Build failed with exit code 1

原因: ローカルでは動くが、本番環境のビルドで失敗している 解決: デプロイログの全文をAIに共有。Node.jsバージョンの不一致が多い

11. 404 Not Found（デプロイ後）

404 - Page Not Found

原因: ルーティング設定のミス、ビルド出力先の設定ミス 解決: デプロイ先の設定（出力ディレクトリ、ベースパス等）を確認

12. Permission denied（EACCES）

Error: EACCES: permission denied

原因: ファイルやフォルダへのアクセス権限がない 解決: Mac: sudo をつけて実行。npm globalの場合は npx を使う方が安全

CSS / スタイル関連

13. スタイルが適用されない

エラーメッセージは出ないが、見た目が期待通りにならないパターンです。

よくある原因: クラス名のタイポ、CSSの優先度（詳細度）の問題、キャッシュ 解決: DevToolsのElementsタブで該当要素を検証。適用されているCSSを確認してAIに共有

14. レイアウト崩れ（Flexbox / Grid）

画面サイズによってレイアウトが崩れるパターンです。

よくある原因: flex-wrap の未指定、min-width / max-width の未設定 解決: DevToolsで崩れた状態のスクリーンショット + CSSコードをAIに共有

環境関連

15. Node.js バージョン不一致

error@vite: The engine "node" is incompatible with this module. Expected version ">=18"

原因: 使用中のNode.jsバージョンがプロジェクトの要件を満たしていない 解決: node -v で現在のバージョンを確認し、必要に応じてアップデート

---

AIでも解決できないケースとその対処法

AIはデバッグの強い味方ですが、万能ではありません。以下のケースではAIだけでは解決が難しいことがあります。

1. 環境固有の問題

自分のPCにだけ起きる問題（セキュリティソフトの干渉、ファイアウォール設定など）は、AIが再現できないため解決が難しいことがあります。

対処法: エラーメッセージだけでなく、OS・セキュリティソフト・ネットワーク環境などの情報もAIに伝える

2. 最新のライブラリ・フレームワークの問題

AIの学習データには最新バージョンの情報が含まれていない場合があります。

対処法: 公式ドキュメントのURLやChangelogの内容をAIに貼り付けて参照させる

3. ロジックの複雑なバグ

「エラーは出ないが、計算結果が間違う」ようなロジックバグは、AIにとっても発見が難しいケースがあります。

対処法: 「期待する入力と出力」の具体例を示し、「実際はこうなる」と伝える

4. 複数のサービスが絡む問題

フロントエンド + バックエンド + データベース + 外部APIなど、複数のサービスが絡む問題は原因の切り分けが難しくなります。

対処法: どのサービス間の通信で問題が起きているか切り分けてからAIに相談する

5. パフォーマンスの問題

「動くけど遅い」という問題は、エラーメッセージが出ないためAIへの伝え方が難しくなります。

対処法: DevToolsのPerformanceタブやLighthouseのスコアなど、具体的な数値をAIに伝える

---

デバッグのベストプラクティス

効率的にデバッグを行うための習慣を身につけましょう。

こまめにコミットする

最も重要なルール。コードが正常に動いている状態を git commit で保存しておけば、壊れたときに git diff で「何が変わったか」が一目瞭然です。

# 機能が動いたらすぐコミット
git add .
git commit -m "トップページに記事一覧を追加"

# 次の変更でエラーが出たら...
git diff  # 何を変えたか確認
# → AIに「この変更後にエラーが出た」と伝える

小さく変更する

一度に大量のコードを変更すると、どの変更がエラーの原因か分からなくなります。

やり方	リスク	デバッグしやすさ
1ファイルずつ変更	低い	簡単
3〜5ファイルまとめて変更	中程度	やや難しい
10ファイル以上一気に変更	高い	非常に困難

エラーが出たら即対処する

エラーを放置して別の作業を進めると、エラーが重なって原因の切り分けが困難になります。1つのエラーを直してから次の作業に進むことを徹底しましょう。

再現手順を記録する

「どの操作をしたらエラーが出るか」を把握しておくと、AIに正確に伝えられます。

1. npm run dev を実行
2. ブラウザで http://localhost:4321 を開く
3. 「記事一覧」ボタンをクリック
4. → エラーが発生

コンソールログを活用する

原因が分からないときは、コードに console.log() を入れて変数の中身を確認します。

// データが正しく取得できているか確認
const posts = await getCollection('posts');
console.log('posts:', posts);        // データの中身を表示
console.log('posts数:', posts.length); // データの件数を表示

DevToolsのConsoleタブに表示された結果をAIに共有すると、原因の特定が早くなります。

「動く最小構成」から始める

新しい機能を追加するときは、まず最もシンプルな形で動かしてから段階的に拡張しましょう。

---

デバッグ時にAIに渡すと喜ばれる情報チェックリスト

AIに効率よくデバッグしてもらうために、以下の情報をできるだけ多く伝えましょう。

情報	重要度	取得方法
エラーメッセージ全文	必須	ターミナル / DevTools Console
該当ファイルのコード	高い	エディタからコピー
やろうとしていたこと	高い	自分の言葉で説明
再現手順	中程度	操作を番号付きで記述
環境情報	中程度	node -v, OS, ブラウザ
フォルダ構成	状況次第	ls -la の結果
package.json	状況次第	ファイルを貼り付け
DevToolsのNetworkタブ	API問題時	スクリーンショットや内容コピー
git diff の結果	変更後のエラー	git diff の出力

---

デバッグの心構え

最後に、デバッグに臨む心構えを整理します。

1. エラーは日常 — プロでも1日に何十回もエラーに遭遇する
2. エラーは味方 — 「ここを直せ」と教えてくれている
3. AIに丸投げでOK — エラーメッセージを貼るだけ
4. 直ったら即コミット — 次のエラーに備える
5. 焦らない — エラーが出てもコードが「壊れた」わけではない
6. 小さく進める — 大きな変更ほどデバッグが大変になる
7. 同じエラーは2度目から楽 — 経験がそのまま力になる

---

FAQ: AIデバッグでよくある質問

Q1. エラーメッセージが英語で読めません。どうすればいいですか?

A. そのまま全文コピーしてAIに貼ればOKです。AIは英語のエラーメッセージを日本語で解説してくれます。むしろ翻訳せずに原文のまま貼った方が、AIが正確に理解できます。「このエラーを日本語で説明して」と一言添えるのも良いでしょう。

Q2. エラーメッセージが長すぎるのですが、全部貼る必要がありますか?

A. できるだけ全文を貼ることをおすすめします。特にスタックトレース（at ... で始まる行の連続）は、エラーの発生場所を特定する重要な手がかりです。ただし、同じエラーが何百行も繰り返されている場合は、最初の20行程度で十分です。

Q3. AIの提案通りに直したのに、別のエラーが出ました。AIが間違っているのでは?

A. 必ずしもAIが間違っているわけではありません。1つのバグを直すと、それまで隠れていた別のバグが表面化することはよくあります。新しいエラーメッセージを再度AIに貼って、1つずつ解決していきましょう。ただし、5回以上ループする場合は別のアプローチをAIに提案してもらうと良いです。

Q4. ターミナルとブラウザの両方にエラーが出ています。どちらを優先すべきですか?

A. ターミナルのエラーを先に解決しましょう。ターミナルのエラーはサーバー側の問題で、これが解決しないとブラウザ側も正常に表示されません。ターミナルのエラーが消えてからブラウザ側のエラーに対処するのが効率的です。

Q5. AIに聞いても「コードを見せてください」と言われます。何を見せればいいですか?

A. エラーメッセージに含まれるファイル名と行番号のファイルを見せましょう。例えば at renderCards (src/components/CardGrid.astro:12:15) なら CardGrid.astro の内容です。また、そのファイルが import している他のファイルも関連する場合があるので、聞かれたら追加で共有しましょう。

Q6. node_modules を削除して再インストールすると直ることがあると聞きました。本当ですか?

A. はい、パッケージ関連のエラーでは有効な手段です。以下のコマンドで実行できます。ただし、これは「おまじない」ではなく、キャッシュやバージョンの不整合をリセットする合理的な方法です。

rm -rf node_modules package-lock.json
npm install

Q7. エラーではなく「警告（Warning）」が出ています。対処すべきですか?

A. 警告はすぐに対処しなくてもアプリは動きますが、放置すると将来のバージョンアップ時にエラーに変わる可能性があります。まずはエラーの解決を優先し、余裕があるときに警告にも対応しましょう。AIに「この警告は対処すべき?」と聞けば、緊急度を教えてくれます。

---

まとめ

デバッグは、プログラミングにおいて避けられない作業です。しかしバイブコーディングでは、AIという強力なパートナーがいます。

覚えておくべきことは3つだけ。

1. エラーが出たらメッセージを全文コピー
2. AIに貼り付けて聞く
3. 直ったらすぐコミット

この3ステップを繰り返すだけで、どんなエラーも恐れる必要はありません。最初は戸惑うかもしれませんが、エラーに何度も遭遇するうちに「ああ、このパターンね」と分かるようになってきます。AIと一緒に、楽しくデバッグしていきましょう。