chore(phase): Phase 1 收尾 — 一鸡多吃 + Dev工作台初始化 + Phase 2启动
- 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>
This commit is contained in:
@@ -1,5 +1,75 @@
|
||||
# ADR-007 决策故事
|
||||
# ADR-007 决策故事:信息架构为什么从「大文档」变成「分层设计」
|
||||
|
||||
> 信息架构为什么从"单体文档"变成"分层设计"
|
||||
>
|
||||
> *(Phase 1 完成时撰写,基于 `.ai/knowledge/decisions.md` 中的 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 的核心逻辑:
|
||||
|
||||
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 的注意力分配方案。**
|
||||
|
||||
Reference in New Issue
Block a user