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

Claude Codeで快適に仕事を進めるうえで、CLAUDE.mdの出来は体験を大きく左右します。CLAUDE.mdとは、Claude Codeが起動時に自動で読み込む指示書ファイルのことで、プロジェクトのルール・よく使うコマンド・してほしくないことを、あらかじめAIに伝えておけます。この記事では、海外の開発者が公開している実際のCLAUDE.mdを題材に、構成のパターン、記述の粒度、陥りがちなアンチパターン（やってはいけない書き方）を具体例とともに紹介します。読み終える頃には、自分のプロジェクトに合うCLAUDE.mdを組み立てる感覚がつかめるはずです。

この記事は実例集です。基本の書き方を体系的に知りたい方はCLAUDE.mdの書き方: 生産性を10倍にする設計パターン、個人設定・プロジェクト設定・モジュール設定の使い分けはCLAUDE.md 3階層設計: グローバル/プロジェクト/モジュールの使い分けで詳しく解説しているので、あわせて読むと理解が立体的になります。

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

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

CLAUDE.mdはClaude Codeが起動時に自動で読み込むメモリファイルで、プロジェクトのルール・コマンド・構造をAIに伝える常駐コンテキスト（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（JavaScriptのパッケージ管理ツール）を試行錯誤しがちで、トークン（AIの処理量の単位）も時間も浪費します。

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

大規模リポジトリでは、ディレクトリ構造を簡潔に図示する派が多く見られます。モノレポとは、複数のアプリやツールを1つのリポジトリでまとめて管理する構成のことです。以下は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階層までという制約があるので注意してください。

非エンジニアはまず何を書くか: 3ステップ

ここまでの事例はソフトウェア開発の現場のものですが、CLAUDE.mdの考え方そのものは、経理・総務・マーケティングといった非エンジニアの仕事でもそのまま使えます。CLAUDE.mdの実体は、新しく入ったアシスタントに渡す仕事の手順書と同じだからです。プログラミングの知識は要りません。次の3ステップで最初の1枚を作れます。

  1. 仕事の前提を3行で書く。業種・職種、よく扱うファイル（例: Excelの売上データ、Wordの報告書）、成果物の置き場所（フォルダ名）を書きます。
  2. 成果物のルールを箇条書きにする。文体（です・ます調）、ファイル名の付け方（例: 日付_案件名）、日付や金額の表記ルールなどです。
  3. してほしくないことを書く。元データを直接書き換えない、指示していないファイルを作らない、社外秘の情報を外部に送らない、といった禁止事項です。

たたき台づくり自体もClaudeに任せられます。次のプロンプトを貼り付けて、【 】の中を自分の状況に書き換えてください。

自分の仕事に合ったCLAUDE.mdのたたき台を作る 
私は【業種と規模: 例・10人規模の会計事務所】で働いており、Claude Codeを【主な用途: 例・月次資料の集計と報告書の下書き】に使う予定です。
よく扱うファイルは【例: Excelの売上データ、PDFの請求書】です。
この前提で、CLAUDE.mdのたたき台を作ってください。条件は次の通りです。
・見出しは「前提」「成果物のルール」「してほしくないこと」の3つ
・各見出しの下は3〜5行の箇条書き
・専門用語を使わない
・全体で30行以内
最後に、私が追記したほうがよい項目があれば、質問の形で挙げてください。
Claude Code自体をこれから始める方は、導入から最初の自動化までをClaude Code 使い方 完全ガイド2026で確認できます。また、当サイトの機能逆引き辞典ではCLAUDE.mdを含む機能を「やりたいこと」から逆引きできるので、用語で迷ったときに使ってください。

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

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

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

まとめ

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

実際に稼働している設定ファイル一式を手元で見たい方には、CLAUDE.md・エージェント定義・フックをセットにした教材ライブラリを見るを無料で配布しています。この記事の事例と見比べながら、自分の1枚に写し取ってください。