enhance-prompts

enhance-prompts

分析提示词的清晰度、结构、示例和输出可靠性。

解析参数

const args = '$ARGUMENTS'.split(' ').filter(Boolean);
const targetPath = args.find(a => !a.startsWith('--')) || '.';
const fix = args.includes('--fix');

与 enhance-agent-prompts 的区别

技能	关注点	适用场景
enhance-prompts	提示词质量（清晰度、结构、示例）	通用提示词、系统提示词、模板
enhance-agent-prompts	Agent 配置（frontmatter、工具、模型）	带有 YAML frontmatter 的 Agent 文件

工作流

1. 运行分析器 - 执行 JavaScript 分析器以获取检测结果：

   node -e "const a = require('./lib/enhance/prompt-analyzer.js'); console.log(JSON.stringify(a.analyzeAllPrompts('.'), null, 2));"
   

   对于特定路径：a.analyzeAllPrompts('./plugins/enhance') 对于单个文件：a.analyzePrompt('./path/to/file.md')

2. 解析结果 - 分析器会返回包含 summary 和 findings 的 JSON

3. 筛选 - 根据 --verbose 标志应用确定性筛选

4. 报告 - 将检测结果格式化为 Markdown 输出

5. 修复 - 如果设置了 --fix 标志，则根据检测结果应用自动修复

JavaScript 分析器（lib/enhance/prompt-analyzer.js）实现了所有检测模式，包括基于 AST 的代码验证。以下模式仅供参考。

---

提示词工程知识参考

系统提示词结构

有效的系统提示词包括：角色/身份、能力与约束、指令优先级、输出格式、行为指示、示例、错误处理。

最简模板：

<system>
You are [ROLE]. [PURPOSE].
Key constraints: [CONSTRAINTS]
Output format: [FORMAT]
When uncertain: [HANDLING]
</system>

XML 标签（Claude 专用）

Claude 针对 XML 标签进行了微调。可使用：<role>、<constraints>、<output_format>、<examples>、<instructions>、<context>

<constraints>
- Maximum response length: 500 words
- Use only Python 3.10+ syntax
</constraints>

少样本示例

• 2-5 个示例最为理想（有研究支持）
• 包含边缘情况，并确保格式一致
• 从零样本开始，仅在需要时添加示例
• 相关时同时展示正确和错误示例

思维链（CoT）

使用 CoT	不使用 CoT
复杂的多步推理	简单的事实性问题
数学和逻辑问题	分类任务
代码调试	模型具备内置推理能力时

要点： 现代模型（Claude 4.x、o1/o3）会在内部进行 CoT。“逐步思考”是多余的。

角色提示

有帮助： 创意任务、语气/风格、角色扮演
没有帮助： 准确性任务、事实检索、复杂推理

更好的写法：“系统地处理并展示过程”，而不是“你是一位专家”。

指令层级

优先级：系统 > 开发者 > 用户 > 检索内容

当提示词包含多个约束来源时，应明确说明优先级。

否定式提示

正向替代方案比否定表达更有效：

效果较差	效果较好
“不要使用 Markdown”	“使用散文段落”
“不要含糊其辞”	“使用具体语言”

结构化输出

• 基于提示词：可靠性约为 35.9%
• 强制执行架构：可靠性为 100%
• 始终提供架构示例并验证输出

上下文窗口优化

中间信息遗失： 模型对开头和结尾的重视程度更高。

将关键约束放在开头，示例放在中间，错误处理放在结尾。

扩展思考

高层级指令（“深入思考”）比逐步指导更有效。对于现代模型，“逐步思考”是多余的。

反模式速查

反模式	问题	修复方法
模糊指代	“上面的代码”会丢失上下文	明确引用内容
只给出否定要求	只说“不要做 X”，却不提供替代方案	明确说明应该做什么
过度强调	“重要：必须”	使用普通表达
多余的 CoT	浪费令牌	让模型自行处理
关键信息埋得太深	中间信息遗失	放在开头或结尾

---

检测模式

1. 清晰度问题（高确定性）

