Prompt 工程与技巧

好的 prompt 是高效使用 Claude Code 的关键。掌握 prompt 工程，可以让 Claude 的输出质量提升数倍。以下是从基础到进阶的完整指南。

核心原则

1. 具体优于笼统

::: bad ❌ 不好的写法

帮我修一下这个 bug

:::

::: good ✅ 好的写法

src/auth/login.ts 第 42 行的 try-catch 缺少对 Mongoose 连接超时的处理，导致用户登录偶尔 500。帮我加上超时处理和错误分类。

:::

**原因：**笼统描述让 Claude 需要猜测你要做什么，浪费多轮迭代。具体描述直接进入执行。

2. 先规划再执行

复杂任务不要让 Claude 直接动手改代码。先让它分析：

不要直接修改代码。先分析 src/api/ 下所有文件，列出重复的逻辑，在 plan.md 中写出重构方案。

审查方案后再让它执行。这就是 Plan Mode 的核心思想。

3. 给约束和上下文

用 TypeScript 重构这个模块。项目约定：使用命名导出、优先 async/await、API 路由必须用 Zod 验证输入。不要改动测试文件。

约束越明确，Claude 产出越可控。

4. 用 @file 引用而非粘贴

::: bad ❌ 不好的写法

这段代码有问题：function formatDate(d: Date) { return d.toISOString() } 帮我改成 YYYY-MM-DD 格式

:::

::: good ✅ 好的写法

帮我把 @src/utils/formatDate.ts 里的 formatDate 函数改成输出 "YYYY-MM-DD" 格式

:::

粘贴代码浪费上下文窗口。@file 引用让 Claude 在需要时才读取文件内容。

高级技巧

5. 指定工具范围

告诉 Claude 用什么工具完成任务：

只用 Read 和 Grep 工具搜索代码，不要 Edit。找出所有使用了 deprecated API 的地方，列出来。

这在调试和分析场景下很有用——只搜索不修改。

6. 分步描述复杂任务

第一步：读取 src/models/ 下所有模型文件，理解当前的数据结构。
第二步：在 plan.md 中列出需要修改的文件和变更内容。
第三步：等我确认后，再按计划逐文件修改。

7. 要求验证

帮我实现这个功能。完成后运行测试确认没有引入新错误，如果有就自动修复。

这触发 Claude 的 Agentic 自愈循环——执行 → 验证 → 发现错误 → 修复 → 再验证。

8. 要求提交 commit

帮我修复这个 bug，完成后用 git commit 提交。commit message 用中文，格式：fix: 简短描述。

Claude Code 可以自主执行 git 操作（commit、diff、PR），前提是你授权了 Bash(git:*)。

进阶 Prompt 技巧

9. 角色扮演（Persona Prompting）

给 Claude 设定一个专业角色，让它以该角色的视角思考和输出：

你是一位有 10 年经验的高级 TypeScript 工程师，擅长设计模式和代码重构。
请审查 @src/services/UserService.ts 的设计，指出架构层面的问题并给出改进建议。

为什么有效： 角色扮演激活 Claude 在特定领域的深层知识，输出更专业、更有深度。

常见角色设定：

角色	适用场景	示例
高级工程师	架构审查、设计评审	"你是一位高级 TypeScript 工程师..."
安全专家	安全审计、漏洞排查	"你是一位应用安全专家..."
测试工程师	测试策略、用例设计	"你是一位资深 QA 工程师..."
DevOps 工程师	CI/CD、部署配置	"你是一位 DevOps 工程师..."
技术写作	文档生成、README	"你是一位技术文档作家..."

10. Few-Shot 示例引导

给 Claude 看几个期望输出的示例，让它模仿格式和风格：

帮我生成 API 端点文档。参考以下格式：

## GET /api/users
**描述：** 获取用户列表
**参数：** page (number), limit (number)
**响应：** { users: User[], total: number }
**示例请求：** curl https://api.example.com/api/users?page=1&limit=10

现在为 @src/api/products.ts 中的端点生成文档。

为什么有效： Few-shot 示例消除了对输出格式的不确定性，Claude 会严格模仿你提供的模板。

11. 结构化输出（Structured Output）

明确要求 Claude 以特定格式输出：

分析 @src/ 下所有文件的复杂度，输出 JSON 格式：
[
  { "file": "文件路径", "complexity": 分数, "issues": ["问题1", "问题2"] }
]

只输出 JSON，不要额外文字。

适用场景：

• 生成配置文件模板（JSON/YAML）
• 生成表格数据（CSV/Markdown 表格）
• 生成测试数据
• 批量分析代码并结构化结果

12. 否定约束（Negative Prompting）

明确告诉 Claude 不要做什么：

