experiment-pipeline

実験パイプライン

初期実装からアブレーション研究まで、試行予算とゲート条件を設けて無駄な労力を防ぎながら研究実験を実行するための、体系的な4段階フレームワークです。EvoScientist 論文の Experiment Tree Search 設計に基づいており、エンジニアエージェントが実行可能なコードを反復的に生成して実験を実行し、各段階で構造化された実行結果を記録します。

このスキルを使うタイミング

• ユーザーが実験を計画しており、実行ワークフローを整理する必要がある
• ユーザーが新しい手法をベースラインに対して体系的に検証したい
• ユーザーが実験段階、試行予算、または次に進むタイミングについて質問している
• ユーザーが手法をテストする前にベースライン結果を再現する必要がある
• ユーザーが「実験パイプライン」「まずはベースライン」「アブレーション研究」「段階別予算」「実験実行」について言及している

パイプラインの考え方

実験が失敗する理由は、順序の誤りと停止基準の欠如の2つです。 多くの研究者は、ベースラインの設定を確認せずに新しい手法のテストに直行し、結果が意味をなさない理由に悩みます。また、次の実行がうまくいくことを期待して、予算を決めずに何週間もハイパーパラメーターを調整する人もいます。

この4段階パイプラインは、両方の問題を解決します。厳格な順序を徹底し（各段階で、次の段階が前提とする仮定を検証します）、試行予算を割り当てることで（力任せの反復よりも体系的な思考を促します）。

開始前：過去の知見を読み込む

research-ideation から引き継ぐ場合、研究提案（ステップ7）に実験計画が記載されています。この計画にはデータセット、ベースライン、評価指標、アブレーション設計が含まれ、以下のステージ1～4に直接対応します。

パイプラインに入る前に、過去のサイクルから実験メモリー（M_E）を読み込みます。

1. evo-memory スキルを参照 → /memory/experiment-memory.md から M_E を読み込みます
2. 各エントリーの Context と Category を現在の問題と比較し、現在の実験領域に最も関連する上位1件（k_E=1）を選びます
3. 選択した戦略は、ハイパーパラメーターの範囲（ステージ2）、デバッグ方法（ステージ1～3）、およびすべての段階における学習設定の参考になります
4. まだ M_E が存在しない場合（初回のサイクル）は、この手順を省略して先に進みます。パイプライン完了後、ESE を通じて実験結果が M_E に蓄積されます

4段階パイプラインの概要

各段階では、生成 → 実行 → 記録 → 診断 → 改訂のループを行います。

段階	目標	予算（N_E^s）	ゲート条件
1. 初期実装	ベースラインコードを実行し、既知の結果を再現する	≤20 回	評価指標が報告値の2%以内（または報告された分散の範囲内）
2. ハイパーパラメーター調整	使用環境に合わせて設定を最適化する	≤12 回	安定した設定で、3回の実行における分散が5%未満
3. 提案手法	新しい手法を実装して検証する	≤12 回	主要評価指標で調整済みのベースラインを上回り、3回の実行で一貫した結果が得られる
4. アブレーション研究	各コンポーネントの貢献を証明する	≤18 回	すべての主張が統制された実験で裏付けられている

各段階の成果物は /experiments/stageN_name/ に保存されます。

段階ごとのループ

各段階では、試行ごとに次のサイクルを繰り返します。

1. 生成：今回の試行で検証する仮説や計画を立てます。具体的に何を試すのか、何が起こると予想するのかを決めます。
2. 実行：実験を実行します。正確な設定、コードの変更内容、実行時間を記録します。
3. 記録：段階別ログのテンプレートを使って、直ちに結果を記録します。評価指標と所見の両方を含めます。
4. 診断：結果を予想と比較します。一致する場合は、ゲート条件を評価します。一致しない場合は、experiment-craft を読み込み、5段階の診断フローに従います。
5. 改訂：診断に基づき、次の段階に進む（ゲート条件を満たした場合）か、次の試行を計画する（ゲート条件を満たしていない場合）かを決めます。

ステージ 1：初期実装

目標：実行可能なベースラインコードを見つけるか生成し、公開済みの結果を再現できることを検証します。このステージは、論文の「初期実装」に相当します。エンジニアエージェントが動作するコードを探して実行し、構造化された実行結果を記録します。

重要な理由：ベースラインを実行して既知の結果を再現できなければ、それ以降の比較には意味がありません。初期実装により、データパイプライン、評価コード、トレーニングインフラストラクチャ、先行研究への理解を検証できます。

