CLAUDE.md や AGENTS.md のベストプラクティスな書き方

Claude Code を使っていて、なんか思い通りに動かんなって感じたことない？指示を書いてるはずなのに無視される、毎回同じことを説明し直さなあかん、コードスタイルがバラバラになる

こういう問題の多くは、実は CLAUDE .md の書き方に原因があったりするんよね

X で 毎日 AI 情報を配信してるコムテです。Agentic AI / AI 駆動開発などを中心に情報を配信しています

この記事は HumanLayer のブログ記事「Writing a good CLAUDE .md」をベースに、Anthropic の公式ドキュメントと最新の学術研究を加えて、効果的な CLAUDE .md の書き方を徹底解説していく

５つの原則

Claude Code の CLAUDE .md や AGENTS .md で使えるベストプラクティス

• WHY、WHAT、HOW を定義
• 命令は少なく
• 段階的開示
• リンターをさせるな
• 自動生成は避ける

これがどれほど重要かピンときてない君！

これ、どんな AI コーディングエージェントでも何年でも使える汎用的なコツだよ？

WHY、WHAT、HOW を定義

まず、この３つを必ず書く

WHAT

テックスタック、プロジェクト構造、コードベースの全体像
Claude が最初に迷子にならないための地図を書く

WHY

プロジェクトの目的、各ディレクトリやコンポーネントの役割
なぜこの構成になっているのかを理解させる

HOW

作業の進め方そのものではなく、どうやって正解を検証できるか
テスト、型チェック、ビルドなど、変更の是非を判断する手段を示す

これについては、後述するね

少ないほど良い、を徹底する

• 理想は 300 行未満。HumanLayer の実例は 60 行未満
• 情報を詰め込みすぎると、重要な指示ほど無視されやすくなる

これは好みの問題ではなく、仕様の問題でもある

正直、この記事の方法でいけば SaaS レベルのプロダクトでも 100 行くらいで収まるよ？

それ以上書いちゃう人は、「もうちょっと抽象的に考えろ」ってことやね

CLAUDE .md には「この情報はタスクと無関係かもしれない」という前提付きで渡されるから、汎用性の低い指示が多いと、まとめて relevance なし判定されやすい

それでも収まらないって？

その対処法も後述する

LLM はステートレスという大前提を理解する

まず最初に押さえておきたいのが、LLM の根本的な性質。LLM は状態を持たない関数なんよね

重みは推論時点で凍結されてるから、使ってるうちに学習していくなんてことはない。つまり、セッションごとに完全にリセットされるってこと

HumanLayer のブログでは、この点について明確に述べられてる

LLM がコードベースについて知ってることは、こちらが渡したトークンだけ。Claude Code のようなコーディングエージェントは、明示的にメモリを管理する必要がある。そして CLAUDE .md は、デフォルトでエージェントとのすべての会話に含まれる唯一のファイルなんよね

これには 3 つの重要な意味がある

• コーディングエージェントは各セッションの開始時点でコードベースについて何も知らない
• エージェントには毎回、コードベースについて重要なことを伝える必要がある
• CLAUDE .md がそのための推奨方法

ここをちゃんと理解してないと、CLAUDE .md の設計がブレてしまうんよね

WHY / WHAT / HOW の 3 要素

CLAUDE .md に書くべき内容は、大きく分けて 3 つある。これは HumanLayer のブログでも強調されてるポイント

WHAT（何があるか）

技術スタック、プロジェクト構造、コードベースの全体像を伝える部分。Claude が最初に迷子にならないための地図を書くイメージ

特にモノレポでは重要で、各アプリケーションは何か、共有パッケージは何か、それぞれが何のためにあるのかを明示する。Claude がどこを見れば何があるかを把握できるようにするんよね

例えば、こんな感じで書く

この「地図」があるかないかで、Claude の探索効率がめっちゃ変わってくる

WHY（なぜそうなっているか）

プロジェクトの目的、各ディレクトリやコンポーネントの役割を説明する部分。単に「何があるか」だけでなく「なぜこの構成になっているのか」を理解させることで、Claude がより適切な判断を下せるようになる

WHY を書いておくと、Claude が新しいコードを書くときに既存の設計思想に沿った提案をしてくれるようになる

HOW（どうやって作業するか）

作業の進め方そのものではなく、どうやって正解を検証できるかを示す部分。テスト、型チェック、ビルドなど、変更の是非を判断する手段を明示する

