ベストプラクティス

Cloud Agent をより安定して動作させるための推奨事項です。

まず環境をセットアップする

Cursor の環境が設定されるように、Cloud Agent のセットアップ を使ってください。人間の開発者と同じように、Cursor も、環境が正しくセットアップされているほうが、より良い成果を出せます。

エージェントが必要なものにアクセスできるようにする

Cloud Agentを実行する前に、次の前提条件を確認してください:

• Secrets: ダッシュボードの Secrets tab から、エージェントが必要なシークレット (API キー、データベース認証情報など) にアクセスできることを確認してください。クラウドロールでは、長期間有効なアクセスキーではなく OIDC トークン を優先してください。
• Egress controls: network access 制限を有効にしている場合は、ローカル開発で必要なすべての URL が許可リストに登録されていることを確認してください。
• ローカルでのテスト容易性: リポジトリは、VM から到達できない外部サービスを必要とせずに、ローカルで問題なく実行できるように設定されている必要があります。人間の開発者がローカルでテストしにくい場合は、エージェントにとっても難しくなります。

skills と agents.md を使ってエージェントを設定する

クラウドエージェントが自分の変更のテストに手こずっている場合は、skills と agents.md を使ってエージェントを設定することをおすすめします。

エージェントは、賢いけれど前提知識の少ない人間の開発者だと考えてください。正しく動作させるいちばんの方法は、「何をすべきか」を理解するために必要なコンテキストを与えることです。

たとえば Cursor では、agents.md にモノレポ内で最もよく使われるマイクロサービスを実行・デバッグするためのヒントを記載しています。また、主要なサービスをテスト・デバッグする方法についての skills も多数用意しており、それぞれの skill には、いつその skill を使うべきかが明確に示されています。

skills には、特定のマイクロサービスのデバッグ方法や、テストに必要な場合のサードパーティ依存関係のセットアップ方法など、より踏み込んだ情報が含まれています。

ルールで規約を徹底する

Cloud Agents は、3 つのレベルで ルール を読み取り、それに従うことができます。

• ユーザー ルール: Cursor の設定で設定します。すべてのリポジトリにまたがる自分のセッションに適用されます。個人にのみ適用したいルールに最適です。
• チーム ルール: ルール、コマンド、フックのダッシュボード で設定します。すべてのリポジトリにわたって、すべてのチーム メンバーに適用されます。組織全体の規約に最適です。
• リポジトリ ルール: リポジトリにコミットされた .cursor/rules/*.mdc ファイルです。そのリポジトリを使用するすべてのエージェントに適用されます。リポジトリやプロジェクト固有の規約に最適です。

エージェントに必要なツールを持たせる

エージェントは、利用できるツールによって能力が制限されがちです。MCP を活用してカスタムツールを作成し、人間の開発者と同じシステムにエージェントがアクセスできるようにすることを推奨します。

エージェントに合わせてツールを調整する

エージェントがうまく使いこなせるツールを用意することが重要です。まずツールを作成し、エージェントがそれらをどう使うか観察しながら改善していくことをおすすめします。

たとえば Cursor では、モデルが Cursor のコードベース内のマイクロサービスを実行できるようにするためのカスタム CLI を作成しています。package.json ファイル内のカスタム開発用コマンドを実行する際に、一部のモデルは引数を忘れてしまったり、エージェントが人間の開発者なら無視してよいと分かっているようなノイズの多いビルドログに気を取られてしまうことが分かりました。