编码代理为什么会忽略您的指令?
指令文件写着“停止”,代理却继续执行?了解规则未进入上下文、与代码冲突或距当前内容过远的原因,并在重写规则前完成诊断。
编码代理为何忽略您的指令
编码代理忽略您的指令有4个原因,而且都不是因为您的语气不够强硬。规则从未进入上下文窗口。规则过于模糊,无法据此检查某项操作。上下文中的其他内容与规则冲突,通常是代理刚刚读取的代码与规则冲突。或者,规则仍在上下文中,但位于当前轮次之前很远的位置,代理会依据距离当前位置较近的内容工作。
每个原因都有对应的修复方法,因此首先要做的是区分这些原因。使用大写字母或 IMPORTANT 一词不能诊断问题。下面以 Claude Code 为例说明这些机制,因为截至 October 2026,其加载和压缩行为已有详细文档记录。其他工具的具体细节有所不同,但总体行为相同。
先说明两个术语。上下文窗口是模型在某一轮中看到的文本块,包括系统提示、您的指令文件、对话内容,以及代理读取过的每个文件。执行框架是模型周围的程序,负责从磁盘读取文件并组装这个文本块。本文几乎所有抱怨的真正对象都是执行框架,而不是模型。
您的指令文件是消息,不是设置
指令文件不是配置。运行时不会读取 CLAUDE.md 并强制执行它。运行框架会从磁盘读取该文件,再将文本粘贴到对话中。在 Claude Code 中,这些内容会作为位于系统提示之后的用户消息传递,因此模型看到这些规则的方式,与看到您输入的其他内容相同。
这会带来一个令人不适的结果。您的规则会与窗口中的其他文本处于同等位置并相互竞争。规则是一项声明。代理刚刚打开的文件则是证据。两者不一致时,证据往往会胜出,而且不会触发任何错误,因为从模型的角度看,并没有发生异常。
官方文档对此说明得很清楚:指令文件会作为上下文处理,而不是作为强制执行的配置。无论模型如何决定,如果您都要阻止某项操作,就需要使用 hook,而不是写一句话。请记住这一点。本文末尾的大多数修复方案,都是将这一原则应用到具体场景中。
加载哪些指令文件,以及何时加载
Claude Code 会从启动目录开始沿目录树向上查找。启动时,会完整加载从文件系统根目录到当前工作目录之间的所有 CLAUDE.md 和 CLAUDE.local.md。这些文件会按该顺序拼接,因此距离启动目录最近的文件最后读取;同一目录中,.local 文件会追加在主文件之后。
当前工作目录下方子目录中的文件加载方式不同。它们不会在启动时加载,而是在代理读取该目录中的文件时加载。.claude/rules/ 中带有 paths: frontmatter 字段的路径范围规则也是如此:代理读取匹配文件时才会将其加入上下文,而不是在每轮对话中都加载。从 v2.1.309 开始,以这种方式加载的文件还受到单文件大小限制(在 200K 上下文窗口中为 40,000 个字符)。对于更长的文件,代理只会收到文件开头的内容,因此大型嵌套文件末尾附近的规则可能永远无法进入上下文。
这个差异可以解释相当多的报告故障。您将规则放在 packages/api/CLAUDE.md 中,询问有关 API 的问题,而代理从未打开 packages/api/ 下的文件就给出了回答。规则并没有被忽略,而是从未存在于上下文中。如果您的仓库将指导拆分到单体仓库中的各个软件包指令文件,每次都应首先检查这一点。
另一个加载陷阱会影响采用 AGENTS.md 的仓库。从 v2.1.277 开始,Claude Code 默认将 AGENTS.md 作为项目指令读取,但仅当当前工作目录及其上方目录中不存在 CLAUDE.md、.claude/CLAUDE.md 或 CLAUDE.local.md 时才会这样做(个人的 ~/.claude/CLAUDE.md 不计入其中)。只要添加其中任意一个文件,即使是用于个人笔记的 CLAUDE.local.md,Claude Code 就会改为读取您的 CLAUDE.md 文件,并完全不加载 AGENTS.md。如需同时加载两者,请在 /config 中将 Project instructions 设置为 claude-md-and-agents-md。在 v2.1.277 之前的版本中,或者当您希望保留 CLAUDE.md 时,可使用一个 CLAUDE.md 作为桥接文件,其第一行是 @AGENTS.md;该行会在启动时导入此文件,下面可以添加 Claude 专用的备注。如果没有其他内容要添加,也可以使用符号链接。首先决定哪些内容应放入该文件是另一个问题,详见拆分代理指令与人工文档。
确认文件已加载后再重写
在确认代理可以看到文件之前,不要修改其中的措辞。需要进行两项检查,先执行成本较低的一项。
在会话中运行 /context。它会按类别列出当前窗口中的内容,其中 Memory files 列出启动时已加载的所有指令文件。文件未出现在该列表中,说明它未在启动时加载;在有其他机制加载它之前,写入其中的任何内容都不会生效。子目录中的嵌套文件不会出现在该列表中,因为它们会按需加载;文件加载后,终端中会出现带有其路径的 Loaded 行。/memory 会列出文件位置并打开文件进行编辑,包括尚不存在的文件。
如需更确切地确认,请记录加载事件。每当 CLAUDE.md 或规则文件进入上下文时,InstructionsLoaded 钩子事件都会触发,其匹配器会说明加载原因:session_start、nested_traversal、path_glob_match、include 或 compact。将以下内容放入 .claude/settings.json:
{
"hooks": {
"InstructionsLoaded": [
{
"matcher": "nested_traversal",
"hooks": [
{
"type": "command",
"command": "cat >> /tmp/instructions-loaded.log"
}
]
}
]
}
}该钩子会将事件载荷以 JSON 形式写入标准输入,因此 cat 会追加完整记录。工作期间使用 tail -f /tmp/instructions-loaded.log 监控该记录。系统会忽略此事件的退出状态,因此该钩子只能观察,不能阻止加载。如果在预期会加载嵌套文件的会话中,该文件始终未出现在日志中,请停止修改措辞。问题在于文件位置。存在一个例外:Claude Code 直接读取的 AGENTS.md 不会触发此事件,因此请在 /memory 中查找其路径。从 CLAUDE.md 导入的 AGENTS.md 会按通常方式触发该事件。
长会话对规则的影响
这里有两种不同的影响,需要采用不同的应对方式。
距离。在执行压缩之前,第 1 轮中声明的规则到第 90 轮仍然处于上下文窗口中,但此时它要与最近 90 轮的文本竞争。后者对当前任务更及时,也更具体。执行压缩后,只在聊天中输入的规则可能根本不在窗口中:Claude Code 的文档明确警告,会话早期的指令可能丢失,这就是下面介绍的第二种影响。无法配置来消除距离,但可以测量它。在新会话中执行相同任务。如果规则在新会话中有效,但在长会话深入进行后失效,那么原因就是距离或压缩。
压缩。窗口填满后,运行环境会汇总截至当前的会话,并从该摘要继续执行。能够保留下来的内容取决于摘要器判断哪些信息重要,这不一定符合您的判断。Claude Code 按机制记录了具体结果,而这些机制之间差异很大。项目根目录中的 CLAUDE.md 和未限定作用域的规则会在压缩后从磁盘重新注入。自动记忆也会从磁盘重新注入。带有 paths: frontmatter 的规则会丢失,直到再次读取匹配的文件。子目录中的嵌套 CLAUDE.md 文件会丢失,直到再次读取该子目录中的文件。
根据这张表排列指令后,就能看出它们的脆弱性顺序。只在聊天中输入的规则是会话中最脆弱的内容:只有摘要碰巧保留它时,规则才能继续存在。packages/api/CLAUDE.md 中的规则次之,因为它只加载过一次,随后被摘要移除,直到下次读取该目录中的文件时才会恢复。项目根目录文件中的规则最持久,因为每次都会从磁盘重新读取。
因此,如果某条指令必须在整个会话期间有效,就应将其放入项目根目录文件,并且不要使用 paths: frontmatter。其他做法都属于权衡,应根据目的主动选择。管理上下文窗口中保留的内容介绍了如何使用焦点参数处理 /compact,以及如何处理无关任务之间的 /clear;这两种方式都会改变摘要器决定您的规则内容的频率。
为何周边代码比规则更有说服力
这是人们最常描述、却最少诊断的问题。您的文件规定数据库访问必须经过仓储层。代理却编写了一个直接调用 ORM(对象关系映射器)的处理程序。问题不是代理在风格上忽略了您的要求,而是现有证据占了上风。
规则描述的是一种偏好。代码展示的是一种实际做法。当代理打开即将编辑的模块中的 3 个文件,而这 3 个文件都直接调用 ORM 时,当前上下文一侧只有一句抽象规则,另一侧则有 3 个具体、近期且与任务匹配的示例。复制本地模式通常是正确行为。这里只是因为您知道上下文不知道的信息,所以这种做法才是错误的:这些文件属于旧代码。
因此,应将这点写入规则。明确说明自身反例的规则,才能经受真实代码仓库的检验。只陈述偏好的规则做不到这一点。
新的数据库访问必须经过app/repositories/。app/legacy/下的文件仍会直接调用 ORM。这是旧代码,不是应遵循的模式。不要复制它。
第二句话才是关键。它会在代理发现这些文件之前,告诉代理将要看到什么,以及应如何理解这些内容。同样的修复方式适用于任何明显与代码仓库矛盾的规则:历史提交并未遵循的提交格式、半数测试套件都未采用的测试布局、仅适用于新代码的导入约定。只要代码与文件中的规则不一致,就应在文件中明确说明这种不一致。
无法检查的规则也就无法执行
“编写整洁的代码。”“不要过度设计。”“保持简单。”“迁移时要谨慎。”这些要求都无法针对某个具体操作进行测试,无论由代理执行还是由您检查都一样。如果代理拿到一条无法用来检查自身输出的规则,它只能猜测;而您只能凭感觉评判这个猜测。
对文件中的每一行都应用以下测试。写出一条 shell 命令,使规则被违反时命令以非零状态退出。如果无法写出这条命令,规则就不可检查。比较以下示例:
- 不可检查:“保持函数简短。”可检查:“超过 60 行的函数上方必须有注释,说明函数为何需要这么长。”
- 不可检查:“测试你的修改。”可检查:“运行
npm test,并在将任务标记为完成前粘贴失败计数。” - 不可检查:“保持文件井然有序。”可检查:“HTTP 处理程序位于
src/api/handlers/。该目录中不得放置其他内容。” - 不可检查:“正确格式化代码。”可检查:“
.ts文件使用 2 个空格缩进。”
“不要过度设计”是人们最先放弃的一条要求,因为修复方式不是把句子写得更短,而是写得更长:明确说明可行的最小修改实际包含哪些内容,为代理提供可以用来检查自身 diff 的标准。
大小问题只是换了一种形式。Claude Code 的指南建议每个指令文件少于 200 行,并明确指出,文件越长,遵循程度越低。700 行的文件并不会让指令更严格。它只是包含 700 行更容易互相矛盾的陈述,而且每一轮都会占用窗口,这会直接反映在您的 token 使用量中。将文件组织为按标题划分的规则,便于读者快速查找;相关方法见编写代理可以执行的指令文件。更好的做法是删去描述性内容,而不是指令性内容:处理程序和模型所在位置的目录说明属于结构信息,代理可以根据需要从解析后的仓库地图中查询,无需每一轮都将其保留在窗口中。
十分钟内完成诊断
按顺序运行以下步骤。直接跳到最后一步,通常会导致规则文件越来越长,充斥着大写命令,却仍然无法生效。
- 确认规则已加载。 运行
/context并查看 Memory 文件列表;如果是嵌套文件,则在终端中查找其Loaded行。如果文件不在列表中,请修正文件位置,然后停止。此列表中的其他步骤暂时都不适用。 - 在新会话中复现。 启动新会话,并执行应触发该规则的最小任务。在长会话中规则起初有效、之后失效,通常说明上下文距离过长或发生了压缩。如果在新会话中也失败,问题就在规则本身。
- 排除竞争规则。 在现有代码已经遵循该规则的目录中,请求执行相同的修改。如果合规性恢复,说明周围代码中的其他约束压过了你的规则描述。
- 搜索冲突。 两个文件为同一行为提供不同指导,是一种已知故障。模型可能会任意选择其中一个,而且不会告诉你它这样做了。
- 让规则可检查,然后重新测试。 使用具体路径和条件重写规则。合规性大幅提高,说明原因在于原来的措辞。
第 4 步只需运行一条命令。搜索所有指令来源中的相关主题,而不只是你正在编辑的文件:
grep -rni "migration" --include="CLAUDE.md" --include="CLAUDE.local.md" --include="AGENTS.md" .
grep -rni "migration" .claude/rules/ ~/.claude/CLAUDE.md ~/.claude/rules/ 2>/dev/null如果两个文件中的说明相互矛盾,这就是故障原因。删除其中一份。不要试图通过更强的措辞为它们排序,因为没有可供调用的排序引擎。在 Claude Code v2.1.283 或更高版本中,/doctor prompt-audit 会在指令文件、规则和技能中执行范围更广的搜索,并报告矛盾及建议的修改;除非你明确要求,否则不会更改任何内容。
按控制力度排序的修复方法
下面的每一步都比上一步控制力更强,但设置成本也更高。如果规则只需简单改写就能解决,请从顶部开始。如果某条规则重要到不能接受偶尔遗漏,请立即下移到更强的控制层。
- 让规则具体化。 指定路径、命令或条件。像前面所示,补充代理将在仓库中找到的反例。这种做法无需额外成本,却能解决出乎意料多的问题。
- 将规则移到受其约束的对象附近。 可以使用嵌套的
CLAUDE.md、.claude/rules/中按路径限定的规则,或直接写在文件顶部的注释中。这样,规则会与适用的代码在同一次读取中加载。需要接受这个取舍:通过这种方式加载的内容会在下一次压缩时被丢弃,并在下一次匹配读取时重新加载。 - 将强制执行移到 hook 中。 文本说明只能提出要求,hook 才能做出决定。hook 以代码形式在固定的生命周期事件中运行,无论模型得出什么结论,都会应用相应规则。
- 将规则交给确定性工具处理,并删除文字说明。 例如格式化、导入顺序、行长度、禁止导入项和提交消息格式。使用
ruff format、prettier --write、eslint或pre-commithook。格式化工具每次都能正确执行,而且不消耗 token。文字说明大多数时候有效,但每轮都会消耗 token。
以下完整说明第 3 步。假设迁移文件绝不能由代理编辑。将以下内容写入 .claude/settings.json:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/guard-migrations.sh"
}
]
}
]
}
}再将以下内容写入 .claude/hooks/guard-migrations.sh:
#!/usr/bin/env bash
set -euo pipefail
path=$(jq -r '.tool_input.file_path // empty')
case "$path" in
*/migrations/*)
echo "Files under migrations/ are written by hand. Stop and ask first." >&2
exit 2
;;
esac
exit 0运行 chmod +x .claude/hooks/guard-migrations.sh,然后启动新会话,并要求代理编辑 migrations/ 下的文件。编辑操作会被拒绝,消息会返回拒绝原因。PreToolUse 返回退出状态 2 时,会在工具调用执行前将其阻止;stderr 文本会作为阻止消息传递给模型。${CLAUDE_PROJECT_DIR} 会解析为项目根目录,因此无论代理当前位于哪个目录,hook 都能正常工作。代理不必认同这条规则,也不必记住这条规则,甚至不必在当前上下文中保留这条规则。编辑操作不会发生。
对于不包含任何逻辑的简单禁止规则,在设置中使用 permissions.deny 即可实现相同效果,无需维护脚本;权限模式决定哪些操作可以在不先询问您的情况下运行。如果某条指令确实必须位于系统提示词层级,而不能放在用户消息中,--append-system-prompt 可以将其放在那里。不过,这是一个启动参数,每次新会话都必须重新传入,因此它更适合脚本,而不是交互式操作。
无法仅靠指令消除的问题
明确哪些部分由您负责。放置位置、措辞、文件之间的冲突以及文件大小,都是作者的问题,也应由作者修复。其余部分属于模型行为,改进措辞无法消除这些问题。
同意不等于遵守。 代理会确认一条规则,正确复述规则,然后在两次工具调用后违反它。确认本身没有成本,也不能预测后续行为。不要把确认当作修复,也不要把它计为测试。
有些习惯会持续出现。 添加注释、加入防御性错误处理、编写结束总结、运行显而易见的下一条命令。这些行为在规则禁止时仍会回来,只是发生率降低,而不是降为 0。您可以测量自己的发生率:在全新的会话中运行同一任务 10 次,然后统计违规次数。如果该数字必须为 0,就不应再把这条规则放在提示中。任务尚未完成一部分却声称任务已完成,也是同一种习惯。修复方式应采用结构化方案,而不是继续增加文字:unlazy 技能会用深度树和门控文件替代这句话,代理必须清除这些检查项后才能声称任务完成。
当前会话本身会成为示例。 如果代理在第 12 轮违反了规则,而您没有处理,这次违规就会作为示例留在上下文中,而且比规则新得多。发现违规后应立即纠正。未纠正的违规会为当前会话的其余部分提供错误示范。
指令文件不是安全边界。 它只能影响行为,不能强制执行规则。任何遗漏代价高的事项,例如凭据或破坏性命令,都应交给权限或钩子处理。让代理无法接触机密对数据也适用同一原则:不要要求代理不要读取某个文件,而应确保该文件不可读。
简而言之:证明文件已加载,使规则可检查,将规则放在其所约束对象的旁边;当遗漏率仍然重要时,就不要再依赖文字。代理无法忽略的规则,是一条从未要求代理遵守的规则。
FAQ
为什么 Claude Code 会忽略我的 CLAUDE.md?
先确认它是否已加载,不要直接假定它被忽略了。运行 /context,查看 Memory files 列表;列表中没有列出的文件不会在启动时加载。指令文件会在系统提示之后作为用户消息传入,并被视为上下文,而不是强制配置,因此无法保证严格遵守。实际情况通常有四种:文件位于代理从未读取的子目录中;两个文件内容冲突,模型任意选择了其中一个;规则过于模糊,无法据此检查某个操作;或者周围的代码体现了与规则相反的做法。
在会话中途编辑指令文件会产生什么影响?
对已经存在于会话中的副本没有影响。工作目录上层的文件会在启动时完整加载,因此模型持有的文本是启动时的版本。要加载编辑后的内容,请启动新会话,或让代理使用常规文件工具读取该文件;这样当前版本会作为新消息加入会话。压缩上下文后,项目根目录文件会从磁盘重新读取,因此新版本也会在此时加载。
根目录中的 CLAUDE.md 与嵌套文件冲突时,哪个文件优先?
都不能可靠地优先。已发现的文件会按从文件系统根目录到工作目录的顺序拼接到上下文中,而不是相互覆盖,因此距离当前目录最近的文件只会最后读取。不存在用于解决矛盾的优先级引擎,Claude Code 文档也说明,冲突规则可能会被任意处理。应将嵌套文件写成补充规则,并明确说明其适用路径;不要试图通过提高优先级来解决冲突,而应直接删除冲突内容。
我的指令在 /compact 后还会保留吗?
这取决于指令的加载方式。项目根目录中的 CLAUDE.md、未限定范围的规则以及自动记忆会在压缩上下文后从磁盘重新注入。带有 paths: frontmatter 的规则,以及子目录中的嵌套 CLAUDE.md 文件,会丢失,直到再次读取匹配的文件。仅在聊天中输入的内容,只有在摘要器恰好保留它时才会继续存在。如果某条规则必须在整个会话期间有效,请将它放在项目根目录文件中,并且不要使用 paths: frontmatter。
什么时候应将规则改为 hook,而不是继续写成说明文字?
当检查是确定性的,并且遗漏检查的代价高于编写一个小脚本的代价时,就应这样做。文件路径限制、提交前必须运行的命令,以及禁止调用的工具都符合条件。PreToolUse hook 如果以状态码 2 退出,会直接阻止工具调用,并将其 stderr 文本作为原因返回给模型,因此无论规则是否仍存在于上下文中,该约束都会生效。凡是格式化工具或 lint 工具能够判定的内容,都应交由相应工具负责,并从指令文件中完全删除。