AI 全流程开发实战教程¶

从一句需求到线上验收：用 Claude Code + WSL + Figma MCP + Chrome MCP + 编译型后端，把 AI 变成一支可管理、可验收、可复盘的工程团队。

版本：1.0
整理日期：2026-10-25
适用人群：独立开发者、小团队技术负责人、想用 AI 交付真实项目的工程师
默认环境：Windows 10/11 + WSL2（Ubuntu 24.04）；也适用于原生 Linux / macOS
配套材料：模板目录｜脚本目录

0. 这套教程解决什么问题¶

很多人的 AI 编程停留在“让 AI 写一个函数”“让 AI 改一个 bug”。这当然有用，但它离“交付一个能上线、能验收、能维护的产品”还有很长的距离。

真正困难的地方从来不是“生成代码”，而是：

需求不清：AI 会非常勤奋地把你没想清楚的地方“编”出来。
设计漂移：UI、前端、后端、数据库各写各的，最后拼不起来。
并行混乱：多个 Agent 同时改代码，冲突、覆盖、互相踩踏。
质量不可证：AI 说“已完成”，但你没有证据判断它是否真的完成。
上线失控：本地能跑，线上不行；或者线上验证靠人肉点点点。
上下文爆炸：一个会话越聊越长，AI 越来越糊涂，token 越烧越多。

这套教程的核心，不是教你“更会写提示词”，而是教你建立一套 以产物为中心、以门禁为节奏、以证据为验收 的 AI 开发流水线。AI 负责高吞吐的执行，人负责目标、边界和最终判断。

1. 六条核心主张¶

主张一：AI 是工程团队，不是许愿池¶

把 AI 拆成明确的角色：需求分析师、架构师、UI 工程师、前端工程师、后端工程师、测试工程师、发布工程师、代码审查员。每个角色有输入、输出、权限和完成标准。角色越清晰，AI 的发挥越稳定。

主张二：先冻结契约，再并行开发¶

多 Agent 并行的前提不是“多开几个窗口”，而是 API 契约、数据库模型、模块边界、文件所有权 先冻结。契约不冻结，并行就是制造冲突。

主张三：用编译器和测试当“测谎仪”¶

后端选 Go / Java / Rust 这类编译型语言，能利用编译器、类型检查、lint、单元测试快速证伪 AI 的语法和类型错误。但要记住：编译通过不等于业务正确。编译型语言解决的是“低级幻觉”，业务幻觉仍然要靠验收标准、契约测试、端到端测试和人工评审来解决。

主张四：上下文是稀缺资源¶

一个功能一个会话、一个 Agent 一个边界、一个大文件只读必要片段。用 CLAUDE.md 固化长期约定，用子 Agent 做搜索和隔离，用 /clear 和摘要控制上下文长度。上下文越干净，AI 越聪明，token 越省。

主张五：Chrome MCP 用“文本 + JS”思考，用“截图”留证¶

让 AI 理解页面时，优先用 CDP 的可访问性树、DOM 文本和 chrome_javascript 返回值；截图只作为 给人看的证据，保存到磁盘并嵌入 Word，不必每一步都把图片读回模型上下文。这样既准确又省 token。

主张六：人只做三件事——定目标、过门禁、做最终体验判断¶

需求范围、UI 审美、上线批准，必须由人拍板。其余重复劳动尽量交给 AI。人的时间应该花在“判断”上，而不是“搬运”上。

2. 全流程全景图¶

图较宽，可左右滚动查看完整流程；下方同时提供纯文本版本。

%%{init: {"flowchart": {"useMaxWidth": false}}}%%
flowchart LR
    A[原始想法] --> B[1 需求调研]
    B --> B1{G1 范围门禁}
    B1 --> C[2 UI 设计]
    C --> C1{G2 设计门禁}
    C1 --> D[3 前端原型]
    D --> D1{G3 视觉门禁}
    D1 --> E[4 后端选型]
    E --> F[5 开发环境]
    F --> G[6 技术设计]
    G --> G1{G4 契约冻结}
    G1 --> H[7 多 Agent 编码]
    H --> H1{G5 代码门禁}
    H1 --> I[8 质量保证]
    I --> I1{G6 验收门禁}
    I1 --> J[9 部署]
    J --> J1{G7 发布门禁}
    J1 --> K[10 线上验证]
    K --> L[运营与复盘]
    L --> B

