Congaroo Media
Claude Code × Vibe Coding #3：CLAUDE.mdとドキュメント構成
テクノロジー

Claude Code × Vibe Coding #3：CLAUDE.mdとドキュメント構成

18分で読める
Congaroo Media
#Claude Code#vibe coding#CLAUDE.md#ドキュメント設計#プロジェクト管理

Claude Codeを活用したvibe codingの体系的なガイドブック。AIと協働する新時代の開発ワークフローを学ぶ

カジュアルモードは準備中です

第3章：CLAUDE.mdとドキュメント構成 ― プロジェクトの「取扱説明書」を作る

はじめに：CLAUDE.mdは最高レバレッジポイント

Claude Codeを使った開発で、最も投資対効果が高いのはCLAUDE.mdファイルの整備です。

なぜでしょうか？

CLAUDE.mdは、Claude Codeがセッションを開始するたびに自動的に読み込まれるファイルです。つまり、ここに書いた指示は、あなたが何も言わなくても、毎回Claudeに伝わります。

100回のセッションで毎回同じ説明をする代わりに、CLAUDE.mdに一度書けば済む。これが「最高レバレッジポイント」と呼ばれる理由です。

しかし、CLAUDE.mdは万能ではありません。書きすぎると逆効果になることもあります。この章では、効果的なCLAUDE.mdの書き方と、プロジェクト全体のドキュメント構成戦略を学びます。

CLAUDE.mdの基本

メモリ階層構造

Claude Codeは、複数の場所からCLAUDE.mdを読み込みます。これをメモリ階層と呼びます。

優先度（高い順）：
1. Enterprise Policy   - 組織全体のポリシー（管理者が設定）
2. Project Memory      - プロジェクト固有の指示（./CLAUDE.md）
3. User Memory         - 個人の好み（~/.claude/CLAUDE.md）
4. Project Local       - 個人のプロジェクト固有設定（./CLAUDE.local.md）

それぞれの役割を詳しく見ていきましょう：

Enterprise Policy（エンタープライズポリシー）

macOS: /Library/Application Support/ClaudeCode/CLAUDE.md
Linux: /etc/claude-code/CLAUDE.md

これは組織のIT管理者が設定するファイルです。個人開発では通常使いません。企業での利用時に、セキュリティポリシーや禁止事項を強制するために使われます。

Project Memory（プロジェクトメモリ）

./CLAUDE.md

これが最も重要なファイルです。プロジェクトルートに配置し、Gitで管理します。チームメンバー全員が同じ指示を共有できます。

User Memory（ユーザーメモリ）

~/.claude/CLAUDE.md

個人の好みを設定するファイルです。「私は常に日本語でコメントを書いてほしい」「インデントはスペース2つが好き」といった、プロジェクトに依存しない個人設定を書きます。

Project Local（プロジェクトローカル）

./CLAUDE.local.md

個人のプロジェクト固有設定です。.gitignoreに追加し、Gitにコミットしません。「このプロジェクトでは、私だけの開発用エンドポイントを使っている」といった、チームと共有しない設定を書きます。

読み込み順序と競合解決

複数のCLAUDE.mdに同じ項目について異なる指示が書かれている場合、より限定的なスコープの指示が優先されます。

例：

  • User Memory: 「日本語でコメントを書いて」
  • Project Memory: 「英語でコメントを書いて」

→ Project Memoryが優先され、このプロジェクトでは英語でコメントが書かれます。

効果的なCLAUDE.mdの書き方

黄金律：Less is More

CLAUDE.mdに書く内容は、少なければ少ないほど効果的です。

これは直感に反するかもしれません。「たくさん書けば、Claudeはより賢く動いてくれるのでは？」と思うかもしれません。しかし実際はその逆です。

HumanLayerの研究によると、CLAUDE.mdが長くなるほど、Claudeの指示遵守率は下がります。理由は2つあります：

  1. コンテキストウィンドウの圧迫: 長いCLAUDE.mdは、他の情報（コード、会話履歴など）を入れるスペースを奪います
  2. 注意の分散: 指示が多すぎると、重要な指示が埋もれてしまいます

目安として、CLAUDE.mdは300行以下に抑えましょう。

4つの原則

