
CLAUDE.mdに何を書くべきか|#2 設計論
この記事を読むとどんな悩みが解決するか
Claude Codeに指示を出しても毎回違う結果が返ってくる
CLAUDE.mdを書いてみたが、書いた気がするだけで効果を感じられない
同じミスを何度も繰り返させてしまう
チームで使っているが、人によって結果がバラバラ
この記事を読むと「何をどう書けばClaude Codeが意図通りに動くか」が具体的にわかる。
CLAUDE.mdはClaude Codeの「オリエンテーション資料」だ。
新入社員を雇ったとき、会社のルール・使うツール・やってはいけないことを最初に伝えるように、Claude Codeにもプロジェクトの文脈を与える必要がある。それがCLAUDE.mdの役割だ。
これを適切に設計できるかどうかで、Claude Codeの出力品質が大きく変わる。

WHATルール:何を書くべきか
CLAUDE.mdに書くべき内容は「Claude Codeが作業するために必要な情報」に絞る。
書くべき4つのカテゴリ:
1. 技術スタック
使っている言語・フレームワーク・ライブラリを明示する。
markdown
## 技術スタック
- フロントエンド:Next.js 14(App Router)
- バックエンド:Supabase
- スタイリング:Tailwind CSS
- 言語:TypeScript(strict mode)package.jsonを見れば自明な情報は書かなくていい。Claude Codeはファイルを読める。わざわざCLAUDE.mdに書いても冗長なだけだ。
2. アーキテクチャの方針
ディレクトリ構成の意図や、設計上の決定事項を書く。
markdown
## アーキテクチャ
- Server Componentsをデフォルトとする。Client Componentsは最小限に
- APIルートは /app/api/ 配下に集約
- DBアクセスはすべて /lib/supabase/ を経由すること3. ビルド・テストコマンド
markdown
## コマンド
- 開発:`npm run dev`
- ビルド確認:`npm run build`
- テスト:`npm run test`
- 型チェック:`npm run typecheck`4. 禁止事項・制約
Claude Codeが間違えやすいパターンを具体的に書く。
markdown
## 禁止事項
- `any` 型の使用禁止
- console.logをコミットに含めない
- 直接DBに書くな。必ずRLSポリシーを通すことポイント:具体的に書くほど遵守率が上がる。
具体的なルール → 遵守率 89%
曖昧なルール → 遵守率 35%
「コードをきれいに書いてください」ではなく「any型を使うな」と書く。これだけで遵守率が2倍以上変わる。
この章の相互作用と実践アクション
4つのカテゴリは独立しているようで連動している。技術スタックがあるからアーキテクチャの判断ができる。アーキテクチャがあるから禁止事項が意味を持つ。コマンドがあるから検証まで自動でできる。
今すぐできること:
自分のプロジェクトのCLAUDE.mdを開く
「コードをきれいに」のような曖昧なルールを探す
「any型の使用禁止」のように具体的な禁止事項に書き直す
カスケード構造:4層のファイル設計
CLAUDE.mdは1ファイルだけではない。4層構造で管理するのが正しい設計だ。
~/.claude/CLAUDE.md # グローバル設定
./CLAUDE.md # プロジェクトルート
./CLAUDE.local.md # 個人設定(.gitignore推奨)
./.claude/rules/*.md # ディレクトリ別ルール層ごとの役割
① ~/.claude/CLAUDE.md(グローバル)
自分のすべてのプロジェクトに適用したい設定を書く。50行以内が目安。
markdown
## 共通ルール
- コミットメッセージは日本語で書く
- 作業前に必ずgit statusを確認する
- 大きな変更の前にPlan Modeで計画を立てる② ./CLAUDE.md(プロジェクトルート)
プロジェクト固有のルール。チームで共有するのでGitで管理する。300行以内が目安。
③ ./CLAUDE.local.md(個人設定)
自分だけの設定。APIキーのパス・ローカル環境の差異など。.gitignoreに追加してリポジトリに含めない。
④ ./.claude/rules/*.md(ディレクトリ別)
特定のディレクトリにのみ適用したいルールを分割管理する。必要なときだけ読み込まれる。
.claude/rules/
├── frontend.md # /app 配下のルール
├── api.md # /app/api 配下のルール
└── database.md # /lib/supabase 配下のルール4層がどのように相互作用するか
4層はフィルターのように重なる。Claude Codeがコードを書くとき、まずグローバルルールを読み、次にプロジェクトルール、さらに個人設定、最後に作業中のディレクトリのルールを重ねて適用する。
つまり上の層ほど広く薄く、下の層ほど狭く深いルールを書く設計になる。
グローバル:「コミットメッセージは日本語」など全プロジェクト共通の習慣
プロジェクト:「DBアクセスは必ず/lib/supabase/を経由」などアーキテクチャ判断
個人:「ローカルのAPIキーは.env.localにある」など環境差異
ディレクトリ別:「このAPIルートはJWT認証必須」などファイル単位の制約
この構造があることで「なぜこのルールがあるのか」の文脈が自然に整理される。
この章の実践アクション
まず2層から始める。いきなり4層作る必要はない。
ステップ1:グローバル設定を作る
Claude Codeにこう伝える:
~/.claude/CLAUDE.md を作成して。
内容は以下の共通ルールだけ書いてほしい。
- コミットメッセージは日本語で書く
- 作業前に必ずgit statusを確認する
- 大きな変更の前にPlan Modeで計画を立てる全プロジェクト共通の習慣を3〜5個だけ書く。
ステップ2:プロジェクト設定を作る
Claude Codeにこう伝える:
このプロジェクトのルートにCLAUDE.mdを作成して。
技術スタック・アーキテクチャ方針・禁止事項を書いてほしい。
内容は私が確認してから使うので、まず下書きを出して。出てきた下書きを確認・修正してから保存する。
ディレクトリ別ルールはプロジェクトが大きくなってから必要に応じて追加する。
適切な長さ
全体で2,000トークン以内が推奨値だ。
500行のTypeScriptファイルが約4,000トークンなので、CLAUDE.mdはその半分以下に収める感覚。
長くなりすぎるとどうなるか。コンテキストを圧迫するだけでなく、ルールが埋もれて読まれなくなる(第6回のコンテキスト管理を参照)。
長さとルールの優先度の関係
「2,000トークン以内」という制約は単なる目安ではなく、重要なルールを際立たせるための設計原則だ。
100個のルールが書いてあるCLAUDE.mdでは、Claude Codeが「何が最も重要か」を判断できない。20個に絞られたCLAUDE.mdでは、すべてのルールが等しく重要なものとして扱われる。
つまり削ることがルールの優先度を上げる。
この章の実践アクション
今すぐできること:
現在のCLAUDE.mdのトークン数を確認する(文字数 ÷ 4 ≈ トークン数)
2,000トークンを超えていたら削除候補を探す
「package.jsonを見れば分かること」「READMEに書いてあること」は削除する
運用方法:間違えたら追記する
CLAUDE.mdは最初から完璧に書く必要はない。
正しい運用サイクル:
最小限のCLAUDE.mdで開発を始める
Claude Codeが同じ間違いを繰り返したら
その禁止事項をCLAUDE.mdに追記する
運用サイクルが品質を自動改善する仕組み
このサイクルの核心は「間違いが発生するたびにCLAUDE.mdが賢くなる」点だ。
最初は空に近いCLAUDE.mdでも、開発を続けるうちに「このプロジェクトで間違えやすいこと」が蓄積されていく。1ヶ月後には、そのプロジェクト専用の知識が詰まったCLAUDE.mdができあがっている。
WHATルールで書いた「具体的な禁止事項」が、この運用サイクルで積み上がっていく。カスケード構造があるから、プロジェクト固有の知識とグローバルな習慣が混在しない。適切な長さの制約があるから、本当に重要なルールだけが残る。
4つの章はすべてつながっている。
この章の実践アクション
今日から始められること:
開発セッションが終わったら「今日Claude Codeが間違えたこと」を1つ振り返る
同じ間違いが2回以上あったらCLAUDE.mdに追記する
週1回、CLAUDE.mdを見直して不要になったルールを削除する
まとめ
項目内容書くべきこと技術スタック・アーキテクチャ・コマンド・禁止事項書かなくていいことpackage.jsonで自明な情報具体的ルールの遵守率89%(曖昧なルールは35%)推奨トークン数2,000トークン以内グローバル設定50行以内プロジェクト設定300行以内運用の原則間違えるたびに追記・育てていくドキュメント
実践:CLAUDE.mdチェッカーを使ってみる
記事で学んだ内容を実際に手を動かして確認しよう。
以下の手順でCLAUDE.mdの品質をその場でチェックできる。
Claude chatに以下をそのまま貼り付ける:
あなたはCLAUDE.mdのレビュアーです。
私のCLAUDE.mdを以下の観点でチェックしてください。
【チェック項目】
1. 曖昧なルールがないか(「きれいに」「適切に」などの抽象表現)
→ あれば具体的な禁止事項に書き直す案を提示する
2. package.jsonで自明な情報が含まれていないか
→ あれば削除候補として指摘する
3. トークン数の概算(文字数 ÷ 4)が2,000を超えていないか
→ 超えていれば削除候補を提案する
4. 4層のカスケード構造で分けるべき内容がないか
→ あれば振り分け案を提示する
【私のCLAUDE.md】
(ここに自分のCLAUDE.mdの内容を貼り付ける)このチェックを月1回やるだけで、CLAUDE.mdの品質が継続的に上がっていく。
CLAUDE.md設計論を実施した際のフォルダ構成
最小構成(まず2層から始める)
~/ # ホームディレクトリ
└── .claude/
└── CLAUDE.md # ① グローバル設定(50行以内)
# 全プロジェクト共通の習慣を書く
your-project/ # プロジェクトルート
└── CLAUDE.md # ② プロジェクト設定(300行以内)
# 技術スタック・アーキテクチャ・禁止事項
成長後の構成(大規模プロジェクト)
~/ # ホームディレクトリ
└── .claude/
└── CLAUDE.md # ① グローバル設定(50行以内)
# - コミットメッセージは日本語
# - 作業前にgit statusを確認
# - 大きな変更はPlan Modeで
your-project/ # プロジェクトルート
├── CLAUDE.md # ② プロジェクト設定(300行以内)
│ # - 技術スタック
│ # - アーキテクチャ方針
│ # - ビルド・テストコマンド
│ # - 禁止事項
│
├── CLAUDE.local.md # ③ 個人設定(.gitignoreに追加)
│ # - ローカルのAPIキーのパス
│ # - 自分の環境固有の設定
│
├── .gitignore
│ └── CLAUDE.local.md を追加 # チームに共有しない
│
└── .claude/
└── rules/ # ④ ディレクトリ別ルール
├── frontend.md # /app 配下のルール
│ # - Server Componentsをデフォルト
│ # - Client Componentsは最小限に
├── api.md # /app/api 配下のルール
│ # - JWT認証必須
│ # - エラーレスポンスの形式
└── database.md # /lib/supabase 配下のルール
# - RLSポリシーを必ず通す
# - 直接DBに書かない
各ファイルの中身のイメージ
① ~/.claude/CLAUDE.md(グローバル)
## 共通ルール
- コミットメッセージは日本語で書く
- 作業前に必ずgit statusを確認する
- 3ファイル以上触るタスクはPlan Modeで計画を立てる
- テストなしの実装禁止
② ./CLAUDE.md(プロジェクト)
## 技術スタック
- フロントエンド:Next.js 14(App Router)
- バックエンド:Supabase
- 言語:TypeScript(strict mode)
## アーキテクチャ
- Server Componentsをデフォルトとする
- APIルートは /app/api/ 配下に集約
- DBアクセスはすべて /lib/supabase/ を経由すること
## コマンド
- 開発:npm run dev
- ビルド確認:npm run build
- 型チェック:npm run typecheck
## 禁止事項
- any型の使用禁止
- console.logをコミットに含めない
- 直接DBに書くな。必ずRLSポリシーを通すこと
③ ./CLAUDE.local.md(個人設定)
## ローカル環境
- .env.localにSupabaseのキーがある
- ローカルDBのポートは54322
④ .claude/rules/database.md(ディレクトリ別)
## DBアクセスのルール
- すべてのクエリはRLSポリシーを通すこと
- トランザクションが必要な場合はsupabase.rpcを使う
- N+1クエリ禁止
優先度のイメージ
広く・薄い
↑
│ ~/.claude/CLAUDE.md 全プロジェクト共通の習慣
│ ./CLAUDE.md このプロジェクト固有のルール
│ ./CLAUDE.local.md 自分の環境だけの設定
│ .claude/rules/*.md このディレクトリだけのルール
↓
狭く・深い
上の層ほど「いつでも・どこでも適用」 下の層ほど「このファイルを触るときだけ適用」
追伸
あなたの学びや挑戦の一歩を後押しできていたら幸いです。よければフォローやスキで応援してください。次の記事づくりの力になります。
次回予告
第3回は CLAUDE.mdの失敗パターン。
設計論を知った上で「それでもやりがちなミス」を5つ解説する。Wikiダンプ・/initの罠・曖昧ルール・放置・1ファイル集約——それぞれの「なぜ失敗か」と「どう直すか」をセットで理解すると、この記事の設計論がより深く刺さる。