試行回数の上限：20 回以内（N_E^1=20）。ベースラインの実行には手間がかかる場合があります。論文に記載されていない詳細、バージョンの不一致、報告されていない前処理手順などが原因です。20 回あれば、際限なく試行錯誤することなく、デバッグに十分な余裕ができます。

判定基準：主要な指標が報告値の 2% 以内であること（または、分散が報告されている場合はその範囲内であること）。

手順：

1. 元のベースラインコードを見つけます（公式リポジトリ、再実装、または論文の説明に基づく実装）
2. コードを自分の環境で実行できるようにします。依存関係を解決し、互換性の問題を修正します
3. 論文のトレーニング設定（データセットの分割、前処理、ハイパーパラメーター）を正確に合わせます
4. 実行して指標を比較します。差が 2% を超える場合は、原因を診断します
5. よくある落とし穴：異なる乱数シード、異なるデータ分割、報告されていないデータ拡張、フレームワークのバージョンの違い

experiment-craft を読み込むタイミング：最初の 1～5 回の試行ですべて大きな差（10% 超）が生じた場合は、それ以上試行回数を費やす前に、5 ステップの診断フローに切り替えて原因を特定します。

出力：結果、設定、検証済みのベースラインコードを含む /experiments/stage1_baseline/。

初期実装の詳細なチェックリストについては、references/stage-protocols.md を参照してください。

ステージ 2：ハイパーパラメーターの調整

目標：自分の環境に最適なハイパーパラメーター設定を見つけます。

重要な理由：公開されているハイパーパラメーターは、著者の環境に合わせて調整されています。ハードウェア、データのバージョン、フレームワークのバージョン、または微妙な実装の違いによって、著者の設定が自分の環境に最適とは限りません。この段階で調整しておくことで、最適でないベースラインが新しい手法の結果に影響するのを防げます。

試行回数の上限：12 回以内。ハイパーパラメーター調整の効果は次第に小さくなります。構造化された 12 回の試行で安定した設定が見つからない場合、問題はハイパーパラメーターより根深い可能性があります。

判定基準：安定した設定が見つかること。異なる乱数シードを用いた独立した 3 回の実行で、分散が 5% 未満であること。

手順：

1. 影響の大きいハイパーパラメーターを特定します（通常は、学習率、バッチサイズ、損失の重み）
2. 最も影響の大きいパラメーターについて、粗い範囲で探索を開始します
3. 結果に基づいて範囲を絞り、次のパラメーターに進みます
4. 独立した 3 回の実行で最終設定を検証します

調整の優先順位：学習率 → バッチサイズ → 損失の重み → 正則化 → アーキテクチャ固有のパラメーター。この順序は、一般的な影響の大きさを反映しています。

experiment-craft を読み込むタイミング：実行ごとの結果が大きく不安定（分散が 20% 超）な場合は、トレーニングが不安定になっている可能性があります。診断フローを使用してください。

出力：調整ログ、最終設定、安定性の検証結果を含む /experiments/stage2_tuning/。

試行回数の上限の根拠と調整ルールについては、references/attempt-budget-guide.md を参照してください。

ステージ 3：提案手法

目標：独自の手法を実装して検証し、調整済みのベースラインを上回る改善を示します。

重要な理由：ここが中核となる貢献です。ただし、ベースライン（ステージ 1）を検証し、設定を最適化（ステージ 2）しているため、改善が見られた場合、それはより適切に調整されたセットアップや壊れたベースラインではなく、実際に手法によるものだと判断できます。

予算：12 回以下の試行です。根本的なアイデアが妥当であれば、妥当な反復回数で手法が機能するはずです。試行回数が過剰になる場合、調整の問題ではなく、根本的な問題がある可能性があります。

通過条件：主要指標で調整済みのベースラインを上回ること。少なくとも 3 回の実行で一貫して改善している必要があります。

プロセス：

1. 中核となる手法を段階的に実装します。一度にすべて追加しないでください
2. 各コンポーネントとベースラインパイプラインとの統合をテストします
3. トレーニング全体を実行し、ステージ 2 の結果と比較します
4. 性能が低い場合は、どのコンポーネントが差の原因かを特定します

統合戦略：動作するベースラインに、手法のコンポーネントを 1 つずつ追加します。追加した各コンポーネントの性能は、ベースラインの 20％以内に収めてください。1 つのコンポーネントによって 20％を超える性能低下が生じた場合は、先にそれを切り分けてデバッグします。手法全体を一度に統合してはいけません。

