CLAUDE.md書き方テンプレート｜3パターンと設定ファイル使い分け表

結論: CLAUDE.mdは「Claude Codeに毎回伝えなくていいルール」を1ファイルにまとめる仕組みです。Opus 5世代ではシステムプロンプトの80%以上が削減され、何を書くかより、何を書かないかの判断が出力品質を左右します。この記事では、公式ドキュメントの仕様をもとに、すぐ使える3パターンのテンプレートと、関連ファイルとの使い分け表を提供します。

この記事の要点:

• CLAUDE.mdには4つの配置スコープがある。組織・ユーザー・プロジェクト・ローカルの順に読み込まれ、後から読まれたものほどClaude の注意に残りやすい
• Opus 5/Fable 5では「指示を書き足す」から**「削って背景を伝える」**へ設計思想が変わった（Anthropic公式講演、参照日: 2026-08-27）
• CLAUDE.md・.claude/rules/・SKILL.md・settings.jsonは役割が異なる。書く場所を間違えると指示が空振りしたり、毎回不要なコンテキストを消費したりする

対象読者: Claude Codeを使い始めたエンジニア、またはCLAUDE.mdを作ったものの指示が守られない・ファイルが肥大化していると感じている人

読了後にできること: 自分のプロジェクトに合ったCLAUDE.mdを今日中に作成し、SKILL.mdやsettings.jsonとの使い分けを判断できるようになる

この記事では、CLAUDE.mdの基本仕様から始めて、Opus 5世代で変わった書き方の考え方、3パターンのテンプレート、設定ファイルの使い分けまでを順に解説します。Claude Codeの指示が効かないときのトラブルシューティングも扱います。関連記事として、スキルファイルの設計は「Agent Skillsの作り方｜5分で始める7つの実践設計ルール」、Hooksによる強制実行は「Claude Code Hooks入門｜HTTP対応の設定と自動化レシピ5選」で扱っています。

CLAUDE.mdとは — 毎セッションに引き継がれる指示メモ

CLAUDE.mdは、Claude Codeがセッション開始時に読み込むMarkdownファイルです。ビルドコマンド、コーディング規約、プロジェクト構造の説明、「常にこうしてほしい」というルールを書いておけば、毎回チャットで伝え直す手間が省けます。

公式ドキュメントでは次のように位置付けられています。

CLAUDE.md files are markdown files that give Claude persistent instructions for a project, your personal workflow, or your entire organization. — Anthropic公式ドキュメント（参照日: 2026-08-27）

**CLAUDE.mdはコンテキスト（文脈情報）**として読み込まれる仕組みです。Claudeはこれを参考に行動しますが、遵守が保証されるわけではありません。特定のツール呼び出しを確実にブロックするなら、settings.jsonのpermissions.denyやHooksが適しています。

いつCLAUDE.mdに追記するか

公式ドキュメントが示す追記タイミングは4つです。

1. Claudeが同じ間違いを2回したとき — 口頭の修正は次のセッションに残らない
2. **コードレビューで「Claudeが知っておくべきだった」**と判明したとき
3. 前回のセッションと同じ説明をチャットに入力したとき
4. 新しいメンバーにも伝える必要がある情報だったとき

逆に、コードベースから読み取れるプロジェクト構造や依存関係の一覧は書かなくてよいとされています。/doctorコマンド（v2.1.206以降）はCLAUDE.mdから冗長な部分を提案してくれるので、肥大化したファイルの整理に使えます。

Opus 5世代で変わった設計思想 — 書き足すから「削る」へ

2026年7月、Claude Code のデフォルトモデルがOpus 5に切り替わりました。同時期に、AnthropicはClaude Codeのシステムプロンプトの約80%を削除したと明かしています。品質を落とさずコスト削減できたと報告されました（iret.media講演分析記事、参照日: 2026-08-27）。

なぜ削減できたのか — Capability Overhang

Anthropicはこの変化を「Capability Overhang（能力超過）」と呼んでいます。新世代モデルには活用されていない能力があり、過剰な制約がかえって性能を抑え込んでいたという考え方です。

Anthropicの担当者は次のように述べています。

The harness we put them in…is basically a function of our understanding of Claude. — Anthropic講演（iret.media経由、参照日: 2026-08-27）

つまり、目的と背景を伝えてAI自身の判断力に委ねる方向へシフトしたということです。

Opus 5とFable 5で削れるもの

代わりに書くべきもの

制約を削った分、背景情報（Why）を厚くすることが推奨されています。

• 目的の宣言: 「このプロジェクトは〇〇向けのAPIで、△△を達成したい」
• 判断の基準: 「パフォーマンスより可読性を優先する」「テストカバレッジはN%以上を維持する」
• 方針として書く: 「any型は使わない」→「型安全を維持し、不明な型はunknownで受ける」

