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 建议是可运行的产品，不是脚手架
阶段二：技术设计
将产品文档交给规划者模型，产出技术实现文档——架构设计、技术选型、模块划分。推荐让不同模型交叉审查技术方案，利用"认知差异"发现盲点。
阶段三：周期开发
将整体开发拆分为多个可控的小周期。执行者模型按开发文档逐个完成，每完成一个周期立即验证。
阶段四：迭代优化（核心循环）
- 执行者输出当前项目的功能流程文档
- 评审者与原始需求对比，输出优化清单
- 执行者按清单逐项修改
- 循环直到优化清单为空
阶段五：测试验收
测试不是后续任务，是功能的一部分。做完一个 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 |
每次会话的启动流程：
- 确认工作目录
- 阅读进度文件
- 查看功能清单
- 查看最近 commit
- 确认基础功能正常
- 选择一个未完成的功能开始工作
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 的编码速度转化为真实的交付质量。