你的编程智能体是一个从不阅读测试的初级工程师

基准测试数据讲述了一个奇怪的故事。在 SWE-bench Verified 上，多个运行相同底层模型（均为 Opus 4.5）的智能体产品——Auggie、Cursor、Claude Code——产出了截然不同的结果。尽管“大脑”完全相同，Auggie 在 731 个问题中比最接近的对手多解决了 17 个。差距在于“脚手架”（scaffolding）：智能体是如何被提示的、被赋予了什么上下文、可以调用哪些工具，以及在困惑时测试框架（harness）做了什么。模型是商品，围绕它的脚手架才是产品。

这是成熟的工程团队在十年前对初级工程师达成的相同共识。一个聪明的毕业生能交付价值，并非仅仅因为模型优秀，而是因为 README 是最新的，测试套件运行迅速，代码审查标准每次都能捕捉到那六个同样的错误，并且有人编写了说明约束条件的 CONTRIBUTING.md。剥离这些脚手架，同一个人产出的代码可能局部连贯但全局错误，破坏了团队甚至没想到要写下来的生产环境不变量。

从编码智能体中挤出真实生产力的团队已经注意到了这一点，并且正在为智能体做他们本应为初级雇员做的事情。而那些没有这样做的团队则在责怪模型。

几乎成立的入职类比

将“智能体视为初级工程师”的类比很有用，但值得认真对待而非随口一说。它成立的地方和失效的地方都极具启发性。

初级工程师在卡住时会提问。智能体则会根据训练数据自信地进行模式匹配，并编写出一个可以编译、运行但悄悄违反了他们无从知晓的速率限制的函数。有一个 2026 年 3 月的记录案例：一个 AI 生成的 Slack 清理任务冲击了 Slack 全局每秒一次请求的 API 限制，因为该速率约束在被编辑方法的局部作用域内是不可见的。代码写得很专业，但不变量存在于别处——在智能体从未读过的供应商文档的某个段落中。

初级工程师会阅读测试套件以弄清契约。除非被明确指出，否则智能体会忽略测试。智能体的默认行为是阅读你打开的文件，扫描几个邻近文件，然后开始打字。测试是可执行的文档；不阅读测试的智能体就像是一个还没意识到代码库有规范（spec）的工程师。

初级工程师在数月内积累隐性知识。到第六个月时，他们知道哪个目录是“闹鬼”的，哪个服务在周五不能重启，以及大家都在使用的那个三个字母的缩写与代码中的内容不符。智能体每次会话都从零开始。任何不在提示词、已加载文件或可发现的仓库结构中的东西，对它来说都不存在。这不是一个要修复的 Bug；而是一个需要围绕其进行设计的约束。

一旦你接受了这个约束，工程问题就变成了：对于一个每个周一早晨都重新开始工作的初级工程师，我会写下什么？

起作用的脚手架

看看那些交付了严肃的智能体驱动型工作流的团队所发布的最佳实践，同样的五种产物反复出现。

仓库根目录下的 CLAUDE.md 或 AGENTS.md。不是营销用的 README——而是一份简练的文档，用三句话说明架构，指向入口点，列出包管理器和构建命令，并标记智能体绝不能编辑的文件（生成代码、锁定文件、供应商依赖）。HumanLayer 团队的指南很直白：这是你仓库中对 AI 辅助开发杠杆率最高的文件，其中的每个 token 都在竞争智能体的注意力。保持精简。任何不属于项目通用的内容都应放在子目录文件或技能中，而不是根目录。

兼作可执行文档的测试。并非因为测试能捕捉智能体的 Bug——它们确实可以，但那是次要好处——而是因为测试是唯一能精确定义契约的制品，精确到智能体可以毫无歧义地满足它。失败的测试是智能体可以执行且不会产生误解的提示词。README 中一句“函数应优雅地处理空输入”会留下六种不同实现的空间，其中三种会破坏你忘记存在的调用方。

捕捉智能体常犯错误的代码审查准则。在不同团队中，失败模式往往集中在：缺失认证检查、吞掉实际错误的错误处理、没有退避机制的重试、调用智能体在旧训练数据中看到的已弃用的内部 API、看起来合理但全局错误的并发代码。如果你观察了一个智能体一周并看到了同样的六种模式，请将它们写成自动化检查或审查清单。这相当于每个团队都有、却假装不需要的“每个初级工程师在第一个 PR 中都会漏掉的六件事”清单。

说明代码库强制执行但未记录的不变量的架构文档。关于部落知识（tribal knowledge）的行业研究一致发现，默契的理解——而非技术设置——是新员工的主要生产力障碍。同样的部落知识差距也适用于智能体，甚至更糟，因为智能体无法询问隔壁桌的高级工程师。如果你的服务绝不能在请求处理程序内部调用数据库，请写下来。如果认证上下文必须显式传递，因为没有线程局部变量，请写下来。这种纪律并不是为了写作而写作；它是将部落知识转化为智能体可以加载到提示词中的内容。

