prompt-budget-preflight

用途

Prompt Budget Preflight 是一个在调用 Agent 工具之前运行的预检技能。它耗时不到 30 秒，用于防止子代理最常见的失败模式：被拒绝并返回「Prompt is too long」。

为什么需要它

子代理在你的提示被追加之前，就已经继承了大量基础上下文，包括：

全局 ~/.claude/CLAUDE.md
项目 .claude/CLAUDE.md 链（包括通过 @ 引用的规则文件）
子代理当前工作目录中任何自动加载的插件 CLAUDE.md
MEMORY.md 和自动记忆条目
所选 subagent_type 的系统提示
子代理可见的工具定义

根据一次 9 次生成的会话遥测数据：

生成类型	提示大小	结果
Explore × 2（通用）	每次约 900 词	均被拒绝——「Prompt is too long」，使用 0 token，往返 2.3–2.7 秒
命名专家 × 7（architecture / perf / security / dx / ux / researcher / code-reviewer）	每次约 200–400 词	7 个全部成功

拒绝率：22%。每次拒绝都浪费约 3 秒和一个决策周期。

5 段式最小可行提示

目标总计约 300 词。如果超过 800 词，几乎可以肯定存在冗余。

TARGET
- 绝对文件路径或目录范围
- 清晰的范围内/范围外边界
TASK
- 一句话：要产出什么
- 明确说明只读还是写入
FORMAT
- 输出形态（YAML、表格、项目符号）
- 词数上限或行数上限
- 任何必需字段 / schema
CONSTRAINTS
- 不要做什么
- 要避免的路径 / 模式 / 子目录
- 词数限制的执行提示
RULES（可选，仅在适用时）
- 插件特定的护栏
- 「不要遵循 interview-first 工作流——这是一次审计」
- 「不要写文件——仅做分析」

预检清单

每次 Agent 调用前，回答：

子代理类型：我使用的是已经带有相关系统提示的命名专家，还是通用类型（Explore、general-purpose）？优先使用专家——见 skills/agentic-patterns/SKILL.md 第 4 部分。
提示长度：我的提示是否在 500 词以内？如果超过 800，就精简。
枚举测试：我是否在重复列出代理可以 grep 到的事实？如果是，删掉它们——说「grep for X」而不是粘贴 X。
上下文继承：代理是否会在一个 CLAUDE.md 很大（>4KB）且与任务无关的目录中生成？如果是，加入一行 RULES 告诉它忽略该文件的工作流规定。
输出上限：我是否指定了词数上限和/或行数上限？如果没有，加上一个。

失败模式处理手册

如果代理拒绝并返回…	这样做
「Prompt is too long」	删减枚举事实；把通用子代理换成命名专家；加入 RULES 行告诉它跳过目录 CLAUDE.md 工作流
空输出或存根输出	提示太模糊——加入具体的 file:line 引用和一个输出形态的完整示例
跑题漫谈	缺少 CONSTRAINTS 段——加入明确的「不要探索 X / Y / Z」
超时（简单任务超过 5 分钟）	缺少词数上限 + 缺少范围边界——两者都加上

模板——复制粘贴即可开始

You are analyzing <SCOPE>.

TARGET: <absolute paths>
TASK: <one sentence; read-only or write>
FORMAT:
  <schema / shape>
  Keep under <N> words.
CONSTRAINTS:
  - Do not <X>
  - Do not explore <Y>
RULES (if applicable):
  - Ignore the <plugin-name> CLAUDE.md's interview-first workflow;
    this is an audit, not a setup run.

何时跳过预检

提示少于 2 段，且子代理类型匹配某个命名专家。
任务范围非常明确，错误输出不会导致重试成本（例如「查找所有匹配 X 的文件」）。

其他所有情况：运行上面的 5 问清单。它比一次被拒绝的生成更划算。