Autoresearch: 自動反復実験

任意のプログラミングタスク用の自動実験ループです。ゴールと測定方法を定義すれば、エージェントが自動的に反復します。コード変更、実験実行、結果測定、変更の保持または破棄を繰り返します。

このスキルは Karpathy の autoresearch に触発されており、ML トレーニングから測定可能な結果を持つあらゆるプログラミングタスクへと一般化されています。

---

エージェント動作ルール

1. DO ループ開始前に、セットアップフェーズをインタラクティブにユーザーをガイドする。
2. DO 変更を加える前にベースライン測定を確立する。
3. DO 実験実行前にすべての試験をコミットする（クリーンに戻せるようにするため）。
4. DO 結果ログ（TSV）を保持して、すべての実験を追跡する。
5. DO メトリクスを改善しない変更を戻す（最後の既知の良い状態に git reset する）。
6. DO ループが開始したら自動的に実行する。「続けるべきか？」と聞かない。
7. DO NOT ユーザーがスコープ外としてマークしたファイルを変更する。
8. DO NOT 測定ステップをスキップする。すべての実験は測定される必要がある。
9. DO NOT ユーザーが明示的にトレードオフを許可していない限り、メトリクスを低下させる変更を保持する。
10. DO NOT ユーザーが承認していない限り、新しい依存関係をインストールしたり環境変更を行わない。

---

フェーズ 1: セットアップ（インタラクティブ）

実験が始まる前に、これらのパラメータを確立するためにユーザーと協力します。 各項目について直接ユーザーに質問してください。推測やスキップは行わないでください。

1.1 ゴールの定義

ユーザーに質問してください：

あなたが改善または最適化しようとしているものは何ですか？

例：実行時間、メモリ使用量、バイナリサイズ、テストパス率、コードカバレッジ、 API 応答レイテンシ、スループット、エラー率、ベンチマークスコア、ビルド時間、バンドルサイズ、 コード行数、循環複雑度など。

ユーザーの回答をゴールとして記録してください。

1.2 メトリクスの定義

ユーザーに質問してください：

成功をどのように測定しますか？メトリクスを生成する正確なコマンドは何ですか？

必要な情報：

1. 実行するコマンド（例：dotnet test、npm run benchmark、time ./build.sh、pytest --tb=short）
2. 出力からメトリクスを抽出する方法（例：正規表現パターン、特定の行、JSON フィールド）
3. 方向性：低いほうがいいか、高いほうがいいか？

例：「dotnet test --logger trx を実行し、合格テストを数えます。高いほうがいいです。」 例：「hyperfine './my-program' を実行し、平均時間を抽出します。低いほうがいいです。」

記録する項目：

• METRIC_COMMAND：実行するコマンド
• METRIC_EXTRACTION：出力から数値メトリクスを抽出する方法
• METRIC_DIRECTION：lower_is_better または higher_is_better

1.3 スコープの定義

ユーザーに質問してください：

どのファイルまたはディレクトリを変更することを許可していますか？

そして、どのファイルは禁止（読み取り専用）ですか？

記録する項目：

• IN_SCOPE_FILES：エージェントが編集可能なファイル/ディレクトリ
• OUT_OF_SCOPE_FILES：変更してはいけないファイル/ディレクトリ

1.4 制約の定義

ユーザーに質問してください：

私が尊重すべき制約はありますか？

例：

• 実験ごとの時間予算（例：「各実行は 2 分以下」）
• 新しい依存関係なし
• すべての既存テストが合格している必要があります
• 公開 API を変更してはいけない
• 後方互換性を維持する必要がある
• VRAM/メモリ制限
• コード複雑度の制限（よりシンプルなソリューションを優先）

CONSTRAINTS として記録してください。

1.5 実験予算の定義（オプション）

ユーザーに質問してください：

何回の実験を実行すべきか、それとも、あなたが停止させるまで実行し続けるべきか？

数字を言うことも（例：「20 回の実験を試す」）、「無制限」（あなたが中断させるまで実行する）と言うこともできます。

MAX_EXPERIMENTS（数字または unlimited）として記録してください。

1.6 シンプリシティ基準

デフォルトのシンプリシティポリシーをユーザーに通知してください：

シンプリシティポリシー（デフォルト）： その他の条件が同じであれば、シンプルなほうがいいです。 醜い複雑さを追加する小さな改善は価値がありません。コードを削除しながらメトリクスを維持または改善するのは 素晴らしい結果です。複雑さのコストと改善の大きさを比較検討します。このポリシーで問題ありませんか？ それとも調整したいですか？

調整事項を SIMPLICITY_POLICY として記録してください。

1.7 セットアップの確認

すべてのパラメータを見やすいテーブルでユーザーに要約してください：

パラメータ	値
ゴール	...
メトリクスコマンド	...
メトリクス抽出	...
方向性	低いほうがいい / 高いほう…
スコープ内ファイル	...
スコープ外ファイル	...
制約	...
最大実験数	...
シンプリシティポリシー	...

ユーザーに確認を求めてください。確認されるまで進まないでください。

---

フェーズ 2: ブランチ & ベースライン

ユーザーが確認したら：

1. ブランチを作成：本日の日付に基づくタグを提案します（例：autoresearch/mar17）。 ブランチを作成します：git checkout -b autoresearch/<tag>。

2. スコープ内ファイルを読む：現在の状態の完全なコンテキストを構築するために、スコープ内のすべてのファイルを読んでください。

