s-blog

从 Claude Code 的工具提示词里，我抽出了 7 条可复用的 prompt 设计规范

不是教你写 prompt，是看一个生产级 Agent 怎么给工具写说明书

ssssmy · 2026-06-11 · 7 min · LLM

接《深扒 Claude Code 源码》系列。上一篇盘了默认工具有哪些，这篇换个角度：不看工具做什么，看它给模型的说明书怎么写。通读约 19 个默认工具的 prompt.ts 后，能明显看出 Claude Code 写工具提示词有一套相当一致的范式。我把它抽成 7 条规范，每条配真实实例。

工具提示词（tool description / prompt）是 Agent 工程里最容易被低估的一环——它不是"给工具写句话介绍"，而是用自然语言给模型编程：你写得好，模型就少犯错、少绕路、少越界。下面是 Claude Code 的做法。

规范一：动态拼装，而不是静态字符串

直觉上工具说明应该是个常量。但 Claude Code 里几乎没有一个核心工具的 prompt 是写死的——它们都是按运行环境拼出来的函数。

  • Bash 的 prompt（BashTool/prompt.ts:275-369）是 getSimplePrompt() 把基础说明 + 沙箱段（getSimpleSandboxSection）+ git/PR 段（getCommitAndPRInstructions）拼起来的，约 370 行动态生成。
  • EnterPlanMode（EnterPlanModeTool/prompt.ts:166）直接按 USER_TYPE 派发两套完全不同的 prompt：外部用户版更鼓励用计划模式（列 7 类场景），内部 ant 版更克制（只列 3 类）。
  • Agent（AgentTool/prompt.ts:66）按 coordinator / fork / teammate 模式裁剪内容，fork 模式才追加「When to fork」整段。

为什么这么做：同一个工具在不同上下文里该说的话不一样。沙箱开了才讲沙箱规则、swarm 开了才讲队友协作、内部用户才引导用 /commit skill。把这些塞进一个静态字符串会让模型读到一堆当前用不上的指令——既浪费 token，又稀释真正重要的约束。代价是 prompt 变成了需要维护的代码。

规范二：「何时用 / 何时不用」+ 正反示例

最鲜明的特征。几乎每个有判断空间的工具都不只说"我能干什么"，而是花大量篇幅说什么时候别用我，并配 GOOD/BAD 示例。

  • TodoWrite（TodoWriteTool/prompt.ts:3，约 180 行）：一半篇幅是"何时用（3 步以上复杂任务……）/ 何时不用（单一琐碎任务直接做更好）"，再配暗黑模式、重命名函数、电商功能等正例，和 Hello World、git status 等反例。
  • Agent：明确写"要读具体文件路径用 Read、找 class Foo 用 Glob/grep、只在 2-3 个文件里搜用 Read——这些都比起 agent 更快"。
  • EnterPlanMode / ExitPlanMode 都带 GOOD/BAD 三连示例，区分"研究任务（不用）“和"实现任务（用）”。

为什么这么做：模型的默认倾向是"有锤子就想敲钉子"——给了 TodoWrite 就什么都想列清单，给了 Agent 就什么都想派子代理。用例子划边界比用定义划边界有效得多，因为模型是靠模式匹配工作的，一个反例胜过三句"请勿滥用"。

规范三：工具之间互相引导

工具不是孤立介绍的，它们的 prompt 里互相点名，形成一张"该用谁"的路由网。

  • Bash 明确列出"别用 Bash 跑 find/grep/cat/head/tail/sed/awk/echo"，并逐个指路：搜索→Glob、内容搜索→Grep、读→Read、改→Edit、写→Write。
  • Grep 反过来强调"绝不把 grep/rg 当 Bash 命令调用——本工具已针对权限与访问做优化"。
  • Glob/Grep 又把"开放式、需多轮的搜索"推给 Agent。
  • AskUserQuestion 和 ExitPlanMode 互相划清职责：前者说"别用我问’计划好了吗’，那是 ExitPlanMode 的事"，后者说"别用 AskUserQuestion 问’这计划行吗’，那是我的职责"。

为什么这么做：这是在 prompt 层面做控制流。一个能力（比如"搜索文件内容"）可能有多条实现路径（Bash 的 grep vs Grep 工具），但只有一条是受权限管控、可审查、可优化的。与其指望模型自己选对，不如在每个"错误路径"的工具说明里直接把它导向"正确路径"。

规范四：fail-closed 的硬前置约束

