CLAUDE.mdの書き方ガイド｜Claude Codeの出力精度を高める設定ファイル運用術

Claude Codeを使い始めたものの、毎回同じ指示を繰り返している、プロジェクトのルールを守ってくれない――こうした課題の原因は、CLAUDE.mdの未設定もしくは不適切な記述にあります。

CLAUDE.mdはClaude Codeのプロジェクトメモリファイルです。セッション開始時にシステムプロンプトへ自動で読み込まれ、AIエージェントにプロジェクト固有の知識・制約・作業ルールを伝える役割を担います。適切に設定することで、コード生成の精度向上、開発規約の遵守、チーム内での品質統一が実現します。

CLAUDE.mdとは何か：役割と仕組み

CLAUDE.mdは、Claude Codeが起動するたびに読み込むMarkdownベースの設定ファイルです。新しいメンバーに渡すオンボーディング資料と同じ位置づけと考えるとわかりやすいです。

主な機能は3つあります。

プロジェクト知識の永続化: ディレクトリ構造、技術スタック、ビルドコマンドなどをセッション間で保持
開発ルールの強制: コーディング規約、テスト方針、禁止事項をAIに認識させる
コンテキストの効率化: 毎回プロンプトで繰り返していた指示を一元管理し、トークンの無駄遣いを防ぐ

ファイルは単純なMarkdown形式で記述し、プロジェクトルートに配置します。Git管理下に置くことでチームメンバー全員が同じ指示を共有できます。

6種類の配置場所と優先順位

CLAUDE.mdは配置場所によってスコープと優先度が異なります。公式ドキュメントで定義されている6種類を整理します。

種類	配置パス	スコープ	共有範囲
エンタープライズポリシー	`/etc/claude-code/CLAUDE.md`（Linux）	組織全体	全ユーザー
ユーザーメモリ	`~/.claude/CLAUDE.md`	全プロジェクト共通	個人
プロジェクトメモリ	`./CLAUDE.md` または `./.claude/CLAUDE.md`	リポジトリ単位	チーム（Git管理）
プロジェクトルール	`./.claude/rules/*.md`	リポジトリ単位	チーム（Git管理）
ローカルメモリ	`./CLAUDE.local.md`	リポジトリ単位	個人（`.gitignore`対象）
自動メモリ	`~/.claude/projects/<project>/memory/`	プロジェクト単位	個人

（出典: Claude Code公式ドキュメント）

優先順位は、公式ドキュメントで「より具体的な指示がより広範なものに優先する」と定義されています。

エンタープライズポリシー（最優先・オーバーライド不可）: 組織全体に適用される管理ポリシー
ローカルメモリ: 個人のプロジェクト固有設定がプロジェクト共有設定より優先
プロジェクトメモリ / プロジェクトルール: チーム共有のプロジェクト設定
ユーザーメモリ: 他に設定がない場合に適用される個人の全体設定

読み込みタイミングの違い

配置場所によって読み込まれるタイミングが異なる点は重要です。

作業ディレクトリより上位階層のCLAUDE.md: セッション起動時に全文が読み込まれる
作業ディレクトリより下位階層（サブディレクトリ）のCLAUDE.md: Claudeがそのサブディレクトリ内のファイルにアクセスした時点で遅延読み込みされる
自動メモリ（MEMORY.md）: 先頭200行のみがシステムプロンプトに読み込まれる

この仕様を理解しておくと、情報の配置戦略を適切に設計できます。たとえば、常に参照されるべきビルドコマンドはプロジェクトルートのCLAUDE.mdに書き、特定ディレクトリのテストルールはそのディレクトリ内のCLAUDE.mdや.claude/rules/で管理するのが効率的です。

記述の3本柱：WHAT・WHY・HOW

CLAUDE.mdに書くべき情報は、WHAT（何があるか）、WHY（なぜそうなっているか）、**HOW（どう作業するか）**の3つに分類できます。この構造に沿って記述することで、AIが必要な情報を正しく理解しやすくなります。

WHAT：プロジェクトの全体像を定義する

Claudeが最初に把握すべき「プロジェクトの事実情報」です。

# プロジェクト概要

- Rust製のWebAPI。axum + sqlx + PostgreSQLで構成
- フロントエンドはNext.js（App Router）、TypeScript
- モノレポ構成: /api（Rust）、/web（Next.js）、/shared（共有型定義）

書くべき情報の例を挙げます。

