autoresearch-setup

Autoresearch のセットアップ

概要

autoresearch ハーネスを使うと、LLM が固定の時間枠内で ML の問題に自律的に取り組み、反復できます。ファイルは次の 2 つに分かれています。

• harness.py — 固定。 データの読み込み、train/val の分割、固定の高速反復用サブセット、およびメトリックを管理します。LLM がこのファイルを編集することはありません。
• train.py — 変更可能。 モデル、オプティマイザー、スケジューラー、損失関数、トレーニングループを管理します。ハーネスの I/O 契約（build_spec → ExperimentSpec、eval_forward、train_fn）を守る限り、LLM は自由に書き換えられます。

基本原則：harness.py がデータとメトリックを管理し、編集されることはありません。train.py は契約の範囲内ですべてを管理します。 これにより、バリアント間やセッション間で結果を比較できます。不変のハーネスというルールの文言に違反することは、比較可能で信頼できる結果を得るというルールの精神に違反することになります。

ワークフロー

1. ブレインストーミングの関門（必須）

足場を組む前に、superpowers:brainstorming を呼び出し、次の 6 項目をすべて解決してください。

1. メトリック — およびその厳密な計算方法（予測値とターゲット値をどのように集約してスカラー値にするか）。
2. データ — ソース、train/val の分割、および固定の高速反復用サブセット。
3. I/O 契約 — ハーネスと train のインターフェース（eval_forward の出力形状）。
4. 時間枠 — バリアントごとの実時間。
5. 計算バックエンド — クラスター/GPU の構成（LocalMultiGPU と Sbatch のどちらか）。
6. 固定と編集可能の境界 — harness.py に含める内容を正確に定めます。

推測で決めたり、時間がないからといってこの関門を省略したりしないでください。「質問は飛ばして、急いでいる」というのは、推測してよい理由にはなりません。6 項目を手早く解決してください。推測に基づいて構築したハーネスでは比較できない無価値な実行結果が生まれます。関門を設けるより時間がかかるのではなく、むしろ時間を無駄にします。

2. 足場を組む

templates/ を合意した場所の対象プロジェクトにコピーしてから、次の作業を行います。

• harness.py、train.py、launcher.py、kernels.py の # TODO(autoresearch): マーカーを、関門で決めた内容に基づいて埋めます（kernels.py はカーネルが成熟してからで構いません。空のままでも問題ありません）。
• dynamics.py はそのままコピーします（編集しません）。
• program.md の {{placeholders}} を埋めます。
• findings.md は空のまま開始し、追記のみとします。

3. 契約を接続する

reference/contracts.md を読み、eval_forward の出力形状と ExperimentSpec / TrainContext の各フィールドを確認してください。ソースから形状を逆算しないでください。契約のリファレンスが正式な定義です（エージェントが最も間違えやすいのは eval_forward の形状です）。2 つの実装例については、reference/examples.md を参照してください（cis の完全並列版、trans の最小単一実行版）。

4. ループを実行する

記入済みのプロジェクトの program.md（自律的な実験ループの手順書）に引き継ぎます。

サブエージェントのモデル

autoresearch の実行では、何時間も反復を続けることがあります。長時間の実行でもメインセッションのコンテキストを一定に保つため、ループを次のように分割します。

• メインオーケストレーター — 長時間稼働するセッションです。セットアップ時に findings.md を一度読み、仮説を立て、各反復で 1 つのバッチサブエージェントを起動し、各サブエージェントが返す簡潔な要約だけを蓄積します。ログファイルを読んだり、バリアントのコードを書いたり、dynamics CSV に触れたりすることはありません。コンテキストの増加はバッチあたり約 150 トークンです。
• バッチサブエージェント — 反復ごとに 1 つ起動し、処理を返した後に破棄します。バリアントの作成、起動、待機、結果と dynamics の読み取り、および findings.md への追記を担当します。簡潔な要約を返して終了します。
• Dynamics 分析サブエージェント — バリアントの dynamics に異常が見られる場合、バッチサブエージェントの内部から必要に応じて起動します。変更はありません。

報告の形式と簡潔な要約のスキーマについては、プロジェクトの program.md（「Batch subagent contract」）を参照してください。

不正行為に関する規律

警告

危険信号 — 停止してください。 以下はどれも進歩ではなく、不正行為です。

