はじめに
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 用」と決め打ちします。
| 項目 | 内容 |
|---|---|
| プロファイル名 |
Kaggle-Light（PC ごとに1回 Import） |
| 開き方 | コンペ ROOT を Kaggle 用プロファイル で開く（専用スクリプト推奨） |
| 中身 | Python / Jupyter 中心。Web 系拡張は入れない |
拡張機能52個でPCが重すぎた話 でプロファイル分離をしたのと同じ考え方で、フォルダを変えるたびにプロファイルも合わせる 運用です。
コンペごとに フォルダを1つ 作り、そのフォルダだけを Kaggle-Light で開き直します (｡･ω･｡)
dataset/ — 自動ダウンロードしない理由
dataset/ はスクリプト実行時に 空フォルダだけ 作ります。competitions download は 自動では走らせません。
理由はシンプルで、コンペによっては PC のストレージでは厳しい容量 があるからです。
数 GB〜数十 GB 級のデータも珍しくないので、
- まず Kaggle 上でデータサイズを確認する
- 手元に置くか、クラウド Notebook だけで回すかを 人間が決める
- 置くと決めたら
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 を埋める
-
AGENTS.mdにコンペ概要を追記 -
docs-ja/comp-start-checklist.mdを上から確認 -
exp/experiment-checklist.mdにダミー仮説を2行 -
dataset/は空のまま。データサイズを確認してから手動 DL を判断 - 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 から取りに行けるか試すと確認しやすいです ฅ(＾・ω・＾ฅ)
トラブルシュート
| 症状 | 対処 |
|---|---|
| メモがまた散らばる | Discussion は docs-en/discussion/、要点は exp/exp-intel.md に集約 |
| 他者 NB の分析が混ざる | 原版は docs-en/others-notebook/、要約は docs-ja/others-notebook/
|
| Agent が別コンペの話をする | グローバル Skill に Kaggle 用が残っていないか確認（Skill 分離の記事 参照） |
| ディスクが急に埋まる |
dataset/ 自動 DL 禁止を守り、容量確認後に手動 DL |
| 儀式が重い | 最初は AGENTS.md + experiment-checklist.md + run-log.md の3つだけでも可 |
まとめ
- 親
<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のコスト設計 を参照してください。
同じ轍を踏みたくない人の参考になれば幸いです (ﾉ´∀｀*)
読んで頂き、ありがとうございました (´▽｀)