第一条：把干活的那个「人」固定住

一次评估或部署周期里，模型、编码 Agent 的运行时、原生工具接口三样锁死不动。这三样里任何一样变了，就算换了一代，整套环境要重新验收一遍。

锁住黑盒的收益是失败变得可归因。一个明明很能干的 Agent 干不成一件活，原因通常落在五处：缺相关的机构上下文、缺一个真能用的能力、缺有用的反馈回路、缺权限，或者出口处缺证据。这五样都是部署环境的属性，都能查、都能改。不锁黑盒，你就永远卡在「到底是模型不行还是我没配好」之间打转。

换代能带来多大差别，有两个数字。GPT-5.2 发布的时候他正在休假，回来发现团队在没有任何额外环境投入的情况下，每个工程师每天多产出一到两个 PR。后来一次单独的 Symphony 环境改造，报告的是每个工程师每周 PR 数量十倍的增长。前一个来自模型换代，后一个来自环境改造，两者要分开记账，这正是锁住黑盒的意义。

内循环的延迟也属于验收范围。Agent 能推理到什么程度，取决于它在这一趟（一条轨迹，就是 Agent 干一件活从头到尾的整个过程）跑散之前能拿到多少反馈。GPT-5.2 时代的 Codex 环境没有后台 shell，Agent 会老老实实等阻塞的构建脚本跑完；GPT-5.3 加了后台 shell 之后它就不愿意等了。团队用一周时间把仓库的构建从自己写的脚本一路换到专业构建工具（先后试了 Bazel、Turbo、Nx），停手的条件是全量构建进一分钟以内。这一分钟被定成硬上限，一旦破线就停下手上的活去拆构建图。

验收还包含减法。为了让 Agent 看见界面，团队曾经自建过一套虚拟显示加录屏的东西；模型自己能看屏幕、点鼠标的能力（computer use）出来之后，这一整套被删掉了，端到端的验证并没有因此丢失。

第二条：部署进私有流程数据的水下部分

通用模型的权重里装着的，只是一个组织知识的尖。水线以下才是干活真正要用的那些东西，而且它们是私有的、一直在变的。

这一条要求把两套东西说清楚。一套叫数据本体：有哪些实体、指标、标识符，它们之间什么关系。另一套叫工作本体：有哪些结果、工作流、角色、工具、例外、证据和授权关系。

有个例子很能说明问题。一个内部的数据 Agent，光给它数据仓库的权限是不够的，它解决不了「收入」和「活跃用户」这两个词在公司内部互相打架的定义。它还需要知道公司有哪些产品线、客户怎么分层、有哪些团队、哪些客户在试点、当前的计划是什么、共享的指标定义是怎么写的。有了这些关系，它才能给出一个属于这家公司的答案。

组织形态上有一个可以直接抄的做法。Basis 这家公司有两个仓库：Arnold 是生产用的单体仓库，Atlas 是第二个仓库，专门放公司的上下文，在生产代码树之外。Codex 可以把个人笔记、公司运营知识和生产代码组合起来用，而这两批信息各自保留独立的更新路径。实现形态可以很朴素，他的原话是「就是 Codex 加一个装满 Markdown 的 Git 仓库」。

还有一件事属于这一层：稳定下来的决策要提拔到它管得着的那一层去。某个团队和安全部门一起选定了一个批准使用的加密实现，这个决定留在了 Slack 里。后来一位新工程师用 Codex 干活，Codex 装了另一个 npm 加密包。团队把这个决定捞回来，在仓库里写成守卫规则，然后重新跑了一遍那次改动。

第三条：一个 Agent 领整件活

委托的是结果，交给一条主轨迹全权负责：拆解、执行、整合、举证、安全收尾。步骤留给它自己定。人只在三个地方出手，方向、判断，以及有后果的授权。

他经常给接近零约束的提示词，把这种提示词叫做「懒 prompt」，懒在方法留白，怎么做由 Agent 自己定。稀疏的委托同时是一种测试手段：它测的是你的环境有没有让真实要求变得能被 Agent 自己找回来。Agent 一旦会错意，暴露出来的正是环境里哪一块没做出来。配套的循环是「提出、观察、改进、重跑」：看完轨迹，改环境，把这次的结果丢掉，重新跑一遍。

