18 KiB
Executable File
18 KiB
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
- Cursor Rules：在
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
- Harness Engineering - Martin Fowler
- Anthropic: Harness Design for Long-running Apps
第3页：四大核心问题
原文内容
团队级 AI Coding 面临4个核心问题：
- 需求衔接：如何用 AI 整理需求？
- 开发实现：如何获得高质量的代码？
- 测试验收：如何根据规格自动化测试？
- 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
模版体系
- 需求规格模版：定义需求文档结构
- 技术规格模版：定义技术设计文档结构
- 测试规格模版：定义测试用例结构
- 代码模版：定义代码风格、目录结构
关键工具详解
-
Design.md
- 作用：约束 AI 生成的前端风格
- 内容：颜色、字体、间距、组件库
- 来源：从设计稿提炼或从现有代码反推
-
Playwright MCP
- 作用：让 AI 操作浏览器
- 场景：E2E 测试、UI 调试
- 优势：标准化接口，支持 Accessibility Tree
-
MCP（Model Context Protocol）
- 作用：AI 与外部系统通信的标准协议
- 场景：数据库、API、文件系统接入
- 优势：标准化、双向通信、即插即用
实践建议
- 建立模版库：将常用的文档结构模版化
- 统一工具链：团队使用相同的 AI IDE
- 维护 Design.md：确保 AI 生成的 UI 风格一致
第6页：分隔页（01 需求衔接）
原文内容
章节分隔页，标志进入"需求衔接"部分
研究要点
- 这是第4个核心问题的展开
- 需求衔接是整个开发流程的起点
- 良好的需求衔接能大幅提升 AI 代码质量
第7页：需求规格编写
原文内容
AI 能理解的需求格式：Markdown/Excel 表格
关键要素：
- 模块切分（增量/存量）
- 字段清单
- 原型链接
- 业务规则
编写原则：
- 先写业务背景，再切模块
- 一个模块 = 一个文档
- 分解为增量需求和存量需求：
- 增量需求：全新功能，需新建模块
- 存量修改：对已有功能做变更
- Tips：增量建模块，存量标改动
字段清单示例：
| 字段名 | 类型 | 必填 | 默认值 | 描述 |
|-----------|---------|------|--------|--------------|
| username | string | 是 | — | 登录用户名 |
| email | string | 是 | — | 电子邮箱 |
| role | enum | 否 | user | 用户角色 |
| status | boolean | 否 | true | 是否启用 |
字段定义要求：
- 定义完整字段
- 标注校验规则
- 标注 UI 展示
- 标注数据来源
原型图传递：
- Figma：选中 Frame → Share → Copy link
- Stitch：选中设计稿 → 获取分享链接
- HTML 版本：用 HTML/CSS 做可交互原型，提交到代码仓库
业务规则示例：
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 示例：
# 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 生成：从设计稿提炼、从代码反推
（由于篇幅较长，我将继续为剩余页面创建详细研究文档。需要我继续吗？）