ポイントは「bun を使う」とか「pnpm じゃなくて npm」みたいな、このプロジェクト特有のやり方を伝えること。Claude が間違ったコマンドを叩いて時間を無駄にするのを防げる

なぜ Claude は CLAUDE .md を無視するのか

ここが多くの人が見落としてる衝撃的なポイント

実は Claude Code は、CLAUDE .md の内容を必ずしも従わないように設計されてるんよね

えー、何だってー

HumanLayer のブログによると、Claude Code は CLAUDE .md を渡すときに以下のシステムリマインダーを付けてるらしい

つまり、Claude は CLAUDE .md の内容が現在のタスクに関係ないと判断したら、その指示を無視する。ファイルに書いてある情報が普遍的に適用できるものでなければないほど、全体がまとめて「関係なし」と判定される可能性が高くなるってこと

なぜ Anthropic はこういう設計にしたのか。推測やけど、多くの CLAUDE .md には広く適用できない指示がたくさん含まれてて、ユーザーは気に入らない挙動を「ホットフィックス」するためにどんどん指示を追記していく傾向があるんやと思う

Claude Code チームは、悪い指示を無視させることで、むしろ全体としてより良い結果が出ることを発見したんやろう

命令は短いほど良い

LLM に投げる文章は短いが正義なんよ

ここで学術研究の知見が役立つ。プロンプトエンジニアリングに関する最も包括的なサーベイ論文「The Prompt Report」（arxiv.org/abs/2406.06608）では、58 のプロンプト技法と 33 の用語を体系的に整理してる

この分野の研究によると、フロンティア思考 LLM は約 150〜200 の指示を合理的な一貫性で従えるらしい。やけど、小さいモデルはより少ない指示しか注意を向けられず、非思考モデルは思考モデルよりもさらに少ない

特に重要なのは、小さいモデルは指示の数が増えるにつれて指数関数的に性能が低下するのに対し、大きなフロンティア思考モデルは線形に低下するという点。つまり、軽量モデルを使う場合は特に指示を絞り込む必要がある

LLM は指示がプロンプトの周辺部、つまり最初（Claude Code のシステムメッセージと CLAUDE .md）と最後（最新のユーザーメッセージ）にあるものに偏ってしまう傾向もある

さらに、指示の数が増えると、指示への従い方の質は均一に低下する。つまり、LLM にたくさんの指示を与えると、新しい指示（ファイルの下の方にある指示）だけを無視するんじゃなくて、すべての指示を均一に無視し始めるってこと

HumanLayer の分析によると、Claude Code のシステムプロンプトには約 50 の個別指示が含まれてる。使うモデルによっては、これだけでエージェントが確実に従える指示の約 3 分の 1 を使ってしまってる。ルール、プラグイン、スキル、ユーザーメッセージを追加する前にね

ということは、CLAUDE .md にはできるだけ少ない指示だけを含めるべき。理想的にはタスクに普遍的に適用できるものだけ

理想的なファイル長は 300 行未満

まぁ、３００行でも多いやろって思いますが。

他の条件が同じなら、LLM はコンテキストウィンドウが集中した関連コンテキスト（例、関連ファイル、ツール呼び出し、ツール結果）で満たされてるときに、無関係なコンテキストが多いときよりもタスクでより良いパフォーマンスを発揮する

CLAUDE .md はすべてのセッションに含まれるから、その内容はできるだけ普遍的に適用可能であるべき。例えば、新しいデータベーススキーマの構造化方法についての指示を含めないほうがいい。関係ないことをやってるときにモデルの注意を散らすだけやからね

長さについても「少ないほど良い」原則が適用される。Anthropic は CLAUDE .md の長さについて公式の推奨を出してないけど、一般的なコンセンサスは 300 行未満がベストで、短いほどさらに良い。HumanLayer では、ルートの CLAUDE .md ファイルは 60 行未満らしい

段階的開示（Progressive Disclosure）の活用

Claude に知ってほしいことすべてをカバーする簡潔な CLAUDE .md を書くのは、特に大きなプロジェクトでは難しい。これに対処するために、段階的開示の原則を活用して、タスクやプロジェクト固有の指示を必要なときだけ Claude に見せるようにできる

すべての指示を CLAUDE .md に詰め込む代わりに、タスク固有の指示はプロジェクト内のどこかに自己説明的な名前の別々の Markdown ファイルに保管することを推奨する

そして CLAUDE .md には、これらのファイルのリストと各ファイルの簡単な説明を含め、Claude に作業を始める前にどれが関連するか（もしあれば）を判断して読むように指示する

