Skip to content

Agent 时代的软件工程实践 ​

WARNING

🧪 Beta公测版本提示:教程主体已完成,正在优化细节,欢迎大家提Issue反馈问题或建议。

上一章讲到,Agent 时代人的输入是「一句意图 + 验收标准」。本章把这句话拆开:规格怎么写、验收靠什么、审查审什么、仓库为谁优化。这不是未来学,而是当下正在发生的实践重组。


一、规格驱动开发:规格成为新的源代码 ​

传统流程里,需求文档写给利益相关者看,代码写给机器执行,中间靠程序员的脑子和无数会议来对齐。Agent 把这条链路压缩了:规格既是给人看的文档,也是给 Agent 的指令。

于是「写好规格」突然从大公司才负担得起的仪式,变成了每个开发者的日常核心动作。一份能驱动 Agent 的规格,至少要具备三条性质:

  1. 可测试——每一条都能变成一个可执行的验收判断。「页面要快」不行,「P95 渲染时间 < 200ms」可以。
  2. 无歧义——不留给人(或模型)自由发挥的暗门。「处理异常情况」是暗门,「余额不足时返回 402,重试不扣款」是规格。
  3. 分层——先说清「是什么、为什么」,再给实现约束。Agent 拿到方案层可以自由发挥,拿到约束层必须严格遵守。

图解说明:注意最后那条回流边——审查不通过时,第一反应应当是改规格,而不是亲自下场改代码。改代码只是修了这一次,改规格是修了未来的每一次生成。规格是这个流水线的「源代码」,代码降格为构建产物。

这个转变有个更深的含义:版本控制的重心从代码移向规格。代码可以随时重新生成,但「我们到底要什么、为什么」的决策史无法凭空再生。设计决策记录(ADR)的价值因此上升,这一点在 不变的内功 还会展开。


二、测试与验证:从回归防护升格为合同 ​

在 Agent 时代,测试的角色发生了质变。过去测试主要防「改 A 坏 B」的回归;现在它同时是三样东西:

  • 验收合同——Agent 完成的定义(definition of done)由测试给出,达标即交付;
  • 导航信号——Agent 循环里的每一次「观察」,读的就是测试输出。测试报错信息写得越精确,Agent 修得越快;
  • 安全网——人在审查前,测试是第一道客观防线。

由此推出几条非常实用的工程结论:

  1. 测试的可运行性比覆盖率数字更重要。 一条要手工配置环境才能跑的测试,对 Agent 等于不存在。pytest 一敲就跑、失败信息自解释,这样的测试才进入得了 Agent 的循环。
  2. 为验收写测试,而不是为代码路径写测试。 面向接口行为(给定输入、期望输出)的测试对生成的实现稳健;逐行贴着实现写的测试反而会锁死劣质实现。
  3. 建立分级验收。 快检查(lint、类型、单元)秒级反馈,驱动 Agent 高频迭代;慢检查(集成、端到端)低频触发,防止局部最优。反馈延迟直接决定 Agent 的迭代效率——这与 训练与推理系统 里「反馈回路决定算法选择」是同构的。
补充:evals 思想进入业务代码(点击展开)

模型团队评价模型用 evals(评测集):一组输入 + 期望性质,跑完打分。这套思想正在进入普通业务仓库——把「这段代码是否符合规格」也做成可重复执行的评测,Agent 每次改动自动跑一遍。区别只在于:模型 evals 评的是统计意义上的能力,代码 evals 评的是这一次生成的正确性。两者的共同底座是同一句话:你不能改进你无法度量的事物。当生成变得便宜,度量就是工程的主战场。


三、代码审查:从逐行到抽样 ​

Agent 一天产出几百行 diff,逐行人审既不现实也没必要——因为你审的不是「人的思路」,而是「生成的结果」。审查重心随之移动:

  • 审接口与不变量,不审实现细节。 函数边界、数据结构、错误处理约定是否被遵守——这些是规格层的东西。实现内部的写法,只要测试可信,可以抽查。
  • 审测试本身。 生成的实现和生成的测试可能「合谋」——测试写得刚好让实现通过。对策:测试用例由规格推导(或人审定)再交给 Agent,实现不得改测试。
  • 审风险面。 权限、并发、数据迁移、对外接口——出错代价大的地方,人逐行看;其余地方靠类型、测试和后续监控兜底。
  • diff 太大就拆任务。 一个 PR 装不下一次重写时,正确动作不是硬审,而是回炉拆成带验收的子任务序列。审查的粒度应该匹配人的注意力预算,而不是匹配 Agent 的产能。

四、为 Agent 优化仓库:AGENTS.md 现象 ​

2024 年以来,越来越多仓库根部出现 AGENTS.md 或 CLAUDE.md——给 Agent 的仓库说明书。本仓库的 AGENTS.md 就是一个真实样本,它给人类协作者和 Agent 用的是同一份文档:项目结构、命令、约定、坑。

这不是赶时髦。它的实质是:仓库从「给人读的代码集合」变成「人与 Agent 共享的工作环境」。由此,一批过去「最好有」的工程实践,变成了「必须有」:

实践过去的价值Agent 时代的新价值
一致的目录结构与命名新人上手快检索命中率高,Agent 少瞎猜
README / 架构文档降低沟通成本直接成为上下文的一部分
一条命令跑起构建与测试省配置时间Agent 循环的燃料——跑不起来就没有反馈
显式的约定(lint、类型、格式化)风格统一机器可检查的硬约束,违反即被循环捕获
敏感信息出仓(.env)安全合规权限边界——Agent 不该拿到的东西物理上拿不到

「Agent 可用性」(agent readiness)正在成为可维护性的新度量。一个测试齐全、文档清晰、约定机器可检查的仓库,Agent 在里面如鱼得水;一个依赖口口相传的仓库,Agent 寸步难行——而说实话,新人也一样。


五、流水线全景:一次真实的协作长什么样 ​

把前四节串起来,一个成熟的 Agent 时代开发循环大致是:

图解说明:人出现两次——开头定义规格,结尾审查验收;中间的循环没有人的参与,但每一步都跑在人铺好的轨道(仓库约定与测试)上。工程能力的重心,从「轨道上跑得多快」变成「轨道铺得多好」。

读完本章,进入 不变的内功:工具与流程都会继续变,什么才是值得长期投资的能力。

参考 ​

  1. Anthropic (2025). Building Effective Agents. 工程博客。
  2. Yang, C., et al. (2024). SWE-agent: Agent-Computer Interfaces Enable Automated Software Engineering. arXiv:2405.15793.
  3. Jimenez, C., et al. (2024). SWE-bench: Can Language Models Resolve Real-World GitHub Issues? ICLR.
  4. Nyman, J. & Lahtinen, T. (2025). Specification-Driven Development. arXiv:2505.2052.