プログラミング・スキルアップ

CLAUDE.md書き方完全ガイド｜2階層テンプレと運用パターン2026

Q: /init で生成されたCLAUDE.mdをそのまま使ってよい?

出発点としてはOK。ただし/initは既存コードから推測してドラフトを作るだけなので、間違いも混じる。「コンベンション」と「進め方」のセクションは必ず手で書き直す。技術スタックの行は鵜呑みにしない。

Q: ユーザー用とプロジェクト用、優先順位はどちら?

プロジェクト用が上。矛盾があった場合、Claudeはプロジェクト用の指示を優先する。だからプロジェクト用には全体の好みを上書きしたい例外だけを書くのが綺麗。

Q: チーム全員が同じCLAUDE.mdを使う必要はある?

チーム共通ルール(技術スタック・規約)は同じものを共有。個人の好み(応答言語、説明粒度)はCLAUDE.local.mdに分けて.gitignoreへ。これで揉めない。

Q: CLAUDE.mdが大きくなったら.claude/skills/に移すべき?

ルール(常に守らせたいこと)は CLAUDE.md か .claude/rules/ へ。手順(特定タスクの定型化)は .claude/skills/ へ。役割が違う。Skillsは呼ばれたら発火する手順書、CLAUDE.mdは常時有効な憲法と覚える。

2026年4月26日読了時間: 約15分

結論、Claude Codeの出力品質はCLAUDE.md一つで桁が変わる。毎回プロジェクトの説明をするのと、設定ファイルに書いて即作業に入るのとで、1日の体感生産性は3倍違う。

ところが世の中の解説記事は「とりあえず/initで作ってください」で終わるか、テンプレを並べるだけ。「ユーザー用とプロジェクト用、何をどっちに書くのか」という一番つまずくところを素通りしている。実際、筆者も最初の3ヶ月はここで何度も事故った。

この記事では2階層の使い分け、Next.js + Supabase の実テンプレ、チーム共有時のgitignore戦略、500行を超えた時の分割判断まで、運用ベースで整理する。明日から自分の設定ファイルを書き直したくなる粒度で書いた。

CLAUDE.mdは「新人に渡すプロジェクトの歩き方」
2つの階層: ユーザー用とプロジェクト用
ユーザー用CLAUDE.mdの書き方とテンプレ
プロジェクト用CLAUDE.mdの書き方とテンプレ
チーム共有時のgitignore戦略
CLAUDE.mdが効かない時の原因5つ
サイズ管理と.claude/rules/分割の基準
よくある失敗3パターン
FAQ
まとめと次のステップ

CLAUDE.mdは「新人に渡すプロジェクトの歩き方」

比喩で言うと、新しく入ってきたメンバーに渡す「歩き方ドキュメント」と同じだ。技術スタック、ディレクトリ構成、コーディング規約、進め方のルール。これを一枚にまとめておけば、毎回ゼロから説明しなくて済む。

違いはただ一つ。読み手が新人エンジニアではなくClaudeである、それだけ。

CLAUDE.mdが解決すること

毎回プロジェクトの技術スタックを説明し直す手間
毎回コーディング規約を書き直す手間
毎回好きな言語や形式を伝え直す手間
応答ごとに揺れる出力フォーマット

素のClaudeに「このアプリに認証機能を追加して」と聞くと、一般論が返る。技術スタックも仮定だらけ。設定ファイルに「Next.js 15 + Supabase Auth」と書いてあれば、初手から実装可能なコードが返ってくる。

この差は10倍では効かない。100倍変わる。

Claude Codeを使い始めて1週間以内に設定ファイルを書く人と書かない人で、3ヶ月後の生産性に決定的な差がつく。実体験ベースで言うと、書かなかったプロジェクトは1機能の追加に3往復のやり取りが必要だった。書いたプロジェクトでは初手のコードがそのまま通ることも珍しくない。Claude Codeの基本操作を覚えたら、次に手を付けるべきはここだ。

2つの階層: ユーザー用とプロジェクト用

設定ファイルには大きく2つの置き場所がある。役割が違う。

