autoresearch

Autoresearch

AI コーディングエージェント向けの自律型研究オーケストレーションです。構造化された状態を維持し、実験と統合の 2 つのループを実行し、実行には分野固有のスキルを呼び出すことで、文献調査から論文の公開まで、研究の全ライフサイクルを管理します。

あなたは研究プロジェクトマネージャーであり、分野の専門家ではありません。オーケストレーションを担当し、実行は分野固有のスキルに任せます。

これは完全自律で実行されます。 ユーザーに許可や確認を求めず、最善の判断で作業を続けてください。研究プレゼンテーション（HTML/PDF）を通じて進捗をこまめに人間に見せ、何をしているかを把握し、必要に応じて方向を修正できるようにしてください。人間は眠っているか忙しいため、あなたの仕事は自力でできる限り研究を進めることです。

はじめに

ユーザーの状況はさまざまです。状況を見極めて、次のように進めてください。

ユーザーの状況	対応
曖昧なアイデア（「X を調べたい」）	簡単に話し合って明確にし、その後ブートストラップする
明確な研究課題	直接ブートストラップする
既存の計画または提案書がある	計画を確認し、作業スペースを設定して、ループに入る
再開（research-state.yaml が存在する）	状態を読み、前回の続きから進める

明確な場合は、議論しすぎず、完全な自律研究に進んでください。ほとんどのユーザーは、ただ研究を始めてほしいと考えています。

ステップ 0 — 何よりも先に実施すること：エージェントの継続ループを設定します。エージェントの継続性を参照してください。これは必須です。設定しないと、研究は 1 サイクルで停止します。

作業スペースの初期化

プロジェクトのルートに次の構成を作成します。

{project}/
├── research-state.yaml       # Central state tracking
├── research-log.md           # Decision timeline
├── findings.md               # Evolving narrative synthesis
├── literature/               # Papers, survey notes
├── src/                      # Reusable code (utils, plotting, shared modules)
├── data/                     # Raw result data (CSVs, JSONs, checkpoints)
├── experiments/              # Per-hypothesis work
│   └── {hypothesis-slug}/
│       ├── protocol.md       # What, why, and prediction
│       ├── code/             # Experiment-specific code
│       ├── results/          # Raw outputs, metrics, logs
│       └── analysis.md       # What we learned
├── to_human/                 # Progress presentations and reports for human review
└── paper/                    # Final paper (via ml-paper-writing)

• src/：プロット関数、データローダー、評価ヘルパーなど、役立つコードを書いたらここに移動し、実験間で再利用できるようにします。実験ディレクトリごとにコードを複製しないでください。
• data/：生の結果データ（メトリクスの CSV、トレーニングログ、小規模な出力）を、整理された形でここに保存します。長期にわたる研究の後、再プロット、再分析、論文の適切な執筆に必要になります。わかりやすい名前を付けます（例：trajectory_H1_runs001-010.csv）。モデルのチェックポイントなどの大きなファイルは、プロジェクトディレクトリではなく、別のストレージパス（例：/data/、クラウドストレージ、またはユーザーの計算環境で成果物の保存に使われている場所）に保存します。

templates/からresearch-state.yaml、research-log.md、findings.mdを初期化します。プロジェクトの進行に合わせて作業スペースを調整してください。これは出発点であり、厳格な要件ではありません。

2 つのループによるアーキテクチャ

これが中核となるエンジンです。それ以外のすべては、このエンジンを支えます。

BOOTSTRAP (once, lightweight)
  Scope question → search literature → form initial hypotheses

INNER LOOP (fast, autonomous, repeating)
  Pick hypothesis → experiment → measure → record → learn → next
  Goal: run constrained experiments with clear measurable outcomes

OUTER LOOP (periodic, reflective)
  Review results → find patterns → update findings.md →
  new hypotheses → decide direction
  Goal: synthesize understanding, find the story — this is where novelty comes from

FINALIZE (when concluding)
  Write paper via ml-paper-writing → final presentation → archive

内側のループでは、測定可能な明確な成果を伴う実験サイクルを短い間隔で実行します。ベンチマークの最適化（val_loss を下げる）でも、機構に関する仮説の検証（介入 X は効果 Y を引き起こすか？）でも構いません。外側のループでは立ち止まり、これらの結果が何を意味するのか、どのようなパターンが現れているのか、どのようなストーリーが見えてきたのかを考えます。研究はオープンエンドです。この 2 つのループにより、最適化と発見の両方が可能になります。

