给编程智能体划清实现与发布权限
作者以 Claude Code 修改产品搜索页为例,介绍如何用固定规则约束智能体交付。核心做法是让智能体调查后给出建议,并将批准实现与批准发布设为两次独立决策。
AI 深度解读
让 AI 写大部分代码之后,工程师每天还要做什么?作者用 Claude Code 开发产品搜索页,把答案落在一组具体规则上:人决定做什么、是否发布,Agent 负责实现,也负责提交截图、测试结果和变更记录。速度可以交给工具,验收标准仍要由人确定。
这套做法值得看的地方,是它把「相信 Agent 做对了」拆成了可以检查的证据。从小屏按钮是否可见,到合并的代码是否就是 CI 检查过的那一份,许多检查成本很低,却能挡住容易漏掉的问题。
批准开始开发,为什么不能等于批准发布
作者提到,Claude Code 最近几周承担了搜索页的大量开发工作。有一天,它向开发环境交付了四项独立改动:筛选条件与搜索纯文本视图的组合方式、两处视觉修复,以及适配较小笔记本屏幕的布局调整。
作者没有亲自编写这些改动,但保留了两次决策。
第一次发生在调查之后。Agent 给出推荐方案,而不是罗列所有可能性,然后等待作者决定是否开发。第二次发生在实现和检查完成之后,作者看过结果,再决定是否发布。
同意一个想法,不等于同意最终实现。
这两个停顿对应不同的信息条件。开发前,人判断需求值不值得做;开发后,人才能判断结果是否符合预期。少了第二次确认,最初的一句「可以做」就可能被延伸成对全部实现细节的认可。
作者还要求每个 PR 只包含一项改动,即使一天有四项也分别提交。文件按名称暂存,不使用覆盖全部文件的 git add,避免临时文件和实验代码混入。提交信息描述用户感受到的变化,便于出问题时定位并回退一个独立 PR。
UI 改好了,拿什么证明
作者的标准很直接:视觉改动先进入本地预览,推送前提供截图。文字描述只能说明 Agent 认为自己完成了什么,截图才能让人检查实际结果。
搜索页的一次布局修复很有代表性。较矮的笔记本窗口中,搜索表单旁的面板把 View Results 和 Download 按钮挤出了屏幕。修复后,数量信息固定在顶部,按钮固定在底部,只有中间的详情区域滚动。
Agent 检查了几组尺寸:
- 在
1366 × 640下,按钮底部距离窗口底边还有24像素。 - 在更矮的
1366 × 560下,按钮仍然可见。 - 在
1440 × 1000下,内容无需滚动,页面外观也没有变化。 - 平板和手机宽度采用另一套布局,需要分别检查。
它还在每个尺寸运行小脚本,查找容器中的横向溢出。原文没有提供脚本实现,因此可以借鉴检查目标,不能直接复用工具。
这里最实用的做法,是提前指定哪些屏幕尺寸必须通过,再把截图纳入完成标准。否则,Agent 很容易在一个足够宽敞的窗口里确认成功,而真实用户面对的恰好是短窗口。
本地检查之外,部署后还要到开发环境复验。作者使用自己保存的搜索作为用例,同时限制 Agent 的权限:不碰生产环境,不冒用作者身份登录;会话过期就报告并等待;尽量只读,不修改真实记录,也不运行昂贵的导出。如果必须改动草稿搜索,先保存原状态,检查后恢复,避免自动化验证不断留下脏数据。
把容易忘的规则,变成每次都会执行的检查
作者要求 PR 的所有 CI 检查通过后才能合并,还要把合并动作绑定到被检查的提交:
gh pr checks "$PR" --watch --fail-fast
gh pr merge "$PR" --merge --match-head-commit "$HEAD_SHA"
关键在第二行的 --match-head-commit:如果分支后来又有提交,当前头提交与 $HEAD_SHA 不一致,合并就会失败。「CI 曾经通过」还不够,必须确认最终合并的是通过检查的那份代码。
检查失败也不能靠解释绕过去。要么修代码,要么公开说明测试为何过时,修改测试,并在 PR 中交代,不能悄悄放宽断言。
另一些检查更简单,直接把源文件当文本读取,用正则固定规则。下面这段用于禁止搜索页 CSS 出现十六进制颜色:
import test from 'node:test';
import assert from 'node:assert/strict';
import fs from 'node:fs';
const css = fs.readFileSync('resources/css/search.css', 'utf8');
test('colours come from design tokens, never hex values', () => {
assert.doesNotMatch(css, /#[0-9a-fA-F]{3,8}\b/);
});
要看的是 assert.doesNotMatch 那行,它检查文本模式,并不理解颜色用途。作者就遇到过一次:Agent 为滚动区域边缘添加 CSS mask,在渐变里用了 #000。该颜色不会直接显示,但仍触发规则,最后改成 black。
这说明自动检查确实替人抓到了一次违规,也暴露了它的边界:这段测试能禁止十六进制写法,不能证明所有颜色都来自设计令牌(design tokens)。
他们团队还检查面向用户的文字不能出现破折号或弯引号、发布说明长度不能超限,以及某个大组件不能继续突破行数限制。一次发布说明中的弯单引号也曾被拦下。
文档同样跟着 PR 走。每项用户可见改动都要附带一条产品内的 What's New,标题少于 70 个字符,摘要少于 260 个字符;内部产品文档则记录改了什么、为什么改、谁提出、代码在哪里。
最后是项目笔记。Agent 每次会话开始都读取已知陷阱。例如,测试搜索曾误用字段内部的示例名称,筛选器虽然显示出来,搜索却静默忽略它,结果数量看起来还很合理。笔记因此增加了「始终使用真实字段名」的规则,让一次踩坑能影响后续执行。
我的判断
我认可这套方法把验收要求变成可重复检查的方向。截图、提交绑定、文案长度校验和环境恢复,都能对应到明确的失败方式,团队也容易解释为什么需要它们。
但作者说这些规则不会明显拖慢 Agent,没有给出耗时、缺陷率或对照数据。这是几周使用中的经验,不能据此断言所有团队都能同时获得更高速度和更低风险。
有些规则也带着项目偏好。组件行数只能作为拆分提醒,文件短不代表职责合理;正则适合约束明确的文本格式,遇到复杂语义就容易误伤或漏检。已有 ESLint、Stylelint 等检查时,应先判断能否沿用,避免维护重复规则。
此外,绿色 CI、截图和小 PR 都不能替代对业务逻辑的理解。作者最后仍强调,自己必须能解释、调试和维护交付结果。护栏提供验收证据,最终责任仍然需要有人承担。
能拿来做什么
- 给 AI 编程任务写清两个决策点:先确认推荐方案,再根据实现和检查证据确认发布;调查结束时要求 Agent 给出明确建议。
- 为前端视觉改动维护一份必验尺寸清单,把短窗口、移动端布局和横向溢出检查纳入验收,并要求提交对应截图。
- 在 GitHub 合并流程中绑定已验证的提交;优先把文案长度、禁止格式等确定性要求变成自动检查,再逐步补充项目特有规则。
- 让 Agent 在同一个 PR 中补齐发布说明、内部变更记录和新增陷阱,并为开发环境验证约定状态保存与恢复方式。