355 lines
13 KiB
Markdown
Executable File
355 lines
13 KiB
Markdown
Executable File
# 团队级 AI Coding 简明手册 v0.2 - 逐页研究索引
|
||
|
||
> 原文：系统设计研讨会分享 PPT（2026年6月18日）
|
||
> 研究日期：2026-06-20
|
||
> 研究范围：第1-30页（全文）
|
||
> 归档位置：/obsidian/AI工程/团队级AI_Coding简明手册_逐页研究/
|
||
|
||
---
|
||
|
||
## 文档结构
|
||
|
||
### 00_概述与前言.md
|
||
**覆盖页码**：第1-8页
|
||
|
||
**核心内容**：
|
||
- 第1页：封面信息
|
||
- 第2页：AI 编程思想发展过程（5个阶段）
|
||
- 第3页：四大核心问题概述
|
||
- 第4页：AI 赋能软件开发实现地图
|
||
- 第5页：AI 赋能软件开发工具体系
|
||
- 第6页：分隔页（01 需求衔接）
|
||
- 第7页：需求规格编写
|
||
- 第8页：原型图设计
|
||
|
||
**关键概念**：
|
||
- AI 编程5阶段：原始 → Rule约束 → 规格驱动 → Loop工程 → Harness驾驭
|
||
- 4个核心问题：需求衔接、开发实现、测试验收、Agent as Code
|
||
- 需求规格：Markdown格式、字段清单、业务规则条目化
|
||
- 原型图：Figma/Stitch/HTML + Design.md
|
||
|
||
---
|
||
|
||
### 01_开发实现_第9-15页.md
|
||
**覆盖页码**：第9-15页
|
||
|
||
**核心内容**：
|
||
- 第9页：分隔页（02 开发实现）
|
||
- 第10页：如何让 AI 听话 - 规则、规格、技能
|
||
- 第11页：构建 AI 上下文体系
|
||
- 第12页：如何让 AI 调用外部工具
|
||
- 第13页：用什么 AI 编程工具
|
||
- 第14页：用什么 SDD 框架比较好
|
||
- 第15页：一个新星：Superpower
|
||
|
||
**关键概念**：
|
||
- 三要素：Rules（规则）、Specification（规格）、Skill（技能）
|
||
- 上下文体系：AGENTS.md + docs/（standards/features/plans/designs/others）
|
||
- 过程方案 vs 事实方案：Plans（追加新文件）vs Designs（覆盖更新）
|
||
- 外部工具：MCP、Skills、CLI
|
||
- AI 工具：Claude Code、Cursor、Kiro、Trae、OpenCode、Codex CLI
|
||
- SDD 框架：BMAD、Spec Kit、OpenSpec、Kiro
|
||
|
||
---
|
||
|
||
### 02_开发实现续_第16-19页.md
|
||
**覆盖页码**：第16-19页
|
||
|
||
**核心内容**：
|
||
- 第16页：技术规格如何编写
|
||
- 第17页：打样工程：如何让 AI 抄作业
|
||
- 第18页：如何多任务同步开发
|
||
- 第19页：完整的核心 Loop 过程（研发自测）
|
||
|
||
**关键概念**：
|
||
- 技术规格 DSL：领域模型（PlantUML）、数据库（SQL DDL）、API（OpenAPI）、时序图、专题设计
|
||
- 打样工程：提供代码模版，让 AI "抄作业"
|
||
- 三层架构：Controller → Service → Repository
|
||
- Git Worktree：多任务并行开发
|
||
- 核心 Loop：Plan → TDD → 验证
|
||
|
||
---
|
||
|
||
### 03_测试验收_第20-25页.md
|
||
**覆盖页码**：第20-25页
|
||
|
||
**核心内容**：
|
||
- 第20页：分隔页（03 测试验收）
|
||
- 第21页：AI 辅助下的测试策略
|
||
- 第22页：AI 如何操作浏览器
|
||
- 第23页：如何用测试用例生成 E2E 测试
|
||
- 第24页：Playwright E2E 示例
|
||
- 第25页：超级 Loop（E2E Loop）
|
||
|
||
**关键概念**：
|
||
- 测试策略：Lint → Code Review → 单元测试 → API 测试 → E2E 测试
|
||
- AI 操作浏览器：Playwright MCP、Chrome DevTools MCP、Browser Use、Computer Use
|
||
- E2E 测试生成：Browser Use 探索 → Playwright 固化 → 截图视觉兜底
|
||
- Playwright 最佳实践：稳定选择器、API 登录、测试数据管理
|
||
- 超级 Loop：在核心 Loop 基础上增加 E2E 测试验证
|
||
|
||
---
|
||
|
||
### 04_Agent_as_Code_第26-30页.md
|
||
**覆盖页码**：第26-30页
|
||
|
||
**核心内容**：
|
||
- 第26页：分隔页（04 Agent as Code）
|
||
- 第27页：AI 工程文件管理
|
||
- 第28页：分隔页（附录&参考资料）
|
||
- 第29页：关于 AI 编程实践的心得
|
||
- 第30页：参考资料
|
||
|
||
**关键概念**：
|
||
- Agent as Code：将 AI 协作文件以代码方式管理
|
||
- AGENTS.md 作为宪法级配置
|
||
- 软链接实现多工具共享配置
|
||
- Skills 目录：可复用的 AI 能力单元
|
||
- MCP 配置：让 AI 访问外部工具
|
||
- 实践心得：放弃"开箱即用"，"少量取用，大量实践"
|
||
|
||
---
|
||
|
||
## 核心框架总结
|
||
|
||
### 团队级 AI Coding 的4个核心问题
|
||
|
||
| 问题 | 核心挑战 | 解决方案 |
|
||
|------|---------|---------|
|
||
| **需求衔接** | 如何编写 AI 能理解的需求？ | Markdown 格式、字段清单、业务规则条目化、原型图传递 |
|
||
| **开发实现** | 如何让 AI 生成高质量代码？ | 规则/规格/技能、上下文体系、MCP/Skills/CLI、SDD 框架、打样工程、核心 Loop |
|
||
| **测试验收** | 如何自动化测试 AI 生成的代码？ | 分层测试、AI 操作浏览器、E2E 测试生成、超级 Loop |
|
||
| **Agent as Code** | 如何组织 AI 协作文件？ | AGENTS.md、文档体系、Skills 库、MCP 配置、软链接 |
|
||
|
||
### AI 编程5阶段演进
|
||
|
||
```
|
||
原始阶段 → Rule 约束 → 规格驱动 → Loop Engineering → Harness 驾驭工程
|
||
↓ ↓ ↓ ↓ ↓
|
||
手动复制 RIPER-5 OpenSpec 自动循环 工程治理
|
||
半自动 持续对话 文件进出 测试驱动 无人值守
|
||
```
|
||
|
||
### 文档分层体系
|
||
|
||
```
|
||
AGENTS.md ← 宪法（所有 AI 工具读取）
|
||
docs/
|
||
├── standards/ ← 标准规格（架构/命名/API/安全规范）
|
||
├── features/ ← 需求规格（产品/BA维护）
|
||
├── designs/ ← 设计规格（事实方案，Source of Truth）
|
||
├── plans/ ← 计划规格（过程方案，追加不修改）
|
||
└── others/ ← 架构决策、Release、测试用例等
|
||
skills/ ← AI 技能（可复用能力单元）
|
||
mcp/ ← MCP 配置（外部工具接入）
|
||
```
|
||
|
||
### 核心 Loop 流程
|
||
|
||
```
|
||
Plan 阶段（人机协作）
|
||
↓
|
||
装载需求规格 → 创建 Plan → 确认 Plan
|
||
↓
|
||
执行阶段（AI 自治）
|
||
↓
|
||
编写 API 测试 → 编写实现 → 运行测试
|
||
↓ ↓
|
||
↓ 失败 ↓ 成功
|
||
↓ ↓
|
||
修复重试 ←──────────────────── 退出循环
|
||
```
|
||
|
||
### 测试策略金字塔
|
||
|
||
```
|
||
E2E 测试（Playwright）
|
||
/ \
|
||
/ API 测试（Karate） \
|
||
/ \
|
||
/ 单元测试（JUnit/Jest） \
|
||
/ \
|
||
/ Code Review（AI + 人工） \
|
||
/ \
|
||
/ Lint 代码扫描（ESLint/SonarQube）\
|
||
/____________________________________\
|
||
```
|
||
|
||
---
|
||
|
||
## 关键工具清单
|
||
|
||
### AI 编程工具
|
||
- **Claude Code**：Anthropic 出品，强大的推理能力
|
||
- **Cursor**：基于 VS Code，AI 优先设计
|
||
- **Kiro**：AWS 出品，深度集成 AWS 服务
|
||
- **Trae**：字节跳动出品，中文支持好
|
||
- **OpenCode**：开源，支持多种 AI 模型
|
||
- **Codex CLI**：OpenAI 出品，基于 GPT-4
|
||
|
||
### SDD 框架
|
||
- **BMAD**：企业级，强治理，多 Agent 编排
|
||
- **Spec Kit**：工程化，Git 集成，适合新项目
|
||
- **OpenSpec**：轻量级，灵活，适合存量项目
|
||
- **Kiro**：IDE 原生，可执行 Spec，自动验证
|
||
|
||
### 测试工具
|
||
- **Playwright**：最流行的 E2E 测试框架
|
||
- **Browser Use**：AI 操作浏览器，Token 消耗低
|
||
- **Karate**：BDD 风格的 API 测试框架
|
||
- **RestAssured**：Java API 测试库
|
||
- **SonarQube**：代码质量分析工具
|
||
- **ESLint**：JavaScript 代码检查工具
|
||
|
||
### 文档工具
|
||
- **PlantUML**：文本化的 UML 图
|
||
- **OpenAPI**：API 规范定义
|
||
- **Markdown**：通用文档格式
|
||
- **Mermaid**：Markdown 中的图表
|
||
|
||
### 协作工具
|
||
- **Git**：版本控制
|
||
- **GitHub/GitLab**：代码托管和协作
|
||
- **Git Worktree**：多工作区并行开发
|
||
|
||
---
|
||
|
||
## 最佳实践清单
|
||
|
||
### 需求阶段
|
||
- [ ] 使用 Markdown 编写需求规格
|
||
- [ ] 区分增量需求和存量需求
|
||
- [ ] 使用字段清单定义数据模型
|
||
- [ ] 业务规则条目化，每条规则独立可测
|
||
- [ ] 通过原型图传递 UI 设计（Figma/Stitch/HTML）
|
||
- [ ] 维护 Design.md 约束前端风格
|
||
|
||
### 开发阶段
|
||
- [ ] 建立 AGENTS.md 作为宪法级配置
|
||
- [ ] 区分过程方案（Plans）和事实方案（Designs）
|
||
- [ ] 使用 DSL 编写技术规格（PlantUML/SQL/OpenAPI）
|
||
- [ ] 建立打样工程，提供代码模版
|
||
- [ ] 使用 TDD 驱动开发
|
||
- [ ] 使用 Git Worktree 并行开发
|
||
- [ ] Plan 阶段充分沟通，关闭所有开放性问题
|
||
|
||
### 测试阶段
|
||
- [ ] 分层测试：单元测试 → API 测试 → E2E 测试
|
||
- [ ] 先用 Browser Use 探索，再固化到 Playwright
|
||
- [ ] 使用稳定的选择器（data-testid、角色、标签）
|
||
- [ ] 关键页面截图验证（视觉回归测试）
|
||
- [ ] 所有测试集成到 CI/CD 流程
|
||
|
||
### 协作阶段
|
||
- [ ] 使用 AGENTS.md 作为统一入口
|
||
- [ ] 使用软链接让多个工具共享配置
|
||
- [ ] 所有配置纳入 Git 管理
|
||
- [ ] 建立 Skills 库，沉淀常用 AI 能力
|
||
- [ ] 配置 MCP 让 AI 访问外部工具
|
||
|
||
---
|
||
|
||
## 学习路径
|
||
|
||
### 入门（1-2周）
|
||
1. 理解 AI 编程的5个发展阶段
|
||
2. 建立 AGENTS.md
|
||
3. 使用一个 AI 工具（如 Claude Code）
|
||
4. 实践核心 Loop（Plan → TDD → 验证）
|
||
|
||
### 进阶（1-2月）
|
||
1. 学习 SDD 框架（BMAD/SpecKit/OpenSpec/Kiro）
|
||
2. 使用 DSL 编写技术规格
|
||
3. 建立打样工程
|
||
4. 实践分层测试
|
||
5. 使用 Playwright 进行 E2E 测试
|
||
|
||
### 高级（持续）
|
||
1. 构建完整的 Harness 体系
|
||
2. 开发自定义 Skills
|
||
3. 配置 MCP 访问外部工具
|
||
4. 优化 AI 工作流
|
||
5. 分享实践经验
|
||
|
||
---
|
||
|
||
## 关键洞察
|
||
|
||
1. **AI 编程不是银弹**：需要工程化的方法来驾驭
|
||
2. **上下文是关键**：AI 需要清晰的上下文才能生成高质量代码
|
||
3. **测试是保障**：自动化测试是 AI 生成代码质量的保障
|
||
4. **实践出真知**：没有放之四海而皆准的方案，需要根据项目特点定制
|
||
5. **持续演进**：AI 能力在快速提升，方法也需要持续演进
|
||
6. **区分过程和事实**：Plans 是过程记录（追加不修改），Designs 是事实描述（覆盖更新）
|
||
7. **少量取用，大量实践**：不要一开始就引入所有概念，先实践核心，再逐步扩展
|
||
|
||
---
|
||
|
||
## 术语表
|
||
|
||
| 术语 | 英文 | 定义 |
|
||
|------|------|------|
|
||
| AI 编程 | AI Coding | 使用 AI 辅助或自动化进行软件开发 |
|
||
| Harness | Harness | 为 AI 提供约束和工具的工程实践 |
|
||
| SDD | Spec-Driven Development | 以规格文档为核心的开发方法 |
|
||
| MCP | Model Context Protocol | AI 与外部系统通信的标准协议 |
|
||
| AGENTS.md | AGENTS.md | AI 协作的宪法级配置文件 |
|
||
| Plan | Plan | AI 执行任务的规划文档 |
|
||
| Spec | Specification | 结构化的需求描述 |
|
||
| Rule | Rule | 约束 AI 行为的规则 |
|
||
| Skill | Skill | 可复用的 AI 能力单元 |
|
||
| Loop | Loop | AI 自治运行的开发循环 |
|
||
| TDD | Test-Driven Development | 测试驱动开发 |
|
||
| E2E | End-to-End | 端到端测试 |
|
||
| DSL | Domain Specific Language | 领域特定语言 |
|
||
| Worktree | Git Worktree | Git 的多工作区功能 |
|
||
| Browser Use | Browser Use | AI 操作浏览器的框架 |
|
||
| Playwright | Playwright | 浏览器自动化测试框架 |
|
||
| BMAD | Business Model Architecture Design | 企业级 SDD 框架 |
|
||
| OpenSpec | OpenSpec | 轻量级 SDD 框架 |
|
||
| Kiro | Kiro | AWS 推出的 AI IDE 和 SDD 框架 |
|
||
|
||
---
|
||
|
||
## 参考资料
|
||
|
||
1. [Harness Engineering - OpenAI](https://openai.com/index/harness-engineering/)
|
||
2. [Harness Engineering - Martin Fowler](https://martinfowler.com/articles/harness-engineering.html)
|
||
3. [Anthropic: Harness Design for Long-running Apps](https://www.anthropic.com/engineering/harness-design-long-running-apps)
|
||
4. [从 Rule、Spec 到 Harness：AI Coding 的渐进式建设路径](https://mp.weixin.qq.com/s/UCh2bPzMZjNBMBCCJysuNw)
|
||
5. [让 AI 乖乖听话的几个 Rules](https://mp.weixin.qq.com/s/FXNzk_y2Z2h8BVe62uEn_A)
|
||
6. [Understanding SDD: Kiro, spec-kit, and Tessl](https://martinfowler.com/articles/exploring-gen-ai/sdd-3-tools.html)
|
||
7. [harness-engineering-in-ai-coding](https://github.com/2361485765/harness-engineering-in-ai-coding)
|
||
8. [attractor-guided-engineering-template](https://github.com/entropy-cloud/attractor-guided-engineering-template)
|
||
9. [OpenAI: Tools Computer Use](https://developers.openai.com/api/docs/guides/tools-computer-use)
|
||
|
||
---
|
||
|
||
## 文档信息
|
||
|
||
- **原文**：团队级 AI Coding 简明手册 v0.2
|
||
- **作者**：系统设计研讨会分享人
|
||
- **日期**：2026年6月18日
|
||
- **研究日期**：2026-06-20
|
||
- **研究范围**：第1-30页（全文）
|
||
- **归档位置**：/obsidian/AI工程/团队级AI_Coding简明手册_逐页研究/
|
||
- **文件列表**：
|
||
- 00_概述与前言.md（第1-8页）
|
||
- 01_开发实现_第9-15页.md（第9-15页）
|
||
- 02_开发实现续_第16-19页.md（第16-19页）
|
||
- 03_测试验收_第20-25页.md（第20-25页）
|
||
- 04_Agent_as_Code_第26-30页.md（第26-30页）
|
||
- 00_索引.md（本文档）
|
||
|
||
---
|
||
|
||
**研究完成** ✅
|
||
|
||
所有30页内容已详细研究并归档，包含：
|
||
- 原文内容提取
|
||
- 深入解读和背景知识
|
||
- 实践建议和工具推荐
|
||
- 代码示例和配置示例
|
||
- 最佳实践清单
|
||
- 学习路径指南
|