この記事は、AGENTS.md にも同様に当てはまると述べたうえで、LLM は（ほぼ）ステートレスであるという前提から出発する。推論時には重みが固定されているため、モデルがコードベースについて知っているのは、目の前に置かれたトークンだけである。記事の言葉を借りれば CLAUDE.md はデフォルトでエージェントとのすべての会話に入る唯一のファイルであるため、記事はこのファイルを Claude をコードベースにオンボーディングするための手段として扱う。その内容は、何か（技術スタックとプロジェクトの地図）、なぜか（プロジェクトとその各部分の目的）、どうするか（どのように作業し、変更をどう検証するか）をカバーするものである。
記事の大部分は、ファイルを小さく保つことについて書かれている。記事によれば、Claude Code は CLAUDE.md を、そのコンテキストは「関連があるかもしれないし、ないかもしれない」と告げるシステムリマインダーとともに注入する。そのため Claude は現在のタスクに無関係だと判断した内容を無視し、ファイルに汎用的でない指示が多く含まれるほど、無視される可能性が高くなる。著者らは、多くの CLAUDE.md ファイルが限られた場面にしか当てはまらない「ホットフィックス」的な指示で埋め尽くされているため、Anthropic がこれを追加したのではないかと推測している。記事の結論である 6 つの推奨事項は、そこから導かれている。
要点
- CLAUDE.md は Claude をコードベースにオンボーディングするためのものであり、プロジェクトのなぜ、何を、どのようにを定義すべきである。
- 少ないほど良い：指示は合理的に可能な限り少なくする。記事は、モデルが一貫して従える指示の数には限りがあること、小さいモデルほどはるかに早く性能が落ちること、そして指示の数が増えると、後のほうの指示だけでなくすべての指示について指示追従性が悪化することを論じている。著者ら自身の分析では、Claude Code のシステムプロンプトには、何かを追加する前の時点で約 50 の指示が含まれている。
- 内容は簡潔で、あらゆる場面に当てはまるものにする。記事は、300 行未満が最善だというのが一般的な合意であると報告し、Anthropic には公式の推奨の長さがないことに触れ、HumanLayer のルートの CLAUDE.md は 60 行未満だと述べている。
- 段階的開示を用いる：タスク固有の指示は、説明的な名前をつけた別の Markdown ファイル（例えば
agent_docs/フォルダの下）に置き、CLAUDE.md にはそれらを列挙して、どれを読むかは Claude に判断させる。コードスニペットをコピーすると古くなるため、file:line形式のポインタを優先する（段階的開示（Progressive Disclosure） を参照）。 - Claude はリンターではない：リンターの仕事を LLM にさせてはならない。例えば Claude Code の
Stopフックから決定論的なフォーマッターやリンターを使い、LLM が既存のコードパターンに従う傾向のある文脈内学習者であることを頼りにする（エージェントフック を参照）。 /initを使ったり、その他の方法でファイルを自動生成したりしない：このファイルはワークフローのすべてのフェーズと生成されるすべての成果物に影響するため、記事はこれをハーネスの中で最もレバレッジの高い箇所と呼び、1 行 1 行を慎重に検討する価値があるとしている。
背景
記事は、そのルールを、コンテキストエンジニアリングのベストプラクティスに沿った HumanLayer の推奨事項として位置づけ、「効果には個人差がある」という注意書きを添えている。いつ、なぜ破ってよいかを理解したうえで破るべきルールだということである。その根拠は、著者ら自身の経験と Claude Code の分析、そして記事自身が認めるように、それほど厳密には調査されていない研究である。このファイルに関する Anthropic 自身のガイダンスは CLAUDE.md のページにまとめられている。関連ページには AGENTS.md、コンテキストエンジニアリング、Skill Issue：コーディングエージェントのためのハーネスエンジニアリング がある。