CursorのDebug Modeとは？使い方とログ収集の仕組み、Agent・Plan・Askとの違い

Debug Modeは、AIコードエディタCursorのエージェントを「すぐ直す」のではなく「原因を確かめてから直す」動きに切り替えるモードです。エージェントは原因の仮説を複数立て、コードに計測用のログを仕込み、あなたがバグを再現したときの実行時データを読んでから、数行の修正を出します。2025年12月10日のCursor 2.2で追加され、2026年4月14日にはCLIでも使えるようになりました。この記事では、エディタとCLIでの使い方、ログがどこに集まるか、Agent・Plan・Askとの使い分けを、公式ドキュメントとCLI 2026.10.22版の実装で確かめた内容で整理します。

まとめ：Debug Modeは再現できるのに原因が分からないバグ用のモード

• 動き：仮説を立てる→計測ログを仕込む→あなたが再現する→ログを分析する→的を絞った修正→再現で確認し、確定すると計測コードを撤去する、の6段階です。
• 起動：エディタはAgentパネル（Mac は Cmd+I）で Shift+Tab かモード選択から Debug を選びます。CLIは対話中に /debug と打ちます（--mode の選択肢は plan と ask だけ）。
• ログの行き先：計測ログはローカルで動くデバッグサーバーへ送られます。CLIの実装では 127.0.0.1 の 7242〜7942 番ポートで受け、ワークスペースの .cursor/debug-<セッションID>.log に追記します。
• 選び方：作るものが決まっていればAgent、コードを変えずに理解したいならAsk、複数ファイルの機能を計画から確認したいならPlan、実行時の証拠が要るバグならDebugです。
• 向かない場面：型エラーやタイプミスのように読めば分かるバグ、ビルドが通らずアプリを動かせない状態、Cursorと同じマシンからログを送れない実行環境です。

Debug Modeの仕組み｜仮説・計測ログ・再現による原因の絞り込み

Cursorの公式ブログはDebug Modeを「ランタイム情報と人による検証を軸にした、まったく新しいエージェントループ（an entirely new agent loop built around runtime information and human verification）」と2.2の発表記事で説明しています。公式ドキュメントが示す流れは次の6段階です。

1. 関連ファイルを調べ、根本原因の仮説を複数立てる
2. 仮説を確かめるログ文をコードに追加する
3. あなたに具体的な再現手順を示し、バグを再現してもらう
4. 集まったログから、実際の原因を特定する
5. 原因に絞った修正を入れる（多くは数行）
6. 再現手順をもう一度試して直ったことを確かめ、確定すると計測コードをすべて取り除く

通常のAgentとの違い：実行時の証拠に基づく修正

通常のAgentは、バグの説明を受けるとコードを読んで修正案を出します。原因が見えているバグならこれが一番速い。一方、実行時の状態やタイミングで決まるバグでは、コードを読むだけでは原因を決めきれず、推測で複数ファイルを書き換える案になりがちです。発表記事は、Debug Modeの修正を「標準のエージェントなら返ってきた数百行の推測的なコードではなく、正確な2〜3行の変更」と表現しています。書き換え範囲が小さければ、レビューも差し戻しも楽になります。

修正が効いていないと判断したときは、エージェントがログを追加し、もう一度再現してもらって方針を練り直します。直ったかどうかの最終判断は人に残す設計で、ここがAgentとの一番大きな違いです。

計測ログの送り先：ローカルのデバッグサーバー

Debug Modeが仕込むログは、画面に出す console.log ではありません。公式ドキュメントは「Cursor拡張機能の中で動くローカルのデバッグサーバーへデータを送るログ文」と書いています。受け口の具体はドキュメントに無いため、CLIの配布パッケージ（2026.10.22版）のソースで確かめると、次の作りでした。

サーバーは Access-Control-Allow-Origin: * を返すので、ブラウザで動くフロントエンドのコードからも送れます。仕込まれるログはおおむね次のような形になります。下の例は受け口の仕様に合わせたJavaScriptの断片です。実行する場合はURLのポート・ランダムIDとヘッダーのセッションIDを実際の値に置き換え、isSubmittingとorderIdが参照できる位置に置いてください。実際に挿入されるコードは言語とモデルで変わります。受け口を再現した模擬サーバーで実行し、ログファイルに1行のJSONが追記されることを確認しています。

// 計測ログ（例）：仮説Aを確かめるため、分岐の直前で状態を送る
fetch('http://127.0.0.1:7242/ingest/<ランダムID>', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'X-Debug-Session-Id': 'a1b2c3' },
  body: JSON.stringify({ hypothesis: 'A', at: 'handleSubmit', isSubmitting, orderId, t: Date.now() }),
}).catch(() => {});

この作りから2つのことが言えます。ひとつは、ログがアプリ本来のログ出力（標準出力やログ基盤）と混ざらないこと。もうひとつは、CLIの実装では送り先がループバックなので、CLIと同じマシンで動くコードからしか届かないことです。後者は「コンテナ・実機で再現するときの注意」で扱います。どのレベルのログを本番に残すかという通常のログ設計は、ログレベルの使い分けで整理しています。

