第 28 章：Prompt 工程

前面八章，我们走过了 Claude Code 的八个实战场景——从理解项目到 CI/CD 自动化。在每个场景中，有一个能力始终在发挥作用，却常常被忽视：你如何向 Claude Code 描述你的需求。

同样的工具、同样的模型、同样的代码库，不同的人用出来的效果天差地别。差距的根源，十有八九不在"会不会用工具"，而在"会不会说清楚话"。这就是 Prompt 工程——不是写长篇大论的咒语，而是用精准的语言让 AI 准确理解你的意图。

本章是"方法论篇"的开篇，也是最值得反复查阅的参考章节。我们将把 Prompt 工程拆解为可操作、可复用的方法论：四个要素、五类模板、渐进式细化技巧、六个常见反模式，以及 Claude Code 特有的 Prompt 技巧。

本章目标：掌握 Claude Code Prompt 的四个核心要素，能套用模板库快速构造高质量 Prompt，学会渐进式细化而非推倒重来，识别并避免六种常见反模式，理解 Claude Code 特有的 Prompt 技巧并应用到日常工作中。

28.1 好 Prompt 的四个要素

一个高质量的 Claude Code Prompt，就像一个合格的工程规格书。它不需要文采，但必须包含四个关键信息维度。缺少任何一个，Claude 都需要"猜"——猜得准是运气，猜不准才是常态。

这四个要素可以用 RCCF 框架来记忆：

要素	英文	核心问题	缺失后果
角色	Role	"你是谁？"	Claude 使用泛化的知识，而非领域最佳实践
上下文	Context	"在哪里？什么情况？"	Claude 查看无关文件，浪费 token 和时间
约束	Constraints	"什么能做？什么不能做？"	产出不符合项目规范，需要反复修改
输出格式	Format	"怎么呈现？"	答案正确但形式不适用，需要二次加工

下面我们逐一展开，每个要素都配有对比示例。

28.1.1 角色（Role）

角色定义了你希望 Claude Code 以什么身份来思考和行动。这不是可有可无的"氛围设定"——不同的角色会激活 Claude 知识库中不同的领域模式。

坏 Prompt（无角色）：

帮我写一个 React 表单组件

好 Prompt（明确角色）：

你是一个资深的 React 前端开发者，擅长 TypeScript 和表单状态管理。
帮我写一个 React 表单组件。

角色不一定是职称，也可以是思维方式。以下是常用角色描述：

场景	角色描述
写业务代码	"你是一个资深的全栈 TypeScript 开发者"
代码审查	"你是一个严格的代码审查者，关注安全、性能和可维护性"
性能优化	"你是一个性能优化专家，擅长找出瓶颈并给出可量化的优化方案"
调试排查	"你是一个调试专家，擅长从错误日志中逆向推导根因"
架构设计	"你是一个系统架构师，关注可扩展性、耦合度和技术选型合理性"
写文档	"你是一个技术文档撰写者，擅长用清晰的中文解释复杂概念"

角色的关键在于具体。不要只说"你是一个程序员"——这等于没说。告诉 Claude 它擅长什么、关注什么、用什么技术栈。

28.1.2 上下文（Context）

上下文告诉 Claude Code 在哪里工作、什么情况、有什么背景信息。这是四要素中最容易被省略的一项，也是"Claude 不理解我"最常见的根因。

坏 Prompt（无上下文）：

重构 auth.ts

Claude 会怎么做？它不知道 auth.ts 在项目的哪个位置，不知道这个文件依赖什么，不知道你为什么要重构，也不知道重构的目标是什么。它只能猜。

好 Prompt（充分上下文）：

重构 src/api/auth.ts 中的 token 验证逻辑。
当前问题：回调嵌套太深，错误处理不统一。

Claude 现在知道：文件位置、重构范围、当前痛点。

上下文的层次可以逐步递进：

文件级："只看 src/api/ 目录下的文件"
问题级："当前的问题是登录超时后 token 刷新逻辑会死循环"
项目级："这个项目使用 Express + TypeScript，遵循 RESTful API 设计"
约定级："参考 CLAUDE.md 中的编码规范"

一个实用的上下文检查清单：

[ ] 我是否指定了要操作的文件或目录？
[ ] 我是否说明了当前存在的问题或背景？
[ ] 我是否提到了相关的技术栈或依赖？
[ ] 我是否引用了可以参考的现有代码？