効果的なCLAUDE.mdには、4つの原則があります：

原則1：Universal Applicability（普遍的適用性）

CLAUDE.mdには、すべてのセッションに関連する指示だけを書きます。

良い例：

  • 「TypeScript strict modeを使用」
  • 「mainブランチへの直接コミット禁止」
  • 「テストなしでPRを出さない」

悪い例：

  • 「ユーザー認証機能を実装するときは...」（特定の機能に限定）
  • 「来週のリリースに向けて...」（時限的な内容）

特定の機能やタスクに関する指示は、SKILLSやtask-specific promptsに分離しましょう。

原則2：Don't Auto-Generate（自動生成に頼らない）

Claude Codeには/initコマンドがあり、プロジェクトを分析してCLAUDE.mdを自動生成してくれます。便利ですが、生成されたファイルをそのまま使うのは避けてください。

自動生成されるCLAUDE.mdは往々にして：

  • 冗長（同じことを複数の言い方で書いている）
  • 自明（書かなくてもClaudeが推測できる内容）
  • 古くなりやすい（生成時点の状態を反映）

/initで生成したファイルは、あくまで出発点として使い、各行を慎重に精査して、本当に必要な指示だけを残しましょう。

原則3：Avoid Style Guidelines（スタイルガイドは別で管理）

コーディングスタイルに関する指示は、CLAUDE.mdではなくlinterやformatterに任せます。

悪い例（CLAUDE.mdに書く）：

## Code Style
- インデントはスペース2つ
- 文字列はシングルクォート
- セミコロンは省略
- 行末にカンマを付ける

良い例（.prettierrcに書く）：

{
  "tabWidth": 2,
  "singleQuote": true,
  "semi": false,
  "trailingComma": "es5"
}

そしてCLAUDE.mdには：

## Code Style
Prettier設定に従うこと。`npm run format`でフォーマット。

これにより、CLAUDE.mdは簡潔に保たれ、スタイルの定義は一元管理されます。

原則4：Progressive Disclosure（段階的開示）

詳細な情報は、CLAUDE.mdに直接書くのではなく、別ファイルに分離して参照します。

悪い例：

## Database Schema

### Users Table
| Column | Type | Constraints |
|--------|------|-------------|
| id | uuid | PRIMARY KEY |
| email | varchar(255) | NOT NULL, UNIQUE |
| password_hash | varchar(255) | NOT NULL |
| created_at | timestamp | NOT NULL, DEFAULT now() |
| updated_at | timestamp | NOT NULL, DEFAULT now() |

### Posts Table
| Column | Type | Constraints |
|--------|------|-------------|
...（延々と続く）

良い例：

## Database
スキーマ詳細は `docs/ARCHITECTURE.md` を参照。

推奨するCLAUDE.mdの構成

以下は、私が推奨するCLAUDE.mdのテンプレートです：

# プロジェクト名

[スタックと目的の一行説明]
例：Next.js + Supabase で構築するタスク管理アプリ

## Quick Start

