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

コンソールがまた真っ赤になる。

TypeError: Cannot read property 'map' of undefined——今夜 3 度目。このエラーを見たら、コピーして Google、Stack Overflow……目を閉じてもできる手順。でも 30 分経っても、5〜6 案試しても、問題はそのまま。

Cursor を使い始めて「AI が Bug を直してくれる！」と思った。実際は違った。エラーをそのまま投げると、的外れな案か、A を直して B を壊す提案ばかり。

試行錯誤の末に固めた Cursor Debug ワークフローで、初めて分かった。ツールが悪いのではなく、使い方が足りなかった。

この記事では、その 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 行）をコピーする。

エラー種別を識別し、混ぜない

種別によって対処が変わります。大まかに 4 類型に分けています：

1. 構文エラー：括弧の閉じ忘れ、キーワードの typo など。Cursor はすぐ気づく。
2. ランタイムエラー：undefined is not a function など。データかロジックの問題。
3. 型エラー（TypeScript）：型不一致。関連する型定義も一緒に見せる。
4. 依存／環境エラー：Module not found など。package.json や Node バージョンを確認。

Cursor に聞く前に種別を伝えます。「これは TypeScript の型エラーで……」と一言あるだけで、AI の思考方向が定まります。

コンテキストを記録する：何をした直後に出たか

あるとき設定ファイルを 1 つ変えたら、プロジェクト全体が動かなくなりました。エラー情報だけ渡すと、コード修正を提案。半日直してもダメ。

「webpack.config.js の entry を変えた」と補足したら、Cursor はすぐパスの typo と判断。

教訓：直前の操作を必ず伝える。「問題ないはず」でも省略しない。バグはそこに潜むことが多い。

今は次を 1〜2 文で記録しています：

• 変更したファイル
• 入れた依存
• 切り替えた環境（Node バージョンなど）

AI が調査範囲をすぐ絞れます。

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

Cursor 初期の頃、「AI は何でも知っている」と思い、適当に聞いていました。

実際には、技術スタック、依存バージョン、設定の中身は AI には見えません。教えなければ推測するしかなく、結果はプロジェクトに合わない案ばかり。

学んだのは、過不足なく、必要な分だけコンテキストを渡すこと。

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

Cursor の @ファイル名 で内容を直接参照できます。

コンポーネントでエラーが出たとき：

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

15%割引を入手 →広告

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

説明だけで推測させるのではなく、コード全体を見せられます。

注意：一度に 7〜8 ファイル @ したことがありますが、AI が要点を掴めなくなりました。2〜3 ファイルが目安。ディレクトリ全体なら @folder/ も使えますが、問題は特定ファイルに集中していることがほとんどです。

関連する設定ファイルを見せる

コードの問題に見えて、実は設定の問題——よくあります。

TypeScript の型エラーは tsconfig.json、依存が見つからないのは package.json のバージョン競合、というパターン。

経験則：次のときは能動的に設定を添付します。

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

コードは正しいのにコンパイルが通らない——1 時間格闘した末、package.json を見せたら React と React-DOM のバージョン不一致と即答。早く見せていれば 1 時間節約できた。

必要な型定義を渡す

TypeScript なら特に重要。AI はカスタム型の中身を知りません。

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();

期待するデータ構造が分かれば、より正確な修正案が返ってきます。

上級テクニック：サードパーティの型（node_modules 由来）が絡む場合、その型定義を見るよう指示できます。常用ライブラリなら AI は概ね把握しています。

ステップ 3：Cursor に信頼できる解決策を出させる

エラー収集とコンテキスト提供が終わったら、解決策の段階。

ここで多くの人が「直して」と言い、AI がいきなりコードを書き換えます。なぜそう直したか分からず、次も同じ壁にぶつかる。

今は 先に説明させ、後から修正させる 流れにしています。

構造化して質問する

2 つの聞き方を比べてください。

❌ 非効率：

ここでエラー、直して
[エラー情報]

✅ 効率的：

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

