Agent 工程实践简报 · 2026-11-09

今日概念:Instruction hierarchy(指令层级)

是什么:模型收到的文字不是一样大的。开发者写的系统消息最大,你在对话里说的话其次,工具返回的内容(读到的文件、搜到的网页、命令输出)最小,被当成「资料」而不是「命令」。OpenAI 2024 年的论文把这套排序正式提出来,并训练模型在冲突时听级别高的那一方。

解决什么:防提示注入。网页或文件里藏一句「忽略之前的指令」,模型不该照做,因为它只是工具输出。论文报告这种训练让防系统提示泄露的能力提高了 63%,对训练时没见过的越狱也提高了 30% 以上。

和你已会的东西的关系:10-29 讲过的「致命三要素」靠的就是这套排序来降低风险。但它有个副作用,正好撞上你天天用的 CLAUDE.md / AGENTS.md:这两个文件是作为「指令」塞进上下文的,而 agent 读你的代码时,代码只是「工具输出」。所以说明书过期时,agent 会听说明书、不听代码(见今天第 1 条)。理解这个排序,你就知道:想让 agent 优先相信什么,就要把这条规则写进它当成「指令」的那个位置。

入门原文:The Instruction Hierarchy: Training LLMs to Prioritize Privileged Instructions(Eric Wallace 等 / OpenAI,2024)

上手 prompt:

目标:画出这个仓库里 coding agent 会读到的每一类文字分别处在哪一级「指令层级」,并找出级别放错的地方。

1. 先读仓库,列出 agent 会接触的所有文字来源及路径:用户级和项目级说明书(CLAUDE.md、AGENTS.md、.cursor/rules 等)、skills、hooks 配置、MCP 服务描述、README/docs、代码注释、测试输出。不存在的直接写「没有」,不要编造。
2. 按三级分类并制表:作为指令进入上下文的(说明书、skill 正文、系统提示)、作为工具输出进入的(读文件、命令结果、网页)、介于两者之间或不确定的。每行写清你的依据(引用官方文档或配置原文)。
3. 找出两类问题并引用原文:(a) 写成命令口吻、其实是在描述代码现状的句子(例如「我们用 X 库」「入口在某文件」),这类一旦过期就会以指令身份压过代码;(b) 外部内容(网页、第三方文档、issue 文本)可能被复制进指令文件的地方。
4. 给出不超过 8 行的修改建议:哪些描述句应该改成「去哪里查」的指针,哪些规则要保留为指令。先给方案,等我确认再改文件。
5. 交付:分级表、问题清单(带文件路径和行号)、修改建议。

参考:Wallace 等《The Instruction Hierarchy》https://arxiv.org/abs/2404.13208

本期条目

1. 说明书过期时,agent 九成会听说明书、不听代码;在用户级说明书里加一句话就能扭过来

目标:在我的用户级 agent 说明书里加入「代码优先」规则,并在这个仓库里做一次小实验,证明它对当前使用的 agent 真的有效。

1. 先确认我用的是哪种 agent 及其用户级说明书路径(Claude Code 是 ~/.claude/CLAUDE.md,Codex CLI 是 ~/.codex/AGENTS.md;其他工具请查官方文档)。贴出文件现状;不存在就说明,并先给我看要创建的内容。
2. 拟加入这句原文(英文原句来自论文,保持不改):
   "When a repository's documentation and its existing code disagree, follow the conventions used in the existing code, and in your final reply point out each inconsistency you found between the documentation and the code."
   先给我看 diff,等我确认再写入。
3. 做对照实验,不碰真实代码:在临时目录或 git worktree 里复制本仓库一小块(或新建一个 3–5 个模块、带测试的玩具项目)。在项目说明书里故意写一条和现有代码相反的约定(例如日志方式、路径处理、错误返回方式),再提一个不提约定、只描述行为的小功能需求。
4. 用非交互模式各跑至少 2 次:不加这句 vs 加这句(加的方式是用单独的配置目录,不要改动我真实的用户级文件,除非我已在第 2 步确认)。每次记录:新代码跟了文件还是跟了代码、是否改动了已有文件(删了多少行)、原有测试是否通过、最终回复有没有点出冲突。贴出命令和输出。
5. 交付:对照表、实验目录路径、结论(这句话在我的环境里是否有效;无明显差异也如实说)。