エディタでDebug Modeを使う手順

AgentパネルからのDebugへの切り替え

公式ヘルプの手順は4つです。Agentパネルを開き（Mac は Cmd+I、Windows・Linux は Ctrl+I）、Shift+Tab でモードを順に切り替えるか、モード選択のドロップダウンで Debug を選びます。バグを説明するかエラーメッセージを貼り付け、Return で送ります。

モードを切り替えると新しいコンテキストで始まります（各モードは別々のコンテキストを持つ、と公式ヘルプが明記）。Agentで実装していた会話の途中でDebugに切り替えると、それまでの経緯は引き継がれません。前の会話で分かっていることは、Debugの最初のメッセージに書き直して渡します。

バグ報告の記載項目：期待・実際・再現手順

公式のコツは、再現手順・エラーメッセージ・スタックトレースを含めて詳しく書くこと、期待した動きと実際の動きを分けて書くことです。再現手順や期待した動きを詳しく伝えると、仮説を確かめる計測ログを仕込みやすくなります。次の型で書くと抜けが出にくくなります。

症状：注文フォームの送信ボタンを素早く2回押すと、注文が2件作られる
期待：何回押しても注文は1件
実際：約3回に1回、同じ内容の注文が2件できる
再現手順：1. /checkout を開く 2. 商品を1つ入れる 3. 送信を0.5秒以内に2回押す
エラー：なし（サーバーログに同じ時刻のPOST /orders が2行）
関係しそうな場所：src/checkout/OrderForm.tsx の handleSubmit

バグの再現・修正確認と「修正済み」の確定

エージェントは仮説とログを仕込んだあと、再現手順を示して待ちます。手順どおりにアプリを操作し、続行するとエージェントがログを読みに行きます。CLIでは再現手順のカードに「1. Proceed（Enter）」「2. Mark as fixed（f）」「3. Write a follow-up（w）」の3つの選択肢が出ます。Agents Window では2026年10月9日の3.24から、再現手順がプロンプト上の Debug ピルにまとまり、Proceed か Mark Fixed を押すかDebug以外のモードへ移るまで、キューに入れた追加入力は送られずに待つようになりました（リリースノート）。

修正が入ったら、同じ手順をもう一度試します。症状が消えていれば修正済みとして確定し、エージェントが計測コードを撤去します。競合状態のように毎回は起きないバグなら、公式のコツどおり何度か再現してから判断してください。1回たまたま起きなかっただけで確定すると、計測コードが消えて振り出しに戻ります。

CLIでのDebug Modeの起動（/debug）

ターミナルで動くCursor CLI（agentコマンド）では、2026年4月14日の更新でDebug Modeが使えるようになりました。スラッシュコマンドの一覧にある書式は /debug [prompt] です。

$ agent
> /debug 送信ボタンを2回押すと注文が2件作られる。再現手順は…（以下、上の型で書く）

引数なしの /debug はDebug Modeのオンとオフの切り替え、引数付きはDebug Modeでそのまま送信です。起動オプションの --mode が受け付けるのは plan と ask だけで（2026.10.22版のヘルプ定義）、Debugで始めるオプションはありません。CLIのドキュメントにある Shift+Tab の切り替えもAgent・Plan・Askの3つの循環です。名前が似た /logs は、CLI自身の動作ログのパスを表示するコマンドで、Debug Modeの計測ログとは別物です。

クラウドで動くCloud Agentsは、APIの追加指示で指定できるモードが agent か plan とAPIリファレンスに書かれています。あなたが手元で再現してログを返す前提のモードなので、ローカルのエディタかCLIで使うものと考えておくのが安全です。

Agent・Plan・Ask・Debugの違いと使い分け

公式ヘルプ「Agent mode」の比較表を基に、4つのモードを並べます。

迷ったらAgentで始めるのが公式の推奨です。本記事では、Debugを選ぶ実務上の目安として「Agentに2回直させても症状が変わらない」ときを提案します。原因を推測で当て続けるより、ログで事実を取った方が往復が減ります。プロジェクトのルールやユーザールールは4つのモードすべてに適用されるので、Debug用に別のルールを書き直す必要はありません。

画面の見た目が絡むバグは、Debugのログだけでは足りないことがあります。エージェントにブラウザを操作させてスクリーンショットやコンソールを読ませるCursorのBrowserツールや、画面上の要素を指して直させるDesign Modeと組み合わせると切り分けが早くなります。

Debug Modeが効くバグ・向かないバグ

公式ドキュメントが挙げる、Debug Modeが合うバグは4種類です。

• 再現はできるが、コードを読んでも原因が分からないバグ
• 競合状態・タイミングの問題（実行順序や非同期処理で結果が変わる）
• 性能の問題とメモリリーク（実行時の計測が要る）
• 以前は動いていたものが動かなくなった回帰

旧版の本記事では「安定して再現できないバグは向かない」と書いていましたが、公式は逆に、競合状態のような扱いにくい問題は複数回の再現で原因を特定しやすくなると案内しています。毎回でなくても、何度か試せば起きるバグなら対象です。