用纯文本表示：

原始想法
  │
  ▼
① 需求调研 ──► G1 范围门禁（人确认：做什么、不做什么）
  │
  ▼
② UI 设计 ───► G2 设计门禁（人确认：好不好看、好不好用）
  │
  ▼
③ 前端原型 ──► G3 视觉门禁（人确认：像素级还原）
  │
  ▼
④ 后端选型
  │
  ▼
⑤ 开发环境
  │
  ▼
⑥ 技术设计 ──► G4 契约冻结（API / DB / 模块边界 / 文件所有权）
  │
  ▼
⑦ 多 Agent 编码 ──► G5 代码门禁（单测 + 集成测试 + 代码审查）
  │
  ▼
⑧ 质量保证 ────► G6 验收门禁（Word 报告 + 人工走查）
  │
  ▼
⑨ 部署 ───────► G7 发布门禁（人工批准 + 冒烟测试）
  │
  ▼
⑩ 线上验证 ────► 发布验收（线上 Word 报告 + 监控）
  │
  ▼
运营与复盘 ──► 回到 ①

3. 十个阶段、七个门禁¶

阶段	章节	核心产物	门禁	谁拍板
0 准备	00 总览与工作模型	工具链、仓库、角色分工	—	人
1 需求调研	01 需求调研	`spec.md`、`user-story.csv`、`user-story-details.md`、排期	G1 范围	人
2 UI 设计	02 UI 设计与设计稿转代码	Figma 设计稿、`ui-spec.md`、设计 token	G2 设计	人
3 前端	03 前端开发	HTML/CSS 原型、Vue SPA	G3 视觉	人
4 后端选型	04 后端技术选型	ADR、技术栈清单	—	人 + 架构 Agent
5 开发环境	05 开发环境搭建	WSL、Chrome、MCP、Docker、Git	—	人
6 技术设计	06 技术设计	`tech-design.md`、OpenAPI、DB schema、实现细节、`CLAUDE.md`	G4 契约	人 + 架构 Agent
7 AI 编码	07 AI 编码与多 Agent 并行开发	代码、单测、集成测试、功能报告、CSV 状态	G5 代码	人 + 审查 Agent
8 质量保证	08 质量保证与Word验收报告	E2E 截图、`e2e-report-dev.docx`、缺陷清单	G6 验收	人
9 部署	09 部署与发布	CI/CD 流水线、部署记录、冒烟结果	G7 发布	人
10 线上验证	10 线上验证与运营	`e2e-report-prod.docx`、监控基线、复盘	发布验收	人

门禁不是形式主义。每个门禁都对应一个明确的问题：“如果现在停下来，损失最小吗？”越早发现方向错误，返工成本越低。

4. 角色分工：人 + AI 工程团队¶

角色	由谁担任	主要职责	不该做什么
产品负责人	人	定目标、定范围、定优先级、过 G1/G2/G6/G7	不写大段代码
需求分析师	AI	访谈提问、拆用户故事、写验收标准、查矛盾	不替人做范围决策
架构师	AI（强模型）	技术选型、架构图、API/DB 契约、风险清单	不擅自改需求
UI 工程师	AI + Figma MCP	生成/修改设计稿、设计 token、设计走查	不决定品牌方向
前端工程师	AI	HTML/CSS 原型、Vue SPA、接口联调、前端测试	不擅自改 API 契约
后端工程师	AI（按功能分 Agent）	领域逻辑、API、数据库、单元/集成测试	不跨文件所有权乱改
测试工程师	AI + Chrome MCP	E2E 流程、截图取证、Word 报告、缺陷复现	不在生产造脏数据
发布工程师	AI + CI/CD + AWS CLI	构建、部署、冒烟、回滚	不跳过人工批准发生产
代码审查员	AI + 人	审查安全、边界、测试、契约一致性	不替代最终验收

