best-practices

name	best-practices
description	提示词优化器 - 将模糊的提示词转换为优化的 Claude Code 提示词。添加验证、具体上下文、约束条件和合理的阶段划分。使用 /best-practices 调用。
version	4.1.0

最佳实践 — 提示词转换器 (Best Practices — Prompt Transformer)

通过添加 Claude 成功所需的要素来转换提示词。

从这里开始

根据用户的请求：

用户提供了一个需要转换的提示词： → 使用 AskUserQuestion 询问：

• 问题： "我该如何改进这个提示词？"
• 标题： "模式"
• 选项：
  1. 直接转换 — "我将应用最佳实践并输出改进后的版本"
  2. 先构建上下文 — "我将先收集代码库上下文并进行意图分析"

用户请求学习/理解： → 显示“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	探索此代码库	具体文件路径、类似实现、约定

代理返回后

1. 综合发现 — 结合意图 + 最佳实践 + 代码库上下文
2. 应用匹配模式 — 使用 best-practices-referencer 中的示例作为模板
3. 立足代码库 — 添加来自 codebase-context-builder 的具体文件路径
4. 转换提示词 — 应用 5 大原则及所有收集到的上下文
5. 输出 — 显示改进后的提示词，并进行前后对比

代理定义

代理定义在 agents/ 目录中：

• agents/task-intent-analyzer.md — 分析意图、缺失项和边缘情况
• agents/best-practices-referencer.md — 从 references/ 中查找相关示例和模式
• agents/codebase-context-builder.md — 探索代码库中的文件和约定

---

转换工作流

在转换时（选择模式后）：

1. 识别缺失项 — 对照下面的 5 大原则进行检查
2. 添加缺失元素 — 验证、上下文、约束、阶段、丰富内容
3. 输出改进后的提示词 — 放在代码块中，方便复制粘贴
4. 显示更改内容 — 简要对比前后变化

---

5 大转换原则

按优先级顺序应用以下原则：

1. 添加验证（最高优先级）

单一最高杠杆的改进。 当 Claude 能够验证自己的工作时，表现会显著提升。

缺失项	添加内容
无成功标准	带有预期输入/输出的测试用例
UI 更改	"截屏并与设计图对比"
Bug 修复	"编写一个失败的测试，然后修复它"
构建问题	"修复后验证构建是否成功"
重构	"每次更改后运行测试套件"
未强制要求根因分析	"解决根本原因，不要只是抑制错误"
无验证报告	"总结你运行了什么以及什么通过了"

之前："实现电子邮件验证"
之后："编写一个 validateEmail 函数。测试用例：[e-mail] → true,
      invalid → false, user@.com → false。实现后运行测试。"

之前："修复 API 错误"
之后："/api/orders 端点对大型订单返回 500 错误。检查
      OrderService.ts 中的错误。解决根本原因，不要抑制
      错误。修复后，运行测试套件并总结哪些通过了
      以及你验证了什么。"

2. 提供具体上下文

将模糊的引用替换为精确的位置和细节。

模糊	具体
"代码"	src/auth/login.ts
"bug"	"用户报告当执行 Y 时发生了 X"
"API"	"routes.ts 中的 /api/users 端点"
"那个函数"	第 142 行的 processPayment()

添加上下文的四种策略：

策略	示例
界定任务范围	"为 foo.py 编写测试，涵盖用户已登出的边缘情况。避免使用 mock。"
指向来源	"查阅 ExecutionFactory 的 git 历史记录，总结其 API 是如何演变的"
引用模式	"参考 HotDogWidget.php，并按照该模式实现日历组件"
描述症状	"用户报告会话超时后登录失败。检查 src/auth/，特别是令牌刷新"

尊重项目 CLAUDE.md：

如果项目有 CLAUDE.md，转换后的提示词应当：

• 不违背项目约定
• 在相关时引用项目特有的模式
• 注明任何适用的项目约束

之前："添加一个新的 API 端点"
之后："添加一个 GET /api/products 端点。查看 CLAUDE.md 了解此项目
      的 API 约定。遵循 routes/users.ts 中的模式。实现后运行
      API 测试。"

之前："修复登录 bug"
之后："用户报告会话超时后登录失败。检查 src/auth/ 中的认证流，
      特别是令牌刷新。编写一个重现该问题的失败测试，然后修复它"

3. 添加约束

告诉 Claude 不要做什么。防止过度设计和不必要的更改。

约束类型	示例
依赖项	"不引入新库"、"仅使用现有依赖"
测试	"避免 mock"、"在测试中使用真实数据库"
范围	"不要重构无关代码"、"仅修改认证模块"
方法	"解决根本原因，不要抑制错误"、"保持向后兼容"
模式	"遵循现有代码库约定"、"匹配 utils.ts 中的风格"

之前："添加日历组件"
之后："实现一个带有月份选择和年份分页功能的日历组件。
      遵循 HotDogWidget.php 中的模式。从头开始构建，不使用
      代码库中已使用的库以外的其他库"

4. 将复杂任务分阶段

对于较大的任务，将探索与实现分开。

4 阶段模式：

第 1 阶段：探索 (EXPLORE)
"阅读 src/auth/ 并理解我们如何处理会话和登录。
 同时查看我们如何管理机密信息的环境变量。"