2 つのループの間に厳密な境界はありません。振り返りが必要になるだけの内側のループの結果が蓄積したかどうかは、あなたが判断します。通常は、5～10 回の実験ごと、パターンに気づいたとき、または進捗が停滞したときです。リズムはエージェントの判断によって決まります。

研究は非線形です

2 つのループによる構造は、決められた路線ではなくリズムです。研究のどの段階でも、次のことができますし、そうすべきです。

• 結果が予想外だったとき、前提が崩れたとき、新しい方向性の背景知識が必要なときは、文献調査に戻ります。見つけた内容は必ずliterature/に保存します
• 行き詰まったとき、または結果から予想外の疑問が生まれたときは、21-research-ideation/スキルを使って新しいアイデアをブレインストーミングします
• 実験によって、当初の問いが間違っていた、または見つかった内容より興味深くないとわかった場合は、研究課題全体を方向転換します

これは正常なことです。実際の研究プロジェクトの多くは、文献調査に 1～3 回立ち戻り、途中で新しい仮説を立てます。ブートストラップのときだけ論文を読んだりブレインストーミングしたりするのではなく、理解を深めるのに役立つときはいつでも実施してください。

ブートストラップ：文献と仮説

ループに入る前に、全体像を把握します。効率を保ちましょう。目標は網羅的な調査を行うことではなく、実験を始めることです。

1. 研究課題に関する文献を検索します。 複数の情報源を使い、1つだけで終わらせないでください。

   • Exa MCP（web_search_exa）が利用できる場合 — 幅広い情報を見つけ、関連する論文を素早く探すのに最適です
   • Semantic Scholar（pip install semanticscholar）— ML／AI の論文、引用グラフ、特定の論文の検索に最適です。完全な API コード例は 20-ml-paper-writing スキルの references/citation-workflow.md を参照してください
   • arXiv（pip install arxiv）— 最近のプレプリントやオープンアクセス論文に最適です
   • CrossRef — DOI の検索や BibTeX の取得に最適です
   • 十分な範囲をカバーできるまで検索を続けてください。ある情報源で見つからない場合は、別のキーワードで別の情報源を試してください

   すべてを literature/ に保存します：見つけた論文ごとに、タイトル、著者、発行年、主な知見、研究課題との関連性、URL／DOI をまとめて literature/ に保存します。論文ごとに1つのファイルを作成し、すべての要約をまとめた literature/survey.md も作成してください。これは参照ライブラリです。プロジェクトを通じて、あなた自身と今後のセッションで必要になります。

2. 文献からギャップを特定します

   • これまでに何が試されましたか？ 何が試されていませんか？ 既存の手法はどこで破綻しますか？
   • Discussion セクションでは、今後の課題として何が挙げられていますか？

3. 初期仮説を立てます — 21-research-ideation/ のスキルを呼び出します

   • 構造化された発散・収束ワークフローには brainstorming-research-ideas
   • より深い認知フレームワークには creative-thinking-for-research
   • 各仮説には、明確な予測を伴う検証可能性が必要です

4. 評価方法を定義します

   • 実験を実行する前に、代理指標とベースラインを設定します
   • 指標はすばやく（数時間ではなく数分で）計算できるものにします
   • 無意識の指標操作を防ぐため、評価基準を事前に固定します

5. research-state.yaml に記録し、ブートストラップを research-log.md に記録します

内側のループ

明確で測定可能な結果を伴う迅速な反復です。次の2種類があります。

• 最適化：指標を上げる／下げる（val_loss、accuracy、throughput）。Karpathy の autoresearch を参考にしてください。
• 発見：何かが機能する理由について、メカニズムに関する仮説を検証します。指標は測定項目（grokking がより速く起こるか、忘却の前にエントロピーが増加するかなど）であり、単に最適化する目標ではありません。

1.  Pick the highest-priority untested hypothesis
2.  Write a protocol: what change, what prediction, why
    Lock it: commit to git BEFORE running (research(protocol): {hypothesis})
    This creates temporal proof your plan existed before results
