autoresearch-agent

自動リサーチエージェント

あなたが眠っている間、エージェントが実験します。目覚めると、結果が待っています。

Karpathyのautoresearchに着想を得た、自律型の実験ループです。エージェントは1つのファイルを編集し、固定の評価を実行して、改善を維持し、失敗を破棄しながら、無期限にループします。

1回の推測ではありません。測定を重ねた50回の試行が、着実に成果を積み上げます。

---

スラッシュコマンド

コマンド	内容
/ar:setup	対話形式で新しい実験を設定します
/ar:ar-run	実験を1回実行します
/ar:loop	間隔（10m、1h、daily、weekly、monthly）を設定して自律ループを開始します
/ar:ar-status	ダッシュボードと結果を表示します
/ar:ar-resume	一時停止した実験を再開します

---

このスキルが有効になるとき

ユーザーの次のようなパターンを認識します。

• 「これをもっと速く／小さく／良くして」
• 「[指標]向けに[ファイル]を最適化して」
• 「自分の[見出し／コピー／プロンプト]を改善して」
• 「一晩中実験を実行して」
• 「[指標]をXからYにしたい」
• 最適化、ベンチマーク、改善、実験ループ、自動リサーチに関するリクエスト

ユーザーが対象ファイルと成功を測定する方法を説明している場合、このスキルが適用されます。

---

セットアップ

初回 — 実験を作成する

セットアップスクリプトを実行します。実験を保存する場所はユーザーが決めます。

プロジェクトレベル（リポジトリ内に置かれ、Gitで追跡され、チームで共有可能）：

python scripts/setup_experiment.py \
  --domain engineering \
  --name api-speed \
  --target src/api/search.py \
  --eval "pytest bench.py --tb=no -q" \
  --metric p50_ms \
  --direction lower \
  --scope project

ユーザーレベル（個人用で、~/.autoresearch/に保存）：

python scripts/setup_experiment.py \
  --domain marketing \
  --name medium-ctr \
  --target content/titles.md \
  --eval "python evaluate.py" \
  --metric ctr_score \
  --direction higher \
  --evaluator llm_judge_content \
  --scope user

--scopeフラグで.autoresearch/の保存場所を指定します。

• project（デフォルト）→ リポジトリのルートに.autoresearch/を作成します。実験の定義はGitで追跡され、結果はGitの追跡対象外になります。
• user → ホームディレクトリに~/.autoresearch/を作成します。すべて個人用です。

セットアップで作成されるもの

.autoresearch/
├── config.yaml                        ← Global settings
├── .gitignore                         ← Ignores results.tsv, *.log
└── {domain}/{experiment-name}/
    ├── program.md                     ← Objectives, constraints, strategy
    ├── config.cfg                     ← Target, eval cmd, metric, direction
    ├── results.tsv                    ← Experiment log (gitignored)
    └── evaluate.py                    ← Evaluation script (if --evaluator used)

results.tsvの列： commit | metric | status | description

• commit — Gitの短縮ハッシュ
• metric — 浮動小数点数、またはクラッシュ時は「N/A」
• status — keep | discard | crash
• description — 変更内容、またはクラッシュした理由

分野

分野	用途
engineering	コードの速度、メモリ、バンドルサイズ、テスト合格率、ビルド時間
marketing	見出し、ソーシャル向けコピー、メールの件名、広告コピー、エンゲージメント
content	記事の構成、SEOの説明文、読みやすさ、CTR
prompts	システムプロンプト、チャットボットのトーン、エージェントへの指示
custom	測定可能な指標があれば、その他すべて

program.mdがすでに存在する場合

ユーザーが独自のprogram.mdを作成している場合があります。実験ディレクトリ内に見つかったら、それを読み込みます。テンプレートよりも優先して使用し、不足している項目だけを確認します。

---

エージェントのプロトコル

あなたがループを担当します。スクリプトがセットアップと評価を処理し、あなたは創造的な作業を担当します。

開始前

1. .autoresearch/{domain}/{name}/config.cfgを読み、次の項目を確認します。
   • target — 編集するファイル
   • evaluate_cmd — 変更を測定するコマンド
   • metric — 評価出力から探す指標名
   • metric_direction — 「lower」または「higher」のどちらが良いか
   • time_budget_minutes — 評価にかける最大時間
