コーディングエージェントは、ソフトウェア開発のあり方を変えつつあります。

モデルは今や数時間にわたって連続実行でき、大規模な複数ファイルのリファクタリングを完了し、テストが通るまで反復できるようになりました。しかし、エージェントの性能を最大限に引き出すには、その仕組みを理解し、新しい使い方やパターンを身につける必要があります。

このガイドでは、Cursor のエージェントを活用するためのテクニックを解説します。エージェントによるコーディングが初めての方はもちろん、Cursor を私たちのチームがどのように使っているのか知りたい方に向けて、エージェントを使ったコーディングのベストプラクティスを一通り紹介します。

#エージェントハーネスを理解する

エージェントハーネスは、次の 3 つのコンポーネントで構成されています。

1. Instructions: エージェントの挙動を導くシステムプロンプトとルール
2. Tools: ファイル編集、コードベース検索、ターミナル実行など
3. User messages: 作業内容を指示するあなたのプロンプトとフォローアップ

Cursor のエージェントハーネスは、サポートしている各モデルに対してこれらのコンポーネントを連携・制御します。内部評価と外部ベンチマークに基づき、あらゆる最先端モデルごとに instructions をチューニングし、tools を最適化 しています。

ハーネスが重要なのは、同じプロンプトでもモデルごとに応答が異なるためです。シェル中心のワークフローで訓練されたモデルは、専用の検索ツールよりも grep を好むかもしれません。別のモデルは、編集後に linter ツールを呼び出すための明示的な指示を必要とすることもあります。Cursor のエージェントがこうした部分を代わりに処理するため、新しいモデルがリリースされても、あなたはソフトウェア開発に集中できます。

#まずはプランから始める

最もインパクトの大きい改善は、コーディングを始める前にプランを立てることです。

シカゴ大学の調査によると、経験豊富な開発者ほどコードを生成する前にプランを立てる傾向があることがわかりました。あらかじめプランニングすることで、何を作ろうとしているのかが明確になり、エージェントにとって取り組むべき具体的な目標を与えられます。

#Plan Mode を使う

エージェント入力欄で Shift+Tab を押すと、Plan Mode を切り替えられます。すぐにコードを書き始める代わりに、エージェントは次のことを行います：

1. コードベースを調査して関連するファイルを見つける
2. 要件を明確にするための質問を行う
3. ファイルパスやコード参照を含む、詳細な実装プランを作成する
4. 実装に取りかかる前に、あなたの承認を待つ

プランは Markdown ファイルとして開かれ、その場で不要なステップを削除したり、アプローチを調整したり、エージェントが見落としたコンテキストを追加したりできます。

ヒント: "Save to workspace" をクリックしてプランを .cursor/plans/ に保存します。これによりチーム向けのドキュメントが作成され、中断した作業を簡単に再開でき、同じ機能に取り組む将来のエージェントへのコンテキストも提供できます。

すべてのタスクに詳細なプランが必要なわけではありません。ちょっとした変更や、繰り返し行っている作業であれば、すぐにエージェントに任せてしまって問題ありません。

#プランからやり直す

エージェントが、あなたの意図と合わないものを作ってしまうことがあります。その場合は、追加入力のプロンプトで修正しようとするのではなく、プランに立ち戻りましょう。

変更を元に戻し、必要な内容がより具体的になるようプランを練り直してから、もう一度実行します。この方が、進行中のエージェントを修正するよりも速いことが多く、結果もきれいになります。

#コンテキストの管理

エージェントがコードを書くことに慣れてくると、あなたの主な役割は、各エージェントがタスクを完了できるように必要なコンテキストを与えることになります。

#エージェントにコンテキスト探索を任せる

プロンプト内で、すべてのファイルに手動でタグ付けする必要はありません。

Cursor のエージェントには強力な検索ツールがあり、必要に応じてコンテキストを取得します。たとえば「the authentication flow」について質問すると、プロンプトにその単語が含まれていなくても、grep とセマンティック検索を使って関連するファイルを見つけ出します。

シンプルにいきましょう。どのファイルか正確に分かっているなら、そのファイルだけタグ付けします。分からない場合は、エージェントが見つけてくれます。無関係なファイルを含めると、何が重要かについてエージェントが判断しづらくなります。