28.1.3 约束（Constraints）

约束是 Prompt 的"护栏"——它告诉 Claude Code 什么可以做、什么绝对不能做。没有约束，Claude 会按照自己的"常识"行事，而它的常识不一定等于你项目的规范。

坏 Prompt（无约束）：

写一个登录接口

Claude 可能用 Express、可能用 Koa、可能用 Python Flask、可能返回 JSON、可能返回 HTML……它什么都可能做，但你大概率要改。

好 Prompt（精确约束）：

写一个登录接口。
约束：
- 使用 Express + TypeScript
- 遵循项目中现有的 API 风格（参考 src/api/users.ts）
- 不要改变现有的路由前缀 /api/v1
- 不要使用 any 类型
- 不要引入新的依赖包

约束的类型可以归纳为以下几类：

约束类型	示例
技术约束	"使用 TypeScript 严格模式"、"不要引入新的依赖"
接口约束	"不要改变 API 接口签名"、"保持向后兼容"
风格约束	"遵循项目中现有的组件风格"、"用函数式组件而非 class"
范围约束	"只修改 src/api/ 目录"、"不要动配置文件"
行为约束	"不改变外部行为"、"保持 API 兼容"
质量约束	"需要包含单元测试"、"需要包含错误处理"

约束的有效写法有一个原则：宁可多写一条约束，也不要让 Claude 猜。多写一条约束的成本是你敲几个字；少写一条约束的代价是 Claude 产出后你要花几分钟甚至更久来修正。

28.1.4 输出格式（Format）

输出格式告诉 Claude Code 答案应该长什么样。同样的分析结果，用表格呈现和用段落呈现，可读性和可用性天差地别。

坏 Prompt（无格式约束）：

分析这个项目的模块依赖关系

Claude 可能给你一段 prose，也可能给你一个列表。你不知道会得到什么。

好 Prompt（明确格式）：

分析 src/ 下各模块的依赖关系。
用 Mermaid 流程图展示模块间的依赖，
然后用表格列出每个模块的职责和对外暴露的接口。

常用输出格式指令：

格式指令	适用场景
"用表格列出"	对比分析、清单、问题汇总
"用 Mermaid 画出流程图/时序图"	流程描述、调用链、数据流
"用 Markdown 列表"	要点总结、步骤说明
"分三步输出"	需要阶段性确认的复杂任务
"输出 JSON 格式"	需要程序化处理的结果
"先总结再展开"	需要快速了解全貌 + 深入细节
"用代码块展示"	配置示例、命令示例

进阶技巧——多阶段输出格式：

请帮我分析 src/api/auth.ts，分三个部分输出：
1. 文件概述（3-5 句话）
2. 问题清单（表格，含位置、严重程度、建议）
3. 重构建议（按优先级排序的列表）

这种多阶段格式让 Claude 的输出像一份结构化报告，你可以快速定位到关心的部分。

28.1.5 四要素组合范例

将四个要素组合在一起，一个完整的 Prompt 应该是这样的：

<角色>你是一个资深的 TypeScript 后端开发者，擅长 Express 和 RESTful API 设计。</角色>

<上下文>
重构 src/api/auth.ts 中的 token 验证逻辑。
当前问题：回调嵌套过深（最深 5 层），错误处理分散在多个回调中，
新增一个错误场景需要改 3 个地方。
项目中其他模块（如 src/api/users.ts）已经改为 async/await 风格，可以参考。
</上下文>

<约束>
- 使用 async/await 替代回调
- 不要改变 API 接口签名
- 不要引入新的依赖包
- 保持现有的错误码定义
- 需要包含单元测试
</约束>

<输出格式>
1. 先列出重构计划（步骤清单）
2. 逐步执行每个步骤
3. 最后输出变更摘要（表格，含文件、变更类型、说明）
</输出格式>

记忆口诀：角色说"我是谁"，上下文说"在哪里"，约束说"怎么做"，格式说"长啥样"。四个要素齐了，Claude 猜得少，你改得少。

28.2 Prompt 模板库

理解了四个要素之后，下一步是积累可复用的模板。每当遇到常见任务时，你不需要从零开始构思 Prompt——打开模板库，填空即可。

