拆解 Claude Code 的 Agent 提示词：为什么发一句 hello 要花 2 元

一个让人意外的账单

很多人第一次打开 Claude Code，本能地输入一句 hello 想试试反应。

如果你开着计费面板，会看到一件有点违和的事——这一句 hello 扣了大约 2 块钱人民币。

一句五个字母的招呼，换成英文 token 也就是 1 个 token 的事。为什么账单是 2 元？

这不是 Claude Code 的 bug，也不是计费异常。想搞清楚钱花在哪，得先看看发送这句 hello 时，模型实际收到的输入有多大。

算账：2 元是怎么花掉的

先把 Opus 4.7 的官方价格（来自 LiteLLM 的 model_prices 配置）摆出来：

核心事实：首轮请求没有 prompt cache 可用，所有输入都要按 cache_creation 计费。而 cache creation 的单价还比普通 input 略贵（$6.25 vs $5），因为写缓存本身有额外开销。

再看首轮请求时，Claude Code 实际发给模型的东西有哪些：

取中位数 40K 算一下：

• 首轮 cost ≈ 40,000 × $6.25 / 1,000,000 = $0.25 ≈ ¥1.75
• 模型回复 "Hi!" ≈ 10 tokens 输出 × $25/M = 可忽略
• 合计 ≈ ¥1.8 左右

再把"系统还会顺手初始化一些 memory 读写、hook 触发"之类的隐性开销算进去，2 元就凑齐了。

如果把同样的 hello 再发一次呢？这次有缓存了：

• 40,000 × $0.50 / 1,000,000 = $0.02 ≈ ¥0.14

10 倍差价就在这里。所以 prompt caching 不是性能优化，是 Claude Code 能不能商业化运转的生存线——否则每条对话前面那一大坨 context 每次都全价重算，谁也付不起。

这笔账算清楚后，下一个问题就浮出来了：一个工具的提示词真的能占掉这么多 token 吗？

答案是：能，而且占得理直气壮。下面我们挑其中最能说明问题的那一个——Agent 工具——来拆。

从 Agent 工具提示词，数出 Claude Code 有几类 Agent

Agent 工具是 Claude Code 里"主 Agent 分派子 Agent"的入口。它的提示词开头第一段就列出了所有可用的 subagent 类型。直接读原文（摘自 Claude Code v2.1.116 的实际 API 请求）：

Available agent types and the tools they have access to:

- claude-code-guide: Use this agent when the user asks questions
  ("Can Claude...", "Does Claude...", "How do I...") about:
  (1) Claude Code (the CLI tool) - features, hooks, slash commands, MCP servers, settings...
  (2) Claude Agent SDK - building custom agents
  (3) Claude API - API usage, tool use, Anthropic SDK usage
  (Tools: Glob, Grep, Read, WebFetch, WebSearch)

- Explore: Fast agent specialized for exploring codebases. Use this
  when you need to quickly find files by patterns, search code for
  keywords, or answer questions about the codebase.
  (Tools: All tools except Agent, ExitPlanMode, Edit, Write, NotebookEdit)

- general-purpose: General-purpose agent for researching complex
  questions, searching for code, and executing multi-step tasks.
  When you are searching for a keyword or file and are not confident
  that you will find the right match in the first few tries...
  (Tools: *)

- Plan: Software architect agent for designing implementation plans.
  Use this when you need to plan the implementation strategy for a task.
  (Tools: All tools except Agent, ExitPlanMode, Edit, Write, NotebookEdit)

- statusline-setup: Use this agent to configure the user's Claude Code
  status line setting. (Tools: Read, Edit)

一句话总结：Claude Code 官方内置了 5 类 subagent。整理成一张表：

有几个结论可以直接从这张表读出来：

