---
url: /blog/ai-collaborative-development-methodology/index.md
---
# AI协作开发方法论

> **核心理念**：人类从"编码者"转型为"规划者 + 验证者"，通过前置规划、增量交付和分离评估，驾驭 AI 的编码生产力。
>
> **灵感来源**：Karpathy AI Coding Insight、400k 行代码实战指南、Vibe Coding 开发技巧与指南、ClawFeed 协作开发 SOP、Agent Harness 设计原则。

***

## 一、核心认知

### 1.1 声明式 > 命令式

告诉 AI 成功标准，而不是逐步指令。Karpathy 的核心发现：当编码速度趋近无限快时，规划和验证就成了新的瓶颈。与其告诉 AI "先做 A 再做 B"，不如告诉它"测试全部通过即为完成"，然后让它自主循环。

```
❌ 先写路由处理函数，再写数据库查询，最后写前端组件
✅ 验收标准：用户能在界面上完成 CRUD 操作，E2E 测试全部通过。请实现。
```

**收益**：AI 获得了自主迭代的空间，这恰恰是 Agent 最擅长的工作模式——它不会疲惫、不会气馁，会持续尝试直到达标。

### 1.2 规划前置，验证后置

在传统编码中，规划与实现交织进行。AI 辅助开发中，实现的成本被极度压缩——如果规划有误，AI 会以超人的速度执行错误的计划。

**建议**：在规划阶段投入比传统模式多 2-3 倍的时间。通过前期详尽的 Spec 设计，避免后期的返工和调试螺旋。

### 1.3 增量进展 > 一次性完成

Agent 尝试一次性完成所有功能，上下文耗尽后留下半成品代码，这是最常见的失败模式。解决方式是强制增量交付：每次会话只做一个原子任务，完成后立即验证并提交。

### 1.4 分离评估 > 自我评估

Agent 自评倾向于过度乐观，尤其在 UI 设计等主观任务上。独立的 Evaluator 用怀疑态度审查，比让生成者自我批评有效得多。这也是"多模型交叉审查"的底层逻辑。

### 1.5 方法论的边界

本方法论适用于以下场景：小型团队（1 人 + AI）、CRUD 密集型 Web 应用、文档驱动的功能开发。在以下场景需谨慎使用：

* **冷启动**：AI 未见过的新代码库，需大量时间补充上下文
* **创新架构**：无先例的全新系统，AI 倾向套用训练数据中的旧模式
* **隐蔽缺陷**：竞态条件、大规模并发问题仍需人类直觉
* **安全关键系统**：当前 AI 生成的代码建议经过额外安全审计

***

## 二、方法框架

### 2.1 双角色分工

AI 辅助编程推荐采用规划者与执行者的分离模式：

| 角色 | 职责 | 适合的模型特征 |
|:---|:---|:---|
| **规划者 / 评审者** | 需求分析、方案设计、质量评审、输出优化清单 | 强推理、长上下文（Claude Opus、GPT-4o、Gemini 2.5 Pro） |
| **执行者 / 编码者** | 代码实现、功能开发、测试编写 | 代码生成快、指令跟随准（Cursor 集成 Claude/GPT、Codex） |

**核心循环**：执行者输出 → 评审者审查 → 输出优化清单 → 执行者再执行 → 反复迭代直到收敛。

### 2.2 扩展：三角色 GAN 模式

对质量要求更高的场景，可以引入受 GAN（生成对抗网络）启发的三角色架构：

* **Planner（规划器）**：制定分步计划，不写代码
* **Generator（生成器）**：按计划实现代码，必须解决评估器指出的所有问题
* **Evaluator（评估器）**：独立审查，用怀疑态度评分，不能与生成者共享上下文

关键约束：评估者调校为"怀疑态度"比让生成者自我批评容易得多。5-15 轮迭代后通常能显著提升质量。

### 2.3 新项目：从 0 到 1

```
产品定义 → 技术设计 → 周期开发 ⇄ 迭代优化 → 测试验收
```

**阶段一：产品定义先行**

