CLAUDE.md書き方ガイド｜最初の1枚を書くテンプレート付き

CLAUDE.mdにプロジェクトの説明を書いていた時期があります。

技術スタック、ディレクトリ構成、使っているライブラリ。

丁寧に書いたのに、Claude Codeの出力は何も変わりませんでした。

この記事では、CLAUDE.mdの最初の1枚をテンプレート付きで書けるようにします。

READMEとの違い、最小構成の始め方、やりがちな失敗パターンまで、自分が数ヶ月運用してわかったことをまとめています。

Claude Codeの全体像を先に把握したい方は、Claude Code完全ガイドからどうぞ。

CLAUDE.mdとは何か — READMEとの決定的な違い
最初のCLAUDE.mdはこれだけ書けばいい【テンプレート】
書いてはいけないCLAUDE.md — 3つの失敗パターン
行動ルール型に変えて何が変わったか
CLAUDE.mdを書いた後の次のステップ
まとめ — CLAUDE.mdの最初の1枚を今すぐ書こう

CLAUDE.mdとは何か — READMEとの決定的な違い

CLAUDE.mdとは、Claude Codeがセッション開始時に自動で読み込む指示ファイルです。

プロジェクトの「説明書」ではなく、AIに対する「行動ルール」を書く場所として機能します。

ここが最初にわかりにくいところでした。

READMEは人間向けです。

「このプロジェクトは何か」「どうセットアップするか」を説明するもの。

一方、CLAUDE.mdはAI向けのoperating manual。

「このプロジェクトで何をしてはいけないか」「どう振る舞うか」を指定するものです。

	README.md	CLAUDE.md
読む対象	人間（開発者）	AI（Claude Code）
内容	プロジェクトの説明	AIの行動ルール
目的	理解してもらう	従ってもらう
例	「React + TypeScriptで構築」	「テストは必ずvitest。jestは使わない」

CLAUDE.mdには配置できる場所が4段階あります。

Managed policy（組織共通） — OS指定のパスに配置
（macOS: `/Library/Application Support/ClaudeCode/CLAUDE.md`、Linux: `/etc/claude-code/CLAUDE.md`）
Project（チーム共有） — プロジェクトルートの `./CLAUDE.md`
User（個人全体） — `~/.claude/CLAUDE.md`
Local（個人×プロジェクト） — `./CLAUDE.local.md`

より具体的なスコープの指定が優先されます。

最初に書くなら、プロジェクトルートの`CLAUDE.md`一択です。

ファイル名は大文字小文字を区別します。

`claude.md`や`Claude.md`ではダメで、必ず`CLAUDE.md`にしてください。

最初のCLAUDE.mdはこれだけ書けばいい【テンプレート】

自分が最初から書き直すなら、こう書きます。

markdown

# CLAUDE.md

## プロジェクト概要

- フロントエンド: Next.js 15 + TypeScript

- スタイル: Tailwind CSS

- テスト: vitest（jestは使わない）

## コマンド

- `npm run dev` — 開発サーバー起動

- `npm run test` — テスト実行

- `npm run build` — ビルド

## コードのルール

- 変数名・関数名はキャメルケース

- コンポーネントファイルは PascalCase.tsx

- console.logはPR前に必ず削除

- 日本語でコメントを書く

## やらないこと

- 既存のテストを削除しない

- パッケージの追加は提案のみ。自動でインストールしない

- .envファイルを変更しない

これで30行程度。公式ドキュメントでは200行以下が推奨されています。

コミュニティでは50〜100行が実用的とされていますが、最初は短いほうがいいです。

各セクションのポイントを補足します。

「プロジェクト概要」 — 技術スタックだけ。

READMEみたいにプロジェクトの目的や背景は不要です。Claudeがコードを読めばわかることは書きません。

「コマンド」 — ビルド、テスト、起動。Claudeが推測できないコマンドだけ書きます。

`npm install`は書かなくていいですが、`npm run test:e2e –filter=auth`みたいなプロジェクト固有のものは書く価値があります。

「コードのルール」 — Claudeが推測しづらい規約だけ。

「関数は短く書く」みたいな一般論は不要です。「このプロジェクトではこうする」という具体的なルールだけ書きます。

「やらないこと」 — 正直、ここが一番効きます。

Claudeは親切なので、テストを「整理」してくれたり、依存パッケージを勝手に追加したりする。

やらないことを書いておくと、余計な動きが目に見えて減ります。

判断基準はシンプルで、「この行を消したらClaudeが間違えるか？」。

答えがNoなら、その行は要りません。

書いてはいけないCLAUDE.md — 3つの失敗パターン

自分が通ってきた道と、よく見かけるパターンを3つ挙げます。

1. プロジェクト説明型（READMEのコピペ）

markdown

# プロジェクト概要

このプロジェクトは、ユーザーのタスク管理を効率化するための

Webアプリケーションです。React + TypeScript + Supabaseで構築されており、

リアルタイム同期機能を備えています...

これ、自分が最初に書いたやつとほぼ同じです。

Claudeに「あなたは何のプロジェクトにいるか」を説明している。

でもClaude Codeはコードベースを直接読めるので、この説明は冗長です。

コンテキストを消費するだけで、出力は何も変わりません。

2. 網羅型（全部書こうとする）

markdown

## API設計ルール

- RESTful原則に従う

- HTTPステータスコードは適切に使い分ける

- エラーレスポンスは統一フォーマットにする

...（50行続く）

## テスト方針

- ユニットテストのカバレッジは80%以上

- 結合テストは主要フローをカバー

...（30行続く）

書けば書くほどClaudeは従ってくれる——と思っていた時期がありました。

実際は逆です。

公式も「全部IMPORTANTにすると、何もIMPORTANTでなくなる」と言っています。

長くなるほど、本当に守ってほしいルールが埋もれます。

Claude Codeで失敗した5つのパターンと教訓でも書きましたが、CLAUDE.mdは「引き算」の設計です。