ml-autoresearch

ML 自動研究ループ

このループは分析を最優先します。すべての実験の後に、モデル内部で何が起きたかを調べる診断を行い、次の変更は推測ではなく、その証拠に基づく仮説とします。フィードバック信号は実行ログから読み取る <metric> であり、何を変更するかを決める軸となるのが分析です。<literature> ダイヤル（on／off）を使うと、関連する literature-search スキルを通じて、各変更を先行研究に基づかせることもできます。各イテレーションで変更は1つだけにすることで、各指標の変化を変更に結びつけられます。

あなたは研究者です。ループの実行中は、許可を求めるために中断しないでください。

使用するタイミング

モデルの実際の挙動の分析に基づいて変更を行いながら、自由度の高い自律的な ML 研究を進めたい場合に使用します。自己完結型の分析とスコアのループには <literature> = off を設定し、科学文献に基づく変更（論文検索、エビデンスの評価、再利用可能な知見のバックログ）も行う場合は <literature> = on を設定します。単一のトレーニング実行、固定されたスイープ、測定可能なスカラー指標のないタスクには使用しないでください。ユーザーが文献に基づく調査を希望する場合、または既知で十分な研究があるため先行研究のレシピが役立つ場合を除き、デフォルトは off とします。

セットアップ

バインディングを対話形式で解決します。 作業ディレクトリに loop.run.yaml が存在する場合は読み込み、ループに進みます。存在しない場合は、Claude Code（AskUserQuestion ツールが利用可能な場合。<host> = claude-code と記録）では、プロジェクトから各バインディングの値を推測し、推奨値として提示します。それ以外のホスト（<host> = other）では、それぞれを引用符付きのプレーンテキストの質問として尋ねます。その後、loop.run.yaml（形式：examples/run.example.yaml）を書き込み、他のファイルを作成する前に、すべての値をユーザーに確認します。 branches 戦略の場合は、git checkout -b autoresearch/<run_tag> を実行してブランチを作成します（タグには今日の日付を使います。ブランチはまだ存在していてはいけません）。time ゲートの場合は、<sandbox_root>/run_with_timeout.sh（timeout $(( <budget> * 60 )) <entrypoint> "$@"）を書き込み、これを実行コマンドとして使用します。2 × <budget> 分で強制終了します。epochs の場合は、<editable_files> 内のファイルにあるエポック上限を変更します。

バインディング	意味	デフォルト	推測方法
<metric> / <metric_direction>	最適化するスカラー指標と、minimize／maximize	—	編集可能なファイルと README を検索し、指標名を確認します
<run_cmd> / <entrypoint>	実験をエンドツーエンドで1回実行するコマンド	—	pyproject.toml／.venv／README
<editable_files>	編集可能なファイル（評価ハーネスは対象外）	—	モデル／設定／トレーニングスクリプト。データ、ログ、環境、ハーネスは除外します
<sandbox_root>	スナップショットと台帳の保存先	./sandbox	編集可能なファイルと同じ場所
<iter_strategy>	snapshots または branches	snapshots	作業ディレクトリがクリーンな Git リポジトリかどうか
<gate> / <budget>	time（分）または epochs と、その上限	—	設定内の既存の時間／エポック設定
<literature>	on = 文献に基づく、off = 分析のみ	off	ユーザーが論文に基づく調査を希望するかどうか
<research_scale> (on の場合のみ)	調査の深さダイヤル low／medium／high／x-high	medium	roles/research-subagent.md を参照
<domain> (on の場合のみ)	問題領域を表す1つのフレーズ。検索クエリの表現にのみ使用し、フィルタリングには使用しません	—	データ／モデル／タスクから推測します
<lit_skill_dir> (on の場合のみ)	literature-search スキルのインストールディレクトリ	このループの隣	~/.claude/skills/literature-search/（ホストに応じて調整）
<lit_py> (on の場合のみ)	文献ヘルパー用の Python ≥3.9 インタープリター（標準ライブラリのみ）	python3	<run_cmd> とは独立しています

ファイル編集ガード：セットアップ中でもループ中でも、ファイルに触れる前に、そのファイルが <editable_files> に含まれていることを確認してください。それ以外のすべては読み取り専用のグラウンドトゥルースです（評価ハーネスが <metric> を定義します）。例外はありません。

文献ツールチェーン（<literature> = on の場合のみ）

