内容来源：SurePrompts。https://sureprompts.com/blog/claude-code-prompting-guide
原题：Claude Code Prompting Guide (2026)
原发布时间：2026-04-20
如何为 Anthropic 原生终端编程智能体 Claude Code 编写提示词，涵盖
CLAUDE.md文件、斜杠命令、Hooks、MCP 服务器，以及范围明确的工作单式提示词。
为 Claude Code 写好提示词，与其说像聊天，不如说像填写工作单。Claude Code 是 Anthropic 的原生终端编程智能体：它在你的工作目录中运行，可以执行 Shell 命令、编辑文件，并不断迭代任务。因此，提示词需要预先给出范围、上下文、停止条件和验证方法。这样做的回报是：减少反复修改、减少改错文件，也减少那些最后被证明只是一厢情愿的“我想我已经修好了”。本指南将介绍 Claude Code 与聊天工具有何不同，以及如何使用 CLAUDE.md、斜杠命令、Hooks、MCP 服务器和子智能体。
Claude Code 是什么
Claude Code 是 Anthropic 推出的 CLI 编程智能体。你在代码仓库内通过终端启动它，它会直接操作当前工作目录中的文件。不同于聊天窗口，它拥有一套可以使用的工具：通过 Bash 运行 Shell 命令，通过 Read 打开文件，通过 Edit 和 Write 修改或创建文件，再通过 Grep 和 Glob 搜索内容。它还具备权限模型：你可以把命令加入允许列表、要求危险命令先获得确认，也可以完全禁止破坏性操作。
由于智能体可以运行测试、对代码进行类型检查并检查仓库，最好的提示词会把验证工作交给智能体本身。你不是要求它猜测某项功能是否正常，而是明确告诉它哪些命令能够证明功能正常。
如需了解更广泛的背景，请阅读支柱文章：AI 编程智能体提示词完全指南。类别定义请参阅智能体式 AI。
Claude Code 提示词与 ChatGPT 或 Claude.ai 聊天有何不同
聊天模型会返回一条优秀的后续消息；Claude Code 则会返回一系列文件编辑、Shell 命令执行结果和观察，并逐步收敛至目标。
| 维度 | Claude.ai / ChatGPT 聊天 | Claude Code |
|---|---|---|
| 交互 | 单轮对话 | 多步骤自主执行 |
| 文件 | 由你粘贴片段 | 直接读取、编辑和写入 |
| 工具 | 通常没有 | Bash、Read、Edit、Write、Grep、Glob |
| 验证 | 由你手动检查答案 | 智能体运行测试和类型检查器 |
| 成功标准 | “给出有帮助的回答” | “测试通过、遵守范围、差异干净” |
| 典型失败 | 回答错误或含糊 | 编辑错误文件、陷入循环、虚构 API |
| 解决方式 | 换一种问法 | 收紧规格，增加停止条件 |
“把它重构得更干净”这种聊天式提示词没有为 Claude Code 提供明确目标。它可能改动你不希望触碰的内容，又在没有运行测试的情况下宣布大功告成。把相同请求写成工作单——目标、范围、文件、验收标准、停止条件——就能迅速收敛，并产出便于审查的差异。有关这套方法，请参阅规格驱动的 AI 编程。
CLAUDE.md 文件：持久的项目需求说明
CLAUDE.md 是 Claude Code 用来了解项目基本规则的文件。无需在每条提示词中重复相同上下文，只需写一次，智能体就会在会话开始时读取。
有三层文件需要区分：
• 全局（~/.claude/CLAUDE.md）：适用于所有项目的个人偏好，如编码风格、Git 工作流和提交格式。
• 项目根目录（/your-repo/CLAUDE.md）：当前仓库的事实，如技术栈、脚本、项目约定和禁止触碰的目录。
• 子目录（/your-repo/some-module/CLAUDE.md）：使用不同约定的模块所需的局部上下文，例如旧代码文件夹或生成的客户端。
Claude Code 会读取与当前文件最相关、最具体的 CLAUDE.md，因此子目录文件会在处理该子目录中的内容时扩展项目根目录规则。
下面是一份合理的项目 CLAUDE.md：
# 项目：Acme Billing Service
## 技术栈
- TypeScript（严格模式）、Node 20、Next.js 15（App Router）
- 通过 Prisma 使用 PostgreSQL
- 测试：Vitest（`pnpm test`）。类型检查：`pnpm typecheck`。Lint：`pnpm lint`。
## 约定
- 仅使用函数组件。数据不可变，不得原地修改。
- 文件控制在约 400 行以内，函数控制在约 50 行以内。
- 在系统边界通过 Zod 校验外部输入。
## 目录规则
- `src/app/`：路由。优先使用服务器组件。
- `src/lib/`：纯工具函数。不得发起网络调用。
- `src/server/`：仅限服务器端。客户端组件绝不能从此处导入。
- `prisma/migrations/`：不得手动编辑；使用 `pnpm prisma migrate dev`。
## 验证
宣布任务完成前，运行 `pnpm typecheck && pnpm test && pnpm lint`，
并在总结中粘贴每条命令的输出。
## 默认不在范围内
- 未收到要求时，不得编辑 `prisma/schema.prisma`。
- 未经确认，不得安装新依赖。
- 不得直接提交到 `main`。
这只是一份模板，并非“官方”模板，具体结构取决于你的仓库。每写一行，就少一件需要智能体猜测的事情。有关上下文文件与提示词本身的更多信息，请参阅工具使用术语条目。
斜杠命令：可复用的限定范围工作流
Claude Code 支持通过斜杠命令保存并重复运行限定范围的工作流。无需每次都输入“找出 src/lib 中未经测试的函数，为其添加测试，覆盖率达到 80% 后停止”，你可以只定义一次，以后按名称调用。
任何重复工作都适合使用斜杠命令，例如提交前检查清单、搭建新路由、团队代码审查提示词和生成变更日志条目。斜杠命令可以让智能体的活动范围保持狭窄、可预测——对于一个可以编辑代码的工具来说，这正是你想要的效果。它们与 CLAUDE.md 配合得很好：CLAUDE.md 告诉智能体项目如何运作，斜杠命令则在此之上封装具体工作流。如果不想从头编写每条命令，我们的姊妹网站 AgentsCamp 维护了一套经过格式验证、可以直接使用的斜杠命令、子智能体和 Skills 资源库，专门面向 Claude Code 构建。
Hooks：在工具执行事件中运行脚本
Hooks 是一项高级功能，允许你在特定的工具执行事件发生时运行脚本。普遍认可的事件类别包括 PreToolUse（工具运行前）、PostToolUse（工具运行后）和 Stop（会话结束时）。其理念与 Git Hook 相同：拦截一个已知事件，再执行自己的逻辑。
常见用途包括：Claude 编辑文件后自动格式化、每次写入后运行 Linter 或类型检查，以及阻止提交包含 .env 文件的改动。Hooks 在设置层配置，因此能够一致地应用到每次会话。具体事件名称和配置格式会不断演进，所以在生产环境中配置 Hooks 前，请查看 Anthropic 当前的 Claude Code 文档。核心原则稳定不变，具体细节则会变化。
MCP 服务器：扩展工具访问
Claude Code 可以与 MCP（模型上下文协议）服务器集成。MCP 是一种向 AI 智能体公开工具和上下文来源的开放标准。MCP 服务器可以让 Claude Code 访问数据库、内部 API、文档系统、工单跟踪器，或者任何你接入的其他系统。MCP 是一个连接插头，而不是某项具体功能：你运行服务器，让 Claude Code 指向它，其工具便会与内置工具一起变得可用。有哪些服务器可供使用，是一个快速变化的生态；应当把任何清单都视为某个时间点的快照，并查看 MCP 注册表或服务器自己的文档。
委派给子智能体
Claude Code 可以分派子智能体，也就是在隔离环境中执行范围明确的任务并返回结果。以下情况适合使用子智能体：
• 工作可以并行。 要从同一角度审查三个相互独立的文件？可以分派三个子智能体。
• 需要隔离上下文。 范围狭窄的任务说明不会用中间读取内容污染主会话。
• 角色分工有帮助。 一个负责规划，一个负责实现，第三个负责审查——这正是多智能体提示词指南介绍的模式。
子智能体会增加协调成本，因此简单任务不必使用。如果主会话原本要容纳大量相互无关的上下文，或者工作可以拆分成彼此独立的几条线，子智能体就物有所值。
可以直接复制的工作单式提示词
目标
为 `lib/api/client.ts` 中的 `request()` 添加重试循环，
避免临时故障直接传递给调用方。
范围
- 只编辑 `lib/api/client.ts` 和 `lib/api/client.test.ts`。
- 不得更改 `request()` 对外公开的签名。
- 不得触碰其他文件。
上下文
首先阅读：
- lib/api/client.ts （需要修改的函数）
- lib/api/client.test.ts （现有测试风格）
- lib/api/errors.ts （使用的错误类）
行为
- 只对网络错误和 5xx 响应进行重试。
- 最多尝试 3 次，采用指数退避：100ms、200ms、400ms。
- 不得重试 4xx；应立即将其返回给调用方。
验收
1. `pnpm test lib/api/client.test.ts`：所有测试通过。
2. 新测试覆盖：遇到 5xx 重试、遇到 4xx 不重试、最大尝试次数。
3. `pnpm typecheck`：没有错误。
4. `git diff --name-only`：只出现上述两个文件。
5. 满足以上所有条件后停止。
收尾步骤
输出差异，粘贴测试输出，列出所做假设，然后停止。
不得提交。
每个章节都会消除一项原本需要 Claude Code 猜测的歧义。有关同类工具，请参阅 Cursor AI 提示词指南和 Aider 提示词指南。有关 CLI 之外的团队工作流——共享工作区、持久参考文档——请参阅 SurePrompts + Claude Projects 指南。
常见反模式
• 没有 CLAUDE.md，每条提示词都要重新说明项目。 缺少上下文导致智能体偏离方向。**修复方法：**第一天就编写项目 CLAUDE.md，保持简短具体。
• 范围含糊。 “整理身份验证模块”没有明确边界。**修复方法：**指出允许编辑的确切文件，以及禁止触碰的文件。
• 没有停止条件。 任务结束后，智能体仍在继续“改进”。修复方法：“所有测试通过，且 lib/api/ 之外没有文件被修改时停止。”
• 不重新运行测试就相信输出。 “所有测试都通过”可能是错的，因为测试根本没有运行，或者针对过时的输出运行。**修复方法：**亲自重新运行测试，审查每一项差异。
• 工具访问不设边界。 在一次性仓库中也许没问题，在生产仓库中则很危险。**修复方法：**使用权限模型，把安全命令加入允许列表，危险命令要求确认，并禁止破坏性操作。
• 卡住后只会反复提示，而不诊断问题。 每次推动都会消耗 Token。**修复方法：**停止当前运行，检查最后三个动作，修复缺失环节，再缩小范围重新启动。
常见问题
为 Claude Code 编写提示词，与为 Claude.ai 聊天编写提示词有何不同？
Claude.ai 聊天是单轮交互，Claude Code 则是多步骤自主执行：它会规划、运行 Shell 命令、编辑文件，并围绕目标不断迭代。输入内容应该像一份规格，而不是一个问题：目标、范围、上下文文件、验收标准、停止条件。在聊天中有效的对话式提醒，不会为 Claude Code 提供明确的停止目标。
哪些内容应该放进 CLAUDE.md，哪些应该写进每条提示词？
稳定、可复用的信息应该放进 CLAUDE.md，包括技术栈、项目约定、命令和禁止触碰的目录。任务专属信息则写进提示词：今天要构建什么、可以修改哪些文件、达到什么状态才算完成。如果你发现自己在每条提示词中重复同一句话，它就应该放进 CLAUDE.md。
什么时候应该使用子智能体？
当工作确实可以并行、需要隔离上下文，或者角色分工有帮助时，可以使用子智能体，例如把规划、实现和审查拆成几次独立运行。对于小任务，额外开销不值得，应当留在主会话中完成。
应该允许 Claude Code 运行任何命令吗？
不应该。一个合理的默认方案是：允许读取、测试、类型检查、Lint，以及在功能分支上使用 Git；安装软件包、编辑范围外文件和任何推送操作都要求确认；禁止破坏性操作，包括强制推送到 main、删除分支、部署到生产环境，以及任何会突破沙箱的操作。
如何防止 Claude Code 编辑错误文件？
采用三层约束。首先，在 CLAUDE.md 中列出默认禁止触碰的目录；其次，在提示词中明确指出 Claude Code 可以编辑的具体文件；最后，在收尾步骤中要求它运行 git diff --name-only，只要范围外文件发生改动就停止。层层约束胜过任何单一限制。
Claude Code 工作单式提示词应包含哪些内容？
一份好的工作单式提示词包含六个章节，每个章节都会消除一项原本需要智能体猜测的歧义。目标（GOAL）说明唯一且具体的成果；范围（SCOPE）指出允许编辑的确切文件，禁止触碰其他文件，也可以禁止更改公开签名；上下文（CONTEXT）列出首先需要阅读的文件；行为（BEHAVIOR）规定改动必须遵循的精确规则；验收（ACCEPTANCE）给出可以验证的标准，包括哪条测试命令必须通过、新测试要覆盖什么、类型检查必须干净，以及 git diff --name-only 只能显示预期文件；收尾步骤（CLOSING STEP）要求智能体输出差异、粘贴测试结果、列出假设，然后停止且不得提交。这种结构把验证工作交给智能体本身：你不是要求它猜测功能是否正常，而是告诉它哪些命令能够证明功能正常。
