Cursor Agent モード実戦：3 ヶ月かけて掴んだ 10 のコツ

画面に、Agent が生成した 5 つ目のエラーファイルが並んでいる。この機能のリファクタリングは、今夜で 3 回目だ。「複雑なタスクを自動でこなす」と謳う Agent モードは、本当に助けてくれるのか、それともただ苦しめるだけなのか——疑問が消えない。

3 ヶ月前、Cursor で Agent モードのスイッチを初めて見たときは、新大陸を発見した気分だった。要件を AI に伝えれば、ファイル作成、依存インストール、コーディング、バグ修正まで自動。あとはコーヒーを飲んで結果を待つだけ——そんな理想像が頭に浮かんだ。現実は骨の折れるもので、確かに自動で動く。ただ、自動で壊すことも多い。

3 ヶ月の試行錯誤を経て、Agent との関係は「愛憎」から「阿吽の呼吸」に変わった。今は最頼もしい相棒だ——ただし、扱い方を知っている前提で。この記事では、踏んできた落とし穴と、実戦で得たノウハウをすべて共有する。

Agent モードとは：まず Chat との違いを押さえる

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

通常モードでは、AI はアドバイスしかしない。「ここに関数を追加すべき」「このバグの原因はおそらく……」と教えてくれるが、実際に手を動かすのはあなただ。Agent モードは違う。ファイル作成、コード修正、npm パッケージのインストール、コマンド実行まで、一気にこなす。

魅力的に聞こえる。だが、そこが問題でもある。新人インターンにコード修正を頼んだら、確かに直してくれた——でも確認すると、関係ないファイルまで変えている。コアロジックまで書き換えている。Agent は、そういう「勤勉だけど当てにならないインターン」だ。

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

コツ 1：タスク分割——Agent に一口で食べさせない

最大の失敗は、Agent に巨大なタスクを丸投げしたことだった。

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

それ以来、こう分割するようになった：

1. ラウンド 1：「まず src/components 配下に TypeScript の型を追加して」
2. ラウンド 2：「次に src/utils の型定義を処理して」
3. ラウンド 3：「tsconfig.json を設定して、コンパイルが通るようにして」

各ステップのあとにテストを走らせ、問題がなければ次へ進む。失敗しても、どの段階で問題が起きたかすぐ特定できる。

コツは、1 タスクの影響範囲を 3〜5 ファイル以内 に抑えること。これを超えると、Agent は注意散漫になりがちだ。インターンに一度に 20 ファイルの修正を頼む人はいない。同じ理屈だ。

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

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

Agent タスクを始める前に、必ず 2 つやる。

ステップ 1：.cursorignore を設定

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

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

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

ステップ 2：@ で正確に参照

特定ファイルを修正させたいときは、@ファイル名 で明示する。例：「@api.ts の書き方を参考に、@user.ts にもエラー処理を追加して」。こうすれば Agent はファイルを探し回らない。

一度 @ を付けずに「API ファイルを参考にして」と言ったら、2 年前の古いファイルを見つけて、その古いパターンで実装し始めた。あの惨状は忘れられない。

KiloClaw - 企業向けマネージド OpenClaw、AI エージェントのオーケストレーションとスマートルーティングを加速

今すぐ始める →広告

コツ 3：バージョン管理は命綱

血と涙で学んだ教訓だ。

金曜午後、Agent にモジュールのリファクタリングを頼んで会議に行った。戻ると 30 ファイル以上が変更されていた。「効率いいね」と思ったが、夜のテストでログイン機能が死んでいた。

問題は——何をどう変えたか、誰も覚えていなかったことだ。

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

今のワークフロー：

# 作業前にコミット
git add .
git commit -m "Agent 使用前のバックアップ"

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

# 完了後に差分確認
git diff

Agent が間違えたら、git reset --hard で巻き戻す。このコマンドに何度救われたか数え切れない。

もう 1 つのコツ：Agent には 1 回につき 1 機能モジュールだけ修正させ、終わったらすぐ commit する。ゲームでこまめにセーブするのと同じだ。

コツ 4：「停止」を覚える——Agent に穴を掘らせない

Agent には特徴がある。一度走り出すと、最後まで突き進む。途中でエラーが出ても、無理やり続けて、間違いの上に間違いを重ねていく。

最も酷かったのは、依存パッケージが見つからなかったとき、勝手に偽のファイルを作り、その偽物を前提にコードを書き続けたことだ。気づいたときには、10 ファイル以上がその誤った前提の上に構築されていた。

今は「現場監督」として動く。Agent が動き出したら、出力ログを注視する：

