autoresearch-fleet

Autoresearch Fleet

karpathy/autoresearch に着想を得た、自律型の研究ループです。変更可能なファイルは1つ、変更不可の評価ハーネスは1つ、状態機械としての git、そして「決して停止しない」という指示で構成されます。エージェントがコードを変更して結果を評価し、改善を保持し、性能低下を破棄して、これを無期限に繰り返します。

オープンワールド拡張：エージェントが停滞した場合（N 回連続で破棄した場合）、オーケストレーターがウェブ検索プロンプトを注入します。これにより、LLM 単独では突破できない知識の限界を乗り越えます。

使用する場面

• 単一の指標（レイテンシ、精度、損失、スコア）を最適化する場合
• 問題に対して高速で決定論的な評価ハーネスがある場合
• 自律的な夜間実行を行いたい場合（就寝中に100回以上の実験を実行）
• 探索空間が広すぎて、手動で探索するのが難しい場合

仕組み

┌─────────────────────────────────────────────────┐
│                 orchestrator.sh                  │
│                                                  │
│  for each iteration:                             │
│    1. Count trailing discards in results.tsv     │
│    2. If >= plateau_threshold → search prompt    │
│    3. Spawn agent (claude -p, codex exec, or pi -p)      │
│    4. Agent reads program.md, edits file, evals  │
│    5. Agent updates results.tsv, keeps/reverts   │
│    6. Check stop conditions (iter/cost/plateau)  │
│    7. Loop                                       │
└─────────────────────────────────────────────────┘

エージェントがすべてを処理します。ファイルの読み込み、コードの編集、評価の実行、コミット、results.tsv の更新、失敗時の変更の取り消しを行います。オーケストレーターはループを実行し、停滞時にプロンプトを切り替え、停止条件を適用するだけです。

ディレクトリ構成

$FLEET_ROOT/                    # The problem directory
  fleet.json                    # Fleet config
  program.md                    # Agent instructions (you write this)
  eval.py                       # Immutable eval harness (you write this)
  solution.py                   # Mutable file (agent edits this)
  results.tsv                   # Experiment log (agent updates, git-untracked)
  orchestrator.sh               # Generated by launch.sh
  .orch-state.json              # Iteration state
  .paused                       # Sentinel (touch to pause)
  logs/
    session-iter-1.jsonl         # Per-iteration session logs
    session-iter-2.jsonl
    ...

fleet.json スキーマ

{
  "fleet_name": "optimize-api-latency",
  "type": "autoresearch",
  "config": {
    "model": "sonnet",
    "fallback_model": "haiku",
    "provider": "claude",
    "budget_per_iter": 2.00,
    "max_turns": 0
  },
  "problem": {
    "workdir": "/home/user/my-project",
    "eval_command": "make benchmark",
    "metric_regex": "^p99_latency_ms:\\s*([0-9.]+)",
    "metric_direction": "minimize",
    "results_file": "results.tsv",
    "program_md": "program.md"
  },
  "stop_when": {
    "max_iterations": 30,
    "cost_cap_usd": 15.0
  },
  "search": {
    "enabled": true,
    "plateau_threshold": 3
  }
}

設定項目

項目	デフォルト	説明
config.model	sonnet	エージェントのモデル
config.fallback_model	haiku	フォールバックモデル（model とは異なる必要があります）
config.provider	claude	claude、codex、または pi
config.budget_per_iter	1.00	1回の反復あたりの最大 USD 額
config.max_turns	0	エージェントの最大ターン数（0 = 無制限）
problem.workdir	fleet のルート	作業ディレクトリ — エージェントが操作するリポジトリ／ディレクトリです。fleet のルートには設定とログのみが保存されます。
problem.eval_command	必須	評価を実行するコマンド（python3 eval.py、make benchmark、pytest --tb=short など）
problem.metric_regex	(任意)	評価出力から指標を抽出する正規表現です。キャプチャグループが1つ必要です。評価で単一の数値が出力される場合は省略します。
problem.metric_direction	minimize	minimize または maximize
problem.results_file	results.tsv	TSV ログファイル（workdir 内）
problem.program_md	program.md	エージェントへの指示ファイル（まず workdir 内を確認し、次に fleet のルートを確認します）
stop_when.max_iterations	50	反復回数の上限
stop_when.cost_cap_usd	0	合計コストの上限（0 = 上限なし）
search.enabled	true	停滞をトリガーとするウェブ検索を有効にします
search.plateau_threshold	3	検索を実行するまでの連続破棄回数

必要な入力

fleet のルートディレクトリに3つの項目が必要です。

1. fleet.json — problem.workdir に対象リポジトリを指定し、eval_command を設定します
2. program.md — エージェントへの指示です。「決して停止しない」と記述する必要があります。
3. 評価コマンド — 指標を出力するコマンドであれば何でもかまいません

fleet-root/              ← fleet.json + program.md + logs
  fleet.json
  program.md
  logs/                  ← created automatically
your-repo/               ← workdir (agent operates here)
  src/...
  results.tsv            ← created automatically

ユーザーがベンチマークを指定しない場合

ユーザーからリポジトリと目標が提示されても、評価コマンドが指定されていない場合：

