brain は Markdown のアーキテクチャです。Dylan Engelbrecht は、エージェントが大量の文脈を抱えつつ、タスクに関係する情報だけを選べるように、それを作り込み、磨き続けてきました。
地図のように働きます。エージェントは図書館を丸暗記しません。方位を取ってから、一本の道を開きます。
この考え方には名前があります。progressive disclosure（Nielsen Norman Group）です。人間の思考に似ています。最初に地図を手に取り、方位を取ります。街の通り名を全部先に読むことはしません。
チャットはその地図ではありません。チャットは今の会話です。AGENTS.md もその地図ではありません。リポジトリでの働き方——ビルド、テスト、家を壊さない——を伝えます。brain は、エージェントが動く世界の記憶です。人、サービス、意思決定、語彙、先週何が起きたか。
フォルダ名はプロトコルではありません。プロトコルは形です。インデックス、各項目の横の一行説明、知識は一か所に置くこと。
ウォークスルー（簡略版）
かなり単純化した例ですが、しばらく付き合ってください。
タスクは「私の好きな食べ物は何？」です。
エージェントは全ファイルを読み込みません。インデックスから始めます。インデックスは第一級のパスを並べます。各行は、エージェントが「開く」か「飛ばす」かを決められる短さです。
下のツリーは話半分で見てください。名前は自分の世界に合わせてください。大事なのはインデックス、一行の説明、知識がつながっていることです。
話半分のツリー — 名前は合わせて使う
AGENTS.md — mentions that the user's name is x
INDEX.md — the map
Wiki/
People/
x.md — a page about the user
y.mdエージェントは AGENTS.md ですでに、ユーザーの名前が x だと見ています。インデックスを見ます。Wiki/People/ が見えます。x というファイルが見えます。関係ありそうなので、そのファイルを開きます。y.md は開きません。wiki 全体はダンプしません。
x.md の中に、好きな食べ物はライムだ、というメモがあるかもしれません。メモは未検証と印が付いています。以前のエージェントが推測したのかもしれません。確認はされていません。
だからエージェントは「好きな食べ物はライムです」と言ってはいけません。こう言うべきです。「好きな食べ物はライムだと思いますが、未確認です。合っていますか？」
これが縮小版のプロトコルです。まず地図。一つの一致。一つのファイル。未確認の事実には推測ではなく質問を返します。
インデックスが果たすべきこと
関連するかどうか知るためにファイルを開かなければならないなら、インデックスは失敗しています。
良いインデックス行はルーティングのヒントです。トピック、パス、いつ開くか。入れ子のインデックス（人、サービス、インシデント）は、さらなる地図であり、起動用ファイルを増やすことではありません。事実は一か所に置きます。別の場所で必要なら指差します。コピーしません。コピーはずれます。
同じルールが指示にも当てはまります。編集中のファイルに一番近い AGENTS.md が勝ちます。ルートにデフォルト。例外はサブツリーの隣。The AGENTS.md standard for AI coding agents を参照してください。
おもちゃの例のあと：三つの寿命
検索を一度見れば、層は分かりやすくなります。
今週のためのメモがあります。このインシデント。このローンチ。古くなったらアーカイブするか削除します。
何週間も真であり続けるページがあります。人、サービス、語彙、アーキテクチャ上の決定。それらにはバージョンを付けます。
すでに起きた記録があり、その場で書き換えてはいけません。インシデントの記録、出荷したマイルストーン、監査メモ。エンティティの事実はリンクします。複製しません。
事実は安定すると移せます。確認された推測は、人物ページの verified な一行になります。二度出たチャット指示はプレイブックの一行になります。繰り返し出てくる名前は wiki のエンティティになります。エージェントが同じ質問や同じ失敗を繰り返すまで、余分なフォルダは作らないでください。
どう知ったかを書く
Markdown は人間が読みやすいです。エージェントには停止標識も必要です。
事実やファイルごとに、次を書いてください。
status — verified、needs-verification、または deprecated。
source — URL、人、チケット、文書。
last-verified — 日付。
ライムの例と同じように needs-verification を扱います。聞くか引用する。発明しない。未知は未知のまま。
それが出所です。これは本当か、誰によると、いつの時点か、に答えます。
アクセス制御は別の仕事です。誰がそのファイルを見てよいかを問います。brain によっては internal、restricted、secret といったラベルが要ります。検証フィールドに折り込まないでください。
ルールは、それが支配する層の隣に置く
各層に独自の AGENTS.md を添えます。ルートファイルは全体の境界と読む順を決めます。wiki ファイルは、人物ページやサービスページをいつ書くかを説明します。ホットコンテキストファイルは、いつアーカイブするかを決めます。エージェントは一番近いディレクトリでルールを見つけます。コードリポジトリと同じ優先順位です。
同じウォークスルー、仕事の文脈
課金 API を出荷しているチームを想像してください。タスクは「課金フェイルオーバーは何か？」です。
エージェントは公開ホームページではなく、インデックスから始めます。インデックスは、課金フェイルオーバーなら wiki/runbooks/billing-failover.md を開け、と言います。そのランブックを開きます。すべてのサービスページは読み込みません。
その地図のスケッチです。
INDEX.md — 地図であり、ダンプではない
# INDEX.md — Agent brain
## Read order
1. working-memory/current.md
2. wiki/INDEX.md
3. governance.md
## Layers
| Layer | Path | Lifespan |
| Hot context | working-memory/ | This week |
| Wiki | wiki/ | Stays true |
| Incidents | incidents/ | Already happened |
## Open when
| Signal | Path |
| On-call or Sev | working-memory/current.md, then incidents/ |
| What is service X? | wiki/services/INDEX.md |
| Billing failover | wiki/runbooks/billing-failover.md |ホットコンテキストはこう見えるかもしれません。ソースと日付に注目してください。
working-memory/current.md — 今週、出所つき
---
title: Current focus
status: verified
last-verified: 2026-08-29
source: #inc-1842 retro notes
---
## This week
- Billing retry storm after the card-network timeout change.
- Cut over invoice PDF rendering to the new worker.
## Open threads
- Confirm whether legacy accounts still hit /v1/invoices:finalize.wiki フォルダは、エージェントがそのフォルダに入ったときだけ見つかる独自のルールを持てます。
wiki/AGENTS.md — 一番近いディレクトリのルール
# AGENTS.md — Wiki
## Purpose
Durable entities: services, customers, concepts, runbooks.
## When to write here
- Stable facts with a source (ticket, spec, or named owner).
- One file per service or concept.
## Never
- Duplicate SLOs or owner names that live on the service page — link.
- Treat chat summaries as canonical.あくまでスケッチです。研究室なら papers/ と experiments/ を置くかもしれません。運用チームは二度目の繰り返しまで incidents/ を省略するかもしれません。フォルダ名はプロトコルではありません。
小さく始める
インデックス一つ。ホットコンテキストファイル一つ。エンティティのテンプレート一つ。「知らなければ聞け」と書くページ一つ。
繰り返しが隙間を証明したとき、層を足します。brain は wiki のダンプではありません。地図と、意図して開くファイルと、ライムを発明しない習慣です。
まとめ
コーパスをダンプしない。地図から始めて方位を取る。インデックスの一行をたどる。ファイルを一つ開く。ストアごとに寿命を。主張ごとに出所を。正規の場所は一つ。ルールはそれが支配する層の隣。未確認なら聞く。
Dylan Engelbrecht は、エージェントの実践が進むにつれてこのナレッジハブを更新します。これらの記事は生きた参照として扱ってください。今の実践であり、凍ったスナップショットではありません。