Prompt 工程审查检查清单
审查输出格式、严重性标准和质量检查流程的唯一权威来源 (SSOT)。 引用方:
commands/dev-prompt-review.md。 示例: 阅读 @../prompt-examples/template.md 获取好坏 prompt 对比——审查 agent 应以此为评估基准。
输出规则
每个问题必须包含六个部分——无例外:
- 当前行为 — prompt 当前指示 agent 做什么。描述原文产生的具体 agent 行为:执行什么动作、做什么决策、产生什么输出。包含原文引用(2-5行上下文)以便定位。不要转述——引用实际文本,然后描述其行为效果。
- 修改后行为 — 修改后 prompt 将指示 agent 做什么。描述修改文本产生的具体 agent 行为:动作、决策或输出如何变化。包含可直接复制粘贴的替换文本。不要写模糊建议如”澄清一下”——写出实际改进文本并描述 agent 行为如何变化。
- 原因 — 当前行为导致什么故障、混乱或风险的具体解释。指出具体的失败模式:哪个 agent 混淆、哪个阶段中断、哪个边界情况误处理、哪个静默故障发生。回答:”今天什么会出错?”
- 收益 — 修改后行为带来什么具体改进。指出具体结果:”防止 agent 应用错误的缓存修复”或”消除 P0 分类中 50% 的误报率”。回答:”修改后什么会变好?”每个修复必须证明其存在价值——如果无法陈述具体收益,该问题不值得报告。
- 差异摘要 — 一行行为差异说明:”Agent 当前执行 X → 修复后改为执行 Y。”让审查者无需阅读全部细节即可快速对比前后差异。
- 位置 — 问题所在的文件路径和行号。跨文件问题需引用两个文件。
理由: 审查者需要并排查看当前行为与修改后行为,以评估每个修复是否正确且有价值。没有当前行为描述,无法理解 agent 今天做什么。没有修改后行为,无法评估新行为是否更好。没有原因,无法评估风险。没有收益,无法排优先级。没有差异摘要,无法快速浏览报告。没有位置,无法在源文件中找到问题。
输出格式
所有 agent 完成后,综合生成统一报告:
# Plugin Prompt 审查报告
**日期**: {yyyy-MM-dd HH:mm}
**审查文件数**: {count}
**总问题数**: {count}
## 摘要
| 维度 | 问题数 | P0 | P1 | P2 |
|------|--------|----|----|-----|
| 语义冲突 | | | | |
| 过期引用与完整性 | | | | |
| SSOT 与重复 | | | | |
| 工作流完整性 | | | | |
| 歧义 | | | | |
| 语句精确度 | | | | |
| 边界情况与错误路径 | | | | |
| 命名一致性 | | | | |
| Token 级质量 | | | | |
## P0 — 必须修复(阻断正确执行)
### P0-{nn}: [{维度}] {简短标题}
**位置:** `{file}:{line}`(或 `{file1}` vs `{file2}`)
**验证:** {已验证 | 从 P{n} 降级 | 误报}
**差异摘要:** Agent 当前{执行 X} → 修复后 agent {改为执行 Y}。
**当前行为:**
> {源文件中问题文本的原文引用。包含足够上下文以明确定位。}
使用该文本时,agent {描述 agent 当前做什么——该文本产生的具体动作、决策或输出}。
**修改后行为:**
> {改进版本——解决问题的重写文本。必须是具体的、可复制粘贴的替换,不是模糊建议。}
使用该文本时,agent {描述 agent 将改为做什么——动作、决策或输出如何变化}。
**原因:** {1-2句解释当前行为会出什么问题。具体——指出失败模式、混淆的 agent 行为或矛盾。}
**收益:** {修改后行为带来什么具体改进。指出具体结果:防止什么故障、纠正什么 agent 行为、处理什么边界情况。}
---
## P1 — 应该修复(在边界情况中导致混乱或错误行为)
### P1-{nn}: [{维度}] {简短标题}
**位置:** `{file}:{line}`
**验证:** {已验证 | 从 P{n} 降级}
**差异摘要:** Agent 当前{执行 X} → 修复后 agent {改为执行 Y}。
**当前行为:**
> {原文引用}
使用该文本时,agent {当前行为描述}。
**修改后行为:**
> {改进版本}
使用该文本时,agent {修改后行为描述}。
**原因:** {风险解释}
**收益:** {修改后行为带来什么具体改进}
---
## P2 — 建议修复(清晰度改进)
### P2-{nn}: [{维度}] {简短标题}
**位置:** `{file}:{line}`
**差异摘要:** Agent 当前{执行 X} → 修复后 agent {改为执行 Y}。
**当前行为:**
> {原文引用}
使用该文本时,agent {当前行为描述}。
**修改后行为:**
> {改进版本}
使用该文本时,agent {修改后行为描述}。
**原因:** {清晰度改进解释}
**收益:** {修改后行为带来什么具体改进}
严重性标准
| 严重性 | 定义 |
|---|---|
| P0 | 两个文件对同一操作给出相反指令;引用指向运行时读取的不存在文件;必需参数未文档化;SSOT 概念被另一文件的副本所矛盾;工作流交接传递接收方不处理的字段;新规则静默破坏或覆盖已有正常功能而无明确废弃声明 |
| P1 | 可能导致 agent 采取错误操作的歧义规则;与配置漂移的硬编码值;可能故障模式缺少错误处理;规则被重述(非矛盾副本)而非引用 SSOT;文件间逐字复制内容;故障路径无 else/otherwise 子句的悬空条件 |
| P2 | 轻微措辞歧义;风格不一致;冗余陈述;应更强的弱祈使句;语义重复(同一想法不同表述);可从附近上下文解析的无锚代词 |
质量检查类别
检查按其针对的模型行为分组。对于每项检查,agent 必须评估:(1) 此 prompt 是否正确利用或考虑了该行为?(2) 检查失败时会发生什么具体故障?
阅读 @prompt-engineering-standards.md 获取每个检查类别背后的完整原则。
类别 A: 清晰性与直接性(Claude 遵循明确指令;对模糊指令推断能力差)
| 检查 | 标记内容 | 失败原因(模型行为) | 严重性 |
|---|---|---|---|
| 弱祈使句 | “Consider…“、”Try to…“、”You might want to…“、”It may be helpful to…” | Claude 将含糊措辞视为可选指导而非指令。在上下文压力下(长对话),可选指导首先被跳过。 | P2 |
| 缺少上下文/动机 | 规则未解释 WHY(如”NEVER use git amend”但未解释重试安全原因) | Claude 从有解释的规则中更好地泛化。没有”为什么”,agent 机械应用规则,在规则应/不应适用的边界情况中出错。引用 Anthropic:”提供指令背后的上下文或动机帮助 Claude 更好地理解你的目标。” | P2 |
| 无锚代词 | 指代对象不明确的”it”、”this”、”that”、”these” | Claude 使用最近的合理指代物来解析歧义代词,这可能不是预期对象。在多步骤指令中,讨论 csproj 和 cs 文件后说”update it”确实有歧义。 | P1 |
| 对 Claude 4.6 的过度提示 | “CRITICAL: You MUST use this tool when…“、”ALWAYS be thorough”、”If in doubt, use [tool]” | Claude 4.6 比之前模型主动得多。针对 Claude 3.5 的反懒惰提示现在导致过度触发——工具每轮都触发、探索读取 50+ 文件、子 agent 对简单任务也生成。引用 Anthropic:”这些模型现在可能过度触发。解决方法是减弱激进措辞。” | P1 |
类别 B: 示例与演示(few-shot 是最可靠的引导机制)
| 检查 | 标记内容 | 失败原因(模型行为) | 严重性 |
|---|---|---|---|
| 缺少 few-shot 示例 | 关键操作(工具调用、输出 JSON、csproj 转换、分类决策)没有具体输入/输出示例 | 没有示例时 Claude 即兴发挥格式。Anthropic:”示例是引导 Claude 输出格式、语调和结构最可靠的方式之一。几个精心设计的示例能显著提高准确性和一致性。”对于本插件,缺少 skill 输出格式示例意味着消费 agent 会猜测字段名。 | P1 |
| 抽象示例 | 示例用散文描述模式而非展示精确的 XML/JSON/命令 | Claude 逐字复制示例结构。抽象描述(”add the package to the right group”)产生抽象输出。只有具体示例(<PackageReference Include="X" NoWarn="NU1701" />)产生具体输出。 |
P2 |
| 非多样化示例 | 所有示例只展示多分支决策的同一分支(如只有 REPLACE 映射示例,没有 KEEP_DUAL) | Claude 从示例集学习模式。如果所有示例展示一个分支,Claude 对歧义情况默认选该分支。引用 Anthropic:”覆盖边界情况,变化足够多以免 Claude 学到意外模式。” | P2 |
类别 C: 结构与排序(Claude 遵循编号序列;跳过散文中嵌入的步骤)
| 检查 | 标记内容 | 失败原因(模型行为) | 严重性 |
|---|---|---|---|
| 缺少思维链结构 | 多步决策用散文段落描述而非编号步骤 | Claude 逐步处理编号序列。散文嵌入序列作为整块处理——步骤可能被重排或跳过。引用 Prompt Engineering Guide:带明确步骤的思维链在复杂任务上优于隐式推理。 | P2 |
| 缺少 else/otherwise | if/when 子句没有负面情况的显式回退 |
Claude 在未指定分支时自行发明回退行为。发明的行为可能合理但跨运行不可预测——自主 agent 中最常见的歧义模式。 | P1 |
| 查询下方的长数据 | 参考数据(包映射、错误表)放在使用它的决策逻辑之后 | Anthropic 测试:长上下文 prompt 末尾的查询将响应质量提高多达 30%。对于加载 package-map.md 或 project-map-list.md 的 skill,将数据放在决策步骤之前可提高分类准确性。 | P2 |
类别 D: 契约与边界(上下文边界处的 agent 不共享隐式信息)
| 检查 | 标记内容 | 失败原因(模型行为) | 严重性 |
|---|---|---|---|
| 未文档化的输出 schema | Agent 或 skill 没有列出字段名、类型和可能值的 Output 部分 | 消费 agent/阶段必须知道精确字段名才能读取。没有契约,字段名不匹配是静默的——buildStatus vs LocalBuildStatus 产生 null 值而非错误。 |
P0 |
| 缺少输入参数 | Agent 或 skill 定义没有正式 Input 表(参数名、类型、必需/可选、来源) | 调用 agent 必须知道传什么。没有契约,缺失参数导致子 agent 失败或即兴发挥。测试:agent 是否能仅凭 Input 表(不依赖父级上下文)正常工作? | P0 |
| 隐式上下文继承 | 指令假设 fork 的 agent 或子 agent 能看到未作为参数传递的父级变量 | Fork 的 agent 从零开始。引用 Claude Code System Prompts:worker “直接执行指令”,只有接收到的内容。引用 Claude Code Best Practices:”子 agent 在独立上下文窗口运行,汇报摘要。”不在 Input 表中的值不可见。 | P0 |
| 损坏的阶段契约 | Phase N 的输出字段名/类型与 Phase N+1 的输入字段名/类型不匹配 | 消费者读取生产者命名不同的字段时静默 null/undefined。对照 rules/phase-data-contract.md——跨阶段变量命名的 SSOT。 |
P0 |
类别 E: 验证与锚定(agent 在没有可执行检查时会合理化成功)
| 检查 | 标记内容 | 失败原因(模型行为) | 严重性 |
|---|---|---|---|
| 无命令的自检 | <self-check> 项说”verify X works”但未指定要运行的命令和预期输出 |
引用 Claude Code Best Practices:”Claude 能验证自己的工作时表现显著更好。”没有命令的检查不是 PASS——而是跳过。Claude 会合理化:”代码看起来正确”然后继续。 | P1 |
| 缺少验证步骤 | 操作没有明确的”检查结果”指令(如”create PR”但没有”verify PR URL from API response”) | 没有验证,静默故障传播。agent 报告成功因为没有抛出错误——但 PR 实际未创建,或 csproj 是损坏的 XML。 | P1 |
| 间接值引用 | 指令说”Per @file for format”但不在使用点内联关键值 | Claude 需要跟随 2+ 跳才能到达值。上下文压力下跳转被跳过,agent 即兴发挥。修复:内联值并引用来源:NoWarn="NU1701" PrivateAssets="all" (per @nu1701-handling.md)。 |
P1 |
类别 F: 组合与规模(上下文窗口是首要约束)
| 检查 | 标记内容 | 失败原因(模型行为) | 严重性 |
|---|---|---|---|
| 过大的 prompt 文件 | Agent/command >260 行,skill >300 行(按 @prompt-engineering-standards.md Prompt Size Discipline) | 引用 Claude Code Best Practices:”如果 CLAUDE.md 太长,Claude 会忽略一半因为重要规则淹没在噪音中。”同样适用于任何 prompt 文件。Agent 优先处理早期内容,浏览后期内容——底部三分之一的规则应用不一致。 | P1 |
| 单句 skill/agent 描述 | Frontmatter description 缺少触发短语、使用示例和何时不用的指导 | 引用 Claude Code Sub-Agents:触发丰富的描述(3-5个触发场景)优于单句摘要的 agent 路由。Claude 用 description 决定是否调用 skill——模糊描述导致误路由或不调用。 | P1 |
| 仅通过名称的工具调用 | 指令说”use search_code”但不展示精确参数和预期响应 | Claude 猜测参数。在本插件中,search_code 需要 project: ["O365 Core"](不是 "ControlPlane")——猜测会用错值。 |
P1 |
| 散文段落式护栏 | 约束嵌入段落中而非每行一条规则的列表/表格 | 引用 Claude Code System Prompts:行为护栏平均 16-102 token,作为独立微规则陈述。表格和列表逐行解析;散文段落作为整块处理,个别规则模糊在一起。 | P2 |
| 冗长护栏(>60 token) | 单条护栏规则超过 60 token | 引用 Claude Code System Prompts:平均护栏 47 token。长规则稀释影响力。如果规则需要 >60 token,可能是两条规则或包含不必要解释。 | P2 |
| 未标注的故意冗余 | 使用点处的重复值没有 (per @SSOT-file) 标注 |
审查者无法区分故意的可靠性冗余和意外的 SSOT 违规。在每个故意重复的值后加 (per @file) 以便检测漂移。 |
P1 |
类别 G: 向后兼容性(现有功能不得中断)
| 检查 | 标记内容 | 失败原因(模型行为) | 严重性 |
|---|---|---|---|
| 向后兼容性违规 | 新规则、映射或功能静默覆盖或使现有正常行为失效,没有明确确认或废弃声明 | Agent 遵循遇到的最新指令。如果新规则与现有规则矛盾但没有明确取代声明,agent 可能在行为间摇摆,取决于先加载哪个文件。引用 Claude Code Best Practices:”像对待代码一样对待 CLAUDE.md:出问题时审查它。”同样适用于所有 prompt 文件。 | P0 |
类别 H: Token 级质量模式(按 @../prompt-examples/prompt-engineering-for-skills.md——降低决策点的条件熵)
| 检查 | 标记内容 | 失败原因(模型行为) | 严重性 |
|---|---|---|---|
| 散文分支而非决策树 | 多路径决策用”if X then Y, if Z then W”散文描述而非可视 ├─ YES → / └─ NO → 树 |
散文将条件分散在句子中——注意力在多个位置稀释。树将条件和动作在 token 序列中相邻放置,集中注意力产生确定性行为。运行10次:散文约30%偏差,树约5%。 | P2 |
| 缺少输出 schema | Skill/agent/command 产生结构化输出但没有 <output_schema> 或列出枚举字段名和值类型的输出表 |
Schema token 在解码时充当”轨道”——每个字段值由 schema 键引导。没有 schema,模型自行发明格式,产生不一致输出,下游消费者无法解析。 | P1 |
| 远距离约束 | 约束放在远离其管辖动作的”通用规则”部分 | Transformer 注意力有位置偏差——附近 token 获得更高注意力分数。距其动作 500 token 的约束应用不一致。将约束移到动作旁边:<constraint> 放在 <task> 内,或子弹点紧接步骤下方。 |
P2 |
| 缺少锚定模板 | Agent 必须产生结构化输出(报告、代码块、XML)但未提供填充好的模板/示例 | 没有模板,模型从”报告应该长什么样”的通用分布中采样。具体模板将输出拉向模板的分布,大幅降低方差。 | P1 |
| 多动作指令 | 单句映射到多个隐式动作(”check and fix issues then run tests”) | 模型将一条清晰指令可靠地映射到一个工具调用。多动作句子导致动作合并、跳过或重排。拆分:”1. Run X. 2. Run Y. 3. If fail → Z.” | P2 |
| 只有否定没有替代 | “Don’t modify the database” / “Never use sudo” 但不指定应该做什么 | “Don’t do X”抑制 token 但不提升替代——模型知道哪里不能去但不知道该去哪。不稳定。修复:”Database changes → generate migration file, never raw SQL.” | P2 |
| 缺少 XML 语义边界 | Skill/agent/command 文件仅用 markdown 标题分隔部分——没有 <context>、<steps>、<boundaries>、<output_schema> 标签 |
XML 标签创建硬语义边界。不同标签内的内容被视为独立部分,减少交叉污染。Markdown 标题是较软边界——上下文压力下相邻部分内容会互相渗透。 | P2 |
| Few-shot 无推理 | <example> 块只展示 input→output,没有展示模型应如何推理的 <thinking> 步骤 |
示例中的 <thinking> 模式被泛化到模型自身的推理中。没有它,模型学到输出模式但不学决策过程——在边界情况中脆弱。 |
P1 |
| 无认知卸载 | 多步推理留在隐式状态(”analyze the error and fix it”)而非显式编号步骤 | LLM 没有工作记忆。每个推理步骤消耗整个上下文的注意力。写出步骤提供”外部记忆”——每步只关注上一步的输出。决策树 = 分支的认知卸载。思维链 = 推理的认知卸载。 | P2 |