以下模板覆盖了 Claude Code 日常使用中最常见的五类任务。每个模板中的 {花括号} 部分是需要你替换的变量。

28.2.1 代码生成

基础版：

在 {目标目录} 下创建一个 {组件/模块名}。

功能描述：{一句话描述}

技术栈：
- {语言/框架}
- {关键依赖}

要求：
- 遵循项目中现有的代码风格（参考 {参考文件路径}）
- 导出类型定义
- 包含基础的错误处理和 {边界情况}

完整版：

你是一个资深的 {技术栈} 开发者。

在 {目录路径} 下创建一个 {名称}，功能是 {功能描述}。

要求：
- 使用 {语言} + {框架}
- 遵循项目中现有的代码风格，参考 {已有文件路径}
- 导出完整的类型定义（interface/type）
- 包含以下状态处理：
  - 加载中（loading）
  - 错误（error，含用户友好的错误提示）
  - 空数据（empty）
  - 正常渲染
- 需要处理的边界情况：{列出边界情况}
- 包含基础的单元测试（vitest）

约束：
- 不要修改已有文件
- 不要引入新的依赖
- 使用 {具体的技术选择，如：CSS Modules / Tailwind / styled-components}

输出顺序：
1. 先列出组件 Props 的类型定义
2. 再给出组件实现
3. 最后给出测试用例

使用示例——填上变量：

你是一个资深的前端开发者。

在 src/components/ 下创建一个 SearchBar 组件，功能是带搜索建议的输入框：
- 用户输入时显示下拉建议列表
- 支持键盘上下选择
- 支持防抖（300ms）
- 点击外部关闭下拉

要求：
- 使用 React + TypeScript
- 遵循项目中现有的组件风格，参考 src/components/Button.tsx
- 导出完整的 Props 类型定义
- 包含 loading、error、empty、正常渲染四种状态
- 包含基础的单元测试

约束：
- 不要修改已有文件
- 不要引入新的依赖
- 使用 Tailwind CSS

输出顺序：
1. Props 类型定义
2. 组件实现
3. 测试用例

28.2.2 代码分析

基础版：

分析 {文件路径} 的 {函数/模块名}。

请关注：
1. 逻辑是否正确
2. 性能是否有优化空间
3. 错误处理是否完整
4. 是否有安全隐患

用表格形式输出问题清单，按严重程度排序。

完整版：

你是一个代码审查专家，擅长发现逻辑错误、性能瓶颈和安全隐患。

请分析 {文件路径} 中的 {函数/类/模块名}，从以下维度进行审查：

1. **逻辑正确性**：是否存在逻辑错误、边界情况遗漏、条件判断缺陷
2. **性能**：是否存在不必要的计算、内存泄漏、N+1 查询
3. **错误处理**：异常是否被正确处理、错误信息是否有用
4. **安全性**：是否存在注入风险、敏感信息泄露、权限校验缺失
5. **可维护性**：命名是否清晰、函数是否过长、职责是否单一
6. **类型安全**：是否存在 any 逃逸、类型断言是否安全

输出格式：
先给出总体评分（1-10 分），然后以表格列出所有问题，
表头为：编号 | 维度 | 严重程度（致命/严重/一般/建议） | 位置（行号） | 问题描述 | 修复建议
最后给出优先修复顺序建议。

28.2.3 重构

你是一个重构专家，擅长在不改变外部行为的前提下优化代码结构。

重构目标：{文件路径或模块名}

当前痛点：{描述为什么要重构，如：函数过长、耦合过重、难以测试}

约束：
- 不改变外部行为（所有现有测试必须通过）
- 保持 API 接口兼容（调用方不需要修改）
- 使用 {目标模式，如：策略模式 / async-await / 依赖注入}
- 不要一次修改超过 {N} 个文件

执行流程：
1. **分析阶段**：先读取目标文件，理解当前结构，列出所有需要修改的地方
2. **计划阶段**：给出分步重构计划（每步可独立验证），等待我确认
3. **执行阶段**：逐步执行，每完成一步后运行相关测试
4. **总结阶段**：输出变更摘要

确认后再开始执行。

关键技巧：重构类 Prompt 中"先列计划，确认后再执行"这句话至关重要。重构风险高，让 Claude 先把计划亮出来，你能在它动手前纠正方向。

28.2.4 调试