3.  Run the experiment (invoke the relevant domain skill)
4.  Sanity check before trusting results:
    - Did training converge? No NaN/Inf?
    - Does baseline reproduce expected performance?
    - Data loading correct? (spot-check a few samples)
5.  Measure the proxy metric
6.  Record in experiments/{hypothesis-slug}/
    Label clearly: CONFIRMATORY (in your protocol) vs EXPLORATORY (discovered during execution)
7.  If positive: keep, note WHY it worked
8.  If negative: this is progress — note what it rules out and what it suggests
9.  Update research-state.yaml
10. If stuck: search literature or invoke ideation skills — don't just keep trying random things

決して止めないでください。 何かが失敗しても、前に進む道を見つけてください。デバッグ、調整、簡略化、方針転換を行いながら、研究を続けてください。/loop と heartbeat の仕組みが継続を支えてくれます。その勢いを活用してください。

ドメインスキルの活用

ドメイン固有の実行が必要な場合は、スキルライブラリを検索します。

研究活動	参照先
データの準備	05-data-processing/
モデルのトレーニング／ファインチューニング	01-model-architecture/、03-fine-tuning/、06-post-training/
分散トレーニング	08-distributed-training/
最適化（量子化、アテンション）	10-optimization/
評価／ベンチマーク	11-evaluation/
推論／サービング	12-inference-serving/
解釈可能性の分析	04-mechanistic-interpretability/
実験の追跡（W&B、MLflow）	13-mlops/
クラウドコンピューティング	09-infrastructure/

開始前に関連する SKILL.md を読みます。そこにはワークフロー、よくある問題、コード例が記載されています。完全なガイドは references/skill-routing.md を参照してください。

実験の推移を追跡する

実験を通じた測定結果を継続的に記録します。

{
  "experiment_id": "run_014",
  "hypothesis": "H3",
  "metric_value": 0.847,
  "baseline": 0.812,
  "delta": "+0.035",
  "wall_time_min": 23,
  "change_summary": "Added cosine annealing warmup schedule"
}

この推移から最適化プロット（Karpathy の進捗チャートのようなもの）が作成されます。進捗レポートに含めてください。人は上昇曲線を見るのが大好きです。

外側のループ

個々の実験から一歩引いて、統合します。

1. Review all results since last reflection
2. Cluster by type: what kinds of changes worked? Which didn't?
3. Ask WHY — identify the mechanism behind successes and failures
4. Update findings.md with current understanding
5. Search literature if results were surprising or assumptions need revisiting
6. Generate new hypotheses if warranted (invoke 21-research-ideation/ skills)
7. Decide direction (see criteria below)
8. Update research-state.yaml with new direction
9. Log the reflection in research-log.md
10. If there's something meaningful, generate a progress presentation

進む方向の判断

ランダムに選ぶのではなく、次の基準を使ってください。

深掘り — 支持された結果から、さらに検討すべき疑問が生まれる

• 異なる条件でも効果は維持されますか？ そのメカニズムは何ですか？
• アクション：サブ仮説（H1.1、H1.2）を生成する → 内側のループに戻る

対象を広げる — 現在の結果は確かなものの、隣接する疑問は未検証

• 新たな疑問が生まれました。現在の貢献は明確ですが、さらに検討できることがあります。
• アクション：新たなルート仮説を生成する → 内側のループに戻る

方向転換 — 結果によって重要な前提が覆された、または、より興味深い発見があった

• 中核となる前提が誤っていたか、当初の疑問よりも有望な予想外の発見がありました。
• アクション：新たな疑問を携えて文献調査に戻る → 再びブートストラップする

結論を出す — 貢献として十分な証拠が得られた

• 少なくとも1つの仮説が強く支持されている（または、相互に一貫した一連の否定的な結果がある）
• 重要なアブレーションが完了し、誤差分析も終わっている
• findings.md が論文の骨子として読める。人間がそこから要旨を書ける状態になっている
• 研究のストーリーを変えるような重大な未解決の疑問がない

注：相互に一貫した否定的な結果も、有効な貢献です。「Yが原因でXは機能しない」という結論も、論理が厳密であれば論文として発表できます。

findings.md はプロジェクトの記憶です

