# 团队级 AI Coding 简明手册 v0.2

> 来源：系统设计研讨会分享 PPT（2026.06.18），版权归分享人所有
> 归档日期：2026-06-20

---

## 一、AI 编程思想发展过程

| 阶段 | 特征 | 模式 |
|------|------|------|
| **原始阶段** | 基于本能的 AI 编程，手动复制代码或通过问答交互 | 半自动，有人值守 |
| **Rule 约束** | 经验规则显化（如 RIPER-5），通过持续对话输入需求 | 半自动 |
| **规格驱动** | 需求结构化表达，基于规格流转（如 OpenSpec），文件进文件出 | 全自动过渡 |
| **Loop Engineering** | 可反馈闭环：AI 根据验收规则自动循环 + 测试套件 | 全自动 |
| **Harness 驾驭工程** | 纳入工程治理体系，提供约束体系 + 外部接口 | 全自动，Plan 后无人值守 |

> 每一次思想的变更是对前者的重新表述而非推翻

---

## 二、AI 赋能软件开发实现地图

```
需求分析 → 需求文档/原型图 → 技术方案设计 → 代码框架+打样工程
    ↓            ↓                ↓                ↓
  人+AI        人+AI             人+AI            人+AI
    ↓            ↓                ↓                ↓
AI代码编写 → 单元测试/调试 → E2E测试 → Code Review → 提测部署
    ↓            ↓              ↓           ↓           ↓
  机           机+人           机+人        机+人        机+人
```

**核心 Loop**：研发自测阶段，AI 自治运行
**全流程超级 Loop**：从需求到部署的完整闭环

---

## 三、四大核心问题

### 01 需求衔接
- 如何编写 AI 能理解的需求？
- 使用什么格式？如何组织需求规格？
- 如何传递原型图？需求模版长什么样？

### 02 开发实现
- 如何让 AI 理解上下文且按要求执行？
- 如何调用外部工具？生成一致的代码？
- 如何多任务同步开发？

### 03 测试验收
- AI 编程需要什么测试策略？
- 如何让 AI 操作浏览器？
- 如何管理测试用例？

### 04 Agent as Code
- 如何把和 AI 协作的文件在代码仓库中合理组织？
- 构建 AI 更友好的环境

---

## 四、需求规格编写

### 关键要素
- **模块切分**（增量/存量）
- **字段清单**
- **原型链接**
- **业务规则**

### 编写原则
1. 先写业务背景，再切模块。**一个模块 = 一个文档**
2. 分解为增量需求和存量需求：
   - **增量需求** — 全新功能，需新建模块
   - **存量修改** — 对已有功能做变更
3. 字段定义需完整：类型、必填、默认值、描述、校验规则、UI展示、数据来源
4. 业务规则条目化 + 正交分解，每条规则独立可测

> **Tips**: BA 也应该工作在代码仓库中，让 AI 基于当前系统事实构建新需求

### 原型图设计
- **设计工具输出**：Figma/Stitch URL 嵌入需求文档
- **HTML+CSS 输出**：可交互原型提交到代码仓库
- **Design.md**：约束 AI 生成的前端风格，确保与项目组件库一致

---

## 五、开发实现

### 让 AI 听话的三要素

| 要素 | 说明 | 示例 |
|------|------|------|
| **规则 Rules** | 约束 AI 行为边界 | Java 代码风格、命名规范 |
| **规格 Specification** | 结构化需求，甚至用 DSL 描述 | 用户故事 + 验收标准 |
| **技能 Skill** | 打包提示词/脚本/模版扩展能力 | Commit & Push Skill |

### 构建 AI 上下文体系（详见下方重点章节）

### 让 AI 调用外部工具的三种方式
1. **CLI Commands** — 最直接，AI 生成命令并执行
2. **MCP** — 标准协议，统一接入数据库/API/文件系统
3. **Skills** — 脚本封装，触发词驱动

### AI 编程工具选择
- **命令行类**：Claude Code、Codex CLI、OpenCode
- **AI IDE**：Cursor、Kiro、Trae
- **增强插件**：Superpower、oh-my-opencode、oh-my-codex

### SDD 框架对比