我遇到了以下问题：

错误信息：
{粘贴完整的错误堆栈或现象描述}

环境信息：
- 运行环境：{Node 版本 / 浏览器 / OS}
- 相关依赖版本：{列出关键依赖}
- 最近改动：{简要描述最近的代码变更}

相关文件：
- {文件路径 1}
- {文件路径 2}

请帮我：
1. 分析可能的根因（按可能性排序）
2. 为每个可能的原因给出验证方法（怎么确认或排除）
3. 对确认的原因给出修复方案
4. 如果以上都无法解决，告诉我还需要哪些额外信息

调试 Prompt 的黄金法则：信息宁可多给，不可少给。Claude 的推理能力再强，也比不上你直接把错误堆栈和相关代码喂给它。

28.2.5 文档生成

你是一个技术文档撰写者。

为 {模块名/API名} 生成使用文档。

需要覆盖的内容：
- 功能说明（1-2 句话）
- 安装或引入方式
- API 参考（每个公开方法的参数、返回值、异常）
- 使用示例（至少 2 个典型场景的完整代码）
- 注意事项和常见陷阱

格式：Markdown

参考风格：{项目中已有的文档文件路径}

约束：
- 使用中文
- 代码示例需要是可运行的
- 不要重复源代码中已有的实现细节
- 面向的读者是 {初学者 / 有经验的开发者 / API 使用者}

模板库使用建议：将这些模板保存到项目的 CLAUDE.md 或一个单独的 prompt-templates.md 文件中。每次使用时复制、填空、发送。随着使用经验的积累，你会逐渐形成自己的模板变体。

28.3 渐进式细化技巧

Prompt 工程最容易犯的错误之一是：试图一次写出完美的 Prompt。现实是，即使最有经验的 Claude Code 用户，也经常需要 2-3 轮对话来逐步逼近最佳结果。

渐进式细化（Progressive Refinement）的核心思想是：先粗后细，由面到点，迭代收敛。它不是"写错了重来"，而是"在正确的方向上不断聚焦"。

28.3.1 先概括，后聚焦

这是最基础也最有效的渐进模式。不要一上来就钻入细节——先让 Claude 给你一个"地图"，然后你再决定往哪里深入。

第一轮（建立全局视图）：

概括一下 src/ 目录的整体结构，列出主要模块及其职责。

第二轮（聚焦核心模块）：

详细分析 src/api/auth/ 模块的代码结构，列出所有公开的函数和它们的职责。

第三轮（深入具体实现）：

重构 src/api/auth/token.ts 的 refreshToken 函数。
当前问题：token 过期时重试逻辑存在竞态条件。

这个过程就像 Google Maps：先看国家 → 再看城市 → 最后导航到具体街道。每一轮都建立在前一轮的理解之上。

28.3.2 "What → Why → How" 模式

当你需要 Claude Code 做一个复杂决策时，按 What → Why → How 的顺序展开：

What：帮我把这个 React Class 组件改成函数组件 + Hooks。
Why：因为项目中其他组件都已经是函数组件了，保持一致性。
How：
  1. 先读取原组件，列出所有 state 和生命周期方法
  2. 设计对应的 Hooks 方案（useState / useEffect / 自定义 Hook）
  3. 列出方案让我确认
  4. 确认后逐步改写

这个模式的关键是 Why——当 Claude 理解了你的动机，它的方案会更贴合你的实际需求，而不是机械地翻译代码。

28.3.3 当 Claude 理解错了——如何高效纠正

Claude Code 不是每次都一击必中。当它的回答偏离了你的意图，不要重新开一个对话，不要从头写 Prompt。纠正比全新描述更高效。

反模式（情绪化纠正）：

你完全理解错了！我不是这个意思！

高效纠正（精准调校）：

不完全是这个意思。
我的实际需求是：{修正后的需求描述}
刚才你方案中的 {具体哪一部分} 方向不对，正确的是 {正确的方向}。
{具体哪一部分} 可以保留，继续基于那部分往下做。

高效纠正的三个关键动作：

肯定可保留的部分——告诉 Claude 哪些是对的，不用推倒
精准指出偏差——具体说哪一句或哪个方案不对
给出正确方向——用一句话概括你真正想要的

渐进式纠正实例：

