概要
https://izanami.dev/post/47b08b5a-6e1c-4fb0-8342-06b8e627450a
詳細内容
## CLAUDE.md や AGENTS.md のベストプラクティスな書き方
https://izanami.dev/post/47b08b5a-6e1c-4fb0-8342-06b8e627450a
提示する、AIエージェントにプロジェクトの全容を正しく伝えるCLAUDE.mdの書き方と、研究に基づくコンテキスト設計の最適解を。
**Content Type**: 📖 Tutorial & Guide
**Language**: ja
**Scores**: Signal:4/5 | Depth:4/5 | Unique:4/5 | Practical:5/5 | Anti-Hype:4/5
**Main Journal**: 88/100 | **Annex Potential**: 85/100 | **Overall**: 84/100
**Topics**: [[Claude Code, CLAUDE.md, Context Engineering, AI駆動開発, プロンプトエンジニアリング]]
AIエージェント（特にClaude Code）を使いこなす上で、プロジェクトの羅針盤となる「CLAUDE.md」や「AGENTS.md」の品質は、開発効率に直結する。本記事は、HumanLayerの知見や最新の論文、Anthropic公式ドキュメントを基に、エージェントに無視されず、かつ正確な推論を導き出すための「コンテキスト設計」の核心を突いている。
著者は、CLAUDE.mdを単なる「指示書（プロンプト）」ではなく、エージェントが各セッションで最初に参照する「唯一の地図」と定義する。その上で、記述すべき要素を「WHAT（テックスタックと構造）」「WHY（設計思想と役割）」「HOW（検証方法）」の3点に絞り込むことを推奨している。
重要なのは「少なさは正義」という原則だ。理想的なファイルサイズは300行未満（実例では60行程度）とされる。これは、LLMの注意力が指示の数に反比例して低下し、さらにClaude Code自体が「タスクに関係ない」と判断したCLAUDE.mdの内容を意図的に無視するよう設計されているからだ。筆者によれば、指示を詰め込みすぎると、重要なルールまで「ノイズ」として処理されるリスクがある。
さらに、2025年の新潮流として「コンテキスト・エンジニアリング（Context Engineering）」という概念が紹介されている。これは、単にプロンプトを工夫する段階を超え、エージェントに渡す情報ペイロードを体系的に管理・最適化するアプローチだ。例えば、詳細な手順や特定のタスク固有の指示は「段階的開示（Progressive Disclosure）」の原則に従い、別ファイルに分離してCLAUDE.mdからはポインタ（参照）のみを張る手法が有効である。
また、エンジニアが陥りがちな罠として、コードスタイルやリントのルールをCLAUDE.mdに記述してしまうことが挙げられる。筆者の主張によれば、LLMは決定論的なリンターに比べて高価で遅く、不正確だ。スタイル管理はBiomeなどのツールに任せ、エージェントにはそのツールを実行してエラーを修正させる「仕組み」だけを伝えるのがベストプラクティスだという。
結論として、CLAUDE.mdは自動生成に頼らず、人間が慎重にキュレーションすべき「高レバレッジな資産」である。プロジェクトの進化に合わせてこの「プレイブック」を磨き続けることが、AI駆動開発の成果を最大化する鍵となると著者は述べている。