两个反例，比正例更有用

一句请求通常只说功能结果，兼容性、可维护性、无障碍、回滚、生成物同步、以及未来改动的需要，全是隐含的。这些隐含要求有个名字，叫「问题背后的问题」。Agent 要自己把它们找回来：去仓库里翻、看当前行为、查历史记录、弄清这个结果和用户的关系。刨不出来，而且缺的这个答案会改变产品意图、会让人承担没预料到的风险、或者需要它没有的权限，这时候才问人。

第四条：一千页手册，换成一张索引

知识库要大而可搜，工作集要小。根部的那份指引应该是一张地图。

这一条有个来历：他们最早那份单体的 Agent 手册，长到没法用了。换成一个简短的根目录索引，背后挂着编好索引的设计文档、产品规格、执行计划和参考资料，把渐进式披露做成仓库自己维护的一个特性，再用链接检查和新鲜度检查保证这些路由可信。

上下文窗口变大，解决的只是容量压力。注意力、检索质量、指令之间互相打架、以及「这一步到底哪条事实要紧」，这几样仍然稀缺。确定性地往上下文里塞东西，在跨越多次压缩之后必然失效。Agent 必须有能力再次找回那条路，指望第一次塞进去的东西还在，是靠不住的。

怎么验收一份知识库

开一个全新的会话，看 Agent 会不会真的检索到它、并且真的改变行为。文档存在，只证明它被写过了。再往前一步是消融测试：把这条上下文拿掉再跑一遍，效果扛不住的，删掉。

这个仓库自己就是这一条的样品

四条可以自己核对的结构事实：

未解决的那个决策决定走哪条路由。目标系统本地的证据可能不需要其中任何一条就解决了它。确实需要上下文时，从其中一条开始，只有在另一个独立的决策仍然悬着的时候，才加第二条。 AGENTS.md，仓库根目录

第五条：工具吐出来的每个字，都是下一步的上下文

一个能力真正可用，要走完六步：发现它、认出这次该用它、正确调用、看懂返回的结果、出错时能修、最后在真实系统里确认效果。任何一环断了，这个能力就是摆设。

解读结果这一步如果发现出错，回到修复，再重新调用，形成回环。

选 MCP 还是选普通命令行，取舍在两件事上。MCP 服务器能立刻广播工具名和输入格式，但模型仍然要现学每个新调用和返回的形状；普通的 POSIX 命令能吃到模型很强的先验，可是在 Agent 知道它装了之前，它是隐形的。有个真实的迁移：团队最早用 MCP 让 Codex 通过 Chrome DevTools 协议连自家的 Electron 应用，后来同事换成一个本地的 TypeScript 守护进程加一个小命令行，因为实际只需要两三个操作。换完之后工作流没有中断。

好工具的七条行为

一个所有人都会踩的坑

有一种失败长得很好认：Agent 会预防性地把一条昂贵的命令，比如 cargo test，用管道接给 head 或者 tail，想少读点输出。

解法不在提示词里，在工具边界上：由仓库自己拥有的一层包装，完整跑一次任务，保留真实的退出状态和全量输出，只返回下一步决策需要的那段语义化失败摘要，同时让底层证据可以被查询，不用重跑一遍。

缺什么就往下挖，挖到能用为止

把整件活交出去，会从外往里把能力缺口一层层暴露出来。原始目标是让 Codex 读 Slack、识别报进来的线上故障，这样就不用人把消息一条条粘进对话里。

这种能力搜索会向下递归六到八层。触底拿到一个可用的基础件之后，再一层层爬回最初那个故障分诊的目标。每一次这样挖一趟，往后所有 Agent 能干的活都跟着扩大一圈。反过来，用一次性的人工中转绕过去，等于把同一个洞原封不动留给下一趟。

第六条：代码就是提示词

Agent 读到的每一个文件，都在影响它下一步预测什么。原话是：仓库里的代码就是提示词。

模型脑子里装着几十种都说得通的做法。仓库的作用是剪枝，用反复出现的结构，把团队选定的那一种挑出来。一致性直接压缩上下文需求：一套可观测性方案，Agent 在一个文件里学到的东西能迁移到全仓；六套方案，它每到一个调用点都得重新研究这里该用哪一套。

