agentic-data-science-competition

エージェント型データサイエンスコンペティション

「エージェントは提出するだけではありません。失敗から学び、戦略を適応させ、自律的に反復します。」

基本理念

このスキルでは、実際のコンペティション経験から得られた実践的なパターンをまとめています。

1. チームメイトとしてのエージェント — 単なるツールではなく、調査、デバッグ、反復を行える協力者です
2. 仕様駆動開発 — コーディングの前に文書化し、明確な制約を設けて作業を委任します
3. 早く失敗し、より早く学ぶ — 初期スコアはあてになりません。体系的なデバッグが成果につながります
4. 重要な部分を自動化 — 監視には Cron ジョブ、複雑な作業には委任を活用します

---

クイックリファレンス

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

トリガー	アクション
新しいコンペティションを開始する	→「プロジェクトのセットアップ」セクションを読む
提出時に 400 エラーが返される	→「トラブルシューティング」セクションを確認する
スコアが予想外に下がった	→「スコアの安定化」セクションを読む
上位ノートブックを再現する必要がある	→「再現ワークフロー」を使う
カーネルのプッシュに失敗する	→「カーネルのワークフロー」セクションを確認する
GPU が必要だが利用できない	→「委任戦略」を使う

主なコマンド

# Submit to competition
kaggle competitions submit <name> -f <file> -m "<message>"

# Check submission status
kaggle competitions submissions <name>

# Pull top notebook WITH metadata
kaggle kernels pull <owner>/<kernel> -p ./path/ -m

# Push kernel to Kaggle
kaggle kernels push -p ./path/

# Monitor kernel status
kaggle kernels status <username>/<kernel-name>

---

スコアの安定化パターン

重要な知見：Kaggle のスコアは、提出後に安定するまで時間がかかります。

|| 時間 | スコアの動き | 対応 || |------|----------------|------------|| | 開始時 | ベースライン | 評価を開始するため、早めに提出する || | +2 時間 | ピーク（過大評価） | 信用しないでください！ 人為的に高くなっていることがよくあります || | +4 時間 | 安定 | 真のスコア — この時点で判断します ||

教訓：序盤の高スコアに浮かれてはいけません。パフォーマンスを評価する前に 4 時間以上待ちましょう。

---

提出時のトラブルシューティング

400 Bad Request エラー

1. 提出形式を確認します（ヘッダーの有無、引用符の有無）
2. ID がテストセットと完全に一致していることを確認します
3. .zip 形式を試します — コンペティションによっては CSV を ZIP 圧縮する必要があります
4. コンペティションで回答の提出ではなく、モデルの提出が必要かどうか確認します

ZIP 提出形式（重要！）

よくある間違い：フォルダー内のすべてのファイルを ZIP 圧縮する（__notebook__.ipynb を含む）

正しい方法：

import zipfile
with zipfile.ZipFile('submission.zip', 'w', zipfile.ZIP_DEFLATED) as zf:
    zf.write('submission.csv', 'submission.csv')  # Only the CSV!

コンペティションの種類

種類	提出するもの	例
回答の提出	予測値を含む CSV	ほとんどのコンペティション
モデルの提出	学習済みモデルの重み（LoRA、チェックポイント）	一部の LLM コンペティション

見分け方：上位ノートブックを確認します。モデルを学習していますか、それとも予測値を生成しているだけですか？

---

カーネルのワークフロー

Run モードと Commit モード

モード	テストセット	用途
Run	非表示	開発、デバッグ
Commit（"Save & Run All"）	マウント済み	本番環境、最終提出

これが重要な理由：kaggle kernels push は Run モードで実行されます。テストセットはマウントされません。プレースホルダーには sample_submission.csv を使用してください。

データパスのパターン

/kaggle/input/competitions/<competition-name>/   ← Correct!
NOT /kaggle/input/<competition-name>/            ← Wrong!

カーネルメタデータのベストプラクティス

{
  "id": "username/kernel-name",
  "is_private": true,          // ← Always true by default!
  "enable_internet": false,    // ← Check competition rules
  "competition_sources": ["competition-name"],
  "dataset_sources": ["dataset-with-dependencies"]
}

---

上位ノートブックの再現

ワークフロー

# 1. Pull with metadata (-m flag is critical!)
kaggle kernels pull <owner>/<kernel> -p ./solution/ -m

# 2. Edit kernel-metadata.json
#    - Change "id" to your username/new-name
#    - KEEP all dataset_sources, model_sources, kernel_sources

# 3. Push
kaggle kernels push -p ./solution/

# 4. Monitor
kaggle kernels status <your-username>/<new-kernel-name>

重要なポイント

1. 必ず -m フラグを使う — 依存関係を含む kernel-metadata.json を取得します
2. すべての依存関係を保持する — dataset_sources、model_sources、kernel_sources
3. 変更するのは id と title だけ — それ以外はすべて元の内容と一致させます
4. enable_internet を確認する — 元の設定が false の場合は、false のままにします

委任するタイミング

次の場合は OpenCode/Claude Code に委任します。

• ソリューションを異なるコンテキストに適応させる
• 複数の手法を組み合わせる
• 既存のコードベースと統合する
• 複雑な変換やリファクタリングを行う

次の場合は 委任しません。

• ファイルを単純にダウンロードする
• メタデータのみを変更する
• 変更せずに直接フォークする

---

