autoresearch

Autoresearch

自律型実験ループ：アイデアを試し、うまくいったものを残し、うまくいかなかったものを捨て、決して止まりません。

概要

自律的な最適化ループを実行します。測定可能な指標を、変更を加えて実験を実行し、改善したものだけを残すことで、体系的に向上させることが役割です。構造化された状態ファイルを維持するため、記憶のない新しいセッションを含め、どのセッションからでも中断したところから正確に再開できます。

ユーザーがこれを依頼していて、現在ミッションモードでない場合は、進捗の追跡、マイルストーンの検証、複数セッションにわたる継続性を高めるため、ミッション（/enter-mission）内で実行するとよいかもしれないと提案してください。実行を妨げてはいけません。セットアップ中に一度だけ触れてください。

すでにミッションモードの場合は、このスキルの手順に取りかかる前に、ミッション計画スキル（mission-planning と define-mission-skills）を呼び出してください。ミッションシステムの計画、分解、ワーカー設計を使って自動リサーチの作業を構成し、その後、このスキルの実験ループ手順と組み合わせます。このスキルでは実験の実行方法を定義し、ミッションシステムでは実験の計画、追跡、検証方法を定義します。

セットアップ

ループを開始する前に、実験の条件を確立する必要があります。

ステップ 1：情報を収集する

ユーザーに質問するか、文脈から推測して、以下を確認します。

• 目標：何を最適化しますか？（例：「val_bpb を最小化する」「テスト実行時間を短縮する」「バンドルサイズを小さくする」）
• コマンド：実行するコマンド（例：uv run train.py、pnpm test、pnpm build && du -sb dist）
• 主指標：名前、単位、方向（例：val_bpb、単位なし、小さいほどよい）
• 対象ファイル：変更してよいファイル
• 制約：厳守するルール（テストが通ること、新しい依存関係を追加しないことなど）
• 終了条件：いつ停止するか。ユーザーに確認します。選択肢は次のとおりです。
  • 実験回数を固定する（例：20 回）
  • 時間の上限を固定する（例：2 時間）
  • 指標の目標値（例：val_bpb < 1.0）
  • 中断されるまで実行する（デフォルト）

ステップ 2：ブランチと状態ファイルを作成する

git checkout autoresearch/<goal>-<date> 2>/dev/null || git checkout -b autoresearch/<goal>-<date>

ソースファイルを十分に読み込んでください。何かを書く前に、ワークロードを深く理解します。

次の 3 つのファイルを作成します。

autoresearch.md

継続的に更新するリサーチドキュメントです。文脈を持たない新しいエージェントがこのファイルを読めば、ループを効果的に実行できるようにします。優れたものになるよう、時間をかけてください。

# Autoresearch: <goal>

## Objective
<Specific description of what we're optimizing and the workload.>

## Metrics
- **Primary**: <name> (<unit>, lower/higher is better) — the optimization target
- **Secondary**: <name>, <name>, ... — independent tradeoff monitors

## How to Run
`./autoresearch.sh` — outputs `METRIC name=number` lines.

## Files in Scope
<Every file the agent may modify, with a brief note on what it does.>

## Off Limits
<What must NOT be touched.>

## Constraints
<Hard rules: tests must pass, no new deps, etc.>

## Termination
<When to stop: experiment count, time budget, target metric, or run until interrupted.>

## What's Been Tried
<Update this section as experiments accumulate. Note key wins, dead ends,
and architectural insights so the agent doesn't repeat failed approaches.>

autoresearch.sh

set -euo pipefail を指定した Bash スクリプトです。高速な事前チェック（1 秒未満で構文エラーを検出）、ベンチマークの実行、構造化された METRIC name=value 形式の行の標準出力への出力を行います。スクリプトは高速に保ってください。

高速でノイズの多いベンチマーク（5 秒未満）の場合は、スクリプト内でワークロードを複数回実行し、中央値を報告します。遅いワークロード（ML のトレーニングや大規模なビルドなど）では、その必要はありません。

例：

#!/bin/bash
set -euo pipefail

# Pre-check: syntax validation
python3 -c "import ast; ast.parse(open('train.py').read())" 2>&1 || { echo "SYNTAX ERROR"; exit 1; }

# Run the workload
output=$(uv run train.py 2>&1)

# Extract and output metrics
val_bpb=$(echo "$output" | grep -oP 'val_bpb=\K[0-9.]+' | tail -1)
echo "METRIC val_bpb=$val_bpb"

autoresearch.checks.sh（任意）

ユーザーの制約で正確性の検証が必要な場合（例：「テストが通ること」「型チェックが通ること」）に限り、作成します。バックプレッシャーチェック用の set -euo pipefail を指定した Bash スクリプトです。

