autoresearch

Autoresearch

自律的な最適化が有用なのは、ベンチマークで賭けをするのではなく、規律ある研究として進められる場合に限られます。

このスキルでは、厳格な実験ループを実行します。

• コードを変更する前に目標を明確にする
• テストの前に仮説を書き留める
• 一度きりの成功ではなく、繰り返し試行して測定する
• 失敗を含むすべての実験を記録する
• チェックインされないローカルレポートとグラフを生成する

基本原則

1. スコープを暗黙に推測しない

依頼が曖昧な場合は、開始前に簡潔な質問をして確認します。対象とするワークロード、正しさの基準、トレードオフを黙って作り上げてはいけません。

2. 実験1つにつき仮説1つ

変更を加える前に、提案する変更と、それが有効な理由を述べます。無関係な調整をまとめて行うのは避けます。

3. すべての実験を記録する

破棄したアイデア、クラッシュ、チェックの失敗も含め、すべての実験を機械可読な台帳に列挙する必要があります。

4. 繰り返し測定は、ノイズの多い逸話に勝る

1回の速い実行だけを理由に変更を採用してはいけません。ウォームアップと繰り返し測定を行い、明示的な判定ルールを設けます。

5. 成果物はローカルに保管する

レポート、CSV、JSONL 台帳、グラフはローカルの .autoresearch/ ディレクトリに保存し、コミットしてはいけません。

利用可能なスクリプト

• scripts/init_experiment.py — .autoresearch/session.json を初期化し、.autoresearch/ が未追跡のままになるようにし、必要に応じて autoresearch.md のひな形を作成します。
• scripts/run_experiment.py — ウォームアップと測定試行を実行し、METRIC 行を解析し、オプションのチェックを実行して、JSON 形式の実験記録を出力します。
• scripts/log_experiment.py — 実験を .autoresearch/results.jsonl に追記し、keep と discard のどちらにするか判定して、CSV と HTML の成果物を更新します。
• scripts/render_report.py — JSONL 台帳から .autoresearch/results.csv と .autoresearch/report.html を再生成します。

すべてのスクリプトは非対話型で、--help を利用でき、標準出力には構造化 JSON を出力し、診断情報は標準エラー出力に表示します。

デフォルトのワークフロー

1. 事前の Q&A の後にセッションを初期化します。

   python3 scripts/init_experiment.py \
     --goal "Reduce latency in hot path" \
     --metric-name latency_ms \
     --unit ms \
     --direction lower \
     --command ./autoresearch.sh \
     --checks-command ./autoresearch.checks.sh \
     --scope src/hot_path.ts
   

2. ベースラインを記録します。

   # Option A: save to file first, then log
   python3 scripts/run_experiment.py \
     --id baseline \
     --hypothesis "Control run" \
     --change-summary "No code changes" \
     --baseline \
     --output .autoresearch/baseline.json
   python3 scripts/log_experiment.py --input .autoresearch/baseline.json
   
   # Option B: pipe directly
   python3 scripts/run_experiment.py \
     --id baseline \
     --hypothesis "Control run" \
     --change-summary "No code changes" \
     --baseline \
     | python3 scripts/log_experiment.py
   

3. 候補となる各実験を記録します。

   python3 scripts/run_experiment.py \
     --id exp-001 \
     --hypothesis "Inlining removes allocation churn" \
     --change-summary "Inline helper and pre-size buffer" \
     --output .autoresearch/exp-001.json
   python3 scripts/log_experiment.py --input .autoresearch/exp-001.json
   

4. 必要に応じて成果物を再生成します。

   python3 scripts/render_report.py
   

事前の Q&A

開始前に、以下のすべてを確認または確定します。不明確な点や不足している項目があれば、まず要点を絞った質問をします。