# 第一轮
用户：帮我在 src/components/ 下创建一个数据表格组件
Claude：[创建了一个支持排序、筛选、分页的表格]

# 第二轮（纠正）
用户：方向对了，但我想的是一个更轻量的表格。
不需要内置排序和筛选——数据由父组件传入时已经是最终状态。
保留分页功能。
还有，列定义的类型参考 src/types/table.ts。

结果是 Claude 删掉了排序和筛选逻辑，保留了分页，对齐了类型定义。两轮搞定，没有推倒重来。

28.3.4 渐进式细化的"止损信号"

当迭代到第三轮还没得到满意的结果时，通常不是 Prompt 的问题，而是：

任务本身太模糊，需要你先想清楚
任务太复杂，需要拆分成子任务
Claude 缺少关键上下文，你漏给了

此时应该停下来问自己：

[ ] 我自己能用一句话说清楚想要什么吗？如果不能，先理清思路
[ ] 这个任务是否应该拆成 2-3 个独立的小任务？
[ ] 我是否漏掉了关键的上下文（文件路径、技术栈、约束）？

28.4 常见 Prompt 反模式

知道了"应该怎么做"，还需要知道"不要怎么做"。以下是 Claude Code 使用中最常见的六种 Prompt 反模式。每一种都是从真实用户的对话中提炼出来的。

28.4.1 太模糊

坏 Prompt 的万能公式：动词 + 代词。"改一下代码"、"优化一下"、"帮我看看"。

反模式：

帮我改一下代码。

这个 Prompt 有三个问题：改哪个文件？怎么改？期望什么结果？Claude 必须追问——或者更糟，自己猜一个答案，然后你得到的是你完全不需要的东西。

修正后：

帮我重构 src/api/auth.ts，把回调改成 async/await。
当前的问题：错误处理分散在 5 层回调中，新增一个错误场景要改 3 个地方。

修正后的 Prompt 包含了：目标文件、具体操作、当前痛点。Claude 不需要猜任何一个维度。

28.4.2 一次要太多

想让 Claude 一次完成整个项目的重构，结果它在中途耗尽 token 或在某个环节卡住，留下一堆半成品。

反模式：

重构整个 src/ 目录，把所有回调改成 async/await。

src/ 目录可能有几十个文件、上百个函数。一次让 Claude 处理所有这些，结果几乎注定是：做到一半 token 耗尽，或者某个文件改坏了影响其他文件，或者 Claude 在中途"忘记"了最初的约定。

修正后：

我们先重构 src/api/auth.ts，把回调改成 async/await。完成后我确认效果，再继续下一个文件。

将大任务拆成 Claude 能在 10-15 个工具调用内完成的粒度。一个有效的判断标准：如果你在一句话里说不清这个任务，那它就需要拆分。

28.4.3 缺少约束

让 Claude 自由发挥，得到的代码风格、技术选型和项目完全不搭。

反模式：

写个登录页面。

Claude 可能用 React、Vue、Svelte、纯 HTML……可能引入 Redux、MobX、Zustand……可能用 CSS、SCSS、Tailwind……你无从预期。

修正后：

用 React + TypeScript 写登录页面。
- 参考 src/pages/Login.tsx 的风格（如果存在）
- 使用项目中已有的 src/components/Input.tsx 和 src/components/Button.tsx
- 表单状态管理用 React Hook Form（项目已安装）
- 不要引入新的依赖
- API 调用使用项目中已有的 src/api/client.ts

好的约束 = Claude 产出的代码可以直接用，不需要你手动替换依赖和调整风格。

28.4.4 反问式沟通

"你怎么不这样做？"——这句话对 Claude Code 来说信息量为零。

反模式：

你怎么不用 async/await？

Claude Code 不是人。它不会反思"哦对，我应该用 async/await"。它需要你明确告诉它：用什么方法、重新做什么。

修正后：

请用 async/await 重新实现刚才的 tokenRefresh 函数，去掉回调嵌套。

直接说"请用 X 方法重新实现 Y"，比"你怎么不用 X"高效一百倍。

28.4.5 假设 Claude 有记忆

Claude Code 在你当前的对话 session 中是有上下文的。但它不会"记得"三天前另一个对话里的内容。

反模式：

和上次一样，再改一下 auth 模块。

Claude Code 不知道"上次"是哪次、"一样"是什么一样。除非你在同一个对话 session 中，否则每次对话对 Claude 来说都是全新的。

