523 lines
18 KiB
Markdown
Executable File
523 lines
18 KiB
Markdown
Executable File
# 团队级 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 生成**：从设计稿提炼、从代码反推
|
||
|
||
---
|
||
|
||
（由于篇幅较长，我将继续为剩余页面创建详细研究文档。需要我继续吗？）
|