背景：API からユーザーデータを取得してリスト表示
エラー：TypeError: Cannot read property 'map' of undefined
期待：ユーザーリストが正常に表示されること

@UserList.jsx
@api/users.ts

後者は (1) 何をしているか (2) 何が起きたか (3) 期待する結果 (4) 関連コードの所在——思考の枠組みが揃い、案の精度が上がります。

Cursor の機能を使い分ける

Cursor は Chat だけではありません。

1. Cmd/Ctrl + K（インライン編集）
数行の修正向け。エラー行を選択してショートカット、修正指示。型注釈や引数調整の小さな修正に。

2. Chat（チャット）
複数ターンが必要な複雑な問題向け。「考えられる原因は？」から始め、分析に沿って深掘り。

3. Composer（複数ファイル連携）
API 変更に伴うコンポーネント・型・テストの一括修正向け。

道具選びが効率を左右します。以前は何でも Chat にしていましたが、単純な問題を複雑に、複雑な問題を説明しきれない——今は種別で選び分けています。

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

最重要ポイント。

第 1 ラウンド：

このエラーの考えられる原因は？可能性をいくつか挙げて。

AI の分析例：

• データロード前にレンダリングしている
• API の戻り値形式が想定と違う
• コンポーネント状態の初期化ミス

第 2 ラウンド：

解決策はいくつある？それぞれの長所・短所は？

第 3 ラウンド：

2 番目の案で実装して。

メリット：(1) 根本原因を理解できる (2) 複数案があると分かる (3) 最初の案を盲信せず能動的に選べる。

パフォーマンス問題で AI の第一声が useMemo だったことがあります。他案を聞くとデータ構造の最適化やレンダリングロジック変更も提示。後者を選び、根本解決——useMemo だけでは対症療法でした。

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

AI が直し、コードが変わった——もう終わり？

早い。

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

今すぐ始める →広告

大きな失敗をしたことがあります。AI の変更を信用し、よく見ずにコミット。本番で A は直ったが B が壊れ、ロールバックで大変な目に。

それ以来、AI の変更は 1 ステップも省略せず検証しています。

コード変更を丁寧にレビューする

AI が直したら、まず Git で diff：

git diff

行ごとに：

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

型エラー修正のついでに、関数引数を string から string | undefined に変えられたことがあります。一見問題なさそうでも、十数箇所の呼び出し元で undefined 未処理——diff を見ていなければ時限爆弾でした。

原則：各行の意図を理解する。分からなければ「なぜこう変えた？副作用は？」と即聞く。

console.log で意図を検証する

エラー表示が消えても、本当に直ったのか、隠しただけか——確信が持てないことがあります。

重要ステップに console.log を入れます：

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

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

Cursor にログ出力を見せます：

ログを入れました。出力はこうです：
ユーザーデータ：undefined
データ型：false

データがまだ来ていない。修正の方向が間違っていませんか？

AI はログから再分析し、レンダリングではなくデータ取得層が原因と気づくことが多い。

非常に有効。問題は A にあると思いきや B にある——ログが真因を早く示します。

テストを実行する

ユニットテストがあれば、修正後は必ず：

npm test

テストがなくても（以前の自分のプロジェクトもそうでした）、あれば必ず使う。想定外の境界条件を拾ってくれます。

配列処理の Bug を直したとき、見た目は問題なし。テスト実行で空配列時にクラッシュ——AI は正常系だけ考え、空配列を見落としていました。

手動テストも重要：

• 元のエラー再現（解決確認）
• 正常フロー（既存機能の破壊なし）
• 境界条件（空値・極端入力）

チェックリスト：

• 元シナリオは直ったか
• 正常データは処理できるか
• 空／異常データは適切に扱えるか
• 他の呼び出し元は問題ないか

実例：AI 修正の副作用

React コンポーネントの再レンダリング問題。AI は関数を useCallback でラップする案。再レンダリングは止まった。

しかしページ読み込みが遅くなった。調べると、useCallback の依存配列に毎回新規作成されるオブジェクトがあり、useCallback が無効化——オーバーヘッドだけ増えていた。