• harness.py のあらゆる箇所を編集すること。
• # FIXED / # TODO(autoresearch) が付いた定数（指標、サブセット、 シード）に手を加えること。
• train.py 内で検証データ／ホールドアウトデータをインポートまたは調査すること — ホールドアウトの目標値を読み取って、それに合わせて学習することも含まれます。「導き出す」 ことも、データリークであることに変わりはありません。
• torch.compile を呼び出すこと、または実行時の .autotune() を追加すること。
• launcher.py の採用／破棄のロジック、勝者のしきい値、または指標の解析を編集すること。

検証／ホールドアウトセットにアクセスする正当な経路は、ハーネス内にある ctx.score(...) だけです。

言い訳と実態

言い訳	実態
「予算がもうすぐ尽きるので、スコアラーのしきい値を少し緩めるだけです」	指標を変更すると、それまでのすべての結果が比較不能になります。指標は実験のグラウンドトゥルースです。
「検証セットは小さいので、ノイズを減らすために学習データをいくつか追加させてください」	これはシグナルを漏らしてスコアを水増しするうえ、それまでのすべての結果を比較不能にします。学習データ／検証データが異なる状態で測定されることになるためです。ノイズの下限も結果の一部です。
「この『固定』定数を train.py に移せば、調整できます」	移動した時点で、比較可能性がひそかに失われます。固定とは固定ということです。変更する場合は、新しいブランチを開始し、意図的に harness.py を編集してください。
「どのサンプルに重みを付けるか選ぶために、検証データを少し見るだけです」	これは検証データのリークです。eval_forward が検証データを見るのは、ハーネスのスコアラーを介した場合だけです。
「torch.compile を使えば、この予算内に収まります」	トレースと自動チューニングで毎回予算を消費します。禁止されています。事前にチューニング済みの kernels.py を使用してください。
「ホールドアウトの目標値をコピーしたのではなく、それらから関数を導き出しただけなので、汎化します」	ホールドアウトの目標値を読んで、それに合わせて学習することは、導き出した場合でもコピーした場合でもデータリークです。ホールドアウトセットに触れるのは、ハーネスのスコアラーを介する場合だけにしてください。「ホールドアウトの関係に適合した」モデルは、タスクを学習したのではなく、テストを記憶したのです。

クイックリファレンス

ファイル	役割	編集可能か
harness.py	FIXED — データ＋指標＋契約	いいえ
train.py	改変可能な学習ループ	はい
launcher.py	FIXED — ディスパッチ、採用／破棄、results.tsv	いいえ
dynamics.py	2階層のダイナミクス記録機能	いいえ（そのままコピー）
program.md	実験ループのマニュアル	プロジェクト側でプレースホルダーを埋めます
findings.md	セッションをまたいで更新する知見ログ	追記のみ
kernels.py	事前チューニング済みカーネルのみ	はい（追加のみ）

相互参照

• superpowers:brainstorming — 必須のゲート（ワークフローのステップ1）。
• helion-jagged-and-autotuning — 事前チューニング済みカーネルを用意し、実行時の自動チューニングは行わないでください。
• pixi — ハーネスを実行するための環境設定。

よくある間違い

間違い	修正方法
ゲートを通さず、指標／分割／予算を推測する	まず superpowers:brainstorming を実行し、6項目すべてを解決してください
eval_forward の形状が一致しない（指標が気付かれずに比較不能になる）	reference/contracts.md を読み、ハーネスのスコアラーが使用する指標に合ったものを返してください
最終的な数値だけを記録する	2階層の dynamics.py 記録機能（スナップショットのヘッダー＋幅広の本文）を使用してください
勝利を捏造するために launcher.py を編集する	Launcher は FIXED です。採用／破棄や解析を緩めるのは不正行為です
train.py でホールドアウトの目標値を「導き出す」	データリークです。ホールドアウトセットに触れるのは ctx.score(...) を介する場合だけにしてください
メインのオーケストレーターループでログファイルやダイナミクスのCSVを読む	バッチサブエージェントに委任してください。メインコンテキストが確認するのは、簡潔な要約だけにしてください
バッチサブエージェントが要約にログの抜粋をそのまま返す	要約は簡潔なスキーマに従い、バリアントごとに1行、さらにバリアントごとにダイナミクスの行を1行だけ含めてください。それ以外は含めないでください