kaggle-new-experiment - SKILL.md Agent Skill

name: kaggle:new-experiment description: 対話的に新しい実験を設計・作成する。大実験/小実験の判断、仮説の批判的レビュー、ディレクトリ/config 作成まで。 disable-model-invocation: true allowed-tools: Bash, Read, Write, Glob, Edit

新しい実験を設計・作成する

このスキルはユーザーと対話しながら新しい実験を設計し、大実験（exp）または小実験（run）を作成する。一方的に作業を進めず、各ステップでユーザーに確認・議論すること。

実験の階層構造

大実験（exp）: アプローチ・アーキテクチャ・データパイプライン・バリデーション戦略が根本的に異なる実験。src/exp{NNN}_{subtitle}/ ディレクトリを新規作成する。
小実験（run）: 既存大実験の範囲内でモデル名・ハイパーパラメータ・前処理の細かな変更を行う実験。config/run{NNN}-{subtitle}.yaml を追加する。

フェーズ 1: コンテキスト収集

既存の実験状況を把握する
- src/exp*/ を Glob で検索し、既存の実験一覧を確認
- 各大実験の config/run*.yaml を確認し、小実験の状況も把握する
- EXP_SUMMARY.md の Experiments テーブルを Read で確認し、各実験の Key Change・CV・LB を把握
- docs/insights/ の知見ファイルを確認（実装上の知見のみ参考にする）
- docs/official/ を Read してコンペの概要・評価指標・データを把握
ユーザーにヒアリングする（必ず質問して回答を待つ）
- 「何を試したいですか？どんな仮説がありますか？」
- 「この実験で比較する変数（独立変数）は何ですか？」
- 必要に応じてドメイン知識やデータの特徴について追加質問する

フェーズ 2: 批判的レビュー（最重要）

2-1. 多様性チェック（バイアス防止）

まず、EXP_SUMMARY.md の Experiments テーブルを Read し、これまでに試したモデルファミリー/アプローチを一覧化する。

これまで試したアプローチ:
- {モデルファミリー1}: exp{XXX} (CV: x.xxx)
- {モデルファミリー2}: exp{YYY} (CV: x.xxx)
- ...

提案された実験が既存のモデルファミリーと同じ場合は、以下を明示してユーザーに確認する:

⚠ 多様性チェック: この実験は「{モデルファミリー名}」ファミリーに属しており、
exp{XXX} ですでに探索済みです。同じファミリー内での改良で問題ありませんか？
（未探索のアプローチ例: {未探索カテゴリ1}, {未探索カテゴリ2}）

ユーザーが同じファミリーでの改良を意図的に選んでいる場合は、そのまま進めてよい。重要なのは「無意識の偏り」を防ぐことであり、意図的な深掘りを妨げることではない。

2-2. メリット・デメリット分析

ユーザーの提案に対して、中立的な立場から以下を整理して提示する:

メリット: このアプローチが有効と考えられる根拠
デメリット・リスク: 想定される問題点、うまくいかない可能性
期待される結果: 成功した場合のスコア改善の見込み（定性的でよい）
変数の確認: 一度に変更する要素が多すぎないか？多い場合は分割を提案する

重要: CLAUDE.md の「探索の独立性」に従い、過去の実験結果に引きずられて探索空間を狭めない。ユーザーの仮説をゼロベースで評価する。

2-3. デュアル戦略の提示（必須）

メリット・デメリット分析の後、ユーザーの提案を踏まえて 2つの実験オプション を提示する。これは、安定志向と挑戦志向の両方を検討させることで、探索の幅を担保するためのメカニズムである。

=== デュアル戦略 ===

【安定型】（着実な改善: +0.5% 程度を見込む）
- 実験名案: exp{NNN}-{subtitle}
- 手法: {既知の有効な手法をベースにした堅実なアプローチ}
- 根拠: {なぜスコア改善が期待できるか}
- リスク: 低（ただし改善幅も限定的）

【爆発型】（高リスク・高リターン: うまくいけば大幅改善）
- 実験名案: exp{NNN}-{subtitle}
- 手法: {従来とは異なる斬新なアプローチ}
- 根拠: {なぜ大幅改善の可能性があるか}
- リスク: 高（うまくいかない可能性も相応にある）

どちらの方向で進めますか？（あるいは両方の要素を組み合わせることも可能です）

ユーザーが既に明確な方針を持っている場合でも、デュアル戦略は提示する。ユーザーの提案がどちらかに近い場合は、もう一方の対案を考えて提示する。