5. 产物驱动：所有工作都落成文件¶

AI 开发最大的风险之一是“聊完就忘”。解决办法是：每一个阶段的结论都必须落成仓库里的文件，并且后续 Agent 只从这些文件获取事实，而不是从聊天记录里猜。

推荐的仓库结构：

project/
├── CLAUDE.md                        # 项目级 AI 工作约定（每次会话自动加载）
├── .claude/
│   ├── agents/                      # 自定义子 Agent 定义
│   ├── skills/                      # 项目内技能
│   └── settings.json                # 权限、环境变量、hooks
├── docs/
│   ├── 00-discovery/                # 需求阶段
│   │   ├── raw-notes.md             # 原始访谈/想法
│   │   ├── spec.md                  # 功能规格说明书
│   │   ├── user-story.csv           # 用户故事总表（唯一状态源）
│   │   ├── user-story-details.md    # 用户故事实现细节
│   │   └── schedule.md              # 排期与里程碑
│   ├── 01-design/                   # 技术设计阶段
│   │   ├── tech-design.md           # 技术设计总文档
│   │   ├── adr/                     # 架构决策记录
│   │   ├── api/openapi.yaml         # API 契约
│   │   └── db/schema.sql            # 数据库模型
│   ├── 02-ui/                       # UI 阶段
│   │   ├── ui-spec.md               # 页面/组件/状态/交互说明
│   │   └── screens/                 # 设计稿导出图
│   ├── 03-dev/                      # 开发阶段
│   │   └── reports/                 # 每个功能一份实现报告
│   │       ├── US-001-用户登录.md
│   │       └── US-004-创建任务.md
│   └── 04-qa/                       # 测试阶段
│       ├── manifests/               # E2E 步骤清单 JSON
│       ├── screens/                 # 每一步的截图
│       ├── e2e-report-dev.docx      # 开发环境验收报告
│       └── e2e-report-prod.docx     # 生产环境验收报告
├── backend/
├── frontend/
├── infra/
├── scripts/
│   ├── update_story_status.py       # 统一更新 CSV，避免手改坏格式
│   ├── build_test_report.py         # 截图 + manifest → Word
│   └── start-chrome-debug.sh        # 启动可调试 Chrome
└── Makefile                         # 一键 lint/test/e2e/report

为什么 CSV 和 MD 要分开？

CSV：适合人快速扫状态、排序、筛选、导入表格；也是脚本更新状态的机器接口。
MD：适合写业务规则、边界条件、验收用例等长文本；Agent 读起来上下文更自然。

两者用 story_id 关联，CSV 里再记录实现报告路径和部署状态，形成可追溯链条。

6. 状态机：用户故事的一生¶

CSV 的 status 字段建议使用固定枚举，避免“做完了”“已完成”“Done”混用：

draft
  └─► ready
        └─► designing
              └─► dev
                    └─► unit_done
                          └─► integ_done
                                └─► qa_pass
                                      └─► deployed_dev
                                            └─► deployed_prod
                                                  └─► verified_prod

异常状态：

blocked：被依赖、契约或环境阻塞。
failed：测试失败或验收不通过，需要回到 dev。
cancelled：范围调整，人工确认后关闭。

规则：状态只能由脚本更新，不能由 Agent 手改 CSV。 手改 CSV 极易引发引号、逗号、编码问题，也会让状态和报告不一致。

7. 快速开始：30 分钟跑通最小闭环¶

如果你不想一次读完，先按下面这条最小路径跑一遍。它会让你对整套方法有体感，再回头补细节。

第 1 步：准备环境（10 分钟）¶

# 在 Windows PowerShell（管理员）中
wsl --install -d Ubuntu-24.04
wsl --update

