Cursor バグ修正完全ガイド：エラー分析から解決策検証までの効率的ワークフロー

午前1時、コンソールはまたしても不快な赤色で埋め尽くされています。

私は画面上の TypeError: Cannot read property 'map' of undefined という行を見つめながら、疲れ切った目をこすりました。このエラーを見るのは今夜でもう3回目です。エラーメッセージをコピーし、新しいタブを開き、Google 検索、Stack Overflow… この一連の流れは目を閉じていてもできます。しかし30分が経過し、5、6種類の解決策を試しても、問題は解決していません。

正直なところ、かなり参っていました。

Alibaba Cloud - 開発者向けクラウドの第一候補、ライトサーバー15%OFF、プロジェクトの迅速な立ち上げを支援

15%割引を入手 →広告

その後 Cursor を使い始めたとき、私は救世主を見つけたと思いました——AI がバグを直してくれる！しかし、現実はそう甘くありませんでした。エラーメッセージを AI に投げるだけでは、的外れな解決策が返ってくるか、直ったと思ったら別の場所が壊れるかのどちらかでした。私は Cursor が使い物にならないのではないかと疑いさえしました。

しかし、自分なりの Cursor デバッグワークフローを確立して初めて、問題はツールではなく自分にあることに気づきました——使い方が悪かったのです。

この記事では、私が失敗から学び、まとめ上げたこのワークフローの4つの重要なステップを共有します。「エラーが出たけど、どうやって AI に助けてもらえばいいかわからない」という状況に陥ったことがあるなら、これらの経験がきっと役立つはずです。

ステップ1：エラー情報の正しい収集と分析

私は以前、とんでもなく愚かな間違いを犯していました。エラーを見たら、最初の1行だけコピーして Cursor に投げていたのです。

例えば Error: Cannot find module 'express' を見て、そのまま「Cursor、このエラー直して」と頼むのです。AI は困惑し、全く的外れな提案をしてきます。後になって理解しました——完全なスタックトレースこそが鍵なのだと。

1行目だけでなく、完全なスタックトレースを見る

エラーメッセージは医者の診断のようなものです。症状（1行目）は単なる表象に過ぎず、病因はその後の検査レポート（スタックトレース）に隠されています。

完全なスタックトレースはこのようなものです：

TypeError: Cannot read property 'map' of undefined
    at UserList.render (src/components/UserList.jsx:23:18)
    at finishClassComponent (react-dom.development.js:17485:31)
    at updateClassComponent (react-dom.development.js:17435:24)

1行目は「何が起きたか」を、その後の数行は「どこで起きたか」を教えてくれます。ほら、問題は React のソースコードではなく、UserList.jsx の23行目にあります。この情報は極めて重要です。

私の習慣：エラーに遭遇したら、1行目だけでなく、スタックトレース全体（通常5-10行）をキャプチャします。

エラーの種類を識別し、十把一絡げにしない

エラーの種類によって対処法は異なります。私は大まかに以下のように分類しています：

1. 構文エラー：括弧の閉じ忘れやキーワードのスペルミスなど。Cursor は一瞬で見抜きます。
2. ランタイムエラー：undefined is not a function など、データの問題やロジックの問題。
3. 型エラー（TypeScript）：型の不一致。関連する型定義を一緒に AI に見せる必要があります。
4. 依存関係/環境エラー：Module not found など、package.json や Node のバージョンを確認する必要があります。

Cursor に質問するときは、まずエラーの種類を説明します。例えば「これは TypeScript の型エラーで…」といった具合に。そうすれば AI はどの方向に思考を巡らせればよいかが分かります。

コンテキストを記録する：何をしてエラーになったか

ある時、設定ファイルを変更したらプロジェクト全体が動かなくなりました。エラー情報だけを Cursor に渡すと、コードを修正するよう提案されました。半日修正しても無駄でした。

その後、「webpack.config.js の entry を変更したところだ」と補足すると、Cursor は即座にパスの記述ミスだと気づきました。

教訓：直前に何をしたか AI に伝えましょう。たとえその操作が「問題ないはず」だと思っていても。多くの場合、問題は「問題ないはず」の場所に潜んでいます。

今の私の習慣は以下を記録することです：

• どのファイルを変更したか
• どんな新しい依存関係をインストールしたか
• どの環境に切り替えたか（Node のバージョンなど）

