Claude Code 的 prompt-audit：先删掉过期指令，再让 agent 写代码

2026年10月12日· 约 4 分钟阅读

部署从容器换成静态托管，任务说明还写着“重建容器”；项目早就用了 pnpm，旧 Skill 却坚持 npm。遇到这种事，我会先查指令文件，而不是继续补一句“请严格遵守最新要求”。旧命令留在仓库里，下次会话就可能重新读到它。

Claude Code 在 9 月 25 日的更新日志中加入了 /doctor prompt-audit，同一份日志还记录了报告排序的改进，让失效路径、失效命令和互相矛盾的文件优先出现。[7] 我建议先用它清理已有指令，再考虑添加新规则。

审计先出报告，不会自动改文件#

官方文档说明，审计会检查面向旧模型的提示方式、不存在的文件或命令，以及彼此冲突的指令。它返回发现和修改建议，只有你要求应用时才会改文件。[17]

默认范围包含 CLAUDE.md、CLAUDE.local.md、AGENTS.md，以及项目和用户 .claude/ 下的规则、Skills、命令、子代理与输出风格；也可以传入路径，只查一个文件或目录。[17] 这点很实用：部署 Skill 过期时，不必顺手重写整套个人配置。

我会把审计结果当线索。命令不存在，可能确实该删，也可能只是当前机器没装工具。路径没找到，可能是写错了，也可能属于构建产物。先查项目配置，再决定删哪条，别把缺少环境误判成流程已经废弃。

先在终端确认版本，再进入项目：[7]

claude --version
claude

prompt-audit 需要 Claude Code v2.1.283 或更高版本，并通过内置 /claude-api Skill 运行；禁用该 Skill 或禁用全部内置 Skills 时，审计不可用。[17] 命令缺失时先检查这些条件，不要让 agent 编出一个替代命令。

假设项目已有 .claude/skills/deploy，在会话中输入：[17]

/doctor prompt-audit .claude/skills/deploy

接着限定处理方式：

只给报告，暂不修改。
每条发现列出文件位置、旧指令、建议改法。
部署命令须与 package.json 和当前 CI 配置核对。
无法确认的内容标为待核查，不要直接删除。

看完报告再选中具体条目应用，例如只把旧部署步骤替换成当前构建和推送流程。不要用“全部优化”授权它顺手改用户级规则。我更愿意分两次处理：先修会执行错的命令，再删冗余说明。

以 pnpm 的静态博客为例，先读 package.json，确认 build 脚本，再查看锁文件和 CI 的安装步骤。若依赖没有变化且本地已经安装，可以直接构建；需要安装时再执行冻结锁文件的安装。下面是这个场景的示例，不是所有仓库通用的命令：

CI=true pnpm install --frozen-lockfile
CI=true pnpm run build
git diff --check
git diff -- .claude/skills/deploy

我会看两类证据：构建是否退出成功，指令 diff 是否只修改了已确认的流程。构建过了，却把发布分支写错，依然不能合并。涉及推送的说明还应写清远端和分支的检查方法，避免把“执行命令”当成“发布完成”。

这里有个边界：CLAUDE.md 和自动记忆是上下文，不是强制配置；官方建议，对必须阻止的动作使用 PreToolUse hook。[17] 因此“不得上传密钥”可以写进说明，但不能把说明本身当成防泄露措施。审计修的是指令内容，不会替你建立权限隔离。

只改部署 Skill 还不够。我建议把被替换的命令当关键词，搜索项目里的指令和 CI 配置：根目录说走静态发布，子目录仍写容器部署，两边分别看都像是有效说明。审计默认覆盖多种指令文件，但局部审计只检查你指定的范围。[17] 查完局部问题后，可以再跑一次不带路径的审计，专门看有没有残留冲突。

处理报告时，给每条发现留一个决定：已修复、保留并说明原因、暂缓核查。例如老脚本仍用于本地预览，就把用途写清楚，不要因为线上不用就删掉。若一个建议没有文件位置，或者声称命令无效却没检查脚本定义，先让 agent 补证据。

最后用下一次真实任务检验效果：让它只读说明并复述准备执行的命令，确认它没有捡回旧流程，再允许修改。这个步骤不证明永远不会出错，但能检查此次清理是否解决了你原本遇到的问题。

官方建议把每次会话都需要的构建命令、约定和易错点留在 CLAUDE.md；多步骤流程或局部规则放进 Skill 或路径规则。[17] 我会在改完后留一句迁移原因，比如“本站现由 Git 推送触发静态部署，旧容器步骤不再适用”。这样下一次审计看到差异，能知道这是刻意选择。

先拿一个经常出错的 Skill 做小范围审计。保留明确规则，修正过期命令，再跑一次它要求的验证。不要因为报告建议更多，就把工作范围一起扩大。