モジュール 3：実アーキテクチャ 5 / 6
上級 S17 CLAUDE.md Project Instructions

CLAUDE.md設計

Claude Code のコンテキストに読み込まれる、簡潔でスコープ付きのプロジェクト指示を設計する。

2026年3月20日 20 分で読む
確認済み カリキュラム確認日: 2026年7月31日
Claude Code ≥ 2.1.226 公式情報 1 公式情報 2

学ぶこと

Claude Codeのセットアップで劇的に良い結果を得るために1つだけ変えられるとしたら、それはCLAUDE.mdファイルです。この1つのファイルが、コーディングスタイルからアーキテクチャの選択、テストアプローチまで、AIがプロジェクトで行うすべての判断を形作ります。

このセッションを終えると、以下を理解できます：

  • CLAUDE.mdがプロジェクトで最もレバレッジの高いファイルである理由
  • 指示の3階層の階層構造
  • 効果的なプロジェクト指示の設計原則
  • paths:フロントマターによるスコープ付きルール
  • トークンを無駄にしAIを混乱させる一般的なアンチパターン
  • さまざまなプロジェクトタイプに合わせたCLAUDE.mdの構造化方法

課題

新しい開発者をプロジェクトに迎えるとき、オンボーディングに何時間もかけます：テックスタック、規約、テストアプローチ、物の配置場所、避けるべきことの説明。このコンテキストがなければ、動くけれどフィットしないコードを書いてしまいます。

Claude Codeも同じ問題に直面しています。指示がなければ、AIは以下のようになります：

  • トレーニングのデフォルトを使用（スタックと一致しない可能性がある）
  • 規約を推測（タブvsスペース、命名パターン、テストフレームワーク）
  • 既存のパターンと矛盾するアーキテクチャの決定
  • 自動メモリが拾うとは限らない場当たり的な訂正に頼り、権威あるバージョン管理された唯一の情報源を持たない

すべての会話で再説明することもできます。または、一度だけ書き留めることもできます。

仕組み

3階層の階層構造

Claude Codeは3つのレベルから指示をロードし、それぞれ異なるスコープを持ちます：

