CLAUDE.mdとREADME.mdの違いは何ですか？

README.mdは人間の開発者向けのプロジェクト説明文書で、CLAUDE.mdはClaude Code（AI）向けの指示ファイルです。記述の粒度や語彙が異なり、CLAUDE.mdにはコマンド・禁止事項・ワークフローなどAIの行動を制御する具体的なルールを書きます。

CLAUDE.mdはどこに置けばいいですか？

Anthropic公式は3階層を推奨しています。ホームディレクトリの~/.claude/CLAUDE.mdに個人設定、プロジェクトルートのCLAUDE.mdにチーム共有ルール、CLAUDE.local.mdに個人用のローカル設定を置き、local.mdはgitignoreに含めます。

CLAUDE.mdが長くなりすぎた場合はどうすればいいですか？

@import機能で領域別のルールファイルに分割できます。例えばTypeScript規約やテスト方針を別ファイルに切り出し、CLAUDE.md本体は薄く保つのがベストプラクティスです。ただし深さ5階層までの制限があります。

海外のCLAUDE.md事例ギャラリー: 設定の極意を学ぶ

Claude Codeで快適に開発するうえで、CLAUDE.mdの出来は体験を大きく左右する。この記事では、海外エンジニアが公開している実際のCLAUDE.mdを題材に、構成のパターン、記述の粒度、陥りがちなアンチパターンを具体例とともに紹介する。読み終えた頃には、自分のプロジェクトに合うCLAUDE.mdを組み立てる感覚が掴めるはずだ。

参照元は主にAnthropic公式ドキュメント（Manage Claude's memory）、コミュニティリポジトリ hesreallyhim/awesome-claude-code、および個人開発者の公開リポジトリである。

なぜCLAUDE.mdが「設定の極意」なのか

CLAUDE.mdはClaude Codeが起動時に自動で読み込むメモリファイルで、プロジェクトのルール・コマンド・構造をAIに伝える唯一の常駐コンテキストである。海外コミュニティでは「prompt as code」と呼ばれ、READMEと並ぶ第一級のドキュメントとして扱われている。

Anthropic公式は3階層のメモリを推奨している。

~/.claude/CLAUDE.md         # ユーザー全体（個人の好み）
<project>/CLAUDE.md         # プロジェクト共有（チーム全員）
<project>/CLAUDE.local.md   # プロジェクト個人（gitignore対象）

この分離を徹底するだけで、「個人の癖」と「チームの規約」が混ざらず、レビュー時にも読みやすいCLAUDE.mdが維持できる。

事例1: ミニマル派（Anthropic公式テンプレート）

Anthropicのclaude-code-actionリポジトリのCLAUDE.mdは驚くほど短い。要点だけを箇条書きで列挙し、AIに「迷い」を与えない構成だ。

# Project: Claude Code Action

## Commands
- Build: `bun run build`
- Test: `bun test`
- Lint: `bun run lint`
- Format: `bun run format`

## Code Style
- Use TypeScript strict mode
- Prefer functional patterns over classes
- No default exports

## Testing
- Co-locate tests as `*.test.ts`
- Use `bun:test`, not jest

ポイントは**「コマンドを最初に書く」**こと。Claude Codeはbun run buildと書かれていればnpm run buildを試さない。逆にコマンドが書かれていないと、AIは推測でnpm/yarn/pnpmを試行錯誤しがちで、トークンも時間も浪費する。

事例2: 構造説明派（大規模モノレポ）

大規模リポジトリでは、ディレクトリ構造を簡潔に図示する派が多い。以下はTypeScript製OSSで頻出するパターンを再構成したものだ。

## Architecture

src/ core/ # Pure domain logic, no IO adapters/ # DB, HTTP, filesystem boundaries api/ # Route handlers (thin) cli/ # Commander entrypoints tests/ unit/ # Mirrors src/ structure e2e/ # Playwright specs


## Boundaries
- `core/` must not import from `adapters/` or `api/`
- `adapters/` exposes interfaces only; implementations stay private
- New routes go in `api/` and call `core/` use-cases

ここで注目したいのは「禁止事項を明示する」点だ。core/がadapters/をimportしてはいけないという制約は、コードを読んだだけではAIには伝わりづらい。文章で先に宣言しておくことで、Claudeは誤った依存方向のコードを書かなくなる。

事例3: ワークフロー派（テスト駆動を強制）

TDDを徹底している開発者のCLAUDE.mdには、AIの行動順序そのものを書き込む例が多い。

## Workflow Rules

When fixing a bug:
1. First, write a failing test that reproduces the bug
2. Run the test to confirm it fails (RED)
3. Implement the minimal fix
4. Run the test to confirm it passes (GREEN)
5. Run the full suite before committing

When adding a feature:
1. Propose a 3-line plan and wait for approval
2. Write tests first based on the agreed interface
3. Implement until tests pass
4. Never create files outside the agreed plan

この種の指示は、Claude Codeの「思考の流れ」を制御する効果が大きい。特にNever create files outside the agreed planのような禁止形は、AIの過剰な親切心（勝手にREADMEやutilを作る挙動）を抑制するのに有効だと、awesome-claude-codeのIssueでも繰り返し報告されている。

事例4: コンテキスト節約派（@import活用）

Claude CodeはCLAUDE.md内で@path/to/file.mdと書くと、そのファイルを再帰的に取り込む。海外の上級者はこれを使ってメインのCLAUDE.mdを薄く保ち、領域別のルールを分割している。

# Project Memory

@docs/conventions/typescript.md
@docs/conventions/testing.md
@docs/conventions/git.md

## Project-specific
- Database: PostgreSQL via Prisma
- Auth: Clerk
- Deploy: Fly.io

利点は二つある。第一に、共通ルールを複数プロジェクトで使い回せる。第二に、CLAUDE.md本体が短く保たれるため、レビューしやすい。ただし@importは深さ5階層までという制約があるので注意が必要だ。

アンチパターン: やりがちな失敗

海外コミュニティで「これはやめたほうがいい」と頻繁に挙がるパターンを紹介する。

長文の哲学を書く: 「我々のチームはクリーンコードを愛する」のような抽象論はトークンを消費するだけで行動を変えない。
コマンドの羅列だけで意図を書かない: npm run build:prodがなぜ存在するのかを書かないと、AIはbuildとの違いを判断できない。
READMEのコピペ: READMEは人間向け、CLAUDE.mdはAI向け。粒度と語彙が違う。
頻繁に更新される情報を埋め込む: スプリント番号や担当者名はCLAUDE.local.mdに逃がすのが推奨されている。
「丁寧に書いてください」のような曖昧な指示: 評価基準が定義できない指示は、ほぼ無視される。

まとめ

海外の優れたCLAUDE.mdに共通するのは、コマンド・境界・禁止事項を最短文で書くという姿勢だ。長く書けば賢くなるわけではなく、むしろ短く具体的なルールほど効く。まずはミニマル派のテンプレートから始め、プロジェクト固有の制約が見えてきたら境界やワークフローを足していくのが、無理のない育て方である。@importで共通規約を分離する手法は、複数プロジェクトを抱える日本のエンジニアにも特に相性が良い。今日から自分のCLAUDE.mdを見直して、不要な行を1行削るところから始めてみてほしい。