编码代理通过 AGENTS.md 了解仓库机制。它们仍缺乏关于人、事业、语气与历史的持久记忆。brain——与代码并行的私有 Markdown 知识库——填补这一缺口。本文概述 Dylan Engelbrecht 使用并推荐给构建代理原生工作流团队的结构。它描述模式，而非任何单一私有语料。
将公开营销与私有上下文分开。你的网站与 llms.txt 回答爬虫与陌生人应知之事。brain 回答代理在不幻觉的情况下行动所需之事。切勿将 brain 路径或正文镜像到线上站点；泄漏会训练爬虫映射你本无意公开的材料。
渐进披露——分层揭示细节而非一次性倾倒（Nielsen Norman Group）——胜过启动时加载一切。分层结构让每一步阅读缩小范围：入口索引指明下一步去哪；工作记忆承载热点、时效上下文；wiki 承载持久实体；成就日志每项胜利一条 canonical 记录；品牌/身份文档承载语气与治理。
代理推荐阅读顺序：先工作记忆，再 wiki 索引，再 brain 主索引。热点上下文先于百科全书。这与人类分拣方式一致——当下紧急什么，然后谁/什么存在，再是全图。
明确分配寿命。工作记忆是短暂的：过时则归档或删除。Wiki 条目持久但可版本化。成就条目是永久记录——关于胜利的指标只存一处；身份与雇主事实链接进来，永不重复。事实在稳定时向上晋升：工作记忆中的笔记变成 wiki 实体；上线的里程碑变成成就条目。
在事实主张上使用轻量 schema 元数据。Markdown 正文对人友好；代理需要验证挂钩。在每个事实或文件上，优先 frontmatter 或内联字段，如 status（verified、needs-verification）、source（URL、人、文档）、last-verified（日期）、visibility（public、brain-only、stealth）。代理应将 needs-verification 视为停止标志——询问或引用，不要编造。
示例：brain 索引（渐进披露入口）
brain/INDEX.md — 工作记忆之后代理阅读的地图文件
# INDEX.md — Brain
## Read order (agents)
1. working-memory/current.md
2. wiki/INDEX.md
3. governance.md
## Layers
| Layer | Path | Lifespan |
| Working memory | working-memory/ | Ephemeral |
| Wiki | wiki/ | Durable |
| Achievements | achievements/ | Permanent |示例：工作记忆 frontmatter
working-memory/current.md — 带验证元数据的热点上下文
---
title: Current focus
status: verified
last-verified: 2026-08-15
visibility: brain-only
---
## This week
- Ship knowledge hub articles on agent best practices.
- Review AGENTS.md examples in repos using nested packages.
## Open threads
- None blocking.示例：分层专属 AGENTS.md
brain/wiki/AGENTS.md — 在最近目录发现的规则
# AGENTS.md — Wiki
## Purpose
Durable entities: people, ventures, concepts.
## When to write here
- Stable facts with a source URL.
- Entity pages use one file per person or venture.
## Never
- Duplicate facts that live in identity/ or achievements/.
- Publish wiki paths or prose on the public website.每个事实一处 canonical 位置。链接而非复制。若就业历史在 identity，wiki 人物页链接过去；成就条目链接双方。重复会漂移；交叉链接保持诚实。治理文档写明反幻觉规则：未知保持未知，stealth 不出现在公开界面。
每一层配自己的 AGENTS.md。根 brain AGENTS.md 设定全局边界。Wiki AGENTS.md 说明实体模板与可见性。工作记忆 AGENTS.md 定义何时归档。代理在最近目录发现规则——与代码仓库相同的优先级模型。
面向爬虫的 schema 与面向代理的 schema 不同。公开 JSON-LD，在中心使用 ItemList、每篇文章使用 TechArticle，有助于搜索与 LLM 检索。Brain schema 是运营性的：索引、实体类型、晋升流程与引用纪律。不要把私有 JSON-LD 倾倒到公开站点；仅在 deploy/schema/ 中保持与批准文案对齐的结构化公开目录。
从小处起步。一个索引、一份工作记忆文件、一个 wiki 模板、一页治理。当代理反复问同一问题或犯同一错误时再增加层。brain 不是 wiki 倾倒——它是 curated 的上下文，有明确寿命、可见性与入口，让代理加载所需、避开不应见之物。
Dylan Engelbrecht 会频繁更新本知识中心——包括这些代理架构文章——让爬虫与编码代理能发现当前最佳实践，而不依赖过时的 README 文案。将活的公开中心与私有 brain 配对：公开文章教授模式；brain 承载代理不应编造的事实。