はじめに
当記事は生成AIによって執筆しています。内容の正確性には十分注意を払っていますが、誤った情報が含まれている可能性があります。実際にご利用の際は、公式ドキュメント等もあわせてご確認ください。
Codex や Claude Code などの AI エージェントと一緒に開発していると、AGENTS.md や CLAUDE.md に「これも守って」「あれも書いておこう」とルールを足し続けてしまいがちです。筆者のリポジトリでも、AGENTS.md と CLAUDE.md がそれぞれ 278 行まで膨らみ、しかも中身はほぼ同じという状態になっていました。
本記事では、これを AGENTS.md 51 行・CLAUDE.md 9 行まで縮め、作業手順を skills/ に、仕様・設計判断を docs/ に分けたときの設計方針と、その判断理由を共有します。
対象読者
-
AGENTS.md/CLAUDE.mdが長くなってきて、管理がつらくなってきた方 - Codex と Claude Code など、複数の AI エージェントを同じリポジトリで使い分けている方
- AI エージェントに読ませるドキュメントを、どこに何を書けばよいか決めたい方
この記事のゴール
- AI エージェント向けドキュメントを「常時読むもの」と「必要なときに読むもの」に分ける考え方が分かる
-
AGENTS.md/CLAUDE.md/ Skills / Specs / ADR の役割分担を、自分のリポジトリに当てはめられる
前提と要件
解決したい課題
整理前のリポジトリは、次のような状態でした。
-
CLAUDE.md（278 行）をコピーしてAGENTS.md（278 行）を作っていた。差分は「Claude」と「Codex」の呼び方を置き換えた 10 行だけ - 媒体ごとのルール（見出しの制約や独自記法など）が、
CLAUDE.md・AGENTS.md・各媒体のREADME.mdの 3 か所に書かれていた - 執筆手順・公開手順・チェックリストまで、すべてエージェント指示書に入っていた
この構造だと、ルールを 1 つ変えるたびに 3 か所を直す必要があり、直し漏れがあればファイル間で内容が食い違います。さらに、どんな作業でも 278 行すべてがコンテキストに載ります。
機能要件
| # | 要件 | 優先度 |
|---|---|---|
| 1 | AI エージェントが、タスクに必要な手順・仕様へ迷わず辿り着ける | 高 |
| 2 | 1 つの情報を 1 か所だけ直せば、全エージェントに反映される | 高 |
| 3 | Codex でも Claude Code でも、同じ知識を参照できる | 高 |
| 4 | 人間が読んでも、どこに何が書いてあるか分かる | 中 |
非機能要件
- コンテキスト効率：毎回読み込まれる情報を最小にする
- 保守性：仕様・手順・設計判断・履歴が混ざらず、古い情報が残りにくい
- ツール非依存：特定の AI 製品にプロジェクトの知識を閉じ込めない
制約
エージェント側の読み込み仕様が、設計の前提になります（2026 年 10 月時点の公式ドキュメントで確認）。
-
Codex：リポジトリのルートから作業ディレクトリまでの
AGENTS.mdを連結して読み込む。合計サイズの上限はproject_doc_max_bytes（既定 32 KiB） -
Claude Code：
CLAUDE.mdを毎セッション読み込む。公式ドキュメントでは 1 ファイル 200 行以内が目安とされ、長いほどコンテキストを消費し指示への追従性も落ちるとされている -
Claude Code の
@pathインポート：CLAUDE.mdから別ファイルを取り込めるが、取り込んだファイルも同時に読み込まれるため、コンテキスト量は減らない -
Claude Code と
AGENTS.md：CLAUDE.mdがあるリポジトリではAGENTS.mdは自動では読まれない（CLAUDE.mdから@AGENTS.mdでインポートすれば読まれる）
つまり、@import でファイルを分けても常時コンテキストは減りません。減らすには、常時読むファイルそのものを小さくし、詳細は「必要になったときにエージェントが自分で読みに行く」場所へ移す必要があります。
全体アーキテクチャ
エージェントがタスクを受けてから情報を取得する流れを、次のように設計しました。
ポイントは、AGENTS.md を知識の本体ではなく「ルーター」として扱うことです。AGENTS.md には「どのタスクのときにどこを読むか」だけを書き、中身はそれぞれの正本に置きます。
構成要素
| 層 | ファイル | 役割 | 読まれるタイミング |
|---|---|---|---|
| 行動原則 | AGENTS.md |
全エージェント共通の原則・絶対制約・ルーティング | 毎回 |
| アダプタ | CLAUDE.md |
Claude Code 固有の設定だけ | 毎回（Claude Code のみ） |
| 手順（How） | skills/<name>/SKILL.md |
特定の作業を正しく行う手順 | 該当タスクのときだけ |
| 仕様（What） | docs/specs/ |
システムが何を満たすべきか | 関連する作業のときだけ |
| 構成（How it's built） | docs/architecture/ |
現在どう構成されているか | 関連する作業のときだけ |
| 理由（Why） | docs/adr/ |
なぜその設計にしたか | 設計判断が必要なときだけ |
| 実体 | Code / Schema / Tests | 実際の動作 | 必要な範囲だけ |
| 入口（人間向け） | README.md |
概要・セットアップ・主要ドキュメントへのリンク | 人間が最初に読む |
設計の判断ポイント
判断1: AGENTS.md に全部書く vs AGENTS.md をルーターにする
選んだもの：ルーターにする
理由：
-
AGENTS.mdは毎回読まれるので、そこに書いた量がそのまま全タスクのコストになる - 記事の公開手順は、執筆中には不要。タスクごとに必要な情報は違う
- 長い指示書ほど、関係のないルールに引っ張られたり、重要なルールが埋もれたりしやすい
AGENTS.md に残すのは次の 3 種類だけにしました。
- 常に守るべき行動原則（例：曖昧な依頼でいきなり書き始めない、嘘を書かない）
- 絶対に破ってはいけない制約（例：自動生成ファイルを手で編集しない）
- タスク → Skill、情報 → 正本の対応表
トレードオフ：
- メリット：常時コンテキストが小さくなる。ルールの置き場所が明確になる
- デメリット：エージェントが Skill を読まずに作業を始めると、手順が抜ける。対策として、
AGENTS.mdに「作業を始める前に該当する Skill を読む」と明記している
判断2: CLAUDE.md と AGENTS.md を別々に書く vs CLAUDE.md を薄いアダプタにする
選んだもの：CLAUDE.md は AGENTS.md をインポートし、Claude Code 固有の差分だけを書く
理由：
- 共通ルールを 2 ファイルに書くと、片方だけ直す事故が必ず起きる
- 前述のとおり、Claude Code は
CLAUDE.mdがあるとAGENTS.mdを自動では読まないため、@AGENTS.mdで明示的に取り込む
トレードオフ：
- メリット：共通ルールの正本が
AGENTS.mdの 1 つになる - デメリット：Claude Code 固有の機能（ツール名など）を
AGENTS.md側に書かないよう、書き分けを意識する必要がある
判断3: Skills を .claude/skills/ に置く vs リポジトリ直下の skills/ に置く
選んだもの：リポジトリ直下の skills/
理由：
-
.claude/skills/は Claude Code の仕組みで、Codex など他のエージェントからは「Claude Code 用の場所」に見える - 手順はエージェントを問わず共通の知識なので、特定ツールのディレクトリに閉じ込めたくなかった
トレードオフ：
- メリット：Codex でも Claude Code でも、
AGENTS.mdのルーティング表から同じSKILL.mdに辿り着ける - デメリット：Claude Code のネイティブな Skills 機能（
descriptionを常に見せておき、必要なときに本文を読み込む仕組み）には乗らない。AGENTS.mdのルーティング表で読みに行かせる必要がある
Claude Code だけで完結するリポジトリなら、.claude/skills/ に置いてネイティブ機能を使うほうが素直です。複数エージェントで共有するかどうかで判断が分かれます。
判断4: What / Why / How / History を分ける
選んだもの：情報の種類ごとに置き場所を分ける
| 種類 | 問い | 置き場所 |
|---|---|---|
| What | システムは何を満たすべきか | docs/specs/ |
| Why | なぜその設計にしたか | docs/adr/ |
| How | どう構成されているか／作業をどう行うか |
docs/architecture/ ／ skills/
|
| History | いつ何をして、何が分かったか | リポジトリの外（Issue、Notion などの作業ログ） |
理由：
- 仕様書に変更の経緯を書き足していくと、「今の仕様」と「昔の仕様」の区別がつかなくなる
- エージェントが古い経緯を読んで、すでに廃止した仕様に従ってしまうのを防ぎたい
- 履歴は通常の実装作業では不要なので、リポジトリの外に置いて読ませない
バックログも同じ考え方で、全量（完了・見送りを含む）はリポジトリの外で管理し、リポジトリには「未着手・対応中」だけを置くようにしています。完了した項目の履歴をエージェントに毎回読ませる必要はないからです。
ドキュメントの責務モデル
アプリのデータモデルにあたるのが、「どのファイルがどの情報の正本か」の定義です。
ディレクトリ構成
アプリ開発のリポジトリでは、次の構成を基本にしています。技術スタックに合わせて調整して構いませんが、What / Why / How / History の分離と「正本は 1 つ」は維持します。
project/
├── AGENTS.md # ルーター兼行動原則（全エージェント共通）
├── CLAUDE.md # Claude Code 固有のアダプタ
├── README.md # 人間向けの入口
├── DOCUMENTATION-PHILOSOPHY.md # ドキュメントの置き場所のルール
├── skills/
│ ├── testing/
│ │ └── SKILL.md
│ └── release/
│ └── SKILL.md
├── docs/
│ ├── specs/ # What
│ │ ├── requirements.md
│ │ └── roadmap.md # 未着手・対応中だけ
│ ├── architecture/ # How it's built
│ ├── adr/ # Why
│ └── operations/ # デプロイ・障害対応など
├── src/
└── tests/
情報の置き場所の判定表
新しい情報を書くときは、次の問いで置き場所を決めます。
| 問い | 置き場所 |
|---|---|
| AI が常に守るべきことか？ | AGENTS.md |
| Claude Code だけに関係することか？ | CLAUDE.md |
| この作業をどう行うか？ | skills/ |
| システムは何をするべきか？ | docs/specs/ |
| システムはどう構成されているか？ | docs/architecture/ |
| なぜこの設計にしたか？ | docs/adr/ |
| 何を実施し、何が分かったか？ | リポジトリ外の作業ログ |
| 新しく参加する人に何を説明するか？ | README.md |
| 機械的に保証できるか？ | Code / Schema / Tests |
正本の優先順位
ドキュメントと実装が食い違ったときにどちらを信じるかも、先に決めておきます。
| 情報 | 正本 |
|---|---|
| 実行時の動作 | Code / Tests |
| API スキーマ | OpenAPI / Code |
| DB スキーマ | Migration / Schema |
| スクリプトの引数・挙動 | スクリプトのコード |
| 製品の要件 | docs/specs/ |
| 設計判断の理由 | docs/adr/ |
| 作業手順 | skills/ |
| エージェントの振る舞い | AGENTS.md |
「動くもの（Code / Tests / Schema）がドキュメントより優先」という原則（Executable Truth Wins）を置いておくと、エージェントがドキュメントの古い記述を信じて実装を壊すのを防げます。たとえばスクリプトの引数は README に書き写さず、「引数はスクリプトのコードが正」と書いておくほうが確実です。
各ファイルの書き方
API 設計にあたるのが、エージェントが読む各ファイルの「インターフェース」です。
AGENTS.md
書くもの・書かないものを決めておきます。
| 書く | 書かない |
|---|---|
| 最重要の行動原則 | 詳細なアーキテクチャ |
| 絶対に守る制約 | DB 定義・API 一覧 |
| ドキュメントの参照ルール | 長大なコーディング規約 |
| Skill の利用ルール（タスク→Skill の表） | 詳細なテスト手順・デプロイ手順 |
| 仕様変更時の判断ルール | 過去の変更履歴 |
| テストの基本方針 | 大量の設計判断 |
実際の AGENTS.md は、おおむね次の形です（記事執筆用リポジトリのものを一般化しています）。
# AGENTS.md
このリポジトリで作業する AI エージェント共通の行動原則とルーティングです。
仕様や手順の詳細はここに書かず、下記の参照先を正本とします。
## 基本行動原則
1. 既存の仕様・設計・コードを優先する。仕様変更を推測で行わない
2. タスクに必要な情報だけを読む。docs/ や skills/ を一括で読まない
3. 実装を変更したら、変更範囲に対応するテストを実行する
## 絶対に守る制約
- 自動生成ファイル（例：INDEX.md）は手で編集しない
- main へ直接コミットしない
## タスク別ルーティング
作業を始める前に、該当する Skill を読んでその手順に従う。
| タスク | Skill |
|---|---|
| テストの追加・実行 | skills/testing/SKILL.md |
| リリース | skills/release/SKILL.md |
## 参照先（正本）
| 情報 | 正本 |
|---|---|
| 要件・仕様 | docs/specs/ |
| 現在の構成 | docs/architecture/ |
| 設計判断の理由 | docs/adr/ |
| ドキュメントの置き場所 | DOCUMENTATION-PHILOSOPHY.md |
行数そのものを目標にする必要はありません。大事なのは、毎回読む必要があることだけを書くことです。
CLAUDE.md
共通ルールは AGENTS.md をインポートして済ませ、Claude Code 固有のことだけを書きます。
# CLAUDE.md
@AGENTS.md
## Claude Code 固有
- 共通の行動原則・ルーティングは上記 AGENTS.md が正本。このファイルには Claude Code 固有のことだけを書く
- Skill は Codex 等と共有するため .claude/skills/ ではなくリポジトリ直下の skills/ に置いている
SKILL.md
Skill は「特定の作業を正しく行うための手順書」です。どの Skill も同じ見出しで書くと、エージェントも人間も読みやすくなります。
---
name: release
description: アプリのリリース作業を行う。「リリースして」「バージョンを上げて」という依頼で使う。
---
# リリース
## いつ使うか
## 必要な入力
## 参照するドキュメント
## 手順
## 検証
## エラー時の対応
## 完了条件
name / description のフロントマターは Claude Code の Skills と同じ形にしておくと、あとから .claude/skills/ に移したくなったときもそのまま使えます。「参照するドキュメント」には正本へのパスだけを書き、仕様をコピーしないのがポイントです。
ADR
設計判断は ADR（Architecture Decision Record）として 1 判断 1 ファイルで残します。Michael Nygard 氏が提案した形式をベースに、次の見出しで書いています。
# ADR-0001: タイトル
## Status
Accepted
## Context
背景・問題。
## Decision
決定内容。
## Rationale
決定理由。
## Alternatives
検討した代替案。
## Consequences
メリット・デメリット。
## Related Documents
関連する仕様・Architecture。
Status は Proposed / Accepted / Deprecated / Superseded のいずれかです。過去の ADR は削除せず、判断が変わったら Superseded にして新しい ADR を書きます。
設計の振り返り
うまくいったこと
整理前後の行数は次のとおりです。
| ファイル | 整理前 | 整理後 |
|---|---|---|
AGENTS.md |
278 行 | 51 行 |
CLAUDE.md |
278 行 | 9 行 |
skills/*/SKILL.md |
なし | 4 ファイル（71〜123 行） |
-
常時コンテキストが小さくなった：Claude Code で毎回読まれるのは
CLAUDE.mdと取り込まれるAGENTS.mdの約 60 行になり、執筆・書き直し・公開・コミットの手順は該当タスクのときだけ読まれるようになった -
直す場所が 1 つになった：媒体のルールは各媒体の
README.mdだけが正本になり、AGENTS.mdには参照先しか書いていない -
エージェントを乗り換えても知識が残る：Codex と Claude Code で同じ
AGENTS.mdとskills/を使える
反省点・次回への学び
- ドキュメントの総量は減っていない：Skill を合わせると全体の行数はむしろ増えている。減ったのは「毎回読む量」であって、書く量ではない
-
ルーティング表のメンテナンスが必要：Skill を追加したら
AGENTS.mdのルーティング表にも 1 行足さないと、エージェントが辿り着けない - 最初から分けておけばよかった：コピーで増やしたファイルを後から分解するより、最初から「ルーター＋Skill」で作るほうがはるかに楽
避けたいアンチパターン
整理してみて、次のような書き方が肥大化と矛盾の原因になると分かりました。
- Mega AGENTS.md / Mega CLAUDE.md：数百行の指示書に全仕様を集約する
- Read Everything First：「作業前に docs 以下をすべて読むこと」と指示する
- Duplicate Rules：同じルールを複数ファイルに書く
- Historical Spec：現在の仕様書に、過去の変更履歴を書き足し続ける
- Documentation as Prompt Dump：一度 AI に渡したプロンプトを、意味を整理せずにそのままドキュメントへ追記し続ける
とくに最後の「プロンプトの貼り溜め」は気づきにくいです。エージェントに口頭で伝えた指示を残しておきたくなったら、その指示が What / Why / How のどれにあたるかを考えて、該当する正本に書き直します。
既存リポジトリを移行するときの手順
すでに肥大化している場合は、次の順で分解すると進めやすいです。
- 棚卸し：エージェント指示書・README・docs にある情報を一覧にする
- 重複の特定：同じ内容が複数か所にあるものを洗い出す
- 正本の決定：情報ごとに正本を 1 つ決める
-
手順の抽出：作業手順を
skills/へ移す -
仕様の抽出：要件・仕様を
docs/specs/へ移す -
構成の抽出：現在の構成を
docs/architecture/へ移す -
判断の抽出：設計判断と理由を
docs/adr/へ移す - 履歴の抽出：経緯・作業ログをリポジトリの外へ移す
-
指示書の最小化：
AGENTS.mdとCLAUDE.mdを行動原則とルーティングだけにする
最後に、ドキュメントの置き場所のルール自体を DOCUMENTATION-PHILOSOPHY.md のようなファイルにまとめておくと、人間もエージェントも「新しい情報をどこに書くか」で迷わなくなります。
まとめ
- AI エージェント向けドキュメントの課題は、量そのものではなく 毎回読み込まれる量・重複・陳腐化・目的の情報に辿り着くまでの手間 にある
-
AGENTS.mdは知識の本体ではなく ルーター にし、手順はskills/、仕様はdocs/specs/、理由はdocs/adr/に分ける -
CLAUDE.mdは@AGENTS.mdを取り込む 薄いアダプタ にすると、Codex と Claude Code で同じ知識を共有できる -
@importで分割しても常時コンテキストは減らない。減らすには、毎回読むファイルそのものを小さくする
「AI にたくさんの情報を与える」より、「AI が必要な情報を必要なときに正確に取れる」ことを優先する。この 1 文が、今回の設計の軸です。