autoresearch

autoresearch

Autoresearch はクローズドループの ML 実験ワークフローです。

• 人間が program.md を記述します
• エージェントが train.py を編集します
• prepare.py は固定したままにします
• 各実行には同じ 300 秒の予算を割り当てます
• val_bpb が低いほうを採用します
• 性能が低下した場合は変更を元に戻します

このスキルは、巨大なチュートリアルではなく、ルーティングを優先する入り口として機能する必要があります。ユーザーのモードを選び、変更不可のハーネスに関するルールを徹底してから、最小限で役立つスクリプトまたはリファレンスに案内します。

このスキルを使う場合

• 実際の GPU マシンに karpathy/autoresearch をセットアップする
• セッション前に program.md を作成またはブラッシュアップする
• 範囲を限定した train.py の夜間検索ループを実行する
• セッション後に results.tsv を解釈する
• 比較の妥当性を損なわずに、より厳しい VRAM 制約にワークフローを適応させる
• autoresearch と関連する評価ツールの、ML 固有の境界を説明する

このスキルを使わない場合

• ユーザーが、プロンプトや評価を固定したうえで SKILL.md、プロンプト、またはリポジトリ内のワークフローを最適化したい場合 — skill-autoresearch を使ってください
• ユーザーがアプリレベルのトレーシング、データセットを使った LLM 評価、フィードバックレビュー、またはオブザーバビリティを求めている場合 — LangSmith、Braintrust、Weave、Promptfoo などのツールを使ってください
• 実際のトレーニングリポジトリ、program.md、train.py、固定の実行時間予算、val_bpb による採用・差し戻しの反復が関係しない作業の場合
• ユーザーが実際には、トレーニングループを実行する意図のない論文調査、一般的なベンチマークの調査、または文献レビューを求めている場合

中核となる境界

懸念事項	autoresearch が担当	別のツールへ案内
変更対象	実際のトレーニングリポジトリ内の train.py	プロンプト、アプリ設定、SKILL.md、製品の挙動
固定する評価器	prepare.py、検証用シャード、TIME_BUDGET=300、セッションで選択した MAX_SEQ_LEN / EVAL_TOKENS	プロンプト／評価用データセット、アプリのスコアカード、オブザーバビリティのダッシュボード
採用ルール	val_bpb が低い場合のみ採用し、同値または性能低下の場合は差し戻す	人によるレビューキュー、アプリレベルのリリースゲート
主な成果物	program.md、results.tsv、採用／破棄されたコミット	プロンプトスイート、トレース、フィードバックデータセット

この境界に合わない場合は、このスキルを無理に適用しないでください。

必須の初回確認事項

作業を始める前に、次の点を確認します。

1. モード — セットアップ、program.md、実行ループ、結果の解釈、または制約のあるハードウェア
2. リポジトリの状態 — クローン済みか、依存関係をインストール済みか
3. ハードウェアの状態 — GPU / VRAM / CUDA / MLX / Windows のパス
4. セッションの状態 — 初回のベースライン、進行中のループ、または完了した実行
5. 制約の状態 — VRAM の上限、セッション用に prepare.py がすでに固定されているか

手順

ステップ 1：動作モードを 1 つだけ選ぶ

リクエストに応えるために必要な、最小限のモードを選びます。

1. セットアップの準備

   • uv をインストールする
   • リポジトリをクローンする
   • 依存関係を同期する
   • scripts/check-hardware.sh で GPU/CUDA/uv を確認する
   • 最初のベースライン実験を実行する

2. program.md の作成

   • 人間が作成する研究方針を記述またはブラッシュアップする
   • 現在のベースライン val_bpb を記録する
   • 仮説に優先順位を付ける
   • すでに試した内容を列挙する
   • ループ開始前に制約を固定する

3. 範囲を限定した実行ループ

   • 評価器がすでに固定されていることを確認する
   • 変更可能な検索対象を train.py のみにする
   • 採用・差し戻しの規律を守ってループを実行する
   • すべての実験を results.tsv に記録する

