CLAUDE.md（クロードドットエムディー）

Claude Codeで動くプロジェクトにCLAUDE.mdを置こうとしている人向け

CLAUDE.mdは、Claude Codeがプロジェクトに入るたびに最初に読む覚え書きファイル。チームで共有するルール（ビルドコマンド、ディレクトリ構成、命名規則、踏んだら困る地雷）をマークダウン（=軽量な書式付きテキスト）で書いておくと、毎セッション同じ説明を繰り返さずに済む。

同じ訂正を会話で2回打ったら、CLAUDE.mdに書く。これが一番分かりやすい合図です。

噛み砕くと

家族で使うレシピノートに近い。「うちの味噌汁は煮干しで取る」「炊飯器のメモリは2まで」みたいな前提を一冊に書いておけば、誰がキッチンに入っても同じ味になる。CLAUDE.mdはそのプロジェクト版です。

違うのは読む相手がClaudeだという点だけ。「このリポジトリではnpmじゃなくてpnpmを使う」「テストはnpm run test:unitで叩く」と1行書いておけば、新しいセッションでもClaudeが同じ前提で動いてくれる。

つまり「言わなくても分かる」を1ファイルに集約する仕掛けです。

大事な前提：CLAUDE.mdは「設定」ではなく「文脈」

公式ドキュメントの言葉を借りると、CLAUDE.mdは「context, not enforced configuration（強制される設定ではなく文脈）」として渡される。つまりClaudeが必ず守る命令ではなく、参考として読むメモという位置づけです。

具体的・短い・整理された指示ほど守られやすい。逆に「ちゃんと書いて」みたいな曖昧な命令は無視されがち。「2スペースインデントで書く」「コミット前にnpm testを流す」のように検証可能な粒度で書く必要があります。

「料理ブログを始める」を例に、中身を育てる手順

前回の/init（イニット）エントリで、料理ブログ用フォルダ（既存記事10本、画像、config.ymlあり）に /init を叩いて雛形CLAUDE.mdを作るところまでやった。続きとして、その雛形を実際に「読まれて効くファイル」に育てるステップを追います。

ステップ1: 雛形を一回ちゃんと読む

/initが吐いたCLAUDE.mdをそのまま使う前に、ターミナルで開いて全部目を通す。雛形は「観察できた事実」を機械的に並べただけなので、私の意図が入っていない。

$ cat CLAUDE.md
# 料理ブログ
- Hugo（静的サイトジェネレーター）で構築
- content/posts/ 配下に記事Markdown
- static/images/ 配下に画像
- config.yml がサイト設定
...

ステップ2: 「同じ訂正を2回打つ前提」を先回りで書く

公式ドキュメントが推奨する書き方は「Claudeが同じ間違いを2回したら追加する」。料理ブログだと、画像パスの書き方とサムネ命名で必ず迷うので、最初から書いておきます。

# 画像
- 画像は static/images/recipes/{slug}/ 配下に置く
- サムネは hero.jpg、本文挿絵は step-{n}.jpg
- ファイル名は kebab-case（半角ハイフン区切り、英小文字のみ）

# 記事の書き方
- frontmatter（記事冒頭のメタ情報ブロック）に title / date / tags / hero_image を必須
- tags は最大5個、すべて日本語の単数形
- 本文の見出しは h2 から始める（h1 はテンプレ側が出力）

ステップ3: ビルド・確認コマンドを書く

これが一番効きます。「この記事をプレビューしたい」と毎回打つ代わりに、コマンドを名前付きで覚えさせる。

# コマンド
- ローカルプレビュー: hugo server -D
- 本番ビルド: hugo --minify
- リンク切れチェック: npx linkinator public/ --recurse

ここで初心者がやりがちな勘違いがある。CLAUDE.mdに書いたコマンドをClaudeが「自動で実行してくれる」わけではない。あくまで「次に料理ブログでビルドしたいと言われたら、このコマンドを使う」という参照情報として読まれるだけ。実行はBashツール経由で別途承認が要ります。

ステップ4: 「やってほしくないこと」も書く

禁止事項を書くと、暴走を未然に防げます。料理ブログだと「過去記事の本文を勝手に書き換えない」が一番大事。

# やらないでほしいこと
- content/posts/ 配下の既存記事本文を編集しない（誤字修正の依頼があった時のみ）
- config.yml の baseURL と theme は変更しない
- public/ ディレクトリは hugo の出力先なので直接編集しない

ステップ5: 個人のクセは CLAUDE.local.md に分ける

「私はサンプルレシピをrecipes-test/フォルダで試している」みたいな、チームに共有したくない前提はCLAUDE.local.mdに書く。これは .gitignore（=Gitに含めないファイル一覧）で除外しておけば、自分の環境だけに残ります。

# CLAUDE.local.md（.gitignore済み）
- ローカル確認用のサンドボックス記事は recipes-test/ 配下
- 公開前のドラフトは drafts/ に置く
- 個人用のメモ画像は static/images/_scratch/ に置く（公開しない）

ステップ6: 育ったら .claude/rules/ に分割する

運用していくとCLAUDE.mdが200行を超えてくる。公式ドキュメントは「200行以内を目標に」と明記しているので、超えたら.claude/rules/配下にトピック別ファイルへ切り出す。

料理ブログ/
├── CLAUDE.md           # プロジェクト全体の前提（短く）
└── .claude/
    └── rules/
        ├── images.md   # 画像の置き場・命名（hero/step）
        ├── posts.md    # 記事の書き方・frontmatter
        └── seo.md      # メタ・OGP・サイトマップ