4階層のスコープ — 置く場所で届く範囲が変わる

CLAUDE.mdは置く場所によってスコープが変わります。すべてのスコープのファイルは連結して読み込まれ、ファイルシステムのルートからワーキングディレクトリへ向かう順で処理されます。後から読まれたものほどClaudeの注意に残りやすい構造です。

公式ドキュメントより作成（参照日: 2026-08-27）

サブディレクトリのCLAUDE.md

ワーキングディレクトリの下位フォルダに置いたCLAUDE.mdは、Claudeがそのフォルダ内のファイルを読んだタイミングで遅延読み込みされます。モノレポで部門ごとに異なるルールを設定するときに便利です。

@importで他ファイルを取り込む

CLAUDE.md内に@path/to/fileと書くと、そのファイルの内容が読み込み時に展開されます。最大4段階までの再帰インポートに対応しています。

# プロジェクト設定
@AGENTS.md
@docs/coding-standards.md

バッククォートで囲んだ場合（`@README`）はインポートされず、テキストとして扱われます。インポートはファイルを整理できますが、インポート先のファイルもすべてコンテキストに読み込まれるため、コンテキスト消費は減りません。

AGENTS.mdとの共存

Claude CodeはCLAUDE.mdだけを読み、AGENTS.mdは自動読み込みしません。両方を使うプロジェクトでは、シンボリックリンクかインポートで対応します。

# 方法1: シンボリックリンク
ln -s AGENTS.md CLAUDE.md

# 方法2: インポート + Claude Code固有の追加指示
# CLAUDE.md の中身:
# @AGENTS.md
# 
# ## Claude Code固有
# src/billing/ の変更はplan modeで行う

テンプレート3パターン — コピペして不要な行を削る

以下は用途別のテンプレートです。公式ドキュメントの推奨に沿い、200行以下を目安にしています。自分のプロジェクトに当てはまらないセクションは削除してください。残すセクションだけで構成するのが、Opus 5世代の「削る」思想に合った使い方です。

パターン1: 個人開発（30〜50行）

# プロジェクト概要

<このプロジェクトの目的を1〜2文で>

## ビルドとテスト

- ビルド: `npm run build`
- テスト: `npm test`
- lint: `npm run lint`

## コーディング規約

- TypeScript strict mode
- インデント: 2スペース
- 型は`unknown`で受け、`any`を使わない
- エラーは早期returnで処理する

## プロジェクト構造

- `src/api/` — APIハンドラ
- `src/lib/` — 共有ユーティリティ
- `src/types/` — 型定義

## やってほしいこと

- コミット前に`npm test`を実行する
- 新しいAPIエンドポイントには入力バリデーションを付ける

## やらなくていいこと

- このファイルにディレクトリ一覧を書き足す（コードから読み取れる）
- 変更のたびに確認を求める（自信があればそのまま進める）

パターン2: チーム開発（80〜120行）

# <プロジェクト名>

<目的と対象ユーザーを2〜3文で>

## ビルド・テスト・デプロイ

- ビルド: `pnpm build`
- テスト（ユニット）: `pnpm test`
- テスト（E2E）: `pnpm test:e2e`（ローカルDBが必要）
- lint + format: `pnpm check`
- デプロイ: mainへのマージでCI/CDが自動実行

## アーキテクチャの判断基準

- フロントエンドはNext.js App Router。Pages Routerは使わない
- 状態管理はサーバーコンポーネント優先。クライアント状態が必要な場合のみuseState
- DBアクセスはリポジトリパターン。直接クエリを書かない
- パフォーマンスより可読性を優先する

## ブランチとコミット

- ブランチ名: `feat/`, `fix/`, `chore/` プレフィックス
- コミットメッセージ: Conventional Commits形式
- force-push禁止

## レビュー時の注意

- 新規APIにはOpenAPIコメントを付ける
- 環境変数の追加時は`.env.example`も更新する
- マイグレーションは`pnpm db:migrate`で検証してからコミット

## セキュリティ

- ユーザー入力は必ずバリデーション
- 機密情報をログに出力しない
- SQLインジェクション対策はORMのパラメータバインディングで担保

ファイルの先頭にプロジェクトの目的を書くのがポイントです。Opus 5世代では、目的を理解したClaudeが細かいルールなしでも適切に判断するケースが増えています。

パターン3: CI/CD・自動化環境（40〜80行）

ヘッドレスでclaude -pを実行する場合や、GitHub Actionsから呼び出す場合のテンプレートです。

# CI自動化環境のルール

## 実行コンテキスト

- このCLAUDE.mdはGitHub Actionsのヘッドレス環境で読まれる
- 対話的な確認はできない。判断に迷う場合は安全側に倒す
- 外部APIへの書き込みは禁止。読み取りのみ