4. 結果の解釈

   • 最良の採用済み実行を要約する
   • 繰り返し発生した失敗やクラッシュのパターンを特定する
   • 次の program.md に含めるべき内容を抽出する
   • 実際の改善と一度限りの異常値を区別する

5. 制約のあるハードウェアへの適応

   • セッション開始前に MAX_SEQ_LEN と EVAL_TOKENS を設定する
   • セッション開始後は変更しない
   • 実行中に評価器をごまかすのではなく、モデルや検索戦略を調整する
   • CUDA の前提が当てはまらない場合は、コミュニティのフォークに案内する

ユーザーがエンドツーエンドの手順全体を明示的に求めていない限り、5 つすべてのモードを一度に回答しないでください。

ステップ 2：変更不可のハーネスを再確認する

どのモードでも、以下のルールを維持する必要があります。

• program.md は人間が作成したファイルであり、セッション中は読み取り専用です
• train.py は主な変更可能な探索対象です
• セッション開始後、prepare.py は読み取り専用です
• TIME_BUDGET=300 は固定です
• val_bpb は主な採用／取り消し指標です
• results.tsv は追記専用です
• pyproject.toml の依存関係セットは固定です

ユーザーが評価器の変更を希望する場合は、現在のセッションではなく、新しい比較トラックを開始してください。

ステップ 3：選択したモードを実行する

モード A — セットアップの準備状況

リポジトリがまだ実行可能な状態でない場合に、この手順を使用してください。

curl -LsSf https://astral.sh/uv/install.sh | sh
git clone https://github.com/karpathy/autoresearch
cd autoresearch
uv sync
bash scripts/check-hardware.sh
uv run prepare.py
uv run train.py > run.log 2>&1
grep "^val_bpb:\|^peak_vram_mb:" run.log

成功条件：ベースラインの実行が 1 回完了し、val_bpb と peak_vram_mb の両方が出力されること。

モード B — program.md の作成

ループは存在するものの、方向性が定まっていない場合に、この手順を使用してください。

最低限、以下のセクションを含めます。

• val_bpb の低下に結び付いた目標
• 現在のベースラインの val_bpb
• 優先順位順の探索方向
• すでに試したこと
• 制約：TIME_BUDGET=300、prepare.py の変更禁止、新しいパッケージの追加禁止、VRAM 上限、各実験で意味のある変更は 1 つだけ

より詳細なテンプレートと更新パターンについては、references/program-md-guide.md を参照してください。

モード C — 制約付き実行ループ

セットアップと program.md の準備が整った後にのみ、この手順を使用してください。

ループの手順：

1. program.md と現在の train.py を読む
2. 仮説を 1 つ立てる
3. train.py を編集する
4. コミットする
5. 300 秒の実験を 1 回実行する
6. val_bpb を取得する
7. 改善した場合は採用し、そうでない場合は git reset HEAD~1 を実行する
8. 結果を results.tsv に追記する

一般的なコマンド：

bash scripts/run-experiment.sh
bash scripts/run-loop.sh --max 20 --desc "session-1"

複数の変更を一度に加える大規模な書き換えは推奨しないでください。目立つ編集よりも、明確なアブレーションが重要です。

モード D — 結果の解釈

実行またはチェックポイントが完了した後に、この手順を使用してください。

便利なコマンド：

bash scripts/show-results.sh --top 10
awk -F'\t' '$4=="keep"' results.tsv | sort -t$'\t' -k2 -n
awk -F'\t' '{print $4}' results.tsv | sort | uniq -c

次の 4 点のみを要約してください。最良の改善、繰り返された失敗、「試したこと」に追加すべき内容、次に試す対象を絞った実験の系統です。

モード E — 制約のあるハードウェアへの適応

VRAM、プラットフォーム、実行時間の制約が支配的な場合に、この手順を使用してください。

ルール：

• セッション開始前に MAX_SEQ_LEN と EVAL_TOKENS を選択する
• セッション中は決して変更しない
• 評価器を変更する前に、モデルや探索の目標を引き下げる
• Apple Silicon／非 CUDA の経路では、コミュニティフォークへの案内を優先する

具体的な値とトラブルシューティングについては、references/hardware-config.md を参照してください。

