跳到主要内容

用 Claude Code 的 prompt-audit 做一次项目规则的“体检与整理”

不少项目里都经历过这种情况：半年前顺手写下的 CLAUDE.md、零散的 .claude/rules/ 规则，以及随手定义的命令（command），当初是为了让 AI 更快上手。但今天一跑起来，AI 却频繁报出“路径不对”、“npm/pnpm 混用”、“脚本不存在”之类的问题。

这不是你记性不好，而是规则和项目现状已经不同步了。与其在每次对话里反复纠正，不如一次性用官方提供的工具做一次有依据的整理：用 /doctor prompt-audit 检查项目规则，保留有价值的约束，修正明显的矛盾。

下面按“为什么做 → 如何审计 → 如何判断与修改 → 如何验证”的顺序写清楚。

一、先确认环境：你有这个功能吗？​

Claude Code v2.1.283 的发布记录里明确加入了 /doctor prompt-audit（别名 /checkup prompt-audit）这一诊断入口，它能够：

  • 检查 CLAUDE.md、skills、agents 和 commands 中面向旧模型的提示模式；
  • 优先报告：失效路径、过时命令、互相矛盾的指令文件；
  • 同时保留官方仍支持的 thinking 关键词（不会“一刀切”删掉你写好的提示）。

发布记录参考：https://github.com/anthropics/claude-code/releases/tag/v2.1.283

1. 确认版本​

在终端里先看看自己安装的版本：

claude --version
  • 如果版本号 ≥ 2.1.283，说明你的环境已包含 prompt-audit；
  • 如果是原生安装但想更新，运行官方命令即可：
claude update

2. 进入项目目录并启动会话​

cd /path/to/your/project
claude

在交互界面中（而不是在终端命令行），输入：

/doctor prompt-audit

注意：

  • claude doctor（不带斜杠）是安装和设置诊断，不启动会话；
  • /claude-api prompt-audit 则是检查你的应用代码里使用的 Claude API 提示词与工具描述；
  • 这里我们用项目配置的 /doctor prompt-audit，它基于当前工作目录加载规则。

二、理解 prompt-audit 会“看”什么​

发布后的审计记录会重点检查 CLAUDE.md、skills、agents 和 commands 里的提示模式；而人工核对时，你同样需要查看个人偏好、项目级配置以及按路径规则引入的指令。下面是一些常见的文件位置，可以作为你核对清单：

  • CLAUDE.local.md —— 个人项目级指令，它会和其他内容一起进入上下文，并不是保证覆盖其他指令的机制。
  • .claude/rules/ —— 可以配置路径作用范围，用来限定规则生效的区域。

它会特别关注：

  • 失效路径：规则里写死的路径，如 /scripts/build.sh，但实际已改名为 build.ts 或移到了 /bin/；
  • 过时命令：如规则要求“使用 npm run dev”，但项目已统一用 pnpm、bun 或 Yarn；
  • 相互矛盾：一个文件要求“所有改动先写长篇规划”，另一个要求“简单修改直接实施”；
  • 残留旧模型提示：面向早期 Claude 的冗余格式描述，影响当前解析效率。

三、解读审计报告：从问题到判断标准​

有了系统性的核对清单，读者可以据此逐项评估项目是否满足核心要求。在实操中，建议将这份清单转化为可操作的检查流程：以 Claude Code 的 /doctor 命令为起点，它首先会报告发现的具体问题；随后，在执行任何修改之前，该工具会请求确认。在此基础上，你可以进一步要求列出相关文件位置、原始规则依据、问题产生的根本原因以及建议的改动方案。这些输出将帮助你结合项目证据逐条核对，确保每一步判断都建立在清晰的事实与逻辑之上。

你不需要一次性把所有建议全改。建议的处理流程是：

  • 把每条建议追溯到原句：看它到底在哪个文件、哪一行；
  • 对照项目证据：package.json、实际脚本、锁文件（package-lock / pnpm-lock）、团队约定等；
  • 然后决定三类操作：
    • 保留（确实必要的安全/质量约束）；
    • 修正（路径、工具、逻辑错误）；
    • 删除或移动（过时、冲突或重复）。

三个典型问题示例​

  1. 工具不一致

    • 规则原文：“使用 npm install 安装依赖，配合 package.json。”
    • 项目现状：已迁移到 pnpm，pnpm-lock.yaml 存在，实际命令是 pnpm i。
    • 判断：修正为“使用 pnpm 安装依赖”。

  2. 路径失效

    • 规则原文：“执行脚本位于 /scripts/lint.sh。”
    • 项目现状：脚本已移到 /tools/lint.js 且是 Node 直接调用。
    • 判断：更新路径，并检查是否仍适用于当前语言与运行方式。

  3. 语义冲突

    • 规则 A：“任何改动前必须先写详细计划。”
    • 规则 B：“对于简单修复可直接实施。”
    • 判断：保留更具体、更有操作性的（B），或合并为“按改动复杂度决定：重大改动先规划，小改动可直改”。

