Files

T

tupingr 5b428d0810 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>

2026-05-26 12:01:04 +08:00

5.5 KiB

Raw Blame History

框架设计思路：当文档的读者不是人类

传统项目结构对 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 阶段复盘 — 基础搭建阶段到底做了什么

5.5 KiB Raw Blame History Unescape Escape