CursorのDebug Modeとは？仮説検証型AIデバッグの使い方と他モードとの違い

Debug Modeは、AIコードエディタCursorが2025年12月10日のバージョン2.2で追加したデバッグ専用のエージェント機能です。従来のエージェントが「コードを読んで即修正案を出す」のに対し、Debug Modeは複数の仮説を立て、ログを仕込み、実際の実行結果で原因を確かめてから直すという順序で動きます。原因が一目で分からない再現性のあるバグを、当てずっぽうの大規模修正ではなく数行の的確な修正で解決させることが狙いです。この記事では、起動から修正確定までの3ステップ、Agent／Plan／Ask／Debugの使い分け、そして効く場面と向かない場面を整理します。

まとめ：Debug Modeは「仮説→ログ→検証」で原因を突き止めるデバッグ機能

• 正体：Cursor 2.2（2025年12月10日）で追加された、ランタイムログと人間の確認を前提にした新しいエージェントループ。現在の3系でも利用できる。
• 流れ：大きく3ステップ。①バグを説明して複数仮説とログを仕込ませる ②バグを再現してランタイムログを収集させる ③修正を検証し、確定するとログが自動撤去される。
• 使い分け：仕様変更や新規実装はAgent、方針づくりはPlan、質問だけならAsk、そして再現できるのに原因が非自明なバグはDebug、と役割で選ぶ。

Debug Modeとは｜Cursor 2.2で追加された仮説検証型のデバッグ

Debug Modeは、Cursorが公式ブログで「ランタイム情報と人間による検証を軸にした、まったく新しいエージェントループ（an entirely new agent loop built around runtime information and human verification）」と説明する機能です。通常のエージェントはコードの静的な読み取りだけで修正案を作りますが、Debug Modeはプログラムが実際に動いたときの変数の値・実行経路・タイミングを手がかりにするため、コードを眺めただけでは分からないバグに強みがあります。

背景には「AIが原因を推測しきれないまま、広範囲を書き換える修正を提案してしまう」という課題があります。Debug Modeはこの推測を、仮説とログという検証可能な手順に置き換えることで、修正の精度と最小性を高めています。

通常のエージェントとの違い｜”当てずっぽうの大規模修正”が起きる理由

通常のAgentモードは、バグを伝えると即座に修正案を生成します。原因が明らかなバグなら速くて有効ですが、実行時の状態に依存するバグでは根拠が乏しく、「たぶんここだろう」という推測で複数ファイルを書き換える提案になりがちです。修正が当たらなければ、書き換えた範囲だけが残り、原因は未解決のまま複雑さが増します。

Debug Modeは修正の前に必ずログで事実を集めます。原因を特定してから直すため、公式が示す典型的な修正は「正確な2〜3行の変更（a precise two or three line modification）」です。書き換え範囲が小さいので、レビューもロールバックも容易になります。

Debug Modeの使い方｜起動から修正確定までの3ステップ

起動は、チャット入力欄のモード選択ドロップダウンから「Debug Mode」を選ぶだけです。以降は次の3ステップで進みます。対応するスタック・言語・モデルを問わず動作します。

ステップ1：バグを説明し、複数の仮説とログを仕込ませる

再現しているバグの症状をできるだけ具体的に伝えます。「送信ボタンを二度押すと注文が重複する」のように、条件・期待動作・実際の動作をセットで書くほど仮説の質が上がります。エージェントはコードベースを解析し、原因の候補となる複数の仮説を立てたうえで、その仮説を検証するためのログ出力（計測コード）を該当箇所へ自動で挿入します。挿入されるのは、たとえば分岐直前で変数の中身を書き出す一行のようなものです。

// エージェントが仮説検証のために自動挿入するログの例
console.log('[debug] handleSubmit isSubmitting=', isSubmitting, 'orderId=', orderId);

ステップ2：バグを再現し、ランタイムログを収集させる

ログを仕込んだ状態で、アプリケーション上でバグを再現します。エージェントは実行中に出力されたログを収集し、変数の状態・実行経路・タイミングを読み取ります。ここが通常のエージェントとの決定的な差で、コードの見た目ではなく「実際に何が起きたか」という実データから根本原因を特定します。再現手順が安定しているほど、収集されるログの信頼性が上がります。

ステップ3：修正を検証し、計測コードを撤去する