2. program.mdを読み、戦略、制約、変更可能なものと変更不可のものを確認します。
3. results.tsvを読み、実験の履歴を確認します（列：commit、metric、status、description）。
4. 実験ブランチをチェックアウトします：git checkout autoresearch/{domain}/{name}

各イテレーション

1. results.tsvを確認します。うまくいったことは何か、失敗したことは何か、まだ試していないことは何かを確認します。
2. 対象ファイルに加える変更を1つ決めます。実験ごとに変数は1つです。
3. 対象ファイルを編集します。
4. コミットします：git add {target} && git commit -m "experiment: {description}"
5. 評価します：python scripts/run_experiment.py --experiment {domain}/{name} --single
6. 出力を読みます。指標値とともにKEEP、DISCARD、またはCRASHが表示されます。
7. ステップ1に戻ります。

スクリプトが処理すること（あなたは処理しません）

• タイムアウト付きで評価コマンドを実行する
• 評価出力から指標を解析する
• これまでの最高値と比較する
• 失敗時にコミットを元に戻す（git reset --hard HEAD~1）
• 結果をresults.tsvに記録する

実験の開始

# Single iteration (the agent calls this repeatedly)
python scripts/run_experiment.py --experiment engineering/api-speed --single

# Dry run (test setup before starting)
python scripts/run_experiment.py --experiment engineering/api-speed --dry-run

戦略の段階的な強化

• 実行 1～5 回：すぐに実施できる改善（明らかな改善、シンプルな最適化）
• 実行 6～15 回：体系的な探索（一度に 1 つのパラメーターを変更）
• 実行 16～30 回：構造的な変更（アルゴリズムの入れ替え、アーキテクチャの変更）
• 実行 30 回以上：大胆な実験（まったく異なるアプローチ）
• 20 回以上実行しても改善がない場合：program.md の Strategy セクションを更新します

自己改善

実験を 10 回行うごとに、results.tsv を確認してパターンを探します。学んだこと（例：「キャッシュの変更は一貫して 5～10％改善する」「リファクタリングを試みても指標は改善しない」）を基に、program.md の Strategy セクションを更新します。以降の反復では、蓄積された知識を活用できます。

停止

• ユーザーに中断されるか、コンテキストの上限に達するか、program.md の目標を達成するまで実行します
• 停止する前に、results.tsv が最新の状態であることを確認します
• コンテキストの上限に達した場合：次のセッションで再開できます。results.tsv と git log は保持されます

ルール

• 実験ごとに変更は 1 つ。 一度に 5 つ変更しないでください。何が効果をもたらしたのか分からなくなります。
• シンプルさの基準。 見苦しい複雑さを加える小さな改善には価値がありません。同等の性能でコードがシンプルになれば成功です。同じ結果を得られるコードを削除できるのが最善です。
• 評価器を変更しないでください。 evaluate.py が正解の基準です。これを変更すると、すべての比較が無効になります。変更しようとしていることに気づいたら、直ちに中止してください。
• タイムアウト。 実行時間が制限時間の 2.5 倍を超えた場合は終了し、クラッシュとして扱います。
• クラッシュへの対処。 タイポやインポート漏れの場合は修正して再実行します。アイデアに根本的な問題がある場合は元に戻し、「crash」と記録して次に進みます。クラッシュが 5 回連続した場合は、一時停止して通知します。
• 新しい依存関係を追加しないでください。 プロジェクトですでに利用できるものだけを使用します。

---

評価器

すぐに使える評価スクリプトです。セットアップ中に --evaluator を指定すると、実験ディレクトリにコピーされます。

無料の評価器（API 費用なし）

評価器	指標	用途
benchmark_speed	p50_ms（低いほど良い）	関数／API の実行時間
benchmark_size	size_bytes（低いほど良い）	ファイル、バンドル、Docker イメージのサイズ
test_pass_rate	pass_rate（高いほど良い）	テストスイートの合格率
build_speed	build_seconds（低いほど良い）	ビルド／コンパイル／Docker のビルド時間
memory_usage	peak_mb（低いほど良い）	実行中のピークメモリ使用量

LLM 評価器（サブスクリプションを使用）