┌──────────────────────────────────────────────┐
│           指示の階層構造                       │
│                                               │
│  Tier 1: ユーザーCLAUDE.md（グローバル）       │
│  ┌───────────────────────────────────────┐    │
│  │ ~/.claude/CLAUDE.md                    │    │
│  │                                        │    │
│  │ すべてのプロジェクトに適用              │    │
│  │ 個人の好み、グローバルルール            │    │
│  │ 例: "常にTypeScript strictモードを      │    │
│  │ 使用。関数型パターンを優先。"           │    │
│  └───────────────────────────────────────┘    │
│                                               │
│  Tier 2: プロジェクトCLAUDE.md（リポジトリ）   │
│  ┌───────────────────────────────────────┐    │
│  │ <project-root>/CLAUDE.md               │    │
│  │                                        │    │
│  │ このプロジェクトに適用                  │    │
│  │ テックスタック、アーキテクチャ、規約    │    │
│  │ バージョン管理にチェックイン            │    │
│  │ チーム全体で共有                        │    │
│  └───────────────────────────────────────┘    │
│                                               │
│  Tier 3: スコープ付きルール（パターン固有）    │
│  ┌───────────────────────────────────────┐    │
│  │ .claude/rules/*.md                     │    │
│  │                                        │    │
│  │ ファイルパスパターンでアクティベート    │    │
│  │ きめ細かい指示                          │    │
│  │ 例: テスト専用ルール、                  │    │
│  │ APIルート専用ルール                     │    │
│  └───────────────────────────────────────┘    │
│                                               │
│  コンテキストの組み立て:                        │
│  ユーザー + プロジェクト + 該当ルール           │
│                                               │
└──────────────────────────────────────────────┘

Claude Code は、適用される指示ファイルを同じコンテキストへ連結し、広い範囲のファイルから具体的なファイルの順に読み込みます。ただし、読み込み順はポリシー境界ではありません。指示が競合すると、Claude はどちらに従う場合もあります。「後勝ち」に頼らず、競合そのものを削除または調整してください。

各階層に含めるべき内容

Tier 1: ユーザーCLAUDE.md (~/.claude/CLAUDE.md)

すべてに適用される個人のデフォルト：

# 個人の好み

- すべてのプロジェクトでTypeScript strictモードを使用
- クラスベースよりも関数型プログラミングパターンを優先
- 実装前にテストを書く（TDD）
- コミットメッセージにconventional commitsを使用
- コードが完成したと見なす前に必ずリンターを実行

短く保ちましょう。すべてのプロジェクトに適用されるため、ここにプロジェクト固有のものがあると問題を引き起こします。

Tier 2: プロジェクトCLAUDE.md (<project-root>/CLAUDE.md)

コアのプロジェクトコンテキスト。これが最も重要な階層です：

# Project: E-Commerce API

## テックスタック
- Runtime: Node.js 20 + TypeScript 5.4
- Framework: Express 4 with express-async-errors
- Database: PostgreSQL 16 via Prisma ORM
- Testing: Vitest + Supertest
- Auth: JWT with refresh tokens

## 開発コマンド
- `pnpm dev` — 開発サーバーを起動（ポート3000）
- `pnpm test` — 全テストを実行
- `pnpm test:watch` — ウォッチモード
- `pnpm lint` — ESLint + Prettierチェック
- `pnpm db:migrate` — Prismaマイグレーションを実行
- `pnpm db:seed` — テストデータを投入

## アーキテクチャ
- Routes: src/routes/<resource>.ts
- Services: src/services/<resource>.ts（ビジネスロジック）
- Models: prisma/schema.prisma（信頼できる唯一の情報源）
- Middleware: src/middleware/（auth、validation、error）
- Tests: src/__tests__/<resource>.test.ts

## 規約
- すべてのルートハンドラはサービスに委譲（ルートにビジネスロジックを置かない）
- リクエストバリデーションにZodスキーマを使用
- エラーレスポンスはRFC 7807（Problem Details）に従う
- データベースクエリはサービスのみ、ルートでは不可
- すべての公開エンドポイントにインテグレーションテストが必要

Tier 3: スコープ付きルール (.claude/rules/*.md)

特定のファイルパターンにのみアクティベートされるルール：

---
paths:
  - "src/__tests__/**"
  - "**/*.test.ts"
---

# テストルール

- describe/itブロックを使用（test()ではなく）
- 各テストファイルは1つのサービスまたはルートをテスト
- テストデータにはファクトリ関数を使用、生のオブジェクトは不可
- afterEachで常にデータベース状態をクリーンアップ
- 外部サービスをモック、データベースは決してモックしない

paths:フロントマターはglobパターンを使用します。ルールは、AIがそのパターンにマッチするファイルで作業しているときにのみロードされます：

┌─────────────────────────────────────────────────┐
│  スコープ付きルールのアクティベーション            │
│                                                  │
│  src/routes/auth.ts で作業中                      │
│  → ロード: api-routes.md ルール                   │
│  → スキップ: testing.md ルール                    │
│                                                  │
│  src/__tests__/auth.test.ts で作業中              │
│  → ロード: testing.md ルール                      │
│  → スキップ: api-routes.md ルール                 │
│                                                  │
│  両方のファイルで同時に作業中                      │
│  → ロード: api-routes.md と testing.md            │
│                                                  │
└─────────────────────────────────────────────────┘

設計原則

1. 明快さは巧妙さに勝る

初日の有能な開発者に説明するように指示を書きましょう。非自明なことについて明示的にしましょう：

# 良い例: 明示的で実行可能
- エラーレスポンスはRFC 7807形式を使用: { type, title, status, detail }
- データベースIDはUUID、自動インクリメント整数は不可
- すべてのタイムスタンプはUTCのISO 8601、フロントエンドでのみローカルタイムに変換

# 悪い例: 曖昧で役に立たない
- 適切なエラーハンドリングを使用
- IDのベストプラクティスに従う
- 時間を正しく扱う

2. 指示で行動を導き、境界は別の層で強制する

CLAUDE.md には通常の作業方針を書きます。行動を導くことはできますが、ツールアクセスを許可または拒否するものではありません。強制すべき境界には permission、sandbox、hooks を使います：