```bash
npm install
npm run dev

Common Commands

コマンド 説明
npm run dev 開発サーバー起動
npm run build プロダクションビルド
npm run test テスト実行
npm run lint Lint実行
npm run format コードフォーマット

Tech Stack

  • Frontend: Next.js 15.x / 16.x (App Router)
    • ⚠️ 重要: CVE-2025-66478（CVSS 10.0）等の重大なRCE脆弱性あり。15.5.7以上または16.0.7以上にアップグレード必須
    • 14.xは2025年10月にサポート終了。15.x/16.xへの移行を推奨
  • Backend: Next.js API Routes / FastAPI (Python)
    • Next.js API Routes: TypeScript一元管理、Vercelとの親和性
    • FastAPI: PyTorch/scikit-learn/LangChain等のAI/MLライブラリを直接利用可能、自動APIドキュメント生成
  • Database: Supabase (PostgreSQL)
  • Auth: Supabase Auth
  • Styling: Tailwind CSS

Architecture Overview

src/
├── app/           # Next.js App Router pages
├── components/    # React components
│   ├── ui/        # 汎用UIコンポーネント
│   └── features/  # 機能固有コンポーネント
├── lib/           # ユーティリティ、設定
├── hooks/         # カスタムフック
└── types/         # TypeScript型定義

詳細は docs/ARCHITECTURE.md を参照。

Critical Rules

Must Do

  • すべての関数にJSDocコメントを付ける
  • 新機能にはテストを書く
  • PRを出す前に npm run lint と npm run test を実行

Must NOT Do

  • any 型を使わない（unknown を使う）
  • mainブランチに直接コミットしない
  • 環境変数をコードにハードコードしない

Context Files

追加の文脈が必要な場合：

  • 設計詳細: docs/ARCHITECTURE.md
  • セキュリティ: docs/SECURITY.md
  • 進捗: docs/PROGRESS.md
  • 学習ログ: docs/LESSONS.md ← 実装前に必ず確認

### 各セクションの解説

**プロジェクト名と一行説明**

Claudeが最初に見る部分です。プロジェクトの本質を一言で伝えます。これにより、Claudeは「このプロジェクトは何のためのものか」を即座に理解できます。

**Quick Start**

新しいセッションで開発を始めるとき、どのコマンドを実行すれば環境が立ち上がるかを示します。Claudeに「開発サーバーを立ち上げて」と言ったとき、ここを参照して正しいコマンドを実行してくれます。

**Common Commands**

頻繁に使うコマンドを一覧にします。ビルド、テスト、リントなど、プロジェクトで使う基本コマンドを記載します。

**Tech Stack**

使用している技術を列挙します。これにより、Claudeは適切なコードスタイルやパターンを選択できます。「Next.js 15.x (App Router)」と書いてあれば、最新のApp Routerの書き方を使ってくれます。

**Architecture Overview**

ディレクトリ構造の概要を示します。新しいファイルをどこに配置すべきかの判断材料になります。詳細は別ファイルに分離し、参照だけを書きます。

**Critical Rules**

**最も重要なセクション**です。絶対に守るべきルールを、Must Do（やること）とMust NOT Do（やらないこと）に分けて記載します。ルールは5〜7個程度に絞りましょう。多すぎると効果が薄れます。

**Context Files**

より詳細な情報が必要なときに参照すべきファイルを示します。Claudeは必要に応じてこれらのファイルを読みに行きます。

**特に重要なのは `docs/LESSONS.md` です。** ここには過去のセッションでClaudeが犯した方向性ミスと、その修正内容が記録されています。新しい実装を始める前に必ず参照することで、同じミスを繰り返さずに済みます。

---

## CLAUDE.mdは業界標準になりつつある

### 他のAIツールでも採用されている設定ファイル

CLAUDE.mdの「プロジェクトの指示をMarkdownファイルで管理する」というアプローチは、Claude Code独自のものではありません。2025年現在、**主要なAIコーディングツールが同様の仕組みを採用**しています。

| ツール | 設定ファイル | 説明 |
|--------|------------|------|
| **Claude Code** | `CLAUDE.md` | 本書で解説している標準形式 |
| **Gemini Code Assist** | `GEMINI.md` または `AGENT.md` | Googleが公式に推奨。階層的なコンテキスト管理が可能 |
| **GitHub Copilot** | `AGENTS.md`, `CLAUDE.md`, `GEMINI.md` | **複数形式に対応**（2025年8月発表）。`.github/copilot-instructions.md`も併用可能 |
| **Cursor** | `.cursor/rules/*.mdc` | `.cursorrules`（レガシー）から進化。glob指定で条件付き適用可能 |

### 相互運用性のメリット

特筆すべきは、**GitHub Copilotが`CLAUDE.md`と`GEMINI.md`の両方を読み込む**という事実です[（GitHub Changelog, 2025）](https://github.blog/changelog/2025-08-28-copilot-coding-agent-now-supports-agents-md-custom-instructions/)。これは、AIコーディングツール間で「設定ファイルの標準化」が進んでいることを意味します。

**実用的なメリット：**
- **マルチツール対応**: 1つの`CLAUDE.md`を書けば、Claude Code、GitHub Copilot、場合によってはGemini Code Assistでも使える
- **チーム内の柔軟性**: メンバーが異なるAIツールを使っていても、同じプロジェクト指示を共有できる
- **ツール移行コストの削減**: 別のツールに乗り換えても、既存の設定資産を活用できる

### 命名規則の推奨

もし将来的に複数のAIツールを併用する可能性があるなら、以下の命名規則を推奨します：

```bash
# 基本構成
CLAUDE.md          # Claude Code / GitHub Copilot用
GEMINI.md          # Gemini Code Assist / GitHub Copilot用
AGENTS.md          # 汎用的なAI指示（全ツール対応を目指す場合）

# または、共通の指示を1ファイルに
CLAUDE.md          # メインの指示ファイル

筆者の推奨: 現時点ではCLAUDE.mdを使い、必要に応じて他のツール用にシンボリックリンクを作成するアプローチが実用的です。

# CLAUDE.mdを基準に、他ツール用にシンボリックリンクを作成
ln -s CLAUDE.md GEMINI.md
ln -s CLAUDE.md AGENTS.md

これにより、1つのファイルを管理するだけで、複数のAIツールで同じ指示を共有できます。

参考リソース

補完するドキュメント群

CLAUDE.mdだけでは、プロジェクトの全ての情報は伝えられません。以下の補完ドキュメントと組み合わせて使います。

docs/ARCHITECTURE.md

システム設計の詳細を記述するファイルです。

# アーキテクチャ設計書

## システム構成図

[図や説明]

## Frontend Architecture

### コンポーネント設計
- Atomic Designに従う
- 状態管理はReact Query + Zustand
- フォームはReact Hook Form + Zod

### ルーティング設計
- App Router使用
- 動的ルートの命名規則: [id], [slug]

## Backend Architecture

### API設計原則
- RESTful API
- レスポンス形式は統一（{ data, error, meta }）
- エラーコードは4桁（1xxx: 認証, 2xxx: バリデーション...）

### データフロー
1. Request → Middleware → Route Handler
2. Route Handler → Service → Repository
3. Repository → Database

## Database Design

### ER図
[図]

### テーブル定義
[詳細]

### インデックス戦略
[説明]

docs/SECURITY.md

セキュリティに関するガイドラインを記述します。

# セキュリティガイドライン

## 認証・認可

### 認証フロー
- Supabase Auth使用
- JWTトークンはHTTPOnly Cookieに保存
- アクセストークン有効期限: 15分
- リフレッシュトークン有効期限: 7日

### 認可ルール
- Row Level Security (RLS) を使用
- すべてのテーブルにRLSポリシーを設定
- サーバーサイドでも二重チェック

## 入力バリデーション

### 原則
- クライアントサイドとサーバーサイドの両方でバリデーション
- Zodスキーマを共有して一貫性を保つ
- SQLインジェクション対策はORMに任せる

### 実装パターン
[コード例]

## 機密情報の取り扱い

### 環境変数
- `.env.local`は絶対にコミットしない
- 本番環境の環境変数はVercel/Supabaseの設定画面で管理
- シークレットローテーションは四半期ごと

### ログ出力
- パスワード、トークン、個人情報はログに出力しない
- エラーログには最小限の情報のみ含める

docs/PROGRESS.md

プロジェクトの進捗を追跡するファイルです。

# 開発進捗

## 現在のフェーズ
フェーズ2: 認証機能実装

## 完了した機能

### フェーズ1: 基盤構築 ✅
- [x] プロジェクト初期設定
- [x] データベース設計
- [x] 基本的なUI/UXデザイン

### フェーズ2: 認証機能 🚧
- [x] ログイン画面UI
- [x] サインアップ画面UI
- [x] Supabase Auth連携
- [ ] パスワードリセット機能
- [ ] OAuth連携（Google）

## 今日の作業ログ

### 2025-01-16
- パスワードリセット機能の設計完了
- メールテンプレート作成中
- 次回: メール送信テスト

### 2025-01-15
- Supabase Auth連携完了
- ログイン/ログアウトの動作確認OK
- セッション管理の実装完了

## 既知の問題

| ID | 概要 | 優先度 | ステータス |
|----|------|--------|----------|
| #1 | ログアウト後にキャッシュが残る | 高 | 調査中 |
| #2 | モバイルでのレイアウト崩れ | 中 | 未着手 |

## 次のマイルストーン
2025-01-20: フェーズ2完了、認証機能リリース

docs/LESSONS.md（学習ログ）

これは最も重要なドキュメントの一つです。 Claudeが犯した方向性ミスと、その修正内容を記録するファイルです。

なぜこれが重要なのでしょうか？

Claudeは優秀ですが、同じタイプのミスを繰り返す傾向があります。セッション間で記憶を持たないため、あなたが記録しない限り、学習は蓄積されません。LESSONS.mdは、過去のセッションで得た教訓を未来のセッションに引き継ぐ「橋渡し役」です。

# 学習ログ（Lessons Learned）

このファイルには、開発中にClaudeが犯した方向性ミスと、
その修正内容を記録しています。
Claudeは新しいセッションでこのファイルを参照し、
同じミスを繰り返さないようにしてください。

---

## 認証・認可

### 2025-01-15: APIエンドポイントの認証チェック漏れ
**状況**: `/api/users/[id]` エンドポイントを実装した際、
認証チェックなしで実装しようとした。

**問題**: 未認証ユーザーが他人のユーザー情報にアクセスできてしまう。

**正しい実装**:
- すべての `/api/` エンドポイントには `authMiddleware` を適用する
- ユーザー固有のリソースには、所有者チェックも追加する

**参照**: `src/middleware/auth.ts`

---

## データベース操作

### 2025-01-16: 生SQLの使用
**状況**: 複雑なクエリを実装する際、Prismaではなく生SQLを書こうとした。

**問題**: 
- 型安全性が失われる
- SQLインジェクションのリスク
- プロジェクトの一貫性が崩れる

**正しい実装**:
- 複雑なクエリでもPrismaの `$queryRaw` は使わない
- Prismaのリレーションクエリで対応できないか検討する
- どうしても必要な場合は、チームに相談してから実装

---

## コンポーネント設計

### 2025-01-16: 既存ユーティリティの重複実装
**状況**: 日付フォーマット関数を新たに作ろうとした。

**問題**: `src/utils/date.ts` に同様の関数が既に存在していた。

**教訓**: 新しいユーティリティ関数を作る前に、
必ず `src/utils/` ディレクトリを確認すること。

LESSONS.mdは、カテゴリ別（認証、データベース、コンポーネントなど）に整理すると、後から参照しやすくなります。新しいToDoを実装するたびに、関連するカテゴリの過去の教訓をClaudeに読ませる習慣をつけましょう。

ディレクトリ構成のベストプラクティス

プロジェクト全体のディレクトリ構成として、以下を推奨します：

my-project/
├── CLAUDE.md                    # プロジェクトメモリ（必須）
├── CLAUDE.local.md              # 個人設定（.gitignoreに追加）
├── .mcp.json                    # MCP設定
│
├── .claude/
│   ├── settings.json            # Claude Code設定（Hooks等）
│   ├── settings.local.json      # 個人設定（.gitignoreに追加）
│   ├── commands/                # カスタムスラッシュコマンド
│   │   ├── start-feature.md
│   │   └── code-review.md
│   ├── skills/                  # プロジェクト固有スキル
│   │   ├── api-patterns/
│   │   └── testing-strategy/
│   ├── agents/                  # カスタムエージェント
│   │   └── code-reviewer.md
│   └── rules/                   # 条件付きルール
│       ├── api/
│       └── frontend/
│
├── docs/
│   ├── ARCHITECTURE.md          # 設計ドキュメント
│   ├── SECURITY.md              # セキュリティガイドライン
│   ├── PROGRESS.md              # 進捗追跡
│   ├── LESSONS.md               # 学習ログ（方向性ミス記録）
│   └── plans/                   # 計画ファイル
│       └── 2025-01-16-auth.md
│
├── src/                         # ソースコード
└── tests/                       # テストコード

各ディレクトリの役割

.claude/commands/

カスタムスラッシュコマンドを格納します。繰り返し行うタスクをコマンド化することで、効率が上がります。

例：start-feature.md

---
description: 新機能の開発を開始するときの標準手順
---

新機能「$ARGUMENTS」の開発を開始します。

1. 最新のmainブランチをpull
2. feature/$ARGUMENTSブランチを作成
3. docs/plans/に計画ファイルを作成
4. PROGRESS.mdに新機能を追加

上記の手順を実行してください。

使い方：

/project:start-feature ユーザー認証

.claude/rules/

特定のディレクトリやファイルにのみ適用されるルールを格納します。

例：.claude/rules/api/security.md

---
globs: ["src/app/api/**/*.ts"]
---

