00 总览与工作模型：AI 全流程开发到底在做什么¶
本章不教你任何具体命令。它要解决一个更根本的问题：你应该把 AI 放在什么位置，才能既快又不失控。
1. 先破三个误区¶
误区一：“AI 能自动完成整个项目，我只要说一句话”¶
这是最大的误解。AI 可以完成大量 执行 工作，但它不能替你承担 责任：
- 它不知道你的真实商业目标；
- 它不知道哪个功能可以砍、哪个不能砍；
- 它无法判断你的用户会不会喜欢这个交互；
- 它无法为线上事故负责；
- 它会在信息不足时“合理地编造”。
所以正确的心智模型不是“AI 自动开发”，而是：
你是一支 AI 工程团队的技术负责人。你定目标、定边界、做验收；AI 负责需求分析、设计、编码、测试、部署和取证。
误区二：“模型越强，流程越不重要”¶
模型越强，单点能力越强，但 协调成本 也越高。一个 10 万行的项目，不是“一个超级模型从头写到尾”就能交付的。你需要：
- 把大问题拆成小问题；
- 让多个 Agent 在互不干扰的边界内工作；
- 用契约保证它们能拼起来；
- 用测试和证据保证它们没有骗你。
流程不是束缚，而是让强模型的能力可以被 并行、复用和验收。
误区三：“用了编译型语言，AI 就不会幻觉了”¶
编译型语言能消灭一类错误：类型不匹配、未定义变量、签名不兼容、明显的语法错误。它消灭不了另一类错误：
- 业务规则理解错；
- 权限判断漏了一个分支；
- 并发场景下的竞态；
- API 语义和前端预期不一致；
- 数据迁移把历史数据弄丢。
编译器是测谎仪，但不是业务验收员。 编译型语言 + 单元测试 + 契约测试 + E2E + 人工验收，才是完整的质量体系。
2. AI 工程团队的工作模型¶
2.1 三种工作模式¶
| 模式 | 适用场景 | 人的参与度 | 风险 |
|---|---|---|---|
| 副驾驶（Copilot） | 改一个函数、写一个脚本、解释代码 | 高，逐步确认 | 低 |
| 结对（Pair） | 一个功能模块、一次重构 | 中，关键节点确认 | 中 |
| 团队（Team） | 一个完整产品、多个功能并行 | 低，门禁确认 | 高，需要流程 |
本教程主要讲第三种。它要求你把 AI 当成“团队”来管理，而不是“工具”来使唤。
2.2 团队角色与交接物¶
┌──────────────────────────────────────────────────────────────┐
│ 人（产品负责人） │
│ 目标 / 范围 / 优先级 / 审美 / 上线批准 / 最终验收 │
└───────────────┬──────────────────────────────────────────────┘
│ 原始想法、约束、反馈
▼
┌──────────────────────────────────────────────────────────────┐
│ 需求分析师 Agent │
│ 输出：spec.md / user-story.csv / user-story-details.md │
└───────────────┬──────────────────────────────────────────────┘
│ 已确认的需求与验收标准
▼
┌──────────────────────────────────────────────────────────────┐
│ 架构师 Agent（强模型） │
│ 输出：tech-design.md / openapi.yaml / schema.sql / ADR │
└───────────────┬──────────────────────────────────────────────┘
│ 冻结的契约、模块边界、文件所有权
▼
┌───────────────┴──────────────────────────────────────────────┐
│ 并行执行层 │
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ │
│ │ 后端 Agent │ │ 前端 Agent │ │ 测试 Agent │ ... │
│ │ US-001 │ │ US-001 │ │ E2E │ │
│ └────────────┘ └────────────┘ └────────────┘ │
│ 输出：代码 / 单测 / 集成测试 / 功能报告 │
└───────────────┬──────────────────────────────────────────────┘
│ 合并后的可运行系统
▼
┌──────────────────────────────────────────────────────────────┐
│ 质量与发布层 │
│ 代码审查 Agent → Chrome MCP E2E → Word 报告 → 部署 Agent │
└───────────────┬──────────────────────────────────────────────┘
│ 证据与报告
▼
┌──────────────────────────────────────────────────────────────┐
│ 人（最终验收） │
│ 按 Word 报告走查 / 体验判断 / 签字 / 上线批准 │
└──────────────────────────────────────────────────────────────┘
关键点：
- 每个箭头都是一份文件，不是一段聊天记录。
- 每个角色都有明确的“不做什么”，防止 AI 越权扩大范围。
- 人只在门禁处介入，但门禁必须真实有效，不能走过场。
2.3 为什么必须“产物驱动”¶
聊天记录有三个致命问题：
- 不可检索：三天后你找不到“当时为什么这么定”。
- 不可并行：多个 Agent 不能可靠地共享同一段聊天上下文。
- 不可审计：出了问题，无法回溯是谁在什么假设下做的决定。
文件则有：
- 版本历史：Git 记录每次变更。
- 可引用：
@docs/01-design/api/openapi.yaml就能让 Agent 读取准确契约。 - 可校验：CSV 可以用脚本校验，OpenAPI 可以 lint，SQL 可以迁移测试。
- 可交接：新会话、新 Agent、新人都能从文件恢复上下文。
所以本教程的一个核心原则是：
不要让 AI “记住”，要让 AI “读文件”。
3. 上下文工程：AI 团队的“工作记忆”¶
3.1 上下文为什么会坏¶
一个 Claude Code 会话的上下文窗口是有限的。随着对话变长，会出现：
- 注意力稀释：早期的重要约束被后来的闲聊淹没。
- 错误累积：AI 前面说错了一句话，后面会围绕错误前提继续推理。
- 成本上升：每轮都要重新发送大量历史 token。
- 响应变慢：上下文越长，推理越慢。
3.2 五层上下文策略¶
| 层级 | 内容 | 生命周期 | 存放位置 |
|---|---|---|---|
| L1 项目宪法 | 技术栈、目录、命令、禁止事项、完成标准 | 长期 | CLAUDE.md |
| L2 契约 | API、DB、模块边界、错误码 | 版本化 | docs/01-design/ |
| L3 当前任务 | 本次要做的用户故事、验收标准、文件所有权 | 一个会话 | Agent 任务书 |
| L4 工作记忆 | 搜索结果、代码片段、测试输出 | 临时 | 会话内，及时清理 |
| L5 证据 | 截图、manifest、报告、日志 | 长期 | docs/04-qa/ |
实践建议：
CLAUDE.md控制在 200-300 行以内。它是“宪法”，不是“百科全书”。细节放到docs/里，用链接引用。- 一个会话只做一个用户故事。做完就
/clear或开新会话。 - 用
@文件精确引用，不要让 AI “自己去找”。找文件的工作交给搜索 Agent。 - 大文件只读片段。先
rg定位，再读 50-100 行，而不是整个文件塞进去。 - 让子 Agent 做脏活。搜索、批量读取、日志分析交给子 Agent，主会话只接收结论。
- 每次重要决策后写文件。不要依赖“AI 还记得”。
3.3 一个反例¶
你：帮我把用户模块做完。
AI：（读了 40 个文件，改了 15 个，跑了 3 次测试，上下文爆了）
你：登录接口的返回格式不对。
AI：好的，我把 UserResponse 改成……（但它已经忘了前面定的错误码规范）
正确做法：
你：@docs/00-discovery/user-story-details.md 中的 US-001（用户登录）。
@docs/01-design/api/openapi.yaml 中的 POST /api/v1/auth/login。
只修改 backend/internal/auth/ 下你拥有的文件。
先写测试，再实现；完成后运行 go test -race ./internal/auth/...
最后按 @模板/feature-report.md 生成报告。
4. 模型选择：好钢用在刀刃上¶
不同任务对模型能力的要求差异很大。一个实用的分工：
| 任务 | 建议模型档位 | 原因 |
|---|---|---|
| 需求访谈、架构设计、契约设计 | 最强模型 | 需要全局推理、发现矛盾、做权衡 |
| 复杂 bug 定位、并发问题 | 最强模型 | 需要深度推理 |
| 普通功能实现 | 中等/快速模型 | 有明确契约和测试，执行导向 |
| 模板化 CRUD、格式转换 | 快速模型 | 机械性强 |
| 代码搜索、日志摘要 | 快速模型 + 子 Agent | 保护主上下文 |
| 最终代码审查 | 最强模型 | 需要发现隐蔽问题 |
如果你通过兼容 Anthropic API 的第三方模型使用 Claude Code（例如 DeepSeek、Kimi、GLM 等），可以在 ~/.claude/settings.json 中分别设置主模型和子 Agent 模型。注意：
- 架构和审查用更强的模型，不要为了省钱让弱模型冻结契约。
- 子 Agent 可以用便宜模型，但任务书要写得更具体。
- 模型能力差异会影响提示词效果，同一套提示词在不同模型上可能需要微调。
具体配置方式见 05 开发环境搭建 的“模型与 Claude Code 配置”一节。
5. 并行开发：什么时候可以并行，什么时候不能¶
5.1 可以并行的条件¶
同时满足以下条件，才可以开多个 Agent 并行：
- 契约已冻结：API、DB、错误码、鉴权方式不再变。
- 文件所有权清晰：两个 Agent 不会改同一个文件。
- 数据库迁移可串行：迁移文件按时间戳排序，避免同时改 schema。
- 依赖已声明：谁依赖谁、合并顺序是什么，写清楚。
- 测试可独立运行：每个 Agent 能在自己的 worktree 里跑测试。
5.2 不能并行的信号¶
出现以下任一情况，停下来，先串行解决：
- 两个故事都要改同一张核心表；
- 两个故事都要改同一个共享组件；
- API 契约还在讨论；
- 数据库迁移还没定；
- 认证/权限模型还没定；
- 前端还在等后端接口格式。
5.3 并行的正确姿势¶
串行阶段：
架构师冻结契约
↓
创建 N 个 git worktree + 分支
↓
并行阶段：
Agent A（US-001） Agent B（US-002） Agent C（US-003）
↓ ↓ ↓
各自单测 + 集成测试 + 功能报告
↓
串行阶段：
按依赖顺序合并 → 跑全量测试 → 修复冲突 → 更新 CSV
不要一上来就开 10 个 Agent。 先从 2-3 个开始，跑通协作流程，再逐步扩大。
6. 质量门禁：把“AI 说完成了”变成“证据说完成了”¶
6.1 完成的定义（Definition of Done）¶
一个用户故事只有同时满足以下条件，才能标记为 qa_pass：
- 代码已合并到集成分支
- 单元测试通过，覆盖率达标
- 集成测试通过（真实数据库/容器）
- E2E 流程通过（Chrome MCP）
- 每一步有截图，Word 报告可读
- 控制台无未处理错误，无 5xx
- 代码审查无 P0/P1 问题
- 功能实现报告已生成
- CSV 状态由脚本更新
- 人已走查并确认
6.2 证据链¶
用户故事（CSV）
└─► 实现报告（docs/03-dev/reports/US-xxx.md）
├─► 代码提交（git commit）
├─► 单元测试结果（CI 日志）
├─► 集成测试结果（CI 日志）
└─► E2E manifest（docs/04-qa/manifests/US-xxx.json）
├─► 步骤截图（docs/04-qa/screens/US-xxx/）
├─► 控制台日志
├─► 网络请求记录
└─► Word 报告（docs/04-qa/e2e-report-dev.docx）
原则：任何一个“完成”结论，都必须能沿着证据链追溯到原始验收标准。
6.3 门禁不是审批，是止损¶
门禁的目的不是让流程变慢，而是让你在 成本最低的时候 发现问题：
- 需求阶段发现方向错：改几行文档。
- 设计阶段发现接口不合理：改 OpenAPI。
- 编码阶段发现契约冲突：改几个文件。
- 测试阶段发现业务逻辑错：改代码 + 补测试。
- 上线后发现方向错：公关、退款、加班、事故复盘。
越往后，修复成本越高。门禁就是把“发现”尽量往前推。
7. 风险登记册：AI 全流程开发最容易翻车的地方¶
| 风险 | 表现 | 预防措施 | 兜底 |
|---|---|---|---|
| 需求幻觉 | AI 自己加了没要求的功能 | 非目标写清楚；需求评审；契约冻结 | 砍功能，回到 G1 |
| 契约漂移 | 前后端字段对不上 | OpenAPI 单一来源；生成类型 | 契约测试 |
| 并行冲突 | 两个 Agent 改同一文件 | worktree + 文件所有权清单 | 串行合并 |
| 测试造假 | AI 写“永远通过”的测试 | 审查测试；变异测试；E2E | 人工走查 |
| 上下文污染 | AI 越写越糊涂 | 一故事一会话；/clear；文件化 |
重开会话，读契约 |
| 截图刷屏 | token 爆炸，成本失控 | 文本/JS 优先；截图只留证 | 降低截图频率 |
| 生产误操作 | 测试数据污染、误删 | 测试租户；数据前缀；只读优先 | 备份 + 回滚 |
| 凭证泄露 | Syncthing 同步了长期密钥 | 用 SSO 短期凭证；加密同步 | 轮换密钥 |
| 过度并行 | 合并地狱 | 先 2-3 个 Agent | 降并行度 |
| AI 过度自信 | “已完成”但没有证据 | DoD + 证据链 | 门禁拒收 |
8. 度量：怎么知道这套方法有没有用¶
不要只盯着“AI 写了多少行代码”。建议跟踪以下指标：
| 指标 | 定义 | 目标 |
|---|---|---|
| 需求返工率 | 因需求变更导致的返工故事数 / 总故事数 | < 20% |
| 缺陷逃逸率 | 上线后发现的 P0/P1 缺陷数 / 总缺陷数 | < 5% |
| 门禁一次通过率 | 首次进入门禁即通过的比例 | > 60% |
| 故事周期时间 | 从 ready 到 qa_pass 的中位时间 |
逐月下降 |
| 人工评审时间 | 人花在走查/评审上的时间 | 逐月下降 |
| Token 成本/故事 | 总 token 成本 / 完成故事数 | 稳定或下降 |
| E2E 覆盖率 | 有 E2E 证据的 P0/P1 故事 / P0/P1 总故事 | 100% |
| 回归缺陷数 | 修复后再次出现的问题数 | 趋近 0 |
注意：AI 可能让“代码产出量”暴涨，但如果缺陷逃逸率和评审时间也暴涨，说明流程有问题，而不是 AI 不行。
9. 成熟度模型：你现在在哪一级¶
| 级别 | 特征 | 典型问题 |
|---|---|---|
| L0 手工作坊 | 让 AI 写片段，人工复制粘贴 | 上下文断裂，返工多 |
| L1 结对开发 | 一个会话做一个功能，人工测试 | 质量不稳定，难并行 |
| L2 流程化 | 有需求文档、契约、测试、报告 | 流程成本高，但可控 |
| L3 并行化 | 多 Agent + worktree + 契约冻结 | 合并冲突，协调复杂 |
| L4 流水线 | CI/CD + 自动 E2E + Word 报告 + 监控 | 需要维护自动化资产 |
| L5 自适应 | 根据风险动态调整门禁和并行度 | 需要长期数据和复盘 |
本教程的目标是把你从 L1 带到 L3/L4。不要一开始追求 L5，那需要团队级的工程文化。
10. 一周工作节奏示例¶
假设你是一个人 + AI 团队，做一个中等规模的产品：
| 时间 | 人的工作 | AI 的工作 | 产物 |
|---|---|---|---|
| 周一上午 | 讲清目标、约束、非目标 | 需求访谈、生成 spec 和故事 | G1 通过 |
| 周一下午 | 确认 UI 方向 | Figma 设计、生成 ui-spec | G2 通过 |
| 周二上午 | 确认视觉还原 | 生成 HTML/CSS 原型、Vue SPA | G3 通过 |
| 周二下午 | 评审架构 | 技术设计、OpenAPI、DB schema | G4 通过 |
| 周三 | 处理例外、评审契约 | 多 Agent 并行实现 + 单测 | 功能报告 |
| 周四 | 走查 Word 报告 | E2E、修 bug、重新取证 | G6 通过 |
| 周五上午 | 批准发布 | CI/CD 部署、冒烟测试 | G7 通过 |
| 周五下午 | 线上走查 | 线上 E2E、Word 报告、监控 | 发布验收 |
| 周末 | 复盘 | 整理反模式、更新模板 | 流程改进 |
关键：人的时间要集中在周一、周四、周五的“判断”上，而不是周三的“搬代码”上。
11. 本章小结¶
- AI 全流程开发的本质是 管理一支 AI 工程团队，而不是使用一个更快的编辑器。
- 产物驱动、契约冻结、门禁验收，是让 AI 的产出可控的三个支柱。
- 上下文是稀缺资源，文件是可靠记忆。
- 编译型语言能减少低级幻觉，但不能替代测试和人工判断。
- 并行不是目的，减少返工才是目的。
- 门禁不是官僚流程，而是成本最低的止损点。
下一章：01 需求调研 —— 把模糊想法变成可验收的用户故事。