# 进入 WSL 后
sudo apt update && sudo apt install -y git curl jq ripgrep fd-find tree python3 python3-venv
mkdir -p ~/projects && cd ~/projects

详细步骤见 05 开发环境搭建。

第 2 步：创建项目骨架（5 分钟）¶

mkdir my-ai-project && cd my-ai-project
git init
mkdir -p docs/{00-discovery,01-design,02-ui,03-dev/reports,04-qa/{manifests,screens}} \
         backend frontend infra scripts
cp /path/to/AI全流程开发教程/模板/spec.md docs/00-discovery/spec.md
cp /path/to/AI全流程开发教程/模板/user-story.csv docs/00-discovery/user-story.csv
cp /path/to/AI全流程开发教程/模板/user-story-details.md docs/00-discovery/user-story-details.md
cp /path/to/AI全流程开发教程/模板/CLAUDE.md ./CLAUDE.md

第 3 步：让 AI 做需求分析（5 分钟）¶

在项目根目录启动 Claude Code：

claude --dangerously-skip-permissions

输入：

你是资深产品经理兼需求分析师。请阅读 @docs/00-discovery/raw-notes.md。
先不要写方案。请一次性提出最多 12 个澄清问题，覆盖：
目标用户、核心场景、非目标、数据实体、权限、集成、合规、成功指标、上线约束。
每个问题给出 2-3 个可选答案，标出你的推荐项。

拿到回答后，再让它生成 spec.md 和用户故事。模板与完整提示词见 01 需求调研和附录 B。

第 4 步：跑一个功能的最小闭环（10 分钟）¶

选一个最小的用户故事（例如“用户登录”），让 AI：

写技术设计和接口契约；
写后端接口 + 单元测试；
写前端页面；
用 Chrome MCP 做一次端到端验证并截图；
生成 Word 报告；
更新 CSV 状态。

完整提示词见 07 AI 编码与多 Agent 并行开发和 08 质量保证与 Word 验收报告。

8. 章节导航¶

主线¶

00 总览与工作模型 —— 先建立正确的心智模型
01 需求调研 —— 把模糊想法变成可验收的故事
02 UI 设计与设计稿转代码 —— Figma MCP 与设计 token
03 前端开发 —— HTML/CSS 原型到 Vue SPA
04 后端技术选型 —— 为什么选编译型语言
05 开发环境搭建 —— WSL、Chrome、MCP、Docker
06 技术设计 —— 架构、契约、数据库、实现细节
07 AI 编码与多 Agent 并行开发 —— 分工、隔离、测试、报告
08 质量保证与 Word 验收报告 —— Chrome MCP E2E 与人工走查
09 部署与发布 —— CI/CD、AWS CLI、Syncthing
10 线上验证与运营 —— 生产验证、监控、复盘

实战与附录¶

Claude Code 使用指南 —— 快捷键、上下文、项目组织、与 VS Code 协作
11 完整实战：从 0 到 1 做一个任务系统
12 常见问题与反模式
附录 A：Chrome MCP / CDP 实战手册
附录 B：提示词与模板合集

可直接复用的材料¶

9. 七个门禁的检查清单（打印出来贴墙上）¶

G1 范围门禁¶

目标用户、核心场景、非目标写清楚
每个功能都有可测试的验收标准
P0/P1/P2 优先级明确
数据实体和权限模型没有明显漏洞
排期包含人工评审和缓冲时间
人明确说“这个范围我接受”

G2 设计门禁¶

所有页面有设计稿或明确的原型
组件、颜色、字体、间距 token 已固化
空状态、加载态、错误态、无权限态都有设计
移动端/窄屏适配规则明确
人明确说“这个视觉方向我接受”

G3 视觉门禁¶

前端原型与设计稿关键页面一致
交互可点通，不是静态图片
控制台无报错
人明确说“这个还原度我接受”

G4 契约门禁¶

