Spec Coding：端到端 AI Agent 打通需求到代码的最后一公里

Spec Coding，直译过来就是“按规格写代码”。但我更愿意把它理解为：把“需求到代码”这条最容易被模糊掉的链路，用一套端到端 AI Agent 应用真正打通。这个应用解决的是开发流程里的一个老问题——需求方心里想的、文档里写的、程序里实现的，经常是三个完全不同的东西。而 Spec 化的方式，等于在需求和大模型之间加了一层“翻译规约”，让 AI 不只是“猜你想写什么”，而是“按你规定的契约写代码”。

今天这篇稿子，我会把这款端到端 AI Agent 应用从立项思路、核心设计、工程实现到踩坑记录完整拆开，给想做类似方向或正在做 AI 编程工具的同学一个可参考的样本。内容偏向实操，不整虚的。

1. Spec Coding 要解的到底是什么问题

1.1 为什么不是“直接让 AI 写代码”

接触 AI 编程时间长了，你会发现在现有工具链里，“让 AI 写代码”这件事看起来很简单：把需求贴进对话框，回车，代码出来了。但绝大多数情况下，这种一次性生成的代码只能用于 Demo，很难直接进入生产链路。原因有几个：

• 需求描述天然是模糊的，模型只能猜，猜错了整个模块推倒重来。
• 业务规则散落在对话里，没有结构化沉淀，换个模型或换个人复现，结果完全不一样。
• 生成代码只解决“写”的问题，没有解决“写完后怎么验证、怎么保证行为符合预期”的问题。

所以我把思路改成：不在“需求”层面直接驱动代码生成，而是先把需求转成一份严格定义的规格说明书（Spec），再让 Agent 基于这份 Spec 去拆解任务、生成代码、编写测试、执行验证。整个过程由 Agent 端到端托管，人只在关键节点做确认。

打个比方：直接让 AI 写代码，像你跟代驾说“你看着开”；Spec 驱动，是给代驾一条精确到路口的导航路线，每个路口怎么转、遇到什么标志算走错，都有明确约定。最终得到的不是“一段能跑的代码”，而是“一段行为可验证、边界可检查的代码”。

1.2 端到端 Agent 的边界在哪里

很多人会把“端到端”理解成“从需求一句话到部署上线全部自动完成”。我不这么看。在我这个项目里，端到端的含义是：在“规格定义—任务拆解—代码生成—执行验证—缺陷修复”这条主链路上，Agent 全程自主闭环，减少人工中转。

参考一个实际过程：

开发者过去要做的是：读需求文档、建工程、写代码、跑测试、修 bug、写变更说明。现在我这边 Agent 做的是：接收 Spec 文件、生成任务清单、逐个实现模块、自动跑单测和接口测试、测试失败后自动定位并修复、最后整理一份变更摘要交给开发者审查。

人的角色从“执行者”变成了“审计者”。这也是我认为端到端的真正价值：它不是替代你的判断力，而是把重复劳动压缩到最低，腾出精力去处理真正需要经验的地方，比如规格边界是否合理、验收标准是否完备。

2. 核心架构设计与关键技术选型

2.1 整体方案：四段式流水线

我把这个应用拆成四个核心模块：

四个模块串起来就是一条完整的 Agent 流水线。这里有个容易被忽略的设计点：Agent 不是一次调用大模型完成所有事，而是多次调用、多轮反馈。每一轮目标都非常收敛，模型的任务越聚焦，输出质量越稳定。

2.2 Spec 不是文档，是数据结构

这是整个应用最核心的决策：Spec 到底是什么？我最终没有选择纯自然语言描述，而是用了一套 JSON Schema 来承载规格内容。原因很直接：自然语言在机器可读、可校验、可追溯方面都太弱了。

我的 Spec 文件长这样：

json复制{
  "id": "order_create",
  "title": "创建订单接口",
  "actor": ["customer", "inventory_service"],
  "preconditions": [
    "customer_authorized",
    "inventory_service_available"
  ],
  "flow": [
    {
      "step": 1,
      "action": "validate_request",
      "input": "request_body",
      "expect": "request_is_valid"
    },
    {
      "step": 2,
      "action": "deduct_stock",
      "system": "inventory_service",
      "input": {"item_id": "item_id", "quantity": "quantity"},
      "expect": "stock_deduct_success"
    },
    {
      "step": 3,
      "action": "save_order",
      "system": "order_database",
      "expect": "order_saved"
    }
  ],
  "exception_handling": [
    {
      "trigger": "stock_deduct_failed",
      "response": "return_409_with_message"
    }
  ],
  "acceptance_criteria": [
    "create_order_returns_order_id",
    "stock_deduct_is_atomic",
    "duplicate_request_returns_same_order"
  ]
}

