はじめに

Kaggle コンペに参加するたびに、「フォルダ構成は？ファイルが無秩序に溢れてきた」「実験メモはどのファイル？」と毎回迷っていたので、コンペ開始時の儀式 をスクリプトとテンプレートで固定しました。
解法やスコアの話は一切しません。最初に置くフォルダとドキュメントだけ を揃える話です (｡･ω･｡)

拡張機能52個でPCが重すぎた話 でローカル環境を整えたあと、次に整えたのが コンペ ROOT の中身 です。
Kaggle を始めた頃の話は ブラウザの Copilot 転記期の記事 にまとめています。

想定読者

• Kaggle を Cursor で回し始めた方
• コンペごとにフォルダ構成がバラバラで困っている方
• エージェントに任せる前に、置き場所の SSOT を決めたい方

私の属性

• エディターは Cursor がメイン
• Kaggle は、最近ローカル検証をするようになった
  • 以前は、Kaggle・Google Colab上で頑張っていた
• コンペごとに 専用フォルダ（comp ROOT） を1つ作り、そこだけで作業する

なぜ「儀式」を固定したか

コンペが始まると、だいたい次のようなことが起きます。

• Discussion を読みながらメモが散らばる
• 「あの実験、どの Notebook だっけ？」となる
• エージェントに任せるほど、都度フォルダやファイルがあちらこちらに作られる
  • 終盤になると、人間が目的物を探せない状態となる

最初から置き場所を作成して、指定する 必要があると感じました。
儀式＝コンペ開始直後に必ず同じツリーを作り、同じファイル名に書く、というルールです。

プロジェクト構成

親リポジトリに テンプレと scripts を置き、その下に コンペごとのフォルダ を1つ作る形です。
Cursor で開くのは {YYYYMMDD}-{comp-slug}/ 側だけ、と決めています。

<repo>/                              # テンプレ・scripts 共有
├─ AGENTS.md
├─ .gitignore                        # dataset / 秘匿除外（GitHub 公開想定）
├─ .vscode/                          # Kaggle-Light プロファイル等
├─ scripts/                          # new-kaggle-comp.ps1 等
└─ {YYYYMMDD}-{comp-slug}/           # ★ コンペ ROOT — ここだけ開く
    ├─ lifecycle-manifest.md         # 成果物の状態索引
    ├─ .cursor/
    │  ├─ skills/                    # Kaggle 用 Skills（グローバルに置かない）
    │  ├─ rules/                     # 学習前・実行・提出前のリマインド
    │  ├─ hooks.json · hooks/
    │  └─ agents/                    # サブエージェント
    ├─ dataset/                      # 公式データ（空で開始 · Git 除外）
    │  ├─ README.md
    │  ├─ derived/                   # 自前加工
    │  └─ （ローカル検証用ユーティリティ等）
    ├─ exp/                          # 実験 SSOT
    │  ├─ experiment-checklist.md    # 仮説1行＝実験1項目
    │  ├─ exp-intel.md               # Discussion 要点・他者示唆
    │  └─ work/                      # 日次 WIP（Git 除外可）
    ├─ my-notebook/                  # WIP（Cursor が編集）
    │  └─ planned/                   # 未実行キュー
    ├─ my-local-eval-notebook/       # 検証専用（提出しない）
    ├─ my-ran-notebook/              # 実行済み + run-log.md
    ├─ my-submitted-notebook/        # 提出凍結（編集禁止）
    ├─ docs-ja/
    │  ├─ folder-map.md              # 置き場所 SSOT
    │  ├─ comp-start-checklist.md
    │  ├─ comp-profile.md            # コンペ型・Skill マップ
    │  ├─ comp-strategy.md           # Goal / Bets / Stop
    │  ├─ comp-timeline.md
    │  ├─ others-notebook/           # 他者 NB 日本語要約
    │  ├─ kernels-runbook.md
    │  ├─ submission-rules.md
    │  ├─ pretrain-gates/
    │  └─ submission-validations/
    ├─ sim-track/                    # simulation 型のみ（任意）
    └─ docs-en/
       ├─ discussion/                # Discussion 原文
       └─ others-notebook/           # 他者 NB ipynb + 抽出 .py

Notebook の流れ: my-notebook/（編集中）→ my-ran-notebook/（実行済み）→ my-submitted-notebook/（提出済）。
外部情報: 原文は docs-en/、要点・要約は exp/exp-intel.md と docs-ja/others-notebook/ に分ける。

.cursor/ — Skills だけではない

ツリー内の .cursor/ に、Skills・rules・hooks・サブエージェントがまとまって入ります。
コンペごとに 新規フォルダを開き直す ので毎回コピーされ、Web 開発用フォルダには載せません（Skill 分離の記事 参照）。

エディタプロファイル — 毎回の開き方

コンペは 毎回新規フォルダ で始めるので、エディタ側も「このフォルダ＝Kaggle 用」と決め打ちします。

