CLAUDE.md 書き方ベストプラクティス｜設計パターン・300行ルール完全ガイド

CLAUDE.md には「Claude がコードを読んでも分からないこと」だけを書き、1ファイル200行未満に収めます。これが Anthropic 公式の目安です。 よく聞く「300行ルール」は公式の数字ではありません。コミュニティで広まった目安で、「これを超えたら必ず分ける」という危険ラインとして使うのが現実的です。

この記事は、Claude Code 公式ドキュメントと CHANGELOG（2026年10月時点の最新版 v2.1.301）をもとに書いています。ここ数か月で CLAUDE.md まわりの仕様は大きく変わりました。主な変更は次の4つです。

• AGENTS.md を Claude Code が直接読むようになった（v2.1.277 以降。CLAUDE.md が無いリポジトリでは AGENTS.md を読む）
• /doctor prompt-audit が追加された（v2.1.283 以降。古い指示・存在しないパス・矛盾を見つける）
• path-scoped rules の読み込み漏れが直った（Write/Edit は v2.1.288、Bash の単一ファイル閲覧は v2.1.293 で修正）
• 起動時の警告がファイルの合計量も数えるようになった（v2.1.281。1ファイルの読み込み上限は 4 MiB）

この記事でわかること

• CLAUDE.md の役割と、Claude Code がいつ・どう読み込むか
• 60行・200行・300行・4 MiB という数字の出どころと使い分け
• 配置場所（4つのスコープ）と読み込み順
• 書くこと・書かないことの線引き
• プロジェクト規模別の設計パターン（小規模・中規模・大規模・モノレポ）
• @import と .claude/rules/ による分割の正しい使い方
• CLAUDE.md / rules / Skill / Hook / Subagent / Auto memory の使い分け
• 指示が守られないときの原因と直し方
• AGENTS.md と1つのファイルで共用する方法（2026年10月の仕様）
• コピーして使えるテンプレート3種

誰向けの記事か

• Claude Code を導入したが、CLAUDE.md に書いた指示が守られずに困っている開発者
• チームで CLAUDE.md の運用ルールを決めたいテックリード・エンジニアリングマネージャー
• 長くなった CLAUDE.md を分割・整理したいプロジェクトオーナー
• Cursor や Codex と併用していて、AGENTS.md との関係を整理したい人
• 組織全体にルールを配りたい IT・DevOps 担当者

Claude Code 自体の機能や料金は Claude Codeとは と Claude Codeの料金 にまとめています。

CLAUDE.md とは：Claude Code が毎回読み込む永続コンテキスト

CLAUDE.md は、Claude Code がセッションを始めるたびに読み込む、人が書く Markdown の指示ファイルです。公式ドキュメントでは "instructions you write to give Claude persistent context" と説明されています。決まった書式はなく、短く人が読める形で書くよう勧められています。

構造について押さえておきたい事実は3つです。

1. 毎セッション、全文が読み込まれる。公式の比較表でも、CLAUDE.md は「セッション開始時に全文・毎リクエスト」に載る扱いです。長いほどトークンを使います
2. システムプロンプトではなく、システムプロンプト直後のユーザーメッセージとして渡される。公式は "Claude treats them as context, not enforced configuration" と書いており、強制力のある設定ではありません
3. コードから推測できないことを書くためのファイル。言語の標準的な書き方や、見れば分かるディレクトリ構成を書いても効果は薄いです

2つ目の「強制力がない」点は、指示が守られない問題を考えるときの出発点になります。どうしても止めたい操作は、CLAUDE.md ではなく Hook や権限設定で止めるのが公式の考え方です。

書き足すタイミング（公式の4つの合図）

公式ドキュメントは、CLAUDE.md に書き足すべきタイミングを次のように挙げています。

• Claude が同じミスを2回した
• コードレビューで「Claude が知っておくべきだった」指摘が出た
• 前のセッションと同じ訂正をまたチャットで打っている
• 新しいメンバーにも同じ説明が必要になる

逆に、複数の手順からなる作業手順書や、一部のコードにしか関係しない規約は CLAUDE.md に入れず、Skill か path-scoped rule に分けるよう公式は勧めています。

なぜ CLAUDE.md が重要か

出典: Anthropic - Introducing Claude Code

CLAUDE.md の出来は、Claude Code の使い勝手を大きく左右します。書いておくと次のような効果があります。

• 同じ説明を毎回しなくて済む：ビルドコマンドや規約を1回書けば、以後のセッションに引き継がれる
• チームで Claude の振る舞いをそろえられる：git で管理すれば、変更を PR でレビューできる
• 推測ミスを減らせる：ポートの競合や独自のテストランナーなど、コードからは分からない事情を伝えられる

ただし、長く書けば効果が上がるわけではありません。公式のベストプラクティスには次の警告があります。

Bloated CLAUDE.md files cause Claude to ignore your actual instructions!

ルールが多すぎると、大事な指示がほかの行に埋もれて守られにくくなります。Anthropic の公式ブログ（2026年6月）も「CLAUDE.md の1行1行が、リポジトリで作業する全エンジニアの全セッションに読み込まれる」と書いています。書く量を絞り、粒度と構成を整えることが、そのまま指示の守られやすさにつながります。

60 行・200 行・300 行ルールの真相

出典: HumanLayer - Writing a good CLAUDE.md

公式の目安は200行未満です。300行は公式の数字ではなく、公式が数字を出していなかった時期に広まったコミュニティの目安です。数字ごとに出どころが違うので、整理しておくと迷いません。

公式は「200 行未満」で一貫している

Anthropic の公式ドキュメントと公式ブログは、どれも200行を目安にしています。