为什么用结构化格式？因为后续 Agent 的所有行为都可以由这份数据驱动。生成代码时知道每一步的输入输出；写测试时知道期望行为；验证失败时能准确对应到某一步流程，而不是笼统地说“这块代码有问题”。

2.3 “先写测试，再写实现”由 Agent 自动执行

在传统开发里，TDD（测试驱动开发）是个好方法论，但执行成本高，很多人坚持不下来。在 Agent 应用里，这个问题反而不存在：测试生成、执行、反馈、修复都自动化。

我的实现顺序是固定的：Spec 解析完成后，Agent 先为每个任务单元生成测试用例，再生成实现代码，然后执行测试。测试是“裁判”，代码是“运动员”。如果测试没过，Agent 会读取失败堆栈，定位到对应实现代码，做定向修补，再跑一次。这个循环最多迭代 5 次，5 次不过就标记为“需人工介入”。

这套顺序带来一个额外的好处：代码覆盖率天然较高。因为测试在实现之前就写好，写实现时会天然遵循测试约束，不太会出现“写完整块业务代码但测试覆盖不到 30%”的尴尬局面。

3. 从零搭建完整实操流程

3.1 技术选型与运行环境

我只说通用方案，不绑定具体供应商：

• 基座模型：选择一个上下文窗口在 128K 以上、代码能力经过评测的中大规模开源模型，参数规模在百亿级左右就够用。太小的模型任务拆解能力不够。
• Agent 框架：基于开源 Agent 框架做二次开发，核心是支持多工具调用和长流程状态管理。
• 向量存储：用向量数据库存历史 Spec 和常见实现片段，做检索增强。
• 代码解析库：用通用的 AST 解析库来定位失败位置，不靠纯文本正则。
• 执行沙箱：代码生成后必须在隔离容器里运行测试，避免 Agent 生成的代码对宿主机产生副作用。

我实际的运行环境是一台 8 卡 GPU 服务器跑模型推理，加上一个 Kubernetes 集群跑沙箱任务。如果你只是做小型验证，用单卡加载量化版模型、加一个简单的进程级沙箱也够。

3.2 Spec 编写与审核：整套流程的地基

这套流程最考功力的地方不是写代码，而是写规格。规格写得好不好，直接决定 Agent 表现。

我踩过三轮坑之后，整理出写 Spec 的几个原则：

• 每个步骤必须有明确的“预期结果”。“调用库存服务”这种描述不合格，“调用库存服务后返回扣减成功”才合格。
• 必须覆盖异常分支。很多失败案例不是因为主流程写错，而是异常分支没约定清楚，Agent 自由发挥出了各种奇怪的错误处理。
• 验收标准要可执行。不要写“系统性能良好”，要写“单接口压测延迟 P95 小于 300ms”。

我们项目里“某订单模块”的 Spec 初稿写了 300 行自然语言，后来结构化重写后精简到 180 行左右。精简的是废话，保留的是可验证的行为约定。这个投入非常值得，因为后续 Agent 端到端跑通的耗时从平均 40 分钟降到了 18 分钟。

3.3 让 Agent 真正“读懂”Spec 的三个关键设计

3.3.1 用角色隔离区分“需求语义”和“实现语义”

我让 Agent 在读完 Spec 后，先输出一份“任务理解清单”，用两栏对照：左边是需求意图，右边是具体实现方案。这样能提前发现理解偏差，而不是等代码写完才发现跑偏。

举两个实际示例：

需求意图“用户只能删除自己创建的订单”，实现方案如果写成“前端隐藏删除按钮”就完全不合格，正确实现必须是“后端校验订单归属后再执行删除”。这个差异在过去都是靠代码评审发现的，现在 Agent 在任务规划阶段就主动暴露出来了。

再比如，Amount 字段的需求意图是“金额必须用分存储避免浮点误差”，实现时如果直接存 double 类型就会在累加统计时出问题。这些约束必须在 Spec 里写成“amount_type: integer_in_cents”这样的硬性规则，Agent 才会在生成实体类时严格遵守。