レビュー結果を提示し、ユーザーが納得するまで議論する。ユーザーが方針を変更したい場合は柔軟に対応する。

フェーズ 3: 大実験 vs 小実験の判断

議論の内容を踏まえ、大実験にするか小実験にするかを判断・提案する:

大実験にすべきケース

新しいモデルアーキテクチャやフレームワークを導入する
データパイプラインや前処理が大幅に異なる
バリデーション戦略（分割方法・fold 数）を変更する
既存のどの大実験にも属さない独立したアプローチ
train.py や model.py 等のコード変更が必要

小実験にすべきケース

既存大実験のモデル名やサイズを変更するだけ
ハイパーパラメータ（lr, batch_size, epochs 等）のチューニング
前処理のパラメータ変更（augmentation の強度等）
config の差分のみで表現できる変更

判断結果をユーザーに提示し、確認する。

大実験の場合の詳細決定

実験番号: 既存の最大番号 + 1（3桁ゼロ埋め）
サブタイトル: 実験内容を端的に表す英語名（ユーザーと相談）
Key Change: Experiments テーブルに記載する、前実験からの主な変更点
Split 方法: 検証データの分割方法（例: 5-Fold SKF）

小実験の場合の詳細決定

対象の大実験: どの大実験に小実験を追加するか
Run 番号: 対象大実験の既存 run の最大番号 + 1（3桁ゼロ埋め）
サブタイトル: 変更内容を端的に表す英語名
変更する config パラメータ: ベース config との差分

確定内容をユーザーに提示し、承認を得る。

フェーズ 4: 作成

大実験の場合

ベース実験の決定
- フェーズ 1〜3 の議論内容から、最も適切なベース実験を判断する
- 既存実験の発展であればその実験のディレクトリをコピー元にする
- 完全新規であれば src/exp000_sample/ をコピー元にする
ディレクトリ作成（src/exp{番号:03d}_{subtitle}/）
- コピー元から必要なファイルをコピー
- ファイル構成はコピー元に縛られない: 実験内容に応じてファイルを追加・分割してよい
config.yaml を更新
- exp_name を新しい実験名に変更
- run_name: run000-base を確認（デフォルト値）
- debug モードの設定を確認
- 他のパラメータはコピー元のフォーマットを維持し、一貫性を保つ
config コピー後チェックリスト（必ず確認）:
- config.yaml の exp_name が新しい実験名（例: exp002_xxx）に更新されているか
- output_dir のパスが新しい実験ディレクトリを参照しているか（${exp_name} 変数経由なら自動で正しくなる）
- logs_dir のパスが新しい実験ディレクトリを参照しているか（同上）
- wandb.project がデフォルト値（kaggle-competition）でないか（/kaggle:init 済みなら OK）

実験 README.md を作成（目的・仮説はフェーズ 2 の議論を反映）

# exp{番号}_{subtitle}

## 目的

（フェーズ 2 で合意した内容）

## 仮説

（ユーザーの仮説を具体的に記述）

## 手法

- データ: （使用データ）
- モデル: （モデル構成）
- 学習: （学習設定の要点）
- 比較変数: （この実験で変更する要素）

## 結果

| Metric | Value |
|--------|-------|
| Split  | {split方法} |
| CV     | -     |
| LB     | -     |

## Runs

| Run | Key Change | CV | LB |
|-----|-----------|----|----|
| run000-base | ベースライン | - | - |

## 考察

（実験完了後に記載する）

EXP_SUMMARY.md を更新
- Experiments テーブルに新しい行を追加
- Experiment Tree に wip クラスで新ノードを追加（ベース実験からエッジを張る）

小実験の場合

config ファイルを作成（src/{exp_name}/config/run{NNN}-{subtitle}.yaml）

defaults:
  - config    # ベース config.yaml を継承

run_name: run{NNN}-{subtitle}

# 変更するパラメータのみ記述
model:
  name: xxx

実験 README.md の Runs テーブルに行を追加
```
| run{NNN}-{subtitle} | {変更内容} | - | - |
```
EXP_SUMMARY.md は更新不要

フェーズ 5: 完了報告

作成したファイルの一覧を表示
実験の概要（目的・仮説・比較変数）を簡潔にまとめる
実行コマンドを提示する:
- 大実験: uv run python -m src.{exp_name}.train run_mode=debug
- 小実験: uv run python -m src.{exp_name}.train --config-name={run_name} run_mode=debug
次のステップを案内（コード実装 → debug で確認 → fold0 で性能確認 → full で本番）