# API Security Rules

このディレクトリのファイルを編集するときは、以下のルールに従うこと：

1. すべてのエンドポイントで認証チェックを行う
2. 入力値は必ずZodでバリデーション
3. エラーメッセージに内部情報を含めない
4. レート制限の設定を確認する

docs/plans/

第1章で学んだPlanフェーズの成果物を保存します。計画ファイルは日付をファイル名に含め、後から追跡可能にします。

Gitでの管理の重要性

なぜGit管理が必須なのか

CLAUDE.mdや.claude/ディレクトリ内の設定ファイルは、必ずGitで管理してください。

理由は3つあります：

  1. 再現性の確保: Claudeへの指示がコードと一緒にバージョン管理されることで、「あの時点ではどんな指示を出していたか」を追跡できます。バグが発生したとき、コードだけでなく指示の変更履歴も確認できます。

  2. チーム共有: Gitで管理することで、チーム全員が同じ指示をClaudeに共有できます。「自分の環境では動くのに、他の人の環境では違う結果になる」という問題を防げます。

  3. ロールバック: 設定を変更して問題が起きた場合、Gitで簡単に以前の状態に戻せます。特にCLAUDE.mdの変更は影響が大きいため、変更履歴を残すことが重要です。

Git管理すべきファイルとしないファイル