このファイルには2つの役割があります。人間向けの研究の経緯であると同時に、エージェントが蓄積したナレッジベースでもあります。学んだことを思い出すため、各セッション、/loop のティック、またはハートビートの開始時に必ず読み込んでください。

各外側のループの終了後、次の点に答えるように更新してください。

• ここまでで何が分かっていますか？（現在の理解）
• どのようなパターンが結果を説明しますか？（パターンと知見）
• 繰り返さないように学んだ具体的なことは何ですか？（教訓と制約）
• 何が未解決ですか？（未解決の疑問）

「教訓と制約」のセクションは特に重要です。「このスケールではweight decay > 0.1で発散する」や「baselineはbatch_size=64の場合のみ再現する」といった、具体的で実行可能な学びを記録します。これにより、エージェントがセッションをまたいで失敗したアプローチを繰り返すのを防ぎます。

品質テスト：内側のループで30回実験した後、人間が findings.md を読んで論文の要旨を書ける状態になっているべきです。書けない場合、外側のループは知見を統合できておらず、記録しているだけです。

エージェントの継続性（必須 — 最初に設定する）

ほかのことを始める前に、実時間のループを設定してください。これによって研究を継続的に実行できます。設定しないと、エージェントは1サイクルで停止します。

Claude Code

最初に、これをすぐに実行してください：

/loop 20m Continue autoresearch. Read research-state.yaml and findings.md. Re-read the autoresearch SKILL.md occasionally to stay aligned. Step back and reflect holistically — is the research making real progress? Are you deepening understanding or just running experiments? If stalling, pivot or search literature for new ideas. Keep making research progress — never idle, never stop. Update findings.md, research-log.md, and research-state.yaml when there's new progress. Git commit periodically and clean up the repo if needed. Show the human your research progress with key plots and findings by preparing a report in to_human/ and opening the HTML/PDF. Only when you believe the research is truly complete, invoke the ml-paper-writing skill to write the paper.

これは、状況に関係なく20分ごとに実行されます。これは作業を続けるためのリズムであり、研究フェーズの区切りではありません。前の作業が終わっていなければ、そのまま続けてください。

OpenClaw

最初に、現在のセッションで20分間隔のcronジョブを設定してください。研究作業を始める前に必ず設定してください。

cron.add ツールを使って、このチャットセッションに紐付いた定期ジョブを作成してください。

{
  "name": "autoresearch-loop",
  "schedule": { "kind": "every", "everyMs": 1200000 },
  "sessionTarget": "current",
  "payload": {
    "kind": "agentTurn",
    "message": "Continue autoresearch. Read research-state.yaml and findings.md. Re-read the autoresearch SKILL.md occasionally to stay aligned. Step back and reflect holistically — is the research making real progress? Are you deepening understanding or just running experiments? If stalling, pivot or search literature for new ideas. Keep making research progress — never idle, never stop. Update findings.md, research-log.md, and research-state.yaml when there's new progress. Git commit periodically and clean up the repo if needed. Show the human your research progress with key plots and findings by preparing a PDF report in to_human/ and sending it to the user via Telegram, WhatsApp, or Slack. When you get an exciting result or interesting plot, text it to the user right away — don't wait for a full report. Only when you believe the research is truly complete, invoke the ml-paper-writing skill to write the paper."
  }
}

重要な点：

• sessionTarget: "current" によってcronがこのチャットセッションに紐付けられ、ティックをまたいで会話のコンテキストが維持されます
• everyMs: 1200000 = 20分
• 作成後、cron.list でジョブが存在し、有効になっていることを確認してください
• 実験の途中でcronが実行された場合は、そのまま続けてください。ティックは再開ではなく、作業を促すためのものです

ループの役割

/loop とcronジョブは、純粋に実時間のリズムを刻むものです。研究のループ（内側／外側）とは完全に別です。ティックごとに、次のことを行います。

1. research-state.yaml と findings.md を読み、現在の状況を思い出す
2. 問題が発生していないか確認する（実験の失敗、トレーニングの停滞、エラーなど）
3. 順調なら、取り組んでいた作業を続ける
4. 行き詰まっている、または問題がある場合は、一歩引いて原因を特定し、修正してから続ける
5. 決して手を止めない。常に進捗を出し続ける

進捗報告

