如何写好 Claude Code 的提示词

约 2918 字大约 10 分钟

2026-03-20

前言

用 Claude Code 写代码，很多人的体验是「时灵时不灵」—— 有时候一句话就能搞定复杂功能，有时候反复沟通还是差点意思。

差距在哪？提示词的质量。

Claude Code 不是聊天机器人，它是一个代理式编码环境（Agentic Coding Environment）。你给它的每一条指令，都在影响它的「思考路径」和「行动策略」。写好提示词，不是在「哄 AI」，而是在精确地表达意图。

这篇文章会从 Claude Code 的提示词体系讲起，然后分享我在实际使用中总结的提示词技巧和模式。

Claude Code 的提示词层级

很多人以为 Claude Code 只看你在终端里敲的那句话。实际上，它的上下文由多层提示词叠加而成：

┌─────────────────────────────────┐
│  System Prompt（系统提示词）       │  ← Anthropic 内置，不可修改
├─────────────────────────────────┤
│  ~/.claude/CLAUDE.md            │  ← 全局指令，所有项目通用
├─────────────────────────────────┤
│  项目根目录/CLAUDE.md            │  ← 项目级指令，团队共享
├─────────────────────────────────┤
│  项目根目录/CLAUDE.local.md      │  ← 个人本地指令
├─────────────────────────────────┤
│  子目录/CLAUDE.md               │  ← 目录级指令，按需加载
├─────────────────────────────────┤
│  用户输入（你敲的每条消息）         │  ← 优先级最高
└─────────────────────────────────┘

System Prompt：底层操作系统

System Prompt 是 Anthropic 内置的指令集，定义了 Claude Code 的核心行为：

工具使用规则：什么时候用 Read、Edit、Bash、Grep 等工具
安全边界：不执行危险操作、不推送未确认的代码
输出风格：简洁直接、不加 emoji、不过度解释
行为准则：先读再改、最小改动、不过度工程化

你无法修改 System Prompt，但理解它很重要 —— 因为你的指令会与它交互。比如 System Prompt 告诉 Claude「避免过度工程化」，如果你的 CLAUDE.md 里写了一堆抽象层要求，两者就会产生冲突。

CLAUDE.md：持久化的提示词

如果说每次对话输入的是「临时指令」，那 CLAUDE.md 就是「持久化的提示词」。它的价值在于：

不用重复说：项目规范、常用命令、架构约定写一次，每次对话自动加载
团队共享：提交到 Git，所有人用同一套上下文
分层管理：全局通用的放 ~/.claude/CLAUDE.md，项目特定的放项目根目录

详细的 CLAUDE.md 编写指南见 CLAUDE.md 配置

用户输入：最高优先级

你在终端里输入的每条消息，优先级最高。即使 CLAUDE.md 里写了「使用 tabs 缩进」，你说「这个文件用 2 spaces」，Claude 会听你的。

理解了这个层级关系，你就知道应该把什么放在哪里：

信息类型	放在哪里	原因
代码规范、项目架构	CLAUDE.md	长期有效，不用每次重复
个人偏好（语言、风格）	~/.claude/CLAUDE.md	跨项目通用
本次任务的具体需求	用户输入	一次性的、具体的
敏感信息、个人配置	CLAUDE.local.md	不提交到 Git

提示词的核心原则

1. 说「要什么」，而不是「怎么做」

Claude Code 是一个 Agent，它会自己规划执行路径。你要做的是清晰描述目标，而不是手把手指挥。

- "打开 src/utils/auth.ts，找到 validateToken 函数，在第 42 行后面加一个
-  if 判断，检查 token 是否过期，如果过期就抛出 TokenExpiredError"

+ "validateToken 函数目前没有检查 token 过期时间，请添加过期检查，
+  过期时抛出 TokenExpiredError"

前者像是在写伪代码，限制了 Claude 的发挥空间。后者描述了问题和期望，让 Claude 自己决定最佳实现方式。

