毎セッション読まれるCLAUDE.mdをどう書くか ── Claudeの「推論の深さ」まで設計する

はじめに

CLAUDE.md は、Claude Code が毎セッションの先頭で読み込むプロジェクト指示書だ。ここに書いたことは、そのプロジェクトで作業するときの前提として毎回効く。

強力なぶん、扱いを間違えると逆効果になる。あれもこれもと書き足していくと、すぐに長大な文書になり、肝心なところが埋もれる。毎回読まれる = 毎回コンテキストを消費するので、長さそのものがコストでもある。

前回はドキュメント全体（spec / ADR）の話を書いた。今回はその入口である CLAUDE.md そのものを、慶弔記録アプリ tsutsum の実物をもとに、どう書いているかを紹介する。

---

大原則：冒頭で「簡潔に保て」と宣言する

tsutsumの CLAUDE.md は、こんな一文から始まる。

> このファイルは毎セッション読み込まれる。
> 簡潔に保つこと。詳細は docs/ を参照。

これはClaudeへの指示であると同時に、書く自分自身への戒めでもある。CLAUDE.md は「全部書く場所」ではなく「入口」だと最初に決めておく。詳細な仕様や手順は docs/ に置き、CLAUDE.md からはリンクで逃がす。

こうすると、CLAUDE.md は薄いまま保てるし、詳細は必要になったときだけClaudeが辿ればいい。

---

何を書くか / 何を書かないか

tsutsumの CLAUDE.md に載せているのは、だいたい次のものだ。

• プロダクトの芯（一言で何のアプリか・ターゲット・UXトーン）
• 技術スタックの制約（何を使い、何を使わないか）
• ディレクトリと依存の方向（どこに何を置くか）
• 主要コマンド（実行・解析・テスト・ビルド）
• 進め方とコミット規約（詳細は docs/ へリンク）

逆に、画面ごとの詳細仕様は載せない。それは docs/specs/ の仕事だ。CLAUDE.md には「specを起点に実装する」という進め方だけ書き、個別仕様はリンクにする。

判断基準はシンプルで、「毎回のセッションで前提として効いてほしいか」だ。効いてほしいものだけをCLAUDE.mdに、参照できればいいものは docs/ に置く。

---

ガードレール：AIの「手癖」を止める

CLAUDE.md がとくに効くのが、AIがやりがちなことを先回りで止める用途だ。

Claudeは気を利かせて、便利なパッケージやコード生成をすぐ導入したがる。放っておくと、依存が増え、ビルドが重くなり、プロジェクトの方針からズレていく。tsutsumは「lean（コード生成なし）」を方針にしているので、CLAUDE.md にこう書いている。

- 状態管理は Riverpod。コード生成は使わない — provider は手書き。
- 安易に freezed や *_generator を追加しない。
  必要なら先に Flutter を更新し、ADR を起票してから。

ポイントは、単に「禁止」と書くのではなく、やりたくなったときの正しい手順（まずADRを起票）まで示していることだ。こうすると、Claudeは勝手に足すこともしないし、必要なときの動き方も分かる。

「AIにやってほしくないこと」と「その代わりにどうするか」をセットで書く。これがガードレールの基本形だ。

---

進め方をルールにする

CLAUDE.md には、作業の型も短く書いておく。tsutsumの場合はこうだ。

• spec-driven: docs/specs/ を書く → 実装＋テスト → flutter analyze / flutter test を通す → アーキ判断は docs/adr/ に1枚。
• コミットは完全にFIX・OKのときだけ。作業途中で勝手にコミットしない。

とくに後者は、自律的に動くエージェントに対する重要な歯止めになる。「いつコミットしていいか」を明示しておかないと、AIは中途半端な状態で気軽にコミットしてしまうことがある。逆に、ここを一行決めておくだけで、コミットの粒度が安定する。

---

目玉：推論の「深さ」まで設計する

tsutsumの CLAUDE.md には、他ではあまり見ない節がある。アダプティブ推論スタイルの表だ。タスクの複雑さに応じて、Claudeにどれくらい考えてから動いてほしいかを指定している。

状況	対応
アーキテクチャ判断・設計変更・ADR起票	回答前に仮説・根拠・トレードオフを整理してから提案
バグの根本原因調査	再現条件・仮説・影響範囲を順に検討してから結論
仕様が曖昧・「なぜ」が不明なタスク	実装前に一度確認する
コード編集・名前変更・typo修正・定型作業	即実行（過剰な説明不要）

狙いは、過剰さと不足の両方を抑えることだ。

• 簡単な作業に長い前置きは要らない。typo修正でトレードオフを語られても邪魔なだけだ。
• 逆に、設計変更を勢いで即実装されると困る。ここは考えてから出してほしい。

さらに、こう補足している。「複雑な問題ほど実装より先に考えを示す。ただし長文の内部独白は書かない ── 結論と根拠を簡潔に」。考える深さは調整しつつ、出力は簡潔に、という指定だ。

AIの「振る舞い」だけでなく「思考の深さ」までCLAUDE.mdで方向づけられる、というのは覚えておくと効く。

---

運用のコツ

書いて終わりではなく、CLAUDE.md は育てて剪定するものだ。

• リンクで逃がす。 詳細は docs/ に置き、CLAUDE.md は薄く保つ。
• 定期的に削る。 一度書いたルールも、不要になったら消す。長さはコストだと意識する。
• 役割を分ける。 CLAUDE.md は毎回効く「憲法」、docs/specs は「今の仕様」、docs/adr は「なぜ」。同じことを二重に書かない。

CLAUDE.md が薄いほど、書いてある一行一行がよく効く。厚くなってきたら、それは docs/ に逃がすべき何かが混ざっているサインだ。

---

まとめ

CLAUDE.md は「プロジェクトの説明書」であると同時に、Claudeの振る舞いと思考の深さを方向づける設定ファイルでもある。

• 冒頭で「簡潔に」と宣言し、詳細は docs/ へ逃がす
• 毎回効いてほしいことだけを載せる
• やってほしくないことは、代わりの手順とセットで書く（ガードレール）
• 推論の深さを、タスクの種類ごとに指定する

tsutsumの CLAUDE.md は、これで100行に満たない。短いからこそ毎回きちんと効く。Claude Code を使い始めた人が最初に整えるべき一枚として、参考になれば。

---

このシリーズ：第1回 spec と ADR／第2回（本記事）／第3回 既存アプリをAIで別スタックへ移植する