反面同样成立，例子传播缺陷和传播好判断一样快。半截子的迁移会造出两套互相打架的提示材料；一个写得不好的辅助函数，会扩散到每一个需要类似行为的包。

一个概念，只认一个出处

在造一个解析器、清单类型、版本常量、状态表示、夹具构造器、策略检查或者命令之前，先找这个概念现有的出处，需要时扩展那个接口。下面这些是「没有明确出处」的信号：

每一处重复的出处，都在制造一个「本地看起来也说得通」的续写方向。Agent 可以忠实地跟随身边每一个先例，同时让整个仓库变得更不连贯。

第七条：能做和能批是两份合同

能力说的是怎么造成一个效果。权限说的是哪个身份、可以对哪个资源、在哪个环境、造成哪个效果、持续多久、需要谁批、怎么回滚。

拆开这两份合同之后，安全问题从「要求一个随机系统零错误」转向「后果有多大、能不能恢复」。凭据的托管要放在轨迹之外：一个代理进程在动作边界处，从安全存储里取出范围很窄的密钥，让 gh 用起来像一条普通命令，而密钥从不进入模型上下文，也不进仓库。再加两层保险：只读身份让检查有用但不能改动；端点绑定的访问可以单独关掉某一条面向 Agent 的通道，不必轮换底层凭据，正在运行的轨迹也能被撤权。

有后果的操作分阶段，每阶段只给那一段需要的权限

Loki 是他家里的一台扫地机器人，跑开源的 Valetudo 固件，唯一的远程访问通道是一个自定义的 Tailscale 守护进程。要把这个守护进程从 v1.90.8 升到 v1.96.4，麻烦在于：升级它本身，可能毁掉你用来抢救失败部署的那条路。

指令也要透过这份授权合同来解读。「合并」的意思是走完仓库受保护的合流流程，它不隐含授予绕过的权限。「准备一次部署」授予的范围到准备为止，生产切换要另外批。当一个不可逆的目标或者范围在查过本地策略之后仍然含糊，Agent 应该在跨过那条边界之前先问。

稳定下来的授权规则应该落进身份策略、类型化的领域操作、有范围的工具、环境边界、测试和合并闸门里。在后果值得的地方，把错误的动作变成不可用的，比写一条规则更管用，规则要靠人时时记着，机制不用。

第八条：一个绿勾只证明它自己那一条

验证要发生在用户、操作者或者下游系统真正依赖这个结果的那个边界上。单元测试、类型检查、代码检查、构建，确立的是内部属性，它们证明不了外面那件事。

这一条落地时最有用的是一张对照表：你的结论是什么，证据就得取在哪个边界。

这张表对非工程的活同样成立。当中间的代码留在 Agent 的执行过程里、用户根本不看时，证明包要用用户听得懂的话来说：一个表格公式、一页渲染好的幻灯片、一条带出处的结论、一次完成的状态流转。隐藏脚本的测试通过，只确立了内部属性。

还要把真实系统交给 Agent 自己看。它应该能启动应用、驱动浏览器、读日志、查指标和链路、检查持久副作用、比对生成语料、观察持续集成和部署。人不该去中转 Agent 本可以直接看的证据，中转既增加延迟，又把诊断需要的状态剥掉了。语义视图和渲染视图要一起用：DOM 快照和结构化状态适合看角色、值和关系，截图、录像或者直接的屏幕操作才能暴露布局、裁切、焦点和交互缺陷。

说清楚证据没有证明什么

前面那个安全公告的案例，报告里明确写了：触发数据损坏需要一个自定义的哈希实现，外加在程序崩溃之后继续恢复运行，这个复现器并没有证明默认路径上存在内存不安全。当时的指令是每个上报的问题都要证明影响或者可利用性，长得像安全发现的推测性输出不算交差。

举证的负担随后果放大。一个错别字、一次解析器迁移、一次远程升级、一次生产发布，需要的证据和权限完全不在一个量级。

第九条：纠正过一次的事，不该再纠正第二次

重复出现的纠正要转化成塑造下一次运行的环境。这一条决定了前面所有条能不能随时间累积。