修正后：

和当前 session 中第三次重构类似，再对 src/api/auth.ts 做一遍：
把回调改成 async/await，保持接口兼容。

如果引用的是本 session 内的内容，"像刚才那样"是可以的。但如果引用的是之前的 session，你必须重新描述需求。把每次对话当成第一次，是最高效的沟通策略。

28.4.6 过度礼貌/冗长

200 字的寒暄 + 300 字的需求 = Claude 要先过滤噪音。

反模式：

你好 Claude！希望你今天过得不错。我有一个小问题想请教你，
如果你方便的话可以帮我看看吗？事情是这样的，我们团队最近在
做一个项目……（200 字背景）……所以我想请你帮我改一下 auth.ts
文件里的一个函数，就是把回调改成 async/await。
先谢谢你了！非常感谢！你之前帮了我很大的忙！

Claude 不会因为礼貌而更努力工作。它会在理解你的 Prompt 时平等对待每一个词——包括那些寒暄和客套。长 Prompt 里的关键信息被稀释，反而更容易被误解。

修正后：

把 src/api/auth.ts 的 tokenRefresh 函数从回调改成 async/await。
约束：不改变接口签名。

简洁、直接、信息密度高。不需要寒暄，不需要客套，把 Claude Code 当成一个工具而不是一个人来沟通。这不是无礼——这是高效。

反模式速查表：
反模式特征修正方向
太模糊动词 + 代词（"改一下"）加文件路径 + 具体操作 + 原因
一次要太多范围是整个项目拆成 10-15 步内能完成的小任务
缺少约束只有功能描述加技术栈、风格、范围约束
反问式 "你怎么不 X？" "请用 X 方法重新实现"
假设记忆 "和上次一样" 重新描述需求
过度礼貌寒暄比需求长删掉寒暄，只保留需求

反模式	特征	修正方向
太模糊	动词 + 代词（"改一下"）	加文件路径 + 具体操作 + 原因
一次要太多	范围是整个项目	拆成 10-15 步内能完成的小任务
缺少约束	只有功能描述	加技术栈、风格、范围约束
反问式	"你怎么不 X？"	"请用 X 方法重新实现"
假设记忆	"和上次一样"	重新描述需求
过度礼貌	寒暄比需求长	删掉寒暄，只保留需求

28.5 Claude Code 特有的 Prompt 技巧

前面四节讲的适用于任何 LLM 工具。但 Claude Code 作为一个专门为软件开发设计的 Agent 工具，有一些独特的 Prompt 技巧。这些技巧利用了 Claude Code 对文件系统、Git、工具链的深度集成，是一般 ChatGPT 或 API 调用不具备的能力。

28.5.1 先读后改

这是 Claude Code 最重要的使用模式。不要让 Claude 凭空写代码——让它先读取相关代码，理解上下文后再动手。

先读取 src/api/ 下所有与 auth 相关的文件，理解当前的 token 管理机制。
然后重构 token 刷新逻辑，解决竞态条件问题。

对比"直接改"的模式：

重构 token 刷新逻辑，解决竞态条件问题。  # Claude 可能看错文件或漏掉关键依赖

为什么有效：Claude Code 的上下文窗口是有限的。当你让它"先读"，它会用 Read 工具把相关文件的内容加载到上下文中，之后的修改就有了准确的依据。而"直接改"意味着 Claude 要么从零猜测，要么边改边读，效率低且容易出错。

适用场景：

修改你不熟悉的模块
跨多个文件的变更
重构前的摸底分析

28.5.2 指定工具

Claude Code 有十几个内置工具。当你明确知道某个任务适合用什么工具时，直接指定。

<!-- 不要模糊地说"找文件" -->
用 Glob 找出 src/ 下所有 .test.ts 文件。

<!-- 不要模糊地说"搜代码" -->
用 Grep 搜索 src/ 下所有使用 deprecated API 的地方，pattern: "deprecated|@deprecated"。

<!-- 不要模糊地说"看看改了啥" -->
用 Bash(git diff --stat) 查看变更概览，然后对变更的每个文件用 Read 读取完整内容。

常用工具与适用场景：

