CLAUDE.md の書き方ガイド — Claude Code を最大限に活かすプロジェクト設定術【2026年版】

CLAUDE.md とは？ — Claude Code に「プロジェクトの前提知識」を伝えるファイル

「Claude Code を使っているのに、毎回同じ説明を繰り返していませんか？」 CLAUDE.md を正しく書くだけで、Claude Code はあなたのプロジェクトを深く理解したパートナーに変わります。

CLAUDE.md は、Claude Code（基本的な使い方は「Claude Code完全ガイド」を参照）がプロジェクトのコンテキストを理解するための設定ファイルです。プロジェクトのルート、またはユーザーのホームディレクトリに配置することで、Claude Code が作業を開始する際に自動的に読み込まれます。

通常、AIコーディングアシスタントに作業を依頼するたびに「このプロジェクトは TypeScript で書かれていて、テストフレームワークは Vitest で…」と説明する必要があります。CLAUDE.md を用意しておけば、この手間がゼロになります。

CLAUDE.md の基本的な役割

• プロジェクトのルールを定義: コーディング規約、ディレクトリ構造、命名規則などをAIに事前共有
• コンテキストの永続化: セッションが変わっても、プロジェクトの前提知識が引き継がれる
• チーム共有: リポジトリに含めれば、チーム全員が同じAI体験を得られる
• 誤操作の防止: 「このブランチには直接pushしない」「テストを通さずコミットしない」などのガードレールを設定（特にエージェントモードでは重要）

💡 Tips: CLAUDE.md は「AIへの申し送り書」と考えると分かりやすいです。新しいメンバーがチームに入ったとき、最初に渡すオンボーディング資料のようなものです。

---

なぜ CLAUDE.md が重要なのか — 3つの理由

1. プロンプトの繰り返しを排除できる

Claude Code を使うたびに「TypeScript を使ってください」「テストは Vitest で書いてください」と指示するのは非効率です。CLAUDE.md に一度書いておけば、以降はすべてのセッションで自動的に適用されます。

2. 出力の品質が安定する

AIの出力は、与えるコンテキストの質に大きく左右されます。CLAUDE.md でコーディング規約やアーキテクチャの方針を明示しておくと、生成されるコードの品質が安定します。

# 具体例: CLAUDE.md がない場合
→ 関数名がキャメルケースだったりスネークケースだったり統一されない
→ テストファイルの配置場所がバラバラ
→ importのパスが相対パスだったり絶対パスだったり混在する

# CLAUDE.md がある場合
→ 命名規則、テスト配置、import方針が毎回一貫する

3. チーム全体のAI活用レベルが底上げされる

CLAUDE.md をリポジトリにコミットすれば、チームメンバー全員が同じルールでClaude Codeを使えます。個人のプロンプト力に依存しない、組織としてのAI活用が実現します。

---

CLAUDE.md の配置場所と読み込み順序

Claude Code は複数の場所から CLAUDE.md を読み込みます。配置場所によって適用範囲が異なるため、目的に応じて使い分けましょう。

配置場所の一覧

配置場所	適用範囲	用途
~/.claude/CLAUDE.md	全プロジェクト共通	個人の共通ルール（言語設定、コミット規約など）
プロジェクトルート/CLAUDE.md	該当プロジェクト	プロジェクト固有のルール（技術スタック、アーキテクチャなど）
プロジェクトルート/.claude/CLAUDE.md	該当プロジェクト	プロジェクト固有（.claude ディレクトリにまとめたい場合）

読み込みの優先順位

Claude Code は以下の順序でファイルを読み込みます。

1. グローバル設定（~/.claude/CLAUDE.md）
2. プロジェクト設定（プロジェクトルートの CLAUDE.md または .claude/CLAUDE.md）

後から読み込まれた設定が優先されるため、プロジェクト固有のルールでグローバル設定を上書きできます。

⚠️ 注意: グローバル設定とプロジェクト設定で矛盾するルールを書くと、予期しない動作になる場合があります。グローバルには汎用的なルールだけを書き、具体的なルールはプロジェクト側に書くのがベストです。

---

CLAUDE.md の基本構成 — 5つのセクション

効果的な CLAUDE.md は、以下の5つのセクションで構成するのがおすすめです。

セクション1: プロジェクト概要

## プロジェクト概要
- プロジェクト名: MyApp
- 概要: SaaS型のタスク管理アプリケーション
- 技術スタック: Next.js 15 / TypeScript / Prisma / PostgreSQL
- パッケージマネージャー: pnpm
- Node.js バージョン: 22.x

プロジェクトの基本情報を簡潔にまとめます。Claude Code が「これはどんなプロジェクトか」を最初に把握するために必要です。

セクション2: ディレクトリ構造

## ディレクトリ構造
- `src/app/` — Next.js App Router のページ
- `src/components/` — 再利用可能なUIコンポーネント
- `src/lib/` — ユーティリティ関数、API クライアント
- `src/server/` — サーバーサイドのビジネスロジック
- `prisma/` — データベーススキーマとマイグレーション
- `tests/` — テストファイル（Vitest）