experiment-craft を読み込むタイミング：正しく実装しているにもかかわらず、手法の性能がベースラインを下回る場合です。5 段階の診断フローにより、実装上のバグと根本的な問題を区別できます。

重要な判断 — 失敗の分類：試行予算を使い切っても手法の性能がベースラインを下回る場合は、IVE（アイデア検証の進化）のために evo-memory に引き継ぎます。これは evo-memory の役割であり、このスキルの役割ではありません。IVE は次の 2 つの条件で開始されます。

1. 実行可能なコードがない：どの段階でも、予算内に動作するコードが見つからない場合。
2. ベースラインより性能が低い：実験は完了したものの、手法の性能が低い場合。

evo-memory スキルは、失敗を次のように分類します。

• 実装上の失敗：バグや不足しているテクニック → 次のサイクルで再試行できます。
• 方向性の根本的な失敗：中核となるアイデアが機能しない → 再試行を防ぐため、アイデア創出のメモリーを更新します。

出力：手法のコード、結果、ベースラインとの比較を含む /experiments/stage3_method/。

ステージ 4：アブレーションスタディ

目標：手法の各構成要素が最終結果に有意義な貢献をしていることを証明します。

重要な理由：査読者は、手法のあらゆる部分について「構成要素 X は本当に必要なのか」と尋ねます。アブレーションがなければ、答えられません。さらに重要なのは、アブレーションによって手法が機能する理由を理解できることです。重要だと思っていた構成要素が実際には重要でなかったり、その逆だったりすることもあります。

予算：≤18 回の試行。アブレーションには複数の条件を制御した実験が必要です。除去する構成要素ごとに 1 回ずつ行い、さらに相互作用の効果も調べます。18 回あれば、構成要素が 4〜5 個ある手法を検証できます。

ゲート：主張する貢献のすべてが、その効果を示す条件を制御した実験によって裏付けられていること。

プロセス：

1. 性能に貢献すると主張する手法の構成要素をすべて列挙します
2. アブレーション実験を設計します。構成要素を一度に 1 つだけ取り除き、影響を測定します
3. 相互作用する構成要素については、相互作用の効果を検証します
4. いずれかの構成要素を取り除くことで結果が改善しないことを確認します（改善する場合、その主張は無効になります）

3 つのアブレーション設計：

• 1 要素除去法：各構成要素を個別に取り除きます。各構成要素の限界的な貢献を示します。
• 段階的追加法：ベースラインから始め、構成要素を 1 つずつ追加します。段階的な性能向上を示します。
• 置換法：構成要素を別の手法に置き換えます。単に何もない状態より優れているだけでなく、代替手法よりも優れていることを示します。

experiment-craft を読み込むタイミング：アブレーション結果が仮説と矛盾する場合（構成要素を取り除くと結果が改善する場合）は、診断フローを使って理由を把握します。

出力：アブレーション結果の表と構成要素ごとの分析を含む /experiments/stage4_ablation/。

アブレーション設計パターンの詳細については、references/stage-protocols.md を参照してください。

診断のための experiment-craft の統合

ステージの試行が失敗した場合は、体系的な診断のために experiment-craft スキルを参照してください。

1. experiment-craft の診断プロトコルに従います
2. 5 段階の診断フロー（観察、仮説、検証、結論、処方）を実行します
3. 診断ではステージの予算を消費しません。無料の分析ステップです
4. 診断の出力（処方）を次の試行の計画にします
5. パイプラインに戻り、診断内容を実験履歴ログに記録します

実行タイミング：いずれかのステージで試行が失敗した後。特に重要なのは次の場合です。

• ステージ 1：5 回以上試行に失敗した後（報告されたメトリクスとの差が 10% を超える場合）
• ステージ 2：実行間の分散が 20% を超える場合
• ステージ 3：手法の性能が一貫してベースラインを下回る場合
• ステージ 4：アブレーション結果が仮説と矛盾する場合

コード実験履歴の記録

すべてのステージで、各試行について、何をしたかだけでなく、なぜ行ったか、何を学んだかも記録できる構造化形式でログを残します。これらのログは、evo-memory の Experiment Strategy Evolution（ESE）メカニズムに取り込まれます。

各試行について、次の内容を記録します。

• 試行番号とステージ
• 仮説：何を予測したか、その理由
• コードの変更：変更内容の要約（差分全体ではなく、主な変更点）
• 結果：メトリクスと観察内容
• 分析：仮説が裏付けられたか、否定されたか、そこから何を学んだか