工具	指定场景
`Glob`	按文件名模式找文件（如 "所有 .test.ts"）
`Grep`	按内容搜索（如 "所有调用 fetchUser 的地方"）
`Read`	读取指定文件内容
`Bash(git diff)`	查看代码变更
`Bash(git log)`	查看提交历史
`Bash(npm test)`	运行测试
`Task`	并行执行多个独立子任务

进阶用法——工具链编排：

第一步：用 Glob 找出 src/api/ 下所有 .ts 文件。
第二步：用 Grep 在每个文件中搜索 "any" 关键字。
第三步：对每个包含 "any" 的文件，用 Read 读取完整内容。
第四步：分析每个 "any" 的使用是否合理，给出替换为具体类型的建议。

28.5.3 引用文件

Claude Code 支持用 @ 符号引用文件，让 Claude 直接读取该文件的内容作为参考。

在 src/pages/ 下创建一个 Dashboard 页面。
布局风格参考 @src/pages/Settings.tsx
数据获取方式参考 @src/hooks/useFetch.ts

@ 引用告诉 Claude Code "把这个文件的内容也加载到上下文中"。这比"参考 Settings 的风格"更精确——Claude 看到了实际代码，而不是靠猜测"Settings 的风格"是什么。

可以直接引用的内容：

@文件路径 — 单个文件
@目录路径 — 目录下所有文件
粘贴的错误堆栈、JSON 数据、日志片段（虽然不是 @ 语法，但同样直接提供）

28.5.4 利用 Git 感知

Claude Code 自带对 Git 仓库的感知能力。它知道当前的 branch、变更状态、提交历史。你可以在 Prompt 中直接利用这些信息。

看看当前的 git diff，针对这次变更写一个中文 commit message。
要求：符合 conventional commits 格式，简要描述做了什么、为什么做。

对比当前分支和 main 分支的差异（git diff main...HEAD），
生成一份 Pull Request 描述，包含：
- 变更概述
- 主要改动点
- 影响范围
- 测试说明

查看最近 5 个 commit，分析团队的提交风格，
然后为当前变更生成一个符合团队习惯的 commit message。

Git 感知让 Claude Code 不仅仅是"代码助手"，而是"项目助手"——它能理解你的代码处于什么状态、你正在做什么类型的变更。

28.5.5 分阶段执行

复杂任务不要一步到位。用明确的阶段划分，让 Claude 在每个阶段结束时停下来等你确认。

这个任务分四个阶段执行：
1. 分析阶段：读取相关文件，理解当前结构，列出发现（不修改任何文件）
2. 方案阶段：给出重构方案，包含改动范围和预期影响，等我的确认
3. 执行阶段：逐步执行修改，每改完一个文件后运行该文件的测试
4. 收尾阶段：运行全量测试，生成变更摘要

现在开始第一阶段。

为什么需要分阶段：

复杂任务的方向容易偏，阶段间确认能及时纠偏
每一阶段的输出是下一阶段的输入，质量层层递进
如果方向不对，你只需要舍弃一个阶段而非整个对话

适合分阶段的任务：

涉及 5 个以上文件的重构
架构级别的调整
不熟悉模块的摸底分析
任何你说不清"最终结果应该长什么样"的任务

28.5.6 利用 CLAUDE.md

CLAUDE.md 是 Claude Code 每次启动时自动加载的项目说明书。你可以在 Prompt 中引用 CLAUDE.md 中的约定，让 Claude 遵循项目规范。

按照 CLAUDE.md 中约定的编码规范，在 src/api/ 下创建一个新的 user 模块。

检查 src/api/auth.ts 是否遵循了 CLAUDE.md 中列出的编码规范。
对不符合的地方，列出清单并给出修复建议。

这省去了每次 Prompt 中重复声明项目规范的工作。写下一次 CLAUDE.md，受益于每一次 Prompt。

如果 CLAUDE.md 中还没有编码规范，现在是时候加上去了。以下是一段可参考的规范模板：

markdown

## 编码规范

- 语言：TypeScript 严格模式（noImplicitAny: true）
- 格式：使用 Prettier 默认配置
- 命名：文件名 kebab-case，变量/函数 camelCase，类型/接口 PascalCase
- 导入顺序：第三方库 → 项目内模块 → 相对路径
- 注释：公共 API 使用 JSDoc，内部逻辑用单行注释
- 错误处理：使用 Result 类型或 try-catch，不吞异常
- 测试：每个模块对应一个 .test.ts 文件，使用 vitest