言語・フレームワーク・主要ライブラリのバージョン
ディレクトリ構造の概要（特にClaude Codeが迷いやすいもの）
データベースのスキーマ概要やモデルの関係性
外部サービスとの連携情報

WHY：設計意図と制約の背景を示す

「なぜその技術を選んだか」「なぜこの制約があるか」を書いておくと、Claudeが文脈に沿った判断を下しやすくなります。

# 設計方針

- ORMを使わずsqlxで直接SQLを書く方針。パフォーマンスの可視性を重視するため
- エラー型はanyhowではなくthiserrorで個別定義する。API応答のエラーコードを細かく制御するため
- CSS-in-JSは使わない。ビルドパフォーマンスとSSR互換性の理由からTailwind CSSを採用

WHYが書かれていないと、Claudeが「一般的なベストプラクティス」を優先して、プロジェクトの設計意図に反するコードを生成するリスクが高まります。

HOW：具体的な作業手順とルールを指示する

日常的に使うコマンドや開発ルールを列挙します。この部分がClaude Codeの動作に最も直接的に影響します。

# 開発コマンド

- ビルド: `cargo build`
- テスト: `cargo test -- --test-threads=1`（DB依存テストがあるため直列実行）
- Lint: `cargo clippy -- -D warnings`
- フォーマット: `cargo fmt --check`

# 開発ルール

- 新しいエンドポイントには必ず結合テストを書く
- コミットメッセージはConventional Commits形式に従う
- PRの説明には変更理由と影響範囲を明記する
- mainブランチへの直接pushは禁止。必ずPRを経由する

実装別テンプレート：言語・フレームワークごとの記述例

Rustプロジェクトの場合

# CLAUDE.md

## プロジェクト概要
RustによるRESTful API。フレームワークはaxum 0.8、ORMはsqlx。

## ディレクトリ構造
- src/handlers/ - HTTPハンドラ
- src/models/ - データモデルとDB操作
- src/errors/ - カスタムエラー型（thiserror）
- migrations/ - SQLマイグレーション

## 開発コマンド
- `cargo build` - ビルド
- `cargo test` - テスト実行
- `cargo clippy -- -D warnings` - Lint
- `sqlx migrate run` - マイグレーション適用

## コーディング規約
- unwrap()は本番コードで使用禁止。Result/Optionで適切にハンドリングする
- 型エイリアスよりもnewtypeパターンを優先する
- pub(crate)を積極的に使い、公開範囲を限定する

TypeScript + Reactプロジェクトの場合

# CLAUDE.md

## プロジェクト概要
Next.js 15（App Router）+ TypeScript。状態管理はZustand。

## ディレクトリ構造
- app/ - ページコンポーネント（App Router）
- components/ - 再利用可能なUIコンポーネント
- lib/ - ユーティリティ関数・API呼び出し
- types/ - 型定義

## 開発コマンド
- `pnpm dev` - 開発サーバー起動
- `pnpm build` - プロダクションビルド
- `pnpm test` - Vitest実行
- `pnpm lint` - ESLint実行
- `pnpm typecheck` - tsc --noEmit

## コーディング規約
- any型は禁止。unknown + 型ガードで安全にハンドリングする
- コンポーネントは関数宣言（function）で定義。アロー関数はコールバック用
- Server Componentsをデフォルトとし、use clientは必要最小限に留める
- importはパスエイリアス@/を使用する

Pythonプロジェクトの場合

# CLAUDE.md

## プロジェクト概要
FastAPI + SQLAlchemy 2.0 + PostgreSQL。Python 3.12。

## ディレクトリ構造
- app/api/ - ルーターとエンドポイント
- app/models/ - SQLAlchemyモデル
- app/schemas/ - Pydanticスキーマ
- app/services/ - ビジネスロジック
- tests/ - pytest

## 開発コマンド
- `uv run uvicorn app.main:app --reload` - 開発サーバー
- `uv run pytest` - テスト実行
- `uv run ruff check .` - Lint
- `uv run ruff format .` - フォーマット
- `uv run mypy app/` - 型チェック

## コーディング規約
- 型ヒントを全ての関数に付与する
- ルーターのパス操作関数にはdocstringを書く（OpenAPI生成のため）
- N+1クエリに注意。joinedloadまたはselectinloadを適切に使う

.claude/rules/ によるモジュール管理

プロジェクトが大きくなると、1つのCLAUDE.mdに全てを書くのは非効率です。.claude/rules/ディレクトリを使えば、トピックごとにルールファイルを分離できます。

