対象CLAUDE.md設計を学びたい開発者

達成目標最適なプロジェクト構成を設計できる

前提知識Getting Started完了

所要時間20分

プロジェクト構成設計

Claude Codeが認識するファイル・フォルダの全体像と、最適な構成設計パターン。CLAUDE.md、.claude/ディレクトリ、Progressive Disclosure、モノレポ戦略まで網羅します。

全体ファイルマップ

Claude Codeが認識するファイル・フォルダの一覧です。プロジェクトルートに以下の構造を意識して配置します。

your-project/
├── CLAUDE.md                    ← プロジェクトの「脳」（常時ロード）
├── .claude/
│   ├── settings.json            ← 権限・許可設定
│   ├── settings.local.json      ← ローカル設定（.gitignore推奨）
│   ├── commands/                ← カスタムスラッシュコマンド
│   ├── skills/                  ← プロジェクト固有スキル
│   └── rules/                   ← ルール分割（Progressive Disclosure）
├── .claudeignore                ← 除外ファイル設定
├── .mcp.json                    ← MCP設定
├── docs/
│   ├── plans/                   ← 設計書・実装プラン
│   └── architecture/            ← アーキテクチャ文書
├── lessons.md                   ← Self-Improvement Loop
└── src/                         ← アプリケーションコード

📝 Note

Claude Codeは起動時にCLAUDE.mdを自動読み込みします。.claude/配下のファイルも設定として認識されます。

CLAUDE.md設計

長さルール

公式推奨は200行以内。理想は短いほど良い（80-120行が実用的な目安）。それ以上になると情報が希釈され、Claudeの行動精度が低下します。

「IMPORTANT」「YOU MUST」などの強調表現を使うと、Claudeの遵守率が上がります。

Boris Cherny流テンプレート

Claude Code開発者Boris Chernyが推奨する構成テンプレートです。

CLAUDE.md

# Project: [プロジェクト名]

## Overview
[プロジェクトの目的を1-2行で]

## Core Principles
- Simplicity First: 最もシンプルな解決策を選ぶ
- Minimal Impact: 変更は最小限に
- Plan Before Code: 常にPlan Modeから始める

## Coding Standards
- MUST: テストを書いてから実装する
- MUST: 既存のコードパターンに従う
- NEVER: 本番DBを直接操作しない
- NEVER: --no-verify でコミットしない

## Workflow
Default: Plan Mode → 設計確認 → Normal Mode → 実装
Test: TDD (Red → Green → Refactor)

## Key Files
- src/app/ - メインアプリケーション
- tests/ - テストファイル
- docs/plans/ - 設計書

## Gotchas
- [過去の失敗や注意点を追記する場所]

MUST/NEVERパターン

曖昧な表現を避け、MUST（必須）/ NEVER（禁止）で明確にルール化します。Claudeはこれらの強い言葉をより確実に遵守します。

パターン	悪い例	良い例
`MUST`	テストを書くのが望ましい	MUST: テストを書いてから実装する
`NEVER`	本番DBには注意する	NEVER: 本番DBを直接操作しない
`MUST`	できればPlan Modeで始める	MUST: 常にPlan Modeから始める

Plan Mode Default宣言

ワークフローセクションで「Default: Plan Mode」と明記することで、Claudeは常に計画フェーズから開始します。いきなりコードを書き始める事故を防ぐ重要なパターンです。

✅ Tip

CLAUDE.mdの長さは最重要ルールです。長すぎると情報が希釈され、Claudeの行動精度が下がります。ルールが増えたら.claude/rules/に分割しましょう。

他ファイルの参照（@import）

CLAUDE.mdから他のファイルを参照できます。@プレフィックスでファイルパスを指定すると、Claudeがそのファイルの内容を読み込みます。

CLAUDE.md 内の@import例

See @README.md for project overview.
- Git workflow: @docs/git-instructions.md
- Personal overrides: @~/.claude/my-project-instructions.md

相対パスはインポート元ファイルからの相対で解決される
最大5ホップの再帰的インポートに対応

.claude/ ディレクトリ

