【保存版】`.claude/` を設計する──CLAUDE.mdに全部書くのをやめる日｜置き場所の決定表と、実物241行の棚卸し

https://note.com/yasuda_forceai/membership

CLAUDE.md は書けた。でも `.claude/` の中は空のまま。 ──これ、かなり多いと思います。

私もそうでした。手元のプロジェクトの `.claude/` を開いたら、 入っていたのは行き当たりばったりのPythonスクリプト9本と `settings.local.json` だけ 。

一方で CLAUDE.md は241行 まで育っていました。ビルド手順も、失敗の作法も、既知の制約も、全部そこに書いてありました。

🎯 公式が引いている線は、実はかなり明確です

Claude Code の公式ドキュメントに、こう書いてあります。

ここに 判断基準がそのまま書かれています 。

• 📌 事実・制約・前提 → CLAUDE.md （毎回読ませる価値がある）

• 📌 手順・チェックリスト・定型作業 → skill （使うときだけ読ませる）

CLAUDE.mdは常にコンテキストに乗ります。 つまり 書けば書くほど、毎ターン払い続けるコストが増える 。

手順書をそこに置くのは、 「めったに使わない道具を、常に手に持って歩く」 のと同じことでした。

1. 置き場所の決定表──5つの箱

結論：`.claude/` の設計とは、「この知識はどの箱に入るか」を決めることです。

箱は5つあります。 役割が重ならないので、迷ったらこの表に戻れば決まります 。

• 📄 CLAUDE.md ── 事実 。毎回知っていてほしいこと（構成・制約・禁止事項）

• 🧰 skills/ ── 手順 。使うときだけ読ませたい作業マニュアル

• 👤 agents/ ── 委任 。別コンテキストで走らせたい調査・レビュー

• 🪝 hooks ── 強制 。指示ではなく、機械的に止めたい境界

• ⚙️ settings.json ── 環境 。権限・モデル・ツールの設定

判断に迷ったときの一文がこれです。

🔁 commandsはskillに統合されました

ここは知らないと損をします。

`.claude/commands/deploy.md` と `.claude/skills/deploy/SKILL.md` は、どちらも `/deploy` を作ります。 既存の `commands/` はそのまま動きます。

ただし skillのほうができることが多い です。

• 📁 補助ファイルを同じフォルダに置ける

• 🎚️ 誰が呼ぶか（人間だけ／Claudeも）をfrontmatterで制御できる

• 🤖 関連する場面でClaudeが自動で読み込める

同名なら skill が優先されます。 これから作るなら skill 側に寄せておくのが素直です。

2〜6の内容（有料パート）

ここまでで 「何をどこに置くか」の原則 はお渡ししました。これだけでもCLAUDE.mdの肥大化は止まります。

ただ、実際に手を動かすと すぐに細部で詰まります 。

• 🤔 skillは どの階層から読まれる？ 個人とプロジェクト、どちらが勝つ？

• 🤔 サブフォルダのskillが補完に出てこない のはなぜ？

• 🤔 subagentに skillを先読みさせる にはどう書く？

• 🤔 同じ名前のsubagentが2つある とき、どちらが動く？

• 🤔 そして 自分のCLAUDE.mdの、どの行を出せばいいのか？

この先は——

• 🗂️ 置き場所の完全な優先順位表 （skill・subagentそれぞれ。enterprise/personal/projectの勝ち負けまで）

• ⏱️ 遅延読み込みの正確な挙動 。 いつ読まれ、いつコンテキストに残り続けるのか

• 🧾 frontmatter全フィールドの実務的な意味 （`paths` / `context: fork` / `allowed-tools` / `skills` / `memory` / `isolation`）

• 🔬 【核心】実物のCLAUDE.md 241行を、5つの箱へ棚卸しする実演 。どの行が残り、どの行がskillへ出るか

• 📋 コピペできるSKILL.md・subagent・settings一式

• 🕳️ よくある失敗8つ と、 「本当に読まれているか」を確かめる手順

を、 全部コピペできる形 でお渡しします。