Cursor Agent モード実戦ガイド：私が3ヶ月かかって掴んだ10の極意

深夜2時、Agent が生成した5つ目のエラーファイルを見つめながら、私は深いため息をつきました。今夜だけで、この機能のリファクタリングをやり直すのは3回目です。「複雑なタスクを自動化する」という触れ込みの Agent モードは、私を助けに来たのか、それとも苦しめに来たのか、疑いたくもなります。

3ヶ月前、初めて Cursor で Agent モードのスイッチを見つけた時、私は新大陸を発見したかのように興奮しました。要望を伝えれば、自動でファイルを作り、依存関係をインストールし、コードを書き、バグを直してくれる。私はコーヒーを飲みながら待つだけ——そんな理想を描いていました。しかし現実は非情です。確かに自動で働いてくれますが、しばしば自動で事態を悪化させるのです。

しかし正直に言うと、3ヶ月の試行錯誤を経て、私と Agent の関係は「愛憎劇」から「阿吽の呼吸」へと変わりました。今では私にとって欠かせない右腕です——ただし、それは「操縦法」を知っていればの話です。この記事では、私が深夜のディスプレイの前で呆然としないために学んだ失敗と経験を、すべてシェアします。

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

15%割引を入手 →広告

Agent モードとは：まずは Chat との違いを理解する

Cursor の Composer を開くと、右上に “Agent” スイッチがあります。これを甘く見てはいけません。オンにすると、AI に手足が生えたような状態になります。

通常モード（Chat）では、AI はアドバイスしかしません。「ここに関数を追加すべきです」「このバグの原因は…」と教えてくれますが、実際に手を動かすのはあなたです。一方 Agent モードは、自分で手を動かします。ファイルの作成、コードの修正、npm パッケージのインストール、コマンド実行まで、一気にやってのけます。

魅力的ですよね？でも、そこが問題でもあります。新人のインターンにコード修正を頼んだら、確かに修正してくれたけど、確認したら「えっ、なんで関係ないファイルまで変えてるの？」「核心ロジックが変わってるじゃん！」という状況を想像してみてください。Agent は、そういう「勤勉だけど危なっかしいインターン」なのです。

私の現在の使い分けはこうです：小さなタスクは Chat（「このコードを解説して」）、複数ファイル操作は Agent（「全コンポーネントに TypeScript の型を付けて」）。重要なのは、いつ任せて、いつ監視するかを知ることです。

極意1：タスク分割のアート——Agent に一口で食べさせない

私が犯した最大のミスは、Agent に巨大なタスクを丸投げしたことでした。

ある時、古いプロジェクトのリファクタリングをしようと思い、Agent にこう言いました。「このプロジェクトを JavaScript から TypeScript に移行して、ついでにパフォーマンスも最適化して、ログイン機能も追加して」。結果は？ 狂ったようにファイルを作り始め、半日いじくり回した挙句、プロジェクトは起動すらしなくなりました。コードを戻すのに丸一日かかりました。

それ以来、私は学びました。今はこう分割します：

1. ラウンド1：「まず src/components ディレクトリのファイルに型定義を追加して」
2. ラウンド2：「次に src/utils の型定義を処理して」
3. ラウンド3：「tsconfig.json を設定して、コンパイルが通るようにして」

各ステップが終わるたびにテストを走らせ、問題がないことを確認してから次に進みます。これなら失敗しても、どの段階で問題が起きたかすぐに特定できます。

コツ：タスクを分割する際は、1回のタスクの影響範囲を 3〜5ファイル以内 に抑えること。これを超えると、Agent は注意散漫になりがちです。インターンに一度に20ファイルの修正を頼んだりしませんよね？同じ理屈です。

極意2：コンテキスト管理——見るべき場所を教える

Agent には欠点があります。どのファイルが重要で、どれを無視すべきか判断できません。プロジェクトには数千のファイルがあり、node_modules が大半を占めています。Agent がこれらをすべてスキャンしようとすると、遅いだけでなく、ノイズに邪魔されて精度も落ちます。

私は Agent を使う前に、必ず2つのことをしています。

ステップ1：.cursorignore の設定

Cursor に「インデックスしなくていいディレクトリ」を教えます。私のテンプレートはこれです：

node_modules/
dist/
build/
.next/
.git/
*.log
coverage/

これを追加するだけで、Agent の応答速度が 30% 以上向上します。1日の積み重ねでかなりの時間節約になります。

ステップ2：@ メンションで正確に参照

特定のファイルを修正させたい時は、@ファイル名 で明確に指示します。例えば：「@user.ts にも @api.ts を参考にしてエラー処理を追加して」。これで Agent は迷子になりません。

一度 @ を付けずに「API ファイルを参考にして」と言ったら、2年前の古いファイルを見つけてきて、その古いパターンで実装し始めたことがありました。悲劇です。

極意3：バージョン管理は命綱

これは血と涙で学んだ教訓です。

