从可观察的结果开始
编程 agent 可能在你决定好界面该做什么之前，就产出一个看似可信的界面。先定义一个小的用户结果：已登录用户编辑个人资料、保存、刷新后看到已保存的名字。这给实现与评审都提供了具体目标。
在简报中写清当前行为、期望行为与重要的失败场景，并指出承担该工作的现有模块。新增资料编辑这类请求应该指向认证层，而不是放任 agent 发明第二个用户存储。凭证不要出现在提示词与截图里——粘贴进去的 apps/web/.env.local 或会话 cookie 会成为对话记录的一部分。
一份可用的简报读起来像这样：“在账户界面中，让已登录用户编辑自己的显示名，并在刷新后看到它。auth 模块拥有用户记录；不要新增表。空名字、或指定了他人记录的请求，必须被拒绝。用 pnpm test 和窄屏下的一次手动保存来证明。”五句话，大部分猜测就消失了。
- 用户可见的结果，措辞要让你能在运行中的应用里核对它。
- 今天拥有该行为的文件或模块——以及应该保持不动的区域。
- 至少一个失败场景：一次未认证的尝试、非法输入，或一次重复的请求。
- 证明它的检查——一条测试命令、一个夹具，或一次明确的手动走查。
让仓库自己说明自己
写清楚如何运行应用、哪些检查是确定性的、归属在哪里执行。在 supastack 中，AGENTS.md 记录工作区边界，.ai/ 记录文件级决策。这些笔记最有价值的时候，是告诉下一位贡献者——无论是人还是 agent——某个实现为何存在，而不只是哪些文件变了。agent 设置指南展示了套件如何暴露这些材料，本地设置指南则是 agent 实际会照做的走查。
让 agent 在改动前先读相关代码。一次小改动通常只需要界面、它的服务端边界，以及围绕该边界的测试。加载整个仓库，不如理解那几个决定新行为是否正确的地方：归属检查、schema、权限。
当功能涉及配置时，点名文件而不是誊写内容——“把 key 加到 apps/web/.env.local”能让密钥留在磁盘上。同样的纪律适用于供应商控制台：描述目的地，不要粘贴凭证。
以小而可评审的变更推进
当一次变更只有一个负责方和一个可核查的结果时，agent 最可靠。“新增资料编辑”是可评审的；“改进账户区域”只会招来没人要求的重构。如果一个功能能拆成 schema 变更、服务端边界和一个界面，就把它们作为独立简报分别运行，每一步都让构建保持绿色。
每次让 agent 动手之前先提交或打检查点。干净的基线能把糟糕的产出变成一删了之的 diff，而不是一次考古发掘，也给评审留下稳定的前后对比。
一次评审一个完整变更
在改变行为之前先写验收检查。以资料编辑为例，覆盖一次合法更新与一次未授权尝试。构建满足这些用例的最小实现，然后用真实感的文本与窄视口检查实际交互。
既看结果也看 diff。留意重复的业务逻辑、过宽的异常处理，以及解决现有技术栈本已覆盖问题的新依赖。运行项目检查并记录它们证明了什么。浏览器夹具可以验证表单交互；它无法证明生产数据库或外部供应商配置正确。
每条命令回答一个不同的问题。pnpm test 用确定性的 fake 与本地适配器演练行为，pnpm check 覆盖 lint、类型检查与格式，pnpm build 暴露只在打包时才出现的集成错误。它们合起来是评审的底线——发布检查清单覆盖了仍需在真实环境中证明的部分。
pnpm test
pnpm check
pnpm build当 agent 走错方向时
结果不对时，忍住别在糟糕的 diff 上叠追问。回滚到检查点，围绕被误解的地方收紧简报——通常是没写出来的约束或缺失的负责方——然后重新运行。每次重试都应该带着新信息，而不只是新的紧迫感。
持续失败通常意味着简报假定了仓库里不存在的上下文。如果 agent 不断发明第二个存用户的地方，修复办法是在 AGENTS.md 里加一句身份归谁管，而不是更强硬的语气。先更新文档再重试任务——套件把这套工作流放在 agent 指南里。
关于 agent 工作流的常见问题
每当创始人开始把真实的产品工作交给编程 agent，总会出现这几个问题。
- 编程 agent 能独立构建整个 SaaS 吗？ —— 它能很快拼出看得见的部分，但持久的部分——授权、计费生命周期、数据隔离——仍然需要简报、检查和评审。没有这个闭环，速度会变成返工。
- 交给 agent 的任务应该多大？ —— 小到你能在几分钟内在运行中的应用里验证结果：一个用户可见的结果、一个负责的模块、一条验收检查。
- 什么绝不应该写进提示词？ —— 供应商密钥、会话 cookie、
.env.local的内容和客户数据。点名文件让工具在本地读，而不是把值复制进聊天记录。 - agent 写的代码会改变评审方式吗？ —— 评审从敲代码变成读代码：检查 diff 里的重复逻辑、过宽的异常处理，以及重复解决技术栈本已覆盖问题的依赖。
- 哪些测试对 agent 产出最重要？ —— 那些钉住归属与失败行为的测试：未授权请求、非法输入和重复提交，而不只是演示里展示的顺利路径。