これらは一言二言で十分です。しかし、AI が問題の範囲を迅速に特定するのに役立ちます。

ステップ2：Cursor に正確なコンテキストを提供する

Cursor を使い始めた頃、私は大きな誤解をしていました。AI は何でも知っているから、適当に聞けばいいと思っていたのです。

実際には、AI はあなたのプロジェクトがどんな技術スタックを使っているか、依存関係のバージョンはいくつか、設定ファイルはどうなっているかを知りません。教えなければ、推測するしかありません。そして推測の結果は——全く役に立たない解決策です。

後に私はテクニックを学びました：正確なコンテキストを、過不足なく提供することです。

@ 記号で関連ファイルを引用する

Cursor には超便利な機能があります：@ファイル名 でファイルの内容を直接引用できます。

例えばコンポーネントのエラーに遭遇したら、こう質問します：

@UserList.jsx このコンポーネントでエラーが出ました。エラー情報は以下の通りです：
[完全なスタックトレースを貼り付け]

これで Cursor は、あなたの説明だけで推測するのではなく、完全なコンポーネントコードを見ることができます。

注意点：一度にあまり多くのファイルを引用しないでください。一度に7、8個のファイルを @ したことがありますが、AI は逆に要点をつかめなくなりました。通常、関連ファイル2-3個で十分です。

ディレクトリ全体に問題がある場合は @folder/ を使えますが、正直なところ、そのような状況は稀で、ほとんどの場合、問題は特定の数ファイルに集中しています。

関連設定ファイルを提示する

コードの問題に見えても、実際は設定の問題であるエラーもあります。

例えば TypeScript の型エラーは、tsconfig.json の設定ミスかもしれません。依存関係が見つからないのは、package.json のバージョン競合かもしれません。

私の経験：以下のようなエラーのときは、能動的に設定ファイルを AI に見せましょう：

• 型エラー → @tsconfig.json
• コンパイルエラー → @webpack.config.js または @vite.config.js
• 依存関係エラー → @package.json
• 環境問題 → Node のバージョンや OS を伝える

以前、奇妙な問題に遭遇しました。コードは間違っていないのにコンパイルが通らないのです。1時間格闘した後、package.json を Cursor に見せたら、React と React-DOM のバージョン不一致だと即座に見抜きました。

もっと早く設定ファイルを見せていれば、1時間節約できたのにと呆然としました。

必要な型定義を提供する

TypeScript を使っているなら、これは特に重要です。

AI はあなたが定義したカスタム型を知りません。User 型のエラーだと言っても、User にどんなフィールドがあるか分かりません。

解決策：型定義も一緒に見せることです。

直接 @types/user.ts とするこもできますし、関連 interface をコピーしてもいいでしょう：

interface User {
  id: string;
  name: string;
  email: string;
}

// ここでエラー：Type 'undefined' is not assignable to type 'string'
const user: User = getUserData();

これで AI は期待されるデータ構造を理解し、より正確な修正案を提示できます。

高度なテクニック：サードパーティライブラリの型（node_modules 由来など）に関連するエラーの場合、そのライブラリの型定義を見るよう AI に伝えることができます。とはいえ、AI は一般的なライブラリの型については基本的な知識を持っていることが多いです。

ステップ3：Cursor を導いて信頼できる解決策を生成させる

エラー情報を収集し、コンテキストを提供しました。次は Cursor に解決策を出させる番です。

しかしここにも落とし穴があります。多くの人は単に「直して」と言って、AI にコードを直接書き換えさせます。修正後、なぜそう修正したのか理解できず、次に似た問題に遭遇しても対処できません。

私の現在のアプローチは：まず AI に説明させ、その後コードを修正させるです。

構造化された方法で質問する

以下の2つの質問方法を比較してください：

❌ 非効率な質問：

ここでエラーが出た、直して
[エラー情報を貼り付け]

✅ 効率的な質問：

Vultr - 高性能NVMeクラウドサーバー、世界32拠点、Dockerワンクリック展開対応

価格を見る →広告

ユーザーリスト機能を実装中に型エラーが発生しました。

背景：API からユーザーデータを取得し、リストにレンダリングする
エラー情報：TypeError: Cannot read property 'map' of undefined
期待する結果：ユーザーリストが正常に表示されること

@UserList.jsx
@api/users.ts