ステップ 4：依頼内容が隣接領域なら積極的に案内先を切り替える

以下の場合は案内先を切り替えてください。

• ユーザーが指示、プロンプト、またはリポジトリ内のスキルの最適化を希望している → skill-autoresearch
• ユーザーがアプリレベルのトレース、フィードバックレビュー、オブザーバビリティ、オンライン／オフライン評価ダッシュボードを希望している → LangSmith / Braintrust / Weave / Promptfoo
• ユーザーが実行可能な ML ループではなく、一般的な文献の統合を希望している → リサーチまたはサーベイ用ツール

ステップ 5：詳細はサポートファイルにまとめる

すべてをインラインで再説明するのではなく、サポートファイルを使用してください。

• references/operating-modes-and-route-outs.md — 迅速な案内用の表、最小限の応答形式、引き継ぎのロジック
• references/architecture.md — 不変性の契約、ファイル一覧、指標の根拠
• references/program-md-guide.md — テンプレートと更新ルール
• references/hardware-config.md — VRAM の表とプラットフォームのトラブルシューティング
• scripts/*.sh — 実行可能なセットアップ／ループ／レポート用ヘルパー

利用可能なスクリプト

autoresearch リポジトリのディレクトリ内で実行してください。

スクリプト	用途	使用方法
setup.sh	環境の初回セットアップ	bash scripts/setup.sh [--seq-len 512]
run-experiment.sh	5 分間の実験を 1 回実行し、指標を抽出	bash scripts/run-experiment.sh
run-loop.sh	自律ループ：実行 → 採用／取り消し → 繰り返し	bash scripts/run-loop.sh [--max 20]
show-results.sh	results.tsv の読みやすいレポート	bash scripts/show-results.sh [--top 10]
check-hardware.sh	GPU／CUDA／uv の準備状況チェック（JSON 出力）	bash scripts/check-hardware.sh

参考資料

詳細なドキュメントは references/ にあります。

ファイル	内容
references/operating-modes-and-route-outs.md	モード選択、隣接領域との境界、最小限の出力要件
references/architecture.md	システム設計、不変性の契約、Git による段階的な改善、指標を採用する理由
references/program-md-guide.md	効果的な program.md ディレクティブの作成と更新方法
references/hardware-config.md	GPU ごとの VRAM 設定、メモリの最適化、プラットフォームのトラブルシューティング

例

例 1：40GB GPU での初回セッション

リクエスト：「40GB GPU で Karpathy autoresearch を実行するのを手伝ってください。」

期待される動作：

• まず Setup readiness を選択する
• ハードウェアと依存関係を確認する
• ベースライン実験を 1 回実行する
• ベースラインができてから program.md の作成に進む

例 2：代わりにスキルを最適化したい場合

リクエスト：「autoresearch を使って、この SKILL.md をバイナリ評価で改善できますか？」

期待される動作：

• すぐに skill-autoresearch に案内する
• このスキルは train.py を使った実際の ML トレーニング探索向けであると説明する

ベストプラクティス

1. 要件に合う最小のモードから始める — セットアップ、作成、実行ループ、解釈、またはハードウェアへの適応
2. 自信満々になる前にベースラインを確認する — 夜通しのループについて話す前に、実行が 1 回成功することを確認する
3. セッション前に評価器を固定する — prepare.py、TIME_BUDGET、MAX_SEQ_LEN、EVAL_TOKENS は比較可能な状態に保つ必要があります
4. 一度に意味のある実験を 1 つ行う — 謎の設定をまとめるより、アブレーションのほうが有効です
5. results.tsv は追記専用にする — 破棄した実行も証拠になります
6. 詳細な内容は参考資料やスクリプトに置く — 入口ではすべての表を重複させず、分類して案内する必要があります
7. 隣接する作業は早めに別の場所へ案内する — プロンプト／アプリの評価と SKILL.md の最適化は別の領域です

参考資料

• GitHub — karpathy/autoresearch
• Karpathy — ニューラルネットワークをトレーニングするためのレシピ
• MLflow Tracking
• Weights & Biases Tracking
• MIT License