项目实战：从需求到部署的 AI 交付闭环

AI Agent 能写代码，但项目交付不能只看代码是否生成。客户项目里真正重要的是：需求有没有被说清楚，设计有没有被确认，任务有没有拆到可执行，验收标准有没有落到测试，AI 的权限有没有边界，最终变更有没有经过 CI/CD、PR Review 和部署控制。

这篇文章用“客户后台新增订单导出能力”作为实战线，说明一条更稳的 AI 交付流程。它的目标不是把开发流程变慢，而是把 AI 的速度放进可验证的工程边界中。

业务需求：先确认真正要交付什么

客户提出“后台订单要支持导出”时，表面上是一个按钮，实际是一个业务能力。运营希望按时间范围、订单状态、支付状态导出明细，用于日常对账和异常排查；财务关心金额字段、优惠字段和支付渠道；安全团队关心是否会导出手机号、地址、用户备注等敏感信息；运维团队关心大数据量导出是否影响数据库。

需求阶段要先把这些角色的关注点拉到同一张图上，而不是直接让 Agent 修改页面。一个可执行的需求描述至少要说明：

• 导出服务于什么业务动作，例如每日对账、售后核查或活动复盘。
• 哪些角色可以使用导出能力。
• 导出范围是否跟随当前筛选条件。
• 第一版支持 CSV 还是 Excel。
• 哪些字段允许导出，哪些字段禁止导出。
• 数据量超过限制时，是提示缩小范围还是进入异步任务。
• 导出行为是否需要审计日志。

需求写到这个程度，才适合进入 Spec Driven 阶段。

Spec Driven：把需求、设计、任务和验收写清楚

Spec Driven 的核心是把“想要一个导出功能”变成 AI Agent 和人类都能执行的规格。规格不是长篇 PRD，而是一份能约束实现的事实来源。

在订单导出项目中，Spec 可以分成四块。

部分	内容	作用
需求	导出目的、使用角色、业务范围	避免只实现按钮，不满足业务流程
设计	页面入口、接口边界、权限点、字段白名单、同步或异步策略	避免 Agent 自行选择架构
任务	前端、后端、测试、文档、审计日志分别要做什么	让 Agent 按步骤执行
验收	成功路径、边界路径、失败路径、验证命令	判断是否完成

一份适合交给 Agent 的简化 Spec 可以这样写：

项目：后台订单导出

需求：
运营人员需要按当前订单列表筛选条件导出 CSV，用于每日对账。

设计：
- 页面入口放在订单列表右上角。
- 导出范围复用当前筛选条件，但不复用分页参数。
- 导出接口必须校验 order:export 权限。
- CSV 字段只允许：订单号、支付时间、订单状态、支付金额、支付渠道、优惠金额、收货省份。
- 禁止导出手机号、详细地址、用户备注和内部风控备注。
- 1 万行以内同步导出，超过限制返回明确错误。

任务：
- 前端增加导出入口、loading 状态、失败重试。
- 后端增加导出接口和字段白名单。
- 补充权限、字段、空结果、超量和失败用例。
- 更新项目文档中的导出能力说明。

验收：
- 有权限用户可以导出当前筛选结果。
- 无权限用户看不到入口，直接请求接口返回 403。
- 空结果导出生成只有表头的 CSV。
- 敏感字段不会出现在 CSV 表头和内容中。
- npm run test -- order-export 通过。
- npm run build 通过。

这个 Spec 的价值在于把 AI 的发挥空间限定在正确范围内。Agent 可以选择具体实现方式，但不能改变字段边界、权限要求和验收标准。

AI Agent：按 Spec 编码，而不是按感觉补全

进入实现阶段后，Agent 的第一步不应该是写代码，而是读上下文。它需要先理解订单列表页面、订单查询 API、权限工具、已有 CSV 工具、测试框架和项目命令。

Agent 的工作循环适合拆成六步：

1. 读取 Spec 和项目说明，确认任务边界。
2. 搜索相关代码，找到页面入口、接口封装、权限点和测试样例。
3. 形成短计划，说明会改哪些模块、先后顺序和风险点。
4. 按计划修改代码和测试。
5. 运行验证命令，根据错误继续修复。
6. 汇报 diff、测试结果和未覆盖风险。

实现过程中要避免两个常见问题。第一是“顺手重构”，例如为了加导出把订单列表查询逻辑整体重写；第二是“自作主张扩展”，例如没有要求 Excel 却新增复杂依赖。Spec 是 Agent 的工作边界，超出边界的内容应该先回到需求讨论。

Harness：把 AI 权限和风险控制住