重要なのは「コピーよりポインタを優先する」こと。これらのファイルにコードスニペットを含めないほうがいい。すぐに古くなるから。代わりに、file:line 参照を使って Claude を権威あるコンテキストに向ける

概念的には、これは Claude Skills の意図する動作に非常に似てるけど、スキルは指示よりもツールの使用に焦点を当ててる

Context Engineering という新しいパラダイム

2025 年に入って、「プロンプトエンジニアリング」を超えた「Context Engineering」という概念が注目されてる。arxiv の最新サーベイ論文「A Survey of Context Engineering for Large Language Models」（arxiv.org/abs/2507.13334）は、166 ページ、1411 件の引用を含む包括的な研究

この論文によると、LLM が単純な指示に従うシステムから複雑な多面的アプリケーションの中核となる推論エンジンへと進化するにつれて、やり取りの方法も進化する必要がある。「プロンプトエンジニアリング」という用語は基礎的やけど、もはや現代の AI システムが必要とする情報ペイロードの設計、管理、最適化の全範囲を捉えるには不十分

Context Engineering は単純なプロンプト設計を超えて、LLM のための情報ペイロードの体系的な最適化を包括する正式な分野として導入されてる。この論文では、基礎コンポーネント（コンテキスト検索と生成、コンテキスト処理、コンテキスト管理）と、それらを統合するシステム実装（RAG、メモリシステム、ツール統合推論、マルチエージェントシステム）を分析してる

Agentic Context Engineering の登場

さらに最新の研究として、「Agentic Context Engineering: Evolving Contexts for Self-Improving Language Models」（arxiv.org/abs/2510.04618）がある

この研究では、ACE（Agentic Context Engineering）というフレームワークを提案してる。コンテキストを「evolving playbooks」（進化するプレイブック）として扱い、生成、リフレクション、キュレーションのモジュラープロセスを通じて戦略を蓄積、洗練、整理する

従来のアプローチには 2 つの問題があった

• brevity bias（簡潔さバイアス）: ドメインの洞察を捨てて簡潔な要約を好む傾向
• context collapse（コンテキスト崩壊）: 繰り返しの書き換えで時間とともに詳細が失われる

ACE はこれらの問題に対処し、エージェントとドメイン固有のベンチマークで +10.6%（エージェント）、+8.6%（金融）の改善を達成してる

この研究は CLAUDE .md の設計にも示唆を与える。静的な指示ファイルではなく、使用を通じて進化していく「プレイブック」としてコンテキストを考えるアプローチが効果的ってこと

Claude はリンターじゃない

CLAUDE .md に入れがちなものの筆頭が、コードスタイルガイドライン。やけど、これは絶対にやめたほうがいい

リンターの仕事を LLM にさせるな

LLM は従来のリンターやフォーマッターに比べて高価で遅い。決定論的なツールを使えるときは常にそっちを使うべき。コードスタイルガイドラインは必然的にたくさんの指示とほとんど無関係なコードスニペットをコンテキストウィンドウに追加し、LLM のパフォーマンスと指示への従い方を低下させ、コンテキストウィンドウを食いつぶす

LLM はコンテキスト内学習者。コードが特定のスタイルガイドラインやパターンに従ってるなら、コードベースのいくつかの検索（または良いリサーチドキュメント）があれば、エージェントは言われなくても既存のコードパターンや規約に従う傾向があるはず

どうしてもやりたいなら、Claude Code の Stop Hook を設定して、フォーマッターとリンターを実行し、エラーを Claude に提示して修正させることを検討してもいい。Claude 自身にフォーマットの問題を見つけさせるな。ボーナスとして、問題を自動修正できるリンター（Biome がおすすめ）を使い、何が安全に自動修正できるかのルールを慎重に調整して、最大の（安全な）カバレッジを得る

コードガイドラインを含み、バージョン管理の変更、または git status などに Claude を向けるスラッシュコマンドを作成することもできる。こうすれば、実装とフォーマットを別々に処理できて、結果として両方でより良い結果が得られる

/init や自動生成を使わない

Claude Code や OpenCode を使った他のハーネスには、CLAUDE .md（または AGENTS.md）を自動生成する方法がある。やけど、これは避けるべき

/init は、余計な情報書いちゃう。もったいない

CLAUDE .md は Claude Code とのすべてのセッションに入るから、ハーネスの最もレバレッジの高いポイントの 1 つ