1. 权限是按需最小化的。statusline-setup 只给了 Read + Edit，就是要防止它跑题去动别的文件。
2. 只有 general-purpose 是"全能"的，也就是说它的心智成本最高——主 Agent 不到万不得已不该用它。
3. claude-code-guide 有 WebFetch/WebSearch，其他几个没有。因为它要去官网/GitHub 查文档。

触发条件是怎么设计的

再看原文一眼，每一类 Agent 的说明都严格遵循这个句式：

Use this agent when + <具体条件>

不是"这个 agent 很擅长 XXX"，而是"什么时候用我"。差别很大。

最典型的是 claude-code-guide。官方没有写"这个 agent 懂 Claude Code"，而是写：

Use this agent when the user asks questions ("Can Claude...", "Does Claude...", "How do I...") about...

触发条件直接锚定到用户输入的句式模式——主 Agent 一看到"Can Claude 支持 MCP 吗？"这种问法，就能确定性地路由过来。这比模糊的"用于 Claude 相关问题"有效得多。

对应的，Explore 的触发条件是动作动词：

Use this when you need to quickly find files by patterns, search code for keywords, or answer questions about the codebase.

Plan 则是任务形态：

Use this when you need to plan the implementation strategy for a task.

三种触发信号各不相同，但共通点是：足够具体，能让模型在多选项里做确定性选择。

这是从这段提示词能学到的第一条原则——触发条件要能让模型"一眼识别"，而不是"权衡后选择"。模糊的描述在多选项里等于随机路由。

子 Agent 内部的提示词长什么样？

这是最有意思也最容易被忽略的问题：主 Agent 调用 Agent(subagent_type="code-reviewer") 之后，被创建出来的那个子 Agent，收到的 system prompt 是什么？

Claude Code 里的 Agent 分两种：

第一种：官方内置 Agent（硬编码）

前面表里的 5 类都是这种。它们的 system prompt 写死在 Claude Code 的二进制/源码里，对外不暴露。想看的话，只能通过抓 Agent 调用时发出的 API 请求来观察（让 LiteLLM 打印 body ）。

第二种：用户自定义 Agent（磁盘文件）

