Claude Code 的 /doctor prompt-audit 是这样一条命令：让 Claude 通读你的指令文件（CLAUDE.md、AGENTS.md、技能、命令等），找出已经过时或彼此矛盾的指令，并给出修改建议。它返回的只有一份报告和建议的 diff——在你要求 Claude 应用之前，文件一个字都不会改。输入 /checkup prompt-audit 运行的是完全相同的审查。

本文依据 Claude Code 官方文档原文（How Claude remembers your project 中的“Audit your instruction files”一节，以及 Commands 和 Skills 页面）、CHANGELOG，以及 Claude Code 内置的审查指南，梳理提示词审查到底查什么、怎么用、结果该怎么处理。所有关于规格的说明，均已在 2026年10月3日对照原文核实。第 7、8 章还记录了我们拿本站自己的指令文件实际跑了一遍的结果（9 条发现，采纳 7 条），以及用下来发现的注意事项。

先说结论：/doctor prompt-audit 一览

来源：Claude Code 官方文档“How Claude remembers your project”“Commands”（2026年10月3日核实）

做什么

审查指令文件

查找为旧模型写的措辞、对已不存在的文件或命令的引用，以及相互矛盾的指令。

输出

报告和建议的 diff

不开口就不会改。采纳哪一条，由你逐条决定。

范围

CLAUDE.md、技能等

还包括 AGENTS.md、规则、命令和子代理。传入路径即可只查一处。

版本

v2.1.283 及以上

在会话内输入。与终端里的 claude doctor 不是一回事。

目录

1. /doctor prompt-audit 是什么——找出过时和矛盾的指令

Claude Code 每次启动都会加载 CLAUDE.md 等指令文件。这些文件越用越长，慢慢积攒下为旧模型写的强硬措辞、早已不存在的文件和命令名，以及和另一个文件相互矛盾的规则。/doctor prompt-audit 就是让 Claude 专门去找这些问题的命令。

把官方文档的说明归纳一下：

  • 找什么：为旧模型写的指令、对不存在的文件或命令的引用、彼此矛盾的文件。
  • 返回什么：发现的问题报告，以及以 diff 形式给出的修改建议。在你要求 Claude 应用之前，文件不会有任何变化。
  • 运行方式：通过 Claude Code 内置的 /claude-api 技能运行。如果你在设置里关掉了这个技能（用 skillOverrides 停用，或开启了 disableBundledSkills），就无法使用这项审查。
  • 版本：Claude Code v2.1.283 及以上。/checkup prompt-audit 是同一条命令。

CHANGELOG 的 v2.1.283 条目新增了 /doctor prompt-audit（以及 /checkup prompt-audit），用来检查 CLAUDE.md、技能、代理和命令中针对旧模型的提示写法。同一版本还改进了审查：把过时的路径、过时的命令和相互矛盾的指令文件排在报告最前面，并保留 Claude Code 官方支持的“think”这类控制思考深度的关键词。

为什么过时的指令会成为问题？内置的审查指南是这样解释的：如今的模型比过去的模型更贴近、更字面地遵循指令。当年为了不让旧模型漏看规则而层层叠加的“CRITICAL”“MUST”，现在用力过猛，导致规则被套用到不需要的场合，模型变得死板。指南明确写道，审查的目的不是把指令变短，而是找出已经不再适合当前模型、当前项目或你其他指令的那些指令。

2. 用法——直接输入即可，用路径缩小范围

在 Claude Code 会话中，直接输入：

/doctor prompt-audit

不带参数时，按官方文档的说法，审查的是以下文件：

类型包含的内容
指令文件CLAUDE.md、CLAUDE.local.md、AGENTS.md
.claude/ 和 ~/.claude/ 下规则、技能、命令、子代理、输出风格

如果只想审查某一个文件或文件夹，就传入路径。官方文档中的示例：

/doctor prompt-audit .claude/skills/deploy

根据内置指南，这项审查的设计是中途不停下来提问，一口气跑完。范围以及“以哪个模型为基准来审查”，它会根据你的请求和文件本身自行判断，并把这些前提写在报告开头。前提不对的话，缩小路径再跑一次即可。对于指令文件，基准通常是正在执行审查的那个模型（如果某个技能或子代理指定了自己的模型，就以那个模型为准）。

指南还规定，审查不读取 Claude Code 的设置文件（.claude/settings*.json）和 MCP 配置（.mcp.json），因为里面可能有密钥之类的机密信息。权限和 hooks 的问题不在这项审查的范围内，那是普通 /doctor 的工作（见第 6 章）。

