best-practices

最佳实践 — 提示词转换器

通过补充 Claude 成功完成任务所需的信息来转换提示词。

从这里开始

根据用户的请求：

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

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

用户想要学习或了解： → 显示“5 条转换原则”部分

用户想要示例： → 链接到 references/before-after-examples.md

用户想要评估提示词： → 使用本文档末尾的成功标准评估量规

---

如果选择“直接转换”

应用以下 5 条原则，并立即输出改进后的提示词。

如果选择“先构建上下文”

启动 3 个并行 Agent 来收集上下文：

Run these agents IN PARALLEL using the Task tool:

- Task task-intent-analyzer("[user's prompt]")
- Task best-practices-referencer("[user's prompt]")
- Task codebase-context-builder("[user's prompt]")

每个 Agent 的返回内容

Agent	任务	返回内容
task-intent-analyzer	了解用户想要做什么	任务类型、缺失信息、边缘情况、转换指导
best-practices-referencer	从 references/ 中查找相关模式	匹配的示例、应避免的反模式、转换规则
codebase-context-builder	探索此代码库	具体文件路径、类似实现、约定

Agent 返回后

1. 综合发现 — 结合意图、最佳实践和代码库上下文
2. 应用匹配模式 — 将 best-practices-referencer 中的示例用作模板
3. 以代码库为依据 — 添加 codebase-context-builder 提供的具体文件路径
4. 转换提示词 — 应用 5 条原则，并纳入收集到的所有上下文
5. 输出 — 展示改进后的提示词，并对比转换前后

Agent 定义

这些 Agent 定义在 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 修复	“先编写一个失败的测试，再修复问题”
构建问题	“修复后验证构建成功”
重构	“每次变更后都运行测试套件”
未要求查明根本原因	“解决根本原因，不要压制错误”
没有验证报告	“总结运行了哪些检查以及哪些检查通过”

BEFORE: "implement email validation"
AFTER:  "write a validateEmail function. test cases: [email protected] → true,
         invalid → false, [email protected] → false. run the tests after implementing"

BEFORE: "fix the API error"
AFTER:  "the /api/orders endpoint returns 500 for large orders. check
         OrderService.ts for the error. address the root cause, don't suppress
         the error. after fixing, run the test suite and summarize what passed
         and what you verified."

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，转换后的提示词应：

• 不违背项目约定
• 在相关时参考项目特定模式
• 注明适用的项目约束

BEFORE: "add a new API endpoint"
AFTER:  "add a GET /api/products endpoint. check CLAUDE.md for API conventions
         in this project. follow the pattern in routes/users.ts. run the API
         tests after implementing."

BEFORE: "fix the login bug"
AFTER:  "users report 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"

3. 添加约束

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

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

BEFORE: "add a calendar widget"
AFTER:  "implement a calendar widget with month selection and year pagination.
         follow the pattern in HotDogWidget.php. build from scratch without
         libraries other than the ones already used in the codebase"

4. 将复杂任务分阶段

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

四阶段模式：

Phase 1: EXPLORE
"read src/auth/ and understand how we handle sessions and login.
 also look at how we manage environment variables for secrets."

Phase 2: PLAN
"I want to add Google OAuth. What files need to change?
 What's the session flow? Create a plan."

Phase 3: IMPLEMENT
"implement the OAuth flow from your plan. write tests for the
 callback handler, run the test suite and fix any failures."

Phase 4: COMMIT
"commit with a descriptive message and open a PR"

适合使用阶段的情况：

• 尚不确定采用哪种方法
• 更改涉及多个文件
• 不熟悉要修改的代码

适合跳过阶段的情况：

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

BEFORE: "add OAuth"
AFTER:  "read src/auth/ and understand current session handling. create a plan
         for adding OAuth. then implement following the plan. write tests and
         verify they pass"

5. 包含丰富内容

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

内容类型	提供方式
文件	使用 @filename 引用文件
图片	直接粘贴屏幕截图
错误	粘贴实际错误消息，而非描述
日志	通过 cat error.log | claude 管道传入
URL	链接到相关文档

BEFORE: "make the dashboard look better"
AFTER:  "[paste screenshot] implement this design for the dashboard.
         take a screenshot of the result and compare it to the original.
         list any differences and fix them. ensure responsive behavior
         at 768px and 1024px breakpoints"

BEFORE: "the build is failing"
AFTER:  "the build fails with this error: [paste actual error]. fix it
         and verify the build succeeds. address the root cause, don't
         suppress the error"

---

输出格式

转换提示词时，输出：

**Original:** [their prompt]

**Improved:**

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

**Added:**
- [what was missing and added]
- [another improvement]
- [etc.]

---

快速转换示例

修复 Bug

BEFORE: "fix the login bug"

AFTER: "users report 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. verify by running the auth test suite."

ADDED: symptom, location, verification (failing test), success criteria

实现功能

BEFORE: "add a search feature"

AFTER: "implement search for the products page. look at how filtering works
in ProductList.tsx for the pattern. search should filter by name and category.
add tests for: empty query returns all, partial match works, no results shows
message. no external search libraries."

ADDED: location, reference pattern, specific behavior, test cases, constraint

重构

BEFORE: "make the code better"

AFTER: "refactor utils.js to use ES2024 features while maintaining the same
behavior. specifically: convert callbacks to async/await, use optional
chaining, add proper TypeScript types. run the existing test suite after
each change to ensure nothing breaks."