Cursor のエージェントには @Branch のような便利なツールもあり、今取り組んでいる内容についてコンテキストを与えられます。「このブランチの変更をレビューして」や「自分はいま何を作業している？」といった指示が、現在のタスクにエージェントの意識を向ける自然な方法になります。

#いつ新しい会話を始めるべきか

よくある質問のひとつが、「この会話を続けるべきか、それとも新しく始めるべきか？」というものです。

次のような場合は、新しい会話を始めてください：

• 別のタスクや機能に移るとき
• Agent が混乱しているように見える、または同じ間違いを繰り返すとき
• ひとつの論理的な作業単位が完了したとき

次のような場合は、会話を続けてください：

• 同じ機能について反復しながら作業しているとき
• Agent が、これまでのやり取りのコンテキストを必要としているとき
• Agent が直前に作ったものをデバッグしているとき

長い会話は、Agent がフォーカスを失う原因になり得ます。多くのターンや要約を重ねると、コンテキストにノイズが蓄積し、Agent が注意散漫になったり、無関係なタスクに切り替わったりすることがあります。Agent の有効性が下がってきたと感じたら、新しい会話を始めるとよいタイミングです。

#過去の作業を参照する

新しい会話を始めるときは、会話全体をコピーペーストするのではなく、@Past Chats を使って過去の作業を参照してください。エージェントは、チャット履歴を選択的に読み込み、必要なコンテキストだけを取り込めます。

これは、会話全体を複製するよりも効率的です。

#エージェントを拡張する

Cursor では、エージェントの動作をカスタマイズするための主な方法が 2 つあります。すべての会話に適用される静的コンテキストを定義する Rules と、必要に応じてエージェントが利用できる動的な機能である Skills です。

#Rules: プロジェクト向けの静的コンテキスト

Rules は、エージェントがあなたのコードをどのように扱うかを左右する永続的な指示です。すべての会話の冒頭でエージェントが常に参照するコンテキストだと考えてください。

.cursor/rules/ 配下に Rules 用のフォルダを作成し、その中に RULE.md ファイルを置きます:

# Commands

- `npm run build`: Build the project
- `npm run typecheck`: Run the typechecker
- `npm run test`: Run tests (prefer single test files for speed)

# Code style

- Use ES modules (import/export), not CommonJS (require)
- 可能な場合はインポートを分割代入する：`import { foo } from 'bar'`
- See `components/Button.tsx` for canonical component structure

# Workflow

- Always typecheck after making a series of code changes
- API routes go in `app/api/` following existing patterns

ルールは本質に絞り込みましょう。実行すべきコマンド、従うべきパターン、自分たちのコードベース内にある代表的なサンプルへの参照を中心にまとめてください。内容をコピーするのではなくファイルを参照するようにすると、ルールを短く保てるうえ、コードの変更に伴ってルールが陳腐化するのを防げます。

ルールで避けるべきこと:

• スタイルガイド全文のコピー（代わりに linter を使う）
• 考えうるすべてのコマンドを網羅してドキュメント化すること（エージェントは一般的なツールは把握しています）
• ほとんど当てはまらない稀なケース向けの指示を追加すること

Tip: まずはシンプルに始めましょう。同じミスをエージェントが繰り返していると気づいたときにだけルールを追加します。自分たちのパターンを理解する前に過度に最適化しないでください。

ルールは git にコミットして、チーム全体が活用できるようにしましょう。エージェントのミスに気づいたら、そのルールを更新します。GitHub の issue や PR で @cursor をタグ付けして、エージェントにルールを更新させることもできます。

#Skills: 動的な機能とワークフロー

Agent Skills は、エージェントが実行できることの幅を広げます。Skills は、ドメイン固有の知識やワークフロー、スクリプトをパッケージ化し、エージェントが必要に応じて呼び出せるようにしたものです。

Skills は SKILL.md ファイルで定義されており、次のようなものを含めることができます:

• Custom commands: エージェントへの入力で / を使ってトリガーされる再利用可能なワークフロー
• Hooks: エージェントのアクションの前後に実行されるスクリプト
• Domain knowledge: エージェントがオンデマンドで取り込める特定タスク向けの手順

常に含まれる Rules と異なり、Skills は、関連があるとエージェントが判断したときにのみ動的に読み込まれます。これにより、コンテキストウィンドウをすっきり保ちながら、エージェントに特化した機能へのアクセスを与えられます。

