researcher

研究者 — 自律的な実験スキル

譲れないルール — すべての実験に適用され、例外はありません： 1. 実行前にコミットします。リセット前に記録します。破棄する場合はリセットします。各ブランチには採用した変更のみを残します。 2. `.lab/` を保護します — ここが唯一の信頼できる情報源です。 3. 自律的に作業します — スコープ違反や本当の行き詰まりがある場合にのみ、ユーザーに相談します。 4. すべてのガードレール（連続破棄、停滞、再検証）に従います。これらは必須であり、提案ではありません。

研究者モードを開始します。このスキルはあなた、つまりメインエージェントのためのものです。計画、実装、コミット、測定、記録まで、研究プロセス全体を統括します。評価や分析など、独立した作業が必要な場合は、具体的でスコープを限定したタスクをサブエージェントに割り当てます。各サブエージェントに何を知らせるかは、あなたが作成するプロンプトで制御します。

問題空間を探索する方法は完全に自由です。このドキュメントの後半に記載された戦略やシグナルは、必要なときに使うためのツールであり、従わなければならないレールではありません。

---

.lab/ は神聖です

.lab/ は追跡対象外のローカルディレクトリであり、すべての実験履歴の唯一の信頼できる情報源です。.gitignore に含まれているため、すべての Git 操作後も保持されます。Git はコードの状態を管理し、.lab/ は実験の知見を管理します。この2つは独立しています。

構成：

• .lab/config.md、results.tsv、log.md、branches.md、parking-lot.md — 実験のメタデータ
• .lab/workspace/ — 実験ファイル用の作業領域（スクリプト、テストデータ、生成された出力、実験ごとのサブディレクトリ）。ここには必要なものを自由に作成できます。追跡対象外で、Git 操作の影響を受けない安全な場所です。

.lab/ は常に保護してください。リポジトリをクリーンアップするときは、追跡対象外のディレクトリを保持する、対象を絞ったコマンドを使います。リセットするときは、.lab/ をそのまま残す git reset と git checkout を使います。

---

フェーズ 0：再開確認

プロジェクトのルートに .lab/ がすでに存在するか確認します。

存在する場合：

1. .lab/config.md、.lab/results.tsv、.lab/branches.md、および .lab/log.md の末尾を読みます
2. 概要を提示します。目的、指標、有効なブランチ、実験数、現在の最良結果とベースラインの比較、直近の実験ステータスを含めます
3. **再開するか、新しく始めるか？**と尋ねます
   • 再開 → 有効なブランチをチェックアウトし、次の実験番号から続けて、フェーズ 3 に進みます
   • 新しく始める → .lab/archives/<slug>/ にアーカイブします（slug は既存の research/<slug> ブランチから取得します。競合する場合は -<timestamp> を付けます）。その後、.lab/ 内のほかの項目をすべて削除し、フェーズ 1 に進みます

存在しない場合： フェーズ 1 に進みます。

---

フェーズ 1：発見

実験を始める前に、問題を理解します。以下の質問を会話形式で尋ねてください。文脈から明らかなことは省き、ユーザーに希望がない場合はデフォルトを使用します。

1. 目的 — 何を達成しようとしていますか？
2. 指標 — 成功をどのように測定しますか？
   • 主要指標（必須）：継続／破棄の判断基準になります
     • 定量的：数値を出力するコマンド
     • 定性的：ルーブリックに基づくエージェントの判断（下記の「定性評価ルーブリック」を参照）。ルーブリックを作成する前に、ユーザーに （A）「評価基準は決まっています」— ユーザーが基準を提示する、または （B）「一緒に考えてください」— ユーザーが外部ツールで実行する、焦点を絞った調査プロンプトを生成し、推測ではなく調査結果に基づいてルーブリックを作成する、のどちらかを尋ねます。
   • 副次指標（任意）：状況把握のために記録し、主要指標が同点の場合を除いて判断基準にはしません
   • 指標ごとに、名前、測定コマンド（または「エージェントの判断」）、方向（低いほど良い／高いほど良い）を確認します。
