コアコンセプト

CLAUDE.md：AI にプロジェクトを本当に理解させる

Q: 適切なサイズは？

公式上の目安は ファイルあたり 200 行未満です。超えるとコンテキスト費用が上がり、遵守率も下がります（2026-09-21 確認）。モジュール固有の内容は path スコープのルールに分割し、該当ファイルの時だけ読み込みます。

1 つのファイルでプロジェクト仕様、設計判断、チーム規約を永続的に記録 — Claude はセッション開始時に必ず読み込みます

更新日 2026-10-08

#CLAUDE.md #ProjectMemory #BestPractices

CLAUDE.md とは？

CLAUDE.md はプロジェクトルートに置く特別なファイルで、Claude Code が起動時に自動で読み込みます。AI への「プロジェクトブリーフィング」として、技術スタック、コーディング規約、ディレクトリ構造、主要コマンドを含み、繰り返し説明なしでプロジェクトコンテキストを理解させます。2026-10-07 時点：リポジトリに AGENTS.md だけがあり CLAUDE.md がない場合、Claude Code 2.1.277 以降は代わりに AGENTS.md を読みます。

公式ドキュメントでは「毎回口で説明してきたこと」を書き置く場所と位置づけています。どのセッションでも必要な事実だけを残し、単発タスクの詳細は会話側に置きます（2026-09-21 確認）。

プレーンテキストのファイル

リポジトリの中の普通の markdown ファイルです。自分で書き、Git にコミットし、他のファイルと同じく読めるし diff も取れます。公式では、Claude Code がセッション開始時に必ず読むと明記されています（2026-09-21 確認）。

起動時に自動で読まれる

作業ディレクトリとその上位階層の CLAUDE.md は起動時にまとめて読まれます。サブディレクトリのファイルは、Claude がそこを読むときに入ってきます（2026-09-21 確認）。

設定ではなく文脈

毎セッションコンテキストウィンドウに読み込まれ、会話と一緒に token を消費します。厳密に守られる保証はなく、公式の言い方では設定ではなく文脈です（2026-09-21 確認）。

なぜ CLAUDE.md が必要？

維持する効果は次の三点に集約されます。セッション冒頭の背景説明が不要になる、誰が依頼しても同じ形式の出力になる、新規メンバーが口伝なしで立ち上がれる、となります。

繰り返しの排除

「TypeScript を使っています」「テストは Jest」と毎回説明する必要なし — 一度書けば永続有効

出力の一貫性

コーディングスタイル、命名規約、アーキテクチャ制約を定義し、Claude の出力をプロジェクト基準に統一

チーム知識の共有

新メンバー参加時、CLAUDE.md は AI 設定であると同時に人間向けのプロジェクト入門ガイドとしても機能

推奨テンプレート

優れた CLAUDE.md には通常以下のセクションが含まれます

CLAUDE.md

# プロジェクト概要

- 注文管理バックエンド。Web とミニプログラム向け REST API
- 新規参加者はまず本書、次に入門ガイドを読む
- API 変更前にクライアント側の同期要否を確認する

## 技術スタック

- 言語は TypeScript、実行環境は Node.js、パッケージ管理は pnpm
- データは PostgreSQL、頻出の読み取りは Redis
- テストは Vitest、カバレッジは CI で担保

## ディレクトリ構成

- src/api：HTTP 受付口と引数検証。ビジネスルールは置かない
- src/domain：ビジネスルールのみの層
- tests：src と同じ名前でミラー構成にし、失敗箇所を探しやすい

## コーディング規約

- インデントは半角スペース二つ、引用符は一重、セミコロンは残す
- 命名は略さずフルスペル
- domain 層にフレームワーク由来の型を出さない

## よく使うコマンド

- npm run dev：ローカル起動
- npm test：単体テスト全件、終了前に必ず通す
- npm run lint：コミット前に一度

## 注意事項

- シークレットと内部 URL は本書に書かず環境変数で扱う
- マイグレーションはまずシャドウ DB で実行
- 境界ケースが不明なら推測せず確認する

上級テクニック

この五つの項目で、ファイルが実際に守られるのか、誰も読まない騒音になるのかが決まります。項目ごとに、自分のファイルへ当てはめる判断基準を示します。

繰り返し使うものだけ

基準は明快です。この行は次のセッションでも生きますか。ビルドコマンド・命名規則・はまった箇所は該当し、ディレクトリ一覧や依存リストは該当しません。これらは Claude がコードから読み取ります（2026-09-21 確認）。

200 行以内に抑える

