prompt-improver

提示词改进器

概述

一项根据大模型/Agent 通用最佳实践分析并改进提示词的技能。它着重关注可验证性、明确的范围、清晰的约束和上下文精简，让 Agent 无需反复沟通即可执行任务。

如果你在 Claude Code 中运行，还应阅读 references/claude.md 并应用其中针对 Claude 的额外技巧。 如果你在 Codex CLI 中运行，还应阅读 references/codex.md 并应用其中针对 Codex 的额外技巧。

当输入内容是指导 Agent 的文档（例如计划文件、AGENTS.md、系统指令文档）时，应将该文档作为改进目标；指出其中的问题并提出具体改进建议，并在有帮助时提供修订稿。

工作流

第 0 步：分类任务和复杂度

对任务进行分类，并判断是否应建议明确的探索/规划阶段：

• 任务类型：修复缺陷、功能开发、重构、研究、UI/视觉、文档、运维
• 复杂度：单文件/小改动，还是多文件/影响不确定
• 风险：数据安全、隐私、安全性、兼容性、性能
• 输入类型：提示词或 Agent 指令文档（计划文件、AGENTS.md、系统指令文档）

如果任务复杂或模糊，改进后的提示词应明确要求在实施前进行探索/规划。

第 1 步：分析提示词

从以下角度分析用户提供的提示词：

1. 可验证性：是否包含让 Claude 验证自身工作的方式？
2. 具体性：是否明确指定文件、场景和约束？
3. 上下文：是否提供必要的背景信息？
4. 范围：任务范围是否恰当？
5. 预期结果：成功标准是否明确？
6. 约束：是否指定语言/运行时版本、依赖项、安全性或兼容性要求？
7. 上下文精简：提示词是否简洁聚焦，没有不必要的信息？
8. 执行偏好：是否明确说明模型应实施、提出建议，还是仅进行分析？

第 2 步：识别问题

检查以下反模式：

反模式	说明
指令模糊	缺乏具体要求，例如“做得更好”或“改进一下”
没有验证方式	缺少测试、截图或预期输出
没有验证命令	未说明如何运行测试或检查输出
范围过广	一次要求处理过多事项
上下文不足	缺少文件路径、错误消息，或对现有模式的引用
只描述症状	未要求调查根本原因
缺少约束	未说明环境、依赖项或兼容性要求
未提示探索/规划	复杂任务未要求先进行探索/规划
上下文臃肿	不必要的细节增加了 token 用量
交付内容模糊	不清楚是要规划、实施，还是仅分析
响应格式不明确	未说明对简洁程度或结构的预期

第 3 步：创建改进后的提示词

应用最佳实践，创建改进后的版本：

添加可验证性

Before: "implement a function that validates email addresses"
After: "write a validateEmail function. test cases: [email protected] is true, invalid is false, [email protected] is false. run the tests after implementing"

添加具体上下文

Before: "fix the login bug"
After: "users report that login fails after session timeout. check the auth flow in src/auth/, especially token refresh. write a failing test that reproduces the issue, then fix it"

添加对现有模式的引用

Before: "add a calendar widget"
After: "look at how existing widgets are implemented on the home page to understand the patterns. HotDogWidget.php is a good example. follow the pattern to implement a new calendar widget with month selection and pagination"

精简上下文

Before: "here is a long unrelated history ... fix the dropdown"
After: "fix the dropdown in src/ui/Dropdown.tsx. issue: keyboard navigation skips items. keep the prompt focused; omit unrelated history"

添加丰富的上下文输入

Before: "build fails"
After: "build fails with this error: [paste error]. run the smallest relevant test command. if needed, read the build script and package config"

必要时明确要求探索/规划

Before: "refactor auth to support OAuth"
After: "first explore src/auth and summarize current flow, then propose a plan. after approval, implement with tests"

如果缺少信息，应在改进后的提示词中明确提出问题，不要自行假设默认值。

示例：修复缺陷

Before: "search is broken"
After: "users report search returns empty results for queries with hyphens. reproduce in src/search/. paste the error log if any. write a failing test for 'foo-bar' returning results, fix the root cause, run: pnpm test --filter search"

示例：UI/视觉

Before: "make the dashboard look better"
After: "implement the attached screenshot for the dashboard header in src/ui/DashboardHeader.tsx. match spacing and typography. take a new screenshot and list any differences. run: pnpm lint"

示例：重构