更实用。Claude Code 允许用户在 ~/.claude/agents/*.md 或项目内 .claude/agents/*.md 定义自己的 subagent。格式是 Markdown + frontmatter：

---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code. MUST BE USED for all code changes.
tools: ["Read", "Grep", "Glob", "Bash"]
model: sonnet
---

You are a senior code reviewer ensuring high standards of code
quality and security.

## Review Process

When invoked:

1. **Gather context** — Run `git diff --staged` and `git diff` to see all changes.
2. **Understand scope** — Identify which files changed, what feature/fix they relate to, and how they connect.
...

这就把 Agent 机制的"黑盒"戳破了：

所以主 Agent 的 Agent 工具提示词里那段"Use this agent when..."——那不是官方拍脑袋写的介绍文案，那就是每个自定义 agent 自己 frontmatter 里 description 字段的拷贝。Claude Code 启动时扫 agents 目录，把所有 description 拼接进主 Agent 的系统提示词，就形成了那张路由表。

这个机制意味着：

• 你自己写 agent，description 的重要性等于"招牌"——它决定主 Agent 会不会来敲你的门。description 写得模糊，永远没人调用你；写得具体，甚至会被过度调用。
• 正文是真正的 system prompt——想让子 Agent 守纪律，所有 SOP、检查清单、禁止项都写在正文里。
• tools 字段是安全边界——不想让某个 agent 乱改代码，就不给它 Edit/Write。

想验证这一点，抓一次请求就能看到：主 Agent 调用 Agent 工具时，后台会发起一次新的 API 请求，system prompt 的开头正是你那个 agent 的正文内容。

七条能从这段提示词学到的写作原则

把 Agent 工具的提示词从头到尾看完，能提炼出这几个可操作的规则。

1. 工具网络要显式定路由

主 Agent 的 Agent 工具开头就把 5 类子 Agent + 每一类的使用场景列清楚。没有这段，模型会默认用 general-purpose 跑一切——就像所有东西都用 Bash 跑一样。多选项场景下，必须写"这个用 X，那个用 Y"，不能指望模型自己推断。

2. 用 when/then 代替能力描述

❌ 这个 agent 擅长代码库探索
✅ Use this when you need to quickly find files by patterns...

触发条件要锚定到具体的输入信号（句式、动词、任务形态）。

3. Example 要带 commentary

原文有两个 example，每个都带 <commentary> 标签解释"这个例子好在哪"：

<example>
user: "What's left on this branch before we can ship?"
assistant: <thinking>A survey question across git state, tests,
and config. I'll delegate it and ask for a short report...</thinking>
Agent({ ... })
<commentary>
The prompt is self-contained: it states the goal, lists what to
check, and caps the response length.
</commentary>
</example>

<commentary> 是写给模型看的 meta-prompt——明确告诉它"从这个例子里学什么"。比单纯的 input/output 对有效得多。

4. 反面提醒比正面说教更有效

原文有一段让人印象深刻：

Never delegate understanding. Don't write "based on your findings, fix the bug" or "based on the research, implement it." Those phrases push synthesis onto the agent instead of doing it yourself.

这是在修补主 Agent 的一个真实坏习惯——懒得自己思考，直接把"研究 + 实施"一股脑甩给子 Agent。与其写"请认真思考"，不如直接列出"不要说这些话"。

5. 参数说明里藏 prompt

Agent 工具的 prompt 参数描述里有这么一段（整整占了参数说明的大半）：

Brief the agent like a smart colleague who just walked into the room...
- Explain what you're trying to accomplish and why.
- Describe what you've already learned or ruled out.
- If you need a short response, say so ("report in under 200 words").
- Terse command-style prompts produce shallow, generic work.

这不是在说"这个字段填什么"，是在训练主 Agent 怎么填才算合格。每个参数说明都是一个微型 prompt 的机会，别浪费。

6. 并发与前后台语义要明说

- When you launch multiple agents for independent work, send them in
  a single message with multiple tool uses so they run concurrently
- Foreground vs background: Use foreground (default) when you need
  the agent's results before you can proceed

这种"什么时候并发、什么时候后台"的规则不写出来，模型会默认串行——浪费时间和 token。凡是有"更优解"的行为模式，都要写进提示词。

7. Worktree 隔离是单独一条规则

With isolation: "worktree", the worktree is automatically cleaned up
if the agent makes no changes; otherwise the path and branch are
returned in the result.

这条看起来像实现细节，其实在告诉主 Agent：无副作用的 agent 调用不留痕迹，有改动的会留 branch。这直接影响它是否该用 worktree 模式——决策依据被显式提供。

回到那个 2 元的问题

回头再看那句 hello。

花掉的 2 元里，绝大部分是工具提示词 + CLAUDE.md + 规则链。光 Agent 这一个工具，提示词就把以下东西塞进了上下文：

• 5 类子 Agent 的完整路由表
• 每一类的权限边界和工具白名单
• 怎么写好一个 subagent prompt 的 SOP
• 并发 / 前后台 / 隔离模式的决策规则
• 两个带 commentary 的完整 example

这 2 元买到的不是"一次对话"，而是一整套"Claude Code 应该怎么表现"的行为控制系统，每一轮对话都要完整带一份。

所以 prompt caching 是这套架构的生存线——没有缓存，这套系统在经济上根本跑不通。

而如果你在建自己的 Agent 产品，从这段提示词能直接抄走的方法论是：

Tool description 不是 API 文档，是给模型看的操作手册。

工具提示词的写作投入，应该和产品里最关键的业务逻辑一个量级。

一个写得糙的工具说明，换来的是模型的随机行为和用户的差评。一个写得狠的工具说明，花 2 元钱，就能把一整个 CLI Agent 的纪律性、路由能力、防御意识灌进模型。

Claude Code 选择了后者。