Antigravity でブレークポイントが効かないときの実用診断ガイド

Antigravity で launch.json を整え、ブレークポイントを置き、F5 を押す。期待通りに止まる…はずが、何の反応もないままプログラムが最後まで走り抜けてしまう。デバッガーが効かないトラブルは、そのコードを書いた本人にとってもっとも消耗する瞬間ではないでしょうか。

私自身、個人開発でアプリのリリース前にこの問題で半日を溶かしたことがあります。原因は些細な設定ミスだったのですが、調べる順序を間違えると沼にはまる典型例でした。ここではブレークポイントが効かないときに「上から順に潰していくと最短で原因にたどり着ける」診断手順を、Antigravity 特有の落とし穴も含めて整理していきます。

灰色のブレークポイントは「未バインド」のサイン

Antigravity（および VS Code 系の IDE）では、ブレークポイントの見た目で原因の半分が分かります。ここを最初に見ない方が驚くほど多いので、まずは色と形を確認する習慣をつけてください。

赤い実線の丸 — 実行中のプロセスにバインド済みです。ここで止まらないのは別の問題（後述）の可能性が高いです。
灰色の中空丸 — まだプロセスにバインドされていない（unverified）状態です。「IDE が、このソースコードがロードされたコードと同じだと認識できていない」ことが原因と考えてください。
白抜きで斜線が入った丸 — ソースマップが見つからないか、ファイルパスが一致していません。

つまり、デバッグセッション開始後にブレークポイントが灰色のままならパスやソースマップを疑い、赤になっているのに止まらない場合は実行されているコードパスやコンディショナルブレークポイントの条件を疑う、という二段構えの判断ができます。

ソースマップ不一致 — 全ケースの約8割

TypeScript・Vue・Svelte・JSX や、Babel/SWC/Webpack 経由でビルドされたコードでブレークポイントが効かない場合、もっとも多い原因がソースマップの不一致です。私の体感ですが、ここで詰まっているケースが全体の8割を占めます。

// .antigravity/launch.json — ソースマップを診断するための一時設定
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug Node TS (verify sourcemaps)",
      "type": "node",
      "request": "launch",
      "program": "${workspaceFolder}/dist/server.js",
      "preLaunchTask": "tsc: build",
      "outFiles": [
        "${workspaceFolder}/dist/**/*.js",
        "!**/node_modules/**"
      ],
      // ソースマップの解決ログをコンソールに出力する一時フラグ
      "trace": true,
      "sourceMaps": true
    }
  ]
}

"trace": true を一時的に有効にすると、デバッグコンソールに「どのソースファイルがどの生成ファイルに対応しているか」のログが流れます。ここで sourcemap not found や path mismatch と書かれていれば、原因はほぼ確定です。

修正の典型的な順序は次のとおりです。まず tsconfig.json の "sourceMap": true が抜けていないかを確認し、次にビルドキャッシュ（dist/、.next/cache/、node_modules/.cache/ など）を一度削除してフルビルドし直します。それでも直らない場合は、outFiles のパスが実際に生成されているディレクトリと一致しているかを確認します。

特にモノレポ構成で詰まる方は、Antigravity のモノレポ管理ガイドで扱っているワークスペース解決の挙動を確認しておくと、outFiles のグロブパターン設計の参考になります。

launch.json の cwd と program パスを疑う

ソースマップに問題がない場合、次に疑うのは launch.json の作業ディレクトリ（cwd）と起動するエントリポイント（program）です。

{
  "name": "Debug Python — explicit cwd",
  "type": "debugpy",
  "request": "launch",
  "program": "${workspaceFolder}/src/main.py",
  // ⚠️ cwd を省略すると Antigravity を起動したフォルダが基準になり、
  //     相対パスの import やリソース読み込みが破綻する
  "cwd": "${workspaceFolder}",
  "console": "integratedTerminal",
  "env": {
    "PYTHONPATH": "${workspaceFolder}/src"
  }
}

この設定で重要なのは cwd の明示です。私の経験上、cwd を省略してデフォルト挙動に任せると、別のプロジェクトを開いた状態でデバッグを始めたときに program のパスがずれて、まったく違うファイルを実行していたことが何度もありました。個人開発で複数プロジェクトを同時に開く方は、cwd を明示する習慣をつけることをおすすめします。

