如何让你的编码代理在浏览器中检查其工作
内容提要
作者指出，编码代理常以测试通过宣称前端完成，却从未真正打开应用，导致控件重叠、状态未高亮、刷新后失效等问题。他主张将浏览器审查纳入“完成”标准：用 Playwright MCP 让代理启动真实应用，依据改动制定测试计划，检查最终结果而非仅点击动作，并区分 DOM 状态与截图证据。指令应分层，AGENTS.md 只写原则，详细流程放入按需加载的 skill。审查应由无历史的新代理独立完成，避免作者盲区。清理时只停止自己启动的进程。作者还开发了开源工具 katalepsis，将 Playwright 测试与自然语言检查生成可粘贴进 PR 的报告，模型不能自行判定通过，必须引用真实断言证据。
延伸解读
为什么测试通过不等于前端完成
文章指出，编码代理常以测试通过宣称前端完成，但测试只覆盖已写下的场景，无法发现控件重叠、状态未高亮、刷新后失效等只有打开应用才能察觉的问题。作者将浏览器审查纳入“完成”标准，要求代理启动真实应用，依据改动制定测试计划，并检查最终结果而非仅点击动作。这提醒读者，前端验证需要区分代码正确性与应用可用性。
指令分层：原则与操作手册分离
作者将 AGENTS.md 视为“宪法”，只写必须满足的原则，如用户可见工作未经浏览器验证不算完成；将详细流程放入按需加载的 skill，如如何启动应用、检查哪些状态、清理哪些进程。这样既避免每次任务都消耗大量上下文，又能在需要时提供完整步骤。读者可借鉴这种分层方式，平衡指令的普适性与具体性。
独立审查代理的价值与边界
作者强调，让编写代码的代理自我审查存在盲区，因为它基于自身对改动的理解制定测试计划，容易忽略未意识到的受影响路径。因此，审查应由无历史的新代理独立完成，仅获得原始请求、代码差异和审查技能，自行决定测试范围。文章举例：一个让 E2E 应用 URL 可配置的 PR，作者代理未发现种子数据仍硬编码旧端口，而独立审查代理在更换端口后发现了图片加载失败。这说明了独立视角能捕捉作者盲区，但并非替代人工审查。
工具化审查：证据而非断言
作者开发了开源工具 katalepsis，将 Playwright 测试与自然语言检查生成可粘贴进 PR 的报告。其核心设计是模型不能自行判定通过，必须引用真实断言证据，且断言需显示操作前不存在的内容。工具还区分 blocked 与 failed，避免预览不可用时误报失败。这体现了将主观判断转化为可验证证据的思路，但文章也指出工具尚未覆盖字段值、持久化、控制台网络等场景，需结合手动浏览器审查。
Q&A
为什么编码代理说前端工作完成了，但实际上并没有真正验证？
编码代理通常只运行格式化、类型检查和测试，测试通过就宣称“已实现并验证”，但从未打开应用实际使用。这会导致控件重叠、选中状态未高亮、刷新后失效等只有人眼才能发现的问题。
如何让编码代理用 Playwright MCP 在浏览器中检查它刚做的改动？
给代理配置 Playwright MCP 服务器，让它能打开 localhost、读取页面、点击输入并截图。然后要求代理根据代码差异制定测试计划，启动真实应用，执行计划并检查最终结果，而不是只确认页面加载。
AGENTS.md 和 skill 在给代理的指令中应该怎么分工？
AGENTS.md 作为“宪法”，只写简短、全局适用的原则，比如用户可见的工作必须在浏览器中验证。详细的操作流程放入按需加载的 skill（如 browser-review），这样不会每次任务都消耗上下文。
为什么需要独立的审查代理来检查前端改动？
作者代理有自己的“理论”——它认为改动影响了哪些代码，测试计划也基于此，容易忽略未意识到的路径。独立的新代理没有历史对话和作者偏见，能自行推断影响范围并测试，从而发现作者遗漏的 bug。
代理在浏览器审查后应该如何清理自己启动的进程？
代理应只停止自己启动的进程和容器，删除自己创建的截图、追踪等文件，不能使用 pkill node 或 git clean -fd 等粗暴命令。启动时记录 PID 和临时目录，清理时精确终止并删除，最后用 git status 确认工作区未受污染。
katalepsis 是什么，它如何确保模型不能自行判定检查通过？
katalepsis 是一个开源工具，将 Playwright 测试和自然语言检查生成可粘贴到 PR 的报告。模型只能调用 assert 等工具，assert 由 katalepsis 在浏览器中执行并记录断言 ID；模型调用 finish 时必须引用这些 ID，且 decideOutcome 函数会验证引用的断言确实通过、显示了新内容，否则判定为 blocked。