有些操作有顺序依赖，Claude Code 不靠"建议"，而是把它写成会真的报错的硬前置，并在 prompt 里提前告知。

  • Edit（FileEditTool/prompt.ts:12-28）：「编辑前必须在对话中至少 Read 过该文件，否则编辑会报错」。
  • Write（FileWriteTool/prompt.ts:10-18）：「若是已存在的文件，必须先 Read，否则本工具会失败」。
  • Read：file_path「必须是绝对路径，不能是相对路径」；PDF「超过 10 页必须用 pages 参数」。

注意措辞是「会失败 / will fail」而不是「建议先读」——prompt 在如实预告工具的硬约束。这和代码层的 fail-closed 是一致的（实现里 FileEditTool 真的会因为没 read-before-edit 而拒绝），prompt 只是把这堵墙提前告诉模型，省掉一次必然失败的往返。

规范五：强约束写成 BLOCKING / MANDATORY / CRITICAL

当某条规则绝对不能破时，Claude Code 会用全大写的强语气词单独标出来，而不是混在普通句子里。

  • Skill（SkillTool/prompt.ts:173）：「BLOCKING REQUIREMENT：当某 skill 匹配用户请求时，必须先调用 Skill 工具，再生成任何其他回应」。
  • WebSearch（WebSearchTool/prompt.ts:5）：「MANDATORY / CRITICAL：回答后必须在末尾加 Sources: 段，把所有 URL 以 markdown 超链接列出，绝不可跳过」。

为什么这么做：长 prompt 里所有句子语气一样，模型很难分辨哪条是"建议"、哪条是"铁律"。用 BLOCKING / MUST / NEVER 这类词做视觉与语义的强调，相当于给关键约束加粗。这是一种朴素但有效的注意力引导。

规范六：把安全协议直接嵌进工具说明

安全不是单独一份文档，而是写在最相关的那个工具的 prompt 里，就近约束。

  • Bash 的 git/PR 段内嵌了一整套「Git 安全协议」：不改 git config、不擅自破坏性命令、不擅自跳 hook、不擅自 force push 到 main、按名暂存文件避免误带敏感文件、提交信息用 HEREDOC。
  • WebFetch（WebFetchTool/prompt.ts:3）的 prompt() 在描述前固定加一段认证警告：对认证/私有 URL（Google Docs/Confluence/Jira/GitHub）会失败，应先找专门的 MCP 工具走认证访问。
  • Edit/Write 反复出现「非用户明确要求绝不加 emoji」「绝不主动创建 .md/README」。

为什么这么做：模型读一个工具的 prompt 时，注意力正集中在这个工具上——此刻告诉它"用 git 时别 force push"，比放在某份全局守则里有效得多。安全约束离触发点越近越管用。

规范七：元指令——教模型「怎么用」工具

最高级的一条。Agent 工具的 prompt 里有一整段「Writing the prompt」，教模型怎么给子代理写指令：

把 agent 当成一个刚进屋的聪明同事来 brief：讲清目标和已经排除的方向、给足上下文；查询类给确切命令、调查类给问题本身；严禁让 agent 代替你做理解（不要写 “based on your findings, fix the bug”）。

这已经不是"工具说明"，而是"如何使用工具的方法论"。类似地 Agent 还教你"agent 返回的结果用户看不见，你得自己再发一条摘要给用户"。

为什么这么做：有些工具（尤其是能再派生子任务的 Agent）的效果高度依赖调用者的输入质量。与其等模型踩坑，不如直接把"怎么用好我"写进说明书。

一个可复用的「工具 prompt 模板」

把这 7 条合起来，Claude Code 一个成熟工具的 prompt 大致长这样：

[一句话定义：这个工具做什么]
[硬前置约束：用我之前必须满足什么，否则 will fail]
[何时用：N 个具体场景 / 正例]
[何时不用：该用别的工具的场景 → 点名导向那个工具]
[关键参数说明 + 边界条件]
[BLOCKING/MANDATORY：绝对不能破的铁律，大写强调]
[安全协议：与本工具最相关的安全约束，就近写]
[（高级工具）元指令：怎么用好我]
—— 全部按 USER_TYPE / feature flag / 模式动态拼装

小结

Claude Code 的工具提示词给我最大的启发是：工具说明不是文档，是用自然语言写的控制流和约束系统。它用正反示例划行为边界、用工具互引做路由、用 fail-closed 预告硬约束、用大写词标铁律、把安全约束就近嵌入、还教模型怎么用好工具——每一条都是为了让一个不完全可控的模型，在工具这一层尽量少犯错、少越界。

如果你在给自己的 Agent / MCP server 写 tool description，这 7 条基本可以直接抄。

本文论据来自从 source map 还原的 Claude Code 源码树，各 file:line 可逐一核对；prompt 在不同版本/构建下可能有差异。

原文链接：https://www.ssssmy.com/blog/claude-code-tool-prompt-conventions