• Memory のページ："target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence."
• 機能の使い分けのページ："Rule of thumb: Keep CLAUDE.md under 200 lines."
• 公式ブログ「Steering Claude Code」（2026年6月）："Keep CLAUDE.md under 200 lines, give it an owner, and review changes to it like code."

公式のベストプラクティスは、削る基準も示しています。各行について「この行を消したら Claude はミスをするか？」と問い、しないなら削る、というものです。

「300 行ルール」はコミュニティ発の目安

日本語圏で広まった「300行を超えると崩れる」という話は、HumanLayer のブログ記事「Writing a good CLAUDE.md」（2025年11月）で紹介された目安がもとになっています。この記事は「Anthropic に公式の上限はない」としたうえで、「一般的な合意は300行未満、短いほど良い」と書いています。HumanLayer 自身が提唱したというより、当時の合意を記事にしたものと読むのが正確です。

同じ記事には次の観察もあります。

• HumanLayer 自社のルート CLAUDE.md は 60行未満
• 研究によると、最先端の思考モデルが安定して守れる指示は 150〜200個程度
• 指示が増えると、特定の指示が無視されるのではなく、全体の遵守率が一様に下がる

なお、指示数の研究は HumanLayer の記事経由の引用で、原論文は確認できていません。

技術的な上限は 4 MiB

行数とは別に、読み込みには技術的な上限があります。公式によると、CLAUDE.md は 4 MiB までは全文を読み込み、それを超えるファイルは読み込みません。また、推奨の長さを超えるファイルがあると、起動時と /status で警告が出ます。v2.1.281 からは、1つずつは推奨内でも、CLAUDE.md・rules・@import 先の合計が多すぎる場合にも警告が出るようになりました。合計の具体的な閾値は公式に書かれていません。

4つの数字の使い分け

おすすめは「200行未満を目標にし、300行を超えていたら最優先で分ける」という運用です。

参考までに、このメディアを運営するリポジトリの CLAUDE.md は、運用の詳細を別ファイルに分けた後でも2026年10月時点で約310行あります。毎時のキュー運用や画像ルールなど、毎回必要な決まりを足していくうちに膨らみました。公式の目安を超えている実例として、この状態から何を削るか、何を rules や Skill に移すかが課題になっています。

配置場所と優先順位：4 階層のスコープ

CLAUDE.md は4つのスコープに置けます。どこに置くかで、誰に効くかが決まります。

このほか、.claude/rules/*.md（プロジェクト）と ~/.claude/rules/（ユーザー）にルールを分けて置けます。ユーザーのルールはプロジェクトのルールより先に読まれます。

優先順位と「連結」の仕組み

複数の CLAUDE.md があっても、どれか1つで上書きされるわけではありません。すべてが連結されてコンテキストに入ります。

• 起動したディレクトリと、その上位すべての CLAUDE.md / CLAUDE.local.md を起動時に読む
• 並び順はルート側が先、作業ディレクトリ側が後。起動場所に近い指示ほど後ろに来る
• 同じ階層では、CLAUDE.local.md が CLAUDE.md の後に来る

たとえばモノレポで /repo/CLAUDE.md と /repo/apps/web/CLAUDE.md があり、apps/web で起動すれば両方が読まれます。親に共通ルール、子にそのパッケージ固有のルールを置くのが基本形です。親子で矛盾する指示があると、Claude はどちらか一方を選んでしまいます。公式も「矛盾があると Claude は恣意的にどちらかを選ぶ」と注意しています。

起動時に実際に読まれたファイルは、/context の Memory files 欄で確認できます。

サブディレクトリ内の CLAUDE.md は on-demand

src/api/CLAUDE.md のようなサブディレクトリの CLAUDE.md は、起動時には読まれません。Claude がそのディレクトリ内のファイルを Read / Write / Edit したときに読み込まれます。v2.1.293 以降は、Bash で cat や head を使って1つのファイルを見た場合も対象です。

細かいドメインの規約をサブディレクトリに置けば、普段のトークン消費を抑えつつ、必要なときだけ効かせられます。

--add-dir で追加したディレクトリの CLAUDE.md は別途オプトイン

--add-dir で追加したディレクトリの CLAUDE.md は、既定では読まれません。読ませたい場合は環境変数を付けて起動します。

CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared-config

これで追加ディレクトリの CLAUDE.md・.claude/CLAUDE.md・.claude/rules/*.md・CLAUDE.local.md が読まれます。

注意したいのは、settings.json の additionalDirectories で追加したディレクトリです。こちらはこの環境変数を付けても CLAUDE.md が読まれません（Skill も読まれません）。共有の指示を読ませたいなら、--add-dir か /add-dir を使います。

含めるべき内容 / 含めるべきでない内容

出典: Claude Blog「Using CLAUDE.md files」

判断の基準は1つで、「Claude がコードを読んで推測できるか」です。推測できないことだけを書きます。公式のベストプラクティスは次のように整理しています。

検証できる書き方にする

公式は、守れたかどうかを確かめられる書き方を勧めています。

強調表現の使い方にも注意が要ります。IMPORTANT などは、何度書いても守られない1行だけに付けます。公式は「多くの行を強調すると、どれも目立たなくなる」と書いています。

リンターで強制できるものは書かない

インデント幅、クォートの種類、import 順、型チェックのように、ツールで機械的に強制できるルールは CLAUDE.md に書きません。

• インデント・クォート → ESLint / Biome / Prettier などのフォーマッタ
• import 順 → 自動整形ツール
• 型の安全性 → TypeScript コンパイラ

HumanLayer の記事は "Never send an LLM to do a linter's job" と表現しています。公式も、指示がなくても Claude が正しくできていることは削るか Hook に移すよう勧めています。フォーマッタやリンターを Hook（たとえば編集後や Stop 時）で走らせれば、毎回確実に適用されます。

秘密情報は書かない

CLAUDE.md は git で共有され、毎回モデルに送られます。API キーや接続文字列そのものは書かず、「どの環境変数に入っているか」「.env.example を見る」といった場所だけを書きます。.gitignore に入れる CLAUDE.local.md でも、値は書かない運用にしておくと安全です。

基本構造：WHAT / WHY / HOW の 3 層モデル

短い CLAUDE.md でも、WHAT / WHY / HOW の3つに分けて書くと整理しやすくなります。HumanLayer の記事などで広く使われている構成です。

WHY は省かないでください。理由が書いてないと、Claude は似ているが違うケースで判断を誤ります。1〜2文の背景で十分です。

WHAT は、コードを読めば分かる内容（ディレクトリの一覧や依存パッケージの一覧）になりがちです。/doctor の削減案もこの種の行を削る対象にしているので、WHAT は「ここを見れば分かる」というポインタ程度に留めます。

プロジェクト規模別の設計パターン

規模が大きくなるほど、1枚の CLAUDE.md から rules・サブディレクトリ・Skill へ分けていきます。次の表の規模の区分は公式のものではなく、編集部の目安です。

小規模プロジェクト：まず 1 枚で

個人開発や小さなプロジェクトなら、ルートの CLAUDE.md 1枚で足ります。/init で叩き台を作り、WHAT / WHY / HOW を30〜60行に収め、困ったときに書き足すのが一番手間がかかりません。

中規模：.claude/rules/ でドメイン別に分割

ファイルが増えてくると CLAUDE.md が長くなりがちです。そうなったら .claude/rules/ にルールを切り出します。

your-project/
├── CLAUDE.md                     # 全体の指示（100行程度まで）
└── .claude/
    └── rules/
        ├── code-style.md         # コードスタイル
        ├── testing.md            # テスト規約
        └── security.md           # セキュリティ要件

.claude/rules/ 配下の .md は再帰的に見つけられ、paths: が無いものは起動時に .claude/CLAUDE.md と同じ優先度で読み込まれます。@import を書く必要はありません。

ただし、paths: の無いルールは毎回読まれるので、コンテキストの量は1枚にまとめた場合と変わりません。量を減らしたいなら paths: を付けます。

複数プロジェクトで共通ルールを使い回すなら、symlink も使えます。作業ディレクトリの外を指す symlink は外部 import と同じ承認が必要で、承認後も paths: の無いルールだけが読まれます。ネットワークパス（UNC、/net、/Network）を指す symlink は読まれません。

大規模・モノレポ：paths: フロントマターで条件付きロード

ルールを毎回読むとコンテキストが圧迫される規模では、paths: フロントマターで読み込む条件を付けます。

---
paths:
  - "src/api/**/*.ts"