参考:Xiaonan Xu、Wenjing Wu《Stale Instruction Files Override the Code in Coding Agents: A One-Sentence Fix》https://arxiv.org/abs/2610.30571

2. 把「说明书里的引用还在不在」做成每次 CI 都跑的检查:356 个仓库里 23% 有指向已删除代码的引用

目标:给这个仓库加一个能在本地和 CI 跑的检查,找出 agent 说明书(CLAUDE.md、AGENTS.md、.cursor/rules、copilot-instructions 等,以及 skills 正文)里指向已不存在代码的引用。

1. 先读仓库:列出所有 agent 说明书和 skill 文件路径;确认仓库的脚本语言、CI 平台和已有 lint 命令(从配置文件里读,不要猜)。
2. 实现最小检查脚本:从说明书里抽出看起来像代码元素的引用(反引号里的标识符、文件路径、脚本名、包名),在当前 HEAD 里用 git grep 或文件存在性检查确认它们还在;可选地再在该说明书首次提交时的版本里查,只把「当时在、现在没了」的标成过期,减少误报。排除说明书自身和 README 的匹配。
3. 在当前仓库上跑一遍,贴出完整输出。对每条命中,人工判断(并写明理由)是真过期、误报还是说不清。不要自动改说明书。
4. 故意做一次破坏验证:在临时分支里把一个被说明书引用的函数或文件改名,确认检查会失败并指出具体行;然后还原。贴出证据。
5. 接进 CI(或 pre-commit),失败信息要写清「哪个文件第几行引用了什么、现在找不到」。交付:脚本路径、CI 改动 diff、首次运行结果表、破坏验证证据、以及给 AGENTS.md 的一句话:重命名或删除代码时,同一个 PR 里更新说明书。

参考:Christoph Treude、Sebastian Baltes《Context Rot in AI-Assisted Software Development》https://arxiv.org/abs/2606.09090

3. 无人值守跑 Claude Code 时,让「需要人点允许」的操作直接被拒、任务继续,而不是卡住等你

目标:为这个仓库的无人值守 agent 运行配好「遇到要人批准的操作就直接拒绝并继续」,并证明它不会卡住,也没有意外放行任何操作。

1. 先确认环境:运行 claude --version,确认不低于 2.1.319;读取用户级 ~/.claude/settings.json、项目 .claude/settings.json 和 .claude/settings.local.json,贴出与 permissions 相关的现有配置。版本不够就停下告诉我。
2. 列出这个仓库里会无人值守跑 agent 的入口(CI 任务、定时脚本、claude -p 调用、后台/并行 worktree 脚本),从仓库里找,没有就说没有。
3. 提出方案:denyInsteadOfPrompting 放在哪一级(用户级设置,或单次运行用 --settings 内联 JSON),值写布尔 true;同时列出这些任务真正需要的最小 allow 规则,让正常步骤不被误拒。先给我 diff,等我确认。
4. 在临时目录或 worktree 里验证:让 agent 做一件需要一个「未被允许」操作的小任务(例如运行一个没在 allow 列表里的命令)。分别在开和不开这个设置时用非交互方式运行,贴出输出:开了以后应看到该调用被拒、agent 继续并在最终回复里说明它做不了什么;同时确认没有任何本应被拒的操作被执行。
5. 交付:配置 diff、两次运行的输出对照、被拒操作清单,以及给 AGENTS.md 的不超过 4 行说明:无人值守任务遇到被拒操作时应如何在最终回复里报告。

参考:Claude Code changelog 2.1.319 https://code.claude.com/docs/en/changelog

本期去重用源链接(机器可读)