AGENTS.mdとMarkdownでAIエージェントの文脈共有を整理する「世界樹」運用

01ざっくり言うと

AIと一緒に制作・開発を進めていると、新しいチャットやセッションを開くたびに、毎回同じ前提を説明し直すことがあります。

プロジェクトの目的、設計方針、ディレクトリ構造、やってはいけないこと、直近の作業状況……。 これらを毎回口頭で説明していると、作業前の準備だけでかなり消耗します。

そこで、既存の開発文化にある README、Issue 管理、設計メモ、PR 単位の変更管理などを参考にしながら、AI が必要な文脈を自分で読みに行ける Markdown ファイル群を作りました。

私はこれを「世界樹」と呼んでいます。

名前は大げさですが、やっていることはシンプルです。 プロジェクトの前提や判断基準を、AI と人間の両方が参照できる場所に整理しておく、というだけです。

02このシリーズについて

この記事は、AIと制作・開発を進める中で、プロジェクトのコンテキストをどう整理しているかをまとめるシリーズの第1弾です。

今のところ、次の3本に分けて書く予定です。

1. Markdownで文脈を整理した話（この記事）
2. 肥大化した文脈を軽量・最適化する話
3. Skill / WorkflowでHOWを分離する話（手順や作業方法を文脈本体から切り出す）

今回はまず、AIがプロジェクトの前提や判断基準を読み直せるようにするための、Markdownベースの基本構成について書きます。

03はじめに

私はエンジニアではありません。 個人で小規模な Web サイト制作を請け負う「スタジオ猫の手」を運営しています。

AI と一緒に制作を進めるようになってから、README、Issue 管理、設計メモ、PR 単位の変更管理といった既存の開発文化が、なぜ大切にされてきたのかを強く実感するようになりました。

同時に、コードを読めて書ける人の強さも実感しています。

AI が生成したものに対して、「たぶん問題はこのあたりにある」と感じても、自分で読んで直せなければ、結局はもう一度 AI に説明して直してもらう必要があります。小さな修正でも、意図がうまく伝わらなければ遠回りになります。

これは、AI が作ったイラストの一部だけを直したいのに、自分で描けないために何度も指示を出す感覚にも近いです。プログラミングでも同じで、読む力・直す力は、AI の力をより活かすための大きな武器だと感じています。

だからこそ、日々コードを書き、設計し、レビューしているエンジニアやプログラマーの方々には強い敬意があります。私自身も AI 任せで終わるのではなく、少しずつコードを読める範囲、判断できる範囲を増やしていきたいと考えています。

そのうえで、今の自分が AI と継続的に制作していくためにまず必要だったのが、プロジェクトの前提や判断基準を、AI と人間の両方が参照できる形に整理することでした。

AI はとても強力です。ただ、AI に任せる範囲が広がるほど、人間側が「何を大事にするのか」「なぜその判断をしたのか」「何をしてはいけないのか」を外に書き出しておく重要性も増えると感じました。

この記事は、「AI で何でもできるようになった」という話ではありません。 AI と継続的に制作するために、非エンジニアの制作現場でも扱いやすい形で、プロジェクトの文脈をどう整理したかという実践記録です。

04困っていたこと：前提共有の無限ループ

AI と長く作業していると、チャットやセッションが重くなったり、前提がずれてきたりすることがあります。

そのたびに新しいセッションを開くのですが、そこで待っているのが前提共有のやり直しです。

• このプロジェクトは何を大事にしているのか
• どのファイルが何の責務を持っているのか
• 今どの作業フェーズなのか
• どのルールを守るべきなのか
• どの判断はすでに済んでいるのか

これを毎回説明するのはかなり大変です。

しかも、説明が長くなるほどチャットも重くなり、また新しいセッションを開き、また説明し直すことになります。

まさに「現代の賽の河原」。

そこで、新しい AI セッションを開いたときでも、短い指示だけでプロジェクトの文脈を把握できる状態を作りたいと考えました。

05やったこと：AI が文脈を取りに行ける構造を作る

重要なのは、AI にすべてを覚えさせることではなく、必要な情報にたどり着ける構造を用意することだと考えました。

そこで、プロジェクト内に _world_tree/ というディレクトリを作り、役割ごとに Markdown ファイルを分けました。

全体の構造を図にすると、次のようなイメージです。

実際の構成は、おおよそ次のような形です。

