はじめに

Claude Code を使っていて、こんな経験はありませんか？

毎回同じコーディング規約を伝えている
テストの実行コマンドをその都度教えている
プロジェクト固有のルールを守ってくれない

これらをすべて解決するのが CLAUDE.md です。

CLAUDE.md は、Claude Code に「このプロジェクトではこう振る舞ってほしい」と伝えるための 設定ファイルです。一度書けば、セッションをまたいで自動的に読み込まれます。

この記事では、CLAUDE.md の仕組みから実践的な書き方まで、すべてを解説します。

CLAUDE.md とは

CLAUDE.md は、プロジェクトのルートに配置するマークダウンファイルです。Claude Code はセッション開始時にこのファイルを自動で読み込み、記載されたルールに従って動作します。

イメージとしては、新しく入ったチームメンバーに渡す「プロジェクトのお約束集」 のようなものです。

1. ファイルの配置場所と優先度

CLAUDE.md は複数の場所に配置でき、それぞれスコープが異なります。

配置場所の一覧

配置場所	スコープ	Git 管理	用途
`~/.claude/CLAUDE.md`	ユーザー全体	しない	すべてのプロジェクトに適用する個人設定
`./CLAUDE.md`	プロジェクト	する	チームで共有するプロジェクトルール
`./CLAUDE.local.md`	プロジェクト（個人）	しない	個人用のローカル設定
`./.claude/CLAUDE.md`	プロジェクト	する	`./CLAUDE.md` と同じ（配置場所の違い）
`./.claude/rules/*.md`	プロジェクト	する	テーマ別のモジュール化されたルール

読み込みの優先度

より詳細なスコープが優先されます。

ユーザー全体（~/.claude/CLAUDE.md）
  ↓ 上書きされる
プロジェクト（./CLAUDE.md）
  ↓ 上書きされる
プロジェクトローカル（./CLAUDE.local.md）

CLAUDE.local.md は自動で .gitignore に追加

CLAUDE.local.md は Git にコミットされない個人用ファイルです。Claude Code が自動的に .gitignore に追加してくれるため、手動設定は不要です。

2. 最初の CLAUDE.md を作る（/init）

一から書くのが面倒な場合は、/init コマンドで自動生成できます。

claude
> /init

Claude Code がプロジェクト構造を分析し、以下のような CLAUDE.md を自動生成します。

# Build & Test
- Build: `npm run build`
- Test: `npm test`
- Lint: `npm run lint`

# Code Style
- Language: TypeScript
- Format: Prettier (2-space indentation)
- Linter: ESLint

自動生成された内容はあくまでスタート地点です。ここから 自分のプロジェクトに合わせてカスタマイズ していきます。

3. 何を書くべきか

書くべき内容（高い効果が得られるもの）

よく使うコマンド

# Common Commands
- Build: `npm run build`
- Test: `npm test`
- Single test: `npm test -- filename.test.js`
- Lint: `npm run lint`
- Dev server: `npm run dev`

これを書いておくと、「テストを実行して」と言うだけで正しいコマンドを使ってくれます。

コーディング規約

# Code Style
- TypeScript を使用し、strict モードを有効にする
- インデントは 2 スペース
- var は使わず const / let を使用する
- 関数には必ず型注釈をつける
- コンポーネントは関数コンポーネントで書く（クラスコンポーネントは使わない）

テストのルール

# Testing
- テストフレームワーク: Jest
- テストファイルの配置: __tests__/ ディレクトリ
- 新機能には必ずテストを書く
- モックは最小限にし、実際の動作に近いテストを優先する

プロジェクト固有の注意事項

# Architecture
- API ルートは src/api/ に定義
- データベースマイグレーションは migrations/ に配置
- 認証は JWT を使用（src/middleware/auth.ts）
- 環境変数は .env から読み込み（コードにハードコードしない）

Git のルール

# Git Workflow
- コミットメッセージ: `<type>: <description>` 形式
  - type: feat, fix, refactor, docs, test, chore
- ブランチ名: `feature/xxx` または `fix/xxx`
- main ブランチに直接 push しない

書くべきでない内容