良くも悪くも、使い方次第で悪いコード 1 行は悪いコード 1 行。悪い実装計画 1 行は、たくさんの悪いコードを生む可能性がある。システムの動作を誤解したリサーチの悪い 1 行は、計画にたくさんの悪い行を生み、結果としてさらに多くの悪いコードを生む可能性がある

やけど CLAUDE .md は、ワークフローのすべてのフェーズとそれによって生成されるすべての成果物に影響する。だから、そこに入るすべての行について非常に慎重に考える時間を取るべき

公式ドキュメントの階層構造

Anthropic の公式ドキュメントによると、Claude Code は 4 つのメモリロケーションを階層構造で提供してる

階層の上位にあるファイルが優先され、最初に読み込まれる。より具体的なメモリがその上に構築される基盤を提供するってこと。CLAUDE.local.md ファイルは自動的に .gitignore に追加されるから、バージョン管理にチェックインすべきでないプライベートなプロジェクト固有の設定に最適

CLAUDE .md のインポート機能

CLAUDE .md ファイルは @path/to/import 構文を使って追加ファイルをインポートできる

相対パスと絶対パスの両方が使える。特に、ユーザーのホームディレクトリのファイルをインポートすることで、リポジトリにチェックインされない個人の指示をチームメンバーが提供できる便利な方法になる

インポートは複数の git worktree でうまく動作する CLAUDE.local.md の代替手段でもある

衝突を避けるため、インポートは Markdown のコードスパンやコードブロック内では評価されない。インポートされたファイルは追加ファイルを再帰的にインポートでき、最大深度は 5 ホップ

モジュラールール（.claude/rules/）の活用

大きなプロジェクトでは、.claude/rules/ ディレクトリを使って指示を複数のファイルに整理できる。これにより、チームは 1 つの大きな CLAUDE .md の代わりに、焦点を絞った整理されたルールファイルを維持できる

基本構造

.claude/rules/ 内のすべての .md ファイルは、.claude/CLAUDE .md と同じ優先度でプロジェクトメモリとして自動的に読み込まれる

パス固有のルール

ルールは YAML フロントマターの paths フィールドを使って特定のファイルにスコープできる。これらの条件付きルールは、Claude が指定されたパターンに一致するファイルを操作してるときだけ適用される

paths フィールドのないルールは無条件に読み込まれ、すべてのファイルに適用される

glob パターン

paths フィールドは標準的な glob パターンをサポートしてる

複数のパターンを指定することもできる

ブレース展開もサポートされてる

サブディレクトリでの整理

ルールはより良い構造のためにサブディレクトリに整理できる

すべての .md ファイルは再帰的に検出される

シンボリックリンク

.claude/rules/ ディレクトリはシンボリックリンクをサポートしてて、複数のプロジェクト間で共通のルールを共有できる

.claude/rules/ のベストプラクティス

• ルールは焦点を絞る: 各ファイルは 1 つのトピックをカバーする（例: testing.md、api-design.md）
• 説明的なファイル名を使う: ファイル名でルールの内容がわかるようにする
• 条件付きルールは控えめに: ルールが本当に特定のファイルタイプに適用される場合のみ paths フロントマターを追加する
• サブディレクトリで整理: 関連するルールをグループ化する（例: frontend/、backend/）

メモリのベストプラクティス

公式ドキュメントでは、以下のベストプラクティスが推奨されてる

• 具体的に書く: 「コードを適切にフォーマットする」より「2 スペースインデントを使用する」のほうがいい
• 構造を使って整理: 各メモリを箇条書きとしてフォーマットし、関連するメモリを説明的な Markdown 見出しの下にグループ化する
• 定期的にレビュー: プロジェクトの進化に合わせてメモリを更新し、Claude が常に最新の情報とコンテキストを使用するようにする

こんなのでいいんだよ CLAUDE .md

ここまでの知見を踏まえて、「こんなのでいいんだよ」的な CLAUDE .md の例を示す

この例は約 30 行。WHY/WHAT/HOW が簡潔にまとまってて、詳細は別ファイルへのポインタで参照してる

Claude が無視しにくい CLAUDE .md の書き方

先述の通り、Claude Code は CLAUDE .md の内容を「タスクに関係ない」と判断すると無視する。この挙動を踏まえて、無視されにくい CLAUDE .md を書くコツを整理しよう

普遍的に適用できる情報だけを書く

「データベースマイグレーションの手順」みたいな特定タスクの情報は CLAUDE .md に書かない。そういう情報は agent_docs/database-migration.md のような別ファイルに分離して、必要なときだけ読ませる