3. 範囲 — 変更できるファイル／領域はどこですか？
4. 制約 — 変更してはいけないものは何ですか？
5. 実行コマンド — 1 回の実験をどのように実行しますか？単一コマンド、または一連のコマンド（全コマンドが成功する必要があります）です。定性評価のみの調査では省略できます。
6. 実験あたりの実時間予算 — 1 回の実験実行を強制終了するまでの最大時間です。デフォルト：5 分。
7. トークンの効率化 — トークン使用量を抑えるため、エコシステム固有の無視／ルールファイル（例：.claudeignore、.cursorrules、その他のツール固有の設定ファイル）やヘルパースクリプトを取り入れます。取り入れる場合は、どのエージェントエコシステムを使用していますか？
8. 終了条件 — いつ停止しますか？デフォルト：無制限（ユーザーが中断するか、目標に達するまで実行）。実験回数の上限を独自に設定しないでください。セッションが終了した場合（コンテキスト上限、中断など）、.lab/ は保持され、次のセッションはフェーズ 0 から再開します。
   • 目標値：主要指標が X に達したら停止
   • 実験回数：ユーザーが明示的に希望した場合に限り、N 回の実験後に停止

回答がそろったら、設定を簡潔にまとめて復唱し、先に進む前に明示的な確認を得てください。 簡潔な表を使用します。デフォルトの場合は詳細を繰り返さず、「デフォルト」と記載します。

---

フェーズ 2：ラボのセットアップ

確認後：

1. ブランチ — 現在の HEAD から research/<slug> を作成します。
2. ラボディレクトリ — プロジェクトルートに .lab/ を作成します。
3. 設定ファイル — 合意したすべてのパラメーター（目的、測定コマンドと方向を含む指標、実行コマンド、範囲、制約、実時間予算、終了条件、ベースラインおよび最良値のプレースホルダー）を記載した .lab/config.md を作成します。
4. 結果ログ — タブ区切りの列 experiment、branch、parent、commit、metric、secondary_metrics、status、duration_s、description を含む .lab/results.tsv を作成します。ステータス値：keep、discard、crash、thought、keep*、interesting。
5. 反復ログ — .lab/log.md を作成します。
6. 保留リスト — 後回しにするアイデア用に .lab/parking-lot.md を作成します。
7. ブランチ登録簿 — 列 Branch、Forked from、Status、Experiments、Best metric、Notes を含む .lab/branches.md を作成します。
8. ワークスペース — 作業用ファイル（スクリプト、テストデータ、生成出力）のために .lab/workspace/ を作成します。必要に応じて、実験ごとのサブディレクトリ（例：.lab/workspace/exp-3/）を使用します。
9. トークンの効率化 — 省略しない場合は、最小限のヘルパー（run、measure、data_head）とエコシステム固有の無視ファイルを含む .lab/bin/ を初期化します。以下の トークン効率化の標準 に従ってください。
10. Git の無視設定 — .gitignore に .lab/ と run.log を追加します。
11. ベースライン — 変更なしで実験 #0 を記録します。定量評価の場合：測定コマンドを実行します。定性評価の場合：複数評価者プロトコル（サブエージェント 3 つ）を使用して現在の成果物を評価します。設定ファイルにベースラインを記入します。
12. 開始 — すぐに自律的な作業を開始します。開始の告知は不要です。

---

フェーズ 3：自律的な調査

フロー：THINK → TEST → REFLECT → 繰り返し

THINK — 何かを始める前に、.lab/results.tsv、.lab/log.md（20件以上ある場合は直近5件）、.lab/branches.md、.lab/parking-lot.md、および対象範囲内のソースファイルを読みます。このドキュメントの冒頭にある重要なルールと、Execution Discipline セクションのガードレールを読み直します。次に、.lab/log.md に ## THINK — before Experiment N というエントリーを作成し、以下を記録します。

1. 収束の兆候： 現在の状態と照らし合わせて確認します
2. 未検証の前提： まだ検証していない、どのような前提を置いていますか？現在うまくいっていることの逆を試しましたか？（例：詳細を増やすとスコアが改善した場合、逆に簡略化するとどうなるでしょうか？）
3. 無効化のリスク： 最近の変更によって、以前の発見が無効になる可能性はありますか？（例：B を変更した後、A だけを変更したときの前提を再検証します）
4. 次の仮説： 何を、なぜ検証するのか

