CLAUDE.mdは、Claude Codeへプロジェクトのコマンド、規約、構成、禁止事項を繰り返し伝えるためのMarkdownファイルです。短く、具体的に、検証できる指示を書くと守られやすくなります。
何でも1ファイルへ詰め込むと、重要な指示が埋もれます。全体ルールはroot、特定pathだけの規約は下位CLAUDE.mdまたは.claude/rules/、個人設定はCLAUDE.local.mdへ分けます。
この記事では、対象範囲、root・下位テンプレート、競合テスト、更新方法、AGENTS.mdとの違いを解説します。
情報確認日：2026年7月17日（日本時間）
結論：毎回説明する事実だけを短く書く
書くもの：build・testコマンド、coding規約、directory構成、確認手順、プロジェクト固有の制約。
分けるもの：長い作業手順、特定pathだけの規約、個人の設定、強制したい権限制御、秘密情報。
公式ドキュメントは、CLAUDE.mdをcontextであり強制設定ではないと説明しています。具体的で簡潔な方が従われやすく、目安として200行未満が案内されています。
CLAUDE.mdの対象範囲
| scope | 場所 | 用途 |
|---|---|---|
| Managed | OSごとの管理policy path | 組織全体の標準 |
| User | ~/.claude/CLAUDE.md |
自分の全project共通 |
| Project | ./CLAUDE.mdまたは./.claude/CLAUDE.md |
teamで共有する規約 |
| Local | ./CLAUDE.local.md |
自分だけのproject設定 |
| Directory | 下位directoryのCLAUDE.md |
その配下だけの規約 |
起動地点より上のCLAUDE.mdは開始時に読み込まれ、下位directoryのものはClaudeがその中のfileを扱うときに読み込まれます。近い階層の指示ほど後にcontextへ追加されますが、矛盾を作らないことが最善です。
CLAUDE.mdに書く内容
- 使用するpackage managerとruntime
- 開発、test、lint、typecheck、buildコマンド
- source・test・generated fileの場所
- 命名、format、error処理など固有規約
- 変更してはいけないfileや生成手順
- 完了前に実行する最小確認
- 安全なGit・deploy方針
root用CLAUDE.mdテンプレート
# Project Instructions
## Stack
- Node.js version is defined in `.nvmrc`.
- Use `pnpm`; do not create npm or yarn lockfiles.
- Application code is under `src/`.
## Commands
- Development: `pnpm dev`
- Unit tests: `pnpm test`
- Type check: `pnpm typecheck`
- Production build: `pnpm build`
## Coding
- Follow the existing TypeScript and React patterns.
- Keep changes limited to the requested feature.
- Validate external input at API boundaries.
- Do not edit generated files under `src/generated/`.
## Verification
- Run tests related to changed files.
- Run `pnpm typecheck` after TypeScript changes.
- Report checks that could not be run.
## Safety
- Do not read or commit secret files.
- Do not deploy or push without explicit approval.
- Preserve unrelated user changes.「正しく書く」ではなく、「2space」「このcommand」「このdirectory」のように確認できる指示にします。既存のREADMEやpackage.jsonから分かることを大量に複製せず、Claudeが間違えやすい点を優先します。
下位ディレクトリ用テンプレート
src/payments/CLAUDE.mdの例です。
# Payments Instructions
These rules apply to files under `src/payments/`.
## Boundaries
- All money values use integer minor units.
- Never log card, bank, or authentication data.
- Keep provider-specific code under `providers/`.
## Changes
- Add an idempotency test for write operations.
- Add a rollback note for schema changes.
- Do not change public webhook signatures without a migration plan.
## Verification
- Run `pnpm test payments`.
- Run the webhook fixture tests.
file patternだけに適用したい場合は、.claude/rules/のpath-scoped rulesも候補です。多段の作業手順はSkill、必ず実行したい機械的処理はHookへ分けます。
書かない方がよい内容
- APIキー、password、秘密URL
- 長い一般的なプログラミング解説
- 互いに矛盾するformat・test規約
- 一度だけ使うタスク固有の指示
- 変更のたびに古くなるfile一覧
- 権限設定として必ず守られる前提の禁止事項
強制したいtool禁止、sandbox、permissionは設定で制御します。CLAUDE.mdはClaudeの判断を導くcontextであり、セキュリティ境界そのものではありません。
指示競合テスト
| test | root指示 | 下位指示 | 期待 |
|---|---|---|---|
| package manager | pnpmを使う | なし | 下位でもpnpm |
| test | pnpm test |
payments testも実行 | 両方の対象確認 |
| 金額 | 一般TypeScript規約 | 整数minor unit | payments内で下位規約 |
| 矛盾 | single quote | double quote | 矛盾を検出し一方へ統一 |
次のような小さな依頼で確認します。
1. このprojectで使うpackage managerと確認commandを答えて。
2. src/payments/へ金額を扱う関数を追加する場合の規約を列挙して。
3. 互いに矛盾する指示があるか、fileと内容を示して。
4. 実装はせず、変更後に実行すべきtestだけ答えて。
Claude Codeの/memoryで対象fileを確認し、必要に応じて/contextで実際に読み込まれた指示を確認します。
AGENTS.mdと共存する
Claude CodeはCLAUDE.mdを読みます。すでにCodexなど向けのAGENTS.mdがある場合、同じ内容を重複管理せず、CLAUDE.mdからimportできます。
@AGENTS.md
## Claude Code
- Use `/memory` to inspect loaded instructions.
- Put Claude-specific path rules under `.claude/rules/`.Codex側の設計はCodexのAGENTS.mdの書き方で解説しています。
メンテナンス方法
- 同じ訂正を2回したら追加候補にする
- 追加前に既存指示との重複・矛盾を探す
- 具体的な1〜3行で書く
- path限定ならrulesまたは下位fileへ置く
- commandやdirectory変更と同時に更新する
- 定期的に古い指示を削除する
基本操作から確認したい場合はClaude Codeの使い方も参考になります。
まとめ
CLAUDE.mdには、毎回説明するプロジェクト固有の事実を短く具体的に書きます。rootは全体規約、下位fileやrulesはpath限定、Skillは手順、Hook・settingsは機械的な強制に分けます。
追加後は/memoryと小さな競合テストで読み込みと解釈を確認し、古くなった規約を定期的に整理してください。