拡張機能52個でPCが重すぎた話 でプロファイル分離をしたのと同じ考え方で、フォルダを変えるたびにプロファイルも合わせる 運用です。
コンペごとに フォルダを1つ 作り、そのフォルダだけを Kaggle-Light で開き直します (｡･ω･｡)

dataset/ — 自動ダウンロードしない理由

dataset/ はスクリプト実行時に 空フォルダだけ 作ります。competitions download は 自動では走らせません。

理由はシンプルで、コンペによっては PC のストレージでは厳しい容量 があるからです。
数 GB〜数十 GB 級のデータも珍しくないので、

1. まず Kaggle 上でデータサイズを確認する
2. 手元に置くか、クラウド Notebook だけで回すかを 人間が決める
3. 置くと決めたら dataset/README.md の手順で手動 DL

という順にしています。Agent に勝手に DL させると、気づいたらディスクが埋まる、という事故を避けたい意図です（´・ω・`）

儀式のあとに埋めること

ツリーの 空ファイル・空フォルダ に、次だけ追記すれば動き始められます。

AGENTS.md — エージェントの入口

• コンペの URL・締切（概要だけ）
• やってよいこと / 禁止（例: 無断 submit 禁止）
• 詳細は docs-ja/folder-map.md を見る、と書く

解法は載せず、参照先の地図 に留めます。

experiment-checklist.md — ダミー仮説2行

Agent に「仮説1行＝実験1項目」の型を伝えるため、最初から2行だけ入れておきます。

• 例1: 「カテゴリAの前処理を短縮すると、ローカル verify が通る zip が作れる」
• 例2: 「検証用サブセットで CV と Public LB の順位相関を確認する」

checklist には 仮説だけ 載せ、他者 NB 名は exp/exp-intel.md 側に閉じます。

run-log.md — 実行のたびに1行

my-ran-notebook/ 配下に、いつ・目的・環境・完走可否・次の1手を残します。
完走＝提出 ではない、と最初から書いておくと LB を無駄撃ちしにくくなります。

構築手順（儀式の流れ）

1. コンペ ROOT を作る

コンペごとに 専用フォルダを1つ 作り、Cursor は そのフォルダだけ を Kaggle-Light プロファイルで開きます。
Web 開発用リポジトリと混ぜないのがポイントです（Skill 分離は Kaggle用Cursor Skillをコンペフォルダだけに閉じた話）。

2. テンプレートからツリーを生成する

手作業でもよいですが、私は 開始用スクリプト で上記ツリーを毎回コピーしています。

# 例: コンペ slug と URL・締切を渡して ROOT を生成
& .\scripts\new-kaggle-comp.ps1 `
  -Name "<comp-slug>" `
  -Url "https://www.kaggle.com/competitions/<slug>" `
  -Deadline "YYYY-MM-DD"

dataset/ だけは 空のまま 残します。スクリプトが無くても、ツリーを チェックリスト通りに手で作る のでも同じです。

3. AGENTS.md と checklist を埋める

1. AGENTS.md にコンペ概要を追記
2. docs-ja/comp-start-checklist.md を上から確認
3. exp/experiment-checklist.md にダミー仮説を2行
4. dataset/ は空のまま。データサイズを確認してから手動 DL を判断
5. Discussion / 他者 NB を読み始めたら、散らばさず docs-en/discussion/ か exp/exp-intel.md に追記

4. Cursor をリロードする

.cursor/（Skills・rules・hooks・agents）を初めて置いたときは、Developer → Reload Window してから実験に入ります。

動作確認

儀式が終わったら、次を満たせば OK です。

• コンペ ROOT を Kaggle-Light プロファイル で開いている
• .cursor/ に skills・rules・hooks・agents が入っている
• AGENTS.md から docs-ja/・exp/ への参照が書いてある
• docs-en/discussion/ と docs-en/others-notebook/ の置き場が空でも存在する
• experiment-checklist.md に仮説が 手段ではなく検証内容 で書いてある
• dataset/ は空。DL するかは容量確認後に人間が決める
• my-ran-notebook/ に run-log.md のテンプレがある

Agent に「今日やることを1項目だけ」と頼むと、checklist の pending から取りに行けるか試すと確認しやすいです ฅ(＾・ω・＾ฅ)

トラブルシュート

まとめ

• 親 <repo>/ に scripts を置き、コンペごとに {YYYYMMDD}-{comp-slug}/ を1つ 作って開く
• ツリーに .cursor/・docs-en/discussion/・docs-ja/others-notebook/・Notebook 4段階が揃う
• dataset/ は空で始め、容量を確認してから 手動 DL（自動 DL はしない）
• 儀式後は AGENTS.md・ダミー仮説2行・run-log.md を埋めれば動き始められる
• 毎回 Kaggle-Light プロファイル でコンペ ROOT を開く

ローカル verify は Kaggle提出前にローカル検証ループを回す話、API・GPU のコストは Kaggle×Cursor×Google Colabのコスト設計 を参照してください。

同じ轍を踏みたくない人の参考になれば幸いです (ﾉ´∀｀*)

読んで頂き、ありがとうございました (´▽｀)