在写第一行代码之前，先产出 `PRODUCT.md` 或等效文档，定义：定位、功能清单、技术架构、Phase 路线图。这份文档是项目的"宪法"，后续所有决策以此为准。

**实操建议**：

* 一句话说清楚产品是什么
* 列出所有功能，按"用户可见"和"管理功能"分类
* 按 Phase 排列路线图，每阶段 3-5 个交付项
* 第一个 commit 建议是可运行的产品，不是脚手架

**阶段二：技术设计**

将产品文档交给规划者模型，产出技术实现文档——架构设计、技术选型、模块划分。推荐让不同模型交叉审查技术方案，利用"认知差异"发现盲点。

**阶段三：周期开发**

将整体开发拆分为多个可控的小周期。执行者模型按开发文档逐个完成，每完成一个周期立即验证。

**阶段四：迭代优化（核心循环）**

1. 执行者输出当前项目的功能流程文档
2. 评审者与原始需求对比，输出优化清单
3. 执行者按清单逐项修改
4. 循环直到优化清单为空

**阶段五：测试验收**

测试不是后续任务，是功能的一部分。做完一个 Phase，立刻用测试锁住它。推荐做法：

* 发现 Bug 时，先写复现测试，再修复
* 测试代码量建议占总代码量的 1/3 至 1/2
* 强制 AI 默认编写测试，而不是事后补

### 2.4 老项目：理解 → 修改 → 验证

```
项目理解 → 修改规划 → 模块开发(循环) → 集成测试
```

老项目的关键是先让 AI 理解现有结构：让执行者读取整个项目代码，输出功能流程文档。然后将修改需求拆分为功能模块，逐个完成修改 + 评审 + 测试的闭环。

**微服务架构的特殊处理**：每个服务单独运行理解流程，产出各服务的功能流程文档，再逐个修改。

### 2.5 技术栈选择原则

| 原则 | 理由 |
|:---|:---|
| 主流技术栈优先 | AI 训练数据覆盖更广，生成质量更高 |
| 确定性 > 抽象性 | `if/else` 路由比装饰器 + 依赖注入对 AI 更友好 |
| 依赖越少越好 | 工具链复杂度 = Agent 出错概率 |
| 构建步骤越少越好 | `npm start` 就是全部，是最理想的状态 |

**核心洞察**：AI 对确定性代码的生成质量明显高于抽象层代码。原生 `http.createServer` 比中间件链更容易让 AI 精确预测行为，直接 SQL 比 ORM 链式调用出错率更低。

### 2.6 决策空间最小化

ClawFeed 项目 7 天上线的真正奥秘不是"简单技术"，而是"极小的决策空间"——在启动前就锁定所有技术决策，零决策等于零时间浪费在选型上。

**建议**：技术选型的目标不是"最佳实践"，是在当前约束条件下能最快交付的方案。

### 2.7 敢于早期推翻决策

早期架构决策不是永恒的。发现不对就改，越晚改成本越高。但建议每次重大决策变更都记录原因，方便后续回溯。

***

## 三、实践指南

### 3.1 上下文焦虑

模型在接近上下文限制时，会开始过早收尾——即使任务远未完成。Compaction（上下文压缩）并不能完全解决这个问题。

**建议**：Context Reset（上下文重置）比 Compaction 更有效——完全清除上下文，通过结构化制品进行交接。

### 3.2 结构化交接制品

跨会话保持进度的关键制品：

| 制品 | 用途 | 格式建议 |
|:---|:---|:---|
| 进度文件 | 记录每次会话做了什么 | 纯文本（如 `progress.md`） |
| 功能清单 | 列出所有功能点及完成状态 | JSON（模型倾向只修改状态字段） |
| Git history | 代码变更历史 | 每次 commit 消息清晰描述 |
| 设计文档 | 实施过程中的设计决策 | Markdown |

**每次会话的启动流程**：

1. 确认工作目录
2. 阅读进度文件
3. 查看功能清单
4. 查看最近 commit
5. 确认基础功能正常
6. 选择一个未完成的功能开始工作

### 3.3 上下文清理