3. 审查把什么判定为“过时”

审查的具体内容写在 Claude Code 内置的指南里（/claude-api 技能中的 prompt-audit 说明）。我们读了 v2.1.286 自带的文件，检查项分为四组。对指令文件来说，起主要作用的是前两组。

分组主要检查项示例
1. 过时的提示写法过强的措辞、如今已不需要的思考方式指定、过细的步骤指定、为旧模型缺陷打的补丁残留反复出现的“CRITICAL: you MUST...”、“Think step by step”、用“STEP 1... STEP 2...”去框住需要判断的工作
2. 脆弱的配置文件不存在的路径和命令、文件之间互相矛盾、写进文件里的事故经过、把一次失误变成永久规则、带日期的条件已删除脚本的名字、两个文件里相反的规则、“因为某月某日这样出过错……”
3. 工具描述在 API 中定义工具时写的描述（太短的描述会被指出需要写得更详细）只有一行的描述、描述里写着“必须使用这个工具”
4. API 调用设置在当前模型上会报错或已弃用的参数、会破坏缓存的顺序等只在有应用代码时才适用（只有指令文件的项目不涉及）

在第 2 组里，指南对“不存在的路径和命令”处理得尤其严格。它会检查指令文件中写的每条路径是否真的存在于项目中、命令和参数是否在脚本或配置中有定义——靠读文件确认，而不执行任何命令。与项目实际内容不符的描述，都会成为“高”置信度的发现。

两个文件互相矛盾时，审查会用 git blame（记录每一行是谁在何时写的）判断哪一方更新，并建议让旧的一方向新的一方看齐。但如果其中一方是禁令或安全规则、修改会让它变松，或者从历史上看不出哪一方更新，指南规定不给修改方案，只作为“需要用户决定的事”报告出来。

4. 不删的东西——这不是“删短一点”的审查

这项审查最让我们欣赏的一点，是指南把不能删的东西明明白白列了出来。它提醒说，什么都砍的审查，恰恰会让认真写指令的人吃亏；因此即便措辞命中了某种模式，下面这些也要保留：

  • 只有作者才知道的背景：关于读者、产品和环境的事实、质量标准、约束条件，以及它们背后的理由。指南直言，背景信息从来不是浪费。
  • 篇幅本身：不会仅仅因为长就删。造成危害的是过时的指令，而不是数量。
  • 脆弱操作的精确步骤：删除命令、认证流程这类只有一种安全做法的工作，可以保持细致的步骤指定。
  • 针对至今仍会发生的失败的禁令：只要这种失败在当前模型上仍会重现，规则就保留。
  • 运作良好的重复：同样的内容放在两处，只要彼此不矛盾，就只是整理上的偏好问题，不属于审查对象。

反方向也一样。如果补充一条指令对当前模型有帮助，它也会提出补充建议。而且指南写明，什么都没找到时，什么都不改才是正确的结果。

5. 怎么读结果——报告与建议的 diff

结果有两样：审查报告和以 diff 形式给出的修改建议。报告中每条发现都包含六个字段：

字段内容
位置文件名和行号
证据原样引用有问题的文本
模式属于第 3 章中的哪种模式
过时的原因与什么相冲突：当前模型的行为，或项目中实际存在的东西
置信度高（与官方文档或项目本身矛盾）、中（被广泛观察到的行为）、低（从措辞推断）
处理方式删除、改写（附新文本）、移动（附目标位置）、补充，或仅提示

只有高和中置信度的发现才会进入建议的 diff。低置信度的发现只出现在报告里。diff 按每条发现一个片段拆开，所以可以只挑想要的来应用。

应用时，对 Claude 说“应用第 1、3、4 条”之类即可。指南还规定，文件之间的矛盾以及与项目实际不符的文字改写，不会因为“全部清理一下”这种笼统的请求而被应用。任何对仓库有写权限的人，都可能改过较新的那段文字或项目本身，所以设计上默认由人逐条确认。

6. 与 /doctor、/claude-api prompt-audit、claude doctor 的区别

名字相近的东西有四个。按官方文档（Commands 和 Skills）与 CHANGELOG 的说法对比如下：