#例：長時間実行するエージェントループ

強力なパターンの一つに、Skill を使って目標を達成するまで長時間実行し続けるエージェントを作る方法があります。ここでは、すべてのテストが通るまでエージェントを動かし続ける hook を構築する方法を紹介します。

まず、.cursor/hooks.json で hook を設定します。

{
  "version": 1,
  "hooks": {
    "stop": [{ "command": "bun run .cursor/hooks/grind.ts" }]
  }
}

フックスクリプト（.cursor/hooks/grind.ts）は stdin からコンテキストを受け取り、ループを継続するための followup_message を返します。

import { readFileSync, existsSync } from "fs";

interface StopHookInput {
  conversation_id: string;
  status: "completed" | "aborted" | "error";
  loop_count: number;
}

const input: StopHookInput = await Bun.stdin.json();
const MAX_ITERATIONS = 5;

if (input.status !== "completed" || input.loop_count >= MAX_ITERATIONS) {
  console.log(JSON.stringify({}));
  process.exit(0);
}

const scratchpad = existsSync(".cursor/scratchpad.md")
  ? readFileSync(".cursor/scratchpad.md", "utf-8")
  : "";

if (scratchpad.includes("DONE")) {
  console.log(JSON.stringify({}));
} else {
  console.log(JSON.stringify({
    followup_message: `[反復 ${input.loop_count + 1}/${MAX_ITERATIONS}] 作業を続けてください。完了したら .cursor/scratchpad.md に DONE を記入してください。`
  }));
}

このパターンは次のような場面で役立ちます:

• すべてのテストが合格するまで（必要に応じて修正しながら）実行し続ける場合
• UI がデザインモックアップと一致するまで反復改善する場合
• 成否を検証できるあらゆるゴール指向のタスク

Tip: hook を利用する Skill は、セキュリティツール、シークレットマネージャー、オブザーバビリティプラットフォームなどと連携できます。パートナー連携については hooks のドキュメント を参照してください。

Agent Skills は現在、Nightly リリースチャネルでのみ利用できます。Cursor の設定を開き、Beta を選択して、アップデートチャネルを Nightly に設定し、再起動してください。

コーディング以外にも、日常的に使っている他のツールにエージェントを接続できます。MCP (Model Context Protocol) を使うと、エージェントは Slack メッセージの読み取り、Datadog ログの調査、Sentry のエラーのデバッグ、データベースのクエリ実行などを行えます。

#画像を含める

エージェントは、プロンプト内の画像を直接処理できます。スクリーンショットを貼り付けたり、デザインファイルをドラッグ＆ドロップしたり、画像パスを参照したりできます。

#デザインからコードへ

デザインモックアップを貼り付けて、エージェントに実装を依頼できます。エージェントは画像を解析し、レイアウトや配色、余白を合わせて再現します。Figma MCP サーバー を利用することもできます。

#ビジュアルデバッグ

エラー状態や想定外のUIをスクリーンショットで保存し、エージェントに調査させます。多くの場合、そのほうが問題を言葉で説明するよりも素早く対応できます。

エージェントはブラウザを操作して自分でスクリーンショットを撮ったり、アプリケーションをテストしたり、見た目の変化を検証することもできます。詳しくは ブラウザ機能のドキュメント を参照してください。

#一般的なワークフロー

ここでは、さまざまな種類のタスクで有効に機能するエージェントのパターンを紹介します。

#テスト駆動開発

エージェントにコードを書かせ、テストを実行し、自動で反復させることができます:

1. エージェントにテストの作成を依頼 します。期待される入出力ペアに基づいて書かせてください。このとき TDD をしていることを明示し、まだ存在しない機能のモック実装を作らないように伝えます。
2. エージェントにテストを実行させて、失敗することを確認させます。 この段階では実装コードを書かないよう、はっきりと指示します。
3. テストに満足できたら、それをコミットします。
4. エージェントにテストを通過するコードを書くよう依頼し、テストは変更しないよう指示します。すべてのテストが通るまで反復させてください。
5. 変更内容に満足できたら、その実装をコミットします。

エージェントは、反復の対象とするゴールが明確なときに最も良く機能します。テストがあることで、エージェントは変更を加え、結果を評価し、成功するまで段階的に改善していけます。