## 許可する操作

- ファイルの読み取りと編集
- テストの実行（`pnpm test`）
- lintの実行と自動修正（`pnpm lint:fix`）

## 禁止する操作

- `git push --force`
- `rm -rf` を含むコマンド
- 環境変数の外部送信
- `.env`ファイルの読み取り

## 出力フォーマット

- 結果はJSON形式で標準出力に出す
- エラー時は終了コード1で停止する
- 進捗はstderrに出力する

CI環境では禁止事項を明確に書く意味があります。ヘッドレス実行中はCLAUDE.mdが唯一のガードレールになるためです。ツールの実行を確実にブロックするならsettings.jsonのpermissions.denyを併用してください。

設定ファイル使い分け表 — CLAUDE.mdに全部書かない

Claude Codeには複数の設定ファイルがあり、それぞれ役割が異なります。CLAUDE.mdにすべてを詰め込むと肥大化し、遵守率が下がる原因になります。

Hooksについて詳しくは「Claude Code Hooks入門｜HTTP対応の設定と自動化レシピ5選」を参照してください。スキルファイルの設計は「Agent Skillsの作り方｜5分で始める7つの実践設計ルール」で解説しています。

.claude/rules/ の使い方

.claude/rules/ディレクトリに、トピックごとのMarkdownファイルを置く構成です。pathsフロントマターでglobパターンを指定すると、そのパターンに一致するファイルをClaudeが読んだときだけコンテキストに読み込まれます。

---
paths:
  - "src/api/**/*.ts"
---

# API開発ルール

- すべてのエンドポイントに入力バリデーションを付ける
- エラーレスポンスは標準フォーマットを使う
- OpenAPIコメントを付ける

pathsを書かないルールファイルは、起動時にCLAUDE.mdと同じタイミングで読み込まれます。

【要注意】CLAUDE.mdで踏みやすい4つの失敗

❌ 失敗1: 書きすぎて200行を超える

CLAUDE.mdの内容はセッション開始時にコンテキストウィンドウへ読み込まれます。公式ドキュメントでは1ファイル200行以上で遵守率が下がると注記されており、4MiBを超えるファイルはスキップ対象です。

⭕ 回避策: ファイル種別に依存するルールは.claude/rules/へ移す。手順やワークフローはSKILL.mdにする。/doctorコマンドで冗長な記述を検出する。

❌ 失敗2: コードベースから読み取れる情報を書く

ディレクトリ構造の全量リスト、依存パッケージの一覧、アーキテクチャの詳細図をCLAUDE.mdに書いても、Claudeはコードを直接読めるため冗長です。

⭕ 回避策: CLAUDE.mdにはClaudeがコードだけでは判断できない情報を書く。「src/legacy/は移行中なので新規コードを追加しない」のような判断基準が該当する。

❌ 失敗3: 矛盾するルールが複数ファイルに分散する

プロジェクトのCLAUDE.md、サブディレクトリのCLAUDE.md、.claude/rules/のルールファイルに矛盾する指示があると、Claudeはどれかを任意に選ぶ可能性があります。

⭕ 回避策: 定期的に/contextコマンドで読み込まれているファイルを確認し、矛盾を解消する。モノレポではclaudeMdExcludesで無関係なチームのCLAUDE.mdを除外する。

❌ 失敗4: 「〜するな」だけを並べる

Opus 5世代では目的と方針を書く方が効果的です。「any型を使うな」を含む10項目の禁止リストは、「型安全を維持する。不明な型はunknownで受ける」の1行に集約でき、幅広い場面をカバーできます。

⭕ 回避策: 禁止事項は「方針＋その理由」の形に書き換える。どうしても禁止が必要なケース（セキュリティ、データ削除など）だけ明示的に残す。

書く前の判断チェックリスト

CLAUDE.mdに新しい行を追加する前に、次の5項目を確認してください。

• コードベースから読み取れないか？ — ディレクトリ構造、依存関係、設定値はコードにある
• 特定ファイルにしか関係しないか？ — YESなら.claude/rules/にpaths付きで置く
• 呼び出し時だけ必要な手順か？ — YESならSKILL.mdにする
• Claudeの判断に関係なく強制したいか？ — YESならsettings.jsonかHooksを使う
• 追加後も200行以内か？ — NOなら既存の記述を.claude/rules/やSKILL.mdへ移す

すべてをクリアしたものだけCLAUDE.mdに追加します。

コンテキスト消費を意識した運用のコツ

CLAUDE.mdの内容はコンテキストウィンドウを消費する仕組みです。指示が多すぎると、実際の作業に使えるコンテキストが圧迫されます。コンテキストが足りなくなる問題については「Claude Codeコンテキスト管理｜遅い・止まるを5つの設定で解消」で詳しく扱っています。