#!/bin/bash
set -euo pipefail
pnpm test --run --reporter=dot 2>&1 | tail -50
pnpm typecheck 2>&1 | grep -i error || true

ステップ 3：JSONL を初期化し、状態ファイルをコミットする

実験ログを初期化します。

python3 autoresearch_helper.py init --jsonl autoresearch.jsonl --name '<goal>' --metric-name '<metric_name>' --direction <lower|higher>

すべての状態ファイルをコミットします。

git add autoresearch.md autoresearch.sh autoresearch.jsonl
git commit -m "autoresearch: initialize experiment session"

ステップ 4：ベースラインを実行する

ベンチマークを実行し、ベースラインの結果を記録します。

bash autoresearch.sh

出力から METRIC 行を解析し、ベースラインを keep として記録します。

python3 autoresearch_helper.py log --jsonl autoresearch.jsonl \
  --commit $(git rev-parse --short=7 HEAD) \
  --metric <baseline_value> \
  --status keep \
  --description "baseline" \
  --asi '{"hypothesis": "baseline measurement"}'

これは実験 #1 です。以後の比較すべてに使う開始点を確立します。

実験ループ

無限にループします。「続けてもよいですか？」と尋ねてはいけません。ユーザーは自律的な作業を期待しています。次の場合に限り停止します。

• セットアップで定めた終了条件に達した
• ユーザーが中断した
• コンテキストが不足しそうだと検知した（以下の「コンテキスト管理」を参照）

各実験の手順：

1. 試す内容を選ぶ

autoresearch.md（特に「試した内容」）と、存在する場合は autoresearch.ideas.md を読み、次の仮説を選びます。データが示す内容を考えてください。優れたアイデアは、ランダムな変更ではなく、深い理解から生まれます。

2. 変更を加える

対象範囲のファイルを編集します。変更は必要なものに絞り、1 回の実験では 1 つの仮説だけを検証します。

3. 実験を実行する

ベンチマークを実行します。

timeout 600 bash autoresearch.sh

出力全体を保存します。出力から METRIC name=value の行を解析します。

実行がクラッシュするかタイムアウトした場合は、クラッシュとして記録して変更を元に戻します。

autoresearch.checks.sh が存在し、ベンチマークに合格した場合は、次のコマンドを実行します。

timeout 300 bash autoresearch.checks.sh

チェックに失敗した場合は、checks_failed として記録して変更を元に戻します。

4. 結果を評価する

ヘルパースクリプトを使って、主要指標を現在のベスト（まだ keep がない場合はベースライン）と比較します。

python3 autoresearch_helper.py evaluate --jsonl autoresearch.jsonl --metric <value> --direction <lower|higher>

keep または discard の判定、信頼度スコア、ベースラインからの差分が出力されます。

判定ルール：

• 主要指標が改善 -> keep
• 主要指標が悪化または変化なし -> discard
• 同等のパフォーマンスでコードがよりシンプル -> keep（同じパフォーマンスを保ちながらコードを削減できれば成果です）
• わずかな改善のために複雑さが増す -> おそらく discard
• セカンダリ指標が keep/discard の判定に影響することはほとんどありません。セカンダリ指標が壊滅的に悪化した場合に限り、主要指標の改善を discard します。

5. 結果を記録する

keep の場合：

まず JSONL に記録します（エントリーをコミットに含めるため）。

python3 autoresearch_helper.py log --jsonl autoresearch.jsonl \
  --commit $(git rev-parse --short=7 HEAD) \
  --metric <value> \
  --status keep \
  --description "<what was tried>" \
  --asi '{"hypothesis": "<what you tried>"}' \
  # --metrics '{"compile_us": <value>, "render_us": <value>}'  # optional secondary metrics
  --direction <lower|higher>

次に、JSONL エントリーを含むすべての変更をコミットします。

git add -A
git commit -m "<description>