| 维度 | BMAD | Spec Kit | OpenSpec | Kiro |
|------|------|----------|----------|------|
| 定位 | 企业级 SDD 操作系统 | 工程化 Spec 工作流 | 轻量 Spec 层 | IDE 原生 SDD |
| Spec 粒度 | 大（系统/模块级） | 中（Feature级） | 小（变更/Patch级） | 中（Feature+行为） |
| 自动验证 | 无 | 无 | 弱 | 强（内建） |
| 适用场景 | 大型系统/多团队 | 新项目（0→1） | 存量项目/快速迭代 | 小团队/高自动化 |

### 技术规格编写（DSL 驱动）

| 模块 | 标准 | 格式 | 约束 |
|------|------|------|------|
| 领域模型 | PlantUML/Smart Domain | .puml | 必须表达实体关系 |
| 数据库 | SQL DDL/DBML | .sql | 必须可执行 |
| API | OpenAPI 3.x | .yaml/.json | 必须定义 schema |
| 时序图 | PlantUML | .puml | 必须反映真实调用链 |
| 专题设计 | Markdown | .md | 只写策略与规则 |

### 打样工程：让 AI 抄作业
- 原则：约定大于配置、编排逻辑和原子能力分离、操作者和被操作对象分离
- 简单 CRUD：Controller + Command → AppService → Repository → Response
- 复杂 CRUD：Controller + Command → AppService → DomainService → Repository → Response
- 复杂查询：Controller + Query → AppService → QueryPO → Response

### 多任务同步开发
使用 `git worktree` 同时把多个分支映射到不同文件夹：
```bash
git worktree add -b feature-payment ../feature-payment
```

---

## 六、⭐ 过程方案 vs 事实方案（重点）

### 核心理念

> 使用完整的文档来描述上下文和约束体系，**区分过程方案和事实方案，减少维护成本**。

### 文档分层体系

```
AGENTS.md          ← 宪法级约束
docs/
├── standards/     ← 标准规格（架构/命名/API/安全规范）
├── features/      ← 需求规格（产品/BA维护）
├── designs/       ← 设计规格（DB/表等 Source of Truth）  ⬅ 事实方案
├── plans/         ← 计划规格（每轮任务实现方案）          ⬅ 过程方案
└── others/        ← 架构决策、Release、测试用例等
```

### 过程方案（Plans）

**定义**：每一轮任务的实现方案、Tasking、工作状态。

**特征**：
- **临时性**：每次创建新文件，用完即弃
- **不维护**：细微修改不再更新旧文件
- **可追溯**：保留历史决策轨迹，方便复盘
- **增量追加**：`追加: 每次创建一个新的文件`

**示例**：
```
docs/plans/
├── plan-2026-06-01-user-auth.md      # 第1轮
├── plan-2026-06-05-user-auth-v2.md   # 第2轮迭代
├── plan-2026-06-10-payment-flow.md   # 新任务
└── plan-2026-06-15-order-module.md   # 新任务
```

**为什么这样设计**：
1. 避免反复修改同一文件导致的 Git 冲突
2. 保留完整决策轨迹，AI 和人都能回溯
3. AI 执行完可以"丢弃"，不污染长期文档
4. 降低维护成本——过程方案不需要维护

**在 Plan/Go 模式中的角色**：
- Plan 阶段产出 → 锁定上下文到 Plan 中
- 记录实现状态，让任务可以分批完成或重试
- 关闭所有开放性问题后再进入执行

### 事实方案（Designs / Standards / Features）

**定义**：反映系统**当前真实状态**的文档，是 Source of Truth。

**特征**：
- **长期有效**：稳定的、持续维护的
- **最终态更新**：`变更: 每次以最终态更新`
- **事实依据**：作为下一次 Plan 的起点
- **必须一致**：与实际代码/系统保持同步

**示例**：
```
docs/designs/
├── database-schema.md      # 当前数据库表结构（最终态）
├── api-endpoints.md        # 当前 API 定义（最终态）
└── architecture.md         # 当前架构图（最终态）

docs/standards/
├── coding-style.md         # 编码规范
└── security-guidelines.md  # 安全规范

docs/features/
├── user-management.md      # 用户管理需求（当前版本）
└── order-system.md         # 订单系统需求（当前版本）
```