重构 @src/utils/helpers.ts：
- 不要改变任何公开函数的签名
- 不要引入新的依赖
- 不要使用 any 类型
- 不要删除现有的注释

为什么有效： Claude 有时会"自作主张"添加功能或改变行为。否定约束划定清晰的边界。

13. Prompt 链（Multi-Turn Chaining）

将复杂任务拆成多个会话，每个会话专注于一个子任务：

第一回合： 分析

分析当前项目的技术债务。用 Grep 搜索：
1. TODO/FIXME/HACK 注释
2. any 类型的使用
3. console.log 残留
4. 超过 300 行的文件
输出到 tech-debt.md

第二回合： 修复

阅读 @tech-debt.md，优先修复 "高风险" 类别的问题。
每修复一类，更新 tech-debt.md 中的状态。

为什么有效： 每个会话保持专注，避免上下文混杂。Claude 在单一任务上的表现远优于"大杂烩"。

14. 渐进式细化（Progressive Refinement）

从粗粒度描述开始，逐步增加细节：

# 第一轮：高层级需求
我想做一个任务管理系统。先列出核心模块和它们之间的关系。

# 第二轮：细化模块
好，现在为 User 模块设计数据模型，包括字段、类型、验证规则。

# 第三轮：具体实现
基于上面的设计，创建 User 模型的 TypeScript 代码。用 Prisma schema。

为什么有效： 每一轮都在上一轮的基础上细化，Claude 始终有清晰的上下文。

15. 上下文锚定（Context Anchoring）

在 prompt 中明确引用具体的文件、行号、函数名：

@src/auth/login.ts 中 login 函数（第 23-45 行）的密码验证逻辑有问题。
当前用的是 bcrypt.compareSync，但项目其他地方都用 bcrypt.compare（异步版本）。
请统一为异步版本，并更新对应的测试。

为什么有效： 精确定位减少 Claude 搜索时间，也避免它找错位置。

16. 思维链引导（Step-by-Step Reasoning）

对复杂推理任务，要求 Claude 逐步思考：

我们的支付系统偶尔会出现重复扣款。请逐步分析：
1. 先理解 @src/payment/process.ts 中的支付流程
2. 找出可能导致重复扣款的代码路径
3. 对每个可疑路径，说明触发条件和影响
4. 提出修复方案并评估风险

每一步都要有明确的推理依据。

17. 对比式 Prompt

让 Claude 比较两种方案并给出建议：

我们要实现一个缓存层。方案 A 用 Redis，方案 B 用内存 Map + LRU。
请从以下维度对比：
- 性能（QPS、延迟）
- 复杂度（实现和维护）
- 可靠性（崩溃恢复、数据一致性）
- 团队学习成本

最后给出你的推荐和理由。

CLAUDE.md —— 持久化你的 Prompt 约定

把常用的约束和约定写进 CLAUDE.md，就不用每次都重复了：

# CLAUDE.md

## 项目约定
- TypeScript strict mode，不用 any
- 所有 API 路由用 Zod 验证
- 错误处理用 AppError 类
- 测试用 Vitest + Supertest
- Git commit message 用 Conventional Commits 格式

## 代码风格
- 函数不超过 50 行
- 文件不超过 300 行
- 用 async/await 不用 callback
- 变量命名：camelCase（变量/函数），PascalCase（类/组件），UPPER_CASE（常量）

进阶用法

把整个团队的编码规范写进 CLAUDE.md，Claude 会自动遵守。比每次在 prompt 中重复约定高效得多。

高级 Prompt 模式

自检 Prompt

让 Claude 在输出前自我检查：

实现以下功能后，请先自我检查：
1. 是否有边界条件未处理？
2. 是否有安全隐患？
3. 是否有性能问题？
4. 代码是否符合项目约定？

如果有问题，先修正再告诉我结果。

复盘 Prompt

任务完成后做复盘：

这次重构完成了。请复盘：
1. 改了哪些文件？列出变更摘要。
2. 是否有遗漏的边界情况？
3. 测试覆盖是否足够？
4. 下一步建议做什么？

迁移 Prompt

跨技术栈迁移时的万能 prompt：

将 @src/utils/ 下的所有 JavaScript 文件迁移为 TypeScript。

要求：
1. 添加完整的类型注解
2. 消除所有 implicit any
3. 为每个函数添加 JSDoc 注释
4. 保持功能完全不变
5. 迁移后运行 tsc --noEmit 确认无类型错误
6. 运行 npm test 确认测试通过

逐个文件迁移，每完成一个提交一次 commit。

常见陷阱