_world_tree/
├── _README.md           # 案内板。どのファイルを読むべきか判断する起点
├── TRUNK.md             # プロジェクトの憲法。優先順位と禁則事項
├── CONTEXT.md           # 短期記憶。直近の作業状況
├── PROJECT_STATUS.md    # 中期のタスクボード
├── PROJECT_STRUCTURE.md # ディレクトリ構造と責務
├── WATCH_RULES.md       # 世界樹を更新するためのトリガー
├── MAP.md               # サイトマップと導線
└── ARCHITECTURE.md      # 技術設計の詳細

この構成に加えて、プロジェクトルートには AGENTS.md を置き、AI に最初に読んでもらう入口にしています。

AGENTS.md には、詳しいルールをすべて書くのではなく、入口として必要な情報を書きます。 この記事では、世界樹との関係がわかる部分だけを抜粋します。

作業を始める前に `_world_tree/_README.md` を確認し、
タスクに応じて必要な文脈ファイルを参照してください。

AGENTS.md は入口ゲートにする

ここで少し補足します。

実際の運用では、AGENTS.md に「案内板を読んでください」とだけ書いているわけではありません。

AGENTS.md には、プロジェクト概要、参照すべき情報源の優先順位、言語設定、最低限の実装原則、セキュリティ上の注意、完了報告前のチェック項目などを書いています。

つまり、AGENTS.md は世界樹そのものではなく、AI が作業に入る前に必ず通る入口ゲートです。

ただし、ここにプロジェクトの文脈を全部書いてしまうと、すぐに肥大化します。

そこで、AGENTS.md には「必ず守るべき最低限のルール」と「どの順番で情報を読みに行くか」だけを書き、詳しい思想・進捗・構造・設計判断は _world_tree/ 側に分けています。

AGENTS.md は玄関、_world_tree/_README.md は館内案内板、各 Markdown ファイルは個別の部屋、というイメージです。

この分離により、入口は軽く保ちつつ、必要な文脈にはたどり着けるようにしています。

なお、この仕組みは、Claude CodeやCodex、Antigravity などの AI がプロジェクト内のファイルを自律的に読みに行ける制作環境が前提です。チャット型の UI で使う場合は、Google Drive 連携などでファイルを参照できるようにしておくと、同じ考え方で運用できます。

06各ファイルの役割

_README.md：案内板

AI が「今のタスクではどのファイルを読むべきか」を判断するためのファイルです。

たとえば、次のように参照タイミングを整理します。

## Core — Always

- TRUNK.md：プロジェクトの思想・優先順位・禁則事項

## Core — Contextual

- CONTEXT.md：直近の作業状況を確認するとき
- PROJECT_STATUS.md：進捗や次のタスクを確認するとき
- PROJECT_STRUCTURE.md：ファイル配置や責務を確認するとき

## Task-Specific

- MAP.md：サイト構成や導線を扱うとき
- ARCHITECTURE.md：技術設計に関わるとき
- WATCH_RULES.md：作業後に世界樹の更新が必要か確認するとき

全部を毎回読ませるのではなく、必要なものだけ読ませるためのルーティング表です。

TRUNK.md：プロジェクトの憲法

プロジェクトで何を優先するのか、何をしてはいけないのかを書きます。

たとえば、Web サイト制作なら次のような内容です。

- 優先順位1：既存SEO・検索評価を落とさない
- 優先順位2：ユーザーが迷わず目的の情報にたどり着けること
- 優先順位3：サイト全体の世界観・トーンの一貫性
- 禁則：流行や見た目の派手さを、目的や導線より優先しない

AI は優秀ですが、目的や優先順位を共有していないと、単発では良く見えるけれどプロジェクト全体とはずれた提案をすることがあります。

TRUNK.md は、そのずれを減らすための基準になります。

## 優先順位

1. 既存の検索評価を落とさない
   → 理由：現在の流入の大半が検索経由のため
2. ユーザーが迷わず目的にたどり着けること
   → 理由：問い合わせにつながる導線が最重要
3. サイト全体のトーンの一貫性
   → 理由：ページごとに雰囲気がばらけると信頼感が下がる

## 禁則事項

- AI の提案だけで仕様や思想を確定しない
- 流行の見た目を、目的や導線より優先しない
- 専門用語で賢く見せようとしない

PROJECT_STRUCTURE.md：ディレクトリ構造と責務

AI が想定外の場所にファイルを作ったり、公開してはいけない場所を誤解したりしないように、ディレクトリごとの責務を書きます。

my-project/
├── AGENTS.md        # AI向け入口
├── _world_tree/     # プロジェクト文脈の正本
├── src/             # アプリケーションコード
├── public/          # 公開ディレクトリ
└── content/         # コンテンツデータ

特に、公開ディレクトリ、非公開データ、生成物の置き場所などは、明示しておくと事故を減らせます。