1. 目的 — 何を最適化しますか？
2. 主要指標 — 正確な名称と単位、値が低いほどよいのか高いほどよいのか
3. 意味のある最小改善幅 — ユーザーが指定しない場合は、デフォルトで 1% とします
4. ワークロードコマンド — 実際の状況を表す正確なコマンドまたはスクリプト
5. 正しさのゲート — テスト、型チェック、リンター、評価セット、精度の下限、その他の必須条件
6. スコープ — 変更してよいファイルと、変更してはいけないファイル
7. 予算 — ユーザーが設定している場合の時間予算、計算資源の予算、または停止条件

ユーザーが「とにかく進めて」と言った場合は、最初の実験の前に前提を autoresearch.md に明記し、その後 python3 scripts/init_experiment.py ... で設定します。

ワークスペースのセットアップ

1. 新しいブランチに専用のワークツリーを作成することを推奨します。

   git worktree add ../autoresearch-<goal>-<date> -b autoresearch/<goal>-<date>
   

   ワークツリーの使用が現実的でない場合は、クリーンな作業ツリーで新しいブランチを使います。無関係なユーザー変更があるダーティーな作業ツリーでは、このスキルを実行しないでください。

2. 次のものを作成します。

   • autoresearch.md — チェックインする、永続的なセッション概要
   • autoresearch.sh — チェックインする、ベンチマーク実行スクリプト
   • autoresearch.checks.sh — 正しさのゲートが必要な場合にのみチェックインする
   • .autoresearch/ — チェックインしないローカル成果物ディレクトリ

3. ローカル成果物が未追跡のままになるようにします。

   rg -qxF '.autoresearch/' .git/info/exclude || printf '\n.autoresearch/\n' >> .git/info/exclude
   

4. 正確なインターフェースを確認する必要がある場合は python3 scripts/init_experiment.py --help を実行します。その後、セッションを初期化し、python3 scripts/run_experiment.py ... でベースラインを収集し、コードを変更する前に python3 scripts/log_experiment.py ... で記録します。

必須ファイル

autoresearch.md

これはセッションの永続的な契約です。新しいエージェントが推測に頼らず再開できるようにします。

# Autoresearch: <goal>

## Objective
<What is being optimized and why it matters.>

## Up-Front Answers
- Primary metric:
- Unit:
- Direction:
- Minimum meaningful improvement:
- Workload command:
- Correctness gates:
- Budget / stop criteria:

## Scope
- In scope:
- Off limits:

## Decision Rule
<How many warmups, how many measured trials, how "keep" is decided.>

## Experiment Ledger
`.autoresearch/results.jsonl`

## Report Outputs
- `.autoresearch/report.html`
- `.autoresearch/results.csv`
- `.autoresearch/plots/`

## Current Best Result
<Best known baseline or kept variant.>

## What We've Learned
<Key wins, dead ends, confounders, and structural insights.>

前提が変わったとき、新たな最良結果が得られたとき、またはパターンが明らかになったときは、autoresearch.md を更新してください。

autoresearch.sh

set -euo pipefail を指定した Bash スクリプトです。次の処理を行います。

• 非常に高速な事前チェックのみを実行する
• 実際のベンチマーク処理を実行する
• 解析可能な METRIC name=value 行を出力する
• 実験間で安定性を保ち、実行結果を比較可能にする

できる限り小さく、決定性の高いものにしてください。ベンチマークのプロトコルを変更する場合は、その内容を autoresearch.md に記録し、新しいベースラインを設定してください。

autoresearch.checks.sh

セッションに正確性ゲートがある場合は、これを作成してください。次の要件を満たす必要があります。

• 候補がベンチマークに合格した後に正確性を検証する
• 主指標の計測時間に影響しない
• 出力を短く、エラーに焦点を当てる
• 候補を安全に維持できない場合は、確実に失敗させる

チェックに失敗した場合、実験の判定は keep ではなく checks_failed です。デフォルトのスクリプトワークフローがこれを自動的に処理します。

ローカル成果物の契約

以下はすべて .autoresearch/ に置き、バージョン管理対象外のままにしてください。

.autoresearch/results.jsonl