---

# API 開発ルール
- すべてのエンドポイントで入力値を検証する
- スキーマ検証には Zod を使う

このルールは、Claude が src/api/ 以下の TypeScript ファイルを Read / Write / Edit したとき（Bash での単一ファイル閲覧を含む）だけ読み込まれます。

path-scoped rules の注意点（2026年10月時点）

以前は「paths: 付きルールは Read のときしか読まれず、新規作成や編集では効かない」という制約がありました。これは修正済みです。

• v2.1.288：Write / Edit でも path-scoped rules とサブディレクトリの CLAUDE.md を読むよう修正
• v2.1.293：Bash の cat / head / tail / sed -n / grep による単一ファイルの閲覧でも読むよう修正

古いバージョン向けに「ルート CLAUDE.md にも同じ指示を二重に書く」回避策を入れていた場合は、アップデート後に外して構いません。現在注意すべき点は次の3つです。

• ルールで読まれるフロントマターは paths だけ。ほかのフィールドを書いても無視される
• YAML の書式が正しくないと、paths が無い扱いになって常に読み込まれる。効かないときは claude --debug でエラーを確認する
• ブレース展開には上限がある。1つのルールの paths 全体で、展開後1,000パターン・4 MiB まで

@import による構造化と Progressive Disclosure

CLAUDE.md は @パス の記法で別ファイルを取り込めます。

プロジェクトの概要は @README.md、使える npm コマンドは @package.json を参照。

# 追加の指示
- Git の運用: @docs/git-instructions.md
- 個人用の上書き: @~/.claude/my-project-instructions.md

仕様の要点は次のとおりです。

• 相対パスと絶対パスが使える。相対パスは書いたファイルからの位置で解決される
• 取り込んだ先がさらに取り込むのは 最大4ホップまで
• パスに空白があるときはバックスラッシュでエスケープする（@Design\ Docs/api-conventions.md）。引用符で囲むと読まれない
• コードスパンやコードブロックの中の @ は無視される
• プロジェクトの外（ホームディレクトリなど）を取り込むと、初回に承認ダイアログが出る。拒否すると以後は無効
• @import で分けてもコンテキストの量は減らない。読み込み時に展開されるため

最後の点は誤解が多いところです。@import は整理のための仕組みで、量を減らしたいなら paths: 付きの rules か Skill を使います。

Progressive Disclosure（段階的開示）パターン

長くなった CLAUDE.md を整理する定番の方法が、情報を段階に分けて必要なときだけ読ませる Progressive Disclosure です。