OpenAPI 已生成并通过 lint
数据库 schema 已评审，索引和约束合理
模块边界和文件所有权明确
错误码、分页、鉴权、幂等策略统一
CLAUDE.md 已更新，包含构建/测试/运行命令
人明确说“契约冻结，可以并行开发”

G5 代码门禁¶

每个故事有单元测试，覆盖率达标
集成测试通过（真实数据库/容器）
go test -race ./... / mvn verify / cargo test 通过
代码审查无 P0/P1 问题
每个故事有独立实现报告
CSV 状态由脚本更新，和报告一致

G6 验收门禁¶

所有 P0/P1 故事的 E2E 通过
每一步有截图，Word 报告可读
控制台无未处理错误，无 5xx
缺陷已修复并有回归测试
人按 Word 报告走查一遍并签字

G7 发布门禁¶

CI 全绿，镜像/构建产物已签名或可追溯
数据库迁移可回滚，已备份
发布窗口、负责人、回滚方案明确
人工批准生产发布
发布后冒烟测试通过

10. 时间与成本预期¶

AI 不是魔法。一个功能从需求到上线，仍然需要人的判断和验收。下面是一个粗略的经验值（单人 + AI，中等复杂度 CRUD 产品）：

阶段	传统方式	AI 全流程（熟练后）	主要瓶颈
需求与故事	2-5 天	0.5-1 天	人的决策
UI 设计	3-10 天	0.5-2 天	审美与评审
前端原型	3-10 天	0.5-2 天	视觉验收
技术设计	2-5 天	0.5-1 天	契约评审
后端编码	5-20 天	1-5 天	测试与联调
QA	3-10 天	0.5-2 天	人工走查
部署	1-3 天	0.5-1 天	环境与权限
线上验证	1-3 天	0.5-1 天	生产约束

结论：AI 把“执行时间”压缩得很厉害，但“判断时间”不会消失。真正的提效来自 减少返工，而不是单纯提高打字速度。

11. 使用建议¶

第一遍通读：先读 00、01、06、07、08 这五章，建立主骨架。
第二遍照做：拿一个小项目（3-5 个用户故事）完整走一遍，不要一上来就做复杂系统。
第三遍固化：把模板、脚本、检查清单改成你团队自己的版本，沉淀到 CLAUDE.md 和 .claude/agents/。
不要跳过门禁：门禁看起来慢，实际上是防止你花三天做出一个方向错误的东西。
保留证据：每次 E2E 都留下 manifest、截图、Word 报告和请求 ID。上线出问题时，这些证据能救命。

12. 事实与版本说明¶

Claude Code、Figma MCP、Chrome MCP、各云厂商 CLI 的接口和参数会随版本变化。本教程给出的是 可操作的模式和示例，具体命令请以你本地 claude mcp list、--help 和官方文档为准。
文中以 chrome-control 这组 MCP 工具名为例（chrome_navigate、chrome_read_page、chrome_javascript、chrome_screenshot 等）。如果你用的是 chrome-devtools-mcp、Playwright MCP 或 Browser MCP，工具名不同，但“文本优先、截图留证”的方法不变。
文中涉及 AWS、Figma、Syncthing 的操作，请在测试账号/测试环境中先验证，生产操作务必遵循最小权限和变更审批。
本教程不鼓励绕过任何平台的安全机制。Chrome 远程调试、AWS 凭证同步、生产测试账号等能力，仅用于你拥有授权的系统和数据。

13. 一页纸总结¶

需求 → 故事 + 验收标准 → 设计 → 契约冻结 → 多 Agent 并行实现
   → 单元/集成测试 → Chrome MCP E2E + 截图 → Word 报告 → 人工走查
   → CI/CD 部署 → 线上 E2E + Word 报告 → 监控与复盘

三条铁律：
1. 没有验收标准的需求，不进入开发。
2. 没有冻结契约的功能，不并行开发。
3. 没有证据的“完成”，不算完成。

下一步：打开 00 总览与工作模型，先建立正确的心智模型；或者直接跳到 01 需求调研开始你的第一个项目。