• 赤いエラー？ → すぐ ESC で停止
• 怪しいファイルを作成？ → 即停止
• 触るべきでないコアロジックを変更？ → 迷わず中止

停止後、状況を評価する：

• 悪くなければ、その部分を残して指示を修正して再開
• 方向性がズレていれば、git reset して指示を出し直す

止めるのを遠慮する必要はない。Agent は機械だ。中断されても不機嫌にはならない。間違ったロジックを完走させるより、早めに止めた方が後片付けはずっと楽だ。

コツ 5：Agent のコードを盲信しない

正直、Agent のコード品質はガチャのようなものだ。驚くほど良いときもあれば、ひどいときもある。

最初は「AI が賢いから大丈夫」と思っていた。テスト環境を 2 回クラッシュさせて、コードレビューは省略できないと学んだ。

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

ステップ 1：テストを走らせる

npm test

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

ステップ 2：チェックリストで確認

自分用のチェックリスト：

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

ステップ 3：手抜きがないか見る

Agent は賢いので、手抜きも覚える。「データベースクエリを最適化して」と言ったら、SQL 本体をいじらずキャッシュを足しただけ、ということもある。複雑なロジックを // TODO: 後で実装 で飛ばすこともある——ある意味、賢いが、後始末は自分でやることになる。

コツ 6：大規模プロジェクトでの正しい使い方

小規模プロジェクトなら Agent は無双する。大規模プロジェクトは別だ——数百ファイル、複雑な依存関係、複数人のコードスタイル。Agent はすぐ混乱する。

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

大規模プロジェクト向けのやり方：

戦略 1：モジュール単位で処理

プロジェクト全体を見せない。範囲を限定する：

• 「src/components/auth 配下だけ処理して」
• 「ユーザーログイン関連のコードだけ修正して」

こうすると Agent の注意が散漫にならず、無関係なコードに手を出しにくい。

戦略 2：.cursorrules で境界を引く

プロジェクトルートに .cursorrules を置き、ルールを明文化する：

🔥 需要のない製品に3ヶ月も無駄にするな！少額の予算で Adsterra を使い、SaaS の訴求を今すぐ検証 ➡️

今すぐ検証 →広告

# プロジェクトルール
- 全コンポーネントは TypeScript を使うこと
- API 呼び出しは @/lib/api に統一すること
- @/lib/core 配下のコアロジックは変更しないこと
- 新規ファイルには JSDoc コメントを付けること

インターン向けの開発ガイドラインと同じ効果だ。完全には守らなくても、参照基準にはなる。

戦略 3：独立モジュールを優先

ユーティリティ関数や汎用コンポーネントなど、結合度の低い部分が Agent 向き。壊れても影響が小さく、直せば全体に効く。

コツ 7：Agent と Composer の黄金コンビ

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

Composer は作業台、Agent は自動化スイッチ——こう理解すると分かりやすい。

シーン 1：多ファイルリファクタリング = Composer + Agent ON

複数ファイルを一括修正したいとき。「全 API 呼び出しにエラー処理とリトライを追加して」。この手の横断的な作業は Agent モードが効く。

シーン 2：単一ファイルの深い修正 = Composer + Agent OFF

1 コンポーネントの複雑なロジックを直すとき。Agent をオフにして通常 Composer を使う。AI がコード案を出し、手動で適用する。1 行ずつ制御できる。

シーン 3：ちょっとした質問 = Chat

「このエラーは何？」「このコード、どう最適化する？」——Composer すら開かず Chat で済ませる。

実用的なコツ：Composer ではいつでも Agent スイッチを切り替えられる。最初はオンで作業させ、様子がおかしくなったらオフにして主導権を取り戻す。一筋縄ではいかない。

コツ 8：絶対に踏んではいけない落とし穴

Agent を長く使ってきて、よくある落とし穴をまとめた。絶対ダメ、というわけではないが、やる前に三度考えた方がいい。

落とし穴 1：Agent に直接データベース操作をさせる

一度、横着して「テスト DB の重複レコードを消して」と頼んだ。.env に本番 DB の接続が書いてあり、本番データまで消しかけた。環境の切り替えは Agent には任せられない。

教訓：DB 操作は自分でやるか、最低でもバックアップを取る。

落とし穴 2：全ファイルのパターンを一括置換

「全ファイルの var を let に変えて」——シンプルに聞こえるが、コメント内、文字列内、サードパーティライブラリ内の var まで置換されることがある。動くが、意味不明な差分が大量に出る。

安全策：まず 1 ディレクトリで試し、問題なければ範囲を広げる。

