Claude Codeの効果を最大化するCLAUDE.mdの設計方法を解説。セッション間で知識を引き継ぎ、プロジェクトのルール理解を実現する配置場所、優先度、ベストプラクティスを20年の開発経験から紹介します。
AIコーディングアシスタントをチームに導入したけれど、期待通りの効果が出ない
Claude Codeを使い始めた多くの開発チームが直面する共通の課題があります：
- 「Claudeが毎回同じ質問をしてくる」
- 「プロジェクトのルールを理解してくれない」
- 「セッションを切り替えるたびに説明が必要」
- 「チームメンバーによってClaudeの使い方がバラバラ」
これらの問題の根本原因は、CLAUDE.mdファイルの設計にあります。適切に設計されたCLAUDE.mdは、AIアシスタントを単なるツールから、プロジェクトを深く理解する開発パートナーに変えてくれます。
弊社Fivenine Designでは、20年以上のWeb開発経験を活かし、複数のプロジェクトでClaude Codeを活用してきました。その中で得られた知見をもとに、CLAUDE.mdの効果的な設計方法をお伝えします。
CLAUDE.mdとは何か：AIとの協働を支える設計図
CLAUDE.mdは、Claude Codeがセッション開始時に自動的に読み込むMarkdownファイルです。プロジェクト固有の指示、ルール、ワークフローを定義することで、毎回のセッションでClaudeがプロジェクトの文脈を理解できるようになります。
なぜCLAUDE.mdが重要なのか
Claude Codeの各セッションは新しいコンテキストで始まります。つまり、前回のやり取りは記憶されていません。CLAUDE.mdは、この制約を解決する「セッション間で知識を引き継ぐ仕組み」として機能します。
注意点：CLAUDE.mdは強制的な設定ではなく、コンテキストとして読み込まれます。Claudeの行動をガイドしますが、完全にコントロールするものではありません。
配置場所とスコープの理解：適切な場所に適切なルールを
CLAUDE.mdの効果を最大化するには、適切な場所に配置することが重要です。以下の3つの階層があります：
# macOS
/Library/Application Support/ClaudeCode/CLAUDE.md
# Linux
/etc/claude-code/CLAUDE.md
用途：IT管理者による組織全体のポリシー 対象：全社員、全プロジェクト
読み込み順序と優先度
Claude Codeは以下の順序でCLAUDE.mdを読み込みます：
flowchart TD
A[セッション開始] --> B[作業ディレクトリから上方向へ探索]
B --> C[各階層のCLAUDE.mdを読み込み]
C --> D[ユーザーレベルのルール適用]
D --> E[プロジェクトレベルのルール適用]
E --> F[より具体的な場所が優先]
重要：サブディレクトリのCLAUDE.mdはオンデマンドで読み込まれます（そのディレクトリのファイルにアクセスした時のみ）。
何を書くべきか、何を書くべきでないか：効果的なルール設計
適切なCLAUDE.mdを書くには、「書くべきこと」と「書くべきでないこと」を明確に区別する必要があります。
書くべき内容
| カテゴリ | 具体例 | 理由 |
|---|---|---|
| ビルド・テスト手順 | npm run build, pytest tests/ | Claudeが推測できない |
| コードスタイル | 2スペースインデント、セミコロン必須 | デフォルトと異なる場合 |
| リポジトリルール | ブランチ名: feature/JIRA-123 | プロジェクト固有の慣習 |
| 環境固有の設定 | NODE_ENV=development必須 | 特殊な環境変数 |
# プロジェクト固有のルール例
## ビルドとテスト
- ビルド: `npm run build:production`
- テスト実行: `npm test -- --coverage`
- E2Eテスト: `npm run test:e2e`
## コードスタイル
- インデント: 2スペース（タブ禁止）
- 文字列: シングルクォート推奨
- セミコロン: 必須
## ブランチ戦略
- 機能開発: `feature/JIRA-{チケット番号}`
- バグ修正: `bugfix/JIRA-{チケット番号}`
- マージ前に必ずPull Request作成
書くべきでない内容
- コードを読めば分かること：ファイル構造の詳細説明
- 標準的な言語慣習：「変数名はcamelCaseで」
- 頻繁に変わる情報：APIのエンドポイントURL
- 長い説明やチュートリアル：詳細なAPIドキュメント
- 自明な指示：「クリーンなコードを書け」
サイズと構造の最適化：読みやすく、従いやすいルール作り
理想的なサイズ
- 1ファイルあたり200行以内を目標
- 長すぎるとコンテキストを消費し、遵守率が下がる
- 各行について「これを削除したらClaudeがミスするか？」と自問し、NOなら削除
効果的な構造化
# CLAUDE.md の推奨構造
## プロジェクト概要
- 簡潔な目的と技術スタック
## 開発環境
- 必須環境変数
- 起動手順
## コーディング規約
- 言語固有のルール
- フォーマッター設定
## テストとデプロイ
- テスト実行方法
- デプロイフロー
## よくあるハマりポイント
- 環境固有の問題
- 非自明な動作
具体的な書き方のコツ
検証可能な具体的指示を書く：
| 良い例 | 悪い例 | 理由 |
|---|---|---|
| Use 2-space indentation | Format code properly | 具体的で検証可能 |
| Run npm test before committing | Test your changes | 実行可能なコマンド |
| IMPORTANT: Always validate API responses | Be careful with APIs | 重要度を明示 |
遵守率を上げるテクニック：
IMPORTANTやYOU MUSTで重要なルールを強調- 矛盾するルールは避ける（Claudeが恣意的に選択してしまう）
大規模プロジェクトでの分割管理：.claude/rules/の活用
大きなプロジェクトでは、指示を複数ファイルに分割することで管理しやすくなります。
ファイル分割の例
.claude/
├── CLAUDE.md # 基本ルール
├── rules/
│ ├── testing.md # テスト関連
│ ├── api-design.md # API設計
│ ├── frontend.md # フロントエンド
│ └── backend.md # バックエンド
└── skills/ # タスク固有の知識
├── database.md
└── deployment.md
pathsフィールドでスコープ限定
特定のファイルにのみ適用したいルールは、YAMLフロントマターを使用：
---
paths: ["src/api/**/*.ts"]
---
# API設計ルール
- レスポンスは必ずHTTPステータスコードに準拠
- エラーレスポンスには必ずerror_codeを含める
設定ファイルとの使い分け：適切なツールで適切な制御
| 項目 | settings.json | CLAUDE.md |
|---|---|---|
| 目的 | 技術的な強制 | 行動のガイダンス |
| 制御方法 | クライアントが強制 | Claudeの行動を形作る |
| 適用範囲 | 権限制御、環境変数 | コードスタイル、ワークフロー |
| 変更頻度 | 低い | 中程度 |
実際の使い分け例
settings.json：
{
"sandbox_mode": true,
"allowed_commands": ["npm", "git", "pytest"],
"environment_variables": {
"NODE_ENV": "development"
}
}
CLAUDE.md：
## 開発ワークフロー
IMPORTANT: 以下の順序で作業を進めてください：
1. テストを先に書く（TDD）
2. 実装を行う
3. `npm test`でテスト実行
4. `npm run lint`でコードチェック
便利な機能：@import構文と/initコマンド
@import構文
CLAUDE.mdから他のファイルをインポートできます：
# メインのCLAUDE.md
## 基本ルール
@import README.md
@import docs/git-instructions.md
## プロジェクト固有ルール
- 独自のルールをここに記載
制限事項：
- 再帰インポートは最大5段階
- 循環インポートは避ける
/initコマンド
コードベースを分析してCLAUDE.mdの初期版を自動生成：
# Claude Code内で実行
/init
- 既存CLAUDE.mdがあれば上書きせず改善提案を生成
- プロジェクトの構造を分析して適切なルールを提案
運用のベストプラクティス：チーム全体での改善サイクル
Git管理と継続的改善
# CLAUDE.mdをバージョン管理に含める
git add CLAUDE.md .claude/
git commit -m "Update CLAUDE.md: Add API testing guidelines"
運用のポイント：
- CLAUDE.mdもコードと同様に扱う
- 問題が起きたらレビューし、改善する
- 定期的に不要なルールを刈り込む
よくある問題と対処法
**対処**：重要なルールを上部に移動、不要なルールを削除
**対処**：具体的で検証可能な表現に変更
**対処**：プロジェクトレベルでより具体的なルールを定義
実際の運用事例：弊社での活用実績
弊社では、Laravel、WordPress、Next.jsを使った20以上のプロジェクトでClaude Codeを活用しています。
成功事例：ECサイトリニューアルプロジェクト
課題：
- 複数の開発者が参加
- レガシーコードとの共存
- 厳格なコーディング規約
CLAUDE.md設計のポイント：
## レガシーコード対応
IMPORTANT: legacy/フォルダ内のファイルは以下のルールで対応
- 既存コードスタイルを維持
- 新機能のみ新しい規約を適用
- データベース変更は必ずmigrationファイルを作成
## テスト戦略
- 新機能: 100%カバレッジ必須
- レガシー機能: 変更部分のみテスト追加
- E2Eテスト: 購入フローは必須
結果：
- コードレビュー時間が40%短縮
- バグ発生率が30%減少
- チーム間のコーディングスタイルが統一
アンチパターン：避けるべき設計
よくある失敗パターン
| アンチパターン | 問題点 | 改善方法 |
|---|---|---|
| 肥大化したCLAUDE.md | 重要なルールが埋もれる | ファイル分割、不要ルール削除 |
| コードの詳細説明 | メンテナンス負荷増大 | リンクや@importで参照 |
| 頻繁に変わる情報 | 常に古い情報になる | 外部ドキュメントへの参照 |
| 矛盾するルール | Claudeが混乱する | ルール間の整合性チェック |
実際の失敗例
失敗例1：詳細すぎるAPIドキュメント
# 悪い例
## API仕様
- GET /api/users - ユーザー一覧取得
- レスポンス: {id: number, name: string, email: string...}
- POST /api/users - ユーザー作成
- リクエスト: {name: string, email: string...}
# （200行続く...）
改善版：
# 良い例
## API設計
- OpenAPI仕様書: @docs/api-spec.yaml
- 認証: JWT Bearer Token必須
- エラーハンドリング: RFC 7807準拠
このAI技術、御社の業務にも導入できます
AI導入・業務自動化
ChatGPT活用や業務自動化など、最新のAI技術を御社に合わせてご提案します
※ 通常1営業日以内にご返信します
まとめ：効果的なCLAUDE.mdでAI開発を加速する
CLAUDE.mdの適切な設計は、AIアシスタントとの協働を劇的に改善します。重要なポイントを振り返ってみましょう：
成功の鍵：
- 具体性：検証可能で実行可能なルール
- 適切なサイズ：200行以内、重要なルールを上部に
- 継続的改善：コードと同様にレビューと改善を継続
- チーム運用：Git管理で全員が改善に参加
適切に設計されたCLAUDE.mdは、AI支援開発の効果を最大化し、チーム全体の生産性を向上させます。まずは小さく始めて、実際の開発体験を通じて継続的に改善していくことが成功の秘訣です。
Claude Codeの導入やCLAUDE.mdの設計でお困りの際は、20年以上のWeb開発経験を持つ弊社にお気軽にご相談ください。プロジェクトの特性に合わせた最適なAI開発環境の構築をサポートいたします。
