CLAUDE.md の書き方:ユーザー・プロジェクト・ディレクトリの 3 階層と実例テンプレート

Claude Code に同じ説明を毎回繰り返している、指示したはずのコーディング規約が守られない。こうした悩みの多くは CLAUDE.md を整えることで解決します。

CLAUDE.md は、Claude Code がセッション開始時に自動で読み込む Markdown ファイルです。この記事では、どこに何を書くべきかを 3 つの階層に分けて整理し、そのまま使えるテンプレートを示します。

CLAUDE.md の 3 階層

階層	パス	用途	Git 管理
ユーザー	~/.claude/CLAUDE.md	全プロジェクト共通の好み(言語、口調、よく使うコマンド)	しない
プロジェクト	./CLAUDE.md または ./.claude/CLAUDE.md	チームで共有する規約、ビルド手順、構成	する
個人(プロジェクト内)	./CLAUDE.local.md	自分だけのメモ、ローカル環境固有の情報	しない(.gitignore に追加)

これに加えて、サブディレクトリの CLAUDE.md も使えます。たとえば packages/api/CLAUDE.md に置いた内容は、Claude がそのディレクトリ内のファイルを扱うときに読み込まれます。モノレポでは、ルートに全体方針、各パッケージに固有ルールを置く構成が扱いやすいです。

読み込まれた内容は /memory コマンドで確認できます。どのファイルが効いているか分からないときは、まずここを見ます。

最初の 1 枚は /init で作る

リポジトリのルートで /init を実行すると、Claude がプロジェクトを調べて CLAUDE.md の雛形を生成します。生成物はそのまま使わず、次の観点で削ってください。

• README を読めば分かる内容(プロジェクトの目的の長い説明)は削る
• Claude が自分でファイルを見れば分かること(ディレクトリ一覧)は削る
• 残すのは「見ただけでは分からない約束事」

書くべき内容

よく使うコマンド

Claude が推測で間違ったコマンドを実行するのを防ぎます。

## コマンド
- テスト: `npm test`(単体)/ `npm run test:e2e`(E2E、Docker 起動が必要)
- Lint: `npm run lint` — コミット前に必ず通す
- ビルド: `npm run build`
- DB マイグレーション: `npm run db:migrate`

守ってほしい規約

「なぜ」を一言添えると、Claude が判断に迷う場面で規約の意図に沿って動きやすくなります。

## 規約
- 新しい関数には必ず JSDoc を書く(型定義から API ドキュメントを生成しているため)
- `any` は使わない。型が分からない場合は `unknown` にして絞り込む
- 日付は `date-fns` を使う。`moment` は追加しない(バンドルサイズの理由)

触ってはいけない場所

## 変更禁止
- `src/generated/` 配下(コード生成物。元は `schema/` を編集する)
- `migrations/` の既存ファイル(新規ファイルを追加する)

作業の進め方

## 作業の進め方
- 3 ファイル以上を変更するときは、先に変更方針を箇条書きで提示してから着手する
- テストが落ちたまま「完了」と報告しない
- コミットは 1 つの論理的変更ごとに分ける

書かない方がよい内容

内容	理由
ファイル一覧やディレクトリ構成の丸写し	Claude は必要なときに自分で探索する。更新漏れで嘘になりやすい
一般的なベストプラクティス(「読みやすいコードを書く」)	具体的でない指示は行動に反映されにくい
秘密情報・URL・認証情報	CLAUDE.md は Git に入る。個人情報は CLAUDE.local.md にも書かず環境変数にする
長大な仕様書	毎セッションのコンテキストを消費する。必要な部分だけ @ でインポートする

テンプレート(小〜中規模の Web プロジェクト向け)

# プロジェクト概要
Next.js + TypeScript の管理画面。API は `apps/api`(NestJS)。

## コマンド
- 開発サーバー: `pnpm dev`
- テスト: `pnpm test`(変更したファイルに関連するテストは必ず実行する)
- Lint / Format: `pnpm lint && pnpm format`
- 型チェック: `pnpm typecheck`

## 規約
- コンポーネントは関数コンポーネント + hooks。クラスコンポーネントは追加しない
- スタイルは Tailwind。CSS Modules は既存分のみ保守する
- API のレスポンス型は `packages/types` に置き、フロントとバックで共有する
- エラーは握りつぶさず、`AppError` を throw する

## 変更禁止
- `packages/types/generated/`(OpenAPI から生成)
- `.github/workflows/`(変更が必要なら提案だけする)

## 作業の進め方
- 変更前に関連するテストを読む
- 3 ファイル以上の変更は、方針を先に提示する
- 完了報告には実行したテストコマンドと結果を含める

## 参照
@docs/architecture.md

育て方:セッション中に追記する

会話の途中で # から始まる行を入力すると、その内容を CLAUDE.md に追記するよう Claude に指示できます。「今後は〇〇して」と口頭で伝えるだけでは次のセッションに残らないため、繰り返し伝えていることは # で書き込む習慣をつけると、CLAUDE.md が自然に育っていきます。

同じ考え方で AGENTS.md(Codex)や GEMINI.md(Gemini CLI)を使う場合は、CLAUDE.md・AGENTS.md・GEMINI.md の違いと共通化テクニック を参照してください。

まとめ

• CLAUDE.md はユーザー・プロジェクト・個人の 3 階層に分けて置き、/memory で読み込み状況を確認する
• 書くのは「見ただけでは分からない約束事」。コマンド、規約、変更禁止、進め方の 4 種類が中心
• ディレクトリ一覧や一般論は書かない。長い文書は @ でインポートする
• # で会話中に追記して育てる