四、使用审计会话：一条一条确认修改​

在 /doctor prompt-audit 的对话窗口中，你可以像和一个“懂项目的 AI 助理”沟通。以下是一些自然、可复制的审阅请求示例：

  • “把每条建议的文件位置和原因用列表形式列出来。”
  • “对于‘路径失效’这一条，帮我确认实际脚本位置，并给出修改后的句子。”
  • “这两个规则互相矛盾，结合项目团队约定（前端优先 npm，后端用 yarn），给出一个统一表述。”
  • “哪些约束是真正必要的（比如安全扫描、格式检查），哪些可能只是历史残留？”

你可以要求它：

  • 先输出“文件位置 + 原因 + 建议修改”；
  • 然后你自己在终端或编辑器里查看差异；
  • 最后再决定是否采纳。

这样既避免盲目听从，也能让 AI 给出可追溯的建议。

五、整理与检查：git 辅助，一次一个问题​

改动规则时，建议按“一个明确问题”为单位推进，方便回看和复现。

1. 查看改动状态​

git status --short

重点关注对以下路径的未跟踪或已跟踪变更：

  • CLAUDE.md
  • .claude/CLAUDE.md（如果存在）
  • .claude/rules/*
  • 相关的 Skill / Agent / Command 文件

2. 查看未暂存差异​

git diff -- CLAUDE.md .claude/

在查看未暂存差异时，这几个命令各有各的用途：

  • git diff 默认就是未暂存的改动；
  • git diff -- <other-file> 可以限定查看该路径下已跟踪文件的未暂存差异；
  • 暂存后的改动用 git diff --cached -- <other-file>。 如果有些新文件尚未被 git 跟踪，那就直接用编辑器打开查看内容即可。

3. 提交策略建议​

  • 把“prompt-audit 审计与整理”作为一个独立提交：
    • 说明本次更新基于 v2.1.283 的 /doctor prompt-audit；
    • 列出主要修改类型（路径修正、工具统一、冲突合并等）；
  • 之后再有新的规则调整，再单独提交。

六、验证：新会话里“跑”一次规则​

审计和修改完成不代表真正生效。Claude Code 对规则的加载行为有一些细节需要确认：

1. 确认实际加载了哪些文件​

在新会话中输入：

/context

检查：

为了精确知道当前生效的是哪些指令，请在 CLI 中运行 /context 命令（或查看 Memory files 所呈现的状态）。启动时会自动加载当前目录及所有祖先目录中的 CLAUDE.md 等文件；当读取某个子目录的文件时，该子目录下的 CLAUDE.md 也会被纳入；而设置了路径匹配条件的规则，则在读取对应匹配文件时才被激活。因此，建议先定位到你目标操作的文件，再核对其实际加载的指令集，同时留意是否存在已加载但已过时的旧文件。你可以用 /memory 列出所有可选项，选择一个后进行编辑；注意部分目录对应的文件尚未创建，需避免误操作。

2. 用一个“小任务”检验行为​

设计一个能触发规则的小任务，例如：

  • “用项目里定义的工具执行一次 lint。”
  • “按照 CLAUDE.md 中要求的步骤提交一个小修改。”
  • “如果某条路径或命令不存在，明确说明，而不是假设。”

观察：

  • 是否自动使用更新后的路径；
  • 是否还残留旧工具的调用；
  • 对于之前发现“有约束”的场景，AI 是否仍然遵守（如格式检查、安全扫描等）； 如果在新会话中仍发现不一致，下一步请回看 /context 已加载的文件集合以及当前任务的具体指令，定位还有哪些冲突或错误事实需要修正。

七、一些快速检查清单​

在整理完成后，用这个清单自测：

  • 已确认 claude --version ≥ 2.1.283；
  • 已在当前项目目录内运行 /doctor prompt-audit；
  • 审计报告中每条建议都追溯到具体文件位置与原因；
  • 已用 git 查看并理解未暂存的改动范围；
  • 对明显失效路径、过时工具、冲突规则已完成修正或删除；
  • 对必要的安全/质量约束（如 lint、测试条件）做了保留或强化；
  • 在新会话中通过 /context 确认实际加载的规则集；
  • 通过一个小任务验证了规则在实际对话中的行为。

八、进一步参考​

如果你想在项目里长期保持规则的清晰和可用，建议结合官方文档形成一套自己的“维护习惯”：

记错路径、乱调工具、过度规划或跳步，这些问题在自动化环境中会被放大；而把规则当成项目资产持续维护，则是长期可靠的保障。实际操作建议：从项目目录在终端启动 claude 后，进入 Claude Code 的交互会话中运行 /doctor prompt-audit —— 注意这是会话内的诊断命令，不是操作系统终端里的斜杠指令。

相关阅读​