CLAUDE.mdの書き方: 2026年版完全ガイド

Claude Codeを使っているなら、今すぐできる最もインパクトの大きなことのひとつが、良いCLAUDE.mdファイルを書くことだ。これはコードベース向けのシステムプロンプトだ。Claude Codeがプロジェクトを開く度にCLAUDE.mdを最初に読み、その後の全ての作業がそこで見つけた内容に影響される。

このガイドでは、CLAUDE.mdとは何か、なぜ重要なのか、どう構成するか、そして優れたOSSプロジェクトがどんなパターンを使っているかを解説する。全ての例は実際のリポジトリから来ている。

CLAUDE.mdとは？

CLAUDE.mdはリポジトリのルート（またはサブディレクトリ）に置くMarkdownファイルで、Claude Codeにプロジェクトについての永続的な指示を提供する。人間の開発者向けではなく、AIコーディングアシスタント向けに書かれたREADMEだと思えばいい。

CLAUDE.mdファイルを含むディレクトリでClaude Codeを起動すると、Claudeはセッション開始時に自動でそれを読む。消えてしまう会話コンテキストと違い、CLAUDE.mdは永続する。常にそこにあり、常に読み込まれ、常にClaudeの動作に影響している。

AnthropicはCLAUDE.mdをClaude Codeのエージェント型コーディングワークフローの一部として導入した。それ以来、.cursorrulesやAGENTS.mdと並んでAIコーディング設定の最も広く採用された標準のひとつになっている。

CLAUDE.mdが重要な理由

CLAUDE.mdなしでは、Claude Codeはプロジェクトについて合理的な推測をする。あれば、正確な規約に従い、不要なパターンを避け、最初から自分のコードベースに合ったコードを生成できる。

しっかり書かれたCLAUDE.mdが除去するもの：

繰り返しの修正。 「シングルクォートを使って」「クラスを使わないで」と何度も言うなら、それはCLAUDE.mdに書くべきだ。
スタイルの不一致。 フォーマット規約、命名パターン、インポート順序をCLAUDE.mdで指定すればClaudeが自動で従う。
間違ったアーキテクチャの決定。 好みのパターン（例：クライアントコンポーネントよりサーバーコンポーネント）を伝えれば、それをデフォルトにする。
コンテキストウィンドウの無駄。 毎セッション同じプロジェクトの説明を繰り返す代わりに、CLAUDE.mdが一度で全て処理する。

Vercel Next.jsのCLAUDE.md（138Kスター）が完璧な例だ。モノレポ構造から優先テストフレームワークまで全てを指定していて、コントリビューターたちがClaudeに従わせた時のレビューサイクルが劇的に減少したと報告している。

ファイルの配置と階層

CLAUDE.mdファイルは複数のレベルに置ける：

リポジトリルート（/CLAUDE.md）— プロジェクトの全セッションで読み込まれる。プロジェクト全体のルールを書く場所。
サブディレクトリ（/packages/api/CLAUDE.md）— そのディレクトリでClaudeが作業する時だけ読み込まれる。モノレポのパッケージ固有のルールに使う。
ユーザーレベル（~/.claude/CLAUDE.md）— 自分が作業する全プロジェクトで読み込まれる。エディタ設定やフォーマットの好みなど個人的な設定に最適。

Claudeは順番に読む：ユーザーレベルが最初、次にルート、次にサブディレクトリ。より具体的なファイルが優先される。

効果的なCLAUDE.mdの構成

The Prompt Shelfのトップリポジトリの数十のCLAUDE.mdファイルを分析すると、明確なパターンが見えてくる。優れたファイルは以下のセクションを持っている：

1. プロジェクト概要

プロジェクトの説明と技術スタックの簡単な記述から始める。これがClaudeにアーキテクチャの意思決定のためのコンテキストを与える。

# Project

This is a Next.js 14 application using the App Router, TypeScript,
Tailwind CSS, and Drizzle ORM with PostgreSQL.

LangChainのCLAUDE.mdはプロジェクトの目的とコアな抽象化の明確な説明で始まっている。Claudeがコードを書く前にドメインを理解するためだ。

2. コードスタイルと規約

ここが最も時間を節約するセクションだ。具体的かつ処方的に書こう。

## Code Style

- Use functional components with arrow functions
- Prefer named exports over default exports
- Use TypeScript strict mode; no `any` types
- Imports: React first, then third-party, then local (with blank lines between groups)
- File naming: kebab-case for files, PascalCase for components

Excalidrawのサンプルは、フォーマットだけでなくコンポーネント合成パターンや状態管理のアプローチなどアーキテクチャの好みまで特に詳しく書いている。

3. アーキテクチャとパターン

どのパターンを好み、どれを避けるかをClaudeに伝える。

## Architecture

- Server Components by default; only use 'use client' when necessary
- Data fetching happens in Server Components, never in client components
- Use Server Actions for mutations
- Keep components small; extract to separate files at ~50 lines

Dan Abramov / OverreactedのCLAUDE.mdは、コードベースの一貫性を保つ強いアーキテクチャ上の主張のエンコード方法を示している。

4. プロジェクト固有のコマンド

プロジェクトに特殊なビルド手順、テストコマンド、開発ワークフローがあれば記載する。

## Commands

