エージェントのトラブルシューティング
ファイルアクセス、ルール、ターミナルコマンドなどに関する一般的なエージェントの問題の解決方法。
エージェントの精度を向上させるには？
- プロンプトは具体的に記述し、期待する挙動と制約を含めます
- 多くのファイルにまたがるタスクでは、まずPlan モードを使用します
- 機能を完了したりタスクを切り替えたりしたら、新しいチャットを開始します
- エージェントに常に従わせたいパターンは、
.cursor/rules/にルールとして追加します @に続けてファイル名またはフォルダー名を入力すると、エージェントに必要なコンテキストを指定できます
エージェント がファイルを検出しない場合
- プロジェクトルートの
.cursorignoreファイルを確認してください。ここに記載されたファイルは、エージェント、コードベース検索、@メンションでは利用できません。 .gitignoreを確認してください。ここにあるパターンも、エージェント によるファイルの検出を妨げる場合があります。- プロジェクトを再インデックスしてください。コマンドパレットを開き、「Reindex」を検索します。
- チャット入力欄で
@に続けてファイル名を入力し、ファイルを直接添付してください。
エージェントによる変更を元に戻すには？
以前のメッセージにホバーし、右下にあるチェックポイントを復元をクリックすると、その時点以降にエージェントが行ったすべての変更を元に戻せます。
チェックポイントはローカルに保存され、Git とは別に管理されます。永続的なバージョン管理には Git を使用してください。
エージェントがターミナルコマンドで CI=1 を設定するのはなぜですか？
Cherri Code は、エージェント経由でターミナルコマンドを実行する際、環境変数 CI=1 を設定します。これにより、ターミナルツールはより簡潔な出力を生成できます。CI=1 が設定されるとプロジェクトの動作が変わる場合 (たとえば、対話型プロンプトをスキップしたり、CI 固有のパスを使用したりする場合) は、コマンド内でこの設定を解除できます。
unset CI && your-command-hereまたは、エージェントが常にこれを解除するよう、ルールに追加します。
ターミナルコマンドを実行する際、CI環境でコマンドの挙動が変わる場合は、先頭に `unset CI &&` を付けてください。セルフホスト型マシンのセットアップをトラブルシューティングするにはどうすればよいですか？
agent worker debugを実行して、プリフライトレポートを確認します。一般的な修正方法とサポートへの問い合わせが必要な場合については、セルフホスト型マシンを参照してください。
チームプールがキャパシティに達しているか、エージェントの実行を開始できなかった理由を確認するにはどうすればよいですか？
Cloud Agents ダッシュボードを確認するか、GET /v0/private-workers/summaryを呼び出します。失敗モードとスケーリングに関するガイダンスについては、セルフホスト型マシンを参照してください。
Cloud Agent の Web 添付ファイルが大きすぎる場合は？
cursor.com/agents で <filename> is too large (4MB limit) と表示される場合は、サポートされているファイル形式や、ファイルを小さくする・分割する方法について Cloud Agent の Web 添付ファイルの上限 を参照してください。
「エージェント Execution Timed Out」と表示された場合
このエラーは、Cherri Code の拡張機能ホストが 60 秒以内に起動を完了できず、エージェント機能を初期化できなかったことを示します。同じ根本原因は、ネットワーク診断では「Timeout waiting for EverythingProvider」として表示されます。
原因はさまざまなため、変更を加える前にログを収集してください。
- Cmd/Ctrl+Shift+P を押し、Developer: Export Logs... を実行します。
- Main、Window、Extension Host を選択します。
- Output → Extension Host も確認します (Cmd/Ctrl+Shift+P → 「Output」を選択し、ドロップダウンから「Extension Host」を選択) 。空の場合はスクリーンショットを撮影してください。パネルが空であることは重要な診断情報です。
- エクスポートした zip ファイルとスクリーンショットを、OS と Cherri Code のバージョン情報とともにサポートに共有してください。
管理対象またはエンタープライズ環境のマシンでは、エンドポイント セキュリティソフトウェア (アンチウイルス、EDR) が原因の一つである可能性があります。IT チームがセキュリティエージェントが有効であることを確認した場合は、適切なプロセスとパスの除外設定を追加できるよう、エンドポイント セキュリティ設定ページを共有してください。
不適切なエージェントのレスポンスを報告するには？
- レスポンス下部の ... メニューをクリックし、Copy Request ID を選択します。
- リクエスト ID、再現手順、システム情報 (macOS では Cherri Code > About Cherri Code、Windows/Linux では Help > About から確認) を添えて、forum.cursor.com に投稿します。