HTMLコメントで人間向けメモを残す

CLAUDE.mdにHTMLブロックコメント（<!-- -->）を書くと、コンテキスト注入時に自動で除去されます。チームメンバー向けの注釈を残しつつ、Claudeのトークン消費を避けられます。

<!-- このセクションは2026Q4に見直す予定 -->
## デプロイ手順
mainへのマージで自動デプロイ

/compactとCLAUDE.mdの関係

セッション中に/compactを実行しても、プロジェクトルートのCLAUDE.mdはディスクから再読み込みされます。CLAUDE.mdに書いた指示は圧縮では消えない仕組みです。一方、サブディレクトリのCLAUDE.mdやパス指定のルールは、Claudeが該当ファイルを再度読むまで再読み込みされません。

/initで始める

/initコマンドを実行すると、Claudeがコードベースを分析してCLAUDE.mdの初版を自動生成します。すでにCLAUDE.mdが存在する場合は、既存内容を維持したまま改善提案を表示する動作です。CLAUDE_CODE_NEW_INIT=1を設定すれば、対話型のセットアップフローも使えます。

Q&A — よく出る5つの疑問

Q1. CLAUDE.mdとsettings.jsonはどう違う？

CLAUDE.mdは「Claudeへの行動指示」で、コンテキストとして読み込まれます。settings.jsonは「Claude Codeクライアントの強制設定」で、ツールの許可・拒否、サンドボックス、環境変数などを制御するものです。settings.jsonのpermissions.denyは確実に適用されるため、ブロックしたい操作はそちらに書くのが安全です。

Q2. CLAUDE.mdは何行まで書けますか？

技術的には4MiBまで読み込まれますが、公式推奨は1ファイル200行以下です。長くなるほどコンテキスト消費が増え、指示の遵守率が下がります。

Q3. AGENTS.mdがあるプロジェクトではどうすれば？

Claude CodeはAGENTS.mdを自動読み込みしません。CLAUDE.mdから@AGENTS.mdでインポートするか、ln -s AGENTS.md CLAUDE.mdでシンボリックリンクを作成します。

Q4. Cursorや他のAIコーディングツールの設定を取り込める？

/initを実行すると、.cursor/rules/や.github/copilot-instructions.mdの内容を読み取ってCLAUDE.mdに反映できます。CLAUDE_CODE_NEW_INIT=1を設定した場合は、AGENTS.md・Devinルール・Windsurfルールなども対話的に取り込めます。/importコマンド（v2.1.213以降）ではAGENTS.mdなどの指示ファイルをインポート可能です。

Q5. チーム内で個人設定が混ざるのを防ぐには？

個人の設定はCLAUDE.local.md（.gitignoreに追加）に書きます。プロジェクトのCLAUDE.mdには個人の好みを書かず、チーム共通のルールだけを置きます。

今日テンプレートを入れ、来週チームに展開する

1. 今日: 上のテンプレートから自分のプロジェクトに近いパターンを選び、不要な行を削ってCLAUDE.mdを作成する。/initで初版を生成してから手直しするのも有効
2. 今週: /contextで読み込まれているファイルを確認し、CLAUDE.mdに書かなくてよい情報（コードから読み取れるもの）を削る
3. 来週: チームでCLAUDE.mdをレビューし、個人設定はCLAUDE.local.mdへ分離する。ファイル種別固有のルールは.claude/rules/へ移す

次に読むなら、CLAUDE.mdと組み合わせて使うスキルファイルの設計を「Agent Skillsの作り方｜5分で始める7つの実践設計ルール」で解説しています。

参考・出典

• How Claude remembers your project — CLAUDE.md files（https://code.claude.com/docs/en/claude-md） — Anthropic公式ドキュメント（参照日: 2026-08-27）
• Claude Code settings（https://code.claude.com/docs/en/settings） — Anthropic公式ドキュメント（参照日: 2026-08-27）
• Claude Fable 5/Opus 5のプロンプトは"削る"が正解？ — Anthropic講演×公式ドキュメントを読み解く（https://iret.media/203395） — iret.media（参照日: 2026-08-27）
• Claude Opus 5 リリース！Fable 5に迫る性能を半額で（https://blog.serverworks.co.jp/2026/07/29/190000） — サーバーワークスエンジニアブログ（参照日: 2026-08-27）
• CLAUDE.mdとは？書き方やコツ、テンプレートを紹介！（https://shift-ai.co.jp/blog/55804/） — SHIFT AI TIMES（参照日: 2026-08-27）
• CLAUDE.mdとは？書き方テンプレート付き｜書きすぎが逆効果な理由（https://fyve.co.jp/claude-code/articles/claude-code-claude-md-guide） — fyve.co.jp（参照日: 2026-08-27）