ADDED: specific changes, constraint (same behavior), verification after each step

测试

BEFORE: "add tests for foo.py"

AFTER: "write tests for foo.py covering the edge case where the user is
logged out. avoid mocks. use the existing test patterns in tests/. test
cases: logged_out_user returns 401, expired_session redirects to login,
invalid_token raises AuthError."

ADDED: specific edge case, constraint (no mocks), pattern reference, test cases

调试

BEFORE: "the API is slow"

AFTER: "the /api/orders endpoint takes 3+ seconds. profile the database
queries in OrderService.ts. look for N+1 queries or missing indexes.
fix the performance issue and verify response time is under 500ms."

ADDED: specific endpoint, location, what to look for, measurable success criteria

UI 更改

BEFORE: "fix the button styling"

AFTER: "[paste screenshot of design] update the primary button to match this
design. check Button.tsx and the theme in tailwind.config.js. take a
screenshot after changes and compare to the design. list any differences."

ADDED: design reference, file locations, visual verification

探索

BEFORE: "how does auth work?"

AFTER: "read src/auth/ and explain how authentication works in this codebase.
cover: how sessions are created, how tokens are refreshed, where secrets
are stored. summarize in a markdown doc."

ADDED: specific files, specific questions to answer, output format

迁移

BEFORE: "upgrade to React 18"

AFTER: "migrate from React 17 to React 18. first, read the migration guide
at [URL]. then identify all components using deprecated APIs. update one
component at a time, running tests after each. don't change unrelated code."

ADDED: phased approach, reference docs, incremental verification, scope constraint

附带验证报告

BEFORE: "fix the API error"

AFTER: "the /api/orders endpoint returns 500 for large orders. check
OrderService.ts for the error. address the root cause, don't suppress
the error. after fixing, run the test suite and summarize what passed
and what you verified."

ADDED: symptom, location, root cause enforcement, verification report

---

转换检查清单

输出前，请确认改进后的提示词包含：

• 验证 — 如何确认任务已成功（测试、屏幕截图、输出）
• 位置 — 具体文件、函数或区域
• 约束 — 不要做什么
• 单一任务 — 不要包含多个任务（必要时拆分）
• 阶段 — 如果任务复杂，请按探索 → 计划 → 实现的顺序组织
• 根本原因 — 对于 Bug：“解决根本原因，不要压制错误”
• CLAUDE.md — 如果项目存在 CLAUDE.md，则遵循项目约定

---

快速检查提示词质量

根据以下维度为提示词评分：

维度	0（缺失）	1（部分具备）	2（完整）
验证	无	“测试一下”	具体测试用例 + 报告
位置	“代码”	“auth 模块”	src/auth/login.ts:42
约束	无	暗示包含	“避免 X，不要用 Y，只解决根本原因”
范围	模糊	部分明确	单一、明确的任务

快速评估：

• 0-3：需要大幅改进
• 4-5：还需要一些改进
• 6-8：良好，只需微调

---

后备方案：如果仍然太模糊

如果用户选择了“直接转换”，但提示词缺少足够的上下文，只需自然地问一个问题：

“Claude 需要了解什么才能做好这件事？”

不要盘问——一个问题就够了。根据你了解到的信息进行转换。

---

需要修正的常见反模式

反模式	问题	修正方法
“修复这个错误”	没有症状，也没有位置	补充用户反馈的内容和需要查看的位置
“添加测试”	没有范围，也没有测试用例	指明边界情况和测试模式
“让它更好”	没有说明“更好”的标准	定义具体的改进内容
“实现 X”	没有验证方式	添加测试用例或成功标准
“更新代码”	没有限制条件	补充需要保留和避免的内容

---

成功标准——提示词质量评估

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

原则 1：可验证性 ✅

检查项	通过	未通过
有成功标准	“运行测试”“截图一致”	无
结果可衡量	“响应时间 < 500ms”	“让它更快”
可自我验证	Claude 可以检查自己的工作	需要人工判断
强制查找根因	“不要压制错误”	未说明处理方式

原则 2：具体性 ✅

检查项	通过	未通过
文件位置	src/auth/login.ts	“身份验证代码”
函数／类名称	processPayment()	“那个函数”
行号（如相关）	:42	“在那附近”
遵循 CLAUDE.md	“检查项目约定”	忽略项目规则

原则 3：限制条件 ✅

检查项	通过	未通过
不要做的事	“避免使用模拟对象”“不要添加依赖”	没有限定
范围边界	“只修改身份验证模块”	范围不受限
遵循的模式	“遵循 UserService.ts 的风格”	没有参考

原则 4：结构 ✅

检查项	通过	未通过
单一任务	一个明确的目标	多个目标
分阶段（如复杂）	“探索 → 规划 → 实现”	直接开始编写代码
深度适当	与任务复杂度相符	过度／不足指定

原则 5：内容丰富 ✅

检查项	通过	未通过
实际错误	粘贴错误消息	“它坏了”
截图（UI）	附带图片	“按钮看起来不对”
文件引用	@filename 或路径	“那个文件”

总体质量评分

评分	含义	通过的原则
⭐⭐⭐⭐⭐	优秀	全部 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 Skills — Skill 编写指南
• Anthropic 提示工程 — 通用提示模式
• Dicklesworthstone meta_skill — “THE EXACT PROMPT”模式