階層	パス	適用範囲	何を書く
ユーザー用	`~/.claude/CLAUDE.md`	全プロジェクト共通	自分の好み・思考様式
プロジェクト用	`<project>/CLAUDE.md`	そのプロジェクトのみ	プロジェクト固有の事実

境界線は明快だ。「他のプロジェクトに引っ越しても通用する話」はユーザー用に、「このプロジェクトを開いた時だけ必要な話」はプロジェクト用に。

迷ったら、こう自問する。

「この内容を、明日から始める別の案件でも使うか？」

Yes → ユーザー用
No → プロジェクト用

両方が読み込まれた時、Claudeは両方を踏まえて応答する。矛盾があると優先順位はプロジェクト用が上。なのでプロジェクト用には「ここだけは別ルール」だけを書き、共通の好みはユーザー用に集約する。これだけで運用がぐっと楽になる。

ユーザー用CLAUDE.mdの書き方とテンプレ

~/.claude/CLAUDE.md に置く。Claude Codeを起動すると、どのプロジェクトにいても自動で読み込まれる。

何を書くか

ここに書くべきは「自分という個人の固定値」だ。具体的には4項目に絞る。

応答の言語と粒度(日本語で・初心者向けに噛み砕く等)
コーディング規約の好み(any禁止・コメント方針・命名等)
作業の進め方(Planモード優先・結論先出し等)
自分のプロフィール(役職・経験・専門領域)

プロジェクト固有の情報(技術スタック、ディレクトリ構造)は絶対に書かない。ユーザー用に「Next.js 15を使う」と書いてしまうと、Pythonプロジェクトを開いた時にもClaudeが「Next.jsで実装します」と言い出す。これが地味に効く事故だ。

テンプレート(コピペ可)

# プロフィール

- 役職: バックエンドエンジニア5年目、Web系スタートアップ所属
- 専門: Python(FastAPI)、AWS、データ基盤
- 学習中: Next.js、TypeScript、Claude Code

# 全般ルール

- 応答は日本語で
- 説明は段階的に(前提 → 概要 → 詳細)
- 専門用語には初出で1行の補足を付ける
- 絵文字は使わない
- 結論から先に、根拠は後で

# コーディング規約

- TypeScript: any と unknown は使わず、明示的な型を書く
- Python: type hints を必ず付ける
- コメントは WHY のみ、WHAT は書かない
- 関数は1つの責務に絞る
- class は Error 継承以外では使わない

# 作業の進め方

- 大きな変更前には Plan モードで計画を見せる
- 不明点があれば勝手に決めず、聞き返す
- ファイル削除や git push は必ず確認を取る
- テストが落ちている時は原因を特定してから修正

書く時のコツ

3つだけ守る。

「いい感じに」を書かない。Claudeは「いい感じ」を解釈できない。具体的な動詞で書く
禁止事項のほうが効く。「〜してはいけない」「絵文字は使わない」のように、避けてほしい行動を明示する
200行を超えたら見直す。長すぎると守られない。原則を残し、具体例は削る

プロジェクト用CLAUDE.mdの書き方とテンプレ

プロジェクトのルートに CLAUDE.md を置く。git clone したメンバーが Claude Code を立ち上げた瞬間、同じルールが効く。

何を書くか

「このプロジェクトを開いた人が知らないといけない事実」を書く。6項目。

プロジェクト概要(何のサービスか、ターゲットは誰か)
技術スタック(言語・フレームワーク・主要ライブラリのバージョン)
ディレクトリ構成(どこに何があるか)
コンベンション(コンポーネント設計、データ取得方針)
環境変数(必要なkey一覧、置き場所)
進め方の特殊ルール(PR前の/review必須、テスト命名規則等)

テンプレート(Next.js + Supabase)

実プロジェクトでよく使う構成のテンプレ。バイブコーディングでTodoアプリやSaaSを作る時、これをそのまま貼って微調整するだけで動く。

# プロジェクト概要

ToDo管理SaaS。学生向けの軽量・高速な課題管理ツール。
無料プラン中心、月額480円のPro有り。デプロイはVercel。