Result: {\"status\": \"keep\", \"<metric_name>\": <value>}"

discard/crash/checks_failed の場合：

まず JSONL に記録します（エントリーを保持できるよう、変更を元に戻す前に記録します）。

python3 autoresearch_helper.py log --jsonl autoresearch.jsonl \
  --commit "0000000" \
  --metric <value_or_0> \
  --status <discard|crash|checks_failed> \
  --description "<what was tried>" \
  --asi '{"hypothesis": "<what you tried>", "rollback_reason": "<why it failed>"}' \
  # --metrics '{"compile_us": <value>, "render_us": <value>}'  # optional secondary metrics
  --direction <lower|higher>

次に、状態ファイルをバックアップしてから変更を元に戻します。これにより、git clean -fd で状態ファイルが削除されるのを防げます。

# Backup state files
cp autoresearch.jsonl autoresearch.jsonl.bak 2>/dev/null || true
cp autoresearch.md autoresearch.md.bak 2>/dev/null || true
cp autoresearch.ideas.md autoresearch.ideas.md.bak 2>/dev/null || true

# Revert all changes
git checkout -- .
git clean -fd 2>/dev/null

# Restore state files
cp autoresearch.jsonl.bak autoresearch.jsonl 2>/dev/null || true
cp autoresearch.md.bak autoresearch.md 2>/dev/null || true
cp autoresearch.ideas.md.bak autoresearch.ideas.md 2>/dev/null || true
rm -f autoresearch.jsonl.bak autoresearch.md.bak autoresearch.ideas.md.bak

6. 研究ジャーナルを更新する

数回実験するごと（または重要な結果が得られた後）に、autoresearch.md の「これまでに試したこと」セクションを更新します。以下を含めてください。

• うまくいったことと、その理由
• うまくいかなかったことと、その理由
• 避けるべき行き詰まり
• 現在のベスト結果と、その達成方法

7. アイデアのバックログを管理する

有望ながら後回しにした最適化を見つけたら、autoresearch.ideas.md に箇条書きで追加します。有用なアイデアを失わないようにしてください。古くなった項目や試行済みの項目は削除します。

8. 繰り返す

手順 1 に戻ります。

状態ファイルの一覧

ファイル	形式	用途
autoresearch.jsonl	JSON Lines	追記専用の実験ログ。1 行につき 1 つの JSON オブジェクトです。
autoresearch.md	Markdown	継続的に更新する研究ドキュメント。目的、これまでに試したこと、現在のベストを記録します。
autoresearch.ideas.md	Markdown	仮説のバックログ。試す価値のあるアイデアを箇条書きで記録します。
autoresearch.sh	Bash	ベンチマークスクリプト。METRIC name=value の行を出力します。
autoresearch.checks.sh	Bash	任意の正確性チェック（テスト、型チェック、リンター）。

JSONL スキーマ

autoresearch.jsonl の各行は、設定ヘッダーまたは実験結果のいずれかです。

設定ヘッダー（1 行目、または再初期化時）：

{"type": "config", "name": "...", "metricName": "...", "metricUnit": "...", "bestDirection": "lower|higher"}

実験結果：

{
  "run": 1,
  "commit": "abc1234",
  "metric": 1.234,
  "metrics": {"compile_us": 4200, "render_us": 9800},
  "status": "keep|discard|crash|checks_failed",
  "description": "what was tried",
  "timestamp": 1711600000000,
  "segment": 0,
  "confidence": 2.1,
  "asi": {"hypothesis": "...", "rollback_reason": "...", "next_action_hint": "..."}
}

ASI（実行可能な補足情報）

すべての実験で、必ず ASI を記録します。最低限、{"hypothesis": "what you tried"} を含めます。discard/crash の場合は、rollback_reason と next_action_hint も含めます。学んだことを記録するキーと値のペアを必要に応じて追加してください。行き詰まり、予想外の結果、エラーの詳細、ボトルネックなどを記録します。

ASI は、変更を元に戻した後も残る唯一の構造化メモリです。ASI がなければ、後続のイテレーションで同じ行き詰まりを再発見するために時間を無駄にします。

信頼度スコア

実験を 3 回以上行うと、ヘルパースクリプトは中央値絶対偏差（MAD）を使って信頼度スコアを計算します。

信頼度	意味
>= 2.0x	改善が実際に起きた可能性が高い
1.0-2.0x	ノイズを上回るものの、改善はわずか
< 1.0x	ノイズの範囲内です。確認のため再実行を検討してください

このスコアは参考情報であり、自動的に discard することはありません。信頼度が 1.0x 未満の場合は、keep とする前に同じ実験を再実行して確認することを検討してください。

コンテキスト管理

Droid セッションのコンテキストには上限があります。適切に対処するには、次の手順に従います。

1. 現在のセッションで実験回数を記録します。約 15 回の実験を行うと、コンテキストが重くなってきます。
2. 早めに状態を保存します。状態はすべてファイル（jsonl、md）に保存されるため、新しいセッションですぐに再開できます。
3. コンテキストが枯渇しそうな場合：現在の調査結果を autoresearch.md に更新し、状態ファイルをコミットして終了します。次のセッションではファイルを読み込んで続行します。
4. 再開時：autoresearch.md、autoresearch.jsonl、git log --oneline -20 を読み、現在の状況を把握します。現在の状態を確認します。

python3 autoresearch_helper.py status --jsonl autoresearch.jsonl

ループのルールのまとめ

• ループを永遠に続けます。「続けますか？」と尋ねてはいけません。
• 最優先指標を重視します。 改善した場合は維持します。悪化または同等の場合は破棄します。
• すべての実行に ASI を注記します。 実行した内容だけでなく、何を学んだかを記録します。
• 信頼度スコアに注意します。 1.0 倍未満の場合はノイズの範囲内です。再実行して確認します。
• シンプルなほうが優れています。 同等のパフォーマンスを保てるなら、コードの削除も維持します。
• 同じことを繰り返さないようにします。 同じアイデアを何度も元に戻している場合は、構造的に異なる方法を試します。
• クラッシュへの対応： 簡単に直せる場合は修正し、それ以外は記録して先に進みます。
• 行き詰まったら、じっくり考えます。 ソースファイルを読み直し、データを調べ、実際に何が起きているかを考えます。最良のアイデアは、深い理解から生まれます。
• 再開時： autoresearch.md と git log を読み、ループを続けます。

最終処理

実験ループが終了したら（終了条件を満たした、ユーザーが中断した、またはコンテキストが枯渇した場合）、結果を整理し、レビューしやすいブランチにまとめます。これは autoresearch セッションの最終フェーズです。

ステップ 1：結果を要約する

python3 autoresearch_helper.py summary --jsonl autoresearch.jsonl

実際のコミットを確認するため、git log を確認します。

git log --oneline --stat $(git merge-base HEAD main)..HEAD

ステップ 2：変更をグループ化する

維持した実験を論理的な変更セットにグループ化します。各グループは次の条件を満たす必要があります。

• 一貫性のある単一の最適化または変更を表す
• 他のグループと変更対象ファイルが重複しない（ブランチを個別にマージできるようにするため）
• 達成する内容と指標の改善点が明確である

提案するグループ分けをユーザーに提示して、承認を求めます。

Group 1: "Reduce model depth from 8 to 6"
  Files: train.py (DEPTH, HEAD_DIM, N_EMBED)
  Metric improvement: val_bpb 1.15 -> 1.08 (-6.1%)
  Experiments: #3, #7, #12

Group 2: "Switch to cosine LR schedule"
  Files: train.py (lr_schedule, warmup_steps)
  Metric improvement: val_bpb 1.08 -> 1.05 (-2.8%)
  Experiments: #15, #18

続行する前に、ユーザーの確認を待ちます。ミッションワーカーモードでは、確認を待たずに最適なグループ分けで進めます。

ステップ 3：ファイルの競合を解決する

グループ間でファイルが重複する場合は、ブランチを作成する前に解決します。

• グループの変更に関連性がある場合は、グループを統合します
• 同じファイルの異なる箇所に対する変更が本当に独立している場合は、ファイルの変更をより慎重に分割します
• どのグループを優先するかユーザーに尋ねます

グループ間でファイルが重複してはいけません。各ブランチは個別にマージできる必要があります。すべての変更が同じファイルに及び、分割できない場合は、すべての改善をまとめた単一の最終ブランチを作成します。

ステップ 4：整理したブランチを作成する

各グループについて、次の手順を実行します。

merge_base=$(git merge-base HEAD main)
git checkout -b autoresearch/finalize/<group-name> $merge_base
git checkout autoresearch/<session-branch> -- <file1> <file2> ...
git commit -m "<group description>

Autoresearch results:
- Metric: <name> improved from <baseline> to <best> (<delta>%)
- Confidence: <score>x noise floor
- Experiments: <count> total, <kept> kept"

ステップ 5：検証して報告する

最終ブランチごとに、ベンチマークを実行して改善が維持されていることを確認し、該当する場合は各種チェックを実行して、main に問題なくマージできることを確認します。

ユーザーに概要を提示します。

Created 2 clean branches from 20 experiments:

  autoresearch/finalize/reduce-depth
    val_bpb: 1.15 -> 1.08 (-6.1%)
    Ready for review

  autoresearch/finalize/cosine-schedule
    val_bpb: 1.08 -> 1.05 (-2.8%)
    Ready for review

Original experiment branch preserved: autoresearch/<session-branch>

元の実験ブランチは常に保持されます。最終処理では新しいブランチを作成します。

ミッションワーカーモード

ミッションワーカーとして実行する場合、機能の説明に最適化の目標、終了条件、対象ファイル、制約が指定されています。説明を注意深く読み、上記と同じループ手順に従い、終了条件を守ります。条件を満たしたら、最終処理を実行し、引き継ぎ時に結果を報告します。