先看一个精确的反例。有人给了 Agent 一个具体的 Go 接口修正：原本函数只回一个「成没成」，改成回一个能说清「为什么没成」的具体错误值。Agent 只改了被点名的那一个函数。那条指令背后是一条关于接口设计的普遍原则，但这次修复没有去搜同一原则管辖的其他实例。

碰到反复出现的纠正，按系统问题处理，走五步。

改在哪一层，取决于这条教训有多成熟、后果有多大。

判断力怎么变成资产，有一条完整的链子

起点是一个提交到公开 openai/codex 仓库的 PR：升级 pnpm 修掉几个漏洞，并且禁止安装后自动执行脚本。从这个补丁往回倒推，能还原出四条原则：包管理器是高风险边界、依赖要保持更新、安装过程不该在持续集成里执行任意代码、例外需要人工审查。

值得注意的是第二次提拔。扫描器上线之后，Slack 上的反馈显示它更容易抓到一个个具体实例，抓不到那位安全工程师脑子里的通用参考框架。团队把缺失的守卫和调查信号补进 SECURITY.md，这份原则随后同时喂给每日扫描器和新增的依赖深度、许可证扫描器。判断力就是这样一轮一轮攒起来的。

第十条：守住连贯性，扛住终身风险

实现变得廉价之后，稀缺的东西变成了未来的连贯性和长期所有权。每一个被接受的改动，都还在给共享系统添约束和维护义务。

这一条里有全篇最诚实的一段。那个五个月一百万行的内部产品，内部发布和采用证明策略在初创期是行得通的；但架构连贯性在「多年」这个尺度上会怎么演化，是原文公开承认的未解问题。

另一个诚实的地方，是他用自己的项目反驳了「Agent 能一口气啃硬活」这个印象。Artichoke 那次状态模型重构，一开始是一个 114 个文件、根本编译不过的巨型改动；后来摊成 50 个陆续合并的准备 PR，同期仓库里还落了 200 个其他 PR，之后又经历几轮大的整合尝试和运行时失败，才最终合进去。

改动的大小和运行时长，几乎说明不了一条安全路线是不是已经摸清了。区别在于路线本身确不确定。他给这个缺失的能力起了个名字，叫「害怕再来五十个 PR」：预判自己会在未来的改动上后悔到什么程度。他把这件事明确列为仍然没有解决的能力问题。

什么必须活过一次重写

实现本身是可丢弃的一次渲染，下面这六样才是要保住的：

Symphony 就是这么做的：它发布一份行为规格，别的团队可以照着产出各自独立的实现。这种形态被称作「幽灵库」，共享的是契约，不是代码包。

第十一条：已经定了方向的活，跑成常驻循环

有一大类工作方向早就定了，只是排不进日程：本地化、补埋点、依赖保新、删掉过时的兼容路径、修架构漂移、刷新生成的数据和文档。一旦想要的结果、举证方式、授权边界三样都清楚，这些活可以一直自己往前推。

判断一个循环能不能立起来，看它能不能回答五个问题。

「任务」和「目标」在这里要分开。「修好这个不稳定的测试」一个补丁就结束了；「让持续集成的 p95 延迟保持在 N 分钟以内」是一个目标，它会持续观察系统、生成并测试干预、必要时申请人的授权，还需要一个明确的退休条件。

还有一条关于紧急响应的主张：一次代码红警不该以指标转绿告终，它应该留下一个维护循环。响应过程中人学到了哪条不变量重要、哪些信号预示漂移、哪些干预管用，这些应该连同目标、传感器、被授权的动作、升级路径和这个循环的主人一起记下来。因为 Agent 执行足够便宜，一些新发现的不变量可以在没有常驻团队的情况下继续被维护下去。

环境自己也会长草。文档变旧、代码长出互相打架的写法、评审意见暴露出缺失的守卫、某个曾经有用的工具在模型换代之后变成多余。OpenAI 那边用一组常驻的后台任务取代了原来每周一次的人工清理：扫描偏离既定原则的地方、更新质量评级、开聚焦的重构 PR、清理陈旧文档。小修补要在一个坏写法变成未来的提示材料之前就落地。

人的位置在这条里有明确交代：循环维护的是一个已经选好的政策与变化世界之间的关系，「哪个世界值得建」仍然是人的活。