快速反馈循环。缓慢的测试、编译和工具响应不仅让人类感到沮丧，还会彻底打断智能体的循环。一个在五分钟的测试套件上运行“测试-编辑-测试-编辑”循环的智能体会超时、丢失上下文或干脆放弃并开始乱猜。从智能体中获得真实生产力的团队在测试并行化、热重载和快速本地验证路径上投入了大量资金，因为他们必须这样做——智能体的循环对反馈延迟比人类更敏感。

测试优先提示词，限定范围的任务

有两种提示词实践可以弥补大部分差距，而这两种方法都直接源于你如何向一位还不完全信任的初级工程师下达指令。

第一：测试优先。给 Agent 一个失败的测试，并告诉它在不修改测试文件的情况下让测试通过。这会将 Agent 的解空间精确地约束在你所关心的契约中。它消除了“编写一个符合成功案例模式的函数”这种失败模式，因为现在的成功是由可运行的工件定义的，而不是一段散文式的描述。它还会产生审计追踪——失败的测试、通过的测试以及衔接两者的 diff。针对该 diff 进行的代码审查比审查从一段意图描述中实现的特性要快上一千倍。

第二：限定范围。今年早些时候的红帽（Red Hat）开发者指南清楚地说明了这一点——窄范围的提示词比宽泛的提示词能产生显著更可靠的行为，大多数生产环境中的 Agent 提示词聚集在 800 到 2000 个 token 之间是有原因的。一个读起来像初级工程师任务描述的提示词（“修改 lib/dates.ts 中的 formatTimestamp 函数，使其返回 UTC 而不是本地时间，并更新 services/billing/ 中的三个调用方”）远比资深工程师的直觉（“清理时区处理逻辑”）更可靠。前者没有给 Agent 创造范围的空间；后者则邀请它去重构你根本没要求处理的东西。

大多数团队需要的倒置思维是令人不适的。资深工程师会按照他们的思维方式进行提示——宽泛、直觉化，把无聊的决策留到以后。这对于 Agent 来说是错误的频率。正确的频率是你给第一天入职的新外包人员的简报：明确、有范围、且边界清晰。

无论如何都会上线的失败模式

有一类 Agent 失败是任何脚手架都无法完全防止的，识别出这一点是安全交付 AI 辅助代码的团队与不安全团队之间的区别。

3 月份的 Slack 速率限制事件是一个典型案例。代码在每个局部意义上都是正确的。它编译通过，通过了 lint 检查，处理了明显的边缘情况。它只是做了一个在系统层面并不成立的假设——假设它调用的 API 可以在紧密循环中被命中。Agent 在任何地方都看不到这个不变性约束。它只存在于供应商文档中、存在于两年前集成 Slack 的工程师脑海中，以及那个没有人接入开发环境的速率限制仪表盘中。

这就是“局部连贯但全局错误”的失败模式，在这方面，Agent 破坏力的潜力可靠地超过了初级工程师的类比。初级工程师会提问。而 Agent 提交了一个 PR，通过了另一位审查员不彻底的审查，然后合并了。生产环境报警了。

防御手段不是更多的提示词；而是假设局部代码没问题并查看其他地方的审查门槛。这次更改是否跨越了你之前划定的服务边界？它是否在从未调用过外部 API 的上下文中调用了外部 API？它是否触及了现有告警监控的路径？其中的每一个问题都是可以进行机械化编码的检查，并且能捕捉到无论模型变得多么出色， Agent 都会持续产生的失败模式，因为失败模式存在于 Agent 编辑的文件与该文件所属的系统之间的缝隙中。

最终变得至关重要的文档

在团队运行一个季度后，领导层会意识到一个值得落脚的点。Agent 的入职文档——CLAUDE.md、架构不变性文档、作为规范的测试套件、评审准则——结果证明正是下一位人类新员工也需要的文档。原本为了 Agent 的利益而将“我会告诉初级工程师什么”系统化的团队，最终得到的入职产出，让下一位资深新员工在入职第三天读完后，缩短了一个月的磨合期。

这并非巧合。Agent 提供的强制机制是，代码库中的部落知识必须变得显性化，因为 Agent 无法推断它。这是团队多年前就该应用在自己身上但却没有做的强制机制，因为部落知识的成本——研究表明每位开发者每月大约花费 23 小时在寻找知识上——是隐形成本，体现在每位新员工前六周损失的生产力中。Agent 让这种成本变得清晰可见，因为当文档缺失时，Agent 会大声地失败。

这两个结果是紧密相连的。一个将其 Agent 脚手架系统化的团队，会得到一个更高效的 Agent 和一个最终对人类有效的入职流程。一个将 Agent 视为模型问题的团队——追逐基准测试、在结果令人失望时更换供应商、调整 temperature 参数——则两者都得不到。模型现在已经成为通用商品。脚手架才是产品。而这些脚手架看起来非常像每个团队早已知道自己需要的工程卫生习惯，只是因为某个没有耐心的东西最终提出了要求，它们才终于被写了下来。