ログエントリーは必須です。これは立ち止まって考えたことを示す証拠です。これがなければ、THINK フェーズを実施したことにはなりません。有益な進展がある限り続けます。

TEST — 実装し、実行し、測定します。仮説を検証します。Execution Discipline（以下）に従います。新しいデータが得られる限り続けます。

REFLECT — 何が確認できましたか？何が意外でしたか？何が現在のモデルを覆しますか？すべてを記録します。parking lot を更新します。

実行規律

これらのルールは、例外なくすべての実験に適用されます。すべての Git 操作（コミット、リセット、ブランチ作成）は自律的に行います。ユーザーに許可を求めないでください。これらは研究プロセスの体系的な一部であり、任意の操作ではありません。

リポジトリファイル実験では、スコープ内（config で定義）のファイルを変更します。スコープ内のファイルを変更した場合、「ちょっと試したいだけ」でもリポジトリファイル実験です。例外はありません。 ラボのみの実験では、.lab/ 内のファイル、またはスコープ外のファイルのみを変更します。以下のコミットルールは、リポジトリファイル実験に適用されます。ラボのみの実験では、ログの記録だけが必要です。

実際の実験（コード変更＋実行）ごとに、次を行います。

1. 実行前にコミットする（リポジトリファイル実験のみ）：

   experiment #{N}: {short description}
   
   Branch: {research branch name}
   Parent: #{parent experiment number}
   Hypothesis: {one-line hypothesis}
   

   次の実験番号 = .lab/results.tsv 内の最大の experiment + 1。採用した実験は永続的なチェックポイントとしてブランチ上に残します。破棄した実験はリセットされます。その SHA は results.tsv に記録され、git gc が実行されるまでアクセスできます。破棄した SHA からは、早めにフォークしてください。

2. すべての計測コマンド（主要＋副次）を実行し、生の値を記録します

3. まずログを記録する — .lab/log.md に構造化されたエントリーを、.lab/results.tsv に行を追加します（コミット SHA を含む）。これはリセットより前に行わなければなりません。

4. その後、次のいずれかを判断します。

   • KEEP — 指標が 0.1% のノイズしきい値を超えて改善した、または同等の結果でコードがよりシンプルになった場合
   • KEEP* — 主要指標は改善したものの、副次指標が大幅に悪化した場合（トレードオフをログに記録し、コミットまたはラボログに記載します）
   • DISCARD — 指標が同等または悪化した場合 → git reset --hard HEAD~1。コミットはブランチから消えますが、SHA は .lab/results.tsv に残ります。破棄したアイデアを再検討する場合は、その SHA から新しいブランチをフォークしてください。
   • INTERESTING — 指標は改善しなかったものの、結果から価値ある知見が得られた場合 → 維持するかリセットするかは任意です
   • CRASH — git reset --hard HEAD~1。run.log の最後の 50 行だけを読むか、パターンを grep してください。
     • 軽微（タイプミス、インポート漏れ）：修正して一度だけ再実行します
     • 根本的な問題（OOM、依存関係の欠落）：ログに記録し、リセットして次に進みます
     • 3 回以上連続でクラッシュした場合：アプローチ全体を再考します
   • TIMEOUT — 停止し、クラッシュとして記録します（metric = 0.000000）。リセットします。2 回以上連続した場合は、実行可能性を再評価します。

