324 lines
12 KiB
Markdown
Executable File
324 lines
12 KiB
Markdown
Executable File
# 团队级 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)
|