3.3.2 把幂等性做成验证器的内置规则

真实业务里幂等性非常重要。在 Agent 应用的验证执行器里，我专门写了一个插件：自动检查写接口是否实现幂等逻辑。

规则很简单：如果 Spec 中的步骤是“写入类操作”，而生成的代码在入口处没有幂等键查重逻辑，测试就无法通过。我遇到过 Agent 生成“创建订单”接口时把幂等键设计成了请求体里的用户 ID，这是错误的，因为同一用户可能重复下单。正确做法是用客户端生成的一次性请求 ID 做幂等判断。

这个内置规则帮我们拦住了很多线上才会爆发的严重脏数据问题。在一次压测模拟中，关闭幂等校验时重复请求产生了 137 条重复订单；开启校验后全部被拦截并返回原订单 ID。这个差异很直观。

3.3.3 对代码生成范围做硬性约束

我给 Agent 加了一条规则：只允许生成它当前任务单元需要的代码，禁止顺手修改其他模块文件。命令也很简单，在任务上下文中声明“你只能修改当前任务清单中列出的文件”。

这条约束很重要。早期版本里 Agent 在实现“增加订单状态字段”时，疑似顺手改掉了公共工具类的日期格式化逻辑，导致其他模块的测试全部失败。加了范围约束之后，误改他人代码的频率明显下降，整个流水线的稳定性提升了很多。

3.4 验证执行器的设计与失败反馈链路

验证环节是端到端闭环里最容易掉链子的地方。初版我直接让 Agent 跑测试，把终端输出原样丢给模型看。效果很糟糕，1000 行日志里大部分是无用的安装信息和警告，模型经常抓不住重点。

后来我把验证环节改造成结构化反馈，格式如下：

json复制{
  "test_suite": "order_create_test.py",
  "total": 12,
  "passed": 9,
  "failed": [
    {
      "case": "test_create_order_duplicate_request",
      "error_type": "AssertionError",
      "file": "app/services/order_service.py",
      "line": 87,
      "message": "expected order_id to equal previous order_id, but got a new one",
      "suggestion": "check idempotency key lookup before insert"
    }
  ]
}

这里的关键是 suggestion 字段，由第二遍轻量级模型分析失败堆栈后生成。这个设计让修复模型的工作量大减，不需要从头读一遍代码定位问题，直接拿着“哪个文件、哪一行、大概什么问题”去做定向修改。

实测下来，同样的失败信息，用结构化反馈时的修复成功率比直接丢原始日志高了将近一倍。这个比例后续成为整个项目最重要的质量指标之一。

4. 常见问题与排查技巧实录

4.1 Spec 编写不当导致的“连锁翻车”

这个栏目排第一个讲，因为它是所有问题的根源。典型情况：规格里写了“当库存不足时返回友好错误提示”，Agent 非常尽职地实现了提示信息，但完全没约定 HTTP 状态码，结果接口在异常时返回了 200。业务方拿到 200 以为下单成功，后面处理逻辑全乱了。

排查时看任务理解清单会非常明显：需求意图列写的是“提示用户库存不足”，而实现方案列写的是“返回 200 和错误消息体”。这个偏差在规划阶段就该被质疑。现在的流程里，我在审核清单中增加了“异常HTTP状态码约定”这一项，专门用来堵这类漏洞。

4.2 长上下文退化和检索增强的取舍

端到端 Agent 很容易踩的坑：上下文中既有整个工程的说明、又有十几个文件的内容、还有测试输出，模型在处理到后期时，经常会把早期指令“遗忘”掉。

最典型的表现：Agent 生成的代码风格前后不一致，前面用同步方法，后面忽然用异步模式；或者装饰器、日志规范、异常处理风格漂移。这不是理解能力问题，是上下文窗口太长后注意力分散。

我的解决方案是双管齐下：

• 在每一轮新任务开始时，重发“核心规则摘要”，做成“记忆锚点”，包含代码风格、命名规范、禁止触碰的文件列表。类似在长篇对话里定期提醒“别忘了主题”。
• 把大文件拆成按需检索的小片段：Agent 每次只读取当前步骤需要的文件，不一次性全量塞进上下文。