**为什么这样设计**：
1. AI 每次 Plan 前读取这些文档，获得"当前真相"
2. 避免 AI 基于过时信息做决策
3. 只维护一份最终态，减少维护成本
4. 是团队共识的载体

### 规格流转图

```
起点 Features（需求规格）
    ↓
Standards（约束规范）
    ↓
TDD 驱动 → 测试 + 代码
    ↓
事实方案 Designs（更新最终态）  ← 变更：覆盖更新
    ↓
过程方案 Plans（执行记录）      ← 追加：新建文件
    ↓
回到起点 Features（验收）
```

### 实践建议

1. **AGENTS.md 作为宪法**：定义 AI 行为边界和基本原则
2. **区分"打算做"和"已做完"**：Plans 是意图，Designs 是事实
3. **Plan 阶段尽可能锁定上下文**：关闭所有开放性问题
4. **Plan 中记录实现状态**：让任务可以分批完成或重试
5. **给出确定性验收方式**：如通过所有 API 测试，让 AI 建立自我修复标准

---

## 七、测试验收

### AI 辅助测试策略

| 测试类型 | 工具 | 负责人 |
|----------|------|--------|
| Lint 代码扫描 | TS Lint/SonarQube | 程序 |
| Code Review | Copilot/Claude Code/CodeRabbit | 开发者 + AI |
| 单元测试 | JUnit/pytest/Jest | 开发者 + AI |
| API 测试 | Karate/RestAssured | QA + 后端 + AI |
| E2E 测试 | Playwright | QA + 自动化 + AI |

### AI 操作浏览器方案对比

| 方案 | 原理 | 速度 | Token 消耗 | 跨应用 |
|------|------|------|-----------|--------|
| OpenWright (Playwright MCP) | Accessibility Tree | 快 ~0.9s | 高 | 仅浏览器 |
| Chrome DevTools MCP | CDP 协议 | 中 ~1.2s | 中 | 仅浏览器 |
| Browser Use | DOM + 截图双模 | 中 ~1.5s | 极低 | 仅浏览器 |
| Computer Use | 视觉识别+坐标 | 慢 0.8-2s | 高 | 全桌面 |

### E2E 测试生成策略
1. **Browser Use 探索**：AI 自主遍历页面，记录操作轨迹（消耗 Token）
2. **Playwright 固化**：转为测试脚本加入 CI（零 Token 可重复运行）
3. **截图视觉兜底**：覆盖布局偏移、动效、Canvas 等场景

### 核心 Loop（研发自测）
```
Plan 模式装载需求规格 → Plan 确认 → 编写 API 测试 → 编写实现
    → 运行测试 → 通过？→ 退出循环
                 ↓ 否
              修复重试
```

### 超级 Loop（E2E Loop）
在核心 Loop 基础上增加：
- 编写测试用例（docs/test-cases）
- 浏览器调试（Playwright 确认视觉效果）
- 编写 E2E 测试覆盖本轮需求

---

## 八、Agent as Code

### AI 工程文件管理
```
AGENTS.md          ← 宪法，构建引用关系
docs/
├── .ai/           ← AI 配置
├── standards/     ← 标准规格
├── features/      ← 需求规格
├── designs/       ← 设计规格
├── plans/         ← 计划规格
├── skills/        ← AI 技能
└── mcp/           ← MCP 配置

.claude / .opencode / .cursor  → 软链到 AGENTS.md
```

---

## 九、实践心得

> - 放弃"开箱即用"的框架，每个项目需要构建自己的 Harness 工具和文档
> - "少量取用，大量实践"是更好的策略

---

## 参考资料

- [Harness Engineering - OpenAI](https://openai.com/index/harness-engineering/)
- [Harness Engineering - Martin Fowler](https://martinfowler.com/articles/harness-engineering.html)
- [Harness Design for Long-running Apps - Anthropic](https://www.anthropic.com/engineering/harness-design-long-running-apps)
- [从 Rule、Spec 到 Harness 的渐进式建设路径](https://mp.weixin.qq.com/s/UCh2bPzMZjNBMBCCJysuNw)
- [Understanding SDD: Kiro, spec-kit, and Tessl](https://martinfowler.com/articles/exploring-gen-ai/sdd-3-tools.html)
- [harness-engineering-in-ai-coding](https://github.com/2361485765/harness-engineering-in-ai-coding)