陷阱	问题	解决方案
一次要求太多	Claude 一次改 10 个文件，容易遗漏	分步描述，每步只做 2-3 个文件
不给约束	Claude 可能用你不想要的风格/方案	在 CLAUDE.md 或 prompt 中明确约定
只说"不好"	Claude 不知道哪里不好、怎么改好	具体指出问题和期望的修改方向
粘贴大量代码	上下文窗口被占满，质量下降	用 @file 引用，或 /compact 释放空间
忽略测试	Claude 改了代码没跑测试就结束	在 prompt 中要求"完成后运行测试确认"
没有角色设定	Claude 输出过于通用	用角色扮演激活专业视角
输出格式不明确	结果需要大量手动整理	明确要求 JSON/表格/Markdown 格式
缺少否定约束	Claude 自作主张改不该改的东西	明确说"不要做什么"

Prompt 速查清单

在发送 prompt 前，快速检查：

• [ ] 具体：是否描述了具体的问题/需求？（而非笼统的"帮我看看"）
• [ ] 约束：是否给了足够的约束条件？（技术栈、风格、边界）
• [ ] 引用：是否用了 @file 引用而非粘贴代码？
• [ ] 分步：复杂任务是否拆成了多个步骤？
• [ ] 验证：是否要求了测试或验证？
• [ ] 格式：是否明确了输出格式？
• [ ] 边界：是否有否定约束（不要做什么）？

实战案例：从差 Prompt 到好 Prompt

案例 1：添加 API 端点

❌ 差的 Prompt：

帮我加一个用户搜索的 API

✅ 好的 Prompt：

在 @src/api/users.ts 中添加一个用户搜索端点。

需求：
- GET /api/users/search
- 支持按 name 或 email 模糊搜索
- 支持分页（page, limit 参数）
- 返回格式：{ users: User[], total: number }

约束：
- 使用项目现有的 Zod 验证中间件
- 搜索参数必须经过 SQL 参数化处理
- 不要改动现有端点
- 完成后为搜索功能添加单元测试

参考 @src/api/users.ts 中已有的 listUsers 端点的风格。

案例 2：重构遗留代码

❌ 差的 Prompt：

重构 @src/legacy/payment.js 里的代码

✅ 好的 Prompt：

重构 @src/legacy/payment.js。

当前问题：
- processPayment 函数 230 行，做了太多事情（验证、计算、调用 API、写日志）
- 没有错误处理，API 失败时静默失败
- 大量嵌套 if-else，可读性差

重构方案：
1. 拆分为 3 个函数：validatePayment()、calculateAmount()、executePayment()
2. 每个函数不超过 50 行
3. 添加完整的错误处理（try-catch + 日志）
4. 保持对外接口不变（processPayment 仍然导出，但内部调用新函数）

约束：
- 不改变业务逻辑
- 完成后运行 npm test 确认所有测试通过
- 新增函数添加 JSDoc 注释

先在 Plan Mode 下确认方案，再执行。

案例 3：排查 Bug

❌ 差的 Prompt：

我们的用户注册功能有 bug，修一下

✅ 好的 Prompt：

用户注册功能偶尔会出现 500 错误。

复现步骤：
1. 连续快速注册 10 个用户
2. 约 2-3 个会返回 500
3. 日志显示 "ECONNRESET" 错误

相关文件：
- @src/api/auth/register.ts（注册端点）
- @src/db/connection.ts（数据库连接）

请：
1. 先用 Grep 搜索相关代码，理解注册流程
2. 分析可能导致 ECONNRESET 的原因（连接池耗尽？并发冲突？）
3. 在 plan.md 中列出根因分析和修复方案
4. 确认后执行修复，并添加回归测试

注意：不要改动注册接口的对外行为（参数和响应格式不变）。

社区精选 Prompt 技巧

以下是一些来自社区的实用 Prompt 技巧：

"先问再做" 模式

在我确认之前，不要修改任何代码。先告诉我你的分析和计划。

防止 Claude 直接动手，适合复杂场景先评估风险。

"只读分析" 模式

只使用 Read 和 Grep 工具，不要 Edit 或 Bash。分析以下内容...

强制 Claude 进入只读模式，适合代码审查、复杂度分析等场景。

"模拟用户" 模式

模拟一个用户的操作流程：
1. 打开注册页面
2. 填写表单
3. 提交注册
4. 检查数据库
5. 验证邮件发送

在每个步骤，列出预期行为和实际行为。

让 Claude 从用户视角测试代码，发现集成问题。

"生成对比" 模式

对比 @src/old/ 和 @src/new/ 两个版本的代码。
列出所有行为差异，特别关注：
- 边界条件处理
- 错误处理
- 性能特征

适合迁移后验证，确保新版本没有遗漏旧版本的特殊处理。