金曜日の午後、Agent にモジュールのリファクタリングを頼んで会議に行きました。戻ってくると、Agent は30以上のファイルを変更していました。「お、仕事早いね」と思いましたが、夜にテストするとログイン機能が死んでいました。

問題は――どのファイルをどう変えたのか誰も覚えていないことです。

その夜、3時間かけてファイルを1つずつ比較して原因を特定しました。それ以来、私は鉄の掟を作りました：Agent を使う前は必ず commit する。

今の私のワークフロー：

# 作業前にコミット
git add .
git commit -m "Backup before using Agent"

# 安心して Agent に作業させる

# 完了後に差分確認
git diff

もし Agent が間違えたら、迷わず git reset --hard で巻き戻します。このコマンドに何度救われたことか。

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

今すぐ始める →広告

もう一つのコツ：Agent には1回につき1つの機能モジュールだけ修正させ、終わったら即コミットする。ゲームでこまめにセーブするのと同じで、多すぎて困ることはありません。

極意4：「停止」を覚える——傷口を広げさせない

Agent には「一度走り出したら止まらない」という特徴があります。途中でエラーが出ても、強引に進めようとして、間違いの上塗りを重ねていきます。

一番酷かったのは、ある依存パッケージが見つからなかった時、勝手に「偽の依存ファイル」を自作して、その偽物に基づいてコードを書き続けたことです。気づいた時には、その偽の前提の上に10以上のファイルが構築されていました。

今は私は「現場監督」です。Agent が動き出したら、ログを注視します：

• 赤いエラーが出た？ →即座に ESC キーで停止
• 怪しいファイルを作り始めた？ →即停止
• 触るべきでないコアロジックを変えた？ →迷わず中止

停止後、状況を評価します：

• 悪くないなら、その部分だけ残して指示を修正して再開
• ダメなら git reset して、指示を出し直す

止めるのを遠慮する必要はありません。Agent は機械ですから、中断されても文句は言いません。間違ったロジックを完走されるより、止める方が後の修正作業はずっと楽です。

極意5：Agent のコードを盲信するな

正直なところ、Agent のコード品質は「ガチャ」のようなものです。素晴らしい時もあれば、驚くほど酷い時もあります。

最初は「AI は賢いから大丈夫だろう」と思っていました。しかし本番環境を2回クラッシュさせて学びました。コードレビューは省略不可です。

Agent がタスクを完了したら、必ず以下を実行します：

ステップ1：テスト実行

npm test

基本ですが、忘れがちです。Agent はコードを書くだけで、テストまでは（指示しない限り）通してくれません。

ステップ2：チェックリスト確認
自分用のチェックリストを作っています：

• ✓ ロジックの正当性：期待通り動くか
• ✓ 境界値：空値や異常系の処理
• ✓ パフォーマンス：明らかなボトルネックはないか
• ✓ スタイル：プロジェクト規約に沿っているか
• ✓ セキュリティ：SQLインジェクション等のリスク

ステップ3：手抜きチェック
Agent は賢いので、手抜きも覚えます。「データベースクエリを最適化して」と言ったら、クエリ本体をいじらずにキャッシュを追加しただけで終わらせたことがありました。また、複雑なロジックを // TODO: 誰か実装してね でスキップすることもあります（ある意味賢いですが）。ちゃんと中身を見ましょう。

極意6：大規模プロジェクトでの正しい作法

小規模プロジェクトなら Agent は無双しますが、大規模プロジェクト（数百ファイル、複雑な依存関係）では途端にポンコツになります。

私の Next.js プロジェクト（コンポーネント200個以上）で、Agent に「全コンポーネントのパフォーマンス最適化」を頼んだら、ファイル検索だけで10分かかり、結局どうでもいい箇所を数行変えただけでした。

大規模プロジェクト用の攻略法はこれです：

戦略1：モジュール単位で扱う
プロジェクト全体を見せないこと。範囲を限定します。

• 「src/components/auth ディレクトリ配下のみ処理して」
• 「ユーザーログインに関連するコードのみ修正して」

こうすると Agent の注意力が散漫にならず、余計なファイルを壊しません。

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

価格を見る →広告

戦略2：.cursorrules で境界線を引く
ルートディレクトリに .cursorrules を置き、ルールを明文化します：

# プロジェクトルール
- 全コンポーネントは TypeScript を使用すること
- API 呼び出しは @/lib/api に統一すること
- @/lib/core ディレクトリのコアロジックは変更禁止
- 新規ファイルには JSDoc コメントを付与すること

これがあれば、Agent は暴走しにくくなります。「インターン用開発ガイドライン」と同じ効果です。

戦略3：独立モジュールを優先
ユーティリティ関数や汎用コンポーネントなど、結合度が低い部分は Agent の得意分野です。壊れても影響範囲が限定的だからです。

極意7：Agent と Composer の黄金コンビ

Agent と Composer の関係を誤解している人が多いですが、これらは二者択一ではなく、組み合わせて使うものです。