記録形式の詳細と、ログが evo-memory に取り込まれる仕組みについては、references/code-trajectory-logging.md を参照してください。

直感に反するパイプラインのルール

実験を実行する際は、次のルールを優先してください。

1. 初期実装は時間の無駄ではありません：インフラ全体、つまりデータパイプライン、評価コード、トレーニング環境を検証できます。これを省略すると、その後のすべての結果が未検証の土台に基づくことになります。「手法が機能しない」という問題の多くは、実際にはベースラインの設定ミスです。

2. 予算の上限が迷走を防ぎます：試行回数の上限を設けることで、体系的に考えざるを得なくなります。試行が12回だと分かっていれば、それぞれから最大限の情報を得られるように設計します。上限がなければ、47回目の試行が12回目より有益であることはほとんどなく、たださらに切羽詰まっているだけです。

3. ステージの順序は変更できません：各ステージでは、次のステージが前提とする仮定を検証します。ステージ1を省略すると、ベースラインに不備があるためにステージ3の結果が誤っている可能性があります。ステージ2を省略すると、ステージ3での改善は手法の向上ではなく、ハイパーパラメーターの改善にすぎない可能性があります。近道はありません。

4. アブレーションは任意の後処理ではありません：手法が正しい理由で機能していることを示す、主要な根拠です。ベースラインを上回っていてもアブレーションのない手法は、理解できていない手法です。査読者はそれを見抜きます。

5. 失敗した試行は無駄ではなくデータです：失敗した試行のたびに探索空間が絞られ、問題について新たなことが分かります。失敗は注意深く記録してください。evo-memory に反映され、後の研究者が同じ間違いを繰り返すのを防げます。

6. 早期終了は有効な選択肢です：予算を使い切る前に停止するのは賢明な判断であり、怠慢ではありません。体系的に試した結果、ゲートの達成が明らかに不可能であれば、残りの予算を次第に無作為な変更に費やすのではなく、evo-memory の IVE にエスカレーションしてください。

論文執筆への引き継ぎ

4つすべてのステージが完了したら、次の成果物を paper-writing に渡してください。

成果物	生成元のステージ	使用先
初期実装の結果	ステージ1	比較表、設定の検証
最適なハイパーパラメーター設定	ステージ2	再現性のセクション
手法とベースラインの比較	ステージ3	主結果の表
アブレーション研究の結果	ステージ4	アブレーション表、貢献に関する主張
コードの軌跡ログ（全ステージ）	全ステージ	手法セクションの詳細、補足資料
実装の詳細と工夫	ステージ1～3	手法セクション、再現性（軌跡ログの Analysis フィールドと [Reusable] タグに記録）

結果は進化の更新のために evo-memory にも渡してください。

• いずれかのステージで実行可能なコードがないまま予算を使い切った場合、またはステージ3の手法が調整済みのベースラインを下回った場合 → IVE（アイデア検証進化）を起動します
• すべてのステージが成功した場合 → ESE（実験戦略進化）を起動します

スキルの連携

開始前（メモリーを読み込む）

evo-memory スキルを参照して、Experimentation Memory を読み込みます。 → M_E を /memory/experiment-memory.md から読み込みます

失敗時（いずれかのステージ内）

experiment-craft スキルを参照して、5段階の診断を行います。 → 診断を実行 → パイプラインに戻ります

IVE の起動時（予算超過または手法の性能不足）

evo-memory スキルを参照して、失敗を分類します。 → IVE プロトコルを実行します

パイプライン成功時（4ステージすべて完了）

evo-memory スキルを参照して、戦略を抽出します。 → 軌跡ログを使用して ESE プロトコルを実行します

論文執筆への引き継ぎ

paper-writing スキルを参照します。 → すべてのステージの成果物を渡します

リファレンスナビゲーション

トピック	リファレンスファイル	使用するタイミング
ステージごとのチェックリストとパターン	stage-protocols.md	各ステージの詳細なガイダンス
試行予算の根拠と調整	attempt-budget-guide.md	予算が厳しすぎる、または緩すぎると感じるとき
コードの軌跡のログ形式	code-trajectory-logging.md	evo-memory 用に試行を記録するとき
ステージログのテンプレート	stage-log-template.md	1つのステージの進捗を記録するとき
パイプライントラッカーのテンプレート	pipeline-tracker-template.md	4ステージのパイプライン全体を追跡するとき