# 良い例: 作業方針を明確にする
- 変更は src/ 配下を優先する
- 変更後に `pnpm test` と `pnpm lint` を実行する
- 新しい service は src/services/、route は src/routes/ に置く

# CLAUDE.md の外で強制する境界
- permissions: ツールやパスごとに allow、ask、deny を設定
- sandbox: ファイルシステムとネットワークへの到達範囲を制限
- hooks: ライフサイクルイベントで決定論的なチェックを実行

3. スキャン性のための構造化

CLAUDE.md はセッションのコンテキストに入るため、各行がコンテキストを消費し、その後のターンに影響し得ます。ヘッダー、テーブル、短い箇条書きで読み取りやすくしましょう：

## API規約

| パターン | 例 | 備考 |
|---------|---------|-------|
| ルートファイル | `src/routes/users.ts` | リソースごとに1ファイル |
| サービスファイル | `src/services/users.ts` | ビジネスロジックはここ |
| テストファイル | `src/__tests__/users.test.ts` | サービス構造をミラー |
| バリデータ | `src/validators/users.ts` | Zodスキーマ |

## 主要な決定
- **ORM**: Prisma（TypeORMではなく）— 型安全性のために選択
- **Auth**: JWT、15分のアクセス + 7日のリフレッシュトークン
- **Queue**: BullMQ（バックグラウンドジョブ用、Redisバック）

4. 「なぜ」を含める

規約に非自明な理由がある場合は説明しましょう。AIは意図を理解するとより良い判断を下します：

# 自動インクリメントIDではなくUUIDを使用する理由:
# 1. ID列挙攻撃を防ぐ
# 2. オフラインID生成が可能（モバイルクライアント）
# 3. マルチリージョンデータベースレプリケーションに安全

アンチパターン

テキストの壁 — アーキテクチャドキュメント全体を CLAUDE.md に詰め込むと、そのすべてがセッションコンテキストを占有します。プロジェクト CLAUDE.md は簡潔に保ち、詳細にはスコープ付きルールやリンク先ドキュメントを使いましょう。

矛盾する指示 — Tier 1が「Jestを使う」と言い、Tier 2が「Vitestを使う」と言うと、AIは混乱します。階層間の競合を監査しましょう。

過剰な仕様 — すべての関数シグネチャと変数名を指定。規約の範囲内でAIに判断を委ねましょう。すべてのインスタンスではなく、パターンを指定しましょう。

自明な指示 — 「適切なインデントを使用」や「エラーを処理」のようなことを書く。AIはすでにこれらを行います。CLAUDE.mdは自分のプロジェクトに固有のことに集中しましょう。

古い指示 — 3ヶ月前のデータベースマイグレーションに関する指示を残したまま。ドキュメントと同じように、定期的にレビューして整理しましょう。

重要なポイント

CLAUDE.md はバージョン管理できるプロジェクトコンテキストであり、システムプロンプトやポリシーエンジンではありません。 プロジェクト固有の指針は与えますが、動作を保証せず、permissions、sandbox、hooks の代わりにもなりません。コンテキストが良いほど、セッションごとの繰り返しを減らせます。

次のように考えてください：

Without CLAUDE.md:
  Session 1: "VitestでJestではない。PrismaでTypeORMではない。そして..."
  Session 2: "覚えて、VitestでJestではない。Prismaで..."
  Session 3: "もう言ったのに、Vitestを使うんだ..."

With CLAUDE.md:
  Session 1: "パスワードリセットのエンドポイントを追加" → （スタックをすでに知っている）
  Session 2: "認証ルートにレート制限を追加" → （パターンをすでに知っている）
  Session 3: "新しいサービスのテストを書く" → （テストフレームワークをすでに知っている）

公平に言えば、Claude Code の永続メモリが「Vitest を使う」のような訂正を最初のセッション後に記録することはあります。ただし想起はベストエフォートで、個人の環境に閉じたものです。共有 CLAUDE.md はチームに同じバージョン管理された指針を渡せますが、実際の動作はモデル、プロンプト、コンテキスト、強制設定にも依存します。

3階層の階層構造が強力なのは、関心の分離ができるからです：個人の好みが共有プロジェクト設定を汚染せず、ファイル固有のルールがグローバルコンテキストを肥大化させません。