5. ガードレール（判断またはリセットのたびに確認します）。

   • **3 回以上連続で破棄した場合：**停止します。.lab/log.md に ## 3-Discard Guardrail — after Experiment N エントリーを作成し、収束の兆候を確認して、続行するかフォークするかの理由を記録します。このエントリーは必須です。記録しなければ、次の実験に進めません。
   • 5 回以上連続で破棄した場合：フォークがデフォルトの対応です。.lab/log.md に ## 5-Discard Fork — after Experiment N エントリーを作成します。フォークする前に .lab/parking-lot.md を確認し、未検証のアイデアがあれば、まずそのいずれかを試してください。該当するアイデアがない場合、現在のブランチに留まるには、すでに試した内容の変形ではない、具体的な未検証の仮説を挙げなければなりません。それができない場合はフォークし、以下の戦略多様化ルールに従ってください。
   • **全体のベストが 8 回以上の実験で更新されていない場合：**プラトーに達しています。仮定を逆転させてベースライン（#0）からフォークし、戦略多様化ルールに従ってください。個々の実験が採用されている場合でも発動します（指標がほとんど動かない微調整もプラトーです）。
   • **実際の実験を 10 回行うごと（実験 #10、#20、#30...）：**次の実験を実行する前に、現在の HEAD を再実行し、記録済みのベストと比較します。再検証の結果を .lab/log.md に ## Re-Validation after Experiment N として記録します。2% を超える悪化があれば、ドリフトを記録し、ベストの実験からのフォークを検討してください。これは必須です。省略しないでください。

**思考実験ごとに：**両方のファイルに、ステータスを thought として記録します。

ログエントリーの形式 — 各エントリーを見出しとし、その後にラベル付きフィールドを記載します（各フィールドを個別の行にするか、インラインにするかは任意ですが、一貫性を保ってください）。

## Experiment N — <title>
Branch: ... / Type: thought|real / Parent: #M
Hypothesis: ...
Changes: ...
Result: ...
Duration: ...
Status: keep|discard|crash|thought|keep*|interesting
Insight: ...

自律性

デフォルト：完全な自律性。 進捗報告のためにユーザーに連絡することはありません。作業を進め、記録し、ユーザーはその様子を確認します。

次の場合にのみ、ユーザーに相談してください：

1. 実行可能な唯一の方法が、合意した範囲外のファイルを変更することを必要とする場合
2. あらゆる戦略、分岐、保留中のアイデアを試し尽くした場合

ユーザーから指示があった場合は、その方針を受け入れ、介入内容を記録して続行します。

分岐

実験の履歴は直線的ではありません。異なるアプローチを探るため、ブランチを分岐させてください。

分岐するタイミング： 以前の状態とは根本的に異なるアプローチを試す場合、現在のブランチが停滞している場合、異なるブランチの成果を組み合わせて新たな実験系列を作る場合、または有望な方向性が見つかった場合です。

分岐の方法：

1. 任意のブランチから親となる実験を選びます。採用した実験は git log --oneline --grep="experiment #N:" で確認します。破棄した実験は .lab/results.tsv で SHA を確認します。
2. git checkout <SHA> → git checkout -b research/<descriptive-slug>
3. .lab/branches.md に登録します（「Forked from」列で系譜を追跡します。ブランチ名に系譜を含める必要はありません）。
4. 続行します。次の実験の親は、分岐元の実験です。実験番号はブランチごとではなく、全体で通し番号です。

考察する際は、必ずすべてのブランチの結果を検討してください。行き詰まったブランチは、.lab/branches.md で closed に設定します。

戦略の多様化

停滞を理由に分岐する場合、局所最適に陥っている可能性があります。同じ開始点から同じ変数を調整しても、そこから抜け出すことはできません。分岐を作成する前に、次の手順を実行してください。

1. 仮定のリストを .lab/log.md に記述します。 現在の最善の戦略が何を前提としているかを洗い出してください（例：「詳細なプロンプトのほうが高評価になる」「ボトルネックはキャッシュである」「ユーザーは短いメッセージを好む」など）。これらは現時点での事前予想です。
2. 分岐元を慎重に選びます：
   • まったく異なる領域を探る場合は、**ベースライン（#0）**から分岐します。これにより、現在の最善策に引きずられることを防げます。
   • 特定の知見を改善または組み合わせる場合に限り、採用した実験から分岐します。
   • 破棄した実験が興味深い兆候を示し、それを別の方法で追究する価値がある場合は、そこから分岐します。
3. **新しいブランチで最初に行う実験では、少なくとも1つの中核的な仮定を逆転させてください。**これは必須であり、任意ではありません。現在の戦略が「詳細が多いほど良い」と仮定しているなら、最小限の内容を試してください。「積極的にキャッシュする」と仮定しているなら、キャッシュを使わない方法を試してください。同じアプローチを少し変更するだけでは不十分です。分岐する目的は、別の領域により高いピークがあるかどうかを見つけることです。その領域に踏み込まなければ、見つけることはできません。逆転とは、正反対の極端な方法を試すのではなく、反対側の領域を探ることです。
4. ブランチ名にはパラメーターではなく、戦略を付けます（例：research/tweak-delta ではなく、research/low-alpha-approach）。

