📊 页面导航
适用角色与上手难度
🎯 学习产出： 掌握 Claude Code 提示词编写的核心方法论，能独立写出高精度指令
🚀 AI 能力提升： 代码生成、需求表达
提示词编写技巧
预计阅读时间: 21 分钟
Claude Code 的能力上限很大程度上取决于你的提示词质量。同样的需求，不同的表达方式，输出质量可能天差地别。本文从认知模型出发，系统化地拆解提示词编写的核心技巧。
Tip
本文聚焦怎么写好提示词。如果你刚开始接触 Claude Code，建议先阅读第一次对话了解基本交互。
想系统化提升 AI 输出准确率（不仅仅是提示词），参考 提高 AI 生成准确率。
核心理念：把 AI 当新同事
Claude Code 像一个刚加入团队的高级工程师——技术能力很强，但对你的项目一无所知。你不能只说"修一下那个 bug"，而要说清楚上下文、技术栈、期望结果。
记住这三个原则：
- 不说你已知的，AI 不知道的事——项目结构、命名规范、业务逻辑
- 具体比简短好——一行清晰指令 > 十行模糊追问
- 给错误例子比不给好——告诉 AI 不要什么和告诉它要什么同样重要
要不要说"请"和"帮我"
很多人习惯在提示词中加上礼貌用语：
> 请你帮我把用户列表的排序改成按注册时间倒序，谢谢！
结论：不影响生成效果，但浪费 token。
Claude Code 是一个推理模型，不是情感模型。它不会因为你说"请"就更认真，也不会因为你说"谢谢"就多做一步。"请帮我"这三个字对模型来说和空格没有区别——不改变注意力分布，不提升推理深度，不触发任何特殊行为模式。
从 token 经济角度看：
每句话省 10 个 token，一天上百条对话，累积省下的上下文窗口可以多放一段真实的代码参考。
但要分场景：
一条好记的规则：AI 只吃信息，不吃态度。把省下的字数拿去写更具体的需求。
结构化提示词：六要素法
一个好的提示词通常包含六个要素。不是每次都需要全部六个，但要素越全，结果越精准。
六大要素
实战示例
❌ 糟糕的提示词：
✅ 好的提示词：
# 角色
你是一个专注 Next.js 性能的资深前端开发者。
# 上下文
项目使用 Next.js 14 App Router + Prisma + Tailwind。
页面：src/app/users/page.tsx，目前是客户端渲染，首次加载 ~4s。
# 目标
把 /users 页面的用户列表从 CSR 改为 RSC（React Server Component），
用 Prisma Client 直接在 Server Component 里查数据库。
# 约束
- 不要改动现有的 UI 样式和布局
- 搜索和筛选功能先用 URL searchParams，不引入额外状态库
- 保持 TypeScript 严格模式
# 验收标准
- npm run build 无报错
- 列表页首屏 HTML 包含用户数据（SSR 成功）
- 首次内容绘制（FCP）从 ~4s 降到 < 2s
什么时候用哪些要素
上下文管理：给够但不给多
Claude Code 的上下文窗口有限。给太多无关信息会稀释关键信号，给太少则缺少判断依据。
提供上下文的方式
1. 直接描述（一次性的）：
> 项目用 Express + TypeScript，JWT 存在 httpOnly cookie 里。
> 帮我把 /api/auth/refresh 接口改成同时支持 cookie 和 Authorization header。
2. 引用文件（推荐）：
> 参考 src/config.ts 里的数据库配置，给 src/db/schema.ts 加上 createdAt 和 updatedAt 字段
Claude Code 会自动读取引用路径，无需你手动粘贴代码。
3. 建立项目记忆（长期的）：
在 CLAUDE.md 中记录项目规范：
# 项目规范
- 组件用 named export，不用 default export
- API 错误统一返回 { error: { code, message } }
- 数据库字段用 snake_case，TypeScript 用 camelCase
这样每次对话 AI 都会自动读取这些规范，无需重复说明。
多少上下文算合适
太少："修复这个接口" ← AI 不知道是哪个接口
刚好："src/api/users.ts 的 GET /users 接口缺少分页" ← 定位精准
太多：把整个 src/api/ 目录复制过来 ← 信息噪音
提示词模板集
以下是可以直接套用的模板。把 [...] 替换成你的具体内容。
功能开发
在 [文件路径] 中实现 [功能描述]。
技术栈：[Next.js 14 / Express / Django / ...]
要求：
- [具体要求 1]
- [具体要求 2]
不改动：[明确说不改什么]
参考：
- 现有的 [类似功能] 在 [文件路径]
Bug 修复
Bug 描述：[具体现象和复现步骤]
定位：发生在 [文件路径] 的 [函数名/组件名]
期望行为：[正确的结果应该是什么]
提示：[你已经排查过的方向，或者怀疑的原因]
代码审查
审查 [文件路径] 的 [变更范围]。
关注点：
- [关注点 1，比如：是否有 SQL 注入风险]
- [关注点 2，比如：错误处理是否完整]
忽略：[明确说不关注什么，比如代码风格]
重构
重构 [文件路径] 的 [目标部分]。
目标：[更好的可读性 / 减少重复 / 提升性能 / ...]
约束：
- 不改变外部接口
- 保持向后兼容
- 不改动测试文件
如果你的方案有多个选项，先列出对比让我选。
探索分析
分析 [目录/文件] 的 [关注问题]。
我需要了解：
- [问题 1]
- [问题 2]
输出格式：用 Markdown 表格对比，每条附一行建议
常见错误
1. 一次给太多任务
❌ 错误：
> 把用户模块的接口重构一下，加上分页和排序，顺便把认证中间件也优化一下，
> 然后给前端加个骨架屏，最后更新一下 README
✅ 正确： 拆成多个独立指令，逐个完成。
2. 以为 AI 还记得上一条对话
❌ 错误：
（前一条对话讨论了数据库设计）
> 按之前说的，生成 migration
✅ 正确： 每次带上关键上下文。
> 根据之前讨论的数据库设计（users 表：id, name, email, role），生成 Prisma migration
3. 用了太模糊的形容词
❌ 错误：
✅ 正确： 用可量化的词替代。
4. 在一条指令里给矛盾信息
❌ 错误：
✅ 正确： 先理清矛盾点。
> 把这个组件拆成更小的子组件。所有子组件放在同一个文件里，用 named export 导出。
进阶技巧
让 AI 先反问
需求本身不清楚时，与其写一个模糊的提示词然后反复改，不如让 AI 先提问：
> 我需要给 /api/users 接口加上权限控制。在开始之前，如果你有任何不确定的地方，先问我，确认清楚再动手。
效果：AI 会列出它的疑问——"哪些角色可以访问？权限粒度是接口级还是字段级？认证方式是 JWT 还是 session？"——你一次性回答完，代码质量远超反复纠正。
适合场景：需求边界模糊、涉及多条业务规则、需要做架构决策。
分步确认模式
大任务拆成两步走，先看计划再执行：
> 我要重构 src/services/order.ts，拆成 createOrder / updateOrder / cancelOrder 三个独立模块。
> 先列出你的拆分方案和每个模块的职责边界，等我确认后再动手。
关键区别：一个指令拆成两轮交互。第一轮只输出计划（token 成本几乎为零），确认方向正确后再花 token 写实际代码。方向错了直接改计划，比写完整代码再改省 5-10 倍 token。
显式否定：说"不要"有时候比说"要"更省
AI 的搜索空间非常大。排除错误方向比穷举正确方向更高效：
> 不要用 class component
> 不要引入新的 npm 依赖
> 不要改现有的 export 接口
> 不要用 any 类型
技巧：DO/DON'T 对比格式在越复杂的任务中越有效：
要求：
✅ DO：用 React Server Components + Server Actions
✅ DO：所有表单用 react-hook-form + zod
✅ DO：错误状态用 ErrorBoundary 包裹
❌ DON'T：不要用 useState + useEffect 做数据请求
❌ DON'T：不要创建新的 API route
❌ DON'T：全局状态不要用 useContext（用 URL searchParams 替代）
二次提示：追加式修正
AI 输出接近但不是完全正确时，最常见的错误是重写整个提示词。更好的做法——追加一条简短的修正指令：
# 第一次
> 给 src/components/UserTable.tsx 加上排序功能
# AI 输出了，但排序方向反了，且缺少 loading 状态
# ❌ 不要这样——重写整个提示词
> 给 src/components/UserTable.tsx 加上排序功能，默认降序，加上 loading...
# ✅ 追加修正即可
> 1. 排序默认改成降序
> 2. 数据加载时显示 loading skeleton
> 其他保持不变
追加修正 > 重写提示词。每次重写都在消耗你刚建立的上下文对齐。
版本锁定防漂移
AI 训练数据覆盖多个版本，你不说版本号，它可能用到你项目里不存在的 API：
# ❌ 没有版本约束
> 用 Prisma 写一个用户查询
# ✅ 锁版本
> 用 Prisma v5.x 写一个用户查询，不要用 v6 的新 API
> 用 Next.js 14 App Router，不用 Pages Router
> 用 React 18，不用 React 19 的 use() hook
利用 CLAUDE.md 消除重复
如果你发现自己反复在提示词中说同一个约束，把它写进 CLAUDE.md：
# CLAUDE.md（项目根目录）
## 代码规范
- 不要用 default export，统一用 named export
- 组件文件用 PascalCase，工具文件用 kebab-case
- API 错误统一返回 { error: { code: string, message: string } }
- 不要用 any，确实无法推断时用 unknown
## 技术约定
- 本项目锁定 React 18 + Next.js 14 Pages Router
- 状态管理用 Zustand，不用 Redux
- 测试用 Vitest，不用 Jest
之后每次对话 AI 自动读取，你的提示词可以省略这些重复说明——每条指令省 50-100 token。
参考：CLAUDE.md 集合 了解更多实际用法。
用好 @ 和路径引用
Claude Code 能理解项目文件路径。与其粘贴代码或模糊描述，直接给路径：
> 参照 src/utils/api.ts 里 createRequest 的错误处理方式，
> 给 src/services/auth.ts 的所有函数加上同样的错误处理
更深层的技巧——用 @ 引用目录让 AI 自己探索：
> 查看 src/api/routes/ 目录下的所有路由文件，
> 统一给每个接口加上 try-catch 错误包装
AI 会自动读取目录结构，找到所有路由文件并逐个处理。比你自己数有哪些文件再一个个点名高效得多。
给 AI 一个诚实出口
强制性要求会让 AI 在有歧义的情况下强行猜测。加上退路反而提高质量：
> 如果你不能 100% 确定某个 API 的用法，标注为 [待确认] 并说明你的猜测依据。
> 不要假装确定——我宁愿多确认一次，也不要猜错了再改。
效果：对于训练数据模糊的技术点，AI 会主动标注不确定性而非悄悄用错。
迭代优化：别指望一步到位
即使是最好的提示词，第一次结果也不一定完美。把 AI 当成可对话的工具，不要当作一次性命令。
迭代流程
你：[详细提示词]
AI：[输出结果]
你："第 2 点不对，应该用 useReducer 而不是 useState"
AI：[修正]
你："类型定义再加一个 metadata 字段，也是可选的"
AI：[继续修正]
你："好了，这次的可以。给我加上 JSDoc 注释"
关键习惯：每次只修正一个维度，避免一条消息里同时要求修改逻辑、样式、测试。
如果 AI 一直不对
> 你三次都在 XXX 上出错了。请先解释你对这个需求的理解，确认我们理解一致后再写代码。
强制 AI 先解释理解，比对后再动手——比反复纠正高效得多。
技巧速查
下一步
掌握了提示词编写技巧后，你已经有能力让 Claude Code 高效工作了。接下来可以学习：