Tier 3のスコープ付きルールは大規模プロジェクトで特に価値があります。すべての会話で500行の指示をロードする代わりに、AIは現在作業しているファイルに関連する30行のみをロードします。

ハンズオン例

Next.js + Prismaプロジェクトのための完全なCLAUDE.md

# Project: SaaS Dashboard

## テックスタック
- Framework: Next.js 14 (App Router)
- Language: TypeScript 5.4 (strict mode)
- Database: PostgreSQL 16 via Prisma
- Auth: NextAuth.js v5 with GitHub + Google providers
- Styling: Tailwind CSS + shadcn/ui components
- Testing: Vitest (unit) + Playwright (e2e)

## コマンド
- `pnpm dev` — ローカルサーバー localhost:3000
- `pnpm test` — Vitestを実行
- `pnpm test:e2e` — Playwrightを実行
- `pnpm lint` — ESLintチェック
- `pnpm db:push` — スキーマ変更をプッシュ
- `pnpm db:studio` — Prisma Studioを開く

## アーキテクチャ
- `app/` — Next.jsページとレイアウト（App Router）
- `app/api/` — APIルート（Route Handlers）
- `components/` — Reactコンポーネント（shadcn/uiベース）
- `lib/` — 共有ユーティリティと設定
- `lib/db.ts` — Prismaクライアントシングルトン
- `prisma/schema.prisma` — データベーススキーマ

## 規約
- デフォルトでServer Components; 必要な場合のみ"use client"を追加
- APIルートは適切なステータスコードでNextResponse.json()を返す
- フォームミューテーションにはserver actionsを使用（APIルートではなく）
- Prismaクエリはlib/db/モジュールで、コンポーネントに直接書かない
- Tailwindクラス: 条件付きクラスにはcn()ヘルパーを使用
- コンポーネントファイル: PascalCase.tsx（例: UserProfile.tsx）

## 現在のスプリント
- チーム招待フローを実装中
- pages/からapp/ルーターへの移行（80%完了）

APIルートのスコープ付きルール

.claude/rules/api-routes.mdを作成：

---
paths:
  - "app/api/**"
---

# APIルートルール

- 処理前に必ずZodでリクエストボディをバリデーション
- 標準化されたエラー形式を返す: { error: string, code: string }
- 認証にミドルウェアパターンを使用: withAuth()でハンドラをラップ
- 公開エンドポイントにはrateLimit()ラッパーでレート制限
- すべての5xxエラーを構造化ログで記録（lib/logger.ts）
- 内部エラーメッセージをクライアントに公開しない

CLAUDE.mdの効果を確認する

以下の質問を自問してください：

1. 新しい開発者がこれを読んで貢献を始められるか？
   → いいえなら、アーキテクチャと規約についてコンテキストを追加

2. ここに自明またはジェネリックなものがあるか？
   → はいなら、削除（セッションコンテキストを節約）

3. 言及されていないプロジェクト固有の落とし穴があるか？
   → はいなら、追加（例: "レガシーuserテーブルは
     'user_id'ではなく'userid'を使用 — Prismaがスキーマでマッピング"）

4. 200行以下か？
   → いいえなら、ファイル固有のルールを.claude/rules/に移動

5. グローバルCLAUDE.mdと矛盾する指示があるか？
   → はいなら、明示的に競合を解決

何が変わったか

CLAUDE.mdなし3階層CLAUDE.mdあり
毎セッションで規約を再説明規約が自動的にロード
AIがスタックとパターンを推測AIが正確なスタックとパターンを把握
指示がプロンプトに散在共有されたプロジェクト指針、バージョン管理
すべてのファイルタイプに同じルールファイルパターンごとにスコープ付きルールがアクティベート
新しいチームメンバーが異なるコンテキストから始める共有 CLAUDE.md が一貫した指針を提供

次のセッション

セッションの保存とプロジェクト指示の定義を理解しました。モジュール3の最後のピースは信頼です。セッション18ではパーミッションモデルとセキュリティを扱います — サンドボックスから承認ゲート、組織ポリシーまで、Claude Codeの多層セキュリティモデルがどのように機能するかの詳細です。