NG	理由
API キーやパスワード	Git にコミットされるため危険
「きれいなコードを書いて」のような曖昧な指示	具体性がないと効果がない
言語の基本文法	Claude はすでに理解している
頻繁に変わる情報	メンテナンスコストが高い
ファイルごとの詳細な説明	長くなりすぎる（rules/ に分割する）

4. @import で他のファイルを参照する

CLAUDE.md が長くなりすぎる場合、@ で外部ファイルを参照できます。

基本構文

# Overview
プロジェクトの概要は @README.md を参照してください。

# API Design
API 設計ルールは @docs/api-guidelines.md に記載しています。

# Personal Settings
個人設定は @~/.claude/my-preferences.md を参照。

使い方のポイント

パスは CLAUDE.md からの相対パス で解決される
@~/.claude/... のようにホームディレクトリも参照可能
再帰的なインポートも可能（最大5階層まで）
コードブロック内の @ は無視される（コード例として @ を安全に書ける）
初回インポート時にユーザーへの確認ダイアログが表示される

大規模プロジェクトでの活用

# My Project - CLAUDE.md

## Common Commands
- Build: `npm run build`
- Test: `npm test`

## Detailed Rules
- Frontend: @.claude/rules/frontend.md
- Backend: @.claude/rules/backend.md
- Security: @.claude/rules/security.md
- Testing: @.claude/rules/testing.md

CLAUDE.md 本体は簡潔に保ち、詳細は .claude/rules/ に分割します。

5. ディレクトリごとの CLAUDE.md

サブディレクトリにも CLAUDE.md を配置できます。そのディレクトリ内のファイルにアクセスしたときに読み込まれます。

モノレポでの活用例

your-monorepo/
├── CLAUDE.md                    # 全体ルール（共通）
├── packages/
│   ├── backend/
│   │   ├── CLAUDE.md            # バックエンド固有ルール
│   │   └── src/
│   └── frontend/
│       ├── CLAUDE.md            # フロントエンド固有ルール
│       └── src/

# packages/backend/CLAUDE.md
- フレームワーク: Express.js
- ORM: Prisma
- テスト: Jest + supertest
- API レスポンスは必ず { data, error, message } 形式で返す

# packages/frontend/CLAUDE.md
- フレームワーク: Next.js (App Router)
- スタイリング: Tailwind CSS
- 状態管理: Zustand
- コンポーネントは src/components/ に配置

これにより、バックエンドのコードを編集するときはバックエンドのルール、フロントエンドのコードを編集するときはフロントエンドのルールが自動的に適用されます。

6. .claude/rules/ でモジュール化

.claude/rules/ ディレクトリに、テーマ別のルールファイルを配置できます。

ディレクトリ構造

.claude/
├── CLAUDE.md
└── rules/
    ├── code-style.md
    ├── testing.md
    ├── security.md
    └── api-design.md

パス指定で対象ファイルを限定

rules ファイルでは、対象となるファイルパスを指定できます。

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

# API Development Rules
- すべてのエンドポイントにバリデーションを含める
- エラーレスポンスは統一フォーマットで返す
- OpenAPI のドキュメントコメントをつける

この設定により、src/api/ 配下のファイルを編集するときだけ、このルールが適用されます。

7. チーム利用のベストプラクティス

ファイルの使い分け

./CLAUDE.md               # チーム共通ルール（Git 管理）
./CLAUDE.local.md          # 個人設定（Git 管理しない）
~/.claude/CLAUDE.md        # 全プロジェクト共通の個人設定

チーム共通の CLAUDE.md（Git 管理）

# Team Rules - CLAUDE.md

## Commands
- Build: `./gradlew build`
- Test: `./gradlew test`
- Lint: `./gradlew spotlessCheck`
- Format: `./gradlew spotlessApply`

## Code Style
- Java 17 を使用
- Lombok は使わない
- record を積極的に活用する
- Optional を返す場合は null を返さない

## Git
- コミットメッセージは日本語で「〜を追加」「〜を修正」の形式
- PR にはテストが必須
- main ブランチへの直接 push 禁止

## Security
- .env ファイルを読み取らないこと
- API キーをハードコードしないこと
- SQL は PreparedStatement を使うこと

個人設定の CLAUDE.local.md

# Personal Settings - CLAUDE.local.md