主要なディレクトリの役割を記載します。Claude Code がファイルを作成・編集する際に、適切な場所を選ぶ判断材料になります。

セクション3: コーディング規約

## コーディング規約
- 言語: TypeScript（strict モード）
- 関数名・変数名: キャメルケース（例: getUserById）
- 型定義: interface を優先（type は union/intersection のみ）
- import: エイリアスパス（@/）を使用
- コンポーネント: 関数コンポーネント + named export
- エラーハンドリング: Result パターンを使用（throw しない）
- コメント: 日本語で記述

コードの書き方に関するルールを明示します。ここが曖昧だと、生成されるコードにブレが出ます。

セクション4: 開発ワークフロー

## 開発ワークフロー
- ブランチ戦略: GitHub Flow（main + feature ブランチ）
- コミットメッセージ: Conventional Commits 形式（feat:, fix:, refactor: など）
- テスト: 新機能には必ずテストを書く（Vitest）
- PR: テストが通らない状態でマージしない
- main ブランチへの直接 push は禁止

開発フローに関するルールです。Claude Code が git 操作を行う際に、このルールに従って動作します。

セクション5: 禁止事項・注意事項

## 禁止事項
- any 型の使用禁止
- console.log をコミットに含めない（デバッグ用は必ず削除）
- .env ファイルをコミットしない
- node_modules/ を操作しない
- 既存のテストを削除しない（修正は可）

やってはいけないことを明確にします。AIが「良かれと思って」やりがちなミスを事前に防げます。

---

実践テンプレート — コピーして使える CLAUDE.md

以下は、実際のプロジェクトですぐに使えるテンプレートです。自分のプロジェクトに合わせてカスタマイズしてください。

Next.js プロジェクト用テンプレート

# CLAUDE.md

## プロジェクト概要
- プロジェクト名: [プロジェクト名]
- 概要: [一行で説明]
- 技術スタック: Next.js 15 / TypeScript / Tailwind CSS / Prisma / PostgreSQL
- パッケージマネージャー: pnpm
- Node.js: 22.x

## ディレクトリ構造
- src/app/ — App Router ページ
- src/components/ — UIコンポーネント（Shadcn/ui ベース）
- src/lib/ — ユーティリティ、APIクライアント
- src/server/ — サーバーサイドロジック
- prisma/ — DBスキーマ

## コーディング規約
- TypeScript strict モード
- 関数コンポーネント + named export
- import は @/ エイリアスを使用
- Server Components をデフォルトとし、必要な場合のみ "use client"
- Tailwind CSS でスタイリング（CSS Modules は使わない）

## コマンド
- `pnpm dev` — 開発サーバー起動
- `pnpm build` — プロダクションビルド
- `pnpm test` — テスト実行（Vitest）
- `pnpm lint` — ESLint + Prettier チェック
- `pnpm db:migrate` — Prisma マイグレーション実行

## Git ルール
- Conventional Commits 形式
- main への直接 push 禁止
- PR は必ずテスト通過後にマージ

## 禁止事項
- any 型の使用
- console.log のコミット
- .env ファイルのコミット

Astro プロジェクト用テンプレート

# CLAUDE.md

## プロジェクト概要
- プロジェクト名: [プロジェクト名]
- 概要: [一行で説明]
- 技術スタック: Astro 5 / TypeScript / Tailwind CSS
- ホスティング: Cloudflare Pages
- パッケージマネージャー: npm

## ディレクトリ構造
- src/pages/ — ルーティング（.astro ファイル）
- src/layouts/ — レイアウトコンポーネント
- src/components/ — 再利用可能コンポーネント
- src/content/ — コンテンツコレクション（MDX）
- src/styles/ — グローバルスタイル
- public/ — 静的アセット

## コーディング規約
- Astro コンポーネント: フロントマターで型定義
- MDX: frontmatter スキーマに従う
- 画像: src/assets/ に配置し、Astro Image で最適化

## 禁止事項
- public/ に大きな画像を直接配置しない
- インラインスタイルは使わない

---

書き方のベストプラクティス — 7つのポイント

1. 簡潔に書く

CLAUDE.md は長ければ良いというものではありません。Claude Code のコンテキストウィンドウを消費するため、必要な情報を簡潔にまとめましょう。

# ❌ 冗長な書き方
このプロジェクトではTypeScriptを使用しています。
TypeScriptのバージョンは5.7です。
コンパイラオプションはstrictモードを有効にしています。

# ✅ 簡潔な書き方
- TypeScript 5.7（strict モード）

2. 箇条書きを活用する

AIは構造化されたテキストを正確に理解します。長文の段落よりも、箇条書きの方が確実に伝わります。

3. コマンドを明記する

ビルド、テスト、リント、デプロイなどのコマンドは必ず記載しましょう。Claude Code がこれらの操作を実行する際に参照します。

## コマンド
- `npm run dev` — 開発サーバー（ポート3000）
- `npm run build` — プロダクションビルド
- `npm test` — 全テスト実行
- `npm test -- --watch` — テストウォッチモード

4. 禁止事項は具体的に