論文の検索には、同階層の literature-search スキルを使用します（標準ライブラリのみで、インストール不要です）。 <lit> = <lit_skill_dir>/tools/lit_search.py（tools/ の部分に注意してください）。サブコマンドの後ろに --cache-dir <sandbox_root>/literature/.cache を追加して、キャッシュを共有します。サブコマンドは JSON を出力します。 失敗時は {"error","fallback"} を出力してゼロ以外の終了コードで終了します。その場合は ホストの WebSearch/WebFetch に切り替えてください（引用を捏造してはいけません）。セットアップ時に <lit> --help で動作確認してください。スキルが ない場合はユーザーに伝え、インストールする（cp -r <repo>/loops/literature-search ~/.claude/skills/） か、機能を制限して続行するかを提案してください。初期設定と API キー（すべて任意です。無料の S2_API_KEY を推奨します）には、 <lit> keys --init を実行してください。これはプロジェクトルートにある、共有され Git の追跡対象外となる keys.env を管理し、 キーの有無を真偽値で報告します（秘密情報がチャットに含まれることはありません）。有効なティアを loop.run.yaml に保存してください。

サンドボックスを初期化する

ディレクトリ構成を作成し（<literature> = on の場合のみ、追加の literature/ ツリーを含めます）、台帳のヘッダーを書き込みます：

<sandbox_root>/
├── loop.run.yaml       ← resolved bindings (written now)
├── results.tsv         ← experiment ledger, header only (written now)
├── literature/         ← (on only)
│   ├── corpus.tsv      ← findings ledger, header only (written now)
│   ├── .cache/         ← lit_search on-disk cache
│   ├── pdfs/           ← fallback PDF reads
│   └── text/           ← extracted LaTeX section text
└── iter1/              ← created at loop start

results.tsv のヘッダー（タブ区切り。literature_basis 列は <literature> = on の場合のみ存在します）：

iter	<metric>	status	analysis_summary	[literature_basis	]description

ループ（中断されるまで無限に繰り返す）

イテレーション 1 は常に変更なしのベースラインです。変更計画と調査はスキップします（まだ変更の根拠となる診断結果がありません）が、ベースラインの plan.md は作成し、必須の分析は実行してください。これにより、イテレーション 2 の土台となる最初の実測結果が得られます。<editable_files> 内のすべてが変更対象です（アーキテクチャ、オプティマイザー、ハイパーパラメーター、データパイプライン、損失関数）。制約は、コードがクラッシュせずに実行でき、<budget> 内に完了することだけです。シンプルさの基準：それ以外の条件が同じなら、シンプルな方が優れています。小細工のコードを 20 行追加して 0.001 改善する価値はありませんが、コードを削除して 0.001 改善（または指標が同等）するなら keep です。

各イテレーションでこのチェックリストをコピーして、項目にチェックを入れてください。

• 1. 状態を確認する。 ブランチ方式：git log --oneline -5。スナップショット方式：iter<N>/ が存在しないことを確認します。イテレーション N-1 の分析概要を読みます。（有効な場合）未実装のキーパーがないか corpus.tsv にざっと目を通します。
• 2. 変更を 1 つ計画する（イテレーション 1：スキップ — ベースラインを変更せず実行）。イテレーション N-1 の分析結果を根拠にします。下記の変更の計画を参照してください。（有効な場合）文献調査のステップも実行します。
• 3a. スナップショットを作成／コミットしてから、変更を 1 つ適用する。 スナップショット方式：iter<N>/{code_snapshot,analysis,results}/ を作成し、すべての <editable_files> を code_snapshot/ にコピーして、loop.run.yaml を iter<N>/ にコピーしてから、変更を適用します。ブランチ方式：変更を適用してから、git commit -am "<desc>" を実行します。公開済みの手法／ライブラリを実装する場合は、実際の最新の使用例かリポジトリ内の実際のライブラリを根拠にしてください（先に読んでください）。API を記憶だけで書いてはいけません。
• 3b. 実行前に分析計画を作成する＋必要な計測処理を追加します。下記の分析計画を参照してください。
• 4. 実験を実行する。すべてをリダイレクトしてください（tee は使用禁止）：<entrypoint> > <sandbox_root>/iter<N>/<run_log> 2>&1（時間制限がある場合は run_with_timeout.sh を使用）。実行時間を超えた場合は終了させ、クラッシュとして扱います。
• 5. 指標を確認する：grep '^<metric>:' <sandbox_root>/iter<N>/<run_log>。出力が空の場合は tail -n 50 <run_log> を実行し、トレースを読み、簡単な修正を 1 回試みます（タイプミス／インポートなど）。根本的に壊れている場合は crash と記録して続行します。
• 6. 結果を分析する — 必須です。実際の成果物ファイルを作成します。下記の分析を参照してください。
• 7. 台帳に記録する（追跡対象外 — コミット禁止）。台帳を参照してください。
• 8. 維持するか、元に戻す（この変更は今イテレーションで実行済みです）。<metric_direction> に沿って改善した場合は keep として、現在のベストを更新します。同等／悪化／クラッシュの場合は discard／crash とします。ブランチ方式では git reset --hard HEAD~1、スナップショット方式では iter<N>/code_snapshot/ から <editable_files> を復元します。discard を記録する前に、シンプルさの基準を適用してください。クラッシュ／OOM の場合は、意図を保つ最小限の変更で修正します（OOM の場合は、実効バッチサイズを維持できるよう、バッチを小さくして勾配蓄積を使用します）。実験を、計画にない内容へ変更してはいけません。
• 9. ステップ 1 に戻る — ステップ 6 の分析結果が、次の仮説に対する主要な入力です。