## Local Environment
- DB: localhost:5432
- Redis: localhost:6379
- Dev server: http://localhost:8080

## My Preferences
- コメントは日本語で書く
- テストは変更したファイルに関連するものだけ実行

CLAUDE.md をコードレビューの対象にする

CLAUDE.md の変更は PR でレビューしましょう。チーム全体のルールが変わる重要な変更だからです。

8. CLAUDE.md を「育てる」コツ

CLAUDE.md は一度書いて終わりではなく、使いながら育てていく ものです。

育て方のサイクル

1. 最小限の内容で始める（/init で生成）
     ↓
2. Claude Code を使って開発する
     ↓
3. 「毎回同じことを伝えている」に気づく
     ↓
4. それを CLAUDE.md に追加する
     ↓
5. 2 に戻る

効果的な CLAUDE.md にする3つのコツ

1. 各行に「これがないと Claude が間違えるか？」と問う

不要な行は削除します。CLAUDE.md が長すぎると、重要なルールが埋もれて無視されやすくなります。

2. 曖昧な指示を避け、具体的に書く

# ❌ 曖昧
- きれいなコードを書く
- テストを書く

# ✅ 具体的
- 1関数は30行以内に収める
- 新しい public メソッドには必ず単体テストを書く

3. 定期的に見直す

月1回程度、CLAUDE.md を見直しましょう。

使われなくなったコマンドを削除
新しいツールの導入を反映
効果が薄いルールを改善

9. 実践テンプレート集

Java + Spring Boot プロジェクト

# Commands
- Build: `./gradlew build`
- Test: `./gradlew test`
- Run: `./gradlew bootRun`
- Single test: `./gradlew test --tests "ClassName.methodName"`

# Code Style
- Java 17, Spring Boot 3.x
- Lombok は使用しない（record や手動実装）
- Controller → Service → Repository の3層構造
- 例外は GlobalExceptionHandler で一括処理

# Database
- ORM: Spring Data JPA
- マイグレーション: Flyway（src/main/resources/db/migration/）
- SQL は PreparedStatement 相当（JPA の @Query パラメータバインド）

# Security
- API キーは環境変数から取得
- パスワードは BCryptPasswordEncoder でハッシュ化
- .env ファイルを読み取らない

React + TypeScript プロジェクト

# Commands
- Dev: `npm run dev`
- Build: `npm run build`
- Test: `npm test`
- Lint: `npm run lint`
- Type check: `npx tsc --noEmit`

# Code Style
- TypeScript strict mode
- 関数コンポーネントのみ（クラスコンポーネント禁止）
- Props は interface で定義（type ではなく）
- CSS: Tailwind CSS を使用

# State Management
- グローバル状態: Zustand
- サーバー状態: TanStack Query
- フォーム: React Hook Form + Zod

# Testing
- フレームワーク: Vitest + React Testing Library
- コンポーネントテストは振る舞いテストを優先
- MSW でAPIモックを作成

Python + FastAPI プロジェクト

# Commands
- Run: `uvicorn app.main:app --reload`
- Test: `pytest`
- Lint: `ruff check .`
- Format: `ruff format .`
- Type check: `mypy .`

# Code Style
- Python 3.12+
- Type hints を必ず書く
- async/await を活用する
- Pydantic v2 でバリデーション

# Project Structure
- app/api/ - ルーター
- app/models/ - SQLAlchemy モデル
- app/schemas/ - Pydantic スキーマ
- app/services/ - ビジネスロジック
- app/core/ - 設定、セキュリティ

# Database
- ORM: SQLAlchemy 2.0（async）
- マイグレーション: Alembic

まとめ

ポイント	内容
何を書く	コマンド、コーディング規約、テストルール、プロジェクト構成
何を書かない	API キー、曖昧な指示、基本文法、頻繁に変わる情報
配置場所	チーム共通は `./CLAUDE.md`、個人設定は `./CLAUDE.local.md`
長さ	50〜100行程度が理想。長くなったら `rules/` に分割
育て方	「毎回同じことを伝えている」と気づいたら追記する

CLAUDE.md を整備すると、Claude Code は あなたのプロジェクトを理解したチームメンバー のように振る舞います。最初は数行からでよいので、今日から始めてみてください。

@kotaro_ai_lab