「この依存、おかしくない？」と聞くと、オブジェクトを useMemo でキャッシュするか基本型を渡す案に切り替わった。

教訓：AI の案は最適とは限らず、新たな問題を生むことも。同僚の PR と同じ厳しさでレビューする。

盲信せず、過疑いもしない

手順が多く感じるかもしれません。本番障害の緊急ロールバックに比べれば、検証時間は安い。

検証を重ねると、AI のよくあるミス（null / undefined 処理の漏れなど）が見え、事前に防げます。

バランス：小修正は軽く、大修正は入念に。影響範囲で検証の深さを決める。

実戦ケース：Bug 修正の一連の流れ

理論はここまで。実際のケースを見ましょう。

先週、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 の import 文を変更

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

Cursor Chat で：

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

価格を見る →広告

Next.js プロジェクトでコンポーネント import エラー。

背景：react-markdown (v9.0.1) を入れ、BlogPost で使用しようとした
エラー：[完全なスタック]
期待：Markdown コンテンツが正常にレンダリングされる

@components/BlogPost.tsx
@package.json

Cursor は (1) react-markdown のバージョン (2) BlogPost のコード (3) 依存関係を把握できます。

Step 3：多ターンで解決策を探る

第 1 ラウンド：

このエラーの考えられる原因は？

AI の 3 案：

1. import 文の誤り（named vs default）
2. react-markdown と React のバージョン不一致
3. インストール完了前に使用

第 2 ラウンド：

依存は入れ終わっています。import の問題でしょうか？
今の書き方：import { ReactMarkdown } from 'react-markdown'

AI の回答：

react-markdown v9 は default export です。named export ではありません。
修正：import ReactMarkdown from 'react-markdown'

Step 4：修正を検証

提案通り import を変更——すぐには信じない。

Git diff：

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

変更は最小限。副作用はなさそう。

npm run dev

ページ表示 OK。念のため追加テスト：

• 通常の Markdown
• コードブロック付き Markdown
• 空コンテンツ

すべて問題なし。解決確認。

時間比較

従来方式：

• Google「react-markdown undefined error」→ 10 分
• Stack Overflow で 3 案試すも失敗 → 20 分
• 公式ドキュメント → 15 分
• 合計：45 分

Cursor 支援：

• エラー＋コンテキスト収集 → 2 分
• 多ターンで特定 → 3 分
• 検証 → 2 分
• 合計：7 分

6 倍以上の効率。

鍵は、バージョン・コード・エラー情報という十分なコンテキストを渡し、AI が根本原因を直接特定できたこと。自分で一つずつ試すループを回避できました。

まとめ

Cursor Debug ワークフローの 4 点：

1. エラー収集は完全に——1 行目よりスタック全体
2. コンテキストは正確に——@ でファイル、設定と型定義も
3. 解決策は理性的に——先に「なぜ」、能動的に選ぶ
4. 検証は厳格に——diff、ログ、テスト、省略しない

手順は多く聞こえますが、慣れれば数分。Google + Stack Overflow + 試行錯誤より、効率は段違い。

ただし一点ははっきり：Cursor はツールであって魔法ではない。

代わりに考えたり、ロジックを理解したりはしません。賢いアシスタントが、素早く原因候補を出してくれる——最終判断はあなた。

今の感覚は、経験豊富な同僚が隣にいるようなもの。「これどういうこと？」と聞けば、いくつかの可能性を整理してくれる。あとは状況に合わせて選ぶだけ。

一人でドキュメントを漁るより、ずっと楽。

最後のアドバイス：自分用の Debug チェックリストを作る。

エラーが出たら、この順で進めています：

• 完全なスタックトレースをコピー
• 直前の操作を記録
• @ で関連ファイル（2〜3 個）
• 設定／型が関係すれば添付
• 先に原因分析、それから案を選ぶ
• コード変更をレビュー
• 元シナリオ＋境界条件をテスト

この習慣が、Debug 効率を一気に上げます。

試してみてください。頭の痛いエラーも、手早く片付けられるはずです。