name: best-practices description: >- 将模糊提示转换为优化的Claude Code提示。添加验证、特定上下文、约束和适当的分阶段。通过 /best-practices 调用。
最佳实践 — 提示转换器
通过添加Claude所需内容来转换提示。
从这里开始
基于用户的请求：
用户提供要转换的提示： → 使用AskUserQuestion提问：
- 问题： “我该如何改进这个提示？”
- 标题： “模式”
- 选项：
- 直接转换 — “我将应用最佳实践并输出改进版本”
- 先构建上下文 — “我将先收集代码库上下文和意图分析”
用户询问学习/理解： → 显示5个转换原则部分
用户请求示例： → 链接到 references/before-after-examples.md
用户请求评估提示： → 使用本文档末尾的成功标准评估规则
如果选择"直接转换"
应用下面的5个原则，并立即输出改进的提示。
如果选择"先构建上下文"
启动3个并行代理来收集上下文：
使用Task工具并行运行这些代理：
- Task task-intent-analyzer("[用户提示]")
- Task best-practices-referencer("[用户提示]")
- Task codebase-context-builder("[用户提示]")
每个代理返回的内容
| 代理 | 使命 | 返回 |
|---|---|---|
| task-intent-analyzer | 理解用户试图做什么 | 任务类型、差距、边缘案例、转换指导 |
| best-practices-referencer | 从references/中查找相关模式 | 匹配示例、要避免的反模式、转换规则 |
| codebase-context-builder | 探索此代码库 | 特定文件路径、类似实现、约定 |
代理返回后
- 综合发现 — 结合意图 + 最佳实践 + 代码库上下文
- 应用匹配模式 — 使用best-practices-referencer中的示例作为模板
- 基于代码库 — 添加codebase-context-builder中的特定文件路径
- 转换提示 — 应用5个原则，并利用所有收集的上下文
- 输出 — 显示改进的提示，并进行前后对比
代理定义
代理定义在 agents/：
agents/task-intent-analyzer.md— 分析意图、差距和边缘案例agents/best-practices-referencer.md— 从references/中查找相关示例和模式agents/codebase-context-builder.md— 探索代码库中的文件和约定
转换工作流
转换时（选择模式后）：
- 识别缺失内容 — 根据下面的5个原则检查
- 添加缺失元素 — 验证、上下文、约束、阶段、丰富内容
- 输出改进的提示 — 在代码块中，准备复制粘贴
- 显示更改内容 — 简要的前后对比
5个转换原则
按优先级顺序应用：
1. 添加验证（最高优先级）
最高杠杆改进。 当Claude可以验证自己的工作时，表现显著更好。
| 缺失 | 添加 |
|---|---|
| 无成功标准 | 带有预期输入/输出的测试案例 |
| UI更改 | “截图并与设计比较” |
| Bug修复 | “编写失败的测试，然后修复” |
| 构建问题 | “修复后验证构建成功” |
| 重构 | “每次更改后运行测试套件” |
| 无根本原因强制执行 | “解决根本原因，不要抑制错误” |
| 无验证报告 | “总结您运行的内容和通过的内容” |
之前： "实现电子邮件验证"
之后： "编写validateEmail函数。测试案例：user@example.com → true,
无效 → false, user@.com → false。实现后运行测试"
之前： "修复API错误"
之后： "/api/orders端点对大订单返回500。检查OrderService.ts中的错误。解决根本原因，不要抑制错误。修复后，运行测试套件并总结您验证的内容和通过的内容。"
2. 提供特定上下文
用精确位置和细节替换模糊引用。
| 模糊 | 特定 |
|---|---|
| “代码” | src/auth/login.ts |
| “Bug” | “用户报告X在Y发生时发生” |
| “API” | “routes.ts中的 /api/users端点” |
| “那个函数” | processPayment() 在第142行 |
添加上下文的四种方式：
| 策略 | 示例 |
|---|---|
| 限定任务范围 | “为foo.py编写测试，覆盖用户注销的边缘案例。避免模拟。” |
| 指向来源 | “查阅ExecutionFactory的git历史，总结其API如何演变” |
| 引用模式 | “查看HotDogWidget.php并遵循该模式为日历小部件” |
| 描述症状 | “用户报告会话超时后登录失败。检查src/auth/，尤其是令牌刷新” |
如果项目有CLAUDE.md，转换后的提示应：
- 不违反项目约定
- 相关时引用项目特定模式
- 注意任何适用的项目约束
之前： "添加新的API端点"
之后： "添加GET /api/products端点。检查此项目中的API约定在CLAUDE.md中。遵循routes/users.ts中的模式。实现后运行API测试。"
之前： "修复登录Bug"
之后： "用户报告会话超时后登录失败。检查src/auth/中的认证流程，尤其是令牌刷新。编写一个重现问题的失败测试，然后修复它"
3. 添加约束
告诉Claude不要做什么。防止过度工程和不想要的更改。
| 约束类型 | 示例 |
|---|---|
| 依赖 | “无新库”, “仅使用现有依赖” |
| 测试 | “避免模拟”, “测试中使用真实数据库” |
| 范围 | “不要重构无关代码”, “仅接触认证模块” |
| 方法 | “解决根本原因，不要抑制错误”, “保持向后兼容” |
| 模式 | “遵循现有代码库约定”, “匹配utils.ts中的风格” |
之前： "添加日历小部件"
之后： "实现具有月份选择和年份分页的日历小部件。遵循HotDogWidget.php中的模式。从零开始构建，不使用代码库中已用库以外的库"
4. 将复杂任务分阶段结构
对于较大任务，将探索与实现分开。
4阶段模式：
阶段1：探索
"阅读src/auth/并理解我们如何处理会话和登录。
同时查看我们如何管理环境变量以存储密钥。"
阶段2：计划
"我想添加Google OAuth。哪些文件需要更改？
会话流程是什么？创建一个计划。"
阶段3：实现
"根据您的计划实现OAuth流程。为回调处理程序编写测试，运行测试套件并修复任何失败。"
阶段4：提交
"用描述性消息提交并打开PR"
何时使用阶段：
- 不确定方法
- 更改涉及多个文件
- 不熟悉被修改的代码
跳过阶段当：
- 可以用一句话描述差异
- 修复拼写错误、添加日志行、重命名变量
之前： "添加OAuth"
之后： "阅读src/auth/并理解当前会话处理。为添加OAuth创建一个计划。然后根据计划实现。编写测试并验证它们通过"
5. 包含丰富内容
提供Claude可以直接使用的支持材料。
| 内容类型 | 如何提供 |
|---|---|
| 文件 | 使用 @filename 引用文件 |
| 图像 | 直接粘贴截图 |
| 错误 | 粘贴实际错误消息，而非描述 |
| 日志 | 使用 cat error.log | claude 管道 |
| URL | 链接到相关文档 |
之前： "让仪表板看起来更好"
之后： "[粘贴截图] 为此设计实现仪表板。
更改后截图结果并与原设计比较。
列出任何差异并修复它们。确保在768px和1024px断点处的响应行为"
之前： "构建失败"
之后： "构建失败并显示此错误：[粘贴实际错误]。修复它
并验证构建成功。解决根本原因，不要抑制错误"
输出格式
转换提示时，输出：
**原始：** [他们的提示]
**改进：**
[转换后的提示在代码块中]
**添加：**
- [缺失内容及添加]
- [另一个改进]
- [等等]
快速转换示例
Bug修复
之前： "修复登录Bug"
之后： "用户报告会话超时后登录失败。检查src/auth/中的认证流程，尤其是令牌刷新。编写一个重现问题的失败测试，然后修复它。通过运行认证测试套件验证。"
添加： 症状、位置、验证（失败测试）、成功标准
功能实现
之前： "添加搜索功能"
之后： "为产品页面实现搜索。查看ProductList.tsx中的过滤工作原理以获取模式。搜索应按名称和类别过滤。添加测试：空查询返回所有、部分匹配有效、无结果显示消息。无外部搜索库。"
添加： 位置、引用模式、特定行为、测试案例、约束
重构
之前： "让代码更好"
之后： "重构utils.js以使用ES2024功能，同时保持相同行为。具体：将回调转换为async/await，使用可选链，添加适当的TypeScript类型。每次更改后运行现有测试套件以确保无破坏。"
添加： 特定更改、约束（相同行为）、每次步骤后的验证
测试
之前： "为foo.py添加测试"
之后： "为foo.py编写测试，覆盖用户注销的边缘案例。避免模拟。使用tests/中的现有测试模式。测试案例：logged_out_user返回401、expired_session重定向到登录、invalid_token引发AuthError。"
添加： 特定边缘案例、约束（无模拟）、模式引用、测试案例
调试
之前： "API慢"
之后： "/api/orders端点耗时3+秒。分析OrderService.ts中的数据库查询。查找N+1查询或缺失索引。修复性能问题并验证响应时间低于500ms。"
添加： 特定端点、位置、要查找的内容、可测量的成功标准
UI更改
之前： "修复按钮样式"
之后： "[粘贴设计截图] 更新主按钮以匹配此设计。检查Button.tsx和tailwind.config.js中的主题。更改后截图并与设计比较。列出任何差异。"
添加： 设计引用、文件位置、视觉验证
探索
之前： "认证如何工作？"
之后： "阅读src/auth/并解释此代码库中认证如何工作。覆盖：会话如何创建、令牌如何刷新、密钥存储在哪里。总结在markdown文档中。"
添加： 特定文件、要回答的特定问题、输出格式
迁移
之前： "升级到React 18"
之后： "从React 17迁移到React 18。首先，阅读[URL]的迁移指南。然后识别所有使用弃用API的组件。一次更新一个组件，每次后运行测试。不要更改无关代码。"
添加： 分阶段方法、参考文档、增量验证、范围约束
带验证报告
之前： "修复API错误"
之后： "/api/orders端点对大订单返回500。检查OrderService.ts中的错误。解决根本原因，不要抑制错误。修复后，运行测试套件并总结您验证的内容和通过的内容。"
添加： 症状、位置、根本原因强制执行、验证报告
转换检查表
输出前，验证改进的提示有：
- [ ] 验证 — 如何知道它有效（测试、截图、输出）
- [ ] 位置 — 特定文件、函数或区域
- [ ] 约束 — 不要做什么
- [ ] 单一任务 — 不复合（如果需要则拆分）
- [ ] 阶段 — 如果复杂，结构化探索 → 计划 → 实现
- [ ] 根本原因 — 对于Bug：“解决根本原因，不要抑制”
- [ ] CLAUDE.md — 如果存在，尊重项目约定
快速提示质量检查
根据这些维度评估提示：
| 维度 | 0（缺失） | 1（部分） | 2（完整） |
|---|---|---|---|
| 验证 | 无 | “测试它” | 特定测试案例 + 报告 |
| 位置 | “代码” | “认证模块” | src/auth/login.ts:42 |
| 约束 | 无 | 隐含 | “避免X、无Y、仅根本原因” |
| 范围 | 模糊 | 部分 | 单一清晰任务 |
快速评估：
- 0-3：需要大量工作
- 4-5：需要一些改进
- 6-8：良好，微小调整
后备：如果仍然太模糊
如果用户选择"直接转换"但提示缺乏足够上下文，问一个自然问题：
“Claude需要知道什么才能做好这件事？”
不要审问 — 一个问题足够。用您学到的内容转换。
常见反模式修复
| 反模式 | 问题 | 修复 |
|---|---|---|
| “修复Bug” | 无症状、无位置 | 添加用户报告 + 在哪里查找 |
| “添加测试” | 无范围、无案例 | 指定边缘案例 + 测试模式 |
| “让它更好” | 无"更好"标准 | 定义具体改进 |
| “实现X” | 无验证 | 添加测试案例或成功标准 |
| “更新代码” | 无约束 | 添加要保留的内容、要避免的内容 |
成功标准 — 提示质量评估
良好转换的提示通过这些检查：
原则1：验证 ✅
| 检查 | 通过 | 失败 |
|---|---|---|
| 有成功标准 | “运行测试”, “截图匹配” | 无 |
| 可测量结果 | “响应 < 500ms” | “让它更快” |
| 可自我验证 | Claude可以检查自己的工作 | 需要人工判断 |
| 根本原因强制执行 | “不要抑制错误” | 对方法保持沉默 |
原则2：特异性 ✅
| 检查 | 通过 | 失败 |
|---|---|---|
| 文件位置 | src/auth/login.ts |
“认证代码” |
| 函数/类名 | processPayment() |
“那个函数” |
| 行号（如果相关） | :42 |
“某个地方” |
| CLAUDE.md尊重 | “检查项目约定” | 忽略项目规则 |
原则3：约束 ✅
| 检查 | 通过 | 失败 |
|---|---|---|
| 不要做什么 | “避免模拟”, “无新依赖” | 开放式 |
| 范围边界 | “仅接触认证模块” | 无限范围 |
| 要遵循的模式 | “匹配UserService.ts风格” | 无引用 |
原则4：结构 ✅
| 检查 | 通过 | 失败 |
|---|---|---|
| 单一任务 | 一个清晰目标 | 多个目标 |
| 分阶段（如果复杂） | “探索 → 计划 → 实现” | 直接跳到代码 |
| 适当深度 | 匹配任务复杂性 | 过度/不足指定 |
原则5：丰富内容 ✅
| 检查 | 通过 | 失败 |
|---|---|---|
| 实际错误 | 粘贴错误消息 | “它坏了” |
| 截图（UI） | 附加图像 | “按钮看起来不对” |
| 文件引用 | @filename 或路径 |
“那个文件” |
整体质量分数
| 分数 | 含义 | 通过原则 |
|---|---|---|
| ⭐⭐⭐⭐⭐ | 优秀 | 全部5个 |
| ⭐⭐⭐⭐ | 良好 | 4个中的5个 |
| ⭐⭐⭐ | 可接受 | 3个中的5个 |
| ⭐⭐ | 需要工作 | 2个中的5个 |
| ⭐ | 差 | 1个或0个 |
目标： 每个转换的提示应评分 ⭐⭐⭐⭐ 或 ⭐⭐⭐⭐⭐
参考文件
更多示例和模式：
- 50+ 示例：参见 references/before-after-examples.md
- 提示模板：参见 references/prompt-patterns.md
- 任务工作流：参见 references/common-workflows.md
- 要避免的内容：参见 references/anti-patterns.md
- 官方指南：参见 references/best-practices-guide.md
来源
- Claude Code最佳实践 — 官方文档
- Claude Code技能 — 技能编写指南
- Anthropic提示工程 — 通用提示模式
- Dicklesworthstone meta_skill — "THE EXACT PROMPT"模式