autoresearch-create

Autoresearch

自律型実験ループ：アイデアを試し、うまくいったものを残し、うまくいかなかったものを破棄し、決して止まりません。

ツール

• init_experiment — セッションを設定します（名前、メトリック、単位、方向）。最適化対象が変わったときは、ベースラインを新たに設定するために再度呼び出します。
• run_experiment — コマンドを実行し、所要時間を計測して、出力を取得します。
• log_experiment — 結果を記録します。keep は自動的にコミットします。discard／crash／checks_failed はコード変更を自動的に元に戻します（autoresearch のファイルは保持されます）。必ず副次的な metrics 辞書も含めてください。ダッシュボード：ctrl+shift+t。

セッションファイル

すべてのセッションファイルは、作業ディレクトリのルートにある単一の .auto/ サブフォルダーに保存されます。これにより、すべてを一か所にまとめて、元に戻す操作をまたいだ保持、gitignore、クリーンアップが簡単になります。

ファイル	用途
.auto/prompt.md	実験プロンプト／プレイブック（セッションの中核）
.auto/measure.sh	ベンチマークスクリプト — METRIC name=value 行を出力します
.auto/log.jsonl	追記専用の結果ログ（ツールによって書き込まれます）
.auto/ideas.md	アイデアのバックログ（任意）
.auto/checks.sh	正確性チェック（任意）
.auto/config.json	セッション設定（任意）
.auto/hooks/{before,after}.sh	ライフサイクルフック（任意）

ファイルは必ず .auto/ のレイアウトで作成してください。進行中のセッションでは従来のフラットな autoresearch.* ファイルも引き続き読み込まれますが、新しいセッションでは .auto/ を使用してください。

セットアップ

1. 目標、コマンド、メトリック（＋方向）、対象ファイル、制約を確認します（または推測します）。
2. git checkout -b autoresearch/<goal>-<date>
3. ソースファイルを読みます。何かを書く前に、ワークロードを深く理解してください。
4. mkdir -p .auto を実行し、.auto/prompt.md と .auto/measure.sh を作成します（下記を参照）。両方をコミットします。
5. init_experiment → ベースラインを実行 → log_experiment → すぐにループを開始します。

.auto/prompt.md

これはセッションの中核です。コンテキストがない新しいエージェントでも、このファイルを読んで効果的にループを実行できる必要があります。優れたファイルになるよう、時間をかけて作成してください。

# Autoresearch: <goal>

## Objective
<Specific description of what we're optimizing and the workload.>

## Metrics
- **Primary**: <name> (<unit>, lower/higher is better) — the optimization target
- **Secondary**: <name>, <name>, ... — independent tradeoff monitors

## How to Run
`./.auto/measure.sh` — outputs `METRIC name=number` lines.

## Files in Scope
<Every file the agent may modify, with a brief note on what it does.>

## Off Limits
<What must NOT be touched.>

## Constraints
<Hard rules: tests must pass, no new deps, etc.>

## What's Been Tried
<Update this section as experiments accumulate. Note key wins, architectural
insights, and discarded ideas: why they failed and what would justify revisiting them.>

.auto/prompt.md は定期的に更新してください。特に「試したこと」セクションを更新し、再開するエージェントが十分なコンテキストを得られるようにします。

.auto/measure.sh

set -euo pipefail を指定した Bash スクリプトで、事前チェックをすばやく行い（構文エラーを1秒未満で検出）、ベンチマークを実行して、構造化された行を標準出力に出力します。スクリプトは高速に保ってください。1秒の差でも数百回の実行で積み重なります。

高速でばらつきの大きいベンチマーク（5秒未満）の場合は、スクリプト内でワークロードを複数回実行し、中央値を報告してください。これにより安定したデータポイントが得られ、最初から信頼性の高い信頼度スコアを算出できます。低速なワークロード（ML のトレーニング、大規模なビルド）では不要です。1回の実行で問題ありません。

構造化出力

• METRIC name=value — 主メトリック（init_experiment の metric_name と一致する必要があります）と、任意の副次メトリック。run_experiment が自動的に解析します。

最適化に役立つスクリプトを設計する

スクリプトでは、次のイテレーションでより良い判断を下すために役立つデータをすべて出力してください。 各実行後にどこに注力すべきか判断するため、何を確認する必要があるか考えてください。

• ワークロードに異なる段階がある場合は、各段階の所要時間
• チェックがさまざまな形で失敗する可能性がある場合は、エラー数、失敗の分類、テスト名
• 関連する場合は、メモリ使用量、キャッシュヒット率、その他のランタイム診断情報
• リグレッションの箇所を特定したり、ボトルネックを見つけたりするのに役立つ、ドメイン固有の情報

スクリプトは各イテレーションで同じコードを実行しますが、必要な情報が足りないとわかった場合は、ループの実行中に更新できます。 重要な情報を学びながら、計測項目を追加してください。

エージェントが指定する ASI（log_experiment 経由）

log_experiment の asi パラメーターを使って、各実行に次のイテレーションがより良い判断をするのに役立つ情報を自由に注釈してください。自由形式のキーと値のペアで、何を記録するかは自分で判断します。説明や生の出力を繰り返さず、コンテキストがリセットされた後に失われる情報を記録してください。