- `pnpm dev` — Start development server
- `pnpm test` — Run Vitest in watch mode
- `pnpm lint` — ESLint + Prettier check
- `pnpm db:push` — Push schema changes to database

DenoのCLAUDE.mdはビルドとテストの詳細な指示を含んでいる。プロジェクトが非標準のビルドシステムを使っていて、Claudeが他では知る方法がないからだ。

5. やってはいけないこと

否定の指示は意外なほど効果的だ。避けるべきことを伝えるのは、すべきことを伝えるより効果的なことが多い。

## Do NOT

- Do not use `class` components
- Do not use `any` type
- Do not add dependencies without asking
- Do not modify the database schema directly
- Do not use inline styles

CockroachDBのCLAUDE.mdには、Claudeが変更すべきでないサブシステムと避けるべきテストパターンについての明示的な制約がある。

6. ファイル構成

大規模なプロジェクトでは、どこに何があるかをClaudeに伝える。

## File Structure

- `src/components/` — Reusable UI components
- `src/app/` — Next.js App Router pages
- `src/lib/` — Utility functions and shared logic
- `src/db/` — Database schema and migrations

7. テストの期待値

テストをいつ・どのように書くかを指定する。

## Testing

- Every new component needs a test file in __tests__/
- Use Testing Library for component tests
- Use Vitest, not Jest
- Integration tests go in tests/integration/
- Run `pnpm test:unit` before committing

参考になる実例

The Prompt Shelfで見られる注目プロジェクトのCLAUDE.mdを紹介する：

Vercel Next.js — モノレポのCLAUDE.mdのゴールドスタンダード。詳細なテストとコントリビューションガイドラインを含むNext.jsフレームワーク全体のコードベースをカバー。138Kスター。

LangChain — 複数パッケージを持つ複雑なPythonライブラリのドキュメント化方法を示す。インポート規約とテストパターンを重視。128Kスター。

Excalidraw — Reactアプリケーションの良い例。コンポーネントパターン、状態管理、UI規約を指定。118Kスター。

Deno — RustベースのランタイムのCLAUDE.mdを示す。ビルドシステムの癖とクロスプラットフォームの考慮事項をカバー。106Kスター。

Zed Editor — GPUIフレームワークを使ったRustアプリのCLAUDE.mdの書き方を示す。カスタムUIフレームワークについての詳細な説明を含む。76Kスター。

Anthropicの公式ガイド — CLAUDE.mdについてのAnthropicの推奨事項。簡潔で原則に基づく。

Freek Van der Herten / Spatie Laravel — PHP/Laravelプロジェクトの優れた例。CLAUDE.mdがJavaScriptエコシステム以外でも機能することを示す。

ベストプラクティス

数百のCLAUDE.mdファイルをレビューした結果、一貫して良い結果を出すパターン：

具体的に、抽象的にならない。 「スタイリングにTailwind CSSを使う」は「モダンなCSSプラクティスに従う」より良い。「条件付きクラスには@/lib/utilsのcn()を使う」はさらに良い。

500行以内に収める。 ClaudeはセッションごとにファイルのBotomを読む。長すぎると重要なルールが薄まる。詳細なドキュメントは別ファイルに移して参照する。

例を使う。 プロジェクトで良いコードがどう見えるかをClaudeに見せる。5行のコードサンプルは50行の説明より価値がある。

定期的に更新する。 CLAUDE.mdはコードベースと共に進化すべきだ。同じことでClaudeを繰り返し修正しているなら、そのファイルに追加しよう。

ルールをテストする。 CLAUDE.mdを変更した後、新しいClaudeセッションを開始して一般的なタスクを実行させる。新しいルールに従っているか確認する。

READMEと重複させない。 CLAUDE.mdはAI固有の指示のためのものだ。人間の開発者には必要だがClaudeには不要なセットアップ手順はREADME.mdに置く。

モノレポはサブディレクトリファイルを使う。 20パッケージのモノレポのための1つの巨大なCLAUDE.mdは、ルートファイルに共通のルール＋パッケージ固有のファイルより効果的ではない。

CLAUDE.md vs 他のフォーマット

CLAUDE.mdはClaude Code専用だ。チームが複数のAIツールを使うなら、以下も必要かもしれない：

.cursorrules — Cursor AI向け。同様のコンセプト、異なるフォーマット。
AGENTS.md — マルチエージェントシステムの広範な標準。Codex、Claude Code、その他で使用。
.github/copilot-instructions.md — GitHub Copilot向け。

良いニュースは、これらのフォーマットは十分似ているので、1つの正典ドキュメントを維持して適応できる。詳細な比較は比較ガイドを参照。

始め方

まだCLAUDE.mdがないなら、小さく始めよう：

プロジェクトルートにCLAUDE.mdファイルを作成する。
プロジェクトの1段落の説明を追加する。
最も重要なコーディング規約5つをリストアップする。
Claudeに絶対にやってほしくないこと3つを追加する。
最もよく使う開発コマンドを含める。

それだけで目に見える改善がある。セッションで必要な追加ドキュメントを発見しながらファイルを拡張していこう。

インスピレーションを探すならCLAUDE.mdファイルの全コレクション、または他のプロジェクトがAIコーディングアシスタントをどう設定しているかを見るなら全ルールギャラリーを参照。