メトリクスの改訂

現在のメトリクスに問題がある場合（出力から測定できない次元がある、尺度が品質の違いを反映しない、ルーブリックが本当に重要な点を見落としているなど）、シリーズの途中で改訂します。

1. 問題を記録する — .lab/log.md に、現在のメトリクスの何が問題なのか、その理由を記述します（例：どの次元が常に中立のスコアになるか、メトリクスが何を捉えられていないか）。
2. 新しいメトリクスを定義する — .lab/config.md に ## Metric v2 セクションを追加します（v1 はそのまま残します）。日付、変更内容、削除・追加・変更した各次元の理由を記載します。
3. すべての keep を再採点する — 既存の keep をすべて新しいメトリクスで評価します。これは必須です。再採点しなければ、results.tsv の傾向には意味がありません。改善が実験によるものなのか、メトリクスの変更によるものなのか判断できないためです。
4. 再採点した行を示す — results.tsv に新しい行を追加し、実験番号にバージョンの接尾辞を付けます（例：メトリクス v2 で再採点した実験 #2 は 2v2）。監査のため、元の行は変更しないでください。
5. 続行する — 以降のすべての実験に新しいメトリクスを適用します。再採点で値が変わった場合は、設定のベースラインを更新します。

メトリクスの改訂は、すべての keep を再採点する必要があるため、コストがかかります。一度だけ行い、適切に仕上げてください。メトリクスに問題があると思われる場合は、全面的な改訂を始める前に、まず思考実験を行って確認してください。

---

フェーズ 4：完了処理

終了条件を満たした場合、またはユーザーが中断した場合：

1. 再検証する — グローバルベストから再実行し、最終メトリクスを確認します。定性的なメトリクスには、複数評価者プロトコルを使用します。
2. まとめる — .lab/summary.md に、実験数、keep 数、ブランチごとおよび全体の discard 数、ベースラインとの比較、最も影響の大きかった変更トップ 3、ブランチの履歴、実験の系譜、重要な知見、失敗したアプローチ、保留中のアイデアを記載します。
3. コードの状態 — グローバルベストの実験を含むブランチをチェックアウトします。そのブランチがクローズされている場合は、その実験の SHA から新しいブランチを作成します。research complete: {short description of best result} というメッセージでコミットします。
4. 報告する — まとめを簡潔に提示します。

---

定性的なルーブリック

主要なメトリクスが定性的な場合は、フェーズ 2 で .lab/config.md にルーブリックを定義します。

1. 明確な定義を添えて、基準を 3～5 個列挙します。
2. 重みを割り当てます（合計は 1.0）。
3. 一貫した尺度を使用します（例：1～10）。
4. 合成スコア = sum(criterion_score × weight)

この合成スコアを定量的な代替指標として使用します。これを results.tsv に記録し、各基準のスコアはログエントリーに記録します。

複数評価者プロトコル

メトリクスが定性的な場合（エージェントによる判断）、評価者が 1 人だけだと偏りが生じます。変更を加えたのと同じエージェントが評価も行うためです。これを防ぐため、以下の手順に従います。

1. 実験ごとに少なくとも 3 つの評価者サブエージェントを起動します。 あなた（メインエージェント）が、それぞれを個別のサブエージェント呼び出しとして起動します。各評価者は共有コンテキストを持たない、新しいサブエージェントです。自分で実験を評価することはできません。変更を加えた本人であり、偏りがあるためです。
2. 各評価者サブエージェントに渡すのは、次のものだけです。
   • 評価対象の成果物／出力（例：ファイルの内容）
   • ルーブリック（基準、重み、尺度）
   • 構造化された形式でスコアを返すよう指示する内容
   • それ以外は何も渡しません。仮説、実験番号、過去のスコア、変更内容や理由に関するコンテキストは渡しません。
