drivelineresearch/autoresearch-claude-code
Autonomous experiment loop skill for Claude Code — port of pi-autoresearch
概要
autoresearch‑claude‑code は、Anthropic の Claude Code または OpenAI の Codex エージェントを使用して 自動リサーチ ループを実行できる Python ベースの実験フレームワークです。エージェントに具体的な目標（例：「テストスイートの実行時間を短縮する」）、固定のベンチマーク、編集可能なソースファイルのリストを指定します。フレームワークは一時的な Git ブランチを作成し、エージェントをターンごとに実行し、各変更の影響を測定し、統計的に有意な改善を示す編集のみを自動的にコミットし、ユーザー定義の予算（最大実行回数、時間、または計算量）内に留めます。すべての状態は JSONL ファイルに保存され、検査またはロールバックできます。
対象読者
- コード生成エージェントが既存のコードベースをどの程度最適化できるかを評価したい研究者やエンジニア。
- カスタムサーバーや MLOps パイプラインを構築せずに、再現可能で予算制約のある「自己改善」ループを必要とするチーム。
- 具体的なソフトウェアタスクに対する Claude Code または Codex の実際の影響を測定することに関心があるすべての人。
中核概念
| 概念 | 機能 |
|---|---|
| 目標定義 | 短い自然言語コマンド（例：テストスイートの実行時間を最適化）がエージェントに最適化対象を指示します。 |
| ベンチマーク | 数値メトリクスを返す決定的なスコアラースクリプト（例：テストランナー）。 |
| 予算 | ターン数、合計ウォールクロック時間、およびオプションで Codex 呼び出しの制限。 |
| ノイズ処理 | フレームワークはベースライン実行で測定ノイズを較正し、そのノイズフロアを超えてメトリクスを改善する変更のみを受け入れます。 |
| アトミック状態 | すべての実験メタデータは JSONL にアトミックに書き込まれます。同時書き込みは破損を防ぐためにロックされます。 |
| 一時停止 / 再開 | センチネルファイル（.autoresearch‑off）でループを一時停止できます。システムは最後の有効なチェックポイントから再開できます。 |
| ロックされたスコアラー | --protect でリストされたファイルは毎ターンハッシュされます。エージェントはそれらを変更できないため、評価スクリプトの偶発的な破損を防ぎます。 |
インストール（クイック）
# リポジトリをクローン
gh repo clone drivelineresearch/autoresearch-claude-code
cd autoresearch-claude-code
# Claude スキル（デフォルト）または Codex スキルをインストール
./install.sh --claude # ~/.agents/skills/autoresearch に Claude フックをインストール
# または
./install.sh --codex # Codex スキルをインストール
# または両方をインストール
./install.sh --all
スクリプトはシンボリックリンクを作成します。リンクを有効に保つためにチェックアウトを維持してください。対応する ./uninstall.sh フラグでアンインストールします。
ループの実行（Claude の例）
- 初期化 – ターゲットプロジェクトでスキルコマンドを実行します：
エージェントは$ autoresearch optimize test suite runtime with at most 20 runsautoresearchワークツリーを作成し、ベースラインを記録し、レビューを待って一時停止します。 - レビュー –
statusまたはreportをチェックしてベースラインメトリクスを確認します。 - 再開 – 自動ループを開始します：
スコアラーが依存するファイルに応じてpython3 ~/.agents/skills/autoresearch/scripts/claude_loop.py \ --max-turns 20 --max-seconds 3600 --protect path/to/scorer.py--protectを調整します。 - 監視 – ループはターンごとのサマリーを出力します。
.autoresearch‑offを作成して中止できます。 - 結果 – 予算が尽きた後、
autoresearch reportは保持されたコミットと最終メトリクスを表示します。
同じワークフローは Codex でも機能し、codex_loop.py スクリプトと Codex IDE 内の autoresearch CLI を使用します。
使用例
リポジトリには、野球の速球速度を予測する OpenBiomechanics デモが同梱されています。以下を示します：
METRIC name=R2を出力するカスタムスコアラーの定義方法。uv sync --extra …を使用したオプションのバックエンド（torch、boost、tabpfn など）のプラグイン方法。- 検索履歴全体をログする再現可能な実行（
./autoresearch.sh 42）。
開発とテスト
- コアユニットテストは Python 標準ライブラリのみを必要とします：
python -m unittest discover -s tests -v。 - 例のテストには科学パッケージが必要です。
uv sync --project examplesの後に実行できます。 - シェルスクリプトは
shellcheckで lint されます。 - CI は Linux/macOS で実行され、コアと例の両方のスイートを検証します。
制限と注意事項
- ノイズモデルは単純で、改善が測定されたベースライン分散を超えるかどうかのみをチェックします。統計的有意性テストは提供しません。
- フレームワークはエージェントを サンドボックス化 しません。「ロックされたスコアラー」のハッシュと Git ブランチの分離に依存して元のコードを安全に保ちます。
- 予算は ターン と 秒 でカウントされ、トークン使用量や金銭的コストではありません。
- OpenBiomechanics の例の歴史的な R² ジャンプ（0.44 → 0.78）はデータリークを使用しました。リポジトリはこれが検証された主張ではないと注記しています。
- Claude Code と Codex のみがサポートされています。新しいエージェントを追加するには、スキルラッパーとフックスクリプトの作成が必要です。
ライセンス
MIT – コードを自由に使用、変更、再配布できます。
結論： autoresearch-claude-code は、厳格な予算と安全制約の下で Claude Code または Codex にコードベースを反復的に改善させるための、すぐに使える再現可能なループを提供し、組み込みのロギング、一時停止/再開、ベースラインノイズ処理を備えています。
関連
- プロジェクト
- プロジェクト
- プロジェクト
- プロジェクト