公式ドキュメントの目安はファイルあたり 200 行未満です。超えるとコンテキストを圧迫し遵守率も落ちます（2026-09-21 確認）。収まらなければ path スコープのルールに分割し、該当ファイルを読んだ時だけ読み込みます。

検証できる形で書く

「コードをきれいに書く」に情報はなく、「インデントは半角スペース二つ、単一引用符、コミット前に npm test を実行」なら遵守できます。小見出しとリストでグループ化すれば、Claude は読者と同じように構造をたどります（2026-09-21 確認）。

生成してから削る

白紙から始めないでください。/init がコードベースを解析し、ビルドコマンド・テスト方法・検出した規約を初期案にします。続いて /doctor の発想で冗長さを削り、はまった箇所と理由を残し、最後に /context で読込を確認します（2026-09-21 確認）。

秘密情報は置かない

このファイルは Git に入り、全員・全セッションで読まれます。シークレット・内部 URL・テスト用アカウントは環境変数に逃がし、個人嗜好は CLAUDE.local.md に分けて .gitignore に入れます（2026-09-21 確認）。

チーム協業規約

複数人プロジェクトでの CLAUDE.md 管理ベストプラクティス

コード同様のレビュー

プロジェクト用ファイルは個人メモではなくチーム資産です。コードと同じ PR で変更し、理由を明記し、該当ディレクトリの責任者をレビュワーに。公式の位置づけは「プロジェクト指令はバージョン管理で共有」（2026-09-21 確認）。

読込順と衝突

上位ディレクトリのファイルが先にコンテキストへ入り、サブディレクトリは必要に応じて後から読まれます。内容は上書きではなく連結です。同じ挙動を違う書き方で二か所に書くと Claude がランダムに一方を選ぶ場合があるため、文言を統一するか一方を削除します（2026-09-21 確認）。

モジュール別に分割

大きいリポジトリでルートに全部詰め込まないでください。モジュール固有の内容はサブディレクトリの CLAUDE.md か path スコープのルールへ移し、読まれた時だけコンテキストに入ります（2026-09-21 確認）。

CI で見張る

二つを定型化しましょう。CI でルートの CLAUDE.md の存在と合意規模内であることを検査し、アーキテクチャ変更の PR ごとに既存項目を見直します。公式も陳腐化・矛盾項目の定期削除を求めています（2026-09-21 確認）。

よくある失敗

以下四つはいずれもファイルを助けから厄介ごとにします。書き直さずに直せます。

単発タスクの書き込み

あるバグの再現手順やリファクタリングの途中結論をそのまま貼り込むと、次のセッションでも場所を占有し、汎用規約は一つも書かれていません。こうした内容は issue か PR の説明に書きます（2026-09-21 確認）。

終わりなく伸びる

公式ドキュメントの目安は 200 行です。超えるとコンテキストを多く消費し、遵守もされにくくなります（2026-09-21 確認）。一行増やす肥大化対策は逆効果なので、特定ディレクトリ専用の内容を外へ移します。

互いに矛盾する記述

ルートでは pnpm、サブディレクトリでは npm と書けば、Claude がどちらかを選ぶ可能性があります（2026-09-21 確認）。テーマごとに正しい記述を一か所だけ残し、他からは参照でつなぎます。

書きっぱなし

フレームワークもディレクトリ構成も変わったのに、ファイル内のコマンドは過去のままです。公式は各階層の定期的な見直しと、陳腐化・矛盾項目の削除を求めています（2026-09-21 確認）。アーキテクチャ変更の PR に載せるのが手軽です。

よくある質問

CLAUDE.md は毎回手渡し？

不要です。作業ディレクトリかその上位の CLAUDE.md はセッション開始時に自動で読まれ、サブディレクトリのファイルはそこを読む際に入ってきます。実際にどれが読まれたかは /context の Memory files で確認できます（2026-09-21 確認）。

適切なサイズは？

公式上の目安はファイルあたり 200 行未満です。超えるとコンテキスト費用が上がり、遵守率も下がります（2026-09-21 確認）。モジュール固有の内容は path スコープのルールに分割し、該当ファイルの時だけ読み込みます。

AGENTS.md との関係を教えて

デフォルトは二者択一です。作業ディレクトリかその上に CLAUDE.md があれば AGENTS.md は読まれません。両方使うなら /config の設定パネルで Project instructions を両方読む値にするか、CLAUDE.md 内で @AGENTS.md を明示的に読み込みます（2026-09-21 確認）。2026-10-07 追記：この挙動は Claude Code 2.1.277（2026-09-18 公開）から。変更履歴の原文は「Added AGENTS.md support: in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead」。2.1.281（2026-09-23）以降は LLM ゲートウェイ経由のセッションでも有効。