また Node.js の場合、--inspect-brk フラグの有無で、最初の行で止まるかどうかが変わります。「アプリ起動時に止まらない」ように見える原因が、単に「最初の行をすでに通り過ぎていた」だけ、ということも珍しくありません。

言語別の落とし穴

ブレークポイントが効かない原因は、言語やランタイムによって特有のものがあります。Antigravity 自体ではなくランタイム側の問題であるケースも多いので、ここを見落とすと延々と IDE 側を疑い続けることになります。

TypeScript: ts-node 経由でデバッグするときは --inspect だけでなく --require ts-node/register も必要です。tsx や swc-node を使っている場合は、それぞれ専用のソースマップ設定があるので公式ドキュメントを確認してください。
Python: pip install debugpy が完了していない、または仮想環境が launch.json の python パスと一致していないと、ブレークポイントは灰色のままです。which python（macOS/Linux）または where python（Windows）の出力と launch.json の python を必ず突き合わせます。
Go: delve のバージョンが古いと、最近の Go コンパイラが生成するデバッグ情報を読めません。go install github.com/go-delve/delve/cmd/dlv@latest で最新化してから再試行します。
Rust: lldb または cppvsdbg のいずれを使うかで挙動が変わります。cargo build のときに --release を付けていると最適化で行情報が消えるため、デバッグ時は必ずデバッグビルドを使ってください。

LLM サポートを併用する場合は、Antigravity の AI デバッグガイドで扱っている手順と組み合わせると、原因切り分けの速度が上がります。

Antigravity 特有の見落としがちな3点

最後に、VS Code 系全般というより Antigravity 特有のチェックポイントを3つ挙げます。意外とこの3つで解決することが多い箇所です。

エージェント実行中のプロセス占有: Antigravity のエージェントが裏でプロセスを保持していると、デバッガーがアタッチできず黙って失敗することがあります。エージェント実行を一度キャンセルしてから F5 を押し直してみてください。
AI 補完の自動編集: AI がデバッグ起動直前にファイルを書き換えると、ソースマップと生成物の対応が壊れます。デバッグ前に Cmd/Ctrl + Shift + P →「Save All」を実行する習慣をつけると、不意の改変が原因のトラブルを減らせます。
マルチワークスペース時のスコープ: 複数フォルダをワークスペースに含めている場合、launch.json がどのフォルダのものを使っているかを左下のステータスバーで確認します。違うフォルダの設定が読まれていることが意外と多いです。

このあたりの設定挙動については、Antigravity のカスタムルールとプロジェクト設定マスターもあわせて参照すると、プロジェクト単位の設計判断がスムーズになります。

それでも効かないときの最終診断

上記をすべて確認しても止まらない場合、以下の順で「コードが本当に実行されているか」を確かめます。ブレークポイントを使わず、最古の道具である console.log に戻る作業です。

// src/main.ts — ブレークポイントの代わりに console.log で実行確認
export async function handler(event: unknown) {
  console.log('🟢 handler invoked', { time: Date.now() });
  // ↑ この行が出力されない = この関数自体が呼ばれていない
  //   出力される + ブレークポイント効かない = ソースマップ問題
  //   出力される + 次の console.log が出ない = 例外で抜けている
  const result = await process(event);
  console.log('🟢 handler returning', result);
  return result;
}

console.log で実行経路を追えれば、「ブレークポイントが効かない」のか「そもそもそのコードが通っていない」のかが切り分けられます。意外と多いのが、テストランナーや別のエントリポイントから実行されていて、デバッグセッションのプロセスではコードに到達していなかった、というケースです。

ブレークポイントの問題は原因が複数の層にまたがるため、当てずっぽうに設定をいじると沼にはまります。次にデバッガーが反応しないと感じたら、まずブレークポイントの色を確認してから、ソースマップ → cwd / program → 言語固有設定 → Antigravity 特有設定の順に切り分けてみてください。順序を守るだけで、原因特定の時間が大きく短縮されるはずです。

私自身、判断に迷ったときに何度も読み返している一冊です。