* 不相关的任务，主动开启新会话
* 如果 AI 三次尝试后仍失败，停止并开启新会话
* 发现自己在重复相同指令时，将其写入 `CLAUDE.md` 等持久化文档

### 3.4 多模型交叉审查

利用不同模型的"认知差异"进行对抗性审查：

* Claude 写的代码让 Codex 审查，反之亦然
* 审查角色设定为"Staff Engineer"，关注正确性、性能、安全性
* 迭代到多方达成一致

### 3.5 验证环

执行计划时，确保每一步都可控：

* 后端：实现前先写集成测试，用测试作为验证环
* 前端：挂载可视化环境进行视觉验证
* 每完成一步，运行验证并确认输出符合预期
* 每约 10 分钟检查一次进度更新，发现偏离立即干预

### 3.6 防止过早宣布完成

这是 Agent 最常见的失败模式之一。解决方案：

* 结构化 Feature List，每个功能有明确的验证步骤
* 端到端测试通过后才能标记完成（如 Puppeteer 浏览器自动化）
* 验收标准用 checklist 格式，`[ ]` 比"描述通过"更不容易遗漏
* 每个功能配回滚方案，迫使思考失败场景

### 3.7 Prompt 要点

| 推荐做法 | 避免 |
|:---|:---|
| 描述具体需求，一次只提一个任务 | 模糊的高层级指令，一次提五件事 |
| 明确告诉 AI 不该做什么 | 只描述期望的正向结果 |
| 提供 mockup、参考文件等辅助材料 | 纯文字描述 UI |
| 强制 AI 在生成前提出澄清问题 | 让 AI 自行假设并执行 |
| 善用"角色设定"框架 | 空泛头衔（"你是专家"） |

### 3.8 控制 AI 输出质量

* **需求理解复述**：强制 AI 在 PR 开头复述需求，理解错了在第一步就能打回
* **验收标准 checklist**：`[x]` 和 `[ ]` 一目了然，比段落描述更不容易遗漏
* **小而具体的指令**：每次只改一个点，立刻看效果，不要一次让 AI 改五个东西
* **定期重构**：AI 倾向于追加代码、膨胀文件、跳过清理。定期要求它退一步重构

### 3.9 版本控制

* 每个新功能从干净的 Git 状态开始
* 每次任务成功后及时 commit，让 AI 建议清晰的 commit message
* 需要回滚时使用 Git，而不是 AI 原生的撤销功能
* Branch Protection 开启，AI 不能自己 merge

***

## 四、工具与资源

### 4.1 常见陷阱与应对

| 陷阱 | 表现 | 应对 |
|:---|:---|:---|
| **信任陷阱** | Agent 跑太久不检查，在错误假设上越跑越偏 | 定期检查进度，发现偏离立即停止 |
| **概念错误** | AI 做了错误假设并一路执行，不寻求澄清 | 强制提问阶段 + 需求复述 |
| **代码膨胀** | 1000 行代码能实现的功能被膨胀到冗余结构 | 定期审查，问"能不能更简单" |
| **过度乐观** | Agent 自评高分但实际远未达标 | 独立评估者 + 端到端测试 |
| **过早完成** | Agent 看到已有进展就认为任务完成 | Feature List + 强制验证 |
| **死代码残留** | AI 不清理重构后的遗留代码 | 每次迭代后要求清理 |
| **隐蔽缺陷** | 竞态条件、并发问题等 AI 难以发现 | 人工审查 + 压力测试 |

### 4.2 总结

```
AI 协作开发的五个关键词：

规划  — 前置投入，Spec 驱动，产品定义先行
增量  — 每次一个原子任务，完成后立即验证提交
分离  — 规划与执行分离，生成与评估分离
验证  — 测试驱动，多模型交叉审查，checklist 验收
简洁  — 技术选型追求最小决策空间，减少 AI 出错概率
```

**"信任，但要验证"**——驾驭 AI 生产力的关键不在于谁的 Prompt 打字更快，而在于谁能通过更严谨的规划和验证流程，把 AI 的编码速度转化为真实的交付质量。