但也不要太模糊：

- "优化一下这个项目"

+ "首页加载时间超过 3 秒，主要瓶颈是图片资源。请分析 src/pages/Home.vue
+  中的图片加载策略，添加懒加载和适当的压缩"

2. 提供验证标准

这是 Claude Code 官方反复强调的第一原则：给 Claude 一种验证自己工作的方式。

实现一个 rate limiter 中间件：
- 每个 IP 每分钟最多 100 次请求
- 超限返回 429 状态码，响应体包含 retryAfter 字段
- 写完后运行 pnpm test 确认测试通过

有了验证标准，Claude 会在完成后自动运行测试，发现问题自己修复，而不是把一个「可能能用」的结果丢给你。

3. 提供足够的上下文

Claude Code 可以读取你的代码库，但它不知道你脑子里的背景信息。

- "修复登录 bug"

+ "用户反馈：使用 Google OAuth 登录后，页面跳转回首页但显示未登录状态。
+  怀疑是 callback 处理中 session 没有正确写入。
+  相关文件在 src/auth/ 目录下。"

好的上下文包括：

问题的表现：用户看到了什么
你的假设：你觉得可能是什么原因
范围限定：相关的文件或模块

4. 分阶段推进复杂任务

一个 prompt 塞太多东西，效果往往不好。利用 Claude Code 的 Plan Mode 分阶段推进：

# 第一步：探索（Plan Mode）
> 阅读 src/api/ 目录，理解当前的 API 认证机制和中间件结构

# 第二步：规划（Plan Mode）
> 我想把认证从 JWT 迁移到 Session-based。给出迁移计划，
> 列出需要修改的文件和步骤

# 第三步：执行（Normal Mode）
> 按照你的计划执行迁移，每个步骤完成后运行测试套件验证

5. 利用 Context 管理保持高效

Claude Code 的 context window 是有限的。长对话会导致早期指令被「遗忘」，性能逐步下降。

几个实用技巧：

一个任务一个会话：完成当前任务后开新会话，而不是在同一个会话里不断追加
用 /compact 压缩：对话过长时手动压缩上下文
善用 @ 引用文件：比起让 Claude 自己搜索，直接 @src/config.ts 更省 token
避免粘贴大段代码：Claude 可以自己读文件，不需要你复制粘贴

实用提示词模式

模式一：Bug 修复

Bug 描述：[具体的错误表现]
复现步骤：[1. 2. 3.]
错误日志：[粘贴关键日志]
期望行为：[应该怎样]
相关文件：[文件路径或模块名]

请定位根因并修复，修复后运行 [测试命令] 验证。

示例：

Bug：用户列表页面在筛选后翻页，页码重置了但数据没有刷新，
还是显示上一次筛选条件的结果。

复现：打开 /admin/users → 输入搜索关键词 → 点击搜索 → 翻到第2页
→ 修改搜索关键词 → 点击搜索 → 注意第1页的数据还是旧的

相关文件：src/pages/admin/UserList.vue

请定位问题并修复，修复后运行 pnpm test 验证。

模式二：新功能开发

需求：[功能描述]
用户场景：[谁在什么情况下用]
技术约束：[需要兼容什么、不能改什么]
验收标准：[怎样算完成]

示例：

需求：在文章详情页添加「预计阅读时间」显示。

用户场景：读者打开文章时，在标题下方看到预计阅读时间（如 "5 分钟阅读"）。

技术约束：
- 按中文 300 字/分钟计算，英文 200 词/分钟
- 代码块不计入阅读时间
- 复用现有的 PostMeta 组件样式

验收标准：
- 文章详情页正确显示阅读时间
- 短文章（<1分钟）显示 "不到 1 分钟"
- 开发服务器能正常运行

模式三：代码重构

重构目标：[要改善什么]
当前问题：[现在的代码有什么问题]
约束：[不能改变的外部接口或行为]
验证方式：[如何确认重构没有破坏功能]

示例：