Harness 是围绕 Agent 的工程化外壳。它决定 Agent 能读什么、能改什么、能执行什么命令，遇到哪些动作必须停下来让人确认。

订单导出项目中的 Harness 可以包括：

控制点	具体规则
文件权限	Agent 可以改订单模块和相关测试，不直接改生产配置、认证核心和部署密钥
命令白名单	允许运行测试、构建、类型检查，不允许直接操作生产数据库
字段检查	导出代码必须使用字段白名单，禁止从数据库对象直接序列化全部字段
风险拦截	新增敏感字段、修改权限模型、引入第三方存储时需要人工确认
日志要求	导出成功、失败、无权限、超量都要有可追踪日志

Harness 的重点不是“不信任 Agent”，而是承认 Agent 一旦有工具权限，就需要和人类工程师一样接受规则约束。权限越大，护栏越要具体。

CI/CD：把验证放到流水线里

本地验证只能证明某次执行环境下没有暴露问题。进入团队协作后，CI/CD 要把关键检查稳定地放到流水线里。

订单导出项目至少应该有这些检查：

• 编译或构建检查，确认变更可以生成生产产物。
• 单元测试和集成测试，覆盖字段白名单、权限、空结果、超量、失败重试。
• Lint 或格式检查，保证代码风格和基础质量。
• 安全扫描，检查依赖漏洞、明显的代码安全问题和敏感信息泄露。
• 产物检查，确认构建结果可追踪、可回滚。

一个简化的 CI 思路如下：

name: order-export-check

on:
  pull_request:
    paths:
      - "src/orders/**"
      - "tests/orders/**"
      - ".github/workflows/**"

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm run lint
      - run: npm run test -- order-export
      - run: npm run build

实际项目还可以加入 CodeQL、依赖扫描、容器镜像扫描、密钥扫描、SBOM 生成和制品签名。是否全部加入，要看项目风险等级，而不是为了堆工具。

PR Review：人工确认业务和风险

CI 通过不代表可以直接上线。CI 擅长检查可执行规则，但不擅长判断业务取舍。PR Review 应该聚焦在机器难以判断的问题上：

• 字段白名单是否符合客户业务和隐私要求。
• 权限点是否放在正确层级，是否只隐藏按钮而漏掉接口鉴权。
• 同步导出上限是否合理，是否会影响数据库。
• 错误提示是否能让用户恢复操作。
• 审计日志是否能支持后续排查。
• 这次变更是否超出了 Spec 范围。

PR 描述也要服务 Review。一个好的 PR 描述应该包含：关联 Spec、改动范围、验证命令、截图或导出样例、风险说明、未覆盖内容和回滚方式。这样 reviewer 不需要从零开始读完整个上下文。

部署：从合并到可控发布

部署阶段要回答三个问题：什么时候发布、发布后怎么观察、出问题怎么退回。

订单导出适合先灰度或通过 feature flag 开关控制。上线后观察导出接口耗时、失败率、超量次数、数据库慢查询、生成文件大小和审计日志。如果发现导出导致数据库压力上升，可以先关闭入口，再排查是否需要异步任务或索引优化。

部署不只是执行脚本。它应该包含：

• 环境审批，生产环境发布需要指定人员确认。
• 发布记录，明确版本、commit、PR 和构建产物。
• 监控指标，关注导出成功率、失败率、耗时和资源消耗。
• 回滚方案，能快速关闭入口或回退版本。
• 事后沉淀，把发现的问题更新到 Spec、Checklist 或 Harness。

一条端到端检查清单

客户项目落地时，可以用下面这张表检查交付链路是否完整。

阶段	必须产物	未完成时的风险
需求	业务目标、使用角色、数据范围	做出功能但不满足真实流程
Spec Driven	需求、设计、任务、验收	Agent 按猜测实现
AI Agent	可审查 diff、测试、验证结果	只生成代码，缺少完成证据
Harness	权限边界、命令边界、风险拦截	Agent 改动越界或触碰敏感操作
CI/CD	构建、测试、安全扫描、产物记录	问题进入主干或生产
PR Review	人工确认业务、风险和架构	机器通过但业务错误
部署	审批、监控、回滚、沉淀	上线不可控，事故难恢复

这张表可以作为项目启动会、PR 模板或发布检查的一部分。

总结

AI Agent 项目实战的关键，不是把“写代码”交给 AI，而是把完整交付链路工程化。需求给出方向，Spec 形成事实来源，Agent 按规格执行，Harness 控制权限和风险，CI/CD 做自动验证，PR Review 做人工判断，部署阶段负责观察和恢复。

当这条链路跑通后，AI 带来的速度才不会停留在个人效率层面，而会变成客户项目可以稳定复用的交付能力。

→ 回到专题首页