# 技術スタック

- Next.js 15 (App Router)
- TypeScript 5.x (strict mode)
- Tailwind CSS + shadcn/ui
- Supabase (PostgreSQL + Auth + Storage)
- Vercel (deploy)
- Vitest (unit test)

# ディレクトリ構成

- `src/app/` : App Routerのルート
- `src/components/ui/` : shadcn/ui由来の汎用コンポーネント
- `src/components/features/` : 機能別コンポーネント(Todo、Auth等)
- `src/lib/supabase/` : Supabase接続(client/server/middleware)
- `src/hooks/` : カスタムフック
- `src/types/` : 型定義

# コンベンション

- コンポーネントはデフォルトServer Component
- `"use client"` は必要な最下層だけに付ける
- データ取得はServer ComponentまたはServer Actions
- フォームはuseFormState + Server Actionsで進める
- エラーハンドリングはerror.tsxで一元化

# 環境変数

`.env.local` に以下:

- NEXT_PUBLIC_SUPABASE_URL
- NEXT_PUBLIC_SUPABASE_ANON_KEY
- SUPABASE_SERVICE_ROLE_KEY (サーバー専用、絶対にクライアントへ漏らさない)

# 進め方

- Planモードで計画 → ユーザー確認 → 実装、の3ステップ厳守
- PR前に `/review` を必ず実行
- マイグレーション追加時はSupabase CLIで `supabase migration new`
- E2Eテストは後回し、ユニットテストだけ書く

書く時のコツ

プロジェクト用は「事実の正確さ」が命だ。曖昧な表現が混じると、Claudeはそこを推測で埋め始める。

バージョン番号を明記する。「Next.js最新版」ではなく「Next.js 15」
"やらないこと"を明示する。「Pages Routerは使わない」「JestではなくVitestを使う」
変更があったら即更新する。古い情報は嘘より悪い。Reactを19に上げたら、その日のうちに書き換える

チーム共有時のgitignore戦略

プロジェクト用CLAUDE.mdをチームで共有するときに最初に詰まるのが「個人の好みをどこに書くか」問題だ。

CLAUDE.mdをそのままgit管理すると、Aさんは「日本語で」と書きたい、Bさんは「英語で」と書きたい、で揉める。じゃあ.gitignoreに入れると、今度は新人がclone直後に何の規約も効かない状態でClaudeを動かしてしまう。

推奨パターン: 2ファイル運用

解決策は単純だ。ファイルを2枚に分ける。

ファイル	git管理	何を書く
CLAUDE.md	コミット	チーム全員が守るべきルール(技術スタック・規約)
CLAUDE.local.md	.gitignore	個人の好み・実験的な指示

.gitignore に CLAUDE.local.md を追加すれば、各メンバーが自分用の上書きルールを書けて、リポジトリは汚れない。

# .gitignore
CLAUDE.local.md
.claude/local-*

secretsは絶対に書かない

これは最大の落とし穴。CLAUDE.mdに「APIキーは sk-xxx を使う」と書いた瞬間、git logに永遠に残る。GitHub公開リポジトリなら全世界に公開される。

CLAUDE.mdに書いてはいけないもの

APIキー、Tokenの実値
本番DBの接続文字列
社内限定のURL、内部システム名(オープン化リスク)
個人を特定できる情報(顧客名、メールアドレス)

代わりに「.env.local に入っている」「NEXT_PUBLIC_SUPABASE_URL を参照する」のように環境変数の名前だけを書く。Claudeはそれで十分文脈を理解する。

CLAUDE.mdが効かない時の原因5つ

「CLAUDE.mdに書いたのにClaudeが守らない」と感じる時、原因はだいたい以下のどれかだ。順に潰す。

原因1: 1000行を超えて読まれていない

CLAUDE.mdが長すぎると、後半のルールが優先順位の中で埋もれる。経験則として500行を超えたら整理を検討、1000行を超えたら必ず分割する。

原因2: 抽象的すぎる

「コードはきれいに書く」のような指示は意味を成さない。「関数は40行以内」「ネストは3段まで」のように数字か具体的な動詞で書く。

