CLAUDE.md 書き方ガイド

Claude Codeの行動を変える設定ファイルの書き方ノウハウ

CLAUDE.mdとは

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

プロジェクトのルール、技術スタック、禁止事項などを書いておくと、毎回同じ説明をする必要がなくなります。

/init で対話的にCLAUDE.mdを作成できます。

配置場所（3階層）

場所スコープGit共有
~/.claude/CLAUDE.md全プロジェクト共通（ユーザー設定）しない
./CLAUDE.mdそのプロジェクトのみする
./CLAUDE.local.mdそのプロジェクトの個人設定しない（自動.gitignore）
./.claude/rules/*.md条件付きルール（特定ファイル時のみ適用）する
./subdir/CLAUDE.mdサブディレクトリのファイル読み時のみする
上の階層から順に読み込まれます。プロジェクト固有の設定は ./CLAUDE.md に、個人の好みは CLAUDE.local.md に書くのが基本。

サイズと精度の関係

行数精度評価
〜40行最高最も効果的。核心だけを書いた状態
〜100行高い推奨上限。十分に実用的
〜300行やや低下限界ライン。重要な指示が埋もれ始める
300行超著しく低下避けるべき。指示が無視される可能性大
なぜ長いとダメなのか: LLMには「理解できる指示数」に上限があります。長すぎると一部の指示が無視されたり、矛盾する指示に混乱したりします。システムプロンプト自体が約50個の指示を使っているため、CLAUDE.mdに書ける余裕は限られています。
解決策: 詳細は別ファイル（docs/配下等）に置き、CLAUDE.mdには「参照先」だけを書く。

書くべきこと

カテゴリ内容例
プロジェクト概要何のプロジェクトか、技術スタック「React Native（Expo SDK 52）のコンテンツクリエイター向けアプリ」
プロジェクト構造主要ディレクトリの役割「app/ = ルーティング、components/ = UI部品」
開発コマンドビルド・テスト・検証コマンド「npm run dev」「npm test」
禁止事項絶対にやってはいけないこと「rm -rf禁止」「mainにforce push禁止」
重要な決定なぜその技術・設計を選んだか「認証はNextAuth.js（深層リンク対応のため）」
検証手順変更後の確認方法「変更後必ず: npm run typecheck && npm test」

書かないこと

書かないこと理由代わりにやること
詳細なコードスタイルLLMは既存コードから学習するリンター（Biome/ESLint）を使う
当たり前のこと「エラーハンドリングをして」等は不要Claudeはすでに知っている
タスク固有の指示特定APIの書き方等はCLAUDE.mdの役割外スコープ付きルールを使う
一時的な修正ルール「〇〇のバグを回避するために〜」Hook または /code-review で対処

良い例 / 悪い例

悪い例（長すぎ・詳細すぎ）

# プロジェクト設定
このプロジェクトはReactアプリです。以下の規約を厳守してください。

## コードスタイル
- インデントはスペース2つ
- 最大行長は80文字
- 変数名はcamelCase
- 関数名はsnake_case
- クラス名はPascalCase
- コメントは日本語で...

## テスト
- テストファイルは__tests__ディレクトリに配置
- Jestを使用
- テストカバレッジは90%以上
- モックはsinonを使用
...

良い例（核心だけ40行以内）

# Content App — コンテンツ管理ツール

## スタック
- Frontend: Next.js 14, TypeScript, Tailwind CSS
- Backend: Next.js API Routes, Prisma
- DB: PostgreSQL / 認証: NextAuth.js

## プロジェクト構造
- app/ — App Router（ページ・API）
- components/ — 共有UIコンポーネント
- lib/ — ユーティリティ、ヘルパー
- prisma/ — スキーマ定義、マイグレーション

## コマンド
- npm run dev — 開発サーバー起動
- npm run typecheck — TypeScriptチェック
- npm test — テスト実行

## 検証
変更後必ず: npm run typecheck && npm test

## 主要パターン
- 認証: NextAuth.js（lib/auth.ts参照）
- データ取得: React Query + Prisma

Memory vs CLAUDE.md — 使い分け

CLAUDE.mdMemory
用途プロジェクトの基本ルールセッション間で保持したい知識
誰が書く人間が手動で書くClaudeが自動で記録
変更頻度ほぼ変わらない頻繁に更新される
内容例「テストはpytest」「コミットは日本語」「ユーザーはfeatureブランチ禁止を好む」
Git共有プロジェクトなら共有個人環境のみ
基本方針: プロジェクトの「変わらないルール」はCLAUDE.mdへ。「ユーザーの好みや学習結果」はMemoryへ。

書く前のチェックリスト

確認項目
100行以内に収まっているか核心だけを書く
すべての指示が「常に適用」されるか特定タスク用ならルールファイルへ
プロジェクト概要が含まれているかスタック・構造・目的
正確なビルド/テストコマンドがあるか動かないコマンドは書かない
コードスタイルルールを書いていないかリンターに任せる
「当たり前」を書いていないかClaudeは知っている
← ガイド一覧に戻る