#コードベースの理解

新しいコードベースに取り組み始めるときは、学習と探索のためにエージェントを使ってください。チームメイトに聞くのと同じような質問をエージェントに投げかけられます：

• 「このプロジェクトではログ出力はどのように実装されていますか？」
• 「新しい API エンドポイントを追加するにはどうすればよいですか？」
• 「CustomerOnboardingFlow はどのようなエッジケースを扱っていますか？」
• 「なぜ 1738 行目で createUser() ではなく setUser() を呼び出しているのですか？」

エージェントは grep とセマンティック検索の両方を使ってコードベースを検索し、答えを見つけます。これは、初めて触れるコードを素早くキャッチアップするための最速の方法の一つです。

#Git ワークフロー

エージェントは git の履歴を検索したり、マージコンフリクトを解消したりして、git ワークフローを自動化できます。

たとえば、コミットしてプッシュし、プルリクエストを作成するところまで行う /pr コマンドは次のようになります。

現在の変更に対してプルリクエストを作成します。

1. `git diff`でステージされた変更とステージされていない変更を確認する
2. 変更内容に基づいて明確なコミットメッセージを書く
3. 現在のブランチにコミットしてプッシュする
4. `gh pr create`を使用してタイトルと説明でプルリクエストを開く
5. 完了したらPR URLを返す

1日に何度も実行するようなワークフローには、コマンドが最適です。.cursor/commands/ に Markdown ファイルとして保存し、git にコミットしておけば、チーム全員が利用できます。

そのほか、私たちが使っているコマンドの例:

• /fix-issue [number]: gh issue view で Issue の詳細を取得し、関連するコードを見つけて修正を加え、PR を作成します
• /review: Linter を実行し、よくある問題をチェックして、注意が必要な点を要約します
• /update-deps: 古くなった依存関係をチェックし、それぞれの更新後にテストを実行しながら 1 つずつ更新します

エージェントはこれらのコマンドを自律的に実行できるため、/ コマンドを 1 回実行するだけで、複数ステップにわたるワークフローを任せることができます。

#コードのレビュー

AI が生成したコードにはレビューが必要です。Cursor には、そのためのいくつかの方法が用意されています。

#生成中

エージェントの作業の様子を確認できます。差分ビューには、変更内容がリアルタイムで表示されます。エージェントが誤った方向に進んでいると思ったら、Escape キーを押して処理を中断し、指示を出し直してください。

#Agent Review

エージェントの処理が終わったら、Review → Find Issues をクリックして、専用のレビュー処理を実行します。エージェントが提案された変更を行ごとに分析し、潜在的な問題を検出してフラグ付けします。

ローカルでのすべての変更について、Source Control タブを開き、Agent Review を実行してメインブランチとの差分を確認します。

#プルリクエスト向け Bugbot

ソースコード管理にプッシュすると、プルリクエストに対して自動レビューが行われます。Bugbot は高度な分析により、問題を早期に検出し、すべての PR について改善提案を行います。

#アーキテクチャ図

重要な変更を行う場合は、エージェントにアーキテクチャ図の生成を依頼してください。次のようにプロンプトしてみてください。「OAuth プロバイダ、セッション管理、トークンリフレッシュを含む認証システムのデータフローを示す Mermaid 図を作成してください。」これらの図はドキュメント化にも有用であり、コードレビューの前にアーキテクチャ上の問題を発見するのに役立ちます。

#エージェントを並列実行する

Cursor では、複数のエージェントを互いに干渉させることなく並列で実行できます。複数のモデルに同じ問題に取り組ませ、その中から最良の結果を選ぶことで、特に難易度の高いタスクで最終的な出力品質が大きく向上することがわかっています。

#ネイティブな worktree サポート

Cursor は並列エージェントのために、Git worktree を自動的に作成・管理します。各エージェントは、ファイルと変更内容が分離された専用の worktree 上で実行されるため、互いに干渉することなくコードの編集、ビルド、テストを行えます。

worktree でエージェントを実行するには、エージェントのドロップダウンから worktree オプションを選択します。エージェントの実行が完了したら、Apply をクリックして、その変更を作業ブランチにマージします。

#複数のモデルを同時に実行する

