给 Coding Agent 升级，先收拾 AGENTS.md

让 Coding Agent 改一个 Bug，它读完仓库，回了一句「这个改动可能影响边界条件，请确认」。

你说先跑测试，它把单元测试、端到端测试和一堆顺手发现的检查全拉起来。十分钟过去，改动还没开始。

很多人会把这口锅扣在模型身上。可 OpenAI 刚更新的 GPT-6 Astra 模型指南 里，有一段我觉得特别值得圈出来，它更会执行自己能读到的提示、项目说明和规则文件，也更容易在缺信息时停下来问。

好家伙。模型升级以后，项目里那堆没人敢删的 AGENTS.md、系统提示和 Skill 说明，突然都从背景板变成了方向盘。

这件事没有那么玄。老模型经常会把模糊规则漏过去，或者凭感觉补完。新模型更认真，它看到「改动前必须确认」「测试必须充分」「有风险就停止」这类句子，就会真的照办。问题在于，很多仓库把不同级别的话堆在一起，有的是团队习惯，有的是生产权限，有的是某次事故后临时加的一句。它们甚至互相打架。

模型没有摸鱼，它只是被交给了一份没有优先级的工作说明书。

OpenAI 在指南里提到，Astra 更可能在会改变结果的信息缺失时发起澄清，也更擅长遵循文件里的指令。它同时支持异步工具调用、中途调整任务、保留缓存前缀下改变推理力度。这些能力让长任务更能跑下去，也让一件事变得更要紧，谁可以决定，谁只能等确认。

如果你准备给 Codex、Claude Code、Cursor 这类 Coding Agent 换模型，我会先做一个很朴素的动作，把规则收口。别急着给提示词再塞三段热血口号，先把下面这张卡填出来。

先把 Agent 当成一个新同事

一个刚进组的新同事拿到五份文档，A 文档说「尽量自主」，B 文档说「任何改动先问」，C 文档说「完整测试后再结束」，D 文档又说「小修不要浪费时间」。他大概率也会卡住。

Agent 的困境差不多。只是它不会在工位上叹气，它会不断把问题弹回给你，或者把一个两分钟的修复拖成一场全仓库巡检。

所以规则文件里最该先写的，不是人格，也不是一长串「要专业、要细致」。要先写权限边界。读代码、搜索文档、运行无副作用的静态检查，通常可以直接做。改生产配置、发外部消息、合并主分支、产生真实费用，就应该停下来。它们中间还隔着一大片灰区，比如删测试数据、重写迁移文件、批量改依赖版本。

这些灰区不写，模型再聪明也只能猜。猜对一次挺爽，猜错一次就得翻日志。

我觉得最实用的写法，是把抽象要求压成五栏。放在项目根目录的说明里也行，拼进系统提示也行，重点是短、明确、能被复核。

栏目	该写什么
任务终点	交付物和成功条件，例如修复哪个行为、补哪类测试
默认可做	读取代码、搜索仓库、运行指定测试、生成草稿
必须确认	部署、对外发送、删除数据、真实付费、合并主分支
规则优先级	用户要求、项目规则、局部目录规则冲突时谁优先
完成证据	相关测试结果、diff、生成文件、外部系统回执

这张卡看着像行政表格，实际挺救命。它把「你要自己判断」翻译成了可执行动作。模型知道什么时候该继续，什么时候该把一个具体选择递到人手里。

落到文件里，不需要写得像法典。下面这种程度已经能让人和模型都少猜几步。

本次任务的成功条件是，修复复现用例并通过相关单元测试。
可以直接做，读代码、搜索仓库、改当前模块、运行指定测试。
必须确认，删除数据、改生产配置、发外部消息、合并主分支。
规则冲突时，用户当前要求高于项目说明，目录说明高于通用约定。
完成时交付，diff、测试命令和结果、仍未解决的风险。

这里没有「尽量谨慎」这种漂亮废话。每一句都能对应一次工具调用，或者对应一次该停下来的时刻。规则越能落到动作上，Agent 越不必用一堆澄清问题来猜你的底线。

把可逆动作和必须确认的动作分开，模型才有可执行的边界。

别把权限控制只写在提示词里

这里还有个容易被忽略的坑。规则写清楚，会减少无效追问，也会让对话更可预期。但它不是门禁系统。

真正要保护生产环境的团队，还是得把边界落在工具层。部署工具用最小权限，危险命令需要显式批准，外部 API 有作用域和额度，关键动作留下审计记录。提示词负责说明工作方式，系统权限负责兜住底线。

这两层缺一层，都会有点悬。只靠权限，Agent 像被蒙住眼睛干活。只靠文字，又像把办公室钥匙挂在墙上，再贴张「请不要拿」的纸。

OpenAI 这次还给了一组很具体的迁移提醒。Astra 的工具调用应该走 Responses API，老调用里的 temperature、top_p 和 top_logprobs 要清掉。它不支持 none 推理力度。需要在任务中段提高推理力度时，可以用 configuration_update，这样不必重写整段原始提示，也能保住缓存前缀。

这些 API 参数当然要改，但我反倒会把它们放在第二天做。第一天先挑一个低风险任务，把规则卡写出来，让 Agent 只读仓库、改一个可逆的小问题、跑指定的检查，再交出 diff 和测试结果。跑顺了再扩权限。

厉害了，这才像升级。不是把一个更强的模型塞进旧流程里，然后祈祷它既主动又听话，还永远知道哪一步该停。

小改动走小而清楚的验证路径，比一头扎进测试迷宫更有交付感。

还有一个小细节。OpenAI 说 Astra 在编码任务里会更愿意认真验证。对复杂改动是好事。可你要它改一个文案、补一个空状态、修一个局部样式时，别只写「完成后充分测试」。告诉它需要跑哪条测试，哪些全量检查这次不用跑，完成标准是什么。模型不是怕麻烦，它只是把你的模糊要求当了真。

很多朋友可能已经发现了，Agent 最难调的时刻，并不总在它写错代码的时候。更常见的是它做了一堆看起来都没错的事，却没有把你真正要的那个结果交出来。

规则卡的最后一栏，完成证据，就是给这个问题留的出口。没有测试结果、没有可看的 diff、没有外部回执，就别把一句「已完成」当交付。棒棒的，至少现在你知道该追问什么了。

新模型会越来越能干。项目里那堆规则也该跟着长大，从口号变成边界，从边界变成证据。给 Agent 升级之前，先收拾 AGENTS.md，这一步不炫，但能让后面的路少绕很多弯。

你们项目里最容易让 Agent 卡住的一句规则是什么？