落とし穴 3：テストのないプロジェクトで Agent を放し飛ばす

テストがない古いプロジェクトで Agent にリファクタリングさせた。見た目は綺麗だったが、本番で 3 機能が壊れた。テストがなければ、何が壊れたか気づけない。

対策：先にテストを書くか、小さく刻んで手動確認する。一気にやらない。

落とし穴 4：Agent への過度な依存

最大の落とし穴はメンタル面だ。慣れると、変数名ひとつ決めるのも Agent に聞きたくなる。Agent は効率化のツールで、思考の代わりにはならない。

コツ 9：Agent を速く回す小技

Agent が遅くてイライラするときの対処法。

小技 1：インデックス範囲を縮める

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

価格を見る →広告

前述の .cursorignore は基本。設定で Codebase インデックスの範囲も絞れる。私は src/ と lib/ だけインデックスし、ドキュメントや設定ファイルは除外している。

小技 2：チャット履歴をクリア

Agent は過去の会話も参照する。履歴が長いと、毎回振り返る分だけ遅くなる。大きなタスクが終わったら新しい会話を始める。買い物かごを空にするイメージだ。

小技 3：高速モデルに切り替える

Cursor のデフォルトは GPT-4。品質は高いが遅い。一括リネームやフォーマットなど単純なタスクなら、Claude Sonnet や GPT-3.5 に切り替えると倍速になることもある。

方針：複雑なロジックは GPT-4 で安定性重視、単純タスクは高速モデルでスピード重視。

小技 4：バッチ処理

100 ファイルにコメントを足すなら、一気に頼まず 20 ファイル × 5 回に分ける。問題の早期発見にもなるし、1 回あたりのコンテキストが軽くなり、結果的に速い。

要するに、Agent も最適化が必要だ。テーブル全体をスキャンするクエリを投げないのと同じで、負荷を減らせば走りやすくなる。

コツ 10：私の Agent 使用チェックリスト

長く使ってきて、起動前に必ず確認するリストを作った。

タスク開始前：

• ✓ Git commit 済み、ワークツリーはクリーン
• ✓ .cursorignore 設定済み
• ✓ タスク範囲（影響ファイル）が明確
• ✓ 作業ブランチが正しい（main で直接触らない）
• ✓ テスト環境が整っている（すぐ検証できる）

Agent 実行中：

• ✓ 出力ログを監視し、異常なら即停止
• ✓ ファイル変動を注視し、コアロジックの誤変更を防ぐ
• ✓ 方向性がズレたら ESC
• ✓ 複雑タスクは段階的に、欲張らない

タスク完了後：

• ✓ git diff で全差分を確認
• ✓ テスト実行（npm test）
• ✓ コードレビュー（ロジック、パフォーマンス、セキュリティ）
• ✓ ローカルテスト通過後に commit
• ✓ 不要になったチャット履歴をクリア

面倒に見えるが、飛行機の離陸前チェックと同じ。毎回やるから、大半の事故を防げる。

最重要：金曜午後に Agent で大工事をしない。週末をバグ修正に捧げたくないなら、これだけは守ってほしい。

まとめ

冒頭の深夜 2 時のシーンに戻ろう。今の私は、Agent を暴走させて 5 つのエラーファイルを量産することはない。いつ任せ、いつ止めるか。タスクの切り方、境界の引き方——これらを身につけたからだ。そして Agent は魔法ではなく、飼い慣らすべき道具だと分かっている。

3 ヶ月の試行錯誤が、この 10 のコツになった。Agent モードは、使い方を覚えれば開発効率を倍にできる——ただし、付き合い方を学ぶ必要がある。経験豊富とは言えない、エネルギーだけはあるインターンのような存在だ。方向を正しく示せば大量の作業をこなしてくれる。放置すれば、プロジェクトをめちゃくちゃにもできる。

アドバイス：落とし穴を恐れず、いつでもロールバックできる状態を保つ。小さなタスクから始めて、徐々に信頼を築く。阿吽の呼吸ができるようになれば、Agent は本当に頼もしい相棒になる。

最後に、心構えを 1 つ：Agent は能力を拡張するもので、思考を代替するものではない。問題に直面したら、まず自分で考え、Agent が必要か判断する。この姿勢を保てば、ツールに振り回されることはない。

Cursor Agent を始めるなら、まず Git を整えておいてほしい。冗談ではない——いつでも戻れる安心感が、大胆な試行を可能にしてくれる。

Agent との協業、うまくいくことを願っている。使い方のコツや落とし穴の経験があれば、コメントで共有してほしい。みんなで避ければ、一人で試行錯誤するよりずっと楽だ。