程序员如何用 AI Agent 完成一个真实开发任务：从需求分析到代码审查

很多程序员已经用 AI 写过代码，但真正把 AI 用进开发流程时，经常会遇到三个问题：

• AI 能生成代码，却不理解完整需求；
• 单个文件看起来没问题，放进项目后却无法运行；
• 改动做完了，却不知道应该怎样验证。

原因并不复杂：我们把 AI 当成了“代码生成器”，而不是一个需要上下文、边界和验收标准的协作者。

这篇文章不讨论复杂理论。我们用一个真实、常见的小需求，演示如何让 AI Agent 参与需求分析、代码定位、方案设计、编码、测试和代码审查。

一、这次要完成什么任务

假设我们维护一个后台管理系统，产品提出了一个需求：

用户列表增加“账号状态”筛选，支持查询全部、正常和已禁用用户，并保证旧接口调用不受影响。

这个需求看起来只是增加一个下拉框，实际上可能涉及：

• 前端筛选控件；
• 请求参数；
• Controller 接口；
• Service 查询逻辑；
• Mapper 或 ORM 条件；
• 参数为空时的兼容行为；
• 自动化测试和回归验证。

如果只对 AI 说“帮我增加账号状态筛选”，它很可能直接猜项目结构、字段名和技术栈。正确做法是先让 Agent 调查，再让它修改。

二、第一步：把模糊需求变成验收标准

开始写代码前，先让 AI 整理需求。可以使用下面的提示词：

你是这个项目的开发协作者。先不要修改代码。

需求：用户列表增加账号状态筛选，支持全部、正常、已禁用，旧接口调用不能受影响。

请输出：
1. 你对需求的理解；
2. 需要确认的字段和接口；
3. 可能涉及的前后端模块；
4. 可执行的验收标准；
5. 存在歧义的地方，不要自行猜测。

经过整理后，验收标准可以变成：

1. 不传状态参数时，查询结果与改造前一致；
2. 传入“正常”时，只返回正常用户；
3. 传入“已禁用”时，只返回已禁用用户；
4. 非法状态值应被拒绝或按照项目既有规范处理；
5. 分页、关键字搜索和其他已有筛选条件仍然有效；
6. 前端刷新页面后，默认显示全部状态；
7. 后端测试和前端构建通过。

这一步很重要。没有验收标准，AI 只会判断“代码是否写完”；有了验收标准，它才有机会判断“需求是否完成”。

三、第二步：让 Agent 先调查项目

接下来不要急着修改代码，而是要求 AI 找到真实实现路径。

请在当前项目中定位用户列表的完整调用链，先只调查，不修改文件。

需要给出：
- 前端页面和请求方法；
- 后端 Controller、Service、Mapper 或 Repository；
- 用户状态对应的真实字段、枚举和数据库含义；
- 当前分页与筛选条件的实现方式；
- 可能需要修改的文件；
- 每个结论对应的代码位置。

如果项目中的实际实现与需求描述不一致，以代码为准并明确指出。

一个可靠的 Agent 应该通过搜索项目得到证据，而不是凭经验编造文件名。

调查完成后，我们重点检查三件事：

1. 状态字段的真实含义

数据库里可能使用 status、enabled、disabled_flag，也可能通过删除标记表达状态。字段值也未必是 0/1。

如果这里判断错误，后面的代码写得再漂亮也没有意义。

2. 查询条件放在哪里

有的项目在 Service 拼装查询对象，有的在 Mapper XML 中写动态条件，还有的使用 ORM 查询构造器。应该延续项目现有风格，不要为了一个小需求引入新的查询方式。

3. 旧调用是否依赖空参数

新增参数必须是可选的。不传参数时，不应该意外变成只查询某一种状态。

四、第三步：先设计最小改动方案

完成调查后，让 Agent 输出方案，而不是立即写代码。

根据刚才找到的真实代码，设计一个最小改动方案。

要求：
- 不改变现有接口路径；
- 新状态参数保持可选；
- 复用项目已有枚举和校验方式；
- 不进行无关重构；
- 列出每个文件的修改内容；
- 列出风险、测试点和回滚方式。

方案确认前不要修改代码。

一个合理的方案通常包括：

• 前端查询表单增加状态下拉框；
• 请求对象增加可选状态参数；
• 后端查询对象接收该参数；
• 查询层仅在参数非空时增加条件；
• 增加正常、禁用和不传参数三组测试；
• 对非法状态值复用现有参数校验。

这里的关键是“最小改动”。AI 很容易顺手重命名变量、抽取公共方法、调整格式，最终让一个简单需求变成大范围改动。任务提示中应该明确禁止无关重构。

五、第四步：分阶段让 AI 修改代码

不要让 Agent 一次改完整个项目。可以分成后端、前端和测试三个阶段。

阶段一：后端查询链路

现在只实现后端部分。

