Claude CodeのCLAUDE.md活用術｜プロジェクトごとのAIカスタマイズで生産性を3倍にする方法
Claude Codeを使い始めて、最初は感動したものの「毎回同じ指示を出すのが面倒」「プロジェクトのルールを無視したコードが出てくる」と感じていませんか？
実はその悩み、CLAUDE.mdというたった1つの設定ファイルで解決できます。
CLAUDE.mdとは、Claude Codeがセッション開始時に自動で読み込む「プロジェクトの指示書」のようなファイルです。
ここにコーディング規約やビルドコマンド、プロジェクト固有のルールを書いておくだけで、Claudeは毎回「プロジェクトを理解した状態」から作業を開始してくれます。
逆に言えば、CLAUDE.mdを設定していない状態でClaude Codeを使うのは、新人エンジニアにオンボーディング資料なしで仕事を任せるようなものです。
的外れな提案が出るのも、コードスタイルがバラバラになるのも、ある意味当然のことなんですよね。
この記事では、CLAUDE.mdの基本的な仕組みから、プロジェクト種別ごとの具体的なテンプレート、そしてチーム開発で生産性を最大化するための運用ノウハウまで、実践的に解説します。
CLAUDE.mdを正しく設計するだけで、指示のやり直しや手戻りが大幅に減り、開発生産性が飛躍的に向上します。
「Claude Codeをもっと賢く使いこなしたい」という方は、ぜひ最後まで読んでみてください。
CLAUDE.mdとは？Claude Codeの指示書ファイルを理解する
CLAUDE.mdとは、Claude Codeがセッション開始時に自動的に読み込むMarkdown形式の設定ファイルです。
プロジェクトのコーディング規約やビルドコマンド、アーキテクチャの概要などを記述しておくことで、Claudeが毎回の会話で「プロジェクトを理解した状態」からスタートできるようになります。
LLM（大規模言語モデル）はセッション間の記憶を持たないため、CLAUDE.mdがなければ毎回ゼロから文脈を説明し直す必要があります。
つまりCLAUDE.mdは、AIとの協業において最も投資対効果が高い設定ファイルと言えるでしょう。
CLAUDE.mdの基本的な役割と仕組み
CLAUDE.mdの役割を一言で表すなら、「新しく入ったエンジニアに渡すオンボーディング資料」です。
Claude Codeは起動するたびにCLAUDE.mdを読み込み、その内容を会話のコンテキスト（前提知識）に含めます。
これにより、以下のような情報をセッションのたびに伝え直す必要がなくなります。
- ✓プロジェクトの概要（何を作っているのか）
- ✓技術スタック（使用言語、フレームワーク、バージョン）
- ✓コーディング規約（インデント、命名規則など）
- ✓ビルド・テスト・デプロイのコマンド
- ✓プロジェクト固有の注意事項や制約
公式ドキュメントではCLAUDE.mdの記述形式に特定のフォーマットは求められていませんが、短く、人間が読める状態に保つことが推奨されています。
3種類のCLAUDE.md（プロジェクト / ユーザー / ルール）の違い
CLAUDE.mdは実は1つだけではありません。
配置場所によって適用範囲が異なる、複数の種類が用意されています。
| 種類 | 配置場所 | 適用範囲 | 用途 |
|---|---|---|---|
| プロジェクトメモリ | ./CLAUDE.md |
そのプロジェクト全体 | チームで共有するコーディング規約・ビルドコマンド |
| ユーザーメモリ | ~/.claude/CLAUDE.md |
全プロジェクト共通 | 個人の好み・作業スタイル（例：日本語で回答、など） |
| プロジェクトルール | .claude/rules/*.md |
条件に応じて適用 | 特定のファイルパスやトピックにだけ適用するルール |
| エンタープライズポリシー | MDM等で配布 | 組織全体 | セキュリティポリシーなど組織で統一したいルール |
優先順位は「エンタープライズ ＞ プロジェクトメモリ = プロジェクトルール ＞ ユーザーメモリ」の順です。
競合しない内容はマージされますが、矛盾する場合は上位の設定が優先されます。
個人の開発スタイル（言語設定など）はユーザーメモリに、プロジェクト固有のルールはプロジェクトメモリに、というように使い分けを意識するのがポイントです。
CLAUDE.mdが読み込まれるタイミングと優先順位
CLAUDE.mdの読み込みタイミングは、配置場所によって異なります。
この仕組みを理解しておくと、情報の「出し分け」ができるようになり、コンテキストウィンドウの節約にもつながります。
つまり、プロジェクトルートのCLAUDE.mdには全体に関わるルールだけを書き、各サブディレクトリには「そこを触るときだけ必要な知識」を配置する、という設計が効果的です。
CLAUDE.mdの内容はセッション中のすべてのリクエストに含まれるため、書きすぎるとコンテキストウィンドウを圧迫し、かえってAIの精度が落ちるという点にも注意が必要です。
公式ドキュメントでは約500行以内に収めることが推奨されています。
CLAUDE.mdを設定するメリットと活用シーン
CLAUDE.mdを適切に設定することで、コードレビューの手戻りや指示の繰り返しが減り、開発生産性が大幅に向上します。
ここでは具体的にどんなメリットがあるのか、活用シーンとあわせて解説します。
コードレビュー指摘の削減とコーディング規約の自動適用
CLAUDE.mdにコーディング規約を明記しておけば、Claude Codeが最初からその規約に沿ったコードを生成してくれます。
たとえば「インデントは2スペース」「import文はES Modules形式で統一」「関数名はcamelCaseで書く」といったルールをCLAUDE.mdに書いておくだけで、毎回の指示が不要になります。
結果として、コードレビューの工数削減だけでなく、開発チーム全体のコード品質の底上げにもつながります。
プロジェクト固有のコンテキスト共有で手戻りを防ぐ
開発プロジェクトには、コードだけでは読み取れない「暗黙の知識」がたくさんあります。
たとえば「このAPIはレガシーなので直接呼ばないでほしい」「schema.prismaは直接編集せず、別ファイルから生成する」といったプロジェクト固有の制約です。
これらをCLAUDE.mdに明記しておけば、Claudeが「やってはいけないこと」を事前に把握できるため、的外れな提案や危険な変更を未然に防げます。
- ✕非推奨のライブラリやAPIを使ったコードを生成してしまう
- ✕直接編集禁止のファイルを書き換えてしまう
- ✕プロジェクトの命名規則と異なるファイル名・変数名を使う
- ✕テストの実行方法を知らず、テストなしでコードを追加する
CLAUDE.mdに書く際のコツは、単なる禁止事項ではなく「いつ・何をするか」をセットで書くことです。
たとえば「schema.prismaの直接編集は禁止」ではなく「schema.prismaを変更したいときは、schema/*.prismaを編集してからpnpm build:schemaを実行する」と書くと、Claudeが正しい手順で作業できます。
チーム全体でAIの出力品質を統一できる
CLAUDE.mdはGitリポジトリにコミットして共有できるため、チーム全員が同じAIの振る舞いを享受できます。
個人の環境で「なんとなくプロンプトを工夫する」のではなく、CLAUDE.mdという形でルールを共有資産にすることで、属人化を防ぎつつ、チーム全体の開発効率を底上げできるのが大きな利点です。
- ✓新メンバーがjoinした日からClaude Codeの恩恵を最大限に受けられる
- ✓「AさんのプロンプトだとうまくいくのにBさんだとダメ」という問題がなくなる
- ✓CLAUDE.md自体をPRレビューの対象にでき、ルールの品質が継続的に向上する
- ✓GitHub ActionsでもCLAUDE.mdが読み込まれるため、CI/CDとの一貫性が保てる
よくある「AIが的外れな提案をする」問題の根本解決
「Claude Codeの精度が悪い」と感じたとき、実はモデルの能力ではなくCLAUDE.mdの設計に問題があるケースが多いです。
よくある失敗パターンとしては、CLAUDE.mdに情報を詰め込みすぎて重要なルールが埋もれてしまうケースや、そもそもCLAUDE.mdを作っていないケースがあります。
LLMのコンテキストウィンドウは人間の「ワーキングメモリ」に近い性質を持っています。
不要な情報でメモリを埋め尽くすと、本当に重要なタスクに割けるリソースが減り、推論精度が低下します。
つまり、「何を書くか」と同じくらい「何を書かないか」が重要ということです。
Lint や Formatter で機械的に強制できるスタイルの指示は CLAUDE.md に書かず、プロジェクト固有の「罠」や「運用ルール」に絞るのがベストプラクティスです。
AI活用でお悩みなら、freedoorにご相談ください
freedoorでは、Claude CodeをはじめとしたAIツールの導入支援から、業務フロー全体のAI化まで、企業のAI活用を包括的にサポートしています。
CLAUDE.mdの書き方｜実践テンプレートとベストプラクティス
CLAUDE.mdの基本構成は、プロジェクト概要・技術スタック・コマンド・アーキテクチャ・注意事項の5セクションで構成するのが効果的です。
ここでは公式のベストプラクティスを踏まえた具体的な書き方と、すぐに使えるテンプレートを紹介します。
基本構成（プロジェクト概要 / 技術スタック / コマンド / アーキテクチャ / 注意事項）
公式ドキュメントやコミュニティのベストプラクティスをもとに、CLAUDE.mdに書くべき5つの基本セクションを紹介します。
| 1. プロジェクト概要 | 1〜2行でプロジェクトの全体像を伝える。Claudeが最初に迷わないための「地図」 |
| 2. 技術スタック | 使用言語、フレームワーク、バージョンを明記。「React」ではなく「React 19, Next.js 15」のように具体的に |
| 3. コマンド | ビルド、テスト、リント、デプロイの各コマンドを列挙。頻繁に使うものに絞る |
| 4. アーキテクチャ | 主要ディレクトリとその役割を簡潔に記述。全ファイルを列挙する必要はない |
| 5. 注意事項（ゴッチャ） | プロジェクト固有の罠、禁止事項、特殊なワークフローを「トリガー＋アクション」形式で記述 |
この5セクションを簡潔にまとめるだけで、Claudeの出力品質は大きく変わります。
公式の推奨では、CLAUDE.mdの各行について「これを削除するとClaudeが間違いを犯すか？」と自問し、そうでなければ削除する、というスタンスが勧められています。
プロジェクト種別ごとのテンプレート例
プロジェクトの種類によって、CLAUDE.mdに書くべき内容は変わります。
ここでは代表的な3パターンのテンプレート例を紹介します。
【Web開発（React / Next.js）のテンプレート例】
## Stack
– Next.js 15 (App Router), React 19, TypeScript strict
– Styling: Tailwind CSS v4
– DB: Supabase (PostgreSQL), ORM: Prisma
– Deploy: Vercel
## Commands
– dev: `pnpm dev`
– test: `pnpm vitest run`
– lint: `pnpm eslint . –fix`
– build: `pnpm build`
## Architecture
– src/app/ – App Router pages
– src/components/ – 共有UIコンポーネント
– src/lib/ – ユーティリティ、API client
– prisma/ – スキーマ定義
## Rules
– ES Modules (import/export) を使用、CommonJS (require) は禁止
– コンポーネントはdefault exportを使用
– schema.prismaを変更する場合は prisma/fragments/*.prisma を編集後、pnpm build:schema を実行
【API開発（Python / FastAPI）のテンプレート例】
## Stack
– Python 3.12, FastAPI, SQLAlchemy 2.0
– DB: PostgreSQL 16
– Queue: Redis + Celery
– Deploy: AWS ECS
## Commands
– dev: `uvicorn main:app –reload`
– test: `pytest -v –cov`
– lint: `ruff check . –fix`
– migrate: `alembic upgrade head`
## Rules
– 型ヒントを必ずつける（Any禁止）
– APIエンドポイントにはPydanticのバリデーションを必ず入れる
– DB操作は必ずリポジトリパターン経由（直接クエリ禁止）
– 決済関連のロジック変更時は必ずテストを書いてから実装
【データ分析（Python / Jupyter）のテンプレート例】
## Stack
– Python 3.11, pandas, polars, matplotlib, plotly
– Notebook: Jupyter Lab
– Data: BigQuery, CSV exports
## Commands
– notebook: `jupyter lab`
– test: `pytest tests/`
– format: `black . && isort .`
## Rules
– DataFrameの列名はsnake_caseで統一
– グラフには必ず日本語タイトルと軸ラベルをつける
– 大規模データ処理はpandasではなくpolarsを使う
– data/raw/内のファイルは読み取り専用。加工後はdata/processed/に保存
効果を最大化するための記述のコツと避けるべき書き方
CLAUDE.mdの効果を最大化するには、書き方のコツを押さえることが重要です。
- 具体的に書く：「2スペースインデント」のように明確に
- トリガーとアクションをセットで書く
- ALWAYS / NEVER で例外なき制約を明示
- バージョンを明記：「React 19」「Python 3.12」
- 定期的にレビューして古い情報を削除する
- 「コードを適切にフォーマットする」のような曖昧な指示
- Linter/Formatterで自動化できるスタイルルールの羅列
- /initの自動生成をそのまま使う（冗長になりがち）
- 情報を詰め込みすぎて500行を大幅に超える
- 更新せず古いルールが残ったまま放置する
特に重要なのは、CLAUDE.mdに書くべきは「スタイル」ではなく「プロジェクト固有の知識・罠・運用ルール」という点です。
Lintで機械的に強制できるルールはフックやCI/CDに任せ、CLAUDE.mdにはコードだけでは推測できない情報を集中させましょう。
また、LLMの研究によると、フロンティアモデルでも安定して扱える指示の数には限界があります。
Claude Codeのシステムプロンプトだけでかなりのトークンを消費しているため、CLAUDE.mdに追加する指示はできるだけ少なく、核心だけに絞ることが精度向上の鍵です。
プロジェクトごとのカスタマイズ実践例
CLAUDE.mdのテンプレートは、プロジェクトの種類や開発体制に応じてカスタマイズするのがベストプラクティスです。
ここでは、実際のプロジェクトを想定した具体的な設定例を3パターン紹介します。
Reactフロントエンド開発プロジェクトでの設定例
フロントエンド開発では、コンポーネントの設計方針やスタイリングのルール、ディレクトリ構成がチームごとに大きく異なります。
CLAUDE.mdでこれらを明示することで、Claudeが「自分のプロジェクトらしい」コードを生成してくれるようになります。
| コンポーネント方針 | 「関数コンポーネント＋Hooks」「default export」「1ファイル1コンポーネント」など設計思想を明記 |
| 状態管理 | 「Server Component優先」「クライアント状態はzustand」「グローバルstateは最小限に」など |
| スタイリング | 「Tailwind CSSのユーティリティクラスを使用」「インラインstyle禁止」「CSS Modulesは使わない」 |
| テスト方針 | 「ユーザー操作をベースにしたテストをvitest + Testing Libraryで書く」「スナップショットテスト禁止」 |
フロントエンドのCLAUDE.mdで特に効果が高いのは、コンポーネントの分割基準やディレクトリへの配置ルールの記述です。
「UIコンポーネントはsrc/components/ui/に、ページ固有のコンポーネントはsrc/app/[page]/の中に置く」のように具体的に書いておくと、ファイルの作成場所で迷うことがなくなります。
Python/FastAPIバックエンド開発での設定例
バックエンド開発では、APIの設計規約やデータベースとのやりとり方法、エラーハンドリングのパターンなど、プロジェクトのアーキテクチャに深く関わるルールが多くなります。
| APIの設計規約 | 「RESTful設計」「エンドポイントのバリデーションは必ずPydanticで行う」「レスポンスは標準フォーマットを使う」 |
| DB操作 | 「リポジトリパターン経由で操作」「直接SQLクエリ禁止」「マイグレーションはAlembicで管理」 |
| 型定義 | 「すべての関数に型ヒント必須」「Any型は禁止」「戻り値の型も明示」 |
| テスト | 「pytestでテストを書く」「API変更時は必ずテストを先に書く（TDD）」「カバレッジ80%以上を維持」 |
バックエンド開発では、テスト駆動開発（TDD）との組み合わせが特に効果的です。
CLAUDE.mdに「コードの追加・修正のたびにテストを書き、テストが通ることを確認してから次に進む」と書いておくと、Claudeがテストファースト で開発を進めてくれます。
これにより、「コードは生成されたけどバグだらけ」という状況を大幅に減らせます。
チーム開発（モノレポ・マイクロサービス）での設定例
大規模なチーム開発やモノレポ構成では、CLAUDE.mdの階層化が威力を発揮します。
プロジェクトルートには全体ルールを、各サービスやパッケージのディレクトリにはそのサービス固有のルールを配置する設計です。
├── CLAUDE.md # 全体の共通ルール
├── .claude/
│ └── rules/
│ ├── code-style.md # 共通コーディング規約
│ ├── testing.md # テスト規約
│ └── security.md # セキュリティ要件
├── packages/
│ ├── frontend/
│ │ └── CLAUDE.md # フロントエンド固有のルール
│ ├── backend/
│ │ └── CLAUDE.md # バックエンド固有のルール
│ └── shared/
│ └── CLAUDE.md # 共有ライブラリのルール
この構成のメリットは、Claudeがフロントエンドのファイルを触るときはフロントエンドのルールが、バックエンドを触るときはバックエンドのルールがそれぞれ適用されるという点です。
サブディレクトリのCLAUDE.mdはオンデマンドで読み込まれるため、コンテキストウィンドウを無駄に消費しません。
- ✓ルートCLAUDE.mdには全サービス共通のルールだけを書く
- ✓.claude/rules/でトピックごとにルールを分割する
- ✓パス固有ルール（YAMLフロントマターのpaths指定）を活用し、API向けルールはAPI用ファイルにだけ適用
- ✓個人の好み（エディタ設定、言語など）はユーザーメモリに分離する
- ✓CLAUDE.mdの変更はPRレビューの対象にして、チーム全体で品質を管理する
また、.claude/rules/ディレクトリ内のMarkdownファイルには、YAMLフロントマターでpathsフィールドを指定できます。
たとえばpaths: ["src/api/**/*.ts"]と書いておけば、API関連のファイルを触るときだけそのルールが適用される仕組みです。
このような「段階的開示（Progressive Disclosure）」の設計パターンにより、必要な情報だけを必要なときに渡すことができ、コンテキストの効率が大幅に向上します。
CLAUDE.mdの導入・運用手順と生産性を維持するコツ
CLAUDE.mdはプロジェクトのルートディレクトリに配置し、Markdown形式でプロジェクト固有のルールを記述します。
ここでは、初めてCLAUDE.mdを作成する方向けに、導入から運用までの具体的な手順とメンテナンスのコツを解説します。
CLAUDE.mdの作成から配置までの5ステップ
CLAUDE.mdの導入は難しくありません。
以下の5ステップで、今日からすぐに始められます。
1
Claude Codeのセッション内で /init を実行すると、プロジェクト構造を分析して CLAUDE.md の雛形を自動生成してくれます。ビルドシステム、テストフレームワーク、コードパターンを検出して初期内容を作成するため、ゼロから書くより効率的です。
2
/init で生成された内容には自明な情報や冗長な記述が含まれることが多いため、必ず手動で見直します。「これを削除するとClaudeが間違いを犯すか？」を基準に、不要な記述を削除しましょう。
3
コードだけでは推測できない情報を追記します。「このファイルは直接編集しない」「テスト前にこのコマンドを実行する」など、プロジェクト特有のゴッチャやワークフローを「トリガー＋アクション」形式で記述しましょう。
4
CLAUDE.md をリポジトリにコミットすれば、チーム全員が同じAIの振る舞いを共有できます。個人的な好みはユーザーメモリ（~/.claude/CLAUDE.md）に分離し、プロジェクトCLAUDE.mdにはチーム共通のルールだけを入れましょう。
5
CLAUDE.md は一度書いて終わりではありません。Claudeが期待通りに動かなかったとき、セッション中に # で始まるメモを入力すると、CLAUDE.md に追記する内容を提案してくれます。使いながら育てていくのがベストです。
定期的なメンテナンスと更新のポイント
CLAUDE.mdは「腐ったドキュメントは、ないよりも有害」と言われるほど、メンテナンスが重要です。
古いルールが残ったまま放置すると、Claudeが誤った前提で作業を進めてしまう原因になります。
なお、Claudeのセッション中に/memoryコマンドを使うと、システムエディタでCLAUDE.mdを直接編集できます。
作業中に気づいた改善点をすぐに反映できるので、メンテナンスのハードルが下がります。
チームへの展開と運用ルールの整備
CLAUDE.mdをチーム全体に展開する際は、いくつかの運用ルールを事前に整備しておくとスムーズです。
- ✓CLAUDE.mdの変更はPRレビュー必須とする（コードレビューと同じ扱い）
- ✓プロジェクトCLAUDE.mdと個人のユーザーメモリの役割分担を明確にする
- ✓新メンバー加入時のオンボーディング手順にCLAUDE.mdの説明を含める
- ✓CLAUDE.mdの「オーナー」を決め、定期的なメンテナンス責任を明確にする
- ✓「Claudeがルールを無視した」事例を共有する場を設ける（改善のインプットになる）
組織全体でClaude Codeを導入する場合は、エンタープライズポリシー（MDM等で配布するCLAUDE.md）を使って、セキュリティルールや共通規約を強制することも可能です。
この層は個人で除外できないため、「絶対に守ってほしいルール」を配布するのに適しています。
AI導入・DX推進でお悩みなら、freedoorにご相談ください
Claude CodeやAIツールの組織導入を検討されている企業さまへ。freedoorでは、開発チームのAI活用支援からDX全体の設計まで、伴走型でサポートしています。
よくある質問
-
ACLAUDE.mdとは、Claude Codeがセッション開始時に自動で読み込むMarkdown形式の設定ファイルです。プロジェクトのコーディング規約、ビルドコマンド、アーキテクチャ情報などを記述しておくことで、Claudeが毎回「プロジェクトを理解した状態」から作業を開始できるようになります。チームでGitリポジトリにコミットして共有することで、メンバー全員が同じAIの振る舞いを享受できます。
-
Aプロジェクト全体に適用するルールはプロジェクトのルートディレクトリ（
./CLAUDE.md）に配置します。個人の好みは~/.claude/CLAUDE.md（ユーザーメモリ）に、特定のディレクトリにだけ適用したいルールは.claude/rules/に配置するのが推奨されています。サブディレクトリに配置したCLAUDE.mdは、Claudeがそのディレクトリのファイルを読むときにオンデマンドで読み込まれます。 -
A基本は「プロジェクト概要」「技術スタック（バージョン付き）」「ビルド・テストコマンド」「アーキテクチャ（ディレクトリ構成）」「注意事項（プロジェクト固有の罠）」の5セクションです。LintやFormatterで自動化できるスタイルルールはCLAUDE.mdに書かず、コードだけでは推測できない「プロジェクト固有の知識」に絞ることが、精度を上げるコツです。公式では500行以内に収めることが推奨されています。
-
ACLAUDE.mdはGitリポジトリにコミットするだけでチーム全員に共有されます。CLAUDE.mdの変更をPRレビューの対象にすることで、ルールの品質も継続的に管理できます。個人的な好み（言語設定、作業スタイルなど）はユーザーメモリ（
~/.claude/CLAUDE.md）に分離し、プロジェクトCLAUDE.mdにはチーム共通のルールだけを書くのがベストプラクティスです。 -
AまずCLAUDE.mdが長すぎないか確認しましょう。情報量が多すぎるとLLMが重要なルールを無視することがあります。次に、指示が曖昧でないか見直します。「コードを適切に書く」ではなく「2スペースインデントを使用する」のように具体的に書くことが重要です。2回同じ失敗をしたら、
/clearでコンテキストをリセットして再プロンプトするのも効果的です。それでも改善しない場合は、フックやSkillsへの移行を検討してみてください。 -
ACLAUDE.mdはClaude Code専用の設定ファイルで、セッション開始時に自動で読み込まれます。一方、AGENTS.mdはGitHub CopilotやCursorなど、複数のAIコーディングツールが参照する汎用フォーマットです。Claude Codeだけを使うならCLAUDE.md、複数のAIツールを併用するチームならAGENTS.mdの採用が主流となっています。どちらもMarkdown形式で、書き方のベストプラクティスはほぼ共通です。
freedoorでは、AIを活用した開発生産性の向上を支援しています
「Claude Codeを導入したいが、チーム全体への展開方法がわからない」「AI活用で開発プロセスを効率化したい」「自社の業務フローにAIを組み込みたい」――そんなお悩みをお持ちの企業さまへ。freedoorでは、AIツールの導入支援から業務全体のDX化まで、包括的にサポートしています。まずはお気軽にご相談ください。
