experiment-craft

Experiment Craft

研究実験の実施、デバッグ、反復を体系的に進める方法です。重要なのは実験の数を増やすことではなく、実験が失敗する理由を理解することです。

このスキルを使用するタイミング

• ユーザーの実験がうまくいかない、または予想外の結果が出る
• 特定のデータで手法が失敗する理由の診断をユーザーが必要としている
• ユーザーが、構造化されたログ記録によって実験プロセスを整理したい
• ユーザーが研究コードのデバッグやアプローチの反復について質問する
• ユーザーが「実験のデバッグ」「なぜうまくいかないのか」「実験ログ」「結果が間違っている」と言及する

このスキルは通常、ステージの試行が失敗した際に experiment-pipeline から読み込まれます。デバッグ後は、パイプラインのステージゲート構造に戻って続行してください。あらゆる実験のデバッグに単独で使用することもできます。

デバッグの考え方

実験が失敗する理由を見つけることは、最も重要な研究スキルです。 結果を分析しないと、次の2つの失敗につながります。

1. 進捗の遅れ：失敗の原因を理解しないまま、手当たり次第に実験を実行する
2. 時間の浪費：活性化の工夫を見落とし、有望なアプローチを断念する

目標は実験の数を増やすことではありません。原因を切り分け、具体的な仮説を検証する適切な実験を行うことです。

5ステップの診断フロー

実験が失敗したり、予想外の結果が出たりした場合は、次の5つのステップに従ってください。

ステップ1：失敗事例を集める

悪い結果の具体例を集めます。集計指標だけでなく、実際の出力を確認してください。具体的に何が問題だったのでしょうか。失敗は系統的なものですか、それともランダムなものですか。

ステップ2：うまくいくバージョンを見つける

動作するベースラインが必要です。見つける方法は2つあります。

• タスクを単純化する：データの複雑さを下げ、タスクの設定を緩和し、より多くの教師信号を追加するか、より簡単な入力を使います
• 変更を取り除く：ベースラインの手法から始め、アルゴリズム上の改善を一つずつ取り除きます

うまくいくバージョンが見つからない場合は、何かが動作するまでさらに単純化してください。必ず動作する、十分に単純なバージョンがあります。

ステップ3：差を埋める

動作するバージョンから始め、失敗するまで複雑さを段階的に追加します。

• 一度に追加する要因は1つだけにします（より複雑なデータ、アルゴリズム上の変更1つ、制約1つ）
• 失敗の原因となる要因を1つ特定します
• 特定された原因がより原子的であるほど、診断は役立ちます

このステップで原因を切り分けます。これを行わなければ、推測に頼ることになります。

ステップ4：仮説を立てて検証する

ステップ3で切り分けた原因に基づき、次の手順で進めます。

1. この要因が失敗を引き起こす理由について、考えられる説明を列挙します
2. 可能性の高い順に並べます（自分の理解と文献に基づきます）
3. 各仮説を検証、または棄却するための的を絞った実験を設計します
4. 実験によって実際の原因を確認します。直感だけに頼らないでください

ステップ5：修正を提案して実装する

確認した原因に基づき、次のように進めます。

• この特定の原因に対処する手法を調べます（research-ideation スキルで作成した文献ツリーを使用します）
• 表面的な症状ではなく、確認した原因を対象とする修正を設計します
• 元の失敗事例で修正が機能することを検証します
• それまで動作していた事例が修正によって壊れないことを確認します

分岐の詳細なロジックと原因の分類については、references/debugging-methodology.md を参照してください。

直感に反する実験のルール

実験を行う際は、以下のルールを優先してください。

1. 一度に変更する変数は1つだけにする：2つのことを変更してうまくいった場合、どちらが問題を解決したのかわかりません。2つのことを変更してうまくいかなかった場合、どちらが間違っているのかわかりません。1変数ずつ変更する実験は1回あたりの時間がかかりますが、全体としてはより早く進められます。
2. 迅速な反復に必要なのは、実験の数ではなく効果的な実験です：やみくもな実験は事態を悪化させます。適切に設計された診断実験1回は、無作為な試行10回に匹敵します。
3. 優れた手法でも、単独では機能しないことがあります：学習率スケジュール、初期化方法、データの前処理など、特定の活性化の工夫が必要な場合があります。1回失敗しただけで、その手法を見限らないでください。関連論文を調べ、公開されていない工夫を確認してください。
4. 関連論文で工夫を確認する：同様の技術的課題を解決している論文には、補足資料やコードに重要な実装の詳細が隠れていることがよくあります。こうした工夫が、手法の成否を左右することがあります。
5. 「不可能なものを除外した後に残ったものは、何であれ真実である」：直感よりも体系的な除外が有効です。デバッグでは、考えられる原因をすべて明示的に列挙し、的を絞った実験で1つずつ除外してください。

実験の記録

すべての実験を、以下の5つのセクションに分けて記録してください。テンプレートはassets/experiment-log-template.mdを使用してください。

セクション	記録する内容
目的	この実験を行う理由と、何を明らかにする予定か
設定	データ、アルゴリズムの変更、ハイパーパラメーターなど、再現に必要なすべての情報
結果	定量的な指標＋定性的な観察＋具体的な成功例・失敗例
分析	結果は予想と一致しているか。一致しない場合は、原因の仮説を可能性の高い順に記載
次のステップ	分析に基づいて行うこと。プロジェクトリーダーはあなたです

「次のステップ」セクションが最も重要です。 次に何をすべきか、誰かに指示されるのを待たないでください。結果を分析し、次の実験を自分で提案してください。これが研究者と技術者の違いです。

サイクルをまたいだ学び：experiment-pipelineを使用している場合、実験ログはevo-memoryのESE（Experiment Strategy Evolution）メカニズムに取り込まれます。再利用可能な戦略には[Reusable]タグを付けて、ESEが今後のサイクルで活用できるようにしてください。

experiment-pipeline に戻る

5段階の診断フローを完了したら、以下を添えてexperiment-pipelineに戻ります。

• 確認された失敗の原因（ステップ4から）
• 提案する修正と、その検証状況（ステップ5から）
• 更新した実験ログの項目

論文執筆への引き継ぎ

実験が成功し、結果がすべて揃ったら、以下の成果物をpaper-writingに渡します。

成果物	出典	使用箇所
最終的な実験結果（表と図）	実験ログ	実験セクション
アブレーション研究の結果	診断実験	アブレーション表
失敗事例の分析	ステップ1＋ステップ3	限界についての考察
主要な実装の詳細と工夫	ステップ3～5	手法セクション／補足資料
ベースラインとの比較結果	ステップ2	比較表

参考資料の参照

トピック	参考ファイル	使用するタイミング
デバッグ手法	debugging-methodology.md	実験が失敗する理由を診断するとき
実験ログのテンプレート	experiment-log-template.md	実験の詳細を記録するとき