# Git管理すべきファイル（コミットする）
CLAUDE.md                    # プロジェクト共通の指示
.claude/settings.json        # Hooks等の設定（チーム共通）
.claude/commands/            # カスタムスラッシュコマンド
.claude/skills/              # プロジェクト固有スキル
.claude/rules/               # 条件付きルール
docs/LESSONS.md              # 学習ログ

# Git管理しないファイル（.gitignoreに追加）
CLAUDE.local.md              # 個人のプロジェクト固有設定
.claude/settings.local.json  # 個人のHooks設定

.gitignoreへの追加例：

# Claude Code personal settings
CLAUDE.local.md
.claude/settings.local.json

Git管理がもたらす副次的メリット

Git管理は設定ファイルの管理だけでなく、Claude Codeの自動許可設定を安全に使える前提条件でもあります。

第5章で後述しますが、WriteやEditなどのツールを自動許可に設定すると、開発フローが大幅にスムーズになります。「毎回許可ボタンを押す」という手間がなくなるからです。

しかし、「Claudeが勝手にファイルを編集して大丈夫なのか？」という不安もあるでしょう。ここでGit管理が効いてきます：

  • 変更はgit diffで確認できる
  • 問題があればgit restoreで即座に元に戻せる
  • コミット前に全ての変更をレビューできる

