第8章 アンチパターン ── やりがちな失敗と脱出法
ツールが優秀であればあるほど、その誤用も洗練されていく。Cursorは2026年時点で最も完成度の高いAIコードエディタのひとつだが、コミュニティには「使い方を間違えると想定外のダメージを受ける」パターンが明確に蓄積されている。本章では7つのアンチパターンを解剖する。それぞれに症状・根本原因・具体的シナリオ・脱出法を添えた。思い当たる節があれば、今日から変えられる。
アンチパターン1：サイレントリバート地獄（Agent Review Tab 競合）
症状 AIが「修正しました」と報告したのに、エディタを見るとコードが元のままになっている。もしくは一時的に変わったように見えたが、数秒後に元に戻る。
根本原因 Cursorの Agent Review Tab（エージェントが変更を提案するパネル）とエディタのファイルロック機構が競合している。Agent Review Tabが開いたまま「Fix in Chat」を実行すると、2つのシステムが同じファイルへの書き込み権限を同時に主張し、後から走ったほうが前の変更を上書き・または無効化する形になる。これにより変更がサイレントに巻き戻る。
関連して、OneDriveやiCloudといったクラウド同期ツールとのレースコンディションも同様の症状を引き起こす。ローカルへの書き込みとクラウド同期の読み取りが競合し、ファイルが古い状態に戻ることがある。また、Format On Saveを有効にしている環境では、AIが保存したファイルに対してフォーマッタが走り、AIの意図した改行やインデントが変わって「別の状態」になることもある。
具体的シナリオ
1. エージェントが auth.ts のバグを発見し修正案を提示
2. Agent Review Tab に変更差分が表示されたまま
3. ユーザーが Chat で「Fix in Chat」をクリック
4. エディタ上では一瞬変更が適用されたように見える
5. Agent Review Tab が閉じるタイミングで元のファイルが復元される
6. ユーザーは「修正されたはず」と思ったまま次の作業へ脱出法 大前提として、Fix in Chat を使う前に Agent Review Tab を閉じる。これだけでほとんどのサイレントリバートは防げる。クラウド同期については、開発中フォルダをOneDrive/iCloudの同期対象から外すか、CursorプロジェクトをCloud管理外のディレクトリに置くことを検討する。Format On Saveは無効化するか、エージェントのセッション中だけオフにするプロファイルを用意しておくと安全だ。
アンチパターン2：ルール肥大化（メガ .mdc）
症状 .cursor/rules/ 以下のひとつのファイルに500行以上のルールが詰め込まれている。ルールを増やしても、むしろエージェントの品質が下がる気がする。
根本原因 「なんでもルール化すれば問題が解決する」という思い込みだ。ルールはコンテキストとしてAIに渡されるため、量が増えるほど1つ1つのルールが薄まり、重要な指示が無視されやすくなる。さらに、Cursorがすでに標準的な振る舞いとして知っていることを改めてルールに書いても、何の効果もなくコンテキストを圧迫するだけだ。
具体例
# 悪い例：肥大化したルール（一部）
- TypeScriptではanyを使わないこと
- 関数は単一責任の原則に従うこと
- 変数名はcamelCaseにすること
- コメントは英語で書くこと
- インポートはアルファベット順にすること
... (以下400行続く)上記の多くはCursorが「デフォルトで守っていること」だ。明示しても効果はなく、むしろ「プロジェクト固有の重要ルール」が埋もれる原因になる。
脱出法 ルールを見直す際の判断基準は「このルールを書かなかったとき、エージェントは実際に違反したか？」だ。違反した記憶がないルールは削除する。また、スタイルガイドのようなボリュームのあるルールは別ファイルに切り出し、ルール内で @styleguide.md を参照すること のようにコードへの参照で代替する。目標は全ルール合計500行以下。少ないルールほど、一つ一つが確実にAIに届く。
# 良い例：プロジェクト固有の本当に必要なルール（20行以内）
- このプロジェクトのデータ取得はすべてConvexクエリを使うこと（fetch/axiosは使わない）
- エラーはResult型で扱うこと（throwは使わない）
- スタイルは @src/styles/guideline.md のパターンに従うことアンチパターン3：ノープランエージェント実行
症状 「この機能を追加して」とだけ指示してAgent Modeで実行したところ、想定外のファイルが大量に変更された。ロールバックしようにも、どこまで戻ればいいかわからない。
根本原因 Cursorの Plan Mode（実行前に変更計画を提示するモード）をスキップしていることだ。大きなタスクを計画なしで渡すと、エージェントは自分なりに解釈して最短経路で実装しようとする。その「最短経路」が開発者の意図と一致しているとは限らない。
エージェントのプロジェクトセットアップ成功率は80%以上と高いが、これは明確なスコープが定義されているタスクでの数字だ。曖昧なタスクでは成功率は大きく下がる。
具体的シナリオ
指示：「認証周りをリファクタリングして」
エージェントの解釈：
- src/auth/ を全て書き直す
- 依存しているコンポーネントを6ファイル変更
- 型定義を3箇所更新
- テストファイルを2つ削除して書き直す
開発者の意図：
- auth.ts の中の冗長な条件分岐を整理したかっただけ脱出法 大きなタスクは必ず Plan Mode → 承認 → 実行 の3ステップを踏む。
flowchart LR
A[タスク定義] --> B[Plan Modeで計画提示]
B --> C{計画を確認}
C -- 問題あり --> D[計画を修正・絞り込み]
D --> B
C -- OK --> E[Agent Modeで実行]
E --> F[差分を確認してApprove]「まず計画だけ見せてください。実装はまだしないでください」という一言がセーフティネットになる。計画を見て「それは広すぎる」と気づけば、スコープを絞ってから渡せる。
アンチパターン4：ビジネスロジックのAI丸投げ
症状 支払い処理や権限チェックをAIに実装させてマージしたら、特定条件でバグが発生した。コードを見ると「それっぽく書いてあるのに穴がある」状態だった。
根本原因 「見た目が正しければ正しい」という誤解だ。AIの生成コードは構文的に正確で、変数名も適切で、コメントも丁寧なことが多い。しかしビジネスロジックの微妙な条件分岐、特に「このケースでは何もしない」「ここは失敗させてはいけない」という暗黙の要件は、指示しない限りAIには伝わらない。
具体的シナリオ
// AIが生成したStripe決済処理（一見正しそう）
async function processPayment(amount: number, customerId: string) {
const paymentIntent = await stripe.paymentIntents.create({
amount,
currency: 'jpy',
customer: customerId,
});
return paymentIntent;
}
// 何が問題か？
// - カード拒否時のエラーハンドリングがない
// - 金額が0円や負の値のバリデーションがない
// - 冪等性キー（idempotencyKey）がないので二重課金リスクがある
// - Webhookとの整合性が考慮されていない脱出法 ビジネスロジックの実装をAIに任せること自体は問題ない。問題はレビューなしにマージすることだ。支払い・権限・バリデーションの3領域については、必ず人間がコードを読んで「何が起きていないか」を確認する。「このコードでエラーケースはすべてカバーされていますか？」という質問をAI自身に投げかけるのも有効だ。AIは自分の見落としを案外正直に教えてくれる。
アンチパターン5：プレミアムリクエストの爆食い
症状 月末になるとCursorのプレミアムリクエスト上限に頻繁に達するようになった。コーディングの生産性は上がっているはずなのに、コスト感が合わない。
根本原因 Agent Modeを軽いタスクにも使っていることだ。Agent Modeはファイルシステムへのアクセスやツール呼び出しを伴うため、単純な補完や質問と比べてリクエストのコストが高い。ファイルを1行変えたいだけなのにエージェントを起動するのは、タクシーで100メートル移動するようなものだ。
タスクの重さとモードの対応：
| タスク例 | 適切なモード |
|---|---|
| 変数名の補完、短いコードの生成 | Tab補完 |
| 特定の関数の説明、簡単な質問 | Chat（通常） |
| 複数ファイルにまたがる変更 | Composer |
| ファイル新規作成・テスト実行・ツール使用 | Agent Mode |
脱出法 Agent Modeは「ツールを使う必要があるタスク」だけに限定する。ファイル検索、ターミナル実行、複数ファイルの同時編集が不要なら、Composerか通常のChatで十分なことが多い。また、試行錯誤中はChatでプロトタイプを作ってから、固まったらAgentで実装、という2段階アプローチも効果的だ。
アンチパターン6：長時間セッションのコード乖離
症状 「この関数の引数はnullableなはずです」とAIが言うが、実際のコードを見るとすでに修正済みで非nullableになっている。AIが古いコードの状態を「現在の状態」として認識し続けている。
根本原因 2時間以上のセッションを継続すると、AIが持つコードベースの認識と実際のファイルの状態が乖離し始める。これはCursorの設計上の制約に近い問題で、エージェントがセッション中に「今のコードはこうなっているはず」というモデルを持ち続けるが、その更新が追いつかなくなる。
脱出法 2時間を目安にセッションをリセットし、引き継ぎ情報を summary.md にまとめる（第7章鉄則6を参照）。セッション中にリファクタリングが発生した場合は特にリスクが高い。大きな変更の後は「今のファイル構造を確認してください」と一度Cursorに現状把握をさせてから次のタスクを渡すと、認識のズレを早期発見できる。
# セッション乖離を検知するサイン
- AIが「そのファイルはまだ存在しません」と言うが実際は存在する
- AIが古い関数名や変数名を使い続ける
- AIが「このエラーはまだ修正されていません」と言うが修正済み
→ これらを見たら即座にセッションをリフレッシュするアンチパターン7：@codebase 頼みの曖昧指示
症状 @codebase を使って「これを直して」「テストを追加して」と指示したが、全く期待と違う変更が返ってきた。何度やり直しても意図が伝わらない。
根本原因 @codebase はCursorにコードベース全体を探索させる強力な機能だが、「探索させるべき場面」と「コンテキストを明示的に指定すべき場面」を混同している。曖昧な指示は「それっぽい何か」を返すことはできるが、開発者の意図した「それ」を返す保証はない。
Before / After
# Before（曖昧）
@codebase auth.tsにテストを追加して
# After（具体的）
auth.ts の logout 関数のエッジケース（トークンが既に失効している場合）を
カバーするテストケースを1つ書いてください。
パターンは __tests__/auth.test.ts の既存テストに合わせ、
モックは使わずSupabaseのテスト用クライアントを使用すること。情報量の違いは明確だ。「何を」「どのファイルに」「どのパターンで」「何を避けて」という4点を明示するだけで、AIの出力は劇的に収束する。
脱出法 @codebase は「AIにどこを見ればいいか探索させたい」ときだけ使う。「ここを見てほしい」と明確にわかっているなら @auth.ts @__tests__/auth.test.ts のようにファイルを直接指定する方が正確だ。参照先・制約・パターン・除外事項の4要素を含めた指示が、最も少ないやり取りで意図通りの結果を得るための近道だ。
アンチパターン分類マップ
7つのアンチパターンをどの軸の問題なのかで整理すると、対策の優先順位が見えてくる。
quadrantChart
title アンチパターン分類マップ
x-axis 個人の習慣 --> 環境・設定
y-axis 低リスク --> 高リスク
quadrant-1 環境設定で防げる高リスク
quadrant-2 習慣改善が必要な高リスク
quadrant-3 習慣で改善できる低リスク
quadrant-4 設定で改善できる低リスク
AP1 サイレントリバート: [0.8, 0.75]
AP2 ルール肥大化: [0.3, 0.3]
AP3 ノープラン実行: [0.2, 0.65]
AP4 ビジネスロジック丸投げ: [0.25, 0.9]
AP5 リクエスト爆食い: [0.35, 0.4]
AP6 セッション乖離: [0.55, 0.55]
AP7 曖昧指示: [0.15, 0.45]右上の「環境設定で防げる高リスク」には AP1（サイレントリバート）が位置する。これはCursorの設定やクラウド同期設定を変えるだけで対処できる。左上の「習慣改善が必要な高リスク」には AP4（ビジネスロジック丸投げ）と AP3（ノープラン実行）が並ぶ。この2つは意識を変えないと繰り返す。
まとめ：失敗パターンを知ることがAgentic Engineeringの入口
アンチパターンはツールの欠点の一覧ではない。「どこでどう使えばいいか」という使用設計の問題だ。サイレントリバートを知っていれば操作順序を変えられる。ルール肥大化を知っていれば削ることをためらわなくなる。ビジネスロジックの危うさを知っていればレビューを省かなくなる。
Vibe Coding の時代が終わり、Agentic Engineering が始まった今、AIとの付き合い方を「設計する」ことが開発者の新しいコアスキルになっている。失敗パターンを言語化し、チームで共有し、ルールや仕組みに落とし込む。それが、ツールを使いこなすということの意味だ。