失敗やクラッシュは詳しく注釈してください。 破棄された実行やクラッシュした実行は元に戻され、コードの変更は失われます。残る記録は .auto/log.jsonl の説明と ASI だけです。何を試し、なぜ失敗したのかを記録しないと、次のイテレーションで同じ行き止まりを再発見するために時間を浪費することになります。

.auto/config.json（任意）

pi セッションの作業ディレクトリ（ctx.cwd）内にある .auto/ に配置する JSON 設定ファイルです。次のフィールドに対応しています。

• maxIterations（数値）— 自動停止するまでの実験の最大回数です。
• workingDir（文字列）— すべての自動リサーチ操作の対象ディレクトリを指定します。ファイル入出力（.auto/log.jsonl、.auto/prompt.md、.auto/measure.sh、.auto/checks.sh、.auto/ideas.md）、コマンド実行、Git 操作が対象です。絶対パスまたは相対パスを指定できます（相対パスは ctx.cwd を基準に解決されます）。設定ファイル自体は常に ctx.cwd 内に置かれます。指定したディレクトリが存在しない場合は失敗します。

{
  "workingDir": "/path/to/project",
  "maxIterations": 50
}

.auto/checks.sh（任意）

バックプレッシャー／正確性チェック（テスト、型チェック、Lint など）を実行する Bash スクリプトです（set -euo pipefail）。正確性の検証がユーザーの制約で求められる場合（例：「テストが通ること」「型チェックを行うこと」）に限り、このファイルを作成してください。

このファイルが存在する場合：

• run_experiment で成功したベンチマークの後に毎回自動実行されます。
• チェックに失敗すると、run_experiment がその旨を明確に報告します。checks_failed として記録してください。
• 実行時間は主要指標に影響しません。
• チェックに失敗した結果を keep することはできません。
• 専用のタイムアウトがあります（デフォルトは 300 秒で、checks_timeout_seconds から設定できます）。

このファイルが存在しない場合、ループに変更はなく、従来どおりに動作します。

出力は最小限にしてください。 チェックの出力は、失敗時に最後の 80 行だけがエージェントに返されます。進捗や成功に関する冗長な出力は抑制し、エラーだけを出力してください。これによりコンテキストを節約し、エージェントが問題の原因を特定しやすくなります。

#!/bin/bash
set -euo pipefail
# Example: run tests and typecheck — suppress success output, only show errors
pnpm test --run --reporter=dot 2>&1 | tail -50
pnpm typecheck 2>&1 | grep -i error || true

ループのルール

ループを永久に続けてください。 「続けてもよいですか？」と尋ねないでください。ユーザーは自律的な作業を期待しています。

• 主要指標を最優先します。 改善したら keep、悪化または同等なら discard します。二次指標がこれに影響することはほとんどありません。
• すべての実行に asi で注釈してください。 実行したことではなく、学んだことを記録します。次のイテレーションや、このセッションを引き継ぐ新しいエージェントに役立つ情報は何でしょうか？
• 信頼度スコアに注目してください。 3 回以上実行すると、log_experiment が信頼度スコアを報告します（セッションのノイズフロアに対する、最良の改善幅の倍率）。2.0 倍以上なら、改善は実際に起きている可能性が高いです。1.0 倍未満ならノイズの範囲内です。結果を keep する前に、確認のための再実行を検討してください。このスコアは参考情報であり、自動的に破棄することはありません。
• シンプルなほうが優れています。 性能が同等でコードを削除できるなら keep します。わずかな改善のために複雑さが増すなら、通常は discard します。
• 同じことを繰り返さないでください。 同じアイデアを何度も元に戻している場合は、構造的に異なる方法を試してください。
• クラッシュ： 簡単に直せるなら修正し、そうでなければ記録して先に進みます。過度に時間をかけないでください。
• 行き詰まったら、じっくり考えてください。 ソースファイルを読み直し、プロファイリングデータを調べ、CPU が実際に何をしているのかを考察してください。優れたアイデアは、手当たり次第に変化を試すのではなく、深い理解から生まれます。
• 再開する場合： .auto/prompt.md が存在する場合は、それと Git ログを確認して、ループを続けてください。

決して停止しないでください。 ユーザーが何時間も離れている場合があります。中断されるまで続けてください。

アイデアのバックログ

複雑でも有望な最適化を見つけたものの、今すぐ取り組まない場合は、.auto/ideas.md に箇条書きで追記してください。良いアイデアを失わないようにしてください。

再開時（コンテキスト制限やクラッシュの後）は、.auto/ideas.md を確認し、古くなった項目や試行済みの項目を削除して、残りを実験してください。試せる方法がすべて尽きたら、このファイルを削除し、最終的なまとめを書いてください。

実験中のユーザーメッセージ

実験の実行中にユーザーがメッセージを送信した場合は、まず現在の run_experiment + log_experiment サイクルを完了してから、次のイテレーションでフィードバックを反映してください。実行中の実験を中断しないでください。