違い分かりますか？後者は以下を明確にしています：

1. 何をしているか（どんな機能を実装中か）
2. 何が問題か（エラー情報）
3. 何を期待しているか（結果）
4. 関連コードはどこか

これで AI は完全な思考フレームワークを持ち、提示される解決策はずっと信頼できるものになります。

Cursor の異なる機能を活用する

Cursor は単なるチャットではありません。いくつかの機能があり、異なるシナリオに適しています：

1. Cmd/Ctrl + K（インライン編集）
数行のコード修正に適しています。エラーが出ている行を選択し、ショートカットキーを押して、どう直したいか AI に伝えます。

私は明らかな小さな問題（型注釈、パラメータ調整など）の修正によくこれを使います。

2. Chat（チャットウィンドウ）
複雑な問題、複数回のやり取りが必要な状況に適しています。

例えば問題の所在が不明な場合、まず「このエラーの考えられる原因は何？」と聞き、AI が提示する方向性に基づいて深掘りしていきます。

3. Composer（複数ファイル連携）
複数のファイルにまたがる問題の修正に適しています。

例えば API インターフェースを変更した場合、コンポーネント、型定義、テストファイルすべてを変更する必要があります。Composer ならこれらを一度に処理できます。

道具選びは重要です。以前は何でも Chat で済ませていましたが、単純な問題を複雑にしたり、複雑な問題を説明しきれなかったりしました。今は問題の種類に応じて機能を選び分けており、効率が格段に上がりました。

「どうやるか」の前に「なぜ」を問う

これが最も重要な点だと思います。

いきなりコードを修正させるのではなく、まず説明させましょう：

第1ラウンド：

このエラーの考えられる原因は何ですか？どのような可能性がありますか？

AI は分析してくれます。例えば：

• データのロードが完了する前にレンダリングしている
• API の戻り値の形式が正しくない
• コンポーネントの状態初期化に問題がある

第2ラウンド：

どのような解決策がありますか？それぞれのメリット・デメリットは？

AI はいくつかの案を提示します。プロジェクトの状況に合わせて最適なものを選べます。

第3ラウンド：

2番目の方法を採用したいです。実装してください。

これをおこなうメリットは：

1. 問題の根本原因を理解できる
2. 複数の解決策があることを知れる
3. AI の最初の提案を盲目的に受け入れるのではなく、能動的に選択できる

ある時パフォーマンス問題に遭遇し、AI の第一声は useMemo でした。他の案を聞くと、データ構造の最適化やレンダリングロジックの変更も提案されました。データ構造の最適化を選んだところ、根本的に解決し、useMemo を使うより遥かに効果的でした。

もし直接修正させていたら、その場しのぎの useMemo 案を受け入れていたでしょう。

ステップ4：AI の修正案を検証・テストする

AI が修正案を出し、コードが変わり、問題は解決しましたか？

祝うのはまだ早いです。

私は大きな失敗をしたことがあります。AI の修正を完全に信用し、よく見ずにコミットしたのです。リリース後、問題Aは直っていましたが、問題Bが発生していました。そのロールバック作業でひどい目に遭いました。

それ以来、習慣にしています：AI の修正は検証が必要であり、1ステップも省略してはならない。

コード変更を注意深くレビューする

AI がコードを修正したら、まず Git で diff を見ます：

git diff

一行ずつチェックします：

• 何が変わったか？
• なぜそう変えたか？
• 他の機能に影響しないか？

ある時、AI が型エラーを直すついでに、ある関数の引数の型を string から string | undefined に変えました。一見問題なさそうですが、その関数は他で十数箇所呼び出されており、それらの場所では undefined の処理をしていませんでした。

diff を注意深く見ていなければ、時限爆弾になるところでした。

私の原則：すべての変更の意図を理解すること。分からないことがあれば AI に聞きます。「なぜこう変えたの？副作用はない？」

デバッグログを追加して思考を検証する

コードが変わってエラーが表示されなくなっても、本当に直ったのか、単にエラーを隠しただけなのか確信が持てないことがあります。

そんなときは console.log を追加して重要なステップを検証します：

// AI が修正したログを追加
console.log('ユーザーデータ：', users);
console.log('データ型：', Array.isArray(users));

return users.map(user => <UserItem key={user.id} {...user} />);