変更の計画（ステップ 2 — 2 回目以降の反復）

最新の分析が方向性を定め、各反復の主要な入力になります。反復 N-1 の分析に基づき、変更する要素を1 つだけ 決めます。ほかの検証済みの案はキューに入れ、1 回の実行にまとめません。

適用する前に、次の内容を明示します。

• 変更する 1 つの内容と、それが対象とする <editable_files>。
• 実証的な根拠 — 反復 N-1 の results/ にある、変更の動機となる具体的なファイルと値／パターン。簡略化以外の変更にはすべて根拠を示す必要があります。理論的な推論だけでは不十分です。別のアーキテクチャに切り替える場合も、根拠が必要です（例：「ファミリーは余地を残して X で頭打ちになる」「Y が必要なケースで正確に失敗する」といった、上限や構造に関する所見）。
• 予測する結果と、その所見が予測を裏付ける理由。

<literature> = off の場合： その根拠が判断のすべてです。分析から変更を直接選びます。計画を書く前に、過去の分析（ls <sandbox_root>/iter*/analysis/*.py）を確認し、比較する理由がないまま診断を繰り返さないようにします。

<literature> = on の場合： 根拠を確定した後、変更を文献に基づいて選びます。

• 2a. ドリフトを解消してから、バックログをキャッシュとして参照します。 最後に採用した変更がアーキテクチャのファミリー（例：CNN→transformer）を変更した場合、未実装の採用案のうち、scope が現在と一致しないアーキテクチャタグのものはすべて result=stale にします。scope=agnostic の採用案（スケジュール、重み減衰、データ拡張、初期化の考え方）は引き続き有効です。次に corpus.tsv を確認し、分析の方向性を対象とする未実装の keep があれば再利用します。ただし、現在のアーキテクチャに対してゲート（2c）を再検証して、今も通過する場合に限ります。現在は当てはまらない所見は、無理に採用せず退役させます。
• 2b. その方向性を調査します（2a で今も有効な変更要素が見つかった場合を除き、これが標準です）。分析で示された制約を、それぞれ対応する問いに変換し、iter<N>/questions.md に記録します。その後、roles/research-subagent.md を参照して調査サブエージェントを起動します（spawn-or-degrade：Claude Code では実際に独立したサブエージェントを起動し、それ以外ではこのコンテキスト内で調査を実行します）。調査の深さ／労力はダイヤルの設定に従います（<research_scale> については同ファイルのダイヤル表を参照）。レベル 1 は大局的な調査（アーキテクチャとの適合性、従来の手法、文献で成功が示されているか）です。まずレベル 1 の調査を行い、説得力のある新しい方向性が見つかった場合は、それを変更要素にします。レベル 2 は具体的なマイクロ最適化（初期化、重み減衰の動的特性、シーケンス長に応じた attention／cache、正規化の配置、スケジュール）です。マンネリ化を防ぐため： 約 3 回の反復で見送られた採用案、または現在有効な方向性に含まれなくなった採用案は、再び浮上しないよう退役させ（result=stale にし）ます。
• 2c. 根拠のゲート（再検証し、履歴も参照します）。次の条件をすべて満たす場合に限り、所見を採用または再利用します。evidence.strength が moderate／strong である（weak ではない）。applicability_to_our_setup が現在のデータ／モデル／予算に適用できる。すべての files_to_edit が <editable_files> の範囲内であり、<budget> に適合する。そして、corpus.tsv に no-effect／hurt／crashed と記録済みの変更と実質的に同等ではない（所見が今回は異なる理由を説明している場合を除く）。ドリフトによる退役を機械的に行えるよう、採用する各所見に scope（agnostic または現在のアーキテクチャタグ）を付けます。採用するものも却下するものも、すべての所見を corpus.tsv に記録します。採用されたものの選ばれなかった所見はキューに残します（implemented=n、result=pending）。
• 2d. 変更要素を 1 つ選びます。 採用案（バックログと新規のもの）から、エビデンス × 適用可能性 × 複雑さあたりの効果が最も高いものを選びます。上記の明示事項に、文献上の根拠（採用した所見と引用、または分析に基づく簡略化／アブレーションのみの場合は none）と、検証項目（効果の有無を判定するための、その所見の how_to_verify に記載された指標／ログ／分析）を追加します。文献上の根拠は実証的な根拠に追加するものであり、それに取って代わるものではありません。

分析計画（ステップ 3b — 実行前に作成）

<sandbox_root>/iter<N>/analysis/plan.md を、文章ではなく成果物の表として作成してください。各行は、作成して実行するスクリプト、そのスクリプトが生成する正確な出力ファイル、答える問い、各結果がどのようなものになるかを示す、確約事項です。

script	output file	question it answers	expected if change helped	expected if not

計画には、少なくとも1つ、過去のどのイテレーションでも測定されていない診断の観点を含めてください（履歴スキャンで検証されます）。「expected if not」列は必須です（結果を見る前に反証条件を定義するためです）。<literature> = on の場合は、2d の verify-todo も含め、定期的に（また、変更幅の大きい試みを検討するたびに）ceiling/headroom probe（現在のアーキテクチャは限界に近いか。train/val の頭打ち、表現崩壊、構造的な失敗）を行ってください。

計測（必要な場合は必須）。 計画した測定に、現在出力されていないメトリクス／ログ（例：レイヤーごとの勾配ノルム、クラスごとの精度、val_acc と併せた val_loss）が必要で、その出力元のスクリプトが <editable_files> にある場合は、実行前の今、そのログ出力を追加してください。先に計画を書くことで、分析時になって必要な数値が記録されていなかったと気づく事態を防げます。

分析（ステップ 6 — 必須。実際の成果物を作成）

このループの要です。plan.md の各行に対応する空でないファイルが iter<N>/results/ にすべて揃うまで、ステップ 7 に進まないでください。ファイルを書き出していない分析は、実施したことになりません。

• 6a. 計画を実行します。 各行について、iter<N>/analysis/ にスクリプトを書き、実行して、出力を iter<N>/results/ にリダイレクトしてください。参照する診断の観点（仮説と結果に応じて選び、決まった順番にはしません）：勾配ノルム／流れ、活性化の統計／飽和、埋め込み（PCA/CKA/崩壊）、誤りと混同行列の分析、損失の動態と余地、重み／パラメーターの統計、データプロファイリング（データ自体の監査は、特に有効性の高い診断の1つです）、計算プロファイリング。
• 6b. チェックリスト。 ls iter<N>/results/ の結果を plan.md と照合し、不足している成果物があれば、今作成して実行してください。
• 6c. 計画と照らして解釈します。 各行について、結果は「変更が役立った場合に予想される結果」と一致したか、それとも「役立たなかった場合に予想される結果」と一致したかを確認してください。一致しなくても、失敗ではなく有益な情報です。
• 6d. （on）2d の verify-todo を確認し、その変更が文献の予測どおりに機能したかを確かめてください。これにより、ステップ 7 での結果の result が決まります。
• 6e. 追加の追跡調査。 予想外の結果（奇妙な損失の形、一貫して誤分類されるクラス、挙動の異なるレイヤーなど）が見つかったら、その原因を追うスクリプトをもう1つ作成してください。最も新しい発見は、こうした調査から得られることがよくあります。

簡潔な分析サマリーを3～8個の箇条書きで作成してください。調べた内容、最も重要な発見（予想どおりかどうかを問わず）、（on の場合）アーキテクチャが限界に近いかどうか、次の計画の根拠となる具体的な実測値（ファイルと値／パターン）を記載します。

実測値による正当化ゲート。 ステップ 7 に進む前に、実際のファイル参照と具体的な値／パターンを用いて、次の文を完成できなければなりません。理論的な説明だけでは不十分です。

「次の変更を X とするのは、分析で Y が示されたためです（results/<file> の値／パターン Z）。」

これができない場合は、6a に戻って、できるまで分析を追加で実施してください。実測値の根拠なしに進むことは、このループで防ごうとしているまさにその失敗です。

今後に向けた計測。 分析後に、「どんなログを記録しておけばよかったか」と考えてください。出力元のスクリプトが <editable_files> にある場合は、今追加してください（最良エポックのチェックポイント、エポックごとの追加診断など）。計測の追加だけでも、1回のイテレーションとして有効です。

Ledger

<sandbox_root>/results.tsv、タブ区切りです。自由記述にカンマは使用しません。literature_basis 列は <literature> = on の場合にのみ存在します。ステータス ∈ {keep、discard、crash}。クラッシュ時はメトリックに 0.000000 を使用します。branches では、最初の列にイテレーション番号ではなく7文字のコミットを記録します。

iter	<metric>	status	analysis_summary	literature_basis	description
1	0.6320	keep	grad norms clean; no pathologies	none (baseline)	baseline
2	0.7050	keep	overfit on small data per val/train gap	Dosovitskiy 2020 ViT — aug+warmup	add RandAug + 3-ep warmup
3	0.7010	discard	warmup ok but LR too high; unstable	Loshchilov 2017 — decoupled wd	switch to AdamW wd=0.05

<sandbox_root>/literature/corpus.tsv（<literature> = on の場合のみ、タブ区切り）：精査済みの知見をまとめたバックログです。再調査する代わりに、各イテレーションで再利用します。オーケストレーター（サブエージェントではありません）がこれに書き込み、最終的なエビデンスゲートを適用するため、質問が異なっても判定は一貫します。

iter	level	paper_id	title	scope	relevance	verdict	implemented	result
2	649def…	1	An Image is Worth 16x16 Words	vit	high	keep	y	helped
3	a1c2…	2	Decoupled Weight Decay Regularization	agnostic	high	keep	y	no-effect
4	7d9e…	1	ConvNeXt blocks	cnn	low	keep	n	stale

列：level ∈ {1,2}、scope = agnostic またはアーキテクチャタグ（ドリフト時の廃止を制御）、relevance ∈ {high,med,low}、verdict ∈ {keep,reject}、implemented ∈ {y,n}、result ∈ {helped,no-effect,hurt,pending,stale}（stale = ドリフト／期限切れにより廃止）。最終行：アーキテクチャがViTに移行した後に廃止されたCNNの採用知見。agnostic なweight-decayの知見はドリフト後も有効です。

進捗を要約するときは、必ず最良のイテレーションを報告してください（最終イテレーションとは限りません）。results.tsv または literature/ をgitにコミットせず、未追跡のままにしてください。

制約

• <editable_files> 内のファイルのみ編集してください。編集のたびに事前確認してください。それ以外はすべて読み取り専用の正解データであり、評価ハーネスが <metric> を定義します。
• イテレーションごとに変更は1つとし、メトリックの変化を1つの要因に帰属できるようにしてください。
• 毎回のイテレーションで分析が必須であり、results/ 内に実ファイルを作成してください（plan.md の各行に、空ではない出力ファイルが対応します）。分析を伴わない変更は禁止です。盲目的な反復に陥り（有効時には、盲目的な頭打ちに至るレシピ追従になり）、ループの質を下げます。
• 単純化以外の変更にはすべて、その分析に基づく実証的な根拠（ファイル＋値／パターン）を示してください。有効時も、文献の根拠は補足であり、実証的な根拠の代わりにはなりません。両方を results.tsv に記録してください。
• パッケージをインストールしたり、プロジェクトにない依存関係を追加したりしないでください。ヘルパースクリプト（文献用ヘルパーを含む）は標準ライブラリのみを使用してください。
• 学習の出力は必ず <run_log> にリダイレクトしてください。tee は使用しないでください。サンドボックスは自己完結型です。../ による外部への移動は禁止です。
• （有効時）APIキーを表示またはコミットしないでください。keys が報告するのはキーの有無のみです。keys.env はプロジェクトのルートに置き、必ずgitignore対象のままにしてください。文献ツールが {"error","fallback"} を返した場合は、WebSearch／WebFetchに切り替えてください。引用を捏造してはいけません。引用する論文はすべて、実際のツール結果に基づく必要があります。

停止条件

このループは人間が中断するまで永続的に実行されます。「続けてもよいですか？」や「ここが適切な終了地点ですか？」と尋ねるために停止してはいけません。人間が不在でも、自律的な作業が無期限に続くことを期待しています。動作する結果は次のイテレーションの始まりであり、終わりではありません。アイデアが尽きたら、対象範囲内のファイルを読み直して見落とした観点を探し、分析をさらに深めてください（勾配／活性化／埋め込み／エラーを調べれば、必ず何かが見つかります）。results.tsv にある過去の惜しい結果を組み合わせ、より大胆な変更を試してください。有効時は、文献調査に戻ってください。引用グラフをさらにたどり、あなたの手法を引用する最近の研究の方法論を読み、corpus.tsv から保留中の採用知見を探し、複数の論文のレシピを組み合わせてください。