実験ごとに JSON オブジェクトを 1 つ追記します。すべての実験を列挙する際の信頼できる情報源です。

必須フィールド：

{
  "id": "exp-007",
  "timestamp": "2026-03-14T13:00:00Z",
  "hypothesis": "Inlining X removes allocation churn in hot path Y.",
  "change_summary": "Inline helper and pre-size buffer.",
  "files_touched": ["src/hot_path.ts"],
  "baseline_commit": "abc1234",
  "candidate_ref": "def5678",
  "metric_name": "latency_ms",
  "direction": "lower",
  "warmup_trials": [12.8, 12.7],
  "measured_trials": [11.9, 12.0, 11.8, 11.9, 12.1],
  "summary": {
    "median": 11.9,
    "mean": 11.94,
    "min": 11.8,
    "max": 12.1
  },
  "secondary_metrics": {
    "memory_mb": 84.1
  },
  "checks": "passed",
  "disposition": "keep",
  "reason": "Median improved by 5.2%, checks passed, complexity acceptable."
}

.autoresearch/results.csv

各実験の後、または定期的に、JSONL をスプレッドシートで扱いやすい形式の概要に変換します。

.autoresearch/report.html

セッションを可視化する HTML レポートを生成します。最低限、次の内容を含めてください。

• すべての実験と判定を列挙する表
• 時間経過に伴う主指標
• これまでの最良値の推移
• 実験ごとの計測試行の分布
• チェックの合格・失敗・クラッシュの件数
• 維持した改善と破棄したアイデアの概要

.autoresearch/plots/

レポートで外部アセットを使用する場合は、生成したグラフやエクスポートした画像をここに保存します。

実験カード

各実験の前に、autoresearch.md または一時的なメモに簡潔な実験カードを記入します。

• id
• hypothesis
• planned change
• why this should affect the metric
• files expected to change
• predicted direction and rough magnitude
• rollback plan

変更が有効な理由を説明できない場合は、まだ実験を実行しないでください。

計測プロトコル

ユーザーがより厳格な条件を指定しない限り、次のデフォルトを使用します。

1. 最初にウォームアップする

   • 判定に使用しないウォームアップ試行を少なくとも 2 回実行します。

2. 繰り返し計測する

   • ベースラインと各有力候補について、計測試行を少なくとも 5 回実行します。
   • ノイズが大きい場合や改善幅がわずかな場合は、サンプル数を増やします。結果が曖昧なまま受け入れてはいけません。

3. 堅牢に要約する

   • 判定の主統計量には中央値を使用します。
   • ばらつきを把握できるよう、平均、最小値、最大値も記録します。

4. 事前に定めたしきい値を適用する

   • 変更を維持するのは、現在の最良値を最低限意味のある改善しきい値以上に上回り、すべての正確性チェックに合格した場合に限ります。

5. 必要に応じてベースラインをリセットする

   • ワークロード、マシンの条件、データセット、またはベンチマークハーネスが大幅に変わった場合は、新しいベースラインを設定し、その理由を記録します。

判定ルール

• keep

  • 宣言した指標の方向において、候補が現在の最良値を上回る
  • 改善幅が最低限意味のある改善しきい値を超える
  • 正確性チェックに合格する
  • 必須の副次指標に許容できない悪化がない

• discard

  • 候補の結果が悪い
  • 候補の結果が実質的に同等である
  • 結果のノイズが大きく、確信を持てない
  • 複雑さの増加に見合う改善がない

• checks_failed

  • ベンチマークの結果は改善した可能性があるが、必須の正確性ゲートに失敗した

• crash

  • 候補によってワークロードが壊れた、または信頼できる計測ができなかった

有望に思えるからという理由で、曖昧な結果を keep に格上げしてはいけません。

ループの動作

自律的に実行しますが、学習せずにいつまでも続けてはいけません。次のいずれかに当てはまるまで続けます。