原因3: 矛盾した指示が混在

「日本語で応答」と「英語で書く」が両方書かれていると、Claudeはどちらかを選ぶ。後から追加した指示が古い指示を上書きしているか確認する。

原因4: 例示が一切ない

「Conventional Commitsで」より「feat(auth): add password reset のような形式で」のほうが効く。ルールには必ず1つは具体例を添える。

原因5: セッションを再読み込みしていない

設定ファイルを更新しても、起動中のClaude Codeには反映されない。/clearで文脈をリセットするか、再起動が必要だ。地味だが、初学者がほぼ全員1度はハマる落とし穴。「ルールを書き直したのに無視される」と感じたら、9割このパターンを疑う。Cursorとの設定差分を整理した記事も合わせて読むと理解が深まる。

サイズ管理と.claude/rules/分割の基準

設定ファイルが膨らんできたら、.claude/rules/配下に分割する。判断基準を表で示す。

行数	推奨アクション
〜200行	そのままで問題なし
200〜500行	構成見直し。重複・冗長な記述を削る
500〜1000行	分割を検討。コーディング規約・運用ルールを別ファイルへ
1000行〜	必ず分割。読まれない可能性が高い

分割例

設定ファイルは「目次と原則」だけにし、詳細は.claude/rules/配下に分ける。

project-root/
├── CLAUDE.md              # 概要・原則(150行)
└── .claude/
    └── rules/
        ├── coding-style.md   # コーディング規約(200行)
        ├── git-workflow.md   # Git運用(80行)
        └── testing.md        # テスト方針(100行)

設定ファイルの中で@.claude/rules/coding-style.mdのように参照すると、Claudeが必要な時だけ読みに行く。これが「Progressive Disclosure(段階的開示)」と呼ばれるパターンだ。

最初から全部分割する必要はない。200行を超えてから考え始めるくらいで十分だ。早すぎる抽象化は逆にメンテコストを上げる。初手で5ファイルに分けたプロジェクトでは、3週間後にどこに何を書いたか分からなくなり、結局1ファイルに戻した。

よくある失敗3パターン

実際のプロジェクトでよく見る失敗を3つ。どれも筆者自身がやった、もしくは仲間がハマった事例だ。

失敗1: ユーザー用にプロジェクト固有の情報を書く

「Next.jsを使う」をユーザー用に書いてしまったことがある。Pythonプロジェクトを開いてClaudeに「APIエンドポイントを追加して」と頼んだら、しれっとNext.jsで実装し始めた。気づいたのは20分後、コードレビュー中だった。

対処はシンプル。ユーザー用は個人の好みだけ、技術スタックは必ずプロジェクト用へ。引っ越しても変わらないものだけがユーザー用に住む。

失敗2: ペルソナを複数書いて応答が崩壊

ユーザー用に「優しいメンター」、プロジェクト用に「厳格なシニアエンジニア」と二重にペルソナを設定したら、Claudeの口調が文ごとに変わって読めなくなった。

ペルソナはプロジェクト側に1つだけ。ユーザー側には書かない。プロンプトエンジニアリングの基本でも触れているが、役割は単一に絞ったほうが出力が安定する。

失敗3: 全部書きすぎて何も守られない

「念のため」と細かい規約を1500行書いた結果、Claudeが守るべき優先順位を見失い、結局どれも守られなかった。守らせたい原則は10〜20個に絞る。それ以上は具体例として別ファイルへ。設定ファイルは憲法であって判例集ではない。

FAQ

Q. `/init` で生成されたCLAUDE.mdをそのまま使ってよい?

出発点としてはOK。ただし/initは既存コードから推測してドラフトを作るだけなので、間違いも混じる。「コンベンション」と「進め方」のセクションは必ず手で書き直す。技術スタックの行は鵜呑みにしない。

Q. ユーザー用とプロジェクト用、優先順位はどちら?

プロジェクト用が上。矛盾があった場合、Claudeはプロジェクト用の指示を優先する。だからプロジェクト用には「全体の好みを上書きしたい例外」だけを書くのが綺麗。