六个技巧速记：先读后改、指定工具、引用文件、Git 感知、分阶段、用 CLAUDE.md。这六个技巧利用了 Claude Code 作为 Agent 的独特能力，是通用 LLM 工具做不到或做不好的。

28.6 本章小结

Prompt 工程的本质不是"写出华丽的提示词"，而是清晰沟通。当你能精准地告诉 Claude Code 你是谁、在哪里、做什么、怎么做、做成什么样时，你就掌握了这门手艺的核心。

本章的核心要点：

RCCF 四要素：角色、上下文、约束、输出格式。四个要素齐全的 Prompt，Claude 猜得少，你改得少。
模板库不是偷懒，是复用经验。将常见任务的 Prompt 模板化，每次填空而非每次重写，稳定且高效。
渐进式细化的三个层次：先概括后聚焦（空间维度）、What → Why → How（逻辑维度）、精准纠正（修正维度）。Iterate, don't restart。
六种反模式：太模糊、一次太多、缺约束、反问式、假设记忆、过度礼貌。识别它们，避免它们。
Claude Code 六技：先读后改、指定工具、引用文件、Git 感知、分阶段、用 CLAUDE.md。这些是 Claude Code 作为 Agent 工具的独有优势。

最好的 Prompt 不是最长的，而是最精准的。当你不再需要"猜 Claude 会怎么理解"，而是"确信 Claude 会怎么理解"，你就真正掌握了 Prompt 工程。

下一章，我们将把视角从"你怎么对 Claude Code 说"转向"你怎么让项目本身对 Claude Code 友好"——为 AI 友好的项目工程学。

第 28 章：Prompt 工程 ​

28.1 好 Prompt 的四个要素 ​

28.1.1 角色（Role） ​

28.1.2 上下文（Context） ​

28.1.3 约束（Constraints） ​

28.1.4 输出格式（Format） ​

28.1.5 四要素组合范例 ​

28.2 Prompt 模板库 ​

28.2.1 代码生成 ​

28.2.2 代码分析 ​

28.2.3 重构 ​

28.2.4 调试 ​

28.2.5 文档生成 ​

28.3 渐进式细化技巧 ​

28.3.1 先概括，后聚焦 ​

28.3.2 "What → Why → How" 模式 ​

28.3.3 当 Claude 理解错了——如何高效纠正 ​

28.3.4 渐进式细化的"止损信号" ​

28.4 常见 Prompt 反模式 ​

28.4.1 太模糊 ​

28.4.2 一次要太多 ​

28.4.3 缺少约束 ​

28.4.4 反问式沟通 ​

28.4.5 假设 Claude 有记忆 ​

28.4.6 过度礼貌/冗长 ​

28.5 Claude Code 特有的 Prompt 技巧 ​

28.5.1 先读后改 ​

28.5.2 指定工具 ​

28.5.3 引用文件 ​

28.5.4 利用 Git 感知 ​

28.5.5 分阶段执行 ​

28.5.6 利用 CLAUDE.md ​

28.6 本章小结 ​

第 28 章：Prompt 工程

28.1 好 Prompt 的四个要素

28.1.1 角色（Role）

28.1.2 上下文（Context）

28.1.3 约束（Constraints）

28.1.4 输出格式（Format）

28.1.5 四要素组合范例

28.2 Prompt 模板库

28.2.1 代码生成

28.2.2 代码分析

28.2.3 重构

28.2.4 调试

28.2.5 文档生成

28.3 渐进式细化技巧

28.3.1 先概括，后聚焦

28.3.2 "What → Why → How" 模式

28.3.3 当 Claude 理解错了——如何高效纠正

28.3.4 渐进式细化的"止损信号"

28.4 常见 Prompt 反模式

28.4.1 太模糊

28.4.2 一次要太多

28.4.3 缺少约束

28.4.4 反问式沟通

28.4.5 假设 Claude 有记忆

28.4.6 过度礼貌/冗长

28.5 Claude Code 特有的 Prompt 技巧

28.5.1 先读后改

28.5.2 指定工具

28.5.3 引用文件

28.5.4 利用 Git 感知

28.5.5 分阶段执行

28.5.6 利用 CLAUDE.md

28.6 本章小结