1. ルートの CLAUDE.md（最小限）：毎回必要な事実だけ。100行未満が目安
2. Skill（.claude/skills/<name>/SKILL.md）：作業ごとの手順。普段は説明文だけが読まれ、本文は使うときに読まれる
3. 詳しい資料（docs/ など）：リファレンス。CLAUDE.md や Skill から「このときはここを読む」と案内する

# 詳しい資料（作業するときに読む）
- DB スキーマを変えるとき: docs/db-migration.md を読む
- API エンドポイントを追加するとき: docs/api-conventions.md を読む
- 決済モジュールを直すとき: docs/billing-rules.md を読む

ここでは @ を付けていない点に注意してください。@docs/... と書くと起動時に全文が展開されます。必要なときだけ読ませたいなら、パスを書いて「読む」と指示する形にします。HumanLayer の記事も、コード片を貼るより file:line のような参照を書くほうが古くなりにくいと勧めています。

CLAUDE.md / Skill / Hook / Subagent の使い分け

出典: GitHub anthropics/skills

毎回必要な事実は CLAUDE.md、一部のファイルだけの規約は rules、手順は Skill、必ず実行・必ず禁止したいことは Hook と権限設定という分け方が基本です。公式ブログ「Steering Claude Code」（2026年6月）は、CLAUDE.md・rules・Skill・Subagent・Hook・Output style・--append-system-prompt の7つの手段を挙げ、"Instructions that are procedural... belong in a skill rather than in CLAUDE.md." と書いています。

CLAUDE.md から外に出すべきものは、次の3つです。

1. 例外なく毎回実行したい処理 → Claude Code Hooks の使い方
2. 特定の作業だけの長い手順 → Claude Code Skills 活用ガイド
3. 大量のファイルを読む調査 → Claude Code サブエージェントの使い方

サブエージェントも CLAUDE.md を読み込みます（組み込みの Explore / Plan エージェントは読みません）。v2.1.271 からは、エージェント定義に omitClaudeMd を付けると、ユーザー・プロジェクト・ローカルの CLAUDE.md を読まずに起動できます。調査専用のエージェントなど、プロジェクト規約が要らない用途でトークンを節約できます。

Skill と Hook のどちらにするか迷う場合は、Claude Code Skills vs Hooks 使い分けガイド で詳しく比べています。

何が起きたら何を足すか（公式の育て方）

公式の「Build your setup over time」は、困りごとに応じて足す仕組みを次のように示しています。

Auto Memory との関係（v2.1.59 以降）

出典: Claude Code Docs「How Claude remembers your project」

Auto memory は、Claude が作業中に学んだことを自分で書き残す仕組みです。人が書く CLAUDE.md とは役割が違います。

使い分けの基本

• CLAUDE.md：守ってほしいことをはっきり書く場所
• Auto memory：Claude が観察して覚えたことの置き場所

チャットで「覚えて」と頼むと、内容は Auto memory に入ります。チーム全員に効かせたいなら、「CLAUDE.md に追加して」と明示してください。Auto memory はマシンの中だけに保存され、ほかのメンバーやほかの PC とは共有されません。

Auto Memory の制御

• 既定でオン。/memory の切り替え、プロジェクト単位の "autoMemoryEnabled": false、環境変数 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 で止められる
• 保存先は autoMemoryDirectory で変えられる
• MEMORY.md が索引で、トピックごとのファイルは必要なときに読まれる
• MEMORY.md が上限を超えると、Claude に書き直しを促すエラーが出る

同じ内容を CLAUDE.md と Auto memory の両方に書くと重複します。明示したいルールは CLAUDE.md、細かい学びは Auto memory と分けておきます。

ルールが守られないときの根本原因と対策

守られない原因は、強制力がない・読み込まれていない・長すぎる・曖昧または矛盾しているの4つにほぼ分けられます。まずは「そもそも読まれているか」から確かめます。

原因 1：ユーザーメッセージとして注入される

CLAUDE.md はシステムプロンプトの直後に、ユーザーメッセージとして渡されます。公式も「厳密な遵守は保証されない」という立場です。会話の途中で別の指示を出せば、そちらが優先されることもあります。

対策

• 例外なく止めたい操作は Hook（PreToolUse）や permissions.deny で止める
• スクリプトからの実行でシステムプロンプト側に指示を入れたいなら --append-system-prompt を使う

公式ブログは、絶対に禁止したいことを CLAUDE.md に頼らない理由として、急いでいるときやプロンプトインジェクションを受けたときに守られないことがあると書いています。

原因 2：そもそも読み込まれていない

書いたつもりのファイルが読まれていないケースです。

対策

• /context の Memory files 欄、または /memory で、読み込まれているファイルを確認する
• サブディレクトリの CLAUDE.md や paths: 付きルールは、該当ファイルに触れるまで読まれない
• /compact の後、ルートの CLAUDE.md は読み直されるが、サブディレクトリの CLAUDE.md と paths: 付きルールは、該当ファイルに再び触れるまで戻らない。会話で伝えただけの指示は消える
• Read の deny ルールや permissions.blockReadsOutsideWorkingDirectories に当たる CLAUDE.md は読まれず、"Instruction file not loaded" という通知が出る
• どのファイルがいつ読まれたかを記録したいなら、InstructionsLoaded フックを使う

原因 3：ファイルが長すぎる

指示が増えると、全体の遵守率が下がります。長い文書の途中にある情報ほど参照されにくいという研究（いわゆる Lost in the Middle）もありますが、Claude Code の公式ドキュメントにこの説明はありません。公式が言っているのは「長いほどコンテキストを使い、遵守率が下がる」という点です。

対策