そして Cursor にログ出力を分析させます：

Railway - モダンなデプロイプラットフォーム、煩わしい運用から解放、数分で公開

今すぐ始める →広告

ログを追加しました。出力は以下の通りです：
ユーザーデータ：undefined
データ型：false

データがまだロードされていないようです。修正の方向性が間違っていませんか？

AI はログに基づいて再分析し、問題はレンダリングロジックではなくデータ取得層にあることに気づくかもしれません。

これは非常に有効です。多くの場面で、問題は A にあると思いきや B にあります。ログは真の問題を素早く特定するのに役立ちます。

テストケースを実行する

プロジェクトにユニットテストがあるなら、修正後は必ず実行しましょう：

npm test

（私を含め）多くのプロジェクトに完全なテストがないことは知っています。しかし、あるなら必ず使いましょう。テストはあなたも AI も想定していない境界状況を見つけてくれます。

AI に配列処理のバグを直してもらったとき、一見問題なさそうでしたが、テストを実行すると空配列のときにエラーになりました。AI は正常系だけを考慮し、空配列を考慮していませんでした。

手動テストも重要です：

• 元のエラー発生シナリオをテストする（問題が解決したか確認）
• 正常なフローをテストする（既存機能を壊していないか確認）
• 境界条件をテストする（空値、極端な入力など）

私は簡単なテストリストを作ります：

• 元のエラーシナリオは修正されたか
• 正常データは正しく処理されるか
• 空データ/異常データは正しく処理されるか
• この関数を呼び出す他の箇所は正常か

リアルケース：AI 修正の副作用

実例をお話しします。

React コンポーネントの再レンダリング問題があり、AI はある関数を useCallback でラップすることを提案しました。確かに再レンダリングは止まりました。

しかし、ページのロードが遅くなりました。よく調べると、AI が追加した useCallback の依存配列にあるオブジェクトが含まれており、そのオブジェクトが毎回新規作成されていたため、useCallback が完全に無効化され、むしろオーバーヘッドが増えていたのです。

AI に「この依存関係おかしくない？」と聞くと、ようやく気づき、オブジェクトを useMemo でキャッシュするか、基本型を渡すよう提案してきました。

教訓：AI の案は最適解とは限らず、新たな問題を引き起こすことさえあります。同僚のコードをレビューするように、AI の修正もレビューしなければなりません。

盲信せず、過度に疑わず

これだけ検証手順があると、面倒に感じるかもしれません。

確かに検証には時間がかかります。しかし、本番環境で問題が起きて緊急ロールバックする手間に比べれば、この時間は十分に価値があります。

検証を重ねることで、AI のミスのパターンも見えてきます。よくある間違い（null/undefined 処理の欠落など）を事前に防げるようになります。

バランス点：単純な修正は素早く検証、複雑な修正は入念にテスト。変更の影響範囲に応じて検証の深さを決めましょう。

実戦ケース：完全なバグ修正フロー

理論はこれくらいにして、実際のケースを見てみましょう。

先週 Next.js プロジェクトで、突然コンパイルエラーに遭遇しました。画面は真っ白、コンソールは真っ赤です。

シナリオ説明

エラーメッセージはこうです：

Error: Element type is invalid: expected a string (for built-in components)
or a class/function (for composite components) but got: undefined.

Check the render method of `BlogPost`.
    at createFiberFromTypeAndProps (react-dom.development.js:25532:21)
    at createFiberFromElement (react-dom.development.js:25560:15)

私の第一反応：は？undefined？コンポーネントはインポートしてるはずだけど。

Step 1: 完全なエラー情報を収集

1行目だけでなく、完全なスタックトレース（約10行）をコピーしました。重要な情報は2行目以降にあります：問題は BlogPost コンポーネントの render メソッドにあります。

コンテキストも記録しました：

• react-markdown という新依存関係をインストールしたばかり
• BlogPost.tsx のインポート文を変更した

Step 2: 正確なコンテキストを提供

Cursor Chat を開き、こう質問しました：

Next.js プロジェクトでコンポーネントのインポートエラーが発生しました。

背景：react-markdown (v9.0.1) をインストールし、BlogPost コンポーネントで使用しようとした
エラー情報：[完全なスタックトレースを貼り付け]
期待する結果：Markdown コンテンツが正常にレンダリングされる

