AI Agent 驱动开发 (AADD) 操作者手册

定义： 本手册适用于使用 AI Agent（如 Devin, Cursor Agent, AutoGPT 等）进行端到端软件开发的场景。在此模式下，人类操作者是架构师（Architect）和验收官（Gatekeeper），AI Agent 是执行者（Executor）。

核心原则：
1. Spec 即 Prompt：SBE 中的规范文档直接作为 AI 的核心指令。
2. 上下文隔离：必须为 AI 提供清晰的边界和上下文，防止幻觉。
3. 信任但验证 (Trust but Verify)：AI 产出的每一行代码必须通过自动化测试验证。

1. 准备阶段：构建上下文 (Context Setting)

步骤 1.1：定义“真理来源” (Source of Truth)

Human

在让 AI 写代码前，必须先准备好结构化的规范文件。AI 不具备“猜测业务意图”的能力，模糊的输入必然导致错误的输出。

输入物：符合 SBE 标准的 Specification 文件（Markdown/Gherkin）。
关键动作：将 Spec 文件置于项目根目录的 /specs 或 /docs 文件夹中。
上下文文件：准备一个 .cursorrules 或 system_prompt.md 文件，包含技术栈约束（如："使用React 18, Tailwind, Jest"）。

# System Context Role: Senior Full-Stack Engineer Tech Stack: TypeScript, Node.js, PostgreSQL Testing Library: Vitest Style Guide: Airbnb Style Guide # Constraint 1. 严禁修改 `/specs` 目录下的业务规则。 2. 所有代码必须优先编写测试 (TDD)。 3. 任何新增依赖库必须先询问。

2. 设计阶段：方案与分解 (Design & Decomposition)

步骤 2.1：生成技术设计方案 (RFC Generation)

AI Agent

禁止 AI 直接开始写代码。 必须要求 AI 先输出设计文档和任务清单。

[指令] 阅读 /specs/payment/vip_free_shipping.md。请根据该规范，编写一份简短的技术实现方案 (Tech Design Doc)。要求包含： 1. 需要修改的数据表结构（SQL Schema）。 2. API 接口定义（OpenAPI/Swagger格式）。 3. 核心算法的伪代码。 4. 潜在的风险点。请不要写任何实现代码，仅输出 Markdown 方案供我评审。

步骤 2.2：方案评审与任务分解 (Review & Breakdown)

Human

人工评审：检查 AI 生成的 SQL 和 API 是否符合系统现状。
任务原子化：要求 AI 将方案拆解为不超过 50 行代码变更的“原子任务列表”。

警告： 如果 AI 试图一次性完成整个功能，必须打断并强制要求拆分（如：先写 Model，再写 Service，最后写 API）。

3. 编码阶段：循环 TDD (Implementation Loop)

在此阶段，操作者进入“监控模式”，AI 进入“执行循环”。必须强制 AI 遵循 Red-Green-Refactor 流程。

子步骤	执行者	操作标准
3.1 编写测试 (Red)	AI	指令："根据 Spec 中的 Example 表格，编写 failing test。" 校验点：人类检查测试代码是否硬编码了 Spec 中的真实数据（如 `5 books`），而非随机数据。
3.2 实现代码 (Green)	AI	指令："编写最少量的实现代码使测试通过。" Agent 自主运行测试，如果失败则自动修正，直到全部通过。
3.3 重构 (Refactor)	AI	指令："检查代码是否有重复逻辑？是否符合 Lint 规范？优化命名。" 此时 AI 往往会产生幻觉引入过度设计，人类需严格把关。

步骤 3.4：活文档同步 (Living Doc Sync)

如果 AI 在编码过程中发现 Spec 遗漏了边缘情况（AI 经常能发现这些）：

[指令] 你发现了一个 Spec 中未定义的边缘情况（当库存不足时）。请不要擅自处理。 1. 先更新 /specs/payment/vip_free_shipping.md，添加这个新的 Scenario。 2. 待我确认文档后，再编写对应的代码。

4. 测试与验收阶段 (Testing & Verification)

步骤 4.1：完整性回归

AI 完成代码后，必须运行全量测试，防止破坏现有功能（Shotgun Surgery）。

操作：要求 AI 运行 npm test 或对应指令。
策略：如果 AI 修改了非相关文件，要求其解释原因并回滚无关修改。

步骤 4.2：人工代码审查 (Human Code Review)

Human

此时不需太关注语法（AI通常是对的），重点关注逻辑与安全。

逻辑一致性：代码逻辑是否真的实现了 Spec 的意图？还是只是凑巧通过了测试？
安全检查：是否有硬编码密钥？是否有 SQL 注入风险？
可读性：变量命名是否符合业务领域的通用语言（Ubiquitous Language）？

5. 异常处理与干预机制 (Intervention Protocol)

当 AI Agent 陷入死循环或产出垃圾代码时，操作者应遵循以下协议：

现象	诊断	干预措施 (Intervention)
反复修改同一段代码测试依旧不通过	上下文丢失或逻辑陷入局部最优。	1. 停止 Agent。 2. 手动 git reset 回退到上一个稳定状态。 3. 给 AI 提供错误日志，并提示："不要尝试修复旧代码，请重新思考实现逻辑。"
修改了大量无关文件	Agent 对系统依赖关系理解错误。	1. 强制回滚。 2. 更新 `.cursorrules` 或上下文文件，明确禁止修改某些目录。 3. 缩小 AI 的文件读取权限。
代码能跑但很丑陋	缺乏重构指令。	发送指令："保持功能不变，提取方法 X，重命名变量 Y 为 Z，使其符合 Clean Code 原则。"

最终检查清单： Spec 已更新且提交？ -> 自动化测试全绿？ -> 代码无明显安全漏洞？ -> 合并代码

原文

源链接