• 200行を超えたら削る。「この行を消したら Claude はミスをするか？」と各行に問う
• /doctor の削減案と /doctor prompt-audit で、削れる行や古い指示を洗い出す
• 手順は Skill、一部のファイルだけの規約は paths: 付きルールへ移す

原因 4：表現が曖昧／複数 CLAUDE.md の間で矛盾

「適切に処理する」のような指示は、守れたかどうかの基準がありません。ユーザー・プロジェクト・サブディレクトリの CLAUDE.md で指示が食い違っていると、Claude はどちらかを選ぶしかありません。

対策

• 成否を判断できる書き方にする（「すべての関数に JSDoc を付ける」「エラーは AppError の派生クラスで投げる」）
• /doctor prompt-audit で、互いに矛盾するファイルを見つける
• モノレポで他チームの CLAUDE.md が混ざるなら claudeMdExcludes で外す

CLAUDE.md を点検する3ステップ（/doctor と prompt-audit）

2026年10月時点では、CLAUDE.md の棚卸しを Claude Code 自身に手伝わせられます。手作業で全行を見直す前に、次の3つを順に試すのが効率的です。

1. /doctor で削減案を出す：チェックインされた CLAUDE.md について、コードから導ける内容（ディレクトリ構成・依存一覧・アーキテクチャの概要）を削り、落とし穴・理由・ツールの既定と違う規約を残す案を出します
2. /doctor prompt-audit で監査する（v2.1.283 以降）：CLAUDE.md・CLAUDE.local.md・AGENTS.md、.claude/ と ~/.claude/ の rules・skills・commands・subagents・output styles を見て、「古いモデル向けに書かれた指示」「存在しないファイルやコマンドへの参照」「互いに矛盾するファイル」を報告します。修正案は報告だけで、頼むまで適用されません。/doctor prompt-audit .claude/skills/deploy のように範囲を絞ることもできます
3. /context で結果を確かめる：Memory files 欄で、読み込まれるファイルと量が減ったかを確認します

/doctor prompt-audit は別名 /checkup prompt-audit でも呼べます。同梱の /claude-api スキルを無効にしていると使えない点に注意してください。

公式は、大きなモデルのリリース後に CLAUDE.md を見直すことも勧めています。古いモデル向けに入れた回避策が、新しいモデルでは不要になっていることがあるためです。システムプロンプトを短くした事例は Claude Code のシステムプロンプト削減 で紹介しています。

CLAUDE.md テンプレート集

規模に合わせた3つのテンプレートです。そのまま使わず、自分のプロジェクトで「書かないと Claude が間違えること」だけを残してください。

ミニマル版（個人開発・小規模向け・30 行）

# MyApp

## 概要
TypeScript + Bun で書いた API サーバー。

## コマンド
- 開発サーバー: `bun run dev`
- 型チェック: `bun run typecheck`
- テスト: `bun run test`
- リント: `bun run lint`

## コーディング規約
- TypeScript の strict モードを使う
- for ループより map / filter / reduce を優先する
- エラーは `AppError` の派生クラスで投げる

## テスト
- 新しい機能には必ずテストを足す
- `describe` + `it` 形式。テスト名は日本語でよい

## 注意点
- DB マイグレーションは `bun run db:migrate` で行う。手動で `ALTER TABLE` しない
- `.env.local` は git 管理外。`.env.example` を見て作る

標準版（チーム開発向け・150 行程度・抜粋）

# EC サイト基盤

## 構成（WHAT）
Next.js App Router + TypeScript + Prisma + PostgreSQL。

## 設計判断（WHY）
- TypeScript strict: implicit any 由来の本番バグの再発防止
- Server Actions 優先。API Route は外部連携のときだけ
- 決済は Stripe に固定。他社との比較は済んでおり再検討しない

## コマンド（HOW）
- 開発: `pnpm dev`
- 型チェック: `pnpm typecheck`
- テスト: `pnpm test`（変更後は必ず実行）
- E2E: `pnpm e2e`（リリース前のみ）
- DB マイグレーション: `pnpm db:migrate`

## コーディング規約
- Server Components を優先。`use client` は必要な所だけ
- Prisma Client は `@/lib/prisma` から import する（直接 new しない）
- エラー処理は `@/lib/errors` のカスタムエラーを使う

## 決済まわり
- IMPORTANT: 金額計算は必ず Decimal 型で行う（number は使わない）
- 個人情報を含むログを出さない
- マイグレーションなしで DB スキーマを変えない

## 詳しい資料（作業するときに読む）
- API 設計: docs/api-conventions.md
- 決済モジュール: docs/billing-rules.md
- セキュリティ要件: docs/security.md

<!-- 決済の Decimal ルールは過去の端数処理の不具合を受けて追加。半年ごとに見直す -->

最後の HTML コメントは、Claude に渡る前に取り除かれます（コードブロック内のコメントは残ります）。ルールを足した経緯や見直しの予定を人向けのメモとして残しつつ、コンテキストは使わずに済みます。

大規模・モノレポ版（rules 活用）

monorepo-root/
├── CLAUDE.md                     # 全体共通のルール（80行程度）
├── .claude/
│   ├── rules/
│   │   ├── typescript.md         # TS 全般の規約（paths なし＝常に読む）
│   │   ├── api.md                # paths: src/api/**
│   │   ├── frontend.md           # paths: apps/web/**
│   │   └── infra.md              # paths: infrastructure/**
│   └── settings.local.json       # claudeMdExcludes で他チームの指示を外す
├── apps/
│   ├── web/CLAUDE.md             # フロント固有
│   └── admin/CLAUDE.md           # 管理画面固有
└── packages/
    └── core/CLAUDE.md            # コアライブラリ固有