ディレクトリ構成例

your-project/
├── CLAUDE.md                  # 概要・ビルドコマンドなど共通情報
├── .claude/
│   └── rules/
│       ├── code-style.md      # コーディングスタイル
│       ├── testing.md         # テスト方針
│       ├── security.md        # セキュリティ要件
│       ├── api-design.md      # API設計ガイドライン
│       └── frontend/
│           ├── components.md  # コンポーネント設計
│           └── styling.md     # スタイリングルール

.claude/rules/内のMarkdownファイルは再帰的に発見され、プロジェクトメモリと同じ優先度で読み込まれます。

パスに応じた条件付きルール

YAMLフロントマターで paths を指定すると、特定のファイルパスにのみ適用されるルールを作成できます。

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

# API開発ルール
- 全エンドポイントにバリデーションミドルウェアを適用する
- レスポンス型はzodスキーマから生成する
- エラーレスポンスはRFC 7807 Problem Details形式で返す

---
paths:
  - "**/*.test.ts"
  - "**/*.spec.ts"
---

# テストファイルのルール
- describeブロックでテスト対象の関数名を明記する
- 外部APIの呼び出しは必ずmockする
- テストデータはファクトリ関数で生成する

パスにはglobパターンと中括弧展開（*.{ts,tsx}）が使えます。pathsフィールドを省略したルールファイルは全ファイルに適用されます。

インポート構文で外部ファイルを参照する

CLAUDE.md内で @path/to/file と書くと、そのファイルの内容をコンテキストに取り込めます。

# プロジェクト概要
プロジェクトの詳細は @README.md を参照。
利用可能なnpmコマンドは @package.json を確認。

# Git運用ルール
@docs/git-workflow.md

インポートの仕様を整理します。

仕様	内容
パス解決	インポート元ファイルからの相対パス
ネスト深度	最大5階層まで再帰インポート可能
コードブロック内	評価されない（``で囲まれた@は無視）
外部インポート	初回アクセス時に承認ダイアログが表示される

（出典: Claude Code公式ドキュメント）

Git Worktreeで複数のワークツリーを使い分ける場合、ホームディレクトリからインポートすることで個人設定を共有できます。

# 個人設定
@~/.claude/my-project-notes.md

CLAUDE.local.md：個人設定をリポジトリから分離する

CLAUDE.local.mdは、チームで共有すべきではない個人的な設定を書くためのファイルです。自動的に.gitignoreの対象となり、リポジトリにコミットされません。

記述例:

# 個人開発環境

- ローカルDBのポート: 15432（デフォルトの5432はシステムが使用中）
- テスト環境のベースURL: http://localhost:3001
- デバッグ時は `RUST_LOG=debug` を設定して実行する
- CIが通らない場合のローカル確認手順: `docker compose up -d && cargo test`

ユースケースとして、個人のサンドボックスURL、ローカル固有のポート設定、デバッグ用の手順メモなどが適しています。

Claudeが指示を無視する場合の対処法

CLAUDE.mdを書いても指示が守られないケースがあります。原因と対策を整理します。

指示が無視される主な原因

原因	対策
情報量が多すぎる	指示を減らし、詳細は`.claude/rules/`に分離する
指示が曖昧	「適切にフォーマットする」→「2スペースインデントを使う」のように具体化
コンテキストウィンドウの上限	長時間セッションではCLAUDE.mdの情報が圧縮される。セッションを分割する
矛盾する指示がある	複数の配置場所で矛盾する記述がないか確認する

指示の確実性を高める記述テクニック

強調の度合いを3段階で使い分けると効果的です。

# 通常の指示
- テストにはVitestを使う

# 強調した指示
- **テストは必ずVitestで書く。Jestは使わない**

# 最高強調（本当に重要な場合のみ）
- IMPORTANT: データベースのマイグレーションは手動で確認してから適用する。自動実行は禁止

ただし、全てを最高強調にすると効果が薄れます。本当に守ってほしいルールに限定して使うのがポイントです。

LLMの特性として、プロンプトに書かれた指示の数が増えるほど1つ1つの遵守率が下がる傾向があります。CLAUDE.mdに書く指示は厳選し、「このルールがないとプロジェクトに実害が出る」ものだけに絞るのが効果的です。

/init コマンドと手動作成の使い分け

