📌 はじめに
AIコーディングエージェントの性能を決めるのは、モデルだけではありません。モデルがどのようにツールを使い、コンテキストを受け取り、ユーザーと対話するかを制御する「エージェントハーネス（Agent Harness）」の設計が、ユーザー体験を大きく左右します。
Cursor チームは、このハーネスを「意欲的なソフトウェア製品」と同じように開発しています。本記事では、Cursor 公式ブログの内容を元に、エージェントハーネスの継続的な改善手法を徹底解説します。
🔑 キーワード・用語集
| 用語 | 説明 |
|---|---|
| エージェントハーネス | LLM エージェントのツール定義、プロンプト、コンテキスト管理、エラーハンドリングなどを統合的に制御するフレームワーク |
| コンテキストウィンドウ | LLM に送信されるプロンプト全体の入力領域。システムプロンプト、ツール説明、会話履歴、ユーザーリクエストで構成 |
| 静的コンテキスト | セッション開始時に固定的に提供される情報（OS情報、git status など） |
| 動的コンテキスト | エージェントが作業中に自ら取得する情報（ファイル読み取り、検索結果など） |
| Keep Rate | エージェントが生成したコードが、一定時間後もユーザーのコードベースに残っている割合 |
| コンテキストの劣化 | エラーがコンテキスト内に蓄積し、モデルの後続の判断品質を低下させる現象 |
| サブエージェント | 新しいコンテキストウィンドウで起動される、特定タスク専用のエージェント |
| CursorBench | Cursor 独自のオフライン評価スイート |
🏗️ 全体アーキテクチャ概要
Cursor のエージェントハーネス改善は、以下のサイクルで回されています。
┌─────────────────────────────────────────────────┐
│ 改善サイクル全体像 │
│ │
│ ① ビジョン策定 │
│ 「理想的なエージェント体験」を定義 │
│ ↓ │
│ ② 仮説立案 │
│ ビジョンに近づくための仮説を設定 │
│ ↓ │
│ ③ 実験・検証 │
│ オフライン評価 + オンライン A/B テスト │
│ ↓ │
│ ④ 定量・定性シグナルの収集 │
│ Keep Rate / ユーザー満足度 / エラー率 │
│ ↓ │
│ ⑤ 改善の適用 │
│ ハーネスの更新・デプロイ │
│ ↓ │
│ （① に戻って繰り返す） │
└─────────────────────────────────────────────────┘
1️⃣ コンテキストウィンドウの進化
コンテキストウィンドウとは？
LLM とのやり取りの中核にあるのがコンテキストウィンドウです。構成は以下の通りです：
┌──────────────────────────────────┐
│ コンテキストウィンドウ │
├──────────────────────────────────┤
│ 1. システムプロンプト │
│ 2. ツールの説明 │
│ 3. 会話の状態（履歴） │
│ 4. ユーザーのリクエスト │
└──────────────────────────────────┘
初期（2024年後半）：ガードレール重視
当初のモデルは自力で適切なコンテキストを選ぶのが苦手だったため、Cursor チームは多くのコンテキストエンジニアリングを行いました：
- 編集のたびに lint エラー・型エラー をエージェントに提示
- 要求した行数が少なすぎる場合は ファイル読み取りを自動補完
- 1ターンで呼び出せる ツール数の上限 を設定
- 大量の 静的コンテキスト を提供（フォルダ構成、コードスニペット、圧縮ファイルなど）
現在：動的コンテキスト中心へ
モデルの能力が向上するにつれて、アプローチは大きく変化しました：
| 項目 | 初期（2024年後半） | 現在（2026年） |
|---|---|---|
| ガードレール | 多い（エラー提示、ツール数制限） | 削減 |
| 静的コンテキスト | 大量（フォルダ構成、スニペットなど） | 最小限（OS、git status、表示中ファイル） |
| 動的コンテキスト | 限定的 | エージェントが自ら取得する方式を大幅拡充 |
| 設計思想 | 「モデルの不足を補う」 | 「モデルの能力を信頼し、自律性を高める」 |
💡 ポイント
モデルの進化に合わせて「ガードレールを減らし、動的コンテキストを増やす」方向へシフト。
エージェント自身が必要な情報を取得・外部とやり取りする手段を増やすことが、現在の注力分野。
2️⃣ ハーネスの変更を評価する2つの方法
ハーネスの変更が本当に「改善」なのかを判断するには、適切な評価基盤が不可欠です。Cursor はオフライン評価と**オンライン実験（A/Bテスト）**の二本立てで評価しています。
方法 A：オフライン評価（ベンチマーク）
┌─────────────────────────────────────┐
│ オフライン評価 │
│ │
│ ・CursorBench（独自評価スイート） │
│ ・公開ベンチマーク │
│ │
│ ✅ 標準化された品質把握 │
│ ✅ 時系列での比較が可能 │
│ ⚠️ 実際の利用状況を完全には再現不可 │
└─────────────────────────────────────┘
方法 B：オンライン実験（A/Bテスト）
2つ以上のハーネスバリアントを本番環境で並行デプロイし、実ユーザーの利用状況で評価します。
測定メトリクス
基本メトリクス（傾向把握向け）：
- レイテンシ
- トークン効率
- ツール呼び出し回数
- キャッシュヒット率
品質メトリクス（エージェントの仕事の質を測る）：
| メトリクス | 測定方法 | シグナル |
|---|---|---|
| Keep Rate | 一定時間後にエージェントのコード変更がコードベースに残っているか | コードが残っている → ✅ 高品質 / 修正された → ❌ 品質不足 |
| ユーザー満足度推定 | LLM でユーザーの応答を意味的に分析 | 次の機能に進む → ✅ 満足 / スタックトレース貼付 → ❌ 不満 |
実験から得られた教訓
ある実験では、コンテキスト要約にもっと高価なモデルを使ってみたが、品質向上はごくわずかでコストに見合わないと判断し、見送りに。
→ データに基づいて「やらないこと」を決める判断も重要。
3️⃣ 劣化の追跡と修復
なぜ劣化が問題なのか？
モデルと機能が増えると、ハーネスの状態空間が拡大し、バグが入り込みやすくなります。特にツール呼び出しエラーは深刻な影響を及ぼします。
ツール呼び出しエラー発生
↓
エラーがコンテキストに残る
↓
トークンの浪費 + コンテキストの劣化
↓
後続の判断品質が低下
↓
エージェントが行き詰まる / 脱線する
エラーの分類体系
Cursor では、想定内のエラーを原因ごとに体系的に分類しています：
| カテゴリ | 説明 | 例 |
|---|---|---|
| Unknown（未知） | ハーネスのバグ → 常にバグとして扱う | 想定外のエラー |
| InvalidArguments | モデルのミス・コンテキスト内の矛盾 | 誤った編集パラメータ |
| UnexpectedEnvironment | 環境とモデルの認識のズレ | 存在しないファイルの読み取り |
| ProviderError | ベンダー側の障害 | WebSearch / GenerateImage の外部 API 障害 |
| UserAborted | ユーザーによる中断 | 手動キャンセル |
| Timeout | 処理時間超過 | 大規模コードベースでの grep タイムアウト |
アラートと自動化
┌──────────────────────────────────────────────┐
│ 劣化検知と修復の仕組み │
│ │
│ [未知のエラー] │
│ → 固定しきい値を超えたら即アラート │
│ │
│ [想定内のエラー] │
│ → baseline（ツール×モデル別）からの │
│ 異常検知でアラート │
│ │
│ [週次自動化] │
│ → ログ検索 AI が新規/急増問題を発見 │
│ → バックログチケットを自動作成/更新 │
│ │
│ [修正] │
│ → クラウドエージェントで一括修正 │
│ → Linear から直接トリガー可能 │
└──────────────────────────────────────────────┘
🎯 成果
集中的なスプリントにより、予期しないツール呼び出しエラーを1桁分（約10分の1に）削減。
4️⃣ さまざまなモデル向けにハーネスをカスタマイズする
モデルごとの違い
Cursor のハーネスはモデルに依存しない抽象設計を採用しつつ、各モデルに深くカスタマイズされています。
| 観点 | OpenAI モデル | Anthropic (Claude) モデル |
|---|---|---|
| ファイル編集方式 | パッチベース | 文字列置換ベース |
| 指示への従い方 | 文字どおり・正確 | 直感的・あいまいな指示にも寛容 |
| カスタマイズ | プロバイダー別 + バージョン別プロンプト | プロバイダー別 + バージョン別プロンプト |
新モデル対応のプロセス
1. 早期アクセス取得
↓
2. 最も近い既存モデルのハーネスを土台にする
↓
3. オフライン評価でモデルの混乱ポイントを特定
↓
4. チームメンバーに実際に使ってもらい問題を洗い出す
↓
5. ハーネスを調整
↓
6. 3〜5 を繰り返す
↓
7. 安心してリリースできる状態になったらデプロイ
モデル固有の癖への対処例：「コンテキスト不安」
あるモデルで、コンテキストウィンドウが埋まってくると「タスクが大きすぎる」と予防線を張り、作業を拒み始める現象が発生。
→ Cursor チームはこれを「コンテキスト不安（Context Anxiety）」と命名し、プロンプト調整で抑制に成功。
5️⃣ チャット途中でのモデル切り替えを支える
課題
モデルごとに挙動・プロンプト・ツール形式が異なるため、会話途中のモデル切り替えは技術的に難しい課題です。
┌────────────────────────────────────────────────┐
│ モデル切り替え時の課題 │
│ │
│ 課題①: 会話履歴の互換性 │
│ ・別モデルが生成した履歴に対し、 │
│ 新モデルのツールを適用する必要がある │
│ ・学習時の分布から外れた入力への対応 │
│ │
│ 課題②: キャッシュミスによる性能低下 │
│ ・プロバイダー×モデルごとにキャッシュが異なる │
│ ・切り替え直後のターンが遅く、コストも増大 │
└────────────────────────────────────────────────┘
対策
| 課題 | 対策 |
|---|---|
| 会話履歴の互換性 | 「別モデルから引き継いだ」ことを伝えるカスタム instructions を追加。自身のツールセットにないツールを呼ばないよう誘導 |
| キャッシュミス | 切り替え時に会話を要約し、整理された概要を渡す（ただし複雑タスクでは詳細が失われるリスクあり） |
| 根本的な回避策 | サブエージェントを使用（新しいコンテキストウィンドウで起動するため、履歴の互換性問題を回避） |
💡 推奨事項
切り替える明確な理由がない限り、会話全体を通して1つのモデルを使い続けることが推奨されている。
6️⃣ ハーネスとソフトウェア開発の未来
マルチエージェント化する未来
Cursor チームは、AI支援ソフトウェア開発の未来はマルチエージェント化していくと考えています。
┌──────────────────────────────────────────┐
│ マルチエージェント・アーキテクチャ │
│ │
│ ┌──────────┐ │
│ │ ハーネス │ ← オーケストレータ│
│ └────┬─────┘ │
│ ┌───────┼───────┐ │
│ ↓ ↓ ↓ │
│ ┌────────┐┌────────┐┌────────┐ │
│ │ 計画 ││ 編集 ││ デバッグ│ │
│ │ Agent ││ Agent ││ Agent │ │
│ └────────┘└────────┘└────────┘ │
│ │
│ 各エージェントが最も得意な領域を担当 │
│ ハーネスがタスク分配と結果統合を制御 │
└──────────────────────────────────────────┘
ハーネスが問われる3つの能力
- どのエージェントに任せるべきかを判断する
- エージェントの強みを活かせる形でタスクを組み立てる
- 結果をつなぎ合わせて一貫したワークフローにする
連携をオーケストレーションする力は、単一のエージェントではなく、ハーネスに宿る。
📊 まとめ：6つの改善領域の全体像
| # | 領域 | 核心 | キーワード |
|---|---|---|---|
| 1 | コンテキストウィンドウ | 静的 → 動的コンテキストへの移行 | ガードレール削減、自律性向上 |
| 2 | 評価方法 | オフライン + オンラインの二本立て | CursorBench、A/Bテスト、Keep Rate |
| 3 | 劣化追跡・修復 | エラー分類 + 異常検知 + 自動化 | コンテキストの劣化、エラー分類、自動修復 |
| 4 | モデル別カスタマイズ | モデル非依存の抽象化 + 深いカスタマイズ | パッチ vs 文字列置換、コンテキスト不安 |
| 5 | モデル切り替え | 互換性とキャッシュの課題に対応 | カスタム instructions、サブエージェント |
| 6 | 未来の方向性 | マルチエージェント × ハーネス設計 | オーケストレーション、専門特化 |
🚀 実務への示唆・学び
エージェント開発者が取り入れるべき5つのプラクティス
-
ガードレールを動的に調整する
- モデルの能力向上に合わせてガードレールを減らし、エージェントの自律性を高める
- ただし、安全網として最低限のガードレールは残す
-
多層的な評価基盤を構築する
- ベンチマーク（オフライン）だけでなく、A/Bテスト（オンライン）で実ユーザーの行動を観測する
- 「Keep Rate」のような間接的だが実質的な品質指標を定義する
-
エラーを体系的に分類し、監視を自動化する
- 未知のエラーは常にバグとして扱う
- 想定内のエラーも baseline からの逸脱を異常検知で捉える
-
モデルごとにハーネスをカスタマイズする
- 各モデルの学習時のツール形式・指示スタイルに合わせる
- バージョン単位での微調整も重要
-
マルチエージェント化を見据えた設計をする
- オーケストレーション層（ハーネス）の設計が将来の鍵
- サブエージェントの活用で柔軟性と堅牢性を両立