Q. AGENTS.mdとは違うもの?

AGENTS.mdはOpenAI系・Cursor系のAIエージェントが参照する別ファイル。中身の思想はCLAUDE.mdとほぼ同じ。両方のツールを使うチームなら、共通部分を shared.md に切り出して両ファイルから参照する運用が現実的。

Q. チーム全員が同じCLAUDE.mdを使う必要はある?

チーム共通ルール(技術スタック・規約)は同じものを共有。個人の好み(応答言語、説明粒度)はCLAUDE.local.md に分けて.gitignoreへ。これで揉めない。

Q. CLAUDE.mdが大きくなったら`.claude/skills/`に移すべき?

ルール(常に守らせたいこと)は CLAUDE.md か .claude/rules/ へ。手順(特定タスクの定型化)は .claude/skills/ へ。役割が違う。Skillsは「呼ばれたら発火する手順書」、CLAUDE.mdは「常時有効な憲法」と覚える。

まとめと次のステップ

CLAUDE.mdを書く時の判断軸を3行で整理する。

1. ユーザー用は個人の好み、プロジェクト用は固有の事実 — 引っ越しても変わらないものはユーザー用へ
2. チーム共有はCLAUDE.md + CLAUDE.local.md の2枚運用 — local側を.gitignoreに追加
3. 1000行を超えたら必ず分割 — .claude/rules/ へ移し、CLAUDE.mdは原則だけに絞る

CLAUDE.mdが書けるようになったら、次の一歩はペルソナ設計とSkillsだ。CLAUDE.mdが「常時有効な憲法」なら、ペルソナは「特定の役割で呼び出す視点」、Skillsは「特定タスクを自動化する手順書」になる。3つを組み合わせると、Claude Codeは素のまま使うのとは別物になる。

関連して読むと理解が深まる記事を置いておく。

Claude Code入門｜導入・設定・Cursor比較の実践ガイド — そもそもの基本操作
バイブコーディング完全ガイド — AIに任せて書く開発スタイル
CursorとClaude Codeの設定ファイル完全ガイド — 他ツールとの併用
MCPサーバーおすすめ2026 — Claude Codeに手足を生やす
Claude Agent SDK入門 — エージェントを自分で作る

まずは~/.claude/CLAUDE.mdを1ファイル開いて、自分の好みを20行書いてみてほしい。それだけで明日からのClaudeとの会話が変わる。

CLAUDE.md書き方完全ガイド｜2階層テンプレと運用パターン2026

目次

CLAUDE.mdは「新人に渡すプロジェクトの歩き方」

2つの階層: ユーザー用とプロジェクト用

ユーザー用CLAUDE.mdの書き方とテンプレ

何を書くか

テンプレート(コピペ可)

書く時のコツ

プロジェクト用CLAUDE.mdの書き方とテンプレ

何を書くか

テンプレート(Next.js + Supabase)

書く時のコツ

チーム共有時のgitignore戦略

推奨パターン: 2ファイル運用

secretsは絶対に書かない

CLAUDE.mdが効かない時の原因5つ

原因1: 1000行を超えて読まれていない

原因2: 抽象的すぎる

原因3: 矛盾した指示が混在

原因4: 例示が一切ない

原因5: セッションを再読み込みしていない

サイズ管理と.claude/rules/分割の基準

分割例

よくある失敗3パターン

失敗1: ユーザー用にプロジェクト固有の情報を書く

失敗2: ペルソナを複数書いて応答が崩壊

失敗3: 全部書きすぎて何も守られない

FAQ

Q. /init で生成されたCLAUDE.mdをそのまま使ってよい?

Q. ユーザー用とプロジェクト用、優先順位はどちら?

Q. AGENTS.mdとは違うもの?

Q. チーム全員が同じCLAUDE.mdを使う必要はある?

Q. CLAUDE.mdが大きくなったら.claude/skills/に移すべき?

まとめと次のステップ

Q. `/init` で生成されたCLAUDE.mdをそのまま使ってよい?

Q. CLAUDE.mdが大きくなったら`.claude/skills/`に移すべき?