tupingr
5b428d0810
- Phase 1 标记 100% 完成，Phase 2 标记 ACTIVE - Dev AI 工作台重写：8个任务入队 + 依赖关系图 - 一鸡多吃：6篇对外分享文章（项目缘起/框架思路/阶段复盘/3篇决策故事） - 新增 share-context Skill（内部文档→对外分享自动化） - P01 文档同步更新（需求/架构/接口定义） Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
3.7 KiB
ADR-007 决策故事：信息架构为什么从「大文档」变成「分层设计」
背景
ErrLens 项目从一开始就确定用「1 人 + 3 AI」的协作模式——Arch AI 做架构，Dev AI 写代码，QA AI 做测试。
但怎么让 3 个 AI 高效协作？我最初的做法很朴素：写一个大的 AGENTS.md，把项目介绍、架构设计、开发规范、权限体系全塞进去，每个 AI 启动时都读这一份。
然后问题就来了。
问题：AI 记不住、看不懂、互相干扰
第一个问题：记不住。
AGENTS.md 写到 2000 行时，Claude 的回复开始出现明显的「失忆」——前面提到的决策，后面讨论时就忘了。原因是上下文窗口虽然号称 200K token，但越靠后的内容，AI 的关注权重越低。
第二个问题：看不懂重点。
AGENTS.md 里混了所有信息——PRD 摘要、架构图、API 定义、目录结构、权限矩阵、Skill 描述……Dev AI 需要在 2000 行里找到和自己相关的 200 行。人类会跳读，AI 不会——它全读完后，重点已经淹没了。
第三个问题：互相干扰。
一个更隐蔽的问题：Dev AI 不需要知道 QA AI 的测试流程，Arch AI 不需要知道具体的代码目录结构。把不该看的信息喂给 AI，不仅浪费 token，更容易让它「想太多」——写出过度设计或不相关的代码。
选项
| 选项 | 优势 | 劣势 |
|---|---|---|
| A: 维持单体文档 | 维护简单，改一处就行 | 越长越差，AI 协作天花板低 |
| B: 精简 AGENTS.md | 立即可做 | 精简意味着丢掉信息，该有的细节还是要有的 |
| C: 分层信息架构 | 每个 AI 只看自己的，token 利用率高 | 需要重新设计目录结构，上下游依赖要梳理清楚 |
思考过程
我一开始想走 B 路线——把 AGENTS.md 精简到 500 行以内。但很快发现不行：精简掉的内容不是「冗余」，是「必要的细节」。比如 Drizzle Schema 定义，对 Dev AI 就是刚需，你不能为了省 token 把它删了。
然后我想到一个类比：人类团队怎么分工？
一个有 3 个员工的团队，不会把所有信息贴在一面墙上。而是每人有独立工位，各自维护自己的待办和参考资料。共享的信息放在公共区域。
AI 也应该这样。
选项 C 的核心逻辑：
- 仪表盘（DASHBOARD.md）——给人类看，30 秒了解项目全貌，不写代码细节
- 路线图（ROADMAP.md）——人+AI 共享视野，任务分配和进度跟踪
- 角色工作台（
.ai/roles/{arch,dev,qa}/）——每个 AI 自己的 today.md + queue.md，只加载自己需要的上下文 - 知识沉淀（
.ai/knowledge/）——ADR（架构决策记录）、journal（开发日志），按需加载
每层有 token 预算。Arch AI 启动时加载约 3K token（today + queue + decisions），Dev AI 类似。比单体 AGENTS.md 的 15K+ token 减少了 80%。
结果
分层后，几个明显的变化：
- AI 回复质量更稳定：不再出现「前面说了后面忘」的情况
- 上下文切换更快：Dev AI 启动直接读 dev/today.md，不需要从 PRD 开始消化
- 人类管理成本降低：DASHBOARD.md 一眼看到项目状态，不需要翻 10 个文件
- 「一鸡多吃」变得自然：内部分层文档 → 去掉敏感信息 → 对外分享文章，流水线化
如果重来一次，我会从第一天就做分层。单体文档阶段浪费了大约 1 天的 AI token 和人类审核精力。
一句话总结
为 AI 设计文档和为人设计文档，是完全不同的两件事。人会跳读，AI 不会——所以你的信息架构就是 AI 的注意力分配方案。