向かないのは次の場面です。

• 読めば分かるバグ：タイプミス、型の不一致、import漏れ。ログを仕込んで再現する手間の方が大きいので、通常のAgentかエディタの指摘で直します。
• アプリを動かせない状態：ビルドやコンパイルが通らない、計測コードが動く前に起動処理が停止する。ログを取る前提が成り立たないので、まずエラーメッセージをAgentに渡して動く状態に戻します。
• 一度も再現できないバグ：本番だけで起きて手元で条件を作れないものは、ログが集まりません。本番のログやトレースから再現条件を絞るのが先です。

コンテナ・実機で再現するときの注意

CLI 2026.10.22版で確認した計測ログの受け口は、CLIプロセスが動く環境の 127.0.0.1 です。エディタでは、計測コードに設定された送信先と拡張機能の実行環境を確認してください。ループバックアドレスは「自分自身」を指すため、別のマシンや隔離された環境で動くコードが 127.0.0.1 へ送ると、その環境の中の自分自身に届き、Cursorのサーバーには届きません。次の構成では、再現してもログが空になる可能性があります。

• Dockerコンテナの中で動くバックエンド（通常のbridge構成ではホストとネットワーク名前空間が分かれる）
• スマートフォン実機で動くアプリ
• SSHで接続した別サーバーで動くプロセス

こうした構成では、最初の再現のあとに .cursor/debug-*.log へ行が追記されているかを1回確かめてください。内容が増えない場合は、計測箇所が実行されたか、送信先とセッションIDが正しいか、HTTP応答と保存先に問題がないかを確認してください。ホスト上で直接起動できる部分（APIサーバーだけをローカルで動かす、Webアプリをブラウザで開くなど）に再現を寄せるのが確実です。

もう1つの注意は後始末です。確定時に撤去されるのはコードに仕込んだ計測文で、.cursor 配下に書かれたログファイルを消すとは公式に書かれていません。ログには変数の値がそのまま入るので、誤ってコミットしないよう、ログ生成前にリポジトリ直下の .gitignore に次のパターンを追加します。すでに追跡されているログは、この設定だけでは対象外にならないため、Gitの追跡からも外してください。

# Cursor Debug Mode の計測ログ
.cursor/debug-*.log

Cursor 2.6（2026年3月3日）からは複数のDebugセッションを並行して走らせられ、セッション間のポート割り当ての競合も修正されています（2.6の変更履歴）。並行で調べるときも、ログはセッションIDごとの別ファイルに分かれます。

Debug Modeの更新履歴（2.2〜3.24）

2.2の変更履歴は、Debug Modeが「スタック・言語・モデルを問わず動く」と書いています。2.6では、問題の複雑さに応じて仕込むログの数を変えることと、ターンごとに古い計測コードを片付けることも加わりました。Cursor本体の安定版は2026年10月31日時点で3.27.22（3.27は10月22日公開）です。手元の版の確認と更新の手順はCursorのバージョン確認とアップデートで扱っています。

よくある質問

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

エディタは2025年12月10日公開のCursor 2.2からです。CLIは2026年4月14日の更新から /debug で使えます。

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

Agentは説明を受けてすぐ修正を書きます。Debugは仮説を立てて計測ログを仕込み、あなたが再現した実行時のデータで原因を確かめてから、範囲を絞った修正を出します。作るものが決まっていればAgent、動かない理由を探すならDebugです。

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

修正済みとして確定すると、エージェントがコードに入れた計測文をすべて取り除きます。.cursor 配下のログファイルの削除は公式に書かれていないので、.cursor/debug-*.log を .gitignore に入れておくと安全です。

Debug Modeとブレークポイントを使うデバッガーは何が違いますか？

「実行とデバッグ」パネルや launch.json で動かすデバッガーは、VS Code由来のデバッグ機能で、人がブレークポイントで止めて変数を見ます。Debug Modeはエージェントの動き方の1つで、止めずにログを取り、その分析と修正までをエージェントが担います。両者は別の機能で、どちらか一方が他方を置き換えるものではありません。

Debug Modeで直らないときはどうすればいいですか？

修正済みにせず、続行するか追加の指示を書きます。エージェントがログを足し、もう一度再現してもらって方針を練り直します。何度回しても変わらない場合は、再現手順と期待・実際の差を書き直す、ログが .cursor/debug-*.log に届いているかを確かめる、の2点を見直してください。

関連記事

• Cursor CLIの使い方｜agentコマンドの導入・非対話実行とCI連携の手順
• Cursorの「Connect to Browser」とは？ブラウザ操作の設定・使い方とChromeをつなぐ方法【3.27対応】
• Cursor Design Mode（デザインモード）の使い方｜Annotateで画面からUIを直す手順
• Cursorの最新バージョンは3.18系｜バージョン確認とアップデート・更新頻度の実際
• ログレベルの使い分け：ERROR・WARN・INFO・DEBUGの判断基準と本番で残す量の設計