Cursorの「Debug Mode」とは？使い方とサンプルプロンプトを解説

※Cursorには「Plan Mode(計画してから実装する機能)」という似た名前のモードもありますが、そちらはPlan Modeの解説記事で扱っています。本記事は、バグ修正に特化した「Debug Mode」についての解説です。

Debug Modeとは何か

2025年12月、Cursorは「Debug Mode」という新しいAgentのモードを発表しました。通常のAgentモードが「コードを読んですぐ修正案を出す」のに対し、Debug Modeは実行時の情報を集めてから原因を特定するという、探偵の捜査のようなアプローチを取るのが特徴です。

具体的には、次のような流れで動作します。

1. バグの内容を説明する：症状や再現手順を、できるだけ具体的に伝える
2. 仮説を立てる：エージェントがコードベースを読み込み、原因についていくつかの仮説を生成する
3. ログ計装を追加する：各仮説を検証するためのログ出力コードを、疑わしい箇所に一時的に挿入する
4. バグを再現する：ユーザーが実際にアプリを操作してバグを再現し、エージェントがランタイムログを収集する
5. 原因を特定して修正する：集まったログ(変数の状態、実行パス、タイミングなど)をもとに、ピンポイントな修正を提案する
6. 修正を検証する：もう一度バグを再現してもらい、直っていれば挿入したログ計装をすべて自動的に削除する。直っていなければ、さらにログを追加して絞り込みを続ける

この「仮説→計装→再現→検証」というループのおかげで、当てずっぽうで何百行も書き換えるのではなく、多くの場合2〜3行程度の的確な修正で済むとされています。

起動方法

Shift + Tab でモードを切り替え、「Debug」を選択すると使えます。もしくはそのまま、モードをクリックして切り替えも可能です。

どんなときに向いているか

公式ドキュメントでは、Debug Modeは次のようなケースに向いていると案内されています。

• 再現はできるものの、原因がなかなか分からない厄介なバグ
• パフォーマンスの問題やメモリリーク
• コードを読むだけでは原因が見えてこない問題

逆に、スタックトレースが明確でひと目で原因が分かるような単純なエラーは、通常のAgentモードの方が速く解決できます。「まず普段の直し方を試してみて、それでもダメならDebug Modeに切り替える」という使い分けが現実的です。

実際どれくらい便利なのか

Debug Modeを日常的に使っている海外の開発者のブログでは、次のような点が評価されています。

• HTTPベースのテキストログという仕組みを使っているため、特定のIDE機能(LSPなど)に依存せず、ほぼどんなプログラミング言語・実行環境でも使える(ローカル環境はもちろん、Remote SSH先でも動作する)
• フロントエンドとバックエンドの両方にログを仕込んで、両者をまたぐ不具合の原因を追跡できる
• DatadogやSentryといった外部の観測ツールをMCP経由で連携させると、さらに精度が上がるという声もある

ある開発者は、外部APIとの連携部分でページネーションが常に1ページ目しか返らないというバグに遭遇した際、Debug Modeが「JSONのフィールド名の誤り」「クエリパラメータの不足」「トークンが正しく渡っていない」という3つの仮説を立て、ログ計装を追加。何度か再現とログ収集を繰り返した結果、実はそのAPIには通常のクエリ用と集計用で異なるページネーションの仕組みがあり、集計系のエンドポイントでは別のやり方でトークンを渡す必要があったことが判明したそうです。コードを読むだけでは気づきにくい、こうした「隠れた仕様の違い」を実データから突き止められるのが強みだと言えます。

シーン別サンプルプロンプト

Debug Modeは、状況を具体的に伝えるほど精度が上がります。公式ドキュメントで紹介されている使い方をもとに、シーン別のプロンプト例をまとめました。

エラーメッセージから調査する

UserService.getProfile の45行目で
'Cannot read property id of undefined' というエラーが出ています。
根本原因を特定して修正してください。

スタックトレースのエラー発生箇所と、実際の原因が起きている場所は別なことが多いです。Debug Modeは「そのエラーを呼び出した側」まで遡って原因を探ってくれます。

ログを渡して原因を絞り込む

注文ID 12345 の処理が失敗しています。
ログでは在庫チェック通過→決済認証開始→ここでエラー、
という順番になっています。決済認証後のどこで失敗しているか特定してください。

タイムスタンプ付きのログを渡すと、Debug Modeはイベントの順序を突き合わせて調査してくれます。

サポートチケットから調査する

お客様から「データをエクスポートしたら空のファイルになった」
という問い合わせがありました。Proプラン、アカウントID12345です。
エクスポート機能のコードを確認し、空ファイルになる原因を洗い出してください。

「空のファイル」という症状だけでは、データが0件だった・タイムアウトした・サイレントに失敗した・ダウンロードが壊れていた、など複数の可能性があります。Debug Modeはこうした可能性を洗い出し、何から確認すべきか整理してくれます。

断続的な不具合(flakyなテスト)を調査する

このテストが不安定です。成功する時と失敗する時があります。
20回実行して、失敗したケースを集めてパターンを見つけてください。

何度も手動でテストを実行するのは面倒ですが、こうした反復作業こそDebug Modeが得意とするところです。

フロントエンドの不具合を調査する

Cursorのブラウザツールと組み合わせると、実際にレンダリングされた画面やコンソールエラー、ネットワークリクエストまで確認できます。

チェックアウトページを開いて「注文する」ボタンを押しても反応しません。
スクリーンショットを撮り、コンソールエラーを確認して原因を特定してください。

再発防止・ナレッジ化のコツ

同じような不具合の調査を繰り返さないために、.cursor/rules/ 配下にデバッグ用のルールファイルを用意しておくのもおすすめです。よくある不具合のパターンや、調査に使う社内クエリ、既知のflakyテストなどをメモしておくと、Debug Modeがそれを踏まえて調査してくれるようになります。

修正が終わったら、「なぜこの不具合が起きたのか」をAskモードで確認し、同じパターンが他の箇所に潜んでいないかもあわせて聞いてみると、再発防止につながります。

なお、これはDebug Mode自体の機能ではありませんが、Cursorでバグを直してもらう際の定番のコツとして、「まず対応方針の概要だけ提示させ、コードは書かせない」というプロンプトを最初に送るユーザーも多いようです。エージェントの理解のズレを、コードを書かせる前に確認できるため、手戻りを減らせます。

既知の制限・注意点

これらの制限の多くは、.cursor/rules/*.mdc に「特定のライブラリを使う」「変更後は指定のlintコマンドをエラーなく通す」といったルールを書いておくことである程度回避できる、という報告もあります。CLIで入力が効かなくなる問題は、Escapeキーで一旦解除するか、信頼できるコマンドをあらかじめ許可リストに入れておく・自動承認を有効にしておくことで回避しやすくなります。

まとめ

Debug Modeは、「コードを読んで推測する」のではなく「実際に動かして得られたデータから原因を特定する」という、地に足のついたデバッグの型をエージェントに組み込んだ機能です。原因不明の厄介なバグやパフォーマンス問題に強い一方、単純なエラーには通常のAgentモードの方が早いこともあるので、使い分けが大切です。

まだ使ったことがない方は、次に「原因がよくわからないバグ」に遭遇したタイミングで、Shift+Tab からDebug Modeを試してみることをおすすめします。