1. 既存のベンチマークを確認する：Makefile のターゲット（make benchmark、make perf）、package.json のスクリプト（npm run bench、yarn test）、pytest のマーカー（pytest -m benchmark）、または bench/ ディレクトリを探します。
2. 見つかった場合：それを eval_command として使用します。単一の数値が出力されない場合は、metric_regex を設定します。
3. 見つからない場合：workdir にベンチマークスクリプト（bench.sh または bench.py）を書きます。スクリプトは次の処理を行います。
   • 関連する処理（API 呼び出し、関数の実行、ビルド、テストスイート）を実行する
   • ユーザーが重視する指標（レイテンシ、合格率、バンドルサイズなど）を測定する
   • 標準出力に単一の数値を出力する
   • 成功時は 0、クラッシュ時は 0 以外で終了する
4. スクリプトを実行するように eval_command を設定します。

例：ユーザーが「Express アプリの API レイテンシを最適化して」と依頼した場合：

#!/usr/bin/env bash
# bench.sh — measure p99 latency
npm start &>/dev/null &
PID=$!
sleep 3
RESULT=$(curl -s -o /dev/null -w '%{time_total}' http://localhost:3000/api/health)
kill $PID 2>/dev/null
echo "$RESULT"

次に、fleet.json で "eval_command": "bash bench.sh" を設定します。

セットアップ

1. fleet.json と program.md（作成した場合は bench.sh も）を含む fleet のルートを作成します
2. bash ${AGENTS_SKILLS_DIR}/scripts/launch.sh <fleet-root> を実行します（git init と results.tsv の作成は自動で行われます）
3. 状況を確認するには bash ${AGENTS_SKILLS_DIR}/scripts/status.sh <fleet-root> を実行します

利用可能なスクリプト

スクリプト	目的
launch.sh <fleet-root> [--dry-run]	orchestrator.sh を生成し、モニター付きで tmux 内に起動します
status.sh <fleet-root> [--watch]	イテレーション、最良のメトリクス、results.tsv、コスト、停滞状況を表示します
view.sh <fleet-root> <iter|latest> [--follow]	指定したイテレーションの解析済みセッションイベントを表示します
report.sh <fleet-root> [--output file.md]	実行完了後に Markdown の概要を生成します
pause.sh <fleet-root>	次のイテレーション境界で一時停止します
resume.sh <fleet-root>	一時停止したフリートを再開します
kill.sh <fleet-root>	強制停止します：tmux を終了し、孤立プロセスを一掃します

program.md テンプレート

program.md は次の構成に従ってください（問題に合わせて調整してください）：

# autoresearch: <problem description>

## Setup
1. Explore the codebase to understand the architecture.
2. Read `results.tsv` for prior experiment history.
3. Run `<eval_command>` to establish a baseline.

## Rules
- Goal: <minimize|maximize> the metric.
- Make ONE change per experiment. Keep changes focused.
- <any constraints: don't touch tests, don't modify config, etc.>

## The experiment loop
LOOP FOREVER:
1. Read results.tsv for context on what's been tried.
2. Make ONE change to the codebase.
3. `git add -A && git commit -m "short description"`
4. Run: `<eval_command>`
5. Record in results.tsv (tab-separated): `commit  metric  status  description`
6. If metric improved: keep the commit.
7. If worse or crash: `git reset --hard HEAD~1` and log as discard/crash.
8. Go to step 1.

**NEVER STOP.** Run until manually interrupted.

主な設計原則（Karpathy による）

1. 状態機械としての Git — 改善時はブランチを進め、性能低下時はリセットします
2. 固定された評価 — すべての実験を比較可能にします
3. 共有メモリとしての results.tsv — エージェントは履歴を読み、失敗の繰り返しを防ぎます
4. 決して停止しない — エージェントは終了されるまで自律的に実行されます
5. シンプルさの基準 — 複雑さが醜い形で増すなら、わずかな改善には価値がありません

オープンワールド探索（拡張機能）

search.enabled が true の場合、オーケストレーターは results.tsv 内の連続する破棄数を数えます。その数が search.plateau_threshold を超えると、次のイテレーションでは、コーディング前に WebSearch を使うようエージェントに指示する、探索機能を追加したプロンプトが使われます。

これは検証済みです。実験 009 では、探索によって Winograd の Strassen 変種（加算 15 回、従来は 18 回）が見つかりました。これは LLM の学習データに含まれていない手法であり、通常の autoresearch が行き詰まっていた停滞を突破しました。

重要：停滞の検出は LLM ではなく、Bash で（決定論的に）行われます。初期の実験では、エージェントが連続する破棄数を誤って数え、停滞を幻覚していました。外部でのカウントが必須です。

却下すべき合理化

エージェントの主張	反論
「最良の結果を得るため、エージェントは毎イテレーションで探索するべきです」	停滞時の探索は、常時探索より優れています。初期の探索の多くは重複しており、レイテンシーを増加させます。行き詰まったとき（破棄 3 回以上）にのみ探索してください。
「オーケストレーターで Git を管理するべきです」	Git はエージェントが処理します。コミットメッセージの修正、エッジケースへの対応、適切なリバートができます。オーケストレーターはループするだけです。
「評価ハーネスで同じ入力を再利用できます」	入力の再利用は攻略される可能性があります。エージェントは ID ベースのメモ化を見つけ、問題ではなくベンチマークに最適化するようになります。時間計測を行う実行ごとに、新しいシード付き入力を使ってください。
「これには iterative-fleet を使うべきです」	iterative-fleet にはレビュアーがあります。Autoresearch にはレビュアーがありません。評価スクリプト自体が品質ゲートです。パターンもスキルも異なります。

$ARGUMENTS