命令做什么会改文件吗版本
/doctor prompt-audit审查指令文件（CLAUDE.md、技能等）中过时和矛盾的指令只给报告和建议（要求后才应用）v2.1.283 及以上
/doctor（别名 /checkup）环境健康检查（重复安装、PATH、损坏的设置、没在用的技能和 MCP 服务器、慢的 hooks、可用更新），以及删掉 CLAUDE.md 中看代码就知道的内容、把常驻加载的指令移到技能或嵌套 CLAUDE.md 的建议先报告，确认后再修（精简 CLAUDE.md 的建议：v2.1.206 及以上）
/claude-api prompt-audit审查基于 Claude API 的应用中的提示词和工具描述，找出针对旧模型的写法给出 diff 建议v2.1.221 及以上
claude doctor（终端）不启动会话，只显示安装状态不改（只读）—

容易混淆的是，/doctor 本身也会处理 CLAUDE.md。区别在于目的。/doctor 的方向是减少常驻加载的内容（去掉重复、删掉 Claude 看代码就知道的东西、挪到只在需要时才加载的地方）；/doctor prompt-audit 则检查内容是否已经过时、是否自相矛盾。终端里的 claude doctor 不会运行提示词审查。

如果 Claude 不遵守指令的原因是这些指令根本没被加载，这项审查就解决不了。怎么确认加载了什么，我们在《AI 为什么不遵守规则：排查 CLAUDE.md、Cursor Rules 与 AGENTS.md》里讲过；指令文件占用了多少上下文、该怎么测，见《Claude Code 的上下文到底被什么吃掉了》。

7. 实际用了一下——审查本站的 CLAUDE.md 和 AGENTS.md

2026年10月3日，我们对开发本站所用的指令文件运行了 /doctor prompt-audit。运行环境是 Claude Code 桌面应用（内置 Claude Code 2.1.286，模型为 Opus 5.5）。本站的指令文件有两个：AGENTS.md（规则主体，Claude Code 与 Codex 共用）和 CLAUDE.md（导入前者并补充 Claude Code 专属的说明），合计约 10,700 个字符。.claude/ 下没有放任何规则、技能或命令。

运行一次的结果

来源：本站实测（2026年10月3日，对 CLAUDE.md 和 AGENTS.md 运行 /doctor prompt-audit）

发现数

9

核实后采纳

7

未采纳（低置信度）

2

第一个意外是，针对旧模型的提示写法几乎没找到。“一步一步思考”这类指定、逐条的步骤脚本，一个都没有。大部分发现都落在第 3 章的第 2 组（脆弱的配置文件）。

置信度条数发现了什么我们怎么处理
高1当天新加了两个审查工具，但一处括号注释仍写着“两者”，和新加的两个工具的说明对不上了采纳（改写注释，把新加的工具分开说明）
中5指令文件里残留着带日期和次数的事故记录（与同一文件中“不要在入口文件里堆积事故记录”的规则相矛盾）采纳（但没有删除，而是移到了单独的记录文件）
中1标题里的“(CRITICAL)”没有附带理由采纳（去掉了）
低2一份在本地跑不起来的命令清单，以及一个带日期的标题未采纳（两处都有存在的理由，指南也把低置信度定为“仅提示”）

唯一一条高置信度的发现，是真实存在的偏差。添加审查工具时，我们把名字加进了清单，却忘了改写旁边的说明。每次加载这个文件，Claude 都可能误解“两者”指的是什么，而我们肉眼一直没看出来。

报告里还记录了它确认过指令文件中出现的每一条路径、每一个工具名和每一份被引用的备忘都真实存在。它甚至核对了 PHP 版本（与 Docker 配置一致）和某个流程的步骤数（与另一个文件里的清单一致）。

我们没有照单全收 Claude 给出的 diff，而是逐条对照原文件核实之后才应用。最需要判断的是那 5 条中置信度发现。建议是删除事故记录，但这些记录本身正是防止同样错误再犯的依据，所以我们选择移走而不是删掉。日期和次数已经记在别的文件里的，只从指令文件中拿掉；另外两条在任何地方都没有记录的，则抄进了记录文件。最终，指令文件的总量从约 10,700 个字符只减少了 40 个字符左右。篇幅几乎没变，消失的只有矛盾。

需要注意，这只是在一个项目上跑了一次的结果。审查的文字由模型撰写，对同样的文件再跑一次，发现的条数和措辞都可能不同。.claude/ 下放了大量技能和命令的项目，得到的发现很可能大不一样。

8. 缺点与注意事项