3. results.tsv を初期化：リポジトリルートに results.tsv を作成してヘッダー行を付けます：

   experiment	commit	metric	status	description
   

   results.tsv と run.log を .git/info/exclude に追加します（既に存在する場合は追加）。追跡済みファイルを変更することなく追跡から外した状態を保ちます。

4. ベースラインを実行：修正されていない現在のコード上でメトリクスコマンドを実行します。 結果を実験 0 として、ステータス baseline で results.tsv に記録してください。

5. ベースラインをユーザーに報告：

   ベースライン確立：[metric_name] = [value] 自動実験ループを開始します。

---

フェーズ 3: 実験ループ

このループを連続実行します。ユーザーに質問するために停止しないでください。以下の場合まで実行してください：

• MAX_EXPERIMENTS に達した、または
• ユーザーが手動で中断した

各実験について：

ループ：
  1. 考える   - 前の結果と現在のコードを分析します。
               実験仮説を生成します。
               何が機能したか、何が機能しなかったか、何が未試行かを考慮してください。

  2. 編集する - スコープ内のファイルを変更してアイデアを実装します。
               実験ごとに変更は焦点を絞り、最小限にしてください。

  3. コミット - git add + 短い説明メッセージで git commit します。
               フォーマット："experiment: <変更内容の短い説明>"

  4. 実行する - メトリクスコマンドを実行します。
               出力を run.log にリダイレクトして、コンテキストウィンドウをあふれさせないようにします。
               シェルに適したリダイレクションを使用します：
               - Bash/Zsh: `<command> > run.log 2>&1`
               - PowerShell: `<command> *> run.log`

  5. 測定する - run.log からメトリクスを抽出します。
               抽出が失敗した場合（クラッシュ/エラー）、run.log の最後の 50 行を
               読んでエラーを確認してください。

  6. 決定する - メトリクスを現在の最高値と比較します：
               - 改善：コミットを保持します。「最高」のベースラインを更新します。
                 ステータス = "keep" をログに記録します。
               - 同じまたは悪化：戻します。`git reset --hard HEAD~1`。
                 ステータス = "discard" をログに記録します。
               - クラッシュ：簡単な修正を試みます（タイプミス、インポート、シンプルなエラー）。
                 実験コミットを修正します（`git commit --amend`）して再実行します。
                 実験は元の番号を保持します。
                 2 回の試行後に修復不可能な場合は、実験全体を戻します
                 （`git reset --hard HEAD~1`）し、ステータス = "crash" をログに記録します。

  7. ログする - results.tsv に行を追加します：
               experiment_number  commit_hash  metric_value  status  description

  8. 続行する - ステップ 1 に進みます。

実験戦略

実験アイデアを生成するときは、この優先順位に従ってください：

1. 低いハングニング果実から始める：シンプルなパラメータ調整、明らかな非効率性。
2. 結果からの情報：ある方向が有望性を示した場合、その方向をさらに探索します。
3. プラトーの後で多様化：最後の 3～5 実験がすべて失敗した場合、まったく別のアプローチを試してください。
4. 勝者を組み合わせる：実験 A と B がそれぞれ独立して改善した場合、それらの組み合わせを試してください。
5. シンプリフィケーションパス：定期的にコード/複雑度を削除してメトリクスが保持されるかを確認します。
6. ラディカルな変更：増分アイデアを使い果たした後、より大きな建築上の変更を試してください。

制約の処理

• 時間予算：実行が予想時間の 2 倍を超える場合は、それを終了し、クラッシュとして扱います。
• 既存テスト：制約がテスト合格を要求する場合、テストを実行し、合格しない場合は戻します。
• メモリ/リソース：監視し、リソース使用量が指定された制限を超える場合は戻します。

---

フェーズ 4: レポート

ループが終了したら（予算到達またはユーザーが中断）：

1. 完全な results.tsv をフォーマットされたテーブルとして出力します。
2. 要約：
   • 実行した実験の総数
   • 保持 / 破棄 / クラッシュした実験
   • 開始メトリクス（ベースライン）対最終メトリクス
   • 改善パーセンテージ
   • 最も影響力のあった変更トップ 3
3. 保持された実験の累積 git ログを表示： git log --oneline <start_commit>..HEAD
4. 次のステップを推奨：結果に基づいて、人間の研究者が次に試すかもしれないことを提案します（自動実験には危険すぎるまたは複雑すぎるアイデア）。

---

クイックリファレンス

Results TSV フォーマット

タブ区切り、5 列：

experiment	commit	metric	status	description
0	a1b2c3d	0.997900	baseline	unmodified code
1	b2c3d4e	0.993200	keep	increase learning rate to 0.04
2	c3d4e5f	1.005000	discard	switch to GeLU activation
3	d4e5f6g	0.000000	crash	double model width (OOM)

Git ワークフロー

• すべての実験は autoresearch/<tag> ブランチで行われます
• 各実験は実行前にコミットされます
• 失敗した実験は git reset --hard HEAD~1 で戻されます
• 成功した実験がブランチを進める
• results.tsv と run.log はまま追跡されません（.git/info/exclude に追加）

重要な原則

1. すべてを測定する：測定なしの実験なし。
2. 失敗を戻す：ブランチは改善時のみ進む。
3. 自動のままで：停止して質問しない。立ち往生した場合はより良く考える。
4. シンプルに保つ：複雑さはコスト。利益に対して検討する。
5. すべてをログする：TSV は研究ジャーナル。