您的 AGENTS.md 是为性能更差的模型编写的:提示词债务审计
旧版的 AGENTS.md 规则依然存在,即便它们已修复了模型中的缺陷。学会识别提示词问题,将技能整合到路由器中,设定权限,并在开始之前明确完成标准。
AGENTS.md 文件中的每一行规则通常都是为了解决某个实际问题而添加的。随着模型性能的提升,问题逐渐消失,但这些规则却依然保留下来。这就是所谓的“提示词债务”:原本为弥补某个模型缺陷而采用的临时解决方案,最终变成了永久性的规则。解决之道是给该文件设定更明确的职责,涵盖不变量、隐藏约束、权限边界以及完成标准的定义。
每当某个编程智能体出现令人印象深刻的故障时,总有人会添加一条新规则。但这些规则往往修改过度,因此文件要求只修改必要的部分。它们还会跳过验证步骤,于是又需要新增规则来要求每次都运行完整的测试套件。它们还会未经许可就更改依赖项,导致依赖项的变更必须经过审批。由于这些规则在代码库中四处散布,文件便需要明确指定应首先阅读哪些文档。
每条规则在最初被编写时都是合理的。但后来模型发生了变化。
OLD: Read A → Edit B → Test C
NEW: Boundaries → Permissions → Definition of done
以GPT-6 Astra为代表的最新一代模型在遵循指令方面明显优于早期的编码模型,这也改变了提示词的使用方式。性能较弱的模型可能会忽略过于宽泛的规则,而性能较强的模型则会严格照做。因此,原本为弥补旧模型缺陷而设计的指令,反而可能在新模型上引发问题。如果不对模型的指令进行审核就直接升级,那些旧有的缺陷就会作为固定规则延续到新系统中。模型虽然变好了,但提示词的使用方式却依然如故。
每一次失败都会留下痕迹
当临时的本地解决方案逐渐演变为结构性限制时,代码就会积累技术债务。给智能体的指令同样会以同样的方式积累“债务”。
假设某个旧版本的编码模型总是忘记检查自己的修改,于是有人添加了如下指令:
Always run the entire test suite after every change.
当时这或许提升了可靠性。一年后,该模型已能识别出受影响的测试并自行检查结果,但那条指令依然存在。如今,一个简单的单字修正就能触发二十分钟的集成测试。实际上并没有任何问题,代理也在严格遵循代码库的规定。问题在于,一个旧的行为修复方案被上升为永久性的工程政策。
这就是“即时债务”。某条规则解决了实际问题,问题消失了,但规则却依然存在。
技能在运行前需要消耗资源
由于技能的完整内容仅在需要时才会加载,因此看起来成本很低。Agent Skills格式采用了渐进式展示方式:首先加载技能的名称和描述,只有当任务匹配时才会加载完整文件。
但在模型选择技能之前,它必须先识别出这些选项,因此名称和描述早已在争夺用户的注意力。
想象一个包含多种独立技能的库,这些技能分别涉及数据库迁移、PostgreSQL、架构设计、后端持久化、查询优化以及数据恢复。每项技能都有一段涵盖面很广的描述,会同时提到SQL、迁移、架构、查询、模型和存储等内容。即便只是对查询进行微小的调整,看起来也与库中一半的技能相关,因此智能体在编写代码之前必须先进行分类。
更好的方式仍是逐步披露,OpenAI的技能文档也支持这一做法:详细的指导信息会放在辅助文件中,只有在任务需要时才会显示出来。
database/
├── router.md
└── references/
├── migrations.md
├── performance.md
└── recovery.md
根文件只需包含足以完成任务所需的必要信息。架构变更相关内容会记录在migrations.md中,查询性能问题则对应performance.md,而数据恢复或丢失的情况则记载于recovery.md。这些细节并未被丢弃,当任务需要让智能体读取相关内容时,它们就会呈现出来,这种方式比凭猜测加载操作知识更能充分利用上下文信息。
AGENTS.md应存储代码无法解释的内容
仓库级别的指令表现有所不同,因为它们几乎会伴随智能体执行每一个任务。像AGENTS.md这样的文件会作为固定上下文加载到会话中,正如Claude Code的记忆文档所描述的那样,因此如果这些内容出错、过时或范围过于宽泛,就会带来很大麻烦。
一个实用的测试:一位能力出色的工程师在查看这个代码库时,能否以安全且低成本的方式解决这个问题?如果可以,那么这条规则或许就不该放在 AGENTS.md 中;如果不行,那它很可能就该放在那里。
比较两条指令。第一条是模型无法安全推断的、与特定代码库相关的知识,因此它仍会保留:
KEEP
Generated API clients in /src/sdk are immutable.
Edit the generator source instead.
第二种描述的是一种可能适用于架构重构的工作流程,但对于修正单个单词的拼写错误而言则过于繁琐,因此应当被移除或舍弃:
MOVE OR REMOVE
Before making any change:
1. Read ARCHITECTURE.md
2. Inspect the repository map
3. Review all package documentation
4. Identify downstream dependencies
持续的指令应主要涵盖三方面:必须始终成立的不变量、代码库未明确体现的隐藏约束,以及界定智能体可行动范围与需由人类决策界限的自主性边界。这与教会模型如何进行软件工程相比,任务要简单得多。
更优秀的模型让权限变得更加重要
更强的指令遵循能力会带来一种更为微妙的故障:智能体可能会过度严格遵守你的边界,以至于在你希望其继续前进的地方就停止了。
假设它执行了某项变更,而因该变更产生的本地测试失败了。它会报告auth_spec.ts存在问题,并询问是否应该修复它。该模型知道如何修复测试,但不知道这种修复是否属于其被赋予的权限范围。在这种情况下,授予权限比其他流程更为有效:
Local tests use disposable fixtures and have no production access.
Run affected tests, fix regressions caused by the requested change,
and rerun them without asking for approval at each step.
这些说明告诉代理三件它并非总能推断出的信息:环境是安全的、修复工作在处理范围内,以及它可以继续执行操作。以这种方式设定的边界比“绝不对处理范围进行扩展”之类的全面禁令更能为决策提供指导。
在实践中划分权限的一种方法:
需要人工审批的情况:
- 删除生产环境数据。
- 更改认证策略。
- 违反公共 API 的契约规定。
- 实施存在运营风险的迁移操作。
代理通常可以继续执行以下操作:
- 修复因其自身更改而出错的测试。
- 更新附近的本地类型定义。
- 格式化其修改过的文件。
- 重新运行受影响的本地测试。
正是后果的不同导致了这些列表的划分——相邻的操作并不都需要同等的审批级别。
在描述操作路径之前先明确完成标准
较旧的提示语通常会描述路线:
Read these files.
Modify these modules.
Run this command.
Inspect this output.
Run these tests.
当工作流确实十分脆弱时,这会有所帮助,但能力较强的智能体通常能从明确的终点获得更多收益。请对比原始请求。
Implement the avatar endpoint.
还有一个添加了终点的版本:
Run the affected local tests, inspect the returned payload,
fix regressions caused by this change, and stop when the requested
behavior works or an external blocker requires a decision from me.
第二个部分不会指定先打开哪个文件,而是描述完成后的结果形态。随着模型具备足够的判断能力,能够自行选择在代码库中的处理路径,这种区别会愈发明显。人们设定目标与危险边界,而智能体则负责规划路径。
合理设计指令层级结构
一个清晰的架构包含三个独立的层次。第一层是仓库文件:
AGENTS.md
↓
Repository invariants
Safety boundaries
Global permissions
第二项包含技能:
Skills
↓
Specialized workflows
Loaded only when relevantTask prompt
↓
Immediate objective
Local constraints
Definition of done
第三点是任务提示本身。当各层内容相互混杂时问题便出现了:一次性任务工作流被写入AGENTS.md,全局安全规则隐藏在模型可能永远不会加载的技能中,某个技能逐渐膨胀成一部百科全书,或是任务提示重复了模型已掌握的仓库知识。随着模型能力不断提升,这种重复带来的成本也会越来越高。
模型更新时审核提示内容
模型升级时应进行指令审核。这并非因为所有旧指令都是错误的,而是因为其背后的假设可能已经发生变化。有效的审核应包含四个步骤。
梳理历史补偿措施
收集所有影响智能体行为的内容:
AGENTS.md- 技能描述
- 技能实现代码
- 系统级的仓库提示
对于每一条规则,都要弄清楚它存在的理由,以及是哪次故障促使人们添加了它。
区分真正的不变量与习惯性规定
思考一下,一位能力出色的工程师是否能够从代码库中安全且低成本地推断出这条规则。如果可以,再测试该规则是否可行;如果不可行,则保留它。涉及生产风险、生成结果、隐藏的基础设施行为以及不明显的运营约束的规则需要特别重视。
将复杂技能转化为标准化流程
如果某项技能涉及多个工作流程,应简化其入口点。仅在需要迁移时才提供迁移说明,仅在需要恢复时才提供恢复流程。这样,专业知识得以保留,而不必强加到每一个相关的任务中。
重新阅读每一项禁令,了解其背后的风险
诸如“绝不可触碰X”、“进行Y操作前务必先询问”或“仅可修改Z”这类规则仍然是合理的,但每条规则都应根据其旨在避免的后果来加以检验。有时更好的规则会是:在本地开发环境中可自由修改X,但在生产环境中则需先询问;或者允许修复由代理自身改动引发的回归问题,而更重大的改动则需获得批准。
目标并非追求最大的自主权,而是在后果值得重视的地方投入人类的注意力。
哪些内容应经得起每次升级
无论模型多么优秀,某些指令都是不可或缺的。部署时可能需要一些未文档化的旧有标志。生成的文件看似可编辑,但实际上任何修改都会被覆盖。使用临时配置时,本地环境可能类似于生产环境。迁移过程可能需要在应用程序的两个运行版本之间进行。这些内容具有很高的价值,因为仅靠智能分析无法可靠地发现它们。
判断标准是信息价值。如果该指令包含了模型无法安全发现的要素,就应保留它;如果它只是描述了旧模型处理常规工程任务的方式,那就需要重新考虑。指令数量多并不会导致提示词债务,真正的债务在于那些存在理由已消失的指令。
过去编写智能代理的思路是尽可能详细地规定执行路径。但随着模型性能的提升,更简洁的设计反而更有效:只需明确不变量、设定权限以及定义“完成”意味着什么,其余部分交由代理自行处理。当有新模型推出时,只需先检查相关规则,再继续编写代码。
相关阅读
- 为什么AI代理需要治理层,而非仅仅更好的提示词 — 提示词仅影响单次交互,无法构建完整工作流程。通过规则、限定上下文、权限限制及完成验证构成的治理层,才能让智能代理具备可靠性。