模糊指令： “通常”“有时”“尽量”“如果可能”“也许”“可以”

仅有否定约束： 使用“不要”“绝不”“避免”，却没有说明应该怎么做

过度强调： 过多使用大写字母（CRITICAL、IMPORTANT）、多个感叹号

2. 结构问题（高／中确定性）

缺少 XML 结构： 复杂提示词（>800 个 token）未使用 XML 标签

章节不一致： 标题样式混杂、跳过层级（H1→H3）

关键信息埋得太深： 重要指令位于中间 40% 的位置，约束条件放在示例之后

3. 示例问题（高／中确定性）

缺少示例： 复杂任务没有少样本示例，格式要求没有示例

数量不理想： 只有 1 个示例（最佳数量：2-5 个），或超过 7 个（内容臃肿）

缺少对比： 没有标注好／坏示例，也没有边缘情况

4. 上下文问题（中确定性）

缺少 WHY： 规则没有解释原因

缺少优先级： 多个约束章节之间没有冲突解决方案

5. 输出格式问题（高／中确定性）

缺少格式： 内容较多的提示词未指定格式

JSON 没有架构： 要求输出 JSON，但没有示例结构

6. 反模式（高／中／低确定性）

冗余思维链（高）： 对现代模型使用“逐步思考”

过度规定（中）： 10 个以上编号步骤，过度微观管理推理过程

提示词臃肿（低）： 超过 2500 个 token，指令冗余

指代模糊（高）： “上面的代码”“如前所述”

---

自动修复实现

1. 过度强调

将 CRITICAL 替换为 critical，将 !! 替换为 !，移除过多的大写字母

2. 将纯否定改为正向表述

为“不要”类语句提供正向替代建议

---

输出格式

## Prompt Analysis: {prompt-name}

**File**: {path}
**Type**: {system|agent|skill|template}
**Token Count**: ~{tokens}

### Summary
- HIGH: {count} issues
- MEDIUM: {count} issues

### Clarity Issues ({n})
| Issue | Location | Fix | Certainty |

### Structure Issues ({n})
| Issue | Location | Fix | Certainty |

### Example Issues ({n})
| Issue | Location | Fix | Certainty |

---

模式统计

类别	模式	可自动修复
清晰度	4	1
结构	4	0
示例	4	0
上下文	2	0
输出格式	3	0
反模式	4	0
总计	21	1

---

### 示例：指令模糊

<bad_example>

You should usually follow best practices when possible.

不好的原因：模糊的限定词会降低确定性。 </bad_example>

<good_example>

Follow these practices:
1. Validate input before processing
2. Handle null/undefined explicitly

好的原因：指令具体且可执行。 </good_example>

示例：纯否定约束

<bad_example>

- Don't use vague language
- Never skip validation

不好的原因：只说明了不能做什么。 </bad_example>

<good_example>

- Use specific, deterministic language
- Always validate input; return structured errors

好的原因：每项约束都包含正向行动要求。 </good_example>

示例：冗余的思维链

<bad_example>

Think through this step by step:
1. First, analyze the input
2. Then, identify the key elements

不好的原因：现代模型会在内部完成这些步骤，浪费 token。 </bad_example>

<good_example>

Analyze the input carefully before responding.

好的原因：提供高层指导，不对过程进行微观管理。 </good_example>

示例：缺少输出格式

<bad_example>

Respond with a JSON object containing the analysis results.

不好的原因：没有架构或示例。 </bad_example>

<good_example>

## Output Format
{"status": "success|error", "findings": [{"severity": "HIGH"}]}

好的原因：具体的架构展示了准确的结构。 </good_example>

示例：关键信息埋得太深

<bad_example>

# Task
[task]
## Background
[500 words...]
## Important Constraints  <- buried at end

不好的原因：产生中间信息丢失效应。 </bad_example>

<good_example>

# Task
## Critical Constraints  <- at start
[constraints]
## Background

好的原因：将关键信息放在开头，此处注意力最集中。 </good_example>

---

约束

• 仅对高确定性问题应用自动修复
• 保留原有结构和格式
• 根据上方嵌入的知识参考进行验证