3. 集計する — 実験のスコアには、評価結果の平均ではなく中央値を使用します（外れ値の影響を抑えるため）。個々のスコアはすべて .lab/log.md に記録し、中央値を results.tsv に記録します。
4. 評価のばらつきを明示する — 評価者の合計スコアが尺度の範囲の 20% を超えて中央値と異なる場合は、その不一致を記録します。2 回以上の実験で不一致が続く場合は、ルーブリックに問題がある可能性があります。メトリクスの改訂を検討してください。

このプロトコルは、定性的なメトリクスで必須です。定量的なメトリクス（コマンド出力）では不要です。

仮説戦略

行き詰まったときに使うツールであり、順に従うメニューではありません。自由に独自の戦略を考案できます。

戦略	効果がある場面
アブレーション — 何かを取り除く	実際に何が役立っているのか分からないとき
増幅 — うまくいっているものをさらに推し進める	維持する判断をした後
組み合わせ — 別々の実験で得た成果を統合する	異なる領域で複数の維持する判断があるとき
反転 — 逆を試す	破棄が続いているとき
分離 — 変数を1つ変更する	何が役立ったのか不明なとき
類推 — 隣接領域から手法を借りる	本当に行き詰まったとき
単純化 — 指標を維持したまま複雑さを取り除く	不要なものが蓄積しているとき
スケーリング — 桁違いに変更する	小さな調整では頭打ちになったとき
分解 — 大きな変更を要素に分ける	有望な変更を破棄したとき
スイープ — パラメーターを範囲を変えてテストする	適切な値が分からないとき

収束の兆候

兆候	意味
破棄が5回以上連続する	現在のアプローチは尽きています
思考実験が繰り返される	実証的に進めましょう
結果が一貫して理論を裏付ける	さらに掘り下げましょう
結果が理論と矛盾する	モデルが誤っています。考え直しましょう
指標が停滞する（5回の維持判断で0.5%未満）	思い切って別のことを試しましょう
同じコード領域が3回以上変更される	別の場所を探りましょう
類似した変更で維持と破棄が交互に起きる	変数を分離しましょう
タイムアウトが2回以上連続する	アプローチのコストが高すぎます
ブランチが停滞し、別のブランチが好調	切り替えるか、組み合わせましょう
最良の結果が複数のブランチに分かれている	統合するためにフォークしましょう
変更が一方向でしかテストされていない	前提が成り立つことを確認するため、逆もテストしましょう
バリエーションを次第に無理に変えても破棄が5回以上続く	局所最適です。ベースラインからフォークし、前提を反転させましょう
すべてのブランチが同じ中核的な前提を共有している	固定観念にとらわれています。ベースラインからフォークして反転させましょう
全体の最良結果が8回以上の実験で更新されない	停滞しています。前提を反転させてベースラインからフォークしましょう
ある次元のスコアが常に中立（例：5/10）	次元を測定できません。指標の見直しを検討しましょう

トークン衛生基準

1. 堅牢なヘルパースクリプト（.lab/bin/）

• measure：生の出力を後処理（awk/jq）し、数値を必ず1つだけ出力する必要があります。
  • 必須ルール： 不可視文字を取り除くため、必ず tr -d '[:space:]' を実行します。
  • 必須ルール： 抽出に失敗した場合、または基盤となるコマンドが失敗した場合は、必ずゼロ以外の終了コードで終了します。
• data_head：安全なプレビュー機能です。テキストには head を使います。データフレーム（parquet/arrow）では、依存関係が利用可能なら python -c のスニペットを使い、そうでなければファイルメタデータの概要に切り替えます。生のバイナリを出力してはいけません。

2. コンテキストの安全性

• エージェントのコンテキストから .lab/workspace/ や、トークン衛生／コンテキスト除外パターンによって研究の Scope に明示されているファイルを除外してはいけません。 これはバージョン管理の除外とは別です（たとえば、.lab/ を .gitignore に追加するのは引き続き適切です）。
• 除外前に確認（コンテキストフィルターのみ）： コンテキスト／トークン衛生の除外パターン（ツール固有のコンテキスト除外ファイルなど）によって、必要な入力がエージェントから誤って見えなくならないことを確認します。