強力な使い方として、同じプロンプトを複数のモデルに同時に投げる方法があります。ドロップダウンから複数のモデルを選択し、プロンプトを送信して、結果を横に並べて比較できます。Cursor は、どの解決策が最適だと判断したかも提案します。

これは次のような場面で特に有用です:

• 難問で、モデルごとに異なるアプローチを取りそうな場合
• モデルファミリー間でコード品質を比較したい場合
• あるモデルが見落とすかもしれないエッジケースを見つけたい場合

多数のエージェントを並列に実行する場合は、完了が分かるように通知やサウンドを設定してください。

#クラウドエージェントへの委譲

クラウドエージェントは、通常なら ToDo リストに追加しておくようなタスクに向いています：

• 別の作業中に見つかったバグ修正
• 直近のコード変更のリファクタリング
• 既存コードに対するテスト生成
• ドキュメントの更新

タスクに応じて、ローカルエージェントとクラウドエージェントを切り替えられます。クラウドエージェントは cursor.com/agents、Cursor エディタ、またはスマートフォンから起動できます。席を外している間も、Web やモバイルからセッションを確認できます。クラウドエージェントはリモートのサンドボックス上で動作するため、ラップトップを閉じて、あとから結果を確認できます。

クラウドエージェントの内部的な動作は次のとおりです：

1. タスク内容と関連するコンテキストを説明する
2. エージェントがリポジトリをクローンし、ブランチを作成する
3. その後は自律的に作業し、完了時に Pull Request を作成する
4. 作業完了時に通知を受け取る（Slack、メール、または Web インターフェース経由）
5. 変更内容をレビューし、準備ができたらマージする

Tip: Slack から "@Cursor" をメンションしてエージェントを起動できます。詳しくはこちら。

#手強いバグ向けの Debug Mode

標準的なエージェントとのやり取りではバグ対応がうまく進まない場合、Debug Mode は別のアプローチを提供します。

修正を当てずっぽうで試すのではなく、Debug Mode は次のことを行います：

1. 問題となっていそうな点について複数の仮説を立てる
2. ログ出力用のステートメントを挿入してコードに計測処理を仕込む
3. 実行時データを収集しながら、あなたにバグの再現を依頼する
4. 実際の挙動を分析し、根本原因を特定する
5. 裏付けデータに基づいてピンポイントに修正する

次のようなケースで特に有効です：

• 再現はできるが原因が分からないバグ
• レースコンディションやタイミング起因の問題
• パフォーマンス問題やメモリリーク
• 以前は動いていたのに動かなくなったリグレッション

重要なのは、問題の再現方法について詳細なコンテキストを伝えることです。具体的な情報を渡せば渡すほど、エージェントが追加する計測やログがより有用になります。

#ワークフローを育てる

エージェントを最大限活用している開発者には、いくつか共通点があります。

プロンプトを具体的に書きます。 エージェントの成功率は、指示が具体的であるほど大きく向上します。「add tests for auth.ts」と「Write a test case for auth.ts covering the logout edge case, using the patterns in __tests__/ and avoiding mocks.」を比べてみてください。

セットアップを繰り返し見直します。 まずはシンプルに始めましょう。同じミスをエージェントが何度も繰り返していると気づいたときだけルールを追加してください。繰り返したいワークフローが見えてから、そこで初めてコマンドを追加しましょう。自分のパターンを理解する前に、過度に最適化しないでください。

入念にレビューします。 AI が生成したコードは、一見正しそうに見えても、さりげなく誤っていることがあります。diff を読み、慎重にレビューしましょう。エージェントが高速に動くようになるほど、レビュー工程の重要性は増していきます。

検証可能な目標を与えます。 エージェントは、知らない問題は直せません。型付き言語を使い、linter を設定し、テストを書きましょう。変更が正しいかどうかを判断できる明確な手がかりを、エージェントに与えてください。

エージェントを有能な共同作業者として扱います。 計画を尋ねてください。説明を求めてください。気に入らないアプローチには、きちんと異議を唱えてください。

エージェントは急速に進化しています。パターンは今後の新しいモデルによって変化していきますが、このガイドが、いまのコーディングエージェントとの作業で生産性を高める一助となれば幸いです。

Cursor のエージェント を使って、これらのテクニックを試してみてください。