起点：Agent 在文档里”迷路”
我用 AI Agent 在一个多项目工作区里做开发和迭代。工作区里有一个积累了半年的本地文档库——几十个项目目录、上百篇文档：需求、方案、报告、计划、手册，还混着已下线和被取代的版本。
问题很快显现：每次开新会话，Agent 都要花大量 token 去”找路”。
典型的浪费：
- 先读一长串
AGENTS.md（根 → 分类 → 项目），动辄几百行，才开始干活 - 不知道某篇权威文档在哪，于是在整个文档库里遍历、读无关文件
- 读到一个”待实施”的计划，结果它三个月前就做完了；读到一篇设计，其实早被否决
- 把面向用户的说明书、报告也当成了工作输入
我意识到：这套文档库是为人类整理的，不是为 Agent 检索设计的。它对人友好，对 Agent 昂贵。
诊断：文档库到底服务谁
把问题拆开，核心是三件事：
- 没有”任务 → 上下文”的路由。 Agent 拿到一个任务，得靠猜和搜。缺一张”改 X 先读 Y”的映射表。
- 活跃面被历史稀释。 几十篇计划里，真正在做的是个位数，其余是已完成/废弃/被取代的，但都平铺在同一层。
- 指令层太重。
AGENTS.md里塞了大量运维细节、端点表、E2E 步骤——这些是参考，不是约束，却每次会话都自动加载。
设计：三层地图 + 状态驱动
我把它重构成一套面向 Agent 的上下文系统，原则是：地图优先、状态驱动、人机分离、指令瘦身。
1. 地图层：根地图 + 项目地图
新增一个 MAP.md 作为唯一入口：
- 根地图：项目注册表（slug / 角色 / 仓库 / 分支 / 环境 / AGENTS 路径）+ 跨项目链路 + 检索协议 + 全局硬约束。
- 项目地图（每个项目一份，固定 schema）：角色、权威上下文（设计/契约/约定路径）、关键源码路径、命令、活跃工作、约束，以及一段
Lifecycle（dev / test / deploy / verify / rollback）。
Agent 的路径变成：根 MAP → 项目 MAP → 只读被点名的权威文档。禁止整库遍历写成硬规则。
2. 状态驱动：frontmatter 与计划生命周期
给所有内容文档统一 frontmatter（title/project/type/status/language + 可选）。其中最关键的是 status：
draft | review | approved | active | on-hold | completed | superseded | abandoned
- 计划必须有状态；终结态要注明日期与结果。
- 终态计划（完成/取代/废弃）移出
plans/到_archive/，活跃面只留在做的。 - 于是”查活跃工作”变成一条命令：
rg '^status: (active|approved|on-hold)' */plans。
3. 人机分离：人类产物移出工作源
把面向用户的产物——操作手册、指南、FAQ、报告——集中到 output/。它们是 Agent 写的东西，不是读的东西。工作源只保留：设计、需求、制度、活跃计划。
4. AGENTS 瘦身：只留硬约束与指针
AGENTS.md 是自动加载的固定成本。我把它压缩到只留：角色一句话、硬约束（安全/部署边界）、指向地图的指针。运维细节、端点表、长流程全部下沉到按需读取的参考文档。
量化：省了多少
同一个”改某功能”的任务，改造前后：
| 指标 | 改造前 | 改造后 |
|---|---|---|
| 每任务固定路由成本 | 400–870 行 | 80–130 行 |
| 全部 AGENTS 合计 | ~2500 行 | ~800 行 |
| 计划噪声（活跃/总量） | 26 篇平铺 | 活跃 5 篇，21 篇归档 |
| 文档定位 | 上百篇中探索 | 地图查表直达 |
固定上下文成本下降约 80%，AGENTS 体积下降约 68%。定点文档（计划/参考）本身是完成任务必需的，不算额外开销。
过程经验
重构本身也踩了几个坑，值得记下：
用源码核验文档状态，别信文档自己写的。 一批”待实施”的计划，状态行是写下时的快照，之后没更新。我逐条对照源码：有的功能其实已实现（计划该标”完成”），有的方案已被数据否证（该废弃）。文档状态是声明，源码是事实。
人机产物的边界要显式。 二进制交付物、品牌源文件、市场资料、备份……各有归属；把它们混进”文档库”会同时污染人和 Agent 的检索。
脱敏与历史清理。 迁移/下沉文档时，生产口令、服务器地址、内部标识必须替换为占位符。已经进入 git 历史的敏感内容，需要重写历史（filter-branch）再强制推送——这是一次性、不可逆的操作，要单独授权。
给 Agent 写检索协议，而不是让它自由发挥。 明确”先读地图、只读被点名文档、禁止整库遍历”，比任何优化都有效。
边界与反思
- 这套设计的收益来自**“多项目 + 文档多 + 频繁开新会话”**的场景。单项目小仓库，加一层地图可能得不偿失。
- 地图需要维护：目录变了、权威文档换了，
MAP.md和项目 AGENTS 要同步，否则地图会过期成新的噪声。 - 结构一次到位很难。我先做了地图层与状态驱动，细节的引用/一致性问题留到实际执行中按需修复——这比预扫全量更现实。
一句话：文档库的目标不该是”给人看得舒服”，而是”让 Agent 用最小上下文找对地方”。 当地图、状态、边界、指针都就位，Agent 的探索成本会断崖式下降。
说明：本文已对项目名、域名、主机、凭据、绝对路径做匿名化处理，仅保留方法与量化结论。