Gitで管理している限り、取り返しのつかない状態にはなりません。 自動許可設定の詳細は第5章「おすすめの自動許可コマンド設定」を参照してください。

まとめ：ドキュメントは「投資」

ドキュメントを書くのは面倒に感じるかもしれません。しかし、Claude Codeを使った開発では、ドキュメントへの投資は何倍にもなって返ってきます。

人間のチームメンバーなら、一度説明すれば覚えてくれます。しかしClaudeは、セッションごとに記憶がリセットされます。ドキュメントがなければ、毎回同じ説明をする必要があります。

逆に、良いドキュメントがあれば、Claudeは初回から「このプロジェクトを熟知したエンジニア」のように振る舞えます。あなたの開発効率は飛躍的に向上するでしょう。

次の章では、さらに開発効率を高めるSKILLSシステムについて学びます。AIに専門知識を教え込み、必要なときに自動で参照させる仕組みを理解しましょう。

この記事をシェア
📚Claude Code × Vibe Coding 体系的教科書(3/6)
前の記事
2. Claude Code × Vibe Coding #2：公式推奨ワークフロー「Explore → Plan → Code → Commit」
次の記事
4. Claude Code × Vibe Coding #4：SKILLSアプローチ ― AIに専門知識を与える
シリーズ一覧を見る
記事一覧に戻る