CLAUDE .md には「このプロジェクトは bun を使う」「テストは vitest」みたいな、どんなタスクでも関係する情報だけを書く

指示ではなく事実を書く

「必ず〜してください」「〜は禁止です」みたいな指示形式より、「このプロジェクトでは〜を使ってる」「〜という設計方針がある」みたいな事実形式のほうが無視されにくい

指示が多すぎると、Claude は全体を「うるさいノイズ」として処理してしまう傾向がある

構造化して読みやすくする

箇条書き、見出し、テーブルを使って情報を構造化する。長い文章の塊は読み飛ばされやすい

こういう形式なら、Claude は必要な情報をすぐに見つけられる

LLM の注意力に関する研究知見

プロンプトエンジニアリングの研究では、LLM の「注意力」についていくつかの重要な知見が得られてる

先述の通り、LLM は指示がプロンプトの周辺部（最初と最後）にあるものに偏る傾向がある。これは「Lost in the Middle」問題として知られてて、長いコンテキストの中間部分にある情報は見落とされやすい

CLAUDE .md の設計でこれを活かすなら

• 最も重要な情報（プロジェクト概要、主要コマンド）をファイルの最初に置く
• 補足的な情報は後ろに回す
• 中間に長い説明を入れない

また、指示の数が増えると全体の従い方が均一に低下するという研究結果も重要。指示を 10 個から 20 個に増やすと、1 番目の指示も 20 番目の指示も同じように無視されやすくなる。だから「重要な指示だけを残す」んじゃなくて「指示の総数を減らす」ことが大事

AGENTS.md との関係

Claude Code 以外のツール（Cursor、Zed、Codex など）では、CLAUDE .md の代わりに AGENTS.md を使うことが多い。基本的な考え方は同じで、ここで解説したベストプラクティスはそのまま適用できる

ただし、ツールによって AGENTS.md の読み込み方や優先度が異なる場合があるから、使ってるツールのドキュメントも確認しておくとよい

トラブルシューティング

Claude が指示を無視する

• CLAUDE .md が長すぎないか確認（300 行以下が目安）
• 普遍的でない指示が混ざってないか確認
• 指示の総数を減らす
• 重要な情報をファイルの最初に移動

Claude が古い情報を使う

• CLAUDE .md 内のコードスニペットが古くなってないか確認
• コードスニペットを file:line 参照に置き換える
• /memory コマンドで読み込まれてるファイルを確認

チームメンバー間で挙動が違う

• ~/.claude/CLAUDE .md（個人設定）の内容を確認
• CLAUDE.local.md の内容を確認
• .claude/rules/ 内のファイルを確認

まとめ

CLAUDE .md を効果的に書くためのポイントをおさらいしよう

1. LLM はステートレス: 毎回「初見」でコードベースを見るという前提を忘れない

2. WHY/WHAT/HOW を定義: プロジェクトの目的、構造、作業方法を簡潔に伝える

3. 指示は少なく: 研究によるとフロンティア LLM でも 150〜200 の指示が限界。Claude Code のシステムプロンプトで約 50 を使ってるから、残りは限られてる

4. 300 行未満を目指す: HumanLayer の実例は 60 行未満。情報を詰め込みすぎると、重要な指示ほど無視されやすくなる

5. 段階的開示: タスク固有の情報は agent_docs/ などに分離し、CLAUDE .md には参照ポイントだけを置く

6. コピーよりポインタ: コードスニペットではなく file:line で一次情報を指す

7. リンターの仕事をさせない: コードスタイルは Biome などの自動ツールに任せる

8. 自動生成を避ける: /init は使わず、手動で慎重に作る。最重要ファイルだから

9. 定期的に見直す: プロジェクトの進化に合わせて更新する

CLAUDE .md が効く理由は、LLM が毎回「初見」でコードを見るから。重要なのは指示を書くことではなく、常に読む価値がある情報だけを残すこと。関係ない指示が増えるほど、全部まとめて無視されやすくなる

だから WHY/WHAT/HOW だけを最小単位で渡し、詳細は別ファイルに逃がす。これはプロンプトではなくコンテキスト設計の話なんよね

参考リンク

• Writing a good CLAUDE .md | HumanLayer Blog
• Manage Claude's memory - Claude Code Docs
• The Prompt Report: A Systematic Survey of Prompt Engineering Techniques
• A Survey of Context Engineering for Large Language Models
• Agentic Context Engineering: Evolving Contexts for Self-Improving Language Models