Before: "clean up the auth code"
After: "inspect src/auth and list duplication hotspots. propose a refactor plan scoped to one module. after approval, remove duplication without changing behavior. add a targeted test if coverage is missing. run the smallest relevant test command"

示例：研究

Before: "why is this API slow?"
After: "explore request flow around src/api/. summarize likely bottlenecks with evidence (logs, timings). propose 2-3 hypotheses and what data is needed to confirm. do not implement yet. if needed, ask for access to profiling output"

示例：运维

Before: "deployment failed"
After: "deploy fails with error: [paste log]. identify the failing step in scripts/deploy.sh and related CI config. suggest a fix and a rollback plan. run: ./scripts/deploy.sh --dry-run (if available)"

示例：文档

Before: "update the README"
After: "update README.md to include install + dev steps based on existing scripts. keep it concise. confirm commands exist and match actual scripts"

第 4 步：输出格式

请按以下格式输出：

## Prompt Analysis

### Original Prompt
[User-provided prompt]

### Issues
- [Issue 1 and its impact]
- [Issue 2 and its impact]
...

### Missing Information (Questions to Ask)
The following questions should be answered to make the prompt more effective:
- [Question 1] (Why it is needed)
- [Question 2] (Why it is needed)
...

### Verification Plan
- Commands to run (tests, build, lint, screenshots)
- Expected results or acceptance criteria

### Exploration/Planning Recommendation
- Recommend exploration/planning first? [Yes/No] and why

### Execution Preference
- Implement now / propose plan only / analyze only
- Any constraints on response length or format

### Improved Prompt
[The improved prompt]

### Document Improvement Suggestions (if applicable)
- [Issue and concrete improvement for the instruction document]
- [Issue and concrete improvement for the instruction document]

### Revised Document (optional)
[A revised draft of the instruction document when helpful]

### Improved Prompt Template (optional)
Use this as a fill-in template if the user wants a reusable prompt format:

[任务]

• 目标：
• 目标文件/路径（@...）：
• 约束（运行时/版本/依赖/安全性/兼容性）：
• 背景（症状、日志、复现步骤、链接）：

[验证]

• 命令：
• 预期结果：
• UI 检查（截图/视觉差异）：

[探索/规划]

• 是否先进行探索/规划？（是/否）+ 原因：

[执行偏好]

• 立即实施 / 仅规划 / 仅分析
• 输出格式（简洁报告、补丁摘要、检查清单等）

### Short Prompt Template (optional)
Use this when the user wants the shortest effective prompt:

目标：…… 目标：path1/path2 背景：症状 + 复现步骤 + 日志 约束：运行时/依赖/兼容性 验证：命令 + 预期结果 探索/规划：是/否（原因） 执行：实施 / 仅规划 / 仅分析 输出：简洁格式

### Improvement Points
1. [Explanation of improvement 1]
2. [Explanation of improvement 2]
...

### Additional Recommendations (optional)
- [Whether to do exploration/planning first]
- [Whether to parallelize or delegate investigation]
- [Whether preliminary research is needed]
- [Ways to reduce context usage]

参考：最佳实践检查清单

改进提示词时可参考的最佳实践：

提供验证方法

• 包含测试用例
• 指定预期输出
• 对于 UI 更改，要求对比截图
• 添加“运行测试”或“验证构建成功”
• 包含要运行的明确命令

按探索 → 规划 → 实施的顺序进行

• 复杂任务应先进行探索/规划
• 实施前先制定计划
• 小型修复无需正式计划
• 不确定时，先提出澄清问题，再编写代码

提供具体背景

• 粘贴错误消息
• 指明现有模式
• 说明边缘情况
• 说明环境约束（运行时、语言版本、依赖）

使用丰富的输入

• 粘贴日志和堆栈跟踪
• 提供文档或 API 参考的 URL
• 必要时附上或粘贴大量文本输出

管理上下文窗口

• 保持提示词简洁、聚焦
• 删除无关的历史记录或推测
• 缺少信息时，请求补充，而不是猜测

利用并行处理/委派

• 对于研究任务：请求并行调查或总结
• 对于代码审查：请求独立审查一遍
• 让主要任务保持聚焦

应避免的模式

• “让它变得更好”或“改进一下”之类的模糊指示
• 未指定验证方法的实施请求
• 一次提出多个无关任务
• 要求修改尚未读取的文件
• 缺少明确信息的大量上下文