.claude/ ディレクトリはClaude Codeの設定と拡張機能を管理するフォルダです。

settings.json — 権限設定

Claude Codeが実行できる操作の許可・拒否を定義します。

.claude/settings.json

{
  "permissions": {
    "allow": ["Read", "Glob", "Grep", "Write", "Edit"],
    "deny": ["rm -rf", "git push --force", "DROP TABLE", "DELETE FROM"]
  }
}

settings.local.json — ローカル固有設定

APIキー参照やローカル環境固有の設定を格納します。チーム共有する必要がないため、.gitignoreに追加してリポジトリから除外します。

commands/ — カスタムスラッシュコマンド

/review、/fix 等のショートカットコマンドを定義できます。よく使うワークフローをコマンド化することで、操作の統一と効率化が実現できます。

skills/ — プロジェクト固有スキル

SKILL.md形式でプロジェクト固有のスキルを定義します。デプロイ手順、コードレビュー基準など、プロジェクト特有の知識をスキルとして体系化できます。

.claude/rules/ フォルダ

Progressive Disclosure

CLAUDE.mdに全ルールを書く代わりに、カテゴリ別にルールファイルを分割する手法です。CLAUDE.mdを短く保ちながら、必要な時に詳細ルールを参照できます。

.claude/rules/
├── security.md      ← セキュリティ関連ルール
├── testing.md       ← テスト規約
├── git-workflow.md  ← Gitルール
└── api-design.md    ← API設計規約

各ファイルは必要な時にClaudeが参照する
CLAUDE.mdには「詳細は.claude/rules/を参照」と書く
ルールファイルはカテゴリごとに分けることで、メンテナンス性が向上する

📝 Note

Progressive Disclosureにより、CLAUDE.mdは80行以内に保ちつつ、必要な時に詳細ルールを読み込むことができます。

パス固有のルール

globパターン（**/*.ts, src/**/*, *.{ts,tsx}）で特定のファイルにのみ適用されるルールを設定できます。ルールファイルの先頭にYAMLフロントマターで対象パスを指定します。

.claude/rules/api-rules.md

---
paths:
  - "src/api/**/*.ts"
---
# API開発ルール
- すべてのAPIエンドポイントに入力バリデーションを含める

.claudeignore

.gitignoreと同じ構文で、Claude Codeが読み込まないファイル・ディレクトリを指定します。不要なファイルを除外することで、コンテキストの消費を最小化できます。

.claudeignore

# 依存関係
node_modules/
vendor/
.venv/

# ビルド出力
dist/
build/
.next/

# 機密情報
.env
.env.local
*.pem
credentials.json

# バージョン管理
.git/

# 大きなファイル
*.zip
*.tar.gz
*.mp4

⚠️ Warning

モノレポでは.claudeignoreが必須です。設定しないとコンテキストが巨大になり、パフォーマンスが即死します。

docs/ 設計ドキュメント

CLAUDE.mdには概要だけ書き、詳細な設計情報はdocs/ディレクトリに分離します。

docs/plans/ — 設計書・実装プラン

日付プレフィックス付きのファイル名で管理します。例: YYYY-MM-DD-feature-name.md

docs/architecture/ — システム構成図

システム構成図、データフロー図などの技術ドキュメントを格納します。

CLAUDE.mdからの参照パターン

CLAUDE.mdでは概要のみを記載し、詳細はdocs/への参照リンクを書きます。

CLAUDE.md 内の参照例

## Architecture
See docs/architecture/system-overview.md for details.

## Current Plans
See docs/plans/ for active implementation plans.

✅ Tip

CLAUDE.mdには概要だけ書き、詳細はdocs/に分離する。これがProgressive Disclosureの実践です。

lessons.md

Self-Improvement Loopを実践するための記録ファイルです。Claudeがミスしたパターンや気づきを蓄積し、プロジェクトのルールへと昇格させていきます。

lessons.md

# Lessons Learned

## 2026-03-21
- Claude がテストなしで実装を進めた → CLAUDE.md に「MUST: テストを書いてから実装する」を追加
- 大きなPRを一度に作ろうとした → 「1PR = 1機能」ルールを追加

