# 团队级 AI Coding 简明手册 - 逐页详细研究

> 原文：系统设计研讨会分享 PPT v0.2（2026年6月18日）
> 研究日期：2026-06-20
> 研究目标：逐页深入分析，补充背景知识、工具推荐、实践建议

---

## 第1页：封面

### 原文内容
- 标题：团队级 AI Coding 简明手册 v0.2
- 日期：2026年6月18日
- 来源：系统设计研讨会分享
- 版权声明：版权归分享人所有

### 研究要点
- 这是 v0.2 版本，说明经过了迭代完善
- "团队级"强调这不是个人技巧，而是组织层面的工程实践
- "简明手册"定位：实用导向，非学术理论

---

## 第2页：AI 编程思想发展过程

### 原文内容
AI 编程经历5个阶段演进：

| 阶段 | 特征 | 自动化程度 |
|------|------|------------|
| **原始阶段** | 基于本能，手动复制代码或通过问答交互 | 半自动，有人值守 |
| **Rule 约束** | 经验规则显化，如 RIPER-5 定义工作模式 | 半自动，持续对话 |
| **规格驱动** | 需求结构化表达，如 OpenSpec 框架 | 过渡阶段 |
| **Loop Engineering** | 可反馈闭环，AI 根据验收规则自动循环 | 接近全自动 |
| **Harness 驾驭工程** | 纳入工程治理体系，提供约束+外部接口 | 全自动，Plan 后无人值守 |

### 深入解读

**1. 原始阶段**
- **现状**：大多数开发者仍在这个阶段
- **典型场景**：复制 ChatGPT 生成的代码到 IDE，手动调整
- **问题**：上下文断裂，每次对话都要重新解释背景
- **工具**：ChatGPT 网页版、早期 Copilot

**2. Rule 约束阶段**
- **RIPER-5 模式**（Research-Investigate-Plan-Execute-Review）：
  - 由 AI 编程社区提出的结构化工作流
  - 将复杂任务分解为5个明确阶段
  - 每个阶段有不同的提示词策略
- **其他 Rule 框架**：
  - Cursor Rules：在 `.cursor/rules` 定义项目规范
  - Claude Code 的 `CLAUDE.md`：项目级指令
  - OpenCode 的 `.opencode/config.json`

**3. 规格驱动阶段**
- **OpenSpec 框架**：
  - 将需求写成结构化的 Spec 文件
  - AI 读取 Spec 生成代码，文件进文件出
  - Spec 可以作为版本控制的产物
- **优势**：需求可追溯，AI 行为可预测

**4. Loop Engineering**
- **核心理念**：AI 不是执行一次就结束，而是进入循环
- **循环机制**：
  - 定义验收标准（测试用例）
  - AI 执行 → 运行测试 → 失败则修复 → 再次运行
  - 直到所有测试通过才退出循环
- **代表工具**：Claude Code 的 `/loop` 命令

**5. Harness 驾驭工程**
- **概念来源**：OpenAI、Anthropic 等公司提出的工程理念
- **Harness（驾驭工具）**：
  - 为 AI 提供约束体系（Rules、Specs）
  - 为 AI 提供外部接口（MCP、Skills、CLI）
  - 让 AI 在受控环境中自主工作
- **关键特征**：
  - Plan 阶段人机协作
  - 执行阶段无人值守
  - 可审计、可回溯

### 实践建议
- **评估你所在团队的位置**：大多数团队在阶段1-2之间
- **渐进式升级**：不要跳级，先建立 Rule，再引入 Spec
- **关键指标**：AI 代码采纳率、人均代码产出、缺陷率