CONTEXT.md と PROJECT_STATUS.md：短期記憶と中期進捗を分ける

直近の作業状況と、プロジェクト全体の進捗は分けて管理しています。

• CONTEXT.md：今やっていること、直近の判断、次に見るべきこと
• PROJECT_STATUS.md：フェーズ、完了したこと、次の大きなタスク

同じファイルに全部書くと、すぐに読みにくくなります。 短期と中期を分けることで、人間も AI も現在地を確認しやすくなりました。

# CONTEXT.md

> 役割: セッション間の短期記憶。

## Now

### A: 現在地

- トップページの主要セクションは仮実装済み
- サービス紹介セクションの導線を調整中
- 次はスマホ表示とCTA周りの見え方を確認する

### B: 次に見る場所

- 中期の進行は PROJECT_STATUS.md を見る
- デザイン方針は TRUNK.md を見る
- サイト構成は MAP.md を見る

### C: 作業境界

- 見た目の大きな変更は、まずデモ版で比較する
- 本番表示に影響する変更は、確認後に反映する
- 文章のトーンはサイト全体の語り口と揃える

## Focus Files

- public/index.php — トップページ
- public/assets/css/ — 表示スタイル
- public/content/ — ページ本文や設定データ

## Hurdles & Notes

- スマホ表示では余白が詰まりやすい
- CTAが強すぎると、サイト全体のやわらかさが崩れる
- 世界観と信頼感のバランスを崩さないこと

## Recent Moves

- 4/28: トップページのヒーロー文言を調整
- 4/27: サービス紹介セクションのデモ案を比較

# PROJECT_STATUS.md

> 役割: プロジェクト全体の俯瞰と中期タスク管理
> 更新: マイルストーン完了時 / 大型タスク開始時

## Current Mode

フェーズ: プレオープン前の調整段階。
主要ページの骨格はできているので、次は導線整理、スマホ表示、公開前チェックを進める。

## Active Tasks

| ID   | 状態        | タスク                 | 備考                       |
| ---- | ----------- | ---------------------- | -------------------------- |
| T-12 | in_progress | トップページ調整       | CTAとセクション順を確認    |
| T-13 | todo        | スマホ表示の確認       | 余白・文字サイズ・画像位置 |
| T-14 | todo        | お問い合わせ導線の確認 | フォームとリンク先を確認   |

ルール: in_progress は同時に最大2件まで。

## Milestones

| 日付 | 内容                           |
| ---- | ------------------------------ |
| 3/15 | プロジェクト構成と世界樹を整備 |
| 3/22 | トップページ初期案を作成       |
| 4/10 | プレオープン用の主要導線を整理 |

## Open Questions

- 正式公開前にどこまで記事導線を整えるか
- トップページでAI協業の説明をどこまで前面に出すか

# ISSUES_BOARD.md

> 役割: 未確定・粒度ばらばらのタスク置き場
> 読込: 通常作業では読まない。課題整理や作業範囲を決めるときだけ見る

## Open（近いうちに見たいもの）

| ID      | 優先度 | 件名                   | 次の一手                   |
| ------- | ------ | ---------------------- | -------------------------- |
| ISS-005 | High   | スマホ表示の余白が狭い | 実機表示で確認して調整する |
| ISS-006 | Medium | CTAの文言が少し強い    | 別案を2〜3個出して比較する |

## Watch（様子見）

| ID      | 件名                 | 見るタイミング         |
| ------- | -------------------- | ---------------------- |
| ISS-008 | トップ画像の表示速度 | 画像追加後に再チェック |

## Later（忘れたくないが今ではない）

| ID      | 件名               | メモ                       |
| ------- | ------------------ | -------------------------- |
| ISS-010 | 制作事例ページ追加 | 正式公開後に優先度を再確認 |

WATCH_RULES.md：情報が古くならないための更新トリガー

Markdown ファイル群を正本として運用するときの弱点は、情報が古くなることです。

そこで、どんな作業をしたら、どのファイルの更新を確認するべきかを書いています。

- 新しいページを追加した → MAP.md の更新を確認
- サービス内容を変更した → TRUNK.md の更新を確認
- ディレクトリ構造を変更した → PROJECT_STRUCTURE.md の更新を確認
- 大きな実装方針を変更した → ARCHITECTURE.md の更新を確認

これにより、AI 側から「この変更なら世界樹も更新した方がよさそうです」と提案してもらいやすくなりました。

ただし、WATCH_RULES.md を置くだけでは、AI が毎回自動的に確認してくれるとは限りません。実際の運用では、AGENTS.md 側に「タスク完了報告の前に、世界樹のメンテナンス提案が必要か確認する」という出口ゲートを書いています。

