モジュール 3：実アーキテクチャ 5 / 6

上級 Session 17 CLAUDE.md System Prompt

CLAUDE.md設計

システムプロンプトエンジニアリングとプロジェクト指示設計をマスターする。

2026年3月20日 · 20 分で読む

学ぶこと

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.mdはユーザーCLAUDE.mdをオーバーライドし、スコープ付きルールはマッチするファイルに対してプロジェクトCLAUDE.mdをオーバーライドします。

各階層に含めるべき内容

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. 制限ではなく許可

AIにできることを伝えましょう。できないことをすべてリストアップするのは無限であり、トークンを無駄にします：

# 良い例: 許可を明確に付与
- src/内の任意のファイルを直接変更可能
- `pnpm test`と`pnpm lint`を確認なしで実行可能
- src/services/とsrc/routes/に新しいファイルを作成可能

# 悪い例: 無限の制限
- package.jsonを変更しない
- データベーススキーマを変更しない
- CI設定を編集しない
- デプロイスクリプトに触れない
- ...（永遠に続く）

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

AIは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にダンプ。AIはすべてのターンでそれをすべて処理する必要があります。プロジェクトCLAUDE.mdは200行以下に抑え、残りはスコープ付きルールを使いましょう。

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

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

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

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

重要なポイント

CLAUDE.mdはプロジェクトのためのシステムプロンプトエンジニアリングです。 Anthropicが書くシステムプロンプトはAIの一般的な動作を制御します。あなたのCLAUDE.mdはプロジェクト固有の動作を制御します。CLAUDE.mdが良ければ良いほど、会話ごとに繰り返す必要が少なくなります。

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

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: "新しいサービスのテストを書く" → （テストフレームワークをすでに知っている）

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が正確なスタックとパターンを把握
指示がプロンプトに散在	信頼できる唯一の情報源、バージョン管理
すべてのファイルタイプに同じルール	ファイルパターンごとにスコープ付きルールがアクティベート
新しいチームメンバーが異なるAI動作を得る	共有CLAUDE.mdが一貫性を保証

次のセッション

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