さらにpaths:フロントマター（=ファイル冒頭のYAMLブロック）を付けると、特定のファイルを触る時だけ読み込まれるルールになる。images.mdをstatic/images/**に限定すれば、記事を書いている時にコンテキストを食わずに済みます。

つまり CLAUDE.md は何をしてくれるのか

• やってくれる: 毎セッションの最初に自動で読み込まれる。プロジェクト固有の前提（コマンド・命名・禁止事項）を文脈として保持する
• やってくれない: 強制力はない。書いた指示を100%守る保証はない。曖昧な指示はだいたい無視される
• 意味が薄い場面: 1回しか触らないリポジトリ。会話の中で1回伝えれば終わる内容。手順が長すぎてSkill（=必要な時だけ呼び出せる手順書）に分けた方がいい場合

使いどころ3シナリオ

シナリオ1: チームで共有するコーディング規約を効かせたい

5人のフロントエンドチームでReactコンポーネントを書いている。インデント幅、命名規則、テストの粒度を毎回口頭で揃えるのが面倒。./CLAUDE.mdに「2スペースインデント、コンポーネント名はPascalCase、各コンポーネントに*.test.tsxを必須」と書いてGitに含める。これでチーム全員のClaude Codeが同じ前提で動きます。

シナリオ2: モノレポ（=複数プロジェクトを1つのリポジトリにまとめた構成）の中で領域別ルールを効かせたい

ECサイトの巨大リポジトリで、frontend/はTypeScript、backend/はGo、infra/はTerraformと言語が違う。ルートのCLAUDE.mdに全部書くと200行超えで読まれにくくなる。.claude/rules/frontend.mdにpaths: ["frontend/**/*.{ts,tsx}"]を付けて、フロント作業の時だけ読み込ませる。コンテキスト消費を抑えつつ、領域ごとに濃いルールを効かせられます。

シナリオ3: 個人の手癖を全プロジェクトで効かせたい

「日本語コミットメッセージを使う」「変数名は省略しない」「説明はコメントじゃなく関数名に込める」みたいな、自分の中で固まっているクセを毎回CLAUDE.mdに書くのが面倒。~/.claude/CLAUDE.md（=ホームディレクトリのユーザー全体設定）に1度書いておけば、全プロジェクトで自動適用されます。プロジェクト固有のCLAUDE.mdより優先度は低いので、特定プロジェクトで上書きしたい時はそちらに書けば勝ちます。

初心者が踏みやすい落とし穴

• 200行を超えると守られにくくなる。公式ドキュメントは「200行以内を目標に」と明示している。超えてきたら.claude/rules/に分割するか、不要なルールを削る
• CLAUDE.mdは「強制」ではなく「文脈」。どれだけ厳しく書いてもClaudeが守るとは限らない。重要な強制（特定ツールの禁止、サンドボックス）はCLAUDE.mdではなくsettings.json側のpermissionsで書く必要がある
• 個人のクセを./CLAUDE.mdに書いてGitに含めるとチームに迷惑。「自分のサンドボックスURL」「個人の好みのテストデータ」はCLAUDE.local.mdに書いて.gitignoreで除外する
• 曖昧な指示は無視されがち。「ちゃんと書いて」「いい感じに整理して」は守られない。「2スペースインデント」「コミット前にnpm testを流す」のように検証可能な粒度にする
• 矛盾する指示が混在すると、Claudeはどちらか勝手に選ぶ。階層上のCLAUDE.mdとサブディレクトリのCLAUDE.mdで違うことを書いていると挙動がブレる。定期的に見直して矛盾を消す
• @path/to/fileでインポートしてもコンテキストは減らない。インポートされたファイルも起動時に展開されて読み込まれる。整理目的には使えるが、容量削減目的なら.claude/rules/のpaths-scopeを使う
• /initで雛形を作っただけで放置しない。雛形は観察事実の羅列でしかない。「同じ訂正を2回打ちそうな前提」を私の言葉で追記してこそ効くファイルになる
• AGENTS.md（=他のAIエージェント向け共通指示ファイル）と混同しない。Claude CodeはCLAUDE.mdしか読まない。AGENTS.mdを使っているリポジトリなら、CLAUDE.md側で@AGENTS.mdとインポートして共通化する

書き方

./CLAUDE.md または ./.claude/CLAUDE.md（プロジェクト共有）／ ~/.claude/CLAUDE.md（ユーザー全体）／ ./CLAUDE.local.md（個人プロジェクト用、.gitignore対象）

やってみるとこうなる

入力

# 料理ブログ

# コマンド
- ローカルプレビュー: hugo server -D
- 本番ビルド: hugo --minify

# 画像
- 画像は static/images/recipes/{slug}/ 配下
- サムネは hero.jpg、本文挿絵は step-{n}.jpg

# やらないでほしいこと
- content/posts/ 配下の既存記事本文を編集しない

出力例

（出力されるファイルではなく、Claude Codeが起動時に上記内容をコンテキストに読み込み、以降のセッションで「料理ブログのプレビューを立ち上げて」と頼むと hugo server -D を提案するようになる、という挙動になる）

関連項目

• /init（イニット）
• /agents（エージェンツ）
• Skills（スキルズ）
• /settings（準備中）
• /memory-command（準備中）

公式ドキュメント

https://code.claude.com/docs/en/memory