原因が特定されると、エージェントは最小限の修正案を提示します。適用したら自分で動作を確認し、バグが解消していれば「修正済み（fixed）」として確定します。確定するとエージェントが挿入したログをすべて自動で撤去し、手元にはそのまま出荷できるクリーンで最小の差分だけが残ります。デバッグ用のログを消し忘れて本番に混入する、という定番の事故を構造的に防げる点が実務では効きます。

Agent／Plan／Ask／Debugモードの違いと使い分け

Cursorには目的の異なる複数のモードがあり、Cursor 3.0以降はエージェントウィンドウ内でこれらを切り替えます。「どのモードを使えばいいか分からない」という悩みは、作業の段階で分けると整理できます。設計はPlan、調査はAsk、実装はAgent、そして原因不明のバグ調査がDebugです。

推奨される流れは、Planで計画を立て、Askで疑問を潰し、Agentで実装、という順です。Debugはこの流れとは独立し、実装後に出た「なぜか動かない」バグの調査で呼び出します。UIを見ながら直すCursorのデザインモードや、AIにブラウザを操作させるConnect to Browserなど目的特化のモードも増えており、作業段階ごとにモードを選び分けるのが前提です。

Debug Modeが効く場面・向かない場面

Debug Modeは万能ではありません。ログ収集を前提とする仕組み上、得意・不得意がはっきり分かれます。

効く場面は、再現できるのに原因が非自明なバグです。実行時の状態やタイミングに依存する不具合、複数の処理が絡んで原因箇所を絞りにくいバグ、既存の大規模・レガシーなコードで影響範囲が読みにくいバグでは、ログという事実が推測を上回ります。

向かない場面もはっきりしています。タイプミスや型不整合のようにコードを見れば分かるバグは、ログを仕込むより通常のAgentやエディタの指摘で直す方が速い。安定して再現できないバグは、ログを仕込んでもデータが集まらず仮説を確かめられません。ビルドやコンパイル自体が通らない状態も、プログラムを実行してログを取れないため不向きです。「再現できる」「実行できる」がDebug Modeを使う前提だと押さえておくと、無駄な回り道を避けられます。

フロント／バックエンド別のDebug Modeが効くバグ類型

フロントエンドでは、フォームの二重送信や特定条件でのみ崩れる画面遷移など、状態管理起因のバグで原因を切り分けやすくなります。Reactのstateやeffectがどの順序で走ったのかをログで追えるため、「なぜかこのタイミングだけ再レンダリングされない」といった再現条件の狭い不具合の原因を切り分けやすくなります。

バックエンドでは、APIが特定リクエストでだけ500を返す、バッチ処理が一部データで止まる、といった原因究明に向きます。リクエストのパラメータやDBから返る値を実行時に記録できるので、想定外の入力や境界値がどこで問題を起こしているかを事実ベースで特定できます。いずれも共通するのは「再現手順が確立していて、実行してログを取れる」ことです。

よくある質問

Debug Modeはどのバージョンから使えますか？

Cursor 2.2（2025年12月10日リリース）で追加されました。以降のバージョンでも利用でき、最新版の変更点はCursor 3.3の変更点まとめで確認できます。

Debug ModeとAgentモードの違いは何ですか？

Agentは説明を受けてすぐ修正案を出しますが、Debug Modeは複数の仮説を立ててログを仕込み、実行時のデータで原因を確かめてから最小限の修正を提示します。原因が明らかなら Agent、原因不明ならDebug、と使い分けます。

Debug Modeを使うには何が必要ですか？

バグが安定して再現でき、アプリケーションを実際に実行してログを収集できる環境が前提です。スタックや言語、使用モデルを問わず動作します。ビルドが通らない、再現できないケースには向きません。

仕込まれたログは後で消えますか？

消えます。修正を「修正済み」として確定すると、エージェントが検証のために挿入した計測コードをすべて自動で撤去し、最小限の変更だけが残ります。デバッグログの消し忘れによる本番混入を防げます。

Debug Modeで必ずバグが直りますか？

必ずではありません。仮説とログで原因に近づく仕組みのため、再現手順が曖昧だと十分なデータが集まらず一度で解決しないこともあります。その場合は再現条件を具体化し、仮説検証のサイクルを繰り返すのが基本です。

関連記事

• Cursor 3.3の変更点｜PRレビュー・並列エージェント・Split PRsを整理
• Cursor Design Modeとは？画面を見ながらUIを直せる公式機能の使い方
• Cursorの「Connect to Browser」とは？AIがブラウザを操作する仕組み・設定・使い方
• Cursor Proとは｜料金プラン・無料版との違い・できることを解説