つまり、WATCH_RULES.md は更新判断の詳細表、AGENTS.md はそれを確認させるためのトリガー、という役割分担です。

07得られた効果

新規セッションの立ち上げが速くなった

以前は、新しいセッションを開くたびに長い前提説明が必要でした。

今は、だいたい次のように伝えるだけで始められます。

プロジェクトの現状を把握してください。
次に○○を進めたいです。
最初にどのファイルを確認すべきか判断してください。

AI が AGENTS.md と _world_tree/_README.md を起点に必要なファイルを読みに行くため、説明コストがかなり下がりました。

提案のずれが減った

プロジェクトの優先順位や禁則事項を先に共有しているため、AI の提案がプロジェクトの方向性から外れにくくなりました。

特に、デザインや文章のトーン、SEO を優先する場面、既存ファイルを触るときの慎重さなどで効果を感じています。

人間側の思考整理にもなった

AI のために書いていたつもりの文脈が、自分自身のための地図にもなりました。

何を大事にしているのか。 なぜその判断をしたのか。 今どこまで進んでいるのか。

それを外に書き出すことで、人間側の判断も安定しやすくなりました。

08限界と注意点

この仕組みは万能ではありません。

まず、Markdown を作るだけではうまく回りません。 情報が古くなれば、AI は古い情報をもとに判断してしまいます。 そのため、更新ルールやメンテナンスの習慣が必要です。

また、ファイルを増やしすぎると、逆にどこを読めばよいのかわかりにくくなります。 最初から全部作るより、必要になったものを少しずつ増やす方がよいと感じています。

さらに、AI が必ず正しく読んで、必ず正しく判断するわけではありません。 最終的な判断やレビューは人間側に残ります。

大規模なチーム開発には、もっと適した仕組みがあるかもしれません。 私自身はチーム開発の経験がないので、そこは正直わかりません。

ただ、個人制作や小規模なプロジェクトで AI と協働するとき、 Markdown ファイルを役割ごとに分けて置いておくだけでも、 かなり楽になったのは確かです。

09実際の制作案件でどう効いたか

ここまで紹介した構成は、実際のサイト制作案件でも使いました。 とくに効果を感じたのは、筆文字の代筆サービスを手がける筆耕ドットコム様のサイトリニューアルです。掲載については、クライアント様の許可をいただいています。

この案件では、単にページを作るだけでなく、「和に寄りすぎず、モダンで、それでいて主張しすぎない――空気のようなデザインにしてほしい」という要望に基づいて、サイト全体のトーン、導線、信頼訴求、SEO、文章表現を一貫させる必要がありました。

AI に単発で「いい感じに作って」と頼むだけでは、ページごとにトーンがずれます。

そこで、世界樹にサイトの思想、優先順位、避けたい表現、デザインの方向性、ページごとの役割を整理しました。

その結果、新しいセッションでも、AI が同じ前提を読み直しながら作業できるようになり、サイト全体の一貫性を保ちやすくなりました。

世界樹は、単に新規セッションの立ち上げコストを下げるだけではなく、 AI と一緒に、プロジェクト全体の判断基準を共有するための仕組みでもありました。

10まず作るなら2ファイルから

最初から大きな構成を作る必要はありません。

まずは、次の2つだけで十分だと思います。

AGENTS.md
_world_tree/_README.md

AGENTS.md には「作業前に案内板を読む」と書く。 _README.md には「どのタスクでは、どのファイルを読むか」を書く。

そのうえで、必要に応じて TRUNK.md や CONTEXT.md を足していくのが扱いやすいです。

世界樹は、最初から完成していたわけではありません。 困るたびに、少しずつ増えていったものです。

11おわりに

AI と制作していると、「もう全部 AI に任せればいいのでは」と感じる瞬間があります。

でも実際には、AI に任せる範囲が広がるほど、人間側の役割も変わっていくと感じています。

何を大事にするのか。 なぜその判断をしたのか。 どこに情報を置くのか。 何をしてはいけないのか。 あとから直しやすい形になっているか。

そうした前提を外に出し、AI と人間の両方が参照できる形にしておくことは、これからますます重要になるのではないかと思います。

「毎回の前提共有がつらい」 「AI がプロジェクトの文脈を忘れてしまう」 「チャットの外に判断基準を置きたい」

そう感じている方にとって、この記事が何かのヒントになれば嬉しいです。

次回は、この運用を続ける中で出てきた「Markdown自体が肥大化する問題」と、それを軽くする JSON index について書く予定です。