重构 src/services/order.ts 中的 createOrder 函数。

当前问题：这个函数有 200 多行，混合了参数校验、库存检查、
价格计算、订单创建、通知发送等逻辑，很难维护和测试。

目标：拆分成职责单一的小函数，保持相同的外部接口。

约束：createOrder 的入参和返回值不能变，因为有 3 个地方在调用它。

验证：重构后运行 pnpm test:unit -- --grep "order" 确认所有订单相关测试通过。

模式四：代码审查

请审查 [文件/PR] 的代码变更，关注：
- 潜在的 bug 或边界情况
- 性能问题
- 安全隐患
- 可读性和可维护性

给出具体的改进建议，按严重程度排序。

模式五：学习和理解

解释 [文件/模块] 的实现：
- 整体架构和数据流
- 关键设计决策及其原因
- 与其他模块的依赖关系

用 [类比/层级] 的方式讲解，我对 [领域] 比较熟悉。

反模式：这些写法要避免

1. 一次要求太多

- "给项目添加用户系统，包括注册、登录、权限管理、OAuth 集成、
-  邮箱验证、密码重置、双因素认证、用户 Profile 页面"

+ 先从核心开始：
+ "实现基础的用户注册和登录功能，使用 JWT 认证。
+  先创建 User 模型和 /api/auth/register、/api/auth/login 两个接口。
+  写完后运行测试验证。"

2. 过度指定实现细节

- "在第 15 行和第 16 行之间插入 const cache = new Map()，
-  然后在第 23 行的 if 语句里加 cache.get(key)"

+ "fetchUserData 函数每次都发网络请求，请添加内存缓存，
+  缓存有效期 5 分钟"

3. 模糊的「优化」请求

- "优化这个组件"
- "让代码更好"
- "性能有问题，帮我看看"

+ "这个列表组件在渲染 1000 条数据时明显卡顿，请添加虚拟滚动"
+ "这个函数的圈复杂度太高（当前 25），请重构降低到 10 以下"

4. 忽略验证

- "实现 XX 功能"  # Claude 写完就结束了，你要自己验证

+ "实现 XX 功能，完成后运行测试套件并确认通过"

进阶技巧

用 CLAUDE.md 固化高频指令

如果你发现自己总是在重复同样的话，把它写进 CLAUDE.md：

## Conventions
- 所有新组件必须包含 TypeScript 类型定义
- API 响应统一使用 { code, data, message } 格式
- 修改数据库模型后必须生成并运行 migration
- 提交前运行 pnpm lint && pnpm test

用图片辅助 UI 需求

Claude Code 支持视觉输入。对于 UI 相关的需求，截图比文字描述高效 10 倍：

[粘贴设计稿截图]

请按照这个设计实现用户 Profile 卡片组件。
使用 Tailwind CSS，响应式布局，移动端居中堆叠。
完成后截图对比设计稿。

利用 Hooks 自动化质量保证

通过 Hooks 配置，可以让 Claude Code 在特定操作后自动执行检查：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "pnpm lint --fix ${file}"
      }
    ]
  }
}

这样每次 Claude 编辑文件后，都会自动跑 lint 修复，省去手动提醒。

利用 @ 符号精确引用

# 引用特定文件作为上下文
> @src/types/user.ts 基于这个类型定义，实现 UserService 的 CRUD 方法

# 引用整个目录
> 阅读 @src/middleware/ 下的所有中间件，添加一个请求日志中间件，
> 风格与现有中间件保持一致

总结

写好 Claude Code 的提示词，核心就四点：

清晰的意图 —— 说清楚要什么，而不是怎么做
充足的上下文 —— 提供背景、约束和相关文件
明确的验证标准 —— 让 Claude 能自己检查结果
合理的粒度 —— 复杂任务分步推进，一次做一件事

Claude Code 是你的编程搭档，不是执行指令的机器。你给它的提示词越接近「和一个靠谱同事沟通」的方式，效果就越好。