「きれいなコードを書いて」のような曖昧な指示ではなく、具体的な禁止事項を書きましょう。

# ❌ 曖昧
- きれいなコードを書く
- パフォーマンスに気をつける

# ✅ 具体的
- any 型を使わない
- N+1 クエリを発生させない
- 1ファイル300行を超えたら分割を検討する

5. 定期的に更新する

プロジェクトの進行に伴い、ルールや構成は変わります。CLAUDE.md もコードと同様にメンテナンスしましょう。

6. グローバル設定とプロジェクト設定を分ける

全プロジェクトに共通するルール（言語設定、コミット規約など）はグローバル設定（~/.claude/CLAUDE.md）に、プロジェクト固有のルールはプロジェクトルートに配置します。

# ~/.claude/CLAUDE.md（グローバル）
## 基本方針
- 日本語で応対する
- コミットメッセージは Conventional Commits 形式

# プロジェクトルート/CLAUDE.md（プロジェクト固有）
## 技術スタック
- Next.js 15 / TypeScript / Prisma

7. チームでレビューする

CLAUDE.md はコードと同じくレビュー対象にしましょう。チームメンバーからのフィードバックを反映することで、全員にとって使いやすい設定になります。

---

プロジェクト別の設定パターン

パターン1: 個人開発プロジェクト

個人開発では、自分の好みやワークフローを自由に設定できます。

# CLAUDE.md

## 基本情報
- 個人プロジェクト（開発者: 1名）
- 技術スタック: Astro / React / TypeScript

## コーディングスタイル
- 関数型アプローチを優先
- 早期リターンパターンを使う
- コメントは「なぜ」を書く（「何を」は書かない）

## ワークフロー
- main ブランチに直接コミットOK
- テストは重要なロジックのみ

パターン2: チーム開発プロジェクト

チーム開発では、統一性と安全性を重視した設定にします。

# CLAUDE.md

## チーム情報
- チーム規模: 5名
- レビュー体制: 全PRに1名以上のレビュー必須

## ブランチ戦略
- main: プロダクション（直接push禁止）
- develop: 開発統合ブランチ
- feature/*: 機能ブランチ
- hotfix/*: 緊急修正ブランチ

## PR ルール
- テンプレートに従って記述
- CI が全て通過してからマージ
- セルフマージ禁止

パターン3: モノレポプロジェクト

モノレポでは、ルートとパッケージごとに CLAUDE.md を配置します。

# ルート/CLAUDE.md
## モノレポ構成
- パッケージマネージャー: pnpm（workspace）
- packages/web — フロントエンド（Next.js）
- packages/api — バックエンド（Hono）
- packages/shared — 共有ライブラリ

## 共通ルール
- パッケージ間の import は shared を経由する
- 直接の相互参照禁止

---

よくある質問（FAQ）

Q. CLAUDE.md と .cursorrules は何が違うの？

CLAUDE.md は Claude Code 専用の設定ファイルです。一方、.cursorrules は Cursor エディタ専用です（詳しくは「Cursor Rulesガイド」を参照）。役割は似ていますが、対応するツールが異なります。両方のツールを使っている場合は、それぞれのファイルを用意しましょう。

Q. CLAUDE.md はリポジトリにコミットすべき？

チーム開発ならコミットすることをおすすめします。ただし、個人の好みが強い設定（言語設定など）はグローバル設定（~/.claude/CLAUDE.md）に置き、リポジトリにはプロジェクト固有のルールだけをコミットしましょう。

Q. どのくらいの長さが適切？

目安として 100〜300行 程度がおすすめです。短すぎるとAIに十分なコンテキストが伝わらず、長すぎるとコンテキストウィンドウを圧迫します。

Q. CLAUDE.md を書かなくても Claude Code は使える？

はい、使えます。ただし、毎回コンテキストをゼロから伝える必要があり、出力の一貫性も下がります。数分の投資で大きなリターンが得られるので、積極的に活用しましょう。

---

まとめ — CLAUDE.md はAI時代の「開発者ドキュメント」

CLAUDE.md は単なる設定ファイルではありません。AIとの協業を効率化するための「開発者ドキュメント」です。

押さえるべきポイント：

実際に筆者のプロジェクトでは、CLAUDE.mdを追加してからコードの一貫性が格段に向上しました。特にimportパスの統一とエラーハンドリングのパターンが安定するようになったのが大きい。

1. 配置場所を理解する — グローバルとプロジェクトで使い分け
2. 5つのセクションで構成 — 概要、構造、規約、ワークフロー、禁止事項
3. 簡潔に、具体的に書く — 箇条書き中心、曖昧な表現を避ける
4. 定期的に更新する — プロジェクトの変化に合わせてメンテナンス
5. チームで共有する — リポジトリにコミットして全員のAI体験を統一

CLAUDE.md を整備するだけで、Claude Code からの出力品質は確実に向上します。まだ書いていない方は、この記事のテンプレートをベースに、今日から始めてみてください。

---

関連リンク

• Claude Code 公式ドキュメント
• Claude Code の使い方 完全ガイド
• Claude Code MCP設定ガイド
• Anthropic 公式サイト