2026-05-26 12:01:04 +08:00
|
|
|
|
# ADR-007 决策故事：信息架构为什么从「大文档」变成「分层设计」
|
2026-05-25 16:49:36 +08:00
|
|
|
|
|
2026-05-26 12:01:04 +08:00
|
|
|
|
## 背景
|
|
|
|
|
|
|
|
|
|
|
|
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 的核心逻辑：
|
|
|
|
|
|
|
|
|
|
|
|
1. **仪表盘**（DASHBOARD.md）——给人类看，30 秒了解项目全貌，不写代码细节
|
|
|
|
|
|
2. **路线图**（ROADMAP.md）——人+AI 共享视野，任务分配和进度跟踪
|
|
|
|
|
|
3. **角色工作台**（`.ai/roles/{arch,dev,qa}/`）——每个 AI 自己的 today.md + queue.md，只加载自己需要的上下文
|
|
|
|
|
|
4. **知识沉淀**（`.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 的注意力分配方案。**
|