结合实际使用以及官方文档和指南，有五点值得留意：

  • 会消耗你的用量额度：Claude 在会话中读取并审查指令文件，和其他工作一样计入用量。官方文档没有提到任何单独计费。
  • 不要盲目应用发现：Claude 未必知道某条规则当初为什么写。拿我们这次来说，如果照单接受“删除事故记录”的建议，就会把防止再犯的依据一并丢掉。
  • 每次结果不一样：审查由模型撰写，条数和措辞每次都可能变化。别把一次干净的结果当作“这个文件没问题”的证明。
  • 不看设置文件：它不读 settings.json 和 .mcp.json，所以权限、hooks 和 MCP 的问题不会出现在结果里。这些请用 /doctor 检查。
  • 不保证内容正确：它能发现不存在的路径和矛盾，但不判断你的方针本身对不对。方针由你来定。

指南本身也把删除视为假设而不是结论。删掉一条指令后，应当在实际工作中确认，它原本约束的那种行为没有出问题。

9. 什么时候该跑一次提示词审查

指南把提示词看作特定模型的产物：上一代需要的句子，到了下一代就成了累赘，因此它建议每出一个新模型就重新审查一次。按我们的判断，下面三种场合比较合适：

  • 换用新一代模型时：看看有没有为旧模型留下的强硬措辞和补丁
  • 大幅改写指令文件之后：就像我们这次一样，新加的规则和旧的说明很容易对不上
  • 在 Claude Code 和 Codex 等多个工具之间共用指令文件时：更容易发现 AGENTS.md 与 CLAUDE.md 之间的矛盾

反过来，如果你的指令文件很短、几乎不改，就不必急着跑。指南也说，什么都没找到是正确的结果。

总结

/doctor prompt-audit 是一条在你的指令文件（CLAUDE.md、AGENTS.md、技能等）中查找为旧模型写的措辞、不存在的路径和命令以及相互矛盾的规则，然后返回报告和建议 diff的命令。Claude Code v2.1.283 及以上可用，不开口就不会改任何东西。

审查指南把背景、理由以及针对仍会发生的失败的禁令列为“不删的东西”加以保护，避免它变成“删短一点”的审查。我们用本站的指令文件跑了一次，针对旧模型的写法几乎没有，倒是发现了添加规则后忘了改写的说明——一处真实的偏差。

稳妥的做法是逐条对照原文件核实发现，对有理由存在的文字，移走而不是删掉。换模型之后或大改指令文件之后跑一次，能捡回肉眼漏掉的矛盾。

FAQ

Q. /doctor prompt-audit 会自己改写我的 CLAUDE.md 吗？

A. 不会。官方文档说它返回报告和修改建议，在你要求 Claude 应用之前，文件不会有任何变化。即便要应用，也可以逐条选择。

Q. /doctor prompt-audit 和 /checkup prompt-audit 有什么区别？

A. 没有区别。/checkup 是 /doctor 的别名，CHANGELOG 的 v2.1.283 条目也把 /doctor prompt-audit 和 /checkup prompt-audit 写在一起。

Q. 给 Codex 用的 AGENTS.md 也会被审查吗？

A. 会。官方文档在不带参数时的审查对象里，把 AGENTS.md 与 CLAUDE.md、CLAUDE.local.md 并列。如果你两个文件共用，它也很适合用来找两者之间的矛盾。

Q. 输入了命令，审查却没有开始。

A. 先确认版本：/doctor prompt-audit 需要 v2.1.283 及以上。版本够新还是不运行的话，检查一下是否在设置里关掉了内置的 /claude-api 技能（skillOverrides 或 disableBundledSkills）。另外，在终端里输入的 claude doctor 只诊断安装状态，不会运行这项审查。

Q. 能审查我用 API 做的应用的系统提示词吗？

A. 可以，但那要用 /claude-api prompt-audit（v2.1.221 及以上）。它会审查你的提示词、工具描述和调用 API 的代码中针对旧模型的写法，并给出 diff 建议。

参考来源

  • Claude Code 官方文档：How Claude remembers your project（“Audit your instruction files”一节）
  • Claude Code 官方文档：Commands（/doctor 和 /claude-api 两行）
  • Claude Code 官方文档：Skills（内置技能 /claude-api 的子命令及所需版本）
  • Claude Code：CHANGELOG（v2.1.283）
  • Claude Code v2.1.286 内置 /claude-api 技能中的 prompt-audit 指南（在我们自己的电脑上确认）

以上来源均于 2026年10月3日核对原文。内置指南会随 Claude Code 每个版本更新，因此审查内容可能因版本而异。