Update from Sync Service

AI工程/团队级AI_Coding简明手册_逐页研究/00_概述与前言.md

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