要求：
1. 使用刚才确认的真实状态字段和枚举；
2. 状态参数为空时不增加筛选条件；
3. 非法值按照项目现有方式校验；
4. 不修改无关文件；
5. 完成后说明改了什么，以及每一处改动对应哪条验收标准。

完成后先查看改动差异。重点检查：

• 是否把可选参数写成了必填参数；
• 动态条件是否判断了空值；
• 字段值是否与数据库实际口径一致；
• 是否影响原来的分页、排序和关键字搜索；
• 是否出现无关格式化。

阶段二：前端筛选控件

后端方案确认后，再实现前端状态筛选。

要求：
- 复用当前页面已有表单组件和字典；
- 默认值表示“全部”；
- 查询和重置行为与其他筛选项一致；
- 不改变现有页面布局风格；
- 不引入新的依赖。

前端最容易遗漏的是“重置”。下拉框可以查询，不代表功能已经完成。点击重置后，应清除状态参数并重新查询全部数据。

阶段三：测试与验证

请根据验收标准补充最小必要测试，并执行与本次改动直接相关的检查。

至少覆盖：
- 不传状态；
- 查询正常状态；
- 查询禁用状态；
- 非法状态；
- 状态与关键字、分页组合查询。

不要为了让测试通过而降低断言或删除原有测试。

六、第五步：不要只相信“测试通过”

AI Agent 经常会说“代码应该可以工作”。“应该”不等于已经验证。

我们需要它提供可检查的证据：

• 实际执行了什么命令；
• 哪些测试通过；
• 哪些检查因为环境限制没有执行；
• 是否出现警告；
• 是否仍存在未验证的风险。

可以使用下面的提示词：

请汇总验证结果，只报告实际执行过的内容。

按以下格式输出：
- 已执行的检查；
- 通过的测试；
- 失败或未执行的检查及原因；
- 仍需人工验证的页面操作；
- 不确定项。

不要把代码分析结果表述成已经运行通过。

人工页面验收仍然不可缺少：

1. 默认进入用户列表，记录总数；
2. 选择正常状态，确认结果中没有禁用用户；
3. 选择禁用状态，确认结果中没有正常用户；
4. 点击重置，确认恢复全部状态；
5. 组合使用关键字和状态筛选；
6. 翻页后确认筛选条件仍然生效。

七、第六步：让另一个视角做代码审查

编码完成后，不要只让原来的 Agent 总结自己的工作。可以重新开启一次审查，让它以审查者视角检查差异。

请对当前改动进行代码审查，不要修改文件。

重点检查：
- 是否完整满足验收标准；
- 是否破坏旧接口兼容性；
- 状态字段和枚举口径是否正确；
- 是否存在空值、非法值和组合查询问题；
- 是否有权限、数据越权或性能风险；
- 测试是否真正覆盖核心分支；
- 是否包含无关改动。

只报告能够从代码中证明的问题。每个问题给出文件位置、影响和修复建议。

审查结果也不能照单全收。AI 提出的每个问题都应该回到代码中验证：它究竟是真问题，还是不了解项目约定产生的误判。

八、一套可以复用的 AI Agent 开发流程

把上面的过程压缩后，可以得到一套通用流程：

需求澄清
  → 项目调查
  → 验收标准
  → 最小方案
  → 分阶段编码
  → 自动化验证
  → 人工验收
  → 独立代码审查
  → 交付总结

每个阶段都有明确产物：

阶段	应得到的产物
需求澄清	无歧义的需求说明
项目调查	带代码位置的调用链
方案设计	文件级修改清单和风险
编码	范围可控的代码差异
验证	可复查的测试结果
审查	有证据的问题清单
交付	改动、验证和剩余风险说明

九、使用 AI Agent 时最常见的五个错误

1. 一句话让 AI 直接开工

上下文不足时，AI 只能猜。先调查，再修改，通常比反复返工更快。

2. 一次修改范围太大

任务越大，越难检查。按后端、前端、测试拆分，出现问题时更容易定位。

3. 没有写明“不要做什么”

除了目标，还应明确禁止无关重构、禁止新增依赖、禁止改变接口兼容行为。

4. 把 AI 的总结当成验证结果

只有实际执行的测试和人工验收才算证据。

5. 不检查最终差异

无论使用什么 Agent，最终代码责任仍属于提交代码的人。合并前必须检查改动范围、关键逻辑和测试结果。

十、结语

AI Agent 的价值，不只是替程序员多写几行代码，而是把需求分析、代码定位、实现、验证和审查串成一条更高效的工作流。

真正决定效果的，不是提示词写得多华丽，而是有没有做到四件事：

• 给它真实的项目上下文；
• 用验收标准定义完成；
• 把任务拆成可检查的小阶段；
• 要求它为结论提供证据。

当你开始用“带一名开发协作者”的方式使用 AI，而不是把它当成代码补全工具，AI 才会真正进入你的日常开发流程。