簡単に言えば、Composer は作業台、Agent は自動化スイッチです。

私の使い分け：

シーン1：多ファイルリファクタリング = Composer + Agent ON
複数のファイルを一括修正したい時。「全 API 呼び出しにエラー処理とリトライを追加して」。この場合、Agent モードが威力を発揮します。

シーン2：単一ファイルの深い修正 = Composer + Agent OFF
1つのコンポーネントの複雑なロジックを直す時。Agent をオフにして通常の Composer を使います。AI はコード案を提示し、私が手動で適用（Accept）します。これなら1行1行コントロールできます。

シーン3：ちょっと質問 = Chat
「このエラー何？」とか「どう書くのがいい？」といった質問は、Composer すら開かず Chat で済ませます。

コツ：Composer ではいつでも Agent スイッチを切り替えられます。最初はオンで作業させ、雲行きが怪しくなったらオフにして主導権を取り戻す。臨機応変にいきましょう。

極意8：絶対に避けるべき地雷

地雷1：Agent に直接データベース操作をさせる
横着して「テストDBの重複データを消して」と頼んだら、本番DBの接続設定（.env）を読み込んで本番データを消しかけたことがあります。
教訓：DB操作は自分でやるか、バックアップ必須。

地雷2：全ファイルの一括パターン置換
「全ファイルの var を let に変えて」。簡単そうですが、コメントの中、文字列の中、ライブラリの中の var まで置換される可能性があります。
対策：まずは1ディレクトリで試し、確認してから広げる。

地雷3：テストのないプロジェクトで Agent を放し飼い
テストコードがない状態で Agent にリファクタリングさせると、何が壊れたか気づけません。
対策：テストを書くか、少しずつ修正して手動確認する。

地雷4：Agent 依存症
最大の落とし穴はメンタルです。慣れると、変数名ひとつ決めるのも Agent に聞きたくなります。しかし、Agent はあくまで道具であり、思考の代行者ではありません。

極意9：Agent を高速化する小技

Agent が遅くてイライラする時の対処法です。

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

15%割引を入手 →広告

小技1：インデックス範囲の縮小
前述の .cursorignore は必須。さらに設定で Codebase Index の範囲を絞れます。私は src/ と lib/ だけインデックスさせ、ドキュメント等は除外しています。

小技2：チャット履歴のクリア
履歴が長くなると、Agent は毎回それを読み直すので遅くなります。大きなタスクが終わったら、「New Chat」で履歴を一掃しましょう。買い物かごを空にするようなものです。

小技3：高速モデルへの切り替え
デフォルトは GPT-4 ですが、高品質な分遅いです。単純なタスク（リネームやフォーマット）なら、Claude Sonnet や GPT-3.5 系に切り替えると倍速で終わります。

小技4：ミニバッチ処理
100ファイルの修正を頼むなら、20ファイルずつ5回に分けます。エラーも早期発見でき、コンテキストも軽くなるので結果的に早いです。

極意10：私の Agent 使用チェックリスト

今では、Agent を起動する前に必ずこのリストを脳内でチェックしています。

開始前：

• ✓ Git コミット済み、ワークツリーはクリーンか？
• ✓ .cursorignore 設定済みか？
• ✓ タスク範囲（影響ファイル）は明確か？
• ✓ 作業ブランチは正しいか？（main で直でやるな）
• ✓ テスト環境はあるか？

実行中：

• ✓ 出力ログを監視し、異常なら即停止
• ✓ ファイル変動を注視し、コアロジック誤爆を防ぐ
• ✓ 方向性がズレたら ESC

完了後：

• ✓ git diff で全差分チェック
• ✓ npm test 実行
• ✓ コードレビュー（ロジック、セキュリティ）
• ✓ ローカル動作確認後にコミット
• ✓ チャット履歴クリア

面倒に見えますが、飛行機の離陸前チェックと同じで、事故を防ぐための儀式です。

そして最も重要な教訓：金曜日の午後に Agent で大工事をするな。週末をバグ修正に捧げたくないならね。

結論

冒頭の深夜2時の話に戻りましょう。今の私は、Agent を暴走させてエラーの山を作ることはありません。いつ手放し、いつ止めるか。どうタスクを切り分け、境界線を引くかを知っているからです。

3ヶ月間の教訓を一言で言えば、**「Agent は魔法ではなく、飼い慣らすべき道具」**です。方向性を正しく示せば強力な助っ人になりますが、放置すれば破壊神にもなります。

まずは小さなタスクから始め、信頼関係を築いてください。そして忘れないでください、Agent はあなたの能力を拡張するものであり、あなたの思考を代替するものではありません。

最後に、もしこれから Agent を使い始めるなら、まずは Git の設定から。「いつでも戻れる」という安心感が、あなたを大胆にしてくれるはずです。

7 min read · 公開日: 2026年1月14日 · 更新日: 2026年2月4日

Easton

技術開発