Claude CodeのCLAUDE.mdの書き方

結論、CLAUDE.mdには「人間には言わなくても伝わるが、Claude Codeには明文化しないと伝わらないルール」だけを書きます。プロジェクトの背景説明や手順の羅列を詰め込みすぎないことが、実用上いちばん重要です。

CLAUDE.mdとは何か

CLAUDE.mdは、Claude Codeがセッション開始時に自動で読み込むプロジェクト規約ファイルです。プロジェクト直下に置けば、そのリポジトリで作業するたびに毎回読み込まれ、口頭やチャットで同じ指示を繰り返す手間を減らせます。個人の作業環境全体に効かせたい内容であれば、ホームディレクトリの~/.claude/CLAUDE.mdに書くことで、プロジェクトを問わず常に効かせることもできます。なお、CLAUDE.md自体に追加費用はかかりませんが、Claude Codeの利用にはPro等のサブスクリプション($20/月〜、2026年7月時点)が前提になります。

CLAUDE.mdに書くべきこと・書かなくていいこと

書く価値があるのは、次のような「明文化しないと守られない」情報です。

• 禁止事項・危険な操作の制約: 触ってはいけないディレクトリ、実行してはいけないコマンド、本番環境への操作制限など。
• プロジェクト固有の規約: ディレクトリ構成の意味、命名規則、コミットメッセージの書式、レビュー基準など、コードを読むだけでは推測しづらいルール。
• ビルド・確認コマンド: npm testやhugo --minifyなど、変更後に必ず通すべき確認コマンド。
• 報告や出力の形式指定: 完了報告の書き方、避けるべき表現など、プロジェクト運用上の約束事。

逆に、次のような内容はCLAUDE.mdに書いても効果が薄く、かえって本来のルールを埋もれさせます。

• コードを読めば分かる実装の詳細や関数一覧(コメントやコードそのものに任せる)。
• 一度きりの作業手順(その都度チャットで指示すれば十分)。
• 頻度の低い定型作業の詳細手順(後述するSkillsに切り出した方が読み込みが軽い)。

書き方の実例

最小構成の例です。見出しごとに「絶対に守ってほしいこと」と「確認コマンド」を分けて書くと、Claude Codeが優先度を判断しやすくなります。

# CLAUDE.md ── プロジェクト規約

## 禁止事項
- `main`ブランチへの直接pushは禁止。必ずPR経由にする。
- `.env`や`secrets/`配下のファイルは読み書きしない。

## 規約
- コミットメッセージは日本語で、変更理由を1行目に書く。
- コンポーネントは`src/components/`配下にPascalCaseで置く。

## ビルド/確認
\`\`\`bash
npm run lint
npm test
\`\`\`

ポイントは、抽象的な心構えではなく「何をしてはいけないか」「何を実行すれば確認できるか」を具体的な語で書くことです。「丁寧に実装してください」のような曖昧な指示は、実際の判断基準にならないため書いても効果が薄くなります。

README・Skills・Hooksとの使い分け

CLAUDE.mdと役割が近い仕組みがいくつかあるため、混同しやすいポイントを整理します。

READMEは人間向けのドキュメントで、Claude Codeの挙動を直接制御するものではありません。CLAUDE.mdは常時読み込まれる分、内容が増えると本来伝えたいルールが埋もれるという弱点があります。頻度の低い手順や長い作業フローは、必要なときだけ読み込まれるSkillsに切り出す方が、CLAUDE.mdを軽く保ちながら運用できます。逆に「常にこの操作を禁止・実行したい」という強制力が必要な場合は、CLAUDE.mdへの記載に加えてHooksでの制御も検討する価値があります。

つまずきやすいポイント

• 抽象的な精神論を書いてしまう: 「丁寧に」「わかりやすく」といった表現は具体的な判断基準にならない。禁止事項・手順・確認コマンドのような、実行可能な形で書く。
• README全文をそのまま貼り付ける: プロジェクト概要の重複はCLAUDE.mdを長くするだけで、Claude Code向けの実効性は上がらない。人間向けの説明とClaude Code向けのルールは分けて考える。
• 更新されずに古い規約が残り続ける: ディレクトリ構成やコマンドを変更したときにCLAUDE.mdを直さないと、誤った前提で作業が進む原因になる。コードの変更と同じタイミングで見直す。
• 個人用とチーム共有用を混同する: プロジェクト直下のCLAUDE.mdはリポジトリに含めればチーム全員に効くが、ホームディレクトリ側は自分の作業環境にしか効かない。共有したい内容かどうかを先に決める。

向いていない人

• リポジトリ規模が小さく、口頭やチャットでの指示で十分足りている人。無理に整備しても管理コストが上回る。
• プロジェクトの構成や規約がまだ固まっておらず、頻繁に変わる段階の人。先にCLAUDE.mdを書き込むより、運用が落ち着いてから規約化した方が手戻りが少ない。
• ルールを一度書いたら見直す運用が組めない人。古いCLAUDE.mdは誤った前提を毎回読み込ませる原因になり、書かない方がましな状態になりやすい。

FAQ

Q. CLAUDE.mdはどこに置けばいいですか？ A. プロジェクト固有のルールはリポジトリ直下のCLAUDE.mdに置きます。個人の作業環境全体に常に効かせたい内容は、ホームディレクトリの~/.claude/CLAUDE.mdに書くと使い分けられます。

Q. CLAUDE.mdに書きすぎるとどうなりますか？ A. CLAUDE.mdは会話のたびに読み込まれるため、量が増えるほど本来の指示が埋もれやすくなります。頻度の低い手順や長い作業手順は、必要な場面だけ読み込まれるSkillsに切り出すのが安全です。

Q. CLAUDE.mdとREADMEはどう使い分けますか？ A. READMEは人間の開発者向けに、セットアップ手順やプロジェクトの概要を説明する場所です。CLAUDE.mdはClaude Code向けに、人間には自明でも明文化しないと守られないルールや、リポジトリ固有の制約を書く場所という違いがあります。

Q. CLAUDE.mdはgitに含めるべきですか？ A. チームで共有したいプロジェクト共通のルールなら、リポジトリに含めて全員に同じ内容が効くようにするのが基本です。自分だけの好みや個人的な作業環境の設定は、ホームディレクトリ側のCLAUDE.mdに分けると混同を防げます。

まとめ

CLAUDE.mdは、人間には自明でもClaude Codeには明文化しないと伝わらないルールだけを書く場所です。抽象的な心構えではなく、禁止事項・規約・確認コマンドを具体的に書き、頻度の低い手順はSkillsへ、常に強制したい制御はHooksへと役割を分けることで、CLAUDE.md自体を軽く保ちながら運用できます。Claude Codeの基本的な使い方から確認したい場合は、Claude Codeの使い方ガイドを参照してください。