仕様駆動開発

プロセス

1. コーディングを始める前に、まず SPEC.md を作成します。

   • コンペティションの概要（タスク、データ、評価）
   • ノートブックで優れたアプローチ
   • 戦略と実装計画
   • 技術的な制約
   • 成功指標とスケジュール

2. 仕様書を添えて AI コーディングエージェントに委任します。

   • SPEC.md をコンテキストとして提供します
   • 制約（時間制限、GPU の利用可否）を指定します
   • 明確な成功基準を設定します

3. 結果に基づいて反復します

SPEC.md テンプレート

# SPEC.md - Competition Name

## 1. Competition Overview
- Task, deadline, prize, current top score

## 2. Task Definition
- Input/Output format, data summary

## 3. Top Approaches (from Kaggle Notebooks)
- Approach A: [votes/score], strategy
- Approach B: [votes/score], strategy

## 4. Strategy & Implementation Plan
- Phase 1: Quick baseline
- Phase 2: High-ROI improvements
- Phase 3: Fine-tuning

## 5. Technical Constraints
- Submission format, time limits, GPU requirements

## 6. Success Metrics
| Milestone | Target | Timeline |
|-----------|--------|----------|
| Baseline | 0.xx | Day 1 |
| Improved | 0.xx | Day 2 |

---

委任戦略

ローカルと Kaggle

タスク	場所	理由
データ分析	ローカル	高速に反復でき、GPU は不要です
プロンプトエンジニアリング	ローカル	素早くテストできます
モデルのトレーニング	Kaggle	無料の GPU
大規模な推論	Kaggle	GPU とインターネット

エージェントの使い分け

エージェント	最適な用途
OpenCode	コード開発、機能の実装
Claude Code	PR レビュー、複雑なデバッグ
サブエージェント（delegate_task）	並行調査、独立した作業ストリーム

---

よくある落とし穴

1. デバッグ時にトレーニングデータへフォールバックする

誤り：

test_files = sorted(TEST_DIR.glob("*.ogg"))
if not test_files:
    test_files = sorted((COMP_DIR / "train_soundscapes").glob("*.ogg"))[:10]

正しい例：

if not test_files:
    submission = pd.read_csv("sample_submission.csv")
    submission.iloc[:, 1:] = 0.0
    submission.to_csv("submission.csv", index=False)

2. ゲーム AI コンペティションでは包括的な機能が必要です

確認されたパターン：上位のゲームエージェントには、多くの場合、包括的な機能の実装が必要です。

教訓：ゲーム AI エージェントを単純化しすぎないでください。上位のソリューションを調査し、競争に必要な機能一式を把握しましょう。

3. ファイル拡張子の重複

ファイル名の列に拡張子がすでに含まれているか確認します：

# Check this:
print(train_df['filename'].head())

# If it shows "1161364/iNat1216197.ogg", don't add .ogg again!

4. 例外を黙ってキャッチする

悪い例（エラーが隠れます）：

try:
    audio, sr = load_audio(file)
except Exception:
    continue  # No idea why it failed!

より良い例：

try:
    audio, sr = load_audio(file)
except Exception as e:
    print(f"Failed on {file}: {type(e).__name__}: {e}")
    continue

---

API の使用パターン

レート制限への対応パターン

• 一部の AI API は、ピーク時間帯（例：北京時間の 10:00～17:00）に制限に達します
• 解決策：制限時間帯は、バックアップのモデルまたはプロバイダーに切り替えます
• 回復：制限は夕方に解除されます

この点を考慮して計画してください：AI コーディングエージェントに委任する前に、時刻を確認します。

---

検証チェックリスト

提出後：

• kaggle competitions submissions に提出内容が表示されていることを確認します
• ステータスを確認します：PENDING → RUNNING → COMPLETE
• 最終スコアを評価する前に 4 時間以上待ちます
• ベースラインおよび目標と比較します

---

高度なパターン

references/research/04-advanced-patterns.md を参照してください。内容は次のとおりです。

• ステートマシン実行ループ — 障害耐性のある自律エージェントパターン
• 設定駆動の cronjob 設計 — ジョブを再作成せずに実験を切り替え
• スーパーバイザーの検証業務 — 不正検出と来歴の検証
• AUC のランク平均化 — +0.001～0.005 の改善手法
• ONNX モデルの検証 — 禁止された演算とエラーのデバッグ
• 依存関係のベンダリング — オフラインでのパッケージインストール

references/research/05-environment-setup-patterns.md を参照してください。内容は次のとおりです。

• Kaggle Environments のソースからのインストール — PyPI が古い場合に GitHub から最新の環境をインストール

references/research/06-competition-types-submission-workflow.md を参照してください。内容は次のとおりです。

• コンペティション種別の分類 — Prediction／Adapter／ONNX、Pure Code／Mixed／Standard
• -k -v フラグの要件 — ノートブックとの関連付けにより、孤立した提出を防止

---

関連スキル

スキル	目的
agentic-competition-workflow	Git を中心としたプロジェクト管理、検証パイプライン、コンペティションの全ライフサイクル
kaggle-auto-submit	cronjob の監視を含むエンドツーエンドの自動化
autonomous-iteration	ANALYSIS → BUILD → EXPERIMENT → REVIEW のループ
opencode	OpenCode CLI にコーディングを委任
claude-code	Claude Code CLI にコーディングを委任