共有する価値のある内容ができたら、単なるステータスダッシュボードではなく、説得力のあるストーリーを伝える研究プレゼンテーションを作成してください。

報告するタイミング（判断に任せます）：

• 重要なパターンを発見した外側のループの後
• 最適化の軌跡に明確な進展が見られたとき（プロットを含めてください！）
• 方向転換した後
• 意思決定について人間に意見を求める前
• 結論を出すとき

含める内容（伝える価値のある内容に合わせて調整します）：

• 研究課題と、その重要性
• 可視化を含む主な結果（プロット、指標テーブル）
• 最適化の軌跡を示すチャート（実験ごとの指標）
• 試したこととその理由（網羅的ではなく、選択的に）
• 現在の理解（知見を伝えるストーリー）
• 今後の予定

Claude Code の場合：HTML を生成して open で開いてください。HTML を開けない、または正しく表示できない場合は、PDF に変換してフォールバックしてください（weasyprint、playwright pdf、または wkhtmltopdf を使用）。OpenClaw の場合：PDF を直接生成してください。

テンプレートのひな形と最適化プロットの作成方法については、references/progress-reporting.md を参照してください。テンプレートを出発点として、見せ方を工夫してください。

Git プロトコル

研究の自然な節目でコミットしてください。

タイミング	メッセージのパターン
ワークスペースの初期化	research(init): {project} — {question}
実験プロトコルの確定	research(protocol): {hypothesis}
重要な結果	research(results): {hypothesis} — {outcome}
外側のループでの方針変更	research(reflect): {direction} — {reason}
論文のドラフト完成	research(paper): {title}

厳守事項：プロトコルのコミットは、必ず結果のコミットに先行させてください。両者を決してまとめないでください。git の履歴は簡易的な事前登録となり、結果を見る前に何を計画していたかを証明します。実験のたびにコミットする必要はありません。意味のある進展があったときにコミットしてください。

まとめ：論文の執筆

外側のループで結論を出すことになったら、次の手順に従ってください。

1. findings.md に明確で、十分な裏付けのあるストーリーが記載されていることを確認します
2. 関連性の高い論文を 2～3 本読み、その形式、スタイル、セクション構成を把握します
3. 20-ml-paper-writing スキルを呼び出します。このスキルには、NeurIPS、ICML、ICLR、ACL、AAAI、COLM、およびシステム系の会議向けの LaTeX テンプレートがあります
4. これまでに集めた文献、実験結果、知見を渡します
5. 引用の検証ワークフローに従い、参考文献を決して捏造しないでください
6. 最終的な包括的研究プレゼンテーションを作成します

執筆プロセスは自律的に進めてください。ml-paper-writing スキルが人間との共同作業を提案した場合は、状況に合わせて作業を続け、可能な限り最良のドラフトを作成してください。人間がレビューし、フィードバックを提供します。

研究の原則

特定のフェーズに限定せず、常に徹底する原則です。

• 実行前に確定する：実験を実行する前に、実験プロトコルを Git にコミットします。これにより、結果を確認する前に計画が存在していたことを証明できます。プロトコルと結果を同じコミットにまとめてはいけません。
• 確認的か探索的かを区別する：確定したプロトコルに沿った結果は確認的です。それ以外はすべて探索的な結果であり、興味深いものの、より慎重に評価する必要があります。
• 否定的な結果も進展です：仮説が反証されれば、新たな知見が得られます。その結果によって何が否定され、何が示唆されるのかを記録します。失敗として扱わないでください。
• 分析の前に健全性を確認する：主要な指標を信頼する前に、学習が収束したこと、ベースラインを再現できること、データが正しいことを確認します。
• 行き詰まったら文献に立ち返る：推測せず、検索してください。結果が予想外だったり、前提が崩れたりした場合は、論文を探します。文献の探索には Exa MCP を、特定の ML／AI 論文の検索には Semantic Scholar を、プレプリントには arXiv を使用します。
• 決して止まらない：日常的な判断について、人間の承認を待たないでください。スキルやツールが協働を促している場合は、状況に合わせて対応し、作業を続けます。自律的に最善の進め方を見つけてください。人間は進捗報告を確認し、必要に応じて方向を変えられます。
• 利用可能な計算資源を活用する：ユーザーの環境に合わせて、ローカル GPU、クラスターへのジョブ送信、クラウドインスタンス、CPU のみの環境などに対応します。GPU が利用できない場合は CPU を使い、それに応じて実験規模を調整します。計算資源が使えるようになるまで作業を止めないでください。

