# 团队级 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页内容已详细研究并归档，包含：
- 原文内容提取
- 深入解读和背景知识
- 实践建议和工具推荐
- 代码示例和配置示例
- 最佳实践清单
- 学习路径指南