公式のモノレポ向けガイドは、ルートに全体共通のルール（コミット規約など）、パッケージごとの CLAUDE.md にそのスタック固有のルール、という2段構成を勧めています。ルートに置く例文として公式が挙げているのは次のような指示です。

- パッケージのスクリプトは、モノレポのルートではなくパッケージのディレクトリで実行する
- packages/*/generated/ 以下のファイルは編集しない。代わりにそのパッケージで `npm run codegen` を実行する

サブディレクトリの CLAUDE.md と path-scoped rule のどちらを使うかは、管理する人で決めます。

モノレポ運用：claudeMdExcludes でノイズを除外

大きなモノレポで、他チームの CLAUDE.md や rules まで読み込まれてしまう場合は、claudeMdExcludes で外します。

{
  "claudeMdExcludes": [
    "**/packages/web/**",
    "**/packages/*/CLAUDE.md"
  ]
}

2つ目の例は、パッケージごとの CLAUDE.md だけを外し、ルートの CLAUDE.md は残す書き方です。

• パターンは絶対パスに対する glob
• user / project / local / managed のどこでも設定でき、配列は層をまたいでマージされる
• 個人用の除外は .claude/settings.local.json（git 管理外）に書くのがおすすめ
• 管理ポリシーの CLAUDE.md は除外できない
• symlink で置いたルールは、リンク側のパスでもリンク先のパスでも除外できる（v2.1.239 以降）

それでもルールが増え続ける規模になったら、公式は Skills や Plugins、社内ドキュメントを検索できる MCP サーバーへ移すことを勧めています。

組織導入：管理ポリシー CLAUDE.md と監査

会社で Claude Code を展開する場合、CLAUDE.md はルールを配る手段の1つになります。ただし、ここでもCLAUDE.md は指示であって強制ではない点は同じです。公式は目的ごとに次の使い分けを示しています。

管理ポリシー CLAUDE.md のデプロイ

管理者は OS ごとのシステムパスに CLAUDE.md を置いて、組織の全員に共通の指示を配れます。

• macOS：MDM（Jamf、Kandji など）で配布
• Windows：グループポリシーや Intune
• Linux：Ansible や Chef などの構成管理ツール

managed-settings.json の claudeMd キーに本文を直接書くこともできます。このスコープの CLAUDE.md は、開発者が claudeMdExcludes で外すことはできません。組織展開の全体像は Claude Code チーム導入ガイド、権限やセキュリティの設定は Claude Code のセキュリティと安全な使い方 で扱っています。

Claude Code の設定を整えたあと、社内の業務システムそのものに AI 機能を組み込みたいという段階に進む会社もあります。その場合の進め方と費用の目安は 既存システムにAIを組み込む方法 にまとめています。

InstructionsLoaded フックでロード履歴を監査（v2.1.69 以降）

InstructionsLoaded は、CLAUDE.md や .claude/rules/*.md が読み込まれたときに発火するフックイベントです（v2.1.69 で追加）。

• どのファイルが、いつ、なぜ読まれたかを記録できる
• 読み込みを止めたり内容を書き換えたりはできない
• 用途は監査ログや、path-scoped rule・サブディレクトリの読み込みのデバッグ
• v2.1.288 で、サブエージェント経由のときに agent_id / agent_type が抜ける不具合が直った

なお、設定経由で読み込んだ AGENTS.md では、このフックは発火しません。

Code Review はベースブランチの CLAUDE.md を使う

GitHub 連携の Code Review は、CLAUDE.md のルールを見てレビューします。PR の中で CLAUDE.md 自体を書き換えている場合は、ベースブランチ側の CLAUDE.mdが使われます。つまり、PR でルールを緩めてレビューをすり抜けることはできません。v2.1.295 では、大きな CLAUDE.md のルールをレビューが読み飛ばす不具合も直っています。CI での使い方は Claude Code GitHub Actions の使い方 を参照してください。

共有リポジトリを開くときの注意

他人がコミットした CLAUDE.md がプロジェクト外のファイルを @import していると、初回に承認ダイアログが出ます。公式はこれを「共有プロジェクトに他人がコミットしたファイルから利用者を守るため」と説明しています。承認する前に、取り込み先を一覧で確かめてください。CLAUDE.md は強制力のない指示なので、外部から入り込む指示（プロンプトインジェクション）への備えも別に必要です。実例は Claude Code Auto Mode が間接プロンプトインジェクションで突破された件 で解説しています。

AGENTS.md や他 AI ツールとの関係

出典: GitHub - anthropics/claude-code

v2.1.277 から、Claude Code は AGENTS.md を直接読めるようになりました。 以前は「Claude Code は AGENTS.md を読まないので、CLAUDE.md から @AGENTS.md で取り込む」のが定番でしたが、前提が変わっています。Cursor や Codex などと併用するチームは、既定の動きを知っておかないと「書いたのに読まれない」状態になります。

既定の動き：CLAUDE.md があると AGENTS.md は読まれない

落とし穴は2つあります。

• CLAUDE.local.md を置いただけで、AGENTS.md が読まれなくなる。個人用のメモを足した途端にチームの AGENTS.md が効かなくなる
• ~/.claude/CLAUDE.md、管理ポリシーの CLAUDE.md、.claude/rules/ は判定に数えない。これらは AGENTS.md と並んで読まれる

AGENTS.local.md、AGENTS.override.md、.agents/ 配下は読まれません。

/config の Project instructions で切り替える

/config → Project instructions で、読み込み方を4つから選べます。

settings.json で設定する場合のキーは pluginConfigs."cc-plugin-agents-md@builtin".options.instructionFiles です（v2.1.285 より前の ID は agents-md@builtin）。プロジェクト・ローカルの設定ファイルに書いても無視されます。

1 ソース化の戦略

チームで確実に同じ内容を読ませたいなら、今でも CLAUDE.md の先頭で @AGENTS.md を取り込む形が分かりやすいです。設定に左右されず、CLAUDE.local.md を置いても AGENTS.md が読まれ続けます。

@AGENTS.md

## Claude Code 固有の指示
- `src/billing/` 以下を変えるときは plan mode を使う

共通のルールは AGENTS.md、Claude Code だけに必要な指示は CLAUDE.md に書きます。

symlink（ln -s AGENTS.md CLAUDE.md）でも共用できますが、Claude の Edit / Write は symlink 越しには書き込みません。Windows では Git が symlink を通常のファイルとして展開することがあるため、公式も取り込み（import）を勧めています。

以前、SessionStart フックで AGENTS.md の中身を出力するなどの回避策を入れていた場合は、今の仕様では二重に読まれるので削除してください。

他ツールの設定から CLAUDE.md を作る

• /init は .cursor/rules/・.cursorrules・.github/copilot-instructions.md を取り込んで CLAUDE.md を作る。CLAUDE_CODE_NEW_INIT=1 のときは AGENTS.md・.devin/rules/・.windsurf/rules/・.windsurfrules・.clinerules も対象
• /import（v2.1.213 以降）は、他のエージェントの設定を取り込み、AGENTS.md などの内容を CLAUDE.md に一度だけ追記する。MCP・コマンド・サブエージェント・スキルも移せる

ツールごとの違いは Cursor と Claude Code の比較 や OpenAI Codex とは で整理しています。

関連コマンドと運用 Tips

CLAUDE.md の運用で使う主なコマンドです。スラッシュコマンド全体は Claude Code スラッシュコマンド完全ガイド にまとめています。

/init の結果はそのまま使わず、必ず手で削ってください。HumanLayer の記事も、1行ずつ意図して書くことを勧めています。

インタラクティブ /init（CLAUDE_CODE_NEW_INIT=1）

環境変数 CLAUDE_CODE_NEW_INIT=1 を付けると、/init が対話式になります。

• CLAUDE.md・Skills・Hooks のどれを作るかを選べる
• サブエージェントがコードベースを調べる
• 分からない点を質問してから、書き込む前に案を見せる

新しいプロジェクトを Claude Code 向けに整えるときに向いています。

圧縮しても残してほしい情報を書いておく

/compact で会話を圧縮しても、ルートの CLAUDE.md はディスクから読み直されます。長いセッションで何度も圧縮するなら、残してほしい情報を CLAUDE.md に書いておけます。公式の例は "When compacting, always preserve the full list of modified files and any test commands" です。

CLAUDE.md の「育て方」フレームワーク

CLAUDE.md は一度書いて終わりではありません。公式ブログは「200行未満を保ち、担当者を決め、コードと同じように変更をレビューする」ことを勧めています。git にコミットしてチームで育てるほど、価値が積み上がっていくファイルです。

書き加えるシグナル

• 同じ訂正を2回した
• コードレビューで「Claude が知っておくべきだった」指摘が出た
• 新しいメンバーが同じところでつまずいた
• 障害の再発防止策を決めた（「なぜダメか」を WHY として残す）

削るシグナル

• 指示がなくても Claude が正しくできるようになった
• リンターや型チェックで強制できるようになった
• 当たり前すぎる内容（「きれいなコードを書く」など）
• もう使っていない技術やコマンドの名残
• 大きなモデルのリリースがあった（古いモデル向けの回避策を見直す）

Skill / Hook / Subagent に移すシグナル

• 手順が長く、書くと CLAUDE.md が膨らむ → Skill
• 特定の作業（DB マイグレーションなど）でしか使わない → Skill か paths: 付きルール
• 例外なく毎回実行されないと困る → Hook
• 大量のコードを調べる作業 → Subagent

公式は、Stop フックでセッションを振り返らせ、CLAUDE.md の更新案を出させる運用も紹介しています。定期的な見直しは /doctor prompt-audit に任せ、人はその提案を PR でレビューする、という分担にすると続けやすくなります。

よくある失敗パターン

1. /init の結果をそのまま置いている：コードを読めば分かる内容が混ざる
2. リンターで強制できるルールを書いている：トークンを使い、ほかの指示の遵守率も下げる
3. 「適切に」「きれいに」などの曖昧な表現：守れたかどうかの基準がない
4. 200行を超えても放置：全体の遵守率が下がる
5. 強調表現を多用：IMPORTANT だらけで、どれも目立たない
6. WHY を書かない：似たケースで判断を誤る
7. 秘密情報や接続文字列を書く：git と毎回のリクエストで外に出る
8. CLAUDE.local.md を .gitignore に入れ忘れる：個人のパスやメモがコミットされる
9. CLAUDE.local.md を置いて AGENTS.md が読まれなくなる：既定の設定では CLAUDE.md 側だけが読まれる
10. @import で量を減らそうとする：取り込み先も全文読み込まれる
11. rules に paths 以外のフロントマターを書いて効くと思っている：paths 以外は無視される
12. 古いバージョン向けの回避策が残っている：path-scoped rules の二重書きや、SessionStart フックでの AGENTS.md 出力など

こんな方に向いています

• Claude Code をチームで本格的に使いたい人：指示をそろえ、PR でレビューできる
• プロジェクトの規約が複雑で、毎回説明している人：一度書けば引き継がれる
• モノレポや大きなコードベースを扱う人：サブディレクトリの CLAUDE.md、paths: 付きルール、claudeMdExcludes で必要な指示だけを読ませられる
• Cursor や Codex と併用している人：AGENTS.md を共通の指示にし、Claude 固有の指示だけを CLAUDE.md に書ける
• 組織でルールを配りたい人：管理ポリシーの CLAUDE.md と managed settings を組み合わせられる

こんな方にはおすすめしません

• Claude Code を使っていない人：CLAUDE.md は Claude Code 向けのファイル。ほかのツールが中心なら AGENTS.md などそのツールの形式を優先する
• ルール自体がまだ固まっていない人：先に何回か使ってみて、2回間違えたことから書くほうが早い
• 書けば必ず守られると期待している人：強制力はない。必ず止めたい操作は Hook や permissions.deny で止める

よくある質問（FAQ）

Q1. CLAUDE.md は何行までが現実的な上限ですか？

公式の目安は1ファイル200行未満です。300行は公式の数字ではありませんが、超えていたら分割を急ぐラインとして使えます。行数とは別に、4 MiB を超えるファイルは読み込まれません。複数のファイルに分けても合計量が多ければ起動時に警告が出るので、分けたあとも全体の量を見てください。

Q2. 日本語で書いても効きますか？

効きます。公式に書く言語の指定はなく、短く人が読める形で書くよう勧めているだけです。チームが読みやすい言語で書き、コマンドやパスなどはコードの表記のまま書くのが実用的です。

Q3. .claude/rules/ と @import はどう使い分けますか？

コンテキストを減らしたいなら paths: 付きの .claude/rules/、既存の README や設計資料を1か所で管理したまま参照したいなら @import です。@import は取り込み先も起動時に全文読み込むので、量は減りません。

Q4. AGENTS.md があるリポジトリでは、CLAUDE.md を作らないほうがいいですか？

AGENTS.md だけで足りるなら、CLAUDE.md を作らなくても v2.1.277 以降の Claude Code は AGENTS.md を読みます。Claude 固有の指示を足したいなら、CLAUDE.md の先頭に @AGENTS.md を書いて取り込むのが確実です。CLAUDE.md を作ったのに取り込みを書かないと、既定の設定では AGENTS.md が読まれなくなります。

Q5. README.md と CLAUDE.md はどう分けますか？

README は人がプロジェクトを理解するための資料、CLAUDE.md は Claude が作業でミスしないための指示です。README の内容を CLAUDE.md に書き写す必要はありません。必要なら「概要は README.md を参照」と一行書くか、@README.md で取り込みます。取り込むと毎回全文が読まれる点は覚えておいてください。

Q6. サブエージェントにも CLAUDE.md は効きますか？

自分で定義したサブエージェントは CLAUDE.md を読み込みます。組み込みの Explore / Plan エージェントは読みません。規約が要らないエージェントは、定義に omitClaudeMd を付けると CLAUDE.md なしで起動できます（管理ポリシーの CLAUDE.md は読まれます）。メイン会話の Auto memory はサブエージェントに渡りません。

Q7. Claude に「これを覚えて」と言えば CLAUDE.md に入りますか？

入りません。「覚えて」と頼むと Auto memory に保存され、そのマシンの中だけで使われます。チームで共有したいルールなら、「CLAUDE.md に追加して」と明示してください。

Q8. 組織で配った CLAUDE.md を、開発者が無効にできますか？

管理ポリシーの場所に置いた CLAUDE.md は、claudeMdExcludes では外せません。ただし CLAUDE.md は強制力のない指示なので、Claude が必ず従う保証はありません。コマンドやパスを確実に禁止したいなら、managed settings の permissions.deny を使ってください。

Q9. CLAUDE.md が長いと料金は上がりますか？

CLAUDE.md は毎リクエストのコンテキストに全文が入るため、長いほどトークンの消費は増えます。API の従量課金で使っている場合は費用に、サブスクリプションで使っている場合は使用量の上限に影響します。料金の仕組みは Claude Code の料金、節約の方法は Claude Code コスト最適化ガイド を参照してください。

Q10. 他人が公開している CLAUDE.md や設定集をそのまま入れてもいいですか？

そのまま入れるのはおすすめしません。自分のプロジェクトに関係ない指示が増えて遵守率が下がり、外部のファイルを取り込む設定が含まれていることもあります。必要な行だけを選んで取り入れてください。設定集の例は SuperClaude フレームワーク や Awesome Claude Code で紹介しています。

まとめ

• 書くもの：Claude がコードを読んでも分からないことだけ
• 長さ：公式の目安は200行未満。300行は超えたら分ける危険ライン、4 MiB は読み込みの上限
• 構成：WHAT / WHY / HOW。特に WHY を省かない
• 置き場所：チームは ./CLAUDE.md、個人は ./CLAUDE.local.md（gitignore）と ~/.claude/CLAUDE.md
• 分け方：一部のファイルだけの規約は paths: 付きの .claude/rules/、手順は Skill。@import は整理用で量は減らない
• 強制：必ず止めたいことは Hook・permissions.deny・managed settings
• AGENTS.md：v2.1.277 から直接読む。CLAUDE.md や CLAUDE.local.md があると既定では読まれないので、@AGENTS.md の取り込みが確実
• 点検：/doctor → /doctor prompt-audit → /context の順に確かめ、モデルが大きく変わったら見直す

書けば書くほど効くファイルではありません。必要な行だけに絞ったほうが指示は守られます。Claude Code の基本操作は Claude Code 使い方ガイド もあわせてご覧ください。