这里有人可能觉得“上下文窗口大就为所欲为”，我的经验恰恰相反：上下文窗口再大，也不如让它“少看、精看”。把上下文当成工作台而不是仓库。工作台上堆满零件，工作效率反而更低。

4.3 测试全绿但业务行为不对的隐形缺陷

项目后期我遇到一个很头疼的问题：所有自动测试都通过，评审也做了，但上线后业务方说“订单金额不对”。查了半天发现，Agent 在实现“优惠券分摊”时，对多商品订单将优惠金额平均分摊到每个商品上，而不是按商品金额比例分摊。

测试之所以全绿，是因为测试用例里写了“订单只包含一件商品”，这种情况下两种分摊算法结果完全一样。这是典型的“规格盲区”：我作为需求方没有在验收标准里写明“多件商品按比例分摊”，Agent 就挥了常理判断的自由。

这个问题的解法很朴素：验收标准里加一条“包含一件商品和包含多件商品分别给出预期计算和字段断言”，让测试用例覆盖真实业务条件。同时我在流程上增加一个强制步骤：Agent 提交实现后，必须列出“哪些边界条件我没有验证”。这个强制反思让很多潜在缺陷在开发阶段就暴露了。

4.4 模型生成不稳定？给缓存和限流留好余地

你会发现在高并发调用时，同样的代码生成请求，质量波动比想象中大。这通常不是模型本事的波动，而是推理服务在繁忙时的超时和低优先级任务抢占。

我的处理方式：对不敏感的任务步骤用低规格模型做首轮生成，再由高规格模型做代码审查和修正。成本节省明显，速度和质量的平衡也比较理想。这个经验在项目规模扩大后尤其有价值。

5. Spec Coding 的适用场景与扩展边界

5.1 哪些场景收益最明显

根据我跑了多种类型项目的观察，以下几类场景是收益最大的：

• 业务 CRUD 接口开发：结构高度相似，但内部规则千差万别，非常适合 Spec 化。
• 跨系统对接：因为每个对接方的协议、字段、错误码都可以写成严格 Spec。
• 测试数据与模拟器生成：从数据结构定义直接生成 Mock Server，省时省力。
• 代码迁移和规范化重构：旧逻辑按新 Spec 重写，行为对比靠测试断言完成。

在这些场景里，Spec 所带来的“契约感”能显著降低返工率。一次对比数据：类似的用户鉴权模块，传统人写从设计到联调耗时约四个工作日，Spec Coding 端到端流水线加人工走查，实际耗时在一个工作日内完成，代码覆盖率还高出不少。

5.2 哪些场景目前不太行

也不是所有领域都适合。比如高度依赖产品审美和创新交互的前端界面生成，Spec 化很难明确定义“这个按钮看起来要高级”，这类偏主观体验的领域，Agent 的自由发挥反而更重要。

再有就是性能调优场景。Spec 可以定义性能目标，比如“接口 P95 小于 300ms”，但定位性能瓶颈需要大量上下文感知和实验验证，目前端到端 Agent 很难自主完成这类排查闭环。

5.3 后续扩展的可行方向

我会继续在三个方向上迭代：

• 把 Spec 从手工编写升级为“半自动生成”：让 Agent 通过阅读历史代码、接口文档和生产日志，自动提炼出初始 Spec 草案，人来审核修正。
• 引入更细粒度的验证能力：不只是单测通过，还要做接口契约测试、数据库迁移检查、依赖安全检查。
• 把 Agent 的“决策轨迹”沉淀成数据资产：每一次规格到代码的转化过程，都可以变成新的训练/评测样本，反过来优化整个流水线。

这个思路其实不止是写代码，它可以延伸到任何“从规范到交付物”的自动化场景里。我个人判断，未来各行业都会有类似 Spec 化的 Agent 框架：先定义可验证的契约，再让 AI 去履行契约。

最后聊点实在的个人体会。开发这个端到端 AI Agent 应用的过程中，我最大的感受是：难点从来不在“调模型”，而在“定义问题边界”。把业务需求变成严格的、可验证的规格，这件事本身就是最大的杠杆点。规格写得好，后面所有环节都会顺；规格模糊，再强的模型也救不回来。如果你也想自己做类似工具，建议从手头一个边界清晰的业务模块开始，先写一版结构化 Spec，再训练你的 Agent 去端到端走完整个闭环。跑通一次之后，你会对“AI 编程”这件事有完全不一样的理解。