Claude Codeには /init コマンドが用意されており、プロジェクトのファイル構造を解析してCLAUDE.mdを自動生成できます。

# セッション内で実行
/init

自動生成されたCLAUDE.mdには、検出された技術スタック、ディレクトリ構造、ビルドコマンドなどが含まれます。

ただし、/initで生成されるファイルには限界があります。

観点	/init（自動生成）	手動作成
技術スタック検出	自動で検出	手動で記述
設計意図（WHY）	含まれない	明記できる
チーム固有のルール	含まれない	明記できる
セキュリティポリシー	含まれない	明記できる
初期構築の手間	少ない	多い

推奨されるアプローチは、/init で土台を生成した後、WHY（設計意図）とHOW（ルール）を手動で追記する方法です。自動生成だけに頼ると、AIが真に必要とする文脈情報（なぜこの構成を選んだか、何を避けるべきか）が欠落します。

チーム運用でのCLAUDE.md管理戦略

複数人でClaude Codeを使う場合、CLAUDE.mdの管理にはルールが必要です。

Git管理下での運用ポリシー

# リポジトリにコミットするファイル
CLAUDE.md             # チーム共有のプロジェクト設定
.claude/rules/*.md    # モジュール化されたルール

# .gitignoreに追加するファイル
CLAUDE.local.md       # 個人設定（自動で.gitignoreに追加される）

レビュー体制のチェックリスト

CLAUDE.mdの変更をPRで管理する場合の確認項目です。

指示が具体的か（「きれいに書く」のような曖昧な表現がないか）
矛盾する記述が既存のルールファイルと発生していないか
セキュリティに関わる情報（APIキーのパス、内部URLなど）が含まれていないか
.claude/rules/に分離すべき長い記述がCLAUDE.mdに直接書かれていないか
不要になったルールが残っていないか

シンボリックリンクで複数リポジトリ間のルールを共有

.claude/rules/はシンボリックリンクをサポートしています。共通のルールを別リポジトリで管理し、各プロジェクトからリンクする運用が可能です。

# 共有ルールリポジトリから特定のルールをリンク
ln -s /path/to/shared-rules/security.md .claude/rules/security.md

循環シンボリックリンクは自動検出されるため安全に利用できます。

段階的開示でコンテキスト効率を最適化する

「段階的開示（Progressive Disclosure）」は、Claudeが必要な時に必要な情報だけを取得する設計手法です。

実装の手順

CLAUDE.mdには最小限の概要とコマンドだけを書く
詳細情報は.claude/rules/や個別のMarkdownファイルに分散させる
インポート構文（@path）で必要に応じて参照する

具体的な構成例

# CLAUDE.md（プロジェクトルート・100行以内が目安）

## プロジェクト概要
ECサイトのバックエンドAPI。Rust + axum + PostgreSQL。

## ビルド・テスト
- `cargo build` - ビルド
- `cargo test` - テスト
- `cargo clippy` - Lint

## 重要なルール
- IMPORTANT: 決済処理に関するコードは必ず @docs/payment-guidelines.md を確認してから修正する
- テストの書き方は .claude/rules/testing.md を参照

こうすることで、日常的なコーディング作業ではコンテキストウィンドウを節約しつつ、決済処理やテスト方針など特定の領域に関する作業時には詳細な指示を取り込めます。

settings.jsonとの役割の違い

CLAUDE.mdと混同されやすい設定ファイルとしてsettings.jsonがあります。両者の役割は明確に分かれています。

項目	CLAUDE.md	settings.json
目的	AIへの指示・プロジェクト知識	権限・環境変数・フック
形式	Markdown	JSON
管理内容	コーディング規約、ビルドコマンド、設計方針	permissions.allow、env変数、hooks
配置場所	プロジェクトルート / `~/.claude/`	`.claude/settings.json` / `~/.claude/settings.json`

settings.jsonはClaude Codeの動作設定（どのBashコマンドを自動許可するか等）を管理するのに対し、CLAUDE.mdは作業内容に関する指示を管理します。

CLAUDE.md運用で陥りやすい失敗パターン

失敗1：情報を詰め込みすぎる

100行を超えるCLAUDE.mdに全てのルールを書き連ねると、LLMの注意力が分散し、重要な指示が無視される確率が上がります。

改善策: CLAUDE.mdは概要とビルドコマンドに絞り、詳細は.claude/rules/に分離します。

失敗2：/init の出力をそのまま使う

自動生成された内容には設計意図（WHY）やチームルールが含まれません。そのまま運用すると、Claudeがプロジェクトの方針に反するコードを生成します。

改善策: /initの出力を土台として、WHYとHOWのセクションを手動で追記します。

失敗3：更新しないまま放置する

プロジェクトの進化に伴い、技術スタックや開発ルールは変わります。古い情報が残ったCLAUDE.mdは、Claudeの判断を誤らせる原因になります。

改善策: スプリントの振り返りやPRレビューのタイミングでCLAUDE.mdの棚卸しを行います。

失敗4：コードスタイルの指示を書きすぎる

「インデントは2スペース」「セミコロンを付ける」のようなフォーマット指示は、ESLint・Prettier・rustfmtなどのリンター・フォーマッターに任せるべきです。CLAUDE.mdにコードスタイルを細かく書くと、ツールとの矛盾が発生するリスクがあります。

改善策: コードスタイルはリンター設定ファイルに委ね、CLAUDE.mdにはリンターの実行コマンドだけを記載します。

現場で使える完成形テンプレート

以下は、実務プロジェクトですぐに利用できるテンプレートです。プロジェクトに合わせて内容を差し替えてください。

# CLAUDE.md

## プロジェクト概要
[1〜3行でプロジェクトの目的と技術構成を記述]

## 技術スタック
- 言語: [例: Rust 1.82]
- フレームワーク: [例: axum 0.8]
- DB: [例: PostgreSQL 16]
- インフラ: [例: AWS ECS + RDS]

## ディレクトリ構造
- src/handlers/ - [説明]
- src/models/ - [説明]
- src/services/ - [説明]
- tests/ - [説明]

## 開発コマンド
- ビルド: `[コマンド]`
- テスト: `[コマンド]`
- Lint: `[コマンド]`
- マイグレーション: `[コマンド]`

## 設計方針
- [WHY: なぜこの技術を選んだか]
- [WHY: なぜこの制約があるか]

## 開発ルール
- IMPORTANT: [最も重要なルール]
- [ルール2]
- [ルール3]

## Git運用
- コミットメッセージ: [形式]
- ブランチ戦略: [例: GitHub Flow]

まとめ：効果を出すCLAUDE.mdの条件

CLAUDE.mdの品質はClaude Codeの出力精度に直結します。効果的なCLAUDE.mdに共通する条件は以下の3つです。

簡潔さ: 指示は厳選し、本当に必要なものだけを書く。詳細は.claude/rules/やインポートで分離する
具体性: 「きれいに書く」ではなく「2スペースインデント、セミコロンなし」のように明確に指定する
鮮度: プロジェクトの変化に合わせて定期的に更新し、古い情報を削除する

CLAUDE.mdの公式ドキュメントはClaude Code公式サイトのメモリ管理ページで確認できます。配置場所の仕様やインポート機能の最新情報はこちらを参照してください。

CLAUDE.mdとは何か：役割と仕組み#

6種類の配置場所と優先順位#

読み込みタイミングの違い#

記述の3本柱：WHAT・WHY・HOW#

WHAT：プロジェクトの全体像を定義する#

WHY：設計意図と制約の背景を示す#

HOW：具体的な作業手順とルールを指示する#

実装別テンプレート：言語・フレームワークごとの記述例#

Rustプロジェクトの場合#

TypeScript + Reactプロジェクトの場合#

Pythonプロジェクトの場合#

.claude/rules/ によるモジュール管理#

ディレクトリ構成例#

パスに応じた条件付きルール#

インポート構文で外部ファイルを参照する#

CLAUDE.local.md：個人設定をリポジトリから分離する#

Claudeが指示を無視する場合の対処法#

指示が無視される主な原因#

指示の確実性を高める記述テクニック#

/init コマンドと手動作成の使い分け#

チーム運用でのCLAUDE.md管理戦略#

Git管理下での運用ポリシー#

レビュー体制のチェックリスト#

シンボリックリンクで複数リポジトリ間のルールを共有#

段階的開示でコンテキスト効率を最適化する#

実装の手順#

具体的な構成例#

settings.jsonとの役割の違い#

CLAUDE.md運用で陥りやすい失敗パターン#

失敗1：情報を詰め込みすぎる#

失敗2：/init の出力をそのまま使う#

失敗3：更新しないまま放置する#

失敗4：コードスタイルの指示を書きすぎる#

現場で使える完成形テンプレート#

まとめ：効果を出すCLAUDE.mdの条件#