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>
107 lines
5.5 KiB
Markdown
107 lines
5.5 KiB
Markdown
# 框架设计思路：当文档的读者不是人类
|
||
|
||
> 传统项目结构对 AI 不友好——我的信息架构是怎么一步步推到重来的。
|
||
|
||
---
|
||
|
||
## 问题的起点：AI 看不懂我的项目
|
||
|
||
第一次用 Claude Code 时，我兴奋地让它帮我写个功能。结果它盯着我的项目看了半天，然后开始瞎写。
|
||
|
||
问题不在 AI，在我的项目文档。
|
||
|
||
一个典型的人类项目文档是这样的：一个巨大的 README.md，里面塞了项目介绍、架构设计、API 文档、部署说明、开发规范……人类会跳着读，挑自己需要的部分。但 AI 不会跳读——它会从头到尾读完，然后在第 5000 行开始「记忆衰减」。
|
||
|
||
更致命的是：**不同 AI 角色需要的信息完全不同。** Dev AI 需要知道数据库表结构，不需要知道为什么 ADR-007 选了分层架构。但你把这些全混在一个文件里，AI 就只能全部消化。
|
||
|
||
结论：**为人类设计的文档结构，不适合 AI 协作。**
|
||
|
||
---
|
||
|
||
## 第一次尝试：从 README 到 AGENTS.md
|
||
|
||
我先学着社区的做法，把所有 AI 需要的信息写进一个 `AGENTS.md`。
|
||
|
||
一开始还行。但越写越长。PRD、架构、技术栈、目录结构、权限矩阵、ADR、Skill 定义……写到 2000 行的时候，AI 开始「忘记」前面的内容。
|
||
|
||
问题出在 **token 预算**。Claude 的上下文窗口约 200K token，看起来很大，但要同时装下 AGENTS.md + 当前代码文件 + 对话历史 + 输出内容，200K 很快就满了。
|
||
|
||
而且还有一个更隐蔽的问题：**不该看的东西 AI 也看了。** Dev AI 不需要知道 QA AI 的工作流，Arch AI 不需要知道具体代码实现。把不属于它的信息喂给它，既浪费 token，又容易干扰判断。
|
||
|
||
---
|
||
|
||
## 第二次重构：分层信息架构
|
||
|
||
关键洞察来自一个简单问题：**人类团队怎么分工？**
|
||
|
||
一个有 3 个人的团队，不会把所有信息贴在一面墙上让每个人读完。而是每人有自己的工作台，只看和自己相关的内容。跨角色共享的信息放在公共区域。
|
||
|
||
把这个逻辑搬到 AI 协作上：
|
||
|
||
```
|
||
┌─────────────────────────────────────────┐
|
||
│ DASHBOARD.md │ ← 人类视角，30 秒了解全貌
|
||
├─────────────────────────────────────────┤
|
||
│ ROADMAP.md │ ← 人+AI 共享视野，任务看板
|
||
├────────────────┬────────────┬───────────┤
|
||
│ .ai/roles/ │ .ai/roles/ │ .ai/roles/ │
|
||
│ arch/ ← Arch │ dev/ ← Dev │ qa/ ← QA │ ← 每人自己的工作台
|
||
│ 今天干啥 │ 今天干啥 │ 今天干啥 │
|
||
│ 任务队列 │ 任务队列 │ 测试计划 │
|
||
├────────────────┴────────────┴───────────┤
|
||
│ .ai/knowledge/ │ ← 共享知识库
|
||
│ decisions.md（ADR） │
|
||
│ journal/（开发日志） │
|
||
├──────────────────────────────────────────┤
|
||
│ docs/ │ ← 项目文档
|
||
│ 01_产品需求/PRD.md │
|
||
│ 02_系统架构/ │
|
||
└──────────────────────────────────────────┘
|
||
```
|
||
|
||
四层结构，每层有明确的 token 预算：
|
||
|
||
| 层 | 读者 | 内容 | token 预算 |
|
||
|----|------|------|-----------|
|
||
| 仪表盘 | 人类 | 30 秒全貌 | < 1K |
|
||
| 路线图 | 人+AI | 任务看板 | < 3K |
|
||
| 角色工作台 | 单个 AI | 今天干啥、任务详情 | < 2K |
|
||
| 知识沉淀 | 所有 AI | ADR、经验教训 | 按需加载 |
|
||
|
||
**核心原则：每个 AI 启动时只加载自己那层的信息，不需要的永远不看。**
|
||
|
||
---
|
||
|
||
## Token 预算：把「省着用」变成设计原则
|
||
|
||
很多人觉得 token 窗口够大就不用省。但我的体验是：**省 token 不是为了省，是为了让 AI 注意力集中。**
|
||
|
||
给你一组对照实验：
|
||
|
||
```
|
||
方案 A：把所有文档塞进 context → AI 的回复质量不稳定，后面的任务比前面的差
|
||
方案 B：只给当前任务相关的文档 → AI 的回复质量和速度都明显更好
|
||
```
|
||
|
||
原因很简单：AI 的注意力也是有限的。信息越多，它在噪音中找信号的难度越大。
|
||
|
||
分层架构的本质，就是**在正确的时刻，给正确的 AI，提供正确的信息量。**
|
||
|
||
---
|
||
|
||
## 「一鸡多吃」：分享层是怎么来的
|
||
|
||
架构稳定后，我发现一个有趣的事：我做的所有决策记录、项目文档、开发日志，天然就是很好的「对外分享素材」。
|
||
|
||
于是我的产出分两条线：
|
||
- **内部线**（`.ai/`）：给 AI 看的，简短、结构化、有决策理由
|
||
- **外部线**（`docs/share/`）：给人看的，有背景、有故事、有思考过程
|
||
|
||
同一份工作，两种产出。内部文档 → 去掉敏感信息 → 加上思考过程 → 对外文章。
|
||
|
||
这就是「一鸡多吃」——开发过程自动积累内容，阶段结束时翻译为对外语言。不需要「专门抽时间写分享」。
|
||
|
||
---
|
||
|
||
*下一篇：[Phase 1 阶段复盘](phase-01/阶段复盘_基础搭建.md) — 基础搭建阶段到底做了什么*
|