第十二条：按实测的有效性优化

token、代码行数、Agent 数量、检查项，这些都是输入。要优化的是每单位稀缺的人类注意力换来的、被接受的结果。

token 排行榜是其中一个虚荣指标：它奖励的那个信号，在价值原地踏步的时候照样往上涨。「每工程师每天十亿 token」这个说法后来被补上了一道结果闸门，这些活必须合进主干并且改善用户体验才算数。

三个概念要分开：可达性Agent 能碰到这份活的多少部分。仓库、本地应用、测试、浏览器、日志、部署、举证，都在扩大可达性、活动量（token 和忙碌时间）、以及有效利用率真正抵达一个被接受的结果、或者产出了可复用证据的那部分活动。可预防的丢弃、返工、修复都在削减它。

四个时钟必须分开计

为什么必须分开，两个例子摆在一起就清楚了。那次 60 小时的重构，实际耗时很长，跨了三到四天，但和人的同步接口小到只有初始提示词加两次追问，消耗约 3.3 到 3.5 亿 token、2800 美元，产出一个 PR，他估计自己手做要三周。对照 2023 年那次和 ChatGPT 的结对：代码在编辑器和浏览器之间来回复制，测试结果人肉转述回聊天框，一次会话几百个提示词，实际耗时并不长，但人的注意力一小时就被榨干了。

探索、返工、浪费是三件不同的事

丢弃可以是有生产力的。在一个最终接口形状还没定的高不确定性重构里，他会让 Agent 产出一个可能到五万行的探索性改动，推成 PR 好让人检查，然后扔掉。这次尝试暴露了 Agent 大概会在哪里失败、以及最终切换需要哪些接口缝。他把这张失败地图变成大约十五个准备和铺垫的 PR，然后才回来做真正的切换。

怎么把这十二条用到自己的项目上

仓库的 playbooks 目录给了一套可以直接照做的流程，针对一件有边界的、能重跑的真实任务。

第五步的「全新」是有讲究的：要用新会话和一个隔离的、等价的起始状态，这样重跑不会从当初那次实现对话里继承到隐藏的帮助。还要单独确认这次干预到底有没有被检索到、有没有被调用、和这次重跑有没有关系。一次成功的结果，对于一条从未被用到的指令或工具，不构成任何证据。

下面三份模板可以直接抄进你自己的项目。

目标系统与版本：
相关外部状态：
锁定的模型与编码 Agent 配置：
代表性任务：
可接受的结果：
能证明这个结果的证据：
权限范围与审批边界：
预算与停止条件：
怀疑缺在哪：

如果在【最早管得住它的地方】加上【某项改动】，那么固定住的 Agent 在【代表性任务】上会出现【可观测的行为变化】，因为【机制】。

能支持这个假设的证据：
能削弱这个假设的证据：
预计的维护成本和归属：

任务与可接受结果：
目标版本与外部状态：
锁定的 Agent 与权限范围：

基线证据：
最早断掉的那次交接，以及它归谁负责：
改动与预期机制：
做了哪些验证：
全新重跑的证据：

结果对比：
证据对比：
人工中转与延迟对比：
风险与维护成本对比：
如果做了「拿掉它再跑一次」，结果是：

决定：保留 | 修改 | 移除
长期归属与记下的教训：
后续动作或退休条件：
已知的局限：

什么情况下你的对照实验不作数

还有一份单独的作废清单。命中其中任何一条，这次评估就支撑不了它想要的结论。

十二条分三层：三条划边界锁定能追责的环境，六条是天天要拧的操作杠杆，三条决定这套系统会不会随时间越用越值。锁边界是起点，模型换代、Agent 配置换了，整套环境都要重新过一遍，不然一个任务干不成，分不清是模型不行还是环境没配对。

仓库里的代码就是喂给 Agent 的提示词，一套写法反复出现，Agent 就照着抄；两套写法并存，两套都会被复制。纠正也一样，一次点名式的修正如果只改了被指出的那一处，同类问题会在别的地方原样再犯一次。

正文另配三份可以直接抄的填空模板，还有一张判断「这次的对照实验算不算数」的九条清单。

下面这些数字都是 Ryan Lopopolo 自己项目里的实测，没有第三方复核过。