CLAUDE.md・AGENTS.mdを書いても効かない原因は設計にある。自然とドメイン注入ができる設計思想と、静的・オンデマンド・自律蓄積の3パターンを解説。
はじめに
ども！いろんなところでAI関連の話をしている龍ちゃんです。
Claude Code、Cursor、GitHub Copilot…AI駆動開発ツールは急速に広がっています。でも、どのツールを使っても同じ課題にぶつかるんですよね。
- 「コーディング規約を無視したコードを生成する」
- 「過去のPR議論を踏まえない提案をしてくる」
- 「プロジェクト固有の設計思想を理解していない」
なぜこんなことが起きるのでしょうか？
考えてみてください。これって、アサインされたばかりのエンジニアと同じ状況ですよね。プロジェクトのルールも、過去の経緯も、なぜこの設計になったかも知らない。優秀なエンジニアでも、ドメイン知識がなければ的外れな提案をしてしまいます。
さらに言えば、セッションごとに毎回記憶喪失になっているエンジニアのようなもの。さっき教えたことを今日また一から説明する…これでは効率が悪いですよね。（掟上今日子って小説面白かったな…）
AIも同じです。ドメイン知識をどうAIに渡すか。これがAI駆動開発の核心的な課題です。
CLAUDE.md、AGENTS.md、copilot-instructions.md…各ツールには設定ファイルがあります。「どう書くか」という記事は多くありますが、そもそもなぜこれが必要で、どう設計すべきかという話はあまり語られていません。
本記事では、特定のツールに依存しない「ドメイン知識の設計思想」を紹介します。
なぜドメイン注入が必要なのか
ドメイン注入がなくても、AIは動きます。開いているファイルや指定したファイルを分析して、現状を理解しようとしてくれるんですよね。
でも、ここに問題があるんです。
セッションごとにクオリティがばらつく
AIがすべてのコードを見てくれれば、一定のクオリティになるはず。でも現実には、トークンの制約やプロンプトの書き方によって、分析するファイルが変わってしまいます。
あるセッションでは重要な設定ファイルを読んでくれたのに、別のセッションでは読まなかった。こういうことが普通に起きます。
分析されないファイルは「存在しない」扱い
分析されなかったファイルはどうなるか？完全に無視されます。
キャンバスに例えると、すでに絵が描かれているのに、その上に全く違うテイストの絵を重ねちゃうようなもの。結果として、プロジェクトの一貫性が崩壊してしまいます。
具体的な失敗パターン
僕が実際に遭遇した例を挙げると：
- OAuth認証を使っているのに、ログインフォームを作ってきた：プロジェクトの認証パターンを完全に無視
- 既存のデータ保存ロジックを再定義：すでにあるのに、別の保存システムを一から構築
- データベース構造を一から設計：既存のスキーマを無視して新しいテーブル定義を提案
これらはライブコーディング初期の笑い話なんですけど、ドメイン知識なし＋プロンプトも雑という状況では、まあ当然の結果ですよね。
コード分析のコスト問題
コードの分析って、書いてあることを全て読み込むってことです。これはトークンを大量に消費します。
毎回同じルールや規約をコードから「推測」させるのは非効率。最初から正解を教えておくほうが、コスト的にも品質的にも良いんです。
書いているのに効かない？
「CLAUDE.mdを書いたのに全然効かない」という声もよく聞きます。これには理由があります。
効かない原因
- 書き方が曖昧：「いい感じにして」「適切に処理して」では、AIは具体的な行動を取れない
- 情報が多すぎる：何でもかんでも詰め込むと、コンテキストが溢れて精度が下がる
- 情報が少なすぎる：肝心なルールが書かれていなければ、無いのと同じ
- AIが見つけられない：存在しても、AIがその存在を知らなければ参照されない
入れすぎ注意
コンテキスト量が増えすぎると精度が下がるってのは、よく言われている話です。関係ない情報が増えると、AIが本当に必要な情報を見落としやすくなります。
ただ、初期段階はとりあえず突っ込んでいけばいいってのが僕の考えです。まずは書いてみて、効果を見ながら削っていく。最初から完璧を目指す必要はないんですよね。
これらは結局、ドキュメントの形式・量・配置の問題に帰着します。CLAUDE.mdの書き方だけでなく、設計思想から見直す必要があるんです。
では、どうすればいいのか。ここからが本題です。
主張: ドキュメントはコードと同じリポジトリにMarkdownで置け
まず、くそでか主張をします。
実装に必要なドメイン知識は、コードと同じリポジトリにMarkdownで置け
なぜ同じリポジトリなのか
Notion、Confluence、Google Docs…ドキュメント管理ツールはたくさんありますよね。議事録、要件定義、顧客との調整事項など、人間がやり取りするドキュメントにはこれらが最適です。
でも、AIが参照すべきドキュメントは別なんです。
AIが開発するとき、コードと一緒にドキュメントも読めることが重要です。
- Notionにある設計書を「読んでおいて」と言っても、AIは直接アクセスできない
- 別システムにあるドキュメントは、コードとの整合性が崩れやすい
- MCPなどの連携機構を使う手もあるけど、複雑さが増す
シンプルな解決策：最初から同じリポジトリに置いちゃえばいいんです。
なぜMarkdownなのか
次に、なぜMarkdown形式なのか。これも理由があります。
1. トークン効率が良い
<!-- HTML -->
<h1>タイトル</h1>
<p>本文です</p>
<ul>
<li>項目1</li>
<li>項目2</li>
</ul>
# タイトル
本文です
- 項目1
- 項目2
同じ内容でも、HTMLはタグのオーバーヘッドでトークンを消費しちゃいます。Markdownはシンプルで無駄がありません。
じゃあTXTでいいじゃないかってなりますけど、それじゃあ人間が読みづらいということで可読性と構造性を考えた時に一番トークン効率が良いんですね。
2. 構造が明確
見出しレベルは#の数で一目瞭然。リスト、コードブロック、引用も直感的。LLMがパースしやすい形式なんです。
3. ツール非依存
どのAIツールでもMarkdownは読めます。Claude Code、Cursor、GitHub Copilot…どれに乗り換えても、ドキュメントはそのまま使えるんですよね。
ツールに依存しない資産になる
「Claude Codeを使っているからCLAUDE.mdを書いている」という考え方、ちょっと危険です。
ツールは変わります。新しいツールも出てきます。でも、リポジトリ内のMarkdownドキュメントは残るんです。
- Claude Code → Cursor に乗り換えても使える
- 新しいツールが出てきても使える
- チームメンバーが別のツールを使っても共有できる
ちなみに、AGENTS.md は2025年にSourcegraph、OpenAI、Googleが推進して、今はLinux Foundation傘下のAgentic AI Foundationが管理する業界標準になってます（Claude Codeは読み込んでくれないんですけどね！！）。これは、いろんなAIツールが自動で読み込んでくれる設定ファイルになります。こういうところからも「ツール非依存」という流れは業界全体で進んでるんですよね。
ドメイン知識をMarkdownでリポジトリに整理することは、特定ツールへの投資ではなく、プロジェクト全体への投資になります。
AIフレンドリー設計の3原則
ドキュメントを置くだけでは不十分です。AIが効果的に使えるよう設計する必要があります。
原則1: トークン効率
無駄なデータを削る
AIに渡すコンテキストには上限があります。無駄なデータはトークンを消費して、本当に必要な情報を圧迫します。
【避けるべきこと】
- HTMLをそのまま保存
- 不要なメタデータを含める
- 冗長な説明を書く
【やるべきこと】
- Markdownに変換
- 本文のみを抽出
- 簡潔に書く
HTMLで保存したドキュメントは、Markdownに変換するだけでトークン数を大幅に削減できます。詳しくは「Markdown保存でトークン削減」で解説してます。これはHTML→Markdownの話ですが、ドキュメントで余分な部分があったらそぎ落とすというのが大事です。余計な情報があればあるほどノイズになります。そうなると僕のブログの「はじめに」は全カットしたほうが良いですね。
原則2: 構造の明確さ
AIがパースしやすい形式にする
# プロジェクト名
## 概要
このプロジェクトは...
## アーキテクチャ
### フロントエンド
- React
- TypeScript
### バックエンド
- Python
- FastAPI
## 開発ルール
1. PRには必ずテストを含める
2. 命名規則はキャメルケース
- 見出しで階層構造を示す
- リストで列挙する
- コードブロックで例を示す
曖昧な自然言語より、構造化された記述のほうがAIは正確に理解してくれます。
原則3: 発見可能性
AIが「見つけられる」設計にする
ドキュメントが存在しても、AIがその存在を知らなければ参照できないんですよね。指定すれば全部の情報を読んでくれるかもしれませんが、それではトークン数が多くなってしまいますね。そんな時に使うのがREADMEです。
docs/
├── README.md ← インデックス（目次）
├── architecture/
│ ├── README.md ← このディレクトリの説明
│ ├── overview.md
│ └── decisions.md
├── guides/
│ ├── README.md
│ └── coding-style.md
└── research/
├── README.md
└── ...
各ディレクトリにREADMEを置いて、インデックス（目次）として機能させます。AIは必要に応じてREADMEを読んで、関連ファイルを見つけてくれるんです。
詳しくは「AIフレンドリーなドキュメント管理」で解説してます。
3つの設計パターン
具体的な設計パターンを3つ紹介しますね。「誰が整理するか」と「いつ読み込むか」の組み合わせです。
| パターン | 誰が整理するか | いつ読み込むか |
|---|---|---|
| 静的コンテキスト | 人間 | 毎回自動で |
| オンデマンド | 人間 | 必要な時にAIが選択 |
| 自律蓄積型 | AI | AIが調査→保存→再利用 |
パターン1: 静的コンテキスト（常に読み込む）
人間が整理し、AIが毎回自動で読み込む情報
まず、ドキュメントを docs/ に整理します。
# docs/project-overview.md
## プロジェクト概要
このプロジェクトは...
## ディレクトリ構造
- src/: ソースコード
- docs/: ドキュメント
- tests/: テスト
## 開発ルール
- コーディング規約: PEP8準拠
- コミットメッセージ: Conventional Commits
次に、ツールの設定ファイルから参照させます。
# CLAUDE.md（または AGENTS.md、copilot-instructions.md）
セッション開始時に以下を必ず読み込んでください：
- docs/project-overview.md
- docs/coding-style.md
この構成なら、ドキュメント自体はツール非依存のまま、各ツールから参照できます。ツールを乗り換えても、参照先の指定を変えるだけ。
常に必要な情報に向いてます。
- プロジェクトの概要
- ディレクトリ構造
- 基本的な開発ルール
詳しくは「毎回検索をやめて実行速度を改善」で解説してます。
パターン2: オンデマンド（必要な時に読み込む）
人間が整理し、AIが必要な時に選んで読み込む情報
# docs/README.md
## ドキュメント一覧
### アーキテクチャ
- [システム全体像](./architecture/overview.md): システムの全体構成
- [技術選定理由](./architecture/decisions.md): なぜこの技術を選んだか
### 開発ガイド
- [コーディング規約](./guides/coding-style.md): コードの書き方
- [テストガイド](./guides/testing.md): テストの書き方
### 調査資料
- [競合分析](./research/competitor-analysis.md): 競合サービスの調査
READMEをインデックスとして、AIが必要に応じて個別ファイルを読み込んでくれます。
- 大量ドキュメントの管理に向いてる
- コンテキスト窓を効率的に使える
- 段階的に詳細を開示できる
実際、主要なAIツールはディレクトリ単位での設定をサポートしてます。
- Claude Code:
.claude/rules/でディレクトリごとのルールを定義可能 - GitHub Copilot: ディレクトリ単位のinstructionsに対応
詳しくは以下の記事で解説してます。
- Claude Code: CLAUDE.md vs .claude/rules/ の実践的な使い分け
- copilot-instructions.md を分割したい？applyTo パターンで解決
- copilot-instructions.md と AGENTS.md、どっちに何を書く？
このパターンはSpec駆動開発とも相性が良いんですよね。仕様書をdocs/features/に配置して、AIが実装時に参照することで、仕様に沿った開発ができます。詳しくは「Claude CodeでSpec駆動開発」で解説してます。
パターン3: 自律蓄積型（AIが調査して蓄積）
AIが調査し、AIが保存し、AIが再利用する情報
このパターンでは、人間は調査の指示を出すだけ。AIが調査を実行して、結果をMarkdownで保存してくれます。
さらにオンデマンドパターンと組み合わせることで、真価を発揮します。docs/research/README.mdにインデックスを用意しておけば、関連タスク時にAIが過去の調査結果を発見・参照できるようになるんです。
- 同じことを何度も調べなくていい
- 調査結果がプロジェクトの知識資産として蓄積される
- 新しいタスクに取り組む際、過去の調査を参照できる
詳しくは「/research コマンドの紹介」で解説してます。
実例: モノレポでの実践
ここまでの考え方を、実際のプロジェクトでどう適用しているか紹介しますね。
ディレクトリ構成
プロジェクトルート/
├── CLAUDE.md # ルート: 全体像・共通ルール
├── docs/ # 計画・設計（実装コードなし）
│ ├── CLAUDE.md # docsフェーズのガイドライン
│ ├── specs/ # 普遍的な仕様（変更不可）
│ ├── features/ # 新機能開発計画
│ ├── research/ # 実装検証結果・知見【自律蓄積型】
│ ├── references/ # スキル・エージェント用参照資料
│ └── article/ # 記事執筆用調査
├── application/ # 実装フェーズ
│ ├── backend/
│ │ └── CLAUDE.md # バックエンド開発ガイド
│ └── frontend/
│ └── CLAUDE.md # フロントエンド開発ガイド
└── infrastructure/
└── CLAUDE.md # インフラ開発ガイド
3つのパターンの適用
| パターン | 適用箇所 |
|---|---|
| 静的コンテキスト | 各階層のCLAUDE.md（docs/specs/への参照を含む） |
| オンデマンド | docs/specs/, docs/features/, docs/references/, docs/article/ |
| 自律蓄積型 | docs/research/ |
ポイント
- 設定ファイルの階層構造: ルートで全体像、各ディレクトリで詳細を提供
- 計画と実装の分離: docs/（計画）と application/（実装）を分ける
- 知見の蓄積: docs/research/ に調査結果を蓄積
- 全てMarkdown: ドキュメントはMarkdownで統一
詳しくは「モノレポでビルド時間を大幅短縮するCLAUDE.md活用法」で、実際のプロジェクト構成とワークフローを解説してます。
ここまで読んで「RAGと似ている」と思った方もいるかもしれません。
実際、その通りなんです。
RAG（Retrieval-Augmented Generation）は「検索で情報を取ってきて、生成に使う」技術。ベクトルDBを使うイメージが強いかもしれませんが、本質は「外部知識をコンテキストに補填する」ことです。
- CLAUDE.md に書く → 外部知識をコンテキストに補填
- docs/ から読み込む → 外部知識をコンテキストに補填
- AIが調査して保存 → 外部知識をコンテキストに補填
全部RAGの考え方なんです。
なぜベクトルDBを使わないのか
「RAGならベクトルDBでは？」と思うかもしれません。
でも、プロジェクト固有のドキュメントって、多くても数十〜数百ファイル程度です。この規模だと：
- ベクトルDBのセットアップコストが過剰
- 「エラーコードE001」を探したいのに関係ない文書がヒットする
- どれが重要かは人間が判断したほうが精度が高い
人間がキュレーションしたドキュメント + AIが自律的に蓄積した調査結果。この組み合わせが、プロジェクト規模のドメイン知識には向いてます。
大規模なドキュメント（数千〜数万件）を横断検索する場合は、ベクトルDBやハイブリッド検索が適切ですね。
まとめ
AI駆動開発における「ドメイン知識の渡し方」についてサクッと解説してきました。ちょっと真面目にまとめておきます
核心
- 課題: AIが「プロジェクトのことを分かってくれない」
- 主張: ドキュメントはコードと同じリポジトリにMarkdownで置け
AIフレンドリー設計の3原則
- トークン効率: 無駄なデータを削る（Markdown化）
- 構造の明確さ: AIがパースしやすい形式に
- 発見可能性: インデックス（README）で見つけられるように
3つの設計パターン
- 静的コンテキスト: 人間が整理、毎回自動で読み込む
- オンデマンド: 人間が整理、AIが必要な時に選んで読み込む
- 自律蓄積型: AIが調査・保存・再利用
ツールに依存しない資産化
この設計思想は、特定のAIツールに依存しません。
- Claude Code → Cursor に乗り換えても使える
- 新しいツールが出てきても使える
- ドキュメントがプロジェクトの資産として残る
まずは、プロジェクトの設計書やルールをMarkdownで整理するところから始めてみてください。それが、AI駆動開発を加速させる第一歩です！
関連記事
設計思想・全体像
本記事の考え方を実際のプロジェクトに適用した実践例です。
- AI協業開発環境の構築術｜モノレポでビルド時間を大幅短縮するCLAUDE.md活用法
- 本記事の実践例。CLAUDE.md階層構造をモノレポで実装し、ビルド時間短縮を実現
- Claude CodeでSpec駆動開発 – AI駆動時代の計画術
- オンデマンドパターンの応用。仕様書をdocs/features/に配置し、AIが参照しながら実装
3原則の深掘り
本記事で紹介した3原則（トークン効率・構造の明確さ・発見可能性）を個別に深掘りした記事です。
- HTMLで保存してる奴、全員Markdownにしろ
- トークン効率の実践。HTML→Markdown変換でトークン数を削減する具体的手法
- Claude Code設計術：AIフレンドリーなドキュメント管理
- 構造の明確さ・発見可能性の実践。READMEインデックスの設計パターン
3パターンの深掘り
本記事で紹介した3パターン（静的コンテキスト・オンデマンド・自律蓄積型）を個別に解説した記事です。
- Claude Codeが遅い？毎回検索をやめて実行速度を劇的改善
- 静的コンテキストの実践。毎回検索していた情報をCLAUDE.mdに埋め込み高速化
- CLAUDE.md vs .claude/rules/ の実践的な使い分け
- オンデマンドの実践（Claude Code）。ディレクトリ単位でルールを分割
- copilot-instructions.md を分割したい？applyTo パターンで解決
- オンデマンドの実践（GitHub Copilot）。*.instructions.mdでファイル/言語別に分割
- Claude Codeの調査品質がバラバラ？：/researchで解決する方法
- 自律蓄積型の実践。AIが調査→Markdown保存→再利用するワークフロー
ツール別ガイド
Claude CodeとGitHub Copilot、それぞれの設定ファイル体系を解説した記事です。
- Claude Code Skills 実装ガイド
- Claude Codeでカスタムスキルを作成し、ワークフローを自動化する方法
- GitHub Copilot設定5種を網羅！生産性を最大化する使い分け術
- copilot-instructions.md、*.instructions.md、AGENTS.mdなど5種類の設定を整理
- Claude Code→GitHub Copilot移行で使える設定ファイル対応表
- 両ツールの設定ファイルを対応表で比較。ツール間の「翻訳表」として活用
- AGENTS.md vs Custom Agents【5つの比較表で混乱解消】
- GitHub CopilotのAGENTS.mdとCustom Agentsの違いを比較表で整理
- copilot-instructions.md と AGENTS.md、どっちに何を書く？
- 公式推奨と「What vs How」の役割分担で使い分けを解説
- Agent Skills 入門：SKILL.md の基本から実践まで
- GitHub Copilot Agent SkillsとSKILL.mdの書き方を実用例付きで解説
- Claude CodeからGitHub Copilotへ移植したらAgent Skillsが動かない？
- Skills発火メカニズムの違いと移行時の注意点を解説
仮説検証シリーズ
「こうすれば上手くいくのでは？」という仮説を実際に検証した記事です。
- 検証→記事化で知見を資産化！RAGもどきで技術ブログ執筆を効率化
- 仮説: 既存記事をRAG的に参照すれば、新規記事の執筆が効率化する
- 結果: 文体・構成の一貫性が向上し、過去記事との重複も防げた