• 時間または計算リソースの予算を使い切った
• 異なる仮説をいくつか試しても、有意な改善が見つからなかった
• 有望なアイデアをすべて試し尽くした
• ユーザーが作業を中断または方向転換した

ループ中は、次の点に従ってください。

• 一度に行う変更は、意味のあるものを一つにする
• 失敗した同じアイデアを、表面的に変えて再試行することは避ける
• 行き詰まった案を記録し、後続のエージェントが繰り返さないようにする
• 実験の合間はワークツリーをクリーンな状態に保つ

候補を破棄するときは、次のアイデアに取りかかる前に、隔離されたワークツリー内で最後にコミットした正常な状態に戻してください。

よくある落とし穴

Autoresearch は規律ある経験主義に基づいていますが、長時間にわたる最適化ループでは、いくつかの失敗パターンが生じます。こうしたパターンを知っておくことで、無駄な実験やワークフローの破損を防げます。

1. 最適化が頭打ちになっても実験ループが終了しない

症状：

• 最後に改善してから何サイクルも、新しい実験を続けてしまう
• 明確な終了点がなく、10～15回の実験後にループの方向性を見失う
• 新たな知見が得られないまま、時間や計算リソースの予算を使い切る

根本原因：

• 予算の使い切り以外の終了条件が設定されていない
• 学習曲線が飽和していないか確認せず、「実験を増やせば知識も増える」とエージェントが考えてしまう
• 仮説のパターンの重複や、収益逓減を体系的に検出できていない

対策：

• autoresearch.md に頭打ちのしきい値を設定します。改善がない実験が N 回連続したら停止します。例：「3 回連続で改善率が 0.5% 未満の場合は停止する」
• 仮説の多様性を追跡します。新しい仮説が過去のアイデアの言い換えにすぎない場合は、停止して学びを記録します
• 移動ウィンドウのヒューリスティックを導入します。直近 5 回の実験における改善速度を計算し、実験あたりの改善速度が 0.1% 未満になったら停止します
• 早期終了する際は、停止理由を autoresearch.md に明記します

2. 5～10 回の反復後、仮説の生成が反復的になる

症状：

• 後半の実験が、それ以前のアイデアの小さなバリエーションになる（例：「バッファーサイズを 16、32、24 にする」）
• 仮説に、明確に異なる因果関係の説明がなく、定数の調整に終始する
• 結果のばらつきが小さくなっても、明確な勝者が現れない

根本原因：

• 根本原因について立ち止まって考えず、エージェントが局所的な勾配降下を既定の方針にしている
• 明示的な仮説の一覧や、新規性を相互確認する仕組みがない
• 細かな最適化に取り組む前に、仮説空間を十分に探索していない

対策：

• 各実験の前に、「なぜこれで指標が改善するのか？」に答える形で仮説を書きます。答えが「つまみを回しているから」であれば、いったん止まり、まず別の方向性を考えます
• 行き詰まった案を記録します。実験を破棄する際は、失敗した理由を明記し、後続の仮説が同じ道をたどらないようにします
• 仮説の種類を 3～4 回の実験ごとに切り替えます。
  • アルゴリズムの変更（例：ハッシュテーブルをスキップリストに置き換える）
  • データ構造の変更（例：事前割り当て、レイアウト）
  • 制御フローの変更（例：分岐予測、ループのアンローリング）
  • 外的要因（例：コンパイラーフラグ、サンプリングレート）
• チェックポイントを設けて振り返ります。5 回実験したら、autoresearch.md を読み返し、重要な知見を 2～3 個まとめた「分かったこと」セクションを明示的に書きます。そのセクションが空なら、堂々巡りになっています

3. 長時間実行するとログファイルが際限なく増える

症状：

• 50 回以上実験すると、.autoresearch/ ディレクトリのサイズが数十〜数百 MB に膨らみます
• python3 scripts/render_report.py の実行時間が、時間とともに明らかに長くなります
• リソースが限られたマシンでは、ディスク使用量が運用上の問題になります

根本原因：

