让 Agent 写代码之前，我会先写好两份说明

上一篇讲了我用只有四个工具的 Pi 写出了 Vizruna。经常有人问：Agent 写代码真的靠谱吗？

我的回答是：靠不靠谱，很大程度上取决于你开工前写了什么。 让 Agent 写代码，就像请一位能力很强、但第一天来上班的工程师。你不告诉他规矩和目标，他就只能靠猜。

所以在 Agent 动手之前，我会准备好两份说明：

	工作守则	任务合同
管什么	在任何项目里都该怎么做事	这个项目要做成什么样
写在哪	全局的 `AGENTS.md`	项目里的需求、验收、路线图文档
多久改一次	很少改，越用越稳	每个项目一套，随阶段更新

第一份：工作守则，告诉它“怎么做事”

Pi 会自动读取一个全局的 AGENTS.md 文件，里面写的规矩对所有项目都生效。我的这份守则开头第一句就是：你是一位资深工程师和技术合伙人，而不只是一个代码生成器。

这句话定了调子：它的责任不只是写出代码，而是帮我把目标变成能用、能维护的产品。下面是守则里我觉得最有用的几条。

分清两种“不确定”

这是整份守则里最重要的一条：

实现上的不确定：比如用哪个库、代码放在哪、怎么写更清楚。这类问题，自己查、自己决定，不用每一步都来问我；
需求上的不确定：比如这个按钮点了之后该发生什么、这个边界情况要不要处理。这类问题，必须停下来问我，不许猜。

Agent 最让人头疼的两种情况，一种是事事都问、烦不胜烦，另一种是自作主张、改出一个你不想要的东西。把这两种不确定分开，这两个问题都解决了。

半自主的工作节奏

需求清楚的时候，按这个顺序自己走完，不用每一步都等我确认：

先看项目的相关上下文；
弄明白现有的实现；
定一个合理的做法；
动手实现；
验证结果；
汇报改了什么。

第 5 步是关键。没有验证，就不算做完。

必须先问我的事

低风险的代码修改不用问，但下面这些，必须先得到我的明确同意：

批量删除文件；
修改 .env 这类配置文件；
创建、替换、暴露或轮换 API Key、密码等敏感信息；
任何会产生真实费用的操作，包括调用付费接口、创建云资源；
需求本身说不清楚的时候。

调试不许“掩盖问题”

守则里专门列了一份“不要做”的清单，因为这些是 Agent 最容易犯、也最难发现的错误：

用大范围的 try/catch 把错误吞掉；
返回一个假的“成功”；
用占位数据假装功能已经完成；
用随便加的延时来“修好”时序问题；
用一层层兜底逻辑，让系统看起来很健康，实际上主功能已经坏了。

同时规定：试了大约 3 次还不行，就重新审视假设；超过 5 种思路还没解决，就停下来，把失败现象、查过什么、试过什么、目前最可能的原因、需要我提供什么整理好再来找我。不许盲目地反复试。

第二份：任务合同，告诉它“要做成什么样”

守则管的是“怎么做事”，但它不知道这个项目要做什么。所以每个项目，我还会准备一套任务合同。Vizruna 的这一套，放在项目的 docs/startup 目录里，按顺序是：

需求文档：产品要解决什么问题、给谁用、目标是什么；
架构方案：技术上打算怎么做；
开发路线图：拆成哪几个阶段；
验收标准：怎样算做完；
风险登记：哪些地方可能出问题；
阶段报告：每个阶段做完后，留下的证据和结论。

看起来很“重”，但这些文档主要不是写给人看的，而是写给 Agent 看的：它每次开工前读一遍，就知道自己在哪、要去哪、怎样算到了。

目标要能判定

需求文档里的每个目标，都带着一个编号和一条成功判定。比如：

编号	目标	成功判定
G-02	支持多个 Agent 并行运行	至少 4 个 Agent 可以并行，状态互不串线
G-04	防止会话被并发写坏	同一个会话只允许一个写入者

“支持多 Agent”是一句口号，“至少 4 个并行、状态互不串线”才是 Agent 能去验证的东西。

完成标准不是“功能做完”

路线图里有一句话，我认为是整套文档的灵魂：阶段的完成标准，不是功能做完了，而是关键风险已经被验证、交付物可以被验收。

验收标准也说得很直接：不以“界面能点”作为验收依据。 每一项核心能力都必须同时证明：正常流程能走通；出错时不会破坏会话、代码和凭据；应用重启后状态能解释、能恢复；用户能看到结果和下一步；而且自动化测试能反复验证这些约束。

状态要说真话

这是我最想分享的一点。每份阶段报告的开头都有一个“状态”，而且状态说得非常诚实。比如 v0.1 的完成度审计，结论是两句话：

工程候选版：完成。 代码仓库里能安全、可重复完成的工作，都已经完成；
正式发布：未完成。 签名公证、干净设备测试、真实模型调用、7 天试运行、真实用户试点，这些需要外部的人、设备和凭据，还没有拿到证据。

审计里还有一句话：“有脚本”不等于“外部门禁通过”。 写了测试脚本，不代表测试已经在真实环境里跑过。

Agent 天生倾向于说“已经完成了”。当你的文档本身就把“完成”拆成了好几种不同的状态，它就很难再含糊过去。

可以直接借用的写法

你不需要写得像 Vizruna 这么完整。一个小项目，两份说明各写一页就够：

# 工作守则（全局 AGENTS.md）
- 实现上的不确定：自己查、自己定；需求上的不确定：停下来问
- 流程：看上下文 → 理解现状 → 定方案 → 实现 → 验证 → 汇报
- 必须先问：删文件、改 .env、动密钥、会花钱的操作
- 不许：吞掉错误、假装成功、用占位数据冒充完成
- 3 次不行重新想，5 种思路还不行就来找我，并说明试过什么

# 任务合同（项目里的 docs/）
- 目标：每条带编号和“成功判定”
- 验收：正常路径、出错路径、重启恢复、自动化测试
- 阶段：每个阶段的完成标准 = 风险已验证 + 交付物可验收
- 状态：分清“工程完成”和“真实环境验证完成”

为什么这比换一个更强的模型更有用

模型会不断变强，但它永远不知道你心里的“做完”是什么意思，除非你写下来。

写这两份说明，花的时间可能只有一两个小时，但它们会在之后的每一次对话里反复起作用。这是用 Agent 写代码的人，投入产出比最高的一件事。

同样的方法，我也用在给客户做的 AI 流程上：先写守则和合同，再让 Agent 动手。如果你的团队想让 Agent 接手一段开发或业务工作，但不知道该怎么立规矩，可以看看我的 Skill / Agent 定制服务。