品質基準

望ましいエージェントの振る舞い：

• 仮説には「Y であるため X となり、Z が予測される」のようなメカニズムに基づく推論があり、単に「X を試す」だけではありません。
• findings.md は結果を羅列するのではなく、一貫したストーリーを構成しています。
• 否定的な結果は、それによって何が否定されるのかとともに記録されています。
• 実験が予想に反した場合、エージェントは自身のモデルを更新します。
• 進捗報告は、説得力のある可視化を用いて研究のストーリーを伝えています。

望ましくないエージェントの振る舞い：

• 解釈を伴わない、純粋なハイパーパラメーター探索
• findings.md が実験ログをそのままコピーして並べただけになっている
• 失敗の後も、エージェントが前提を見直さない
• 変更がなぜ効果を発揮するのかを理解せずに指標を最適化する

使用する場合と代替手段

次の場合は autoresearch を使用してください：

• 実験によって探究できる研究課題がある
• 内部ループの最適化に使える、測定可能な代理指標がある
• 本質的な貢献には、その指標を超えた統合が必要である
• 自律的な研究を継続的に実行したい

次の場合は、代わりに個別のドメインスキルを使用してください：

• 特定の単発タスク（モデルの学習、評価の実行、論文の執筆）がある
• 反復的な実験が必要ない

よくある問題

内部ループが停滞する（指標が改善しない） 外部ループを実行してください。指標は適切ですか？探索空間を使い切っていますか？探索範囲の拡大や方向転換を検討してください。新しいアプローチを求めて文献を検索してください。

行き詰まり、進展がない 手当たり次第に変更を試し続けないでください。一歩引いて、関連研究を文献で調べるか、21-research-ideation/ のブレインストーミングスキルを呼び出すか、外部ループの振り返りを実行してください。行き詰まっているということは、実験を増やすのではなく、新しい情報や視点が必要だということです。

結果がベースラインの予想と矛盾する 無視せず、調査してください。文献に立ち返り、プロトコルに誤りがないか、公表されたベースラインが誤っていないか、条件が異なっていないかを確認してください。分かったことを findings.md に記録してください。

エージェントがティック間でコンテキストを失う 各アクションの後に research-state.yaml と findings.md が更新されていることを確認してください。これらのファイルがセッションをまたいだ記憶になります。

関連論文が見つからない 次の方法を順番にいくつか試してください。幅広い検索には Exa MCP、特定の ML／AI 論文の検索には Semantic Scholar（pip install semanticscholar）、プレプリントには arXiv（pip install arxiv）を使用してください。API のコード全体については、20-ml-paper-writing スキルの references/citation-workflow.md を確認してください。注：Google Scholar には公式 API がないため、プログラムによる検索には Semantic Scholar を使用してください。

GPU が利用できない CPU を使用し、実験の規模を縮小してください。多くの研究タスク（分析、解釈可能性、小規模なモデルのトレーニング）は CPU で問題なく実行できます。計算リソース不足で作業を止めるのではなく、利用可能な計算能力に合わせて実験設計を調整してください。

実験が /loop の間隔より長くかかる 問題ありません。次のティックで完了したか確認してください。まだの場合は、待つか、ほかの有用な作業（メモの更新、論文の検索など）を行ってください。必要に応じて間隔を調整してください。

いつ結論を出せばよいか分からない 次の3つの質問を考えてください。十分な根拠のある知見がありますか？なぜうまくいくのか説明できますか？findings.md は説得力のある論文の要旨になりますか？すべて「はい」なら、結論を出してください。

高度なトピック

• エージェントの継続性の詳細：references/agent-continuity.md
• 進捗報告のテンプレート：references/progress-reporting.md
• スキルのルーティング全般：references/skill-routing.md

関連スキル

• autogpt-agents：継続的なエージェントを構築、デプロイするための自律型 AI エージェントプラットフォームです。
• research-skill-creator：研究ワークフロー（論文執筆、ラボのプロトコル、分析パイプライン、分野別データベース）に対応するエージェントスキルを作成、改善、テストします。…