• 各実験で完全な JSON レコードが生成され、レコードが削除されることはありません
• 測定結果に詳細なデバッグ出力やトレースが含まれると、JSONL に蓄積されます
• HTML レポートにすべての生データがインラインで埋め込まれ、ファイルサイズが数 MB になることがあります

対策：

• 定期的にアーカイブする：実験を 20 回行うごとに、古い結果を .autoresearch/archive/YYYYMMDD-run-N.jsonl にアーカイブし、新しい results.jsonl で再開します
• 測定出力を制限する：autoresearch.sh で詳細なログを出力せず、METRIC 行だけを取得するようにします
• 生のトレースではなくサマリーを保存する：容量が重要な場合は、results.jsonl にすべての試行値を記録する代わりに、{"summary": {...}, "median": X} を記録します
• アーカイブについて autoresearch.md に記録する：台帳をアーカイブした日時と、過去の実行結果へのアクセス方法を記載します
• アーティファクトのサイズを監視する：ループに次のチェックを追加します：du -sh .autoresearch/ | grep -qE '[0-9]+M' && echo "WARNING: artifact directory >100MB"

4. 実験が 100 件を超えると HTML レポートが正しく表示されない

症状：

• 多数の実験後に .autoresearch/report.html を開くと、ブラウザーの動作が遅くなるか、応答しなくなります
• グラフが表示されないか、一部のデータしか表示されません
• ページサイズが 50 MB 以上に膨らみ、共有やバージョン管理が実用的でなくなります

根本原因：

• render_report.py は、すべてのデータをインラインで含む単一の巨大な HTML ファイルを生成します
• JavaScript のグラフ描画ライブラリは、ページネーションや遅延読み込みなしでは 100 件を超えるデータポイントを処理できません
• 大規模な結果セットに対する切り詰めやサマリーモードがありません

対策：

• 結果をページ分割する：実験台帳を 50 件ずつに分割し、ナビゲーションリンク付きの個別レポートページ（report-01.html、report-02.html など）を生成します
• 大規模な実行ではサマリーモードを使う：len(results) > 100 の場合は、次の内容を含む簡潔なレポートを生成します：
  • 採用した実験のみを含む表（discard、crash、checks_failed を除外）
  • すべての個別ポイントではなく、最良値の推移を示す折れ線
  • 実験ごとの分布ではなく、フェーズごとの統計サマリー
• 大容量データを JSON に分離する：完全な結果セットを含む .autoresearch/data.json を用意し、HTML からクライアント側レンダリングで参照することで、HTML 自体を 1 MB 未満に保ちます
• 自動検出して警告する：render_report.py で結果数が 100 を超える場合は、次のログを出力します："WARNING: report contains >100 experiments; consider archiving old runs or using --summary-mode"

---

レポートの生成

.autoresearch/report.html を定期的に生成または更新し、セッションの終了時には必ず更新します：

python3 scripts/render_report.py

レポートでは、次の点に答える必要があります：

• どのような実験を試したか
• どの実験が成功、失敗、クラッシュしたか
• 最良の指標が時間とともにどのように変化したか
• 二次指標にどのようなトレードオフが現れたか
• 最終的に推奨する変更と、その理由

高機能なグラフ描画が難しい場合は、インライン SVG グラフまたは軽量なローカルアセットを使ったシンプルな静的 HTML ファイルを生成します。レポートでは、見た目より内容が重要です。

再開時の動作

再開するときは：

1. autoresearch.md を読む
2. .autoresearch/results.jsonl を確認する
3. .autoresearch/report.html が存在する場合は確認する
4. 採用したコミットについて Git の履歴を確認する
5. 古くなった想定ではなく、把握済みの最良の状態から続行する

実験中のユーザーメッセージ

実験の実行中にユーザーからメッセージが届いた場合、短時間で安全に完了できるなら、現在の測定サイクルを完了してから応答します。実行に時間がかかる場合やリスクがある場合は、最も近い安全なチェックポイントで停止して返信します。