### 相关资源
- [Harness Engineering - OpenAI](https://openai.com/index/harness-engineering/)
- [Harness Engineering - Martin Fowler](https://martinfowler.com/articles/harness-engineering.html)
- [Anthropic: Harness Design for Long-running Apps](https://www.anthropic.com/engineering/harness-design-long-running-apps)

---

## 第3页：四大核心问题

### 原文内容
团队级 AI Coding 面临4个核心问题：

1. **需求衔接**：如何用 AI 整理需求？
2. **开发实现**：如何获得高质量的代码？
3. **测试验收**：如何根据规格自动化测试？
4. **Agent as Code**：如何组织协作文件，构建 AI 友好环境？

### 深入解读

**问题1：需求衔接**
- **痛点**：AI 无法理解模糊需求，需要结构化输入
- **关键问题**：
  - 格式：Markdown vs YAML vs JSON
  - 组织：按功能模块 vs 按用户故事
  - 原型图传递：Figma 链接 vs HTML 原型
  - 模版设计：新建需求 vs 变更需求
- **解决方案**：使用 `docs/features/` 目录管理需求规格

**问题2：开发实现**
- **痛点**：AI 生成的代码质量不稳定，缺乏上下文
- **关键问题**：
  - 上下文管理：如何让 AI 理解项目结构
  - 外部工具：如何调用数据库、API、文件系统
  - 代码一致性：如何保证风格统一
  - 多任务并发：如何同时开发多个功能
  - 调试能力：如何让 AI 自主排查问题
- **解决方案**：
  - AGENTS.md 定义项目约束
  - MCP 协议接入外部工具
  - 打样工程提供代码模版

**问题3：测试验收**
- **痛点**：AI 生成的代码缺乏测试，难以验证
- **关键问题**：
  - 测试策略：单元测试 vs 集成测试 vs E2E 测试
  - 浏览器操作：如何让 AI 操作浏览器进行 E2E 测试
  - 测试用例管理：如何组织、版本控制
- **解决方案**：
  - TDD 驱动：先写测试再写代码
  - Playwright MCP：AI 操作浏览器
  - 测试用例生成：Browser Use 探索 → Playwright 固化

**问题4：Agent as Code**
- **痛点**：AI 协作文件散乱，缺乏组织
- **关键问题**：
  - 文件结构：如何组织 docs、skills、mcp 等目录
  - 工具支持：如何让 Claude、Cursor、OpenCode 都识别
  - 版本控制：如何将 AI 配置纳入 Git 管理
- **解决方案**：
  - AGENTS.md 作为宪法级文件
  - 软链接到各工具的配置文件
  - 统一目录结构：`docs/`, `skills/`, `mcp/`

### 实践建议
- **优先级排序**：先解决问题4（Agent as Code），建立基础
- **逐步引入**：需求衔接 → 开发实现 → 测试验收
- **度量指标**：AI 代码采纳率、测试覆盖率、缺陷逃逸率

---

## 第4页：AI 赋能软件开发实现地图

### 原文内容
完整的软件开发生命周期中，人与 AI 的分工：

```
需求分析 → 需求文档/原型图 → 技术方案 → 代码框架+打样
   ↓              ↓              ↓              ↓
  人+AI          人+AI          人+AI          人+AI
   ↓              ↓              ↓              ↓
AI代码编写 → 单元/API测试 → E2E测试 → Code Review → 提测部署
   ↓              ↓            ↓           ↓           ↓
  机             机+人         机+人        机+人        机+人
```

**核心 Loop**：研发自测阶段（AI 自治运行）
**全流程超级 Loop**：从需求到部署（人机协作）

### 深入解读

**阶段1：需求分析（人+AI）**
- **人的角色**：用户访谈、竞品分析、业务理解
- **AI 的角色**：整理访谈记录、生成用户故事、绘制流程图
- **工具推荐**：
  - ChatGPT/Claude：整理访谈笔记
  - Miro AI：自动生成流程图
  - Whimsical AI：生成用户旅程图

**阶段2：需求文档+原型图（人+AI）**
- **人的角色**：定义业务规则、审核原型
- **AI 的角色**：生成需求文档草稿、生成 HTML 原型
- **工具推荐**：
  - Cursor/Claude Code：生成 Markdown 需求文档
  - v0.dev：生成 React 原型
  - Galileo AI：生成 UI 设计稿

**阶段3：技术方案（人+AI）**
- **人的角色**：架构决策、技术选型
- **AI 的角色**：生成技术规格文档、绘制架构图
- **工具推荐**：
  - PlantUML + AI：生成领域模型、时序图
  - Claude Code：生成 API 设计文档

**阶段4：代码框架+打样（人+AI）**
- **人的角色**：定义目录结构、编写核心接口
- **AI 的角色**：生成 CRUD 代码、填充模版
- **工具推荐**：
  - Claude Code + 打样工程：生成符合项目规范的代码
  - Cursor Composer：批量生成代码

**阶段5：AI 代码编写（机）**
- **AI 的角色**：根据 Spec 自动生成代码
- **人的角色**：审核关键逻辑
- **工具推荐**：
  - Claude Code Loop 模式：自动循环直到测试通过
  - OpenCode：根据 OpenSpec 生成代码

**阶段6：单元/API 测试（机+人）**
- **AI 的角色**：生成测试代码、运行测试
- **人的角色**：审核测试用例、补充边界条件
- **工具推荐**：
  - Jest + AI：生成单元测试
  - Karate：生成 API 测试

**阶段7：E2E 测试（机+人）**
- **AI 的角色**：操作浏览器、生成测试脚本
- **人的角色**：定义关键路径、审核测试
- **工具推荐**：
  - Playwright MCP：AI 操作浏览器
  - Browser Use：探索式测试生成

**阶段8：Code Review（机+人）**
- **AI 的角色**：自动审查代码、发现问题
- **人的角色**：审核 AI 的审查结果
- **工具推荐**：
  - GitHub Copilot Code Review
  - Claude Code：PR Review
  - CodeRabbit：AI 代码审查

**阶段9：提测部署（机+人）**
- **AI 的角色**：生成部署脚本、执行部署
- **人的角色**：审核部署配置、处理异常
- **工具推荐**：
  - GitHub Actions + AI：自动生成 CI/CD
  - Vercel/Netlify：一键部署

### 实践建议
- **从核心 Loop 开始**：先在研发自测阶段引入 AI
- **逐步扩展到超级 Loop**：覆盖需求、测试、部署
- **关键指标**：AI 参与率、自动化程度、交付周期

---

## 第5页：AI 赋能软件开发工具体系

### 原文内容
展示了各阶段使用的工具和产出物：

| 阶段 | 工具 | 产出 |
|------|------|------|
| 原型图 | Stitch/Figma/HTML | Design.md |
| 需求规格 | AI IDE + 模版 | Markdown |
| 技术规格 | AI IDE + 模版 | Markdown |
| 代码编写 | AI IDE + 规范 | TS/Java |
| 测试规格 | AI IDE + 模版 | Markdown |
| E2E 测试 | Playwright MCP | TS 代码 |
| Bug 修复 | AI IDE + 模版 | 代码修复 |
| 部署 | AI IDE + Yaml | 环境部署 |

### 深入解读

**工具链核心：AI IDE**
- **定义**：集成 AI 能力的开发环境
- **代表工具**：
  - **Cursor**：基于 VS Code，AI 优先设计
  - **Claude Code**：命令行 AI 编程工具
  - **OpenCode**：开源的 AI 编程终端
  - **Kiro**：AWS 推出的 AI IDE
  - **Trae**：字节跳动推出的 AI IDE

**模版体系**
- **需求规格模版**：定义需求文档结构
- **技术规格模版**：定义技术设计文档结构
- **测试规格模版**：定义测试用例结构
- **代码模版**：定义代码风格、目录结构

**关键工具详解**

1. **Design.md**
   - 作用：约束 AI 生成的前端风格
   - 内容：颜色、字体、间距、组件库
   - 来源：从设计稿提炼或从现有代码反推

2. **Playwright MCP**
   - 作用：让 AI 操作浏览器
   - 场景：E2E 测试、UI 调试
   - 优势：标准化接口，支持 Accessibility Tree

3. **MCP（Model Context Protocol）**
   - 作用：AI 与外部系统通信的标准协议
   - 场景：数据库、API、文件系统接入
   - 优势：标准化、双向通信、即插即用

### 实践建议
- **建立模版库**：将常用的文档结构模版化
- **统一工具链**：团队使用相同的 AI IDE
- **维护 Design.md**：确保 AI 生成的 UI 风格一致

---

## 第6页：分隔页（01 需求衔接）

### 原文内容
章节分隔页，标志进入"需求衔接"部分

### 研究要点
- 这是第4个核心问题的展开
- 需求衔接是整个开发流程的起点
- 良好的需求衔接能大幅提升 AI 代码质量

---

## 第7页：需求规格编写

### 原文内容
**AI 能理解的需求格式**：Markdown/Excel 表格

**关键要素**：
1. **模块切分**（增量/存量）
2. **字段清单**
3. **原型链接**
4. **业务规则**

**编写原则**：
- 先写业务背景，再切模块
- 一个模块 = 一个文档
- 分解为增量需求和存量需求：
  - **增量需求**：全新功能，需新建模块
  - **存量修改**：对已有功能做变更
- Tips：增量建模块，存量标改动

**字段清单示例**：
```markdown
| 字段名    | 类型    | 必填 | 默认值 | 描述         |
|-----------|---------|------|--------|--------------|
| username  | string  | 是   | —      | 登录用户名   |
| email     | string  | 是   | —      | 电子邮箱     |
| role      | enum    | 否   | user   | 用户角色     |
| status    | boolean | 否   | true   | 是否启用     |
```

**字段定义要求**：
- 定义完整字段
- 标注校验规则
- 标注 UI 展示
- 标注数据来源

**原型图传递**：
- Figma：选中 Frame → Share → Copy link
- Stitch：选中设计稿 → 获取分享链接
- HTML 版本：用 HTML/CSS 做可交互原型，提交到代码仓库

**业务规则示例**：
```markdown
R1 用户名唯一不可重复
R2 邮箱格式正则校验
R3 密码 ≥ 8 位含大小写
R4 删除需二次确认
R5 超时自动登出
R6 管理员不可降级
```

**编写原则**：
- 条目化 + 正交分解
- 每条规则独立可测

**重要 Tip**：BA 也应该工作在代码仓库中，让 AI 基于当前系统事实构建新需求

### 深入解读

**为什么用 Markdown？**
- **版本控制友好**：可以纳入 Git 管理
- **AI 友好**：LLM 对 Markdown 理解能力强
- **可读性好**：人和 AI 都能轻松阅读
- **工具支持**：所有 AI IDE 都支持

**为什么区分增量/存量？**
- **增量需求**：AI 从零生成，需要完整上下文
- **存量修改**：AI 需要理解现有代码，才能安全修改
- **影响 AI 策略**：增量可以用生成式 AI，存量需要理解现有代码

**字段清单的价值**
- **明确数据模型**：AI 可以根据字段生成数据库表、API 接口
- **减少歧义**：类型、必填、默认值都明确定义
- **自动生成代码**：可以根据字段清单生成前端表单、后端 DTO

**业务规则条目化**
- **独立可测**：每条规则可以单独写测试用例
- **正交分解**：规则之间不重叠、不冲突
- **可追溯**：每条规则可以追溯到代码实现

**BA 在代码仓库中工作**
- **优势**：
  - BA 可以看到现有需求、代码结构
  - AI 可以基于现有需求生成新需求
  - 需求变更可以追溯历史
- **实践**：
  - BA 使用 Git 管理需求文档
  - 需求变更通过 PR 审核
  - AI 参与需求文档的生成和审核

### 实践建议
- **建立需求模版**：统一需求文档结构
- **使用字段清单**：明确数据模型
- **业务规则条目化**：方便测试和追溯
- **BA 使用 Git**：将需求管理纳入版本控制

### 工具推荐
- **需求管理**：Git + Markdown
- **原型设计**：Figma、Stitch、HTML
- **字段清单**：Excel、Markdown 表格
- **业务规则**：Markdown 列表

---

## 第8页：原型图设计

### 原文内容
**原型图设计的3种方式**：

**1. AI 设计软件输出**
- 在设计工具中完成原型，通过 URL 链接嵌入需求文档
- 标注映射：在需求中注明对应模块和页面
- **Figma**：选中 Frame → Share → Copy link
- **Stitch**：选中设计稿 → 获取分享链接

**2. HTML + CSS 输出**
- 用 HTML/CSS 做可交互原型，提交到代码仓库
- **优势**：
  - 真实代码：直接使用项目组件库拼装
  - 可交互：点击、跳转、表单输入均可演示
  - 版本管理：随代码仓库一起管理和 Review

**3. Design.md 生成统一的视觉风格**
- **Design.md**：用 Markdown 约束 AI 生成的前端风格，确保输出与项目组件库一致
- **两种产生方式**：
  - 从设计稿提炼规则
  - 从现有代码反推样式

**Design.md 示例**：
```markdown
# Design System

## Colors
- primary: #1a1a1a
- background: #ffffff
- text: #333333

## Typography
- font: -apple-system, sans-serif
- h1: 1.5rem / 700
- body: 0.875rem / 400

## Spacing
- unit: 8px (base)
```

**参考资源**：https://getdesign.md

### 深入解读

**为什么需要原型图？**
- **减少歧义**：文字描述容易产生误解，原型图直观展示
- **AI 理解**：AI 可以通过原型图理解 UI 结构
- **用户确认**：用户可以提前看到效果，减少返工

**Figma vs Stitch vs HTML**

| 维度 | Figma | Stitch | HTML |
|------|-------|--------|------|
| **学习成本** | 中 | 低 | 高 |
| **AI 友好度** | 中 | 高 | 极高 |
| **版本控制** | 差 | 中 | 极好 |
| **交互能力** | 中 | 中 | 极强 |
| **协作能力** | 极强 | 强 | 中 |

**Figma**
- **优势**：设计师常用，生态丰富
- **劣势**：AI 无法直接读取 Figma 文件，需要通过链接
- **适用场景**：专业设计师参与的项目

**Stitch**
- **优势**：AI 友好，可以直接生成设计稿
- **劣势**：生态较小
- **适用场景**：AI 优先的项目

**HTML**
- **优势**：AI 可以直接生成，版本控制友好
- **劣势**：需要前端开发能力
- **适用场景**：技术团队主导的项目

**Design.md 的价值**
- **统一风格**：确保 AI 生成的 UI 风格一致
- **可维护**：Markdown 格式，易于修改和版本控制
- **可复用**：可以在多个项目中复用

**Design.md 的内容**
- **Colors**：主色、背景色、文字色
- **Typography**：字体、字号、字重
- **Spacing**：间距、边距
- **Components**：按钮、表单、卡片等组件样式
- **Layout**：布局规则

### 实践建议
- **选择适合的原型工具**：根据团队能力选择 Figma/Stitch/HTML
- **维护 Design.md**：确保 AI 生成的 UI 风格一致
- **原型与代码同步**：原型变更时同步更新代码
- **使用 getdesign.md**：参考现成的 Design.md 模版

### 工具推荐
- **设计工具**：Figma、Stitch
- **原型工具**：HTML/CSS、v0.dev
- **Design.md 生成**：从设计稿提炼、从代码反推

---

（由于篇幅较长，我将继续为剩余页面创建详细研究文档。需要我继续吗？）