第 2 阶段：计划 (PLAN)
"我想添加 Google OAuth。需要更改哪些文件？
 会话流是怎样的？创建一个计划。"

第 3 阶段：实现 (IMPLEMENT)
"根据你的计划实现 OAuth 流程。为回调处理器编写测试，
 运行测试套件并修复任何失败。"

第 4 阶段：提交 (COMMIT)
"使用描述性的消息提交并开启 PR"

何时使用阶段：

• 对方法不确定时
• 更改涉及多个文件时
• 对要修改的代码不熟悉时

跳过阶段的情形：

• 可以用一句话描述差异 (diff) 时
• 修复拼写错误、添加日志行、重命名变量时

之前："添加 OAuth"
之后："阅读 src/auth/ 并理解当前的会话处理。创建一个
      添加 OAuth 的计划。然后根据计划进行实现。编写测试并
      验证其通过"

5. 包含丰富内容

提供 Claude 可以直接使用的辅助材料。

内容类型	如何提供
文件	使用 @文件名 引用文件
图像	直接粘贴屏幕截图
错误	粘贴实际的错误消息，而非描述
日志	通过 `cat error.log
URL	链接到相关的文档

之前："让仪表板看起来更好看"
之后："[粘贴屏幕截图] 为仪表板实现此设计。
      对结果进行截图并与原图对比。
      列出任何差异并修复它们。确保在 768px 和 1024px
      断点处的响应式行为"

之前："构建失败了"
之后："构建失败，错误如下：[粘贴实际错误]。修复它
      并验证构建成功。解决根本原因，不要
      抑制错误"

---

输出格式

转换提示词时，输出：

**原始提示词：** [用户的提示词]

**改进后的提示词：**

[代码块中转换后的提示词]

**添加的内容：**
- [缺失并添加的内容]
- [另一项改进]
- [等等]

---

快速转换示例

Bug 修复

之前："修复登录 bug"

之后："用户报告会话超时后登录失败。检查 src/auth/ 中的认证流，特别是令牌刷新。编写一个重现该问题的失败测试，然后修复它。通过运行认证测试套件进行验证。"

添加内容：症状、位置、验证（失败测试）、成功标准

功能实现

之前："添加搜索功能"

之后："为产品页面实现搜索功能。参考 ProductList.tsx 中的过滤实现模式。搜索应支持按名称和类别过滤。添加测试用例：空查询返回所有内容、部分匹配正常工作、无结果时显示消息。不使用外部搜索库。"

添加内容：位置、参考模式、具体行为、测试用例、约束

重构

之前："优化代码"

之后："重构 utils.js 以使用 ES2024 特性，同时保持原有行为。具体要求：将回调转换为 async/await，使用可选链，添加正确的 TypeScript 类型。每次更改后运行现有测试套件以确保没有任何损坏。"

添加内容：具体更改、约束（保持原有行为）、每一步后的验证

测试

之前："为 foo.py 添加测试"

之后："为 foo.py 编写测试，涵盖用户已登出的边缘情况。避免使用 mock。遵循 tests/ 中现有的测试模式。测试用例：logged_out_user 返回 401，expired_session 重定向到登录，invalid_token 抛出 AuthError。"

添加内容：具体边缘情况、约束（不使用 mock）、模式引用、测试用例

调试

之前："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"	无验证	添加测试用例或成功标准
"更新代码"	无约束	添加要保留的内容、要避免的内容

---

成功标准 — 提示词质量评估 (Success Criteria — Prompt Quality Eval)

转换良好的提示词应当通过以下检查：

原则 1：验证 ✅

检查项	通过	失败
有成功标准	"运行测试"、"截图匹配"	无
可衡量的结果	"响应时间 < 500ms"	"让它更快"
可自我验证	Claude 可以检查自己的工作	需要人工判断
强制根本原因	"不要抑制错误"	对方法保持沉默

原则 2：具体性 ✅

检查项	通过	失败
文件位置	src/auth/login.ts	"认证代码"
函数/类名	processPayment()	"那个函数"
行号（如果相关）	:42	"在里面的某个地方"
尊重 CLAUDE.md	"检查项目约定"	忽略项目规则

原则 3：约束 ✅

检查项	通过	失败
不该做什么	"避免使用 mock"、"不引入新依赖"	开放式
范围边界	"仅修改认证模块"	无限制的范围
遵循模式	"匹配 UserService.ts 的风格"	无参考

原则 4：结构 ✅

检查项	通过	失败
单一任务	一个明确的目标	多个目标
分阶段（如果复杂）	"探索 → 计划 → 实现"	直接跳到代码
深度适宜	匹配任务复杂度	描述过多/过少

原则 5：丰富内容 ✅

检查项	通过	失败
实际错误	粘贴了错误消息	"它坏了"
屏幕截图 (UI)	附带图像	"按钮看起来不对"
文件引用	@文件名 或路径	"那个文件"

总体质量评分

分数	含义	通过的原则数
⭐⭐⭐⭐⭐	优秀	全部 5 个
⭐⭐⭐⭐	良好	5 个中的 4 个
⭐⭐⭐	可接受	5 个中的 3 个
⭐⭐	需要改进	5 个中的 2 个
⭐	差	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" 模式