@components/BlogPost.tsx
@package.json

これで Cursor は以下を把握できます：

1. 私が使用している react-markdown のバージョン
2. BlogPost コンポーネントの完全なコード
3. プロジェクトの依存関係

Step 3: 多段階の対話で解決策を探る

第1ラウンド、こう聞きました：

Alibaba Cloud - 開発者向けクラウドの第一候補、ライトサーバー15%OFF、プロジェクトの迅速な立ち上げを支援

15%割引を入手 →広告

このエラーの考えられる原因は何ですか？

AI は3つの可能性を挙げました：

1. インポート文の間違い（名前付きインポート vs デフォルトインポート）
2. react-markdown のバージョンと React のバージョン不一致
3. コンポーネントがインストール完了前に使用された

第2ラウンド、こう言いました：

確認しましたが、依存関係はインストール済みです。インポート文の問題でしょうか？
現在の書き方：import { ReactMarkdown } from 'react-markdown'

AI は即座に問題を発見しました：

react-markdown v9 はデフォルトエクスポートを使用しており、名前付きエクスポートではありません。
こう修正すべきです：import ReactMarkdown from 'react-markdown'

Step 4: 修正の検証

AI の提案通りインポート文を修正しましたが、すぐには信じません。

まず Git diff を確認：

- import { ReactMarkdown } from 'react-markdown'
+ import ReactMarkdown from 'react-markdown'

うん、変更は最小限で、副作用はなさそうです。

プロジェクトを実行：

npm run dev

ページが正常に表示されました！

念のため、いくつかのシナリオをテストしました：

• 正常な Markdown コンテンツのレンダリング
• コードブロックを含む Markdown
• コンテンツが空の場合

すべて問題なし。これでようやく解決を確認しました。

時間比較

従来の方法：

• Google 検索 “react-markdown undefined error” → 10分
• Stack Overflow の回答を見て3つの案を試すがダメ → 20分
• react-markdown 公式ドキュメントを漁る → 15分
• 合計：45分

Cursor 支援方式：

• エラー情報とコンテキスト収集 → 2分
• 対話による問題特定 → 3分
• 修正検証 → 2分
• 合計：7分

効率は6倍以上になりました。

重要なのは、Cursor に十分なコンテキスト（バージョン番号、コード、エラー情報）を与えたことで、私が一つ一つ試すことなく、AI が直接根本原因を特定できたことです。

結論

この Cursor デバッグワークフローを振り返ります：

1. エラー収集は完全に：1行目だけでなく、スタックトレース全体が価値ある情報
2. コンテキストは正確に：@ でファイルを引用し、設定や型定義を提供する
3. 解決策は理性的に：なぜかを問い、方法を問い、受動的でなく能動的に選択する
4. 検証テストは厳格に：コードレビュー、ログ追加、テスト実行、一つも省かない

このプロセスは手順が多いように聞こえるかもしれませんが、慣れれば数分で済みます。従来の Google + Stack Overflow + 試行錯誤のループに比べれば、効率は何倍も高いです。

ただし、一つはっきりさせておきたいのは：Cursor はツールであり、魔法ではありません。

あなたの代わりに考えたり、コードロジックを理解したりはできません。それは非常に賢いアシスタントであり、問題の特定と提案をしてくれるだけです。最終的な決定を下すのはあなたです。

今の私にとって、Cursor でのデバッグは、経験豊富な同僚が隣に座っているような感覚です。問題が起きれば、「これどういうこと？」と聞けば、いくつかの可能性を分析してくれます。あとは実情に合わせて判断するだけです。

一人で悶々とドキュメントを調べるよりずっと楽です。

最後にアドバイス：自分専用のデバッグチェックリストを作りましょう。

私は今、エラーが出るとこのリストに沿って進めます：

• 完全なエラースタックトレースをコピー
• 直前の操作を記録
• @ で関連ファイルを引用（2-3個）
• 設定/型が関わるならそれも提供
• まず AI に原因分析させ、それから解決策を選ぶ
• コード変更をレビュー
• 元のシナリオ + 境界条件をテスト

この習慣をつければ、デバッグ効率は劇的に向上します。

試してみてください。あなたも頭の痛いエラーを秒殺できるようになるはずです。

8 min read · 公開日: 2026年1月22日 · 更新日: 2026年2月4日

Easton

技術開発