## 2026-03-20
- .envファイルをコミットしそうになった → PreToolUse hookでシークレットチェックを追加

運用サイクル

記録
タスク完了後、気づきを lessons.md に追記する
昇格
パターンが見えたら CLAUDE.md のルールに昇格させる
自動化
確実に守るべきルールは Hooks に移行して強制力を持たせる

📝 Note

Boris Cherny流: 「Claudeがミスしたら、次は同じミスをしないようCLAUDE.mdにルールを追加する」。これがSelf-Improvement Loopです。

自動メモリシステム

Claude Codeは会話を跨いで情報を保持する自動メモリシステムを備えています。

保存場所: ~/.claude/projects/ 配下にプロジェクトごとのメモリが保存される
インデックス: MEMORY.md がインデックスファイルとして機能する
保存単位: 自動メモリはワーキングツリー（working tree）ごとに保存される
ロード制限: 最初の200行のみがセッションにロードされる

メモリタイプ

タイプ	用途	例
`user`	ユーザー情報	開発者の好み、使用言語
`feedback`	フィードバック	過去の修正指示、改善要望
`project`	プロジェクト情報	アーキテクチャ決定事項、技術選定
`reference`	外部参照	API仕様、ドキュメントURL

メモリは会話を跨いで情報が保持されるため、同じプロジェクトで繰り返し説明する必要がなくなります。

モノレポ戦略

モノレポ（複数パッケージを1リポジトリで管理）ではCLAUDE.mdを階層的に配置します。

monorepo/
├── CLAUDE.md                  ← 全体共通ルール
├── .claudeignore              ← 全体除外設定
├── packages/
│   ├── frontend/
│   │   ├── CLAUDE.md          ← フロントエンド固有ルール
│   │   └── .claudeignore
│   ├── backend/
│   │   ├── CLAUDE.md          ← バックエンド固有ルール
│   │   └── .claudeignore
│   └── shared/
│       └── CLAUDE.md

ルートCLAUDE.mdには全体共通のルールのみを記述
各パッケージのCLAUDE.mdにはそのパッケージ固有のルールを記述
サブディレクトリのCLAUDE.mdはルートのCLAUDE.mdを補完する（上書きではない）

✅ Tip

モノレポでは各パッケージに.claudeignoreを配置し、関係ないパッケージのファイルがコンテキストに含まれないようにすることが重要です。

良い構成例・悪い構成例

プロジェクト構成の典型的なBefore/Afterを比較します。

Before（悪い構成）

CLAUDE.mdが300行以上
.claudeignoreなし
全ルールをCLAUDE.mdに詰め込み
docs/なし、設計がどこにもない
lessons.mdなし

After（良い構成）

CLAUDE.mdは100行以内
.claudeignoreでノイズ除去
.claude/rules/でルール分割
docs/plans/に設計書
lessons.mdでSelf-Improvement Loop

⚠️ Warning

「全部CLAUDE.mdに書く」は最も多い初心者の失敗です。200行を超えたら必ず分割を検討してください。

.gitignore設計

Claude Code関連のファイルで、何をコミットし何を除外すべきかを整理します。

コミットするもの

ファイル	理由
`CLAUDE.md`	プロジェクトの共通ルール。チーム全員で共有
`.claude/commands/`	カスタムコマンドはチームで統一すべき
`.claude/skills/`	プロジェクト固有スキルの共有
`.claude/rules/`	分割ルールの共有
`.claudeignore`	除外設定の統一
`.mcp.json`	MCP設定の共有
`lessons.md`	チーム全体の学びの蓄積

除外するもの (.gitignoreに追加)

ファイル	理由
`.claude/settings.local.json`	ローカル固有の設定・APIキー参照
`.claude/projects/`	自動メモリ（個人の会話履歴）
`.firecrawl/`	スクレイピングキャッシュ

.gitignore に追加する行

# Claude Code - ローカル設定
.claude/settings.local.json
.claude/projects/
.firecrawl/

← 前のページ

Getting Started

判断フレームワーク