評価器	指標	用途
llm_judge_content	ctr_score 0～10（高いほど良い）	見出し、タイトル、説明
llm_judge_prompt	quality_score 0～100（高いほど良い）	システムプロンプト、エージェントへの指示
llm_judge_copy	engagement_score 0～10（高いほど良い）	SNS 投稿、広告文、メール

LLM 評価器は、ユーザーがすでに実行している CLI ツール（Claude、Codex、Gemini）を呼び出します。評価プロンプトは evaluate.py 内で固定されており、エージェントは変更できません。これにより、エージェントが評価器を不正に操作することを防ぎます。

費用はユーザーの既存のサブスクリプションで賄われます。

• Claude Code Max → 評価で Claude を無制限に呼び出し可能
• Codex CLI（ChatGPT Pro）→ Codex を無制限に呼び出し可能
• Gemini CLI（無料枠）→ 無料で評価を実行可能

カスタム評価器

組み込みの評価器が適さない場合は、ユーザーが独自の evaluate.py を作成します。必要な条件は、標準出力に metric_name: value を出力することだけです。

#!/usr/bin/env python3
# My custom evaluator — DO NOT MODIFY after experiment starts
import subprocess
result = subprocess.run(["my-benchmark", "--json"], capture_output=True, text=True)
# Parse and output
print(f"my_metric: {parse_score(result.stdout)}")

---

結果の表示

# Single experiment
python scripts/log_results.py --experiment engineering/api-speed

# All experiments in a domain
python scripts/log_results.py --domain engineering

# Cross-experiment dashboard
python scripts/log_results.py --dashboard

# Export formats
python scripts/log_results.py --experiment engineering/api-speed --format csv --output results.csv
python scripts/log_results.py --experiment engineering/api-speed --format markdown --output results.md
python scripts/log_results.py --dashboard --format markdown --output dashboard.md

ダッシュボード出力

DOMAIN          EXPERIMENT          RUNS  KEPT  BEST         Δ FROM START  STATUS
engineering     api-speed            47    14   185ms        -76.9%        active
engineering     bundle-size          23     8   412KB        -58.3%        paused
marketing       medium-ctr           31    11   8.4/10       +68.0%        active
prompts         support-tone         15     6   82/100       +46.4%        done

エクスポート形式

• TSV — デフォルト。タブ区切り（スプレッドシートと互換性があります）
• CSV — カンマ区切り。適切に引用符で囲まれます
• Markdown — 書式付きの表。GitHub／ドキュメントで読みやすい形式です

---

先回りして通知するトリガー

尋ねられる前に、次の内容を指摘してください。

• 動作する評価コマンドがない → ループを開始する前にテストしてください。一度実行し、出力を確認します。
• 対象ファイルが git にない → まず git init && git add . && git commit -m 'initial' を実行してください。
• 指標の方向性が不明 → 「値が低いほうがよいですか、それとも高いほうがよいですか？」と尋ねてください。開始前に確認が必要です。
• 時間の予算が少なすぎる → 評価に予算以上の時間がかかる場合、実行するたびにクラッシュします。
• エージェントが evaluate.py を変更している → ただちに停止してください。比較が無効になります。
• 5 回連続でクラッシュした → ループを一時停止してください。ユーザーに通知します。実行を続けて時間を浪費しないでください。
• 20 回以上実行しても改善しない → program.md で戦略を変更するか、別のアプローチを試すことを提案してください。

---

インストール

1 行でインストール（任意のツール）

git clone https://github.com/alirezarezvani/claude-skills.git
cp -r claude-skills/engineering/autoresearch-agent ~/.claude/skills/

複数ツールへのインストール

./scripts/convert.sh --skill autoresearch-agent --tool codex|gemini|cursor|windsurf|openclaw

OpenClaw

clawhub install cs-autoresearch-agent

---

関連スキル

• self-improving-agent — エージェント自身のメモリやルールを時間をかけて改善します。構造化された実験ループには使用しません。
• senior-ml-engineer — ML アーキテクチャの判断に使用します。補完的なスキルです。初期設計に使用し、その後、最適化に autoresearch を使用してください。
• tdd-guide — テスト駆動開発に使用します。補完的なスキルです。テストを評価関数として使用できます。
• skill-security-auditor — 公開前にスキルを監査します。最適化ループには使用しません。