我跟他解释完他愣了半天，差点把不用的那份退掉。

这种混乱我这两年见了太多次，干脆整理一篇。

四个入口的真实定位

先把定位讲清楚，后面选型才不纠结。

Claude 桌面端（claude.ai 网页版 + macOS/Windows 原生 App）：面向终端用户的聊天产品。像 ChatGPT 那样聊天用的。有 Projects、Artifacts、记忆、MCP 支持。按月订阅 Claude Pro（20 美元）或 Max（100+ 美元）解锁额度和功能。

Claude Code：面向开发者的命令行 + IDE 集成工具，专门写代码用。跑在你本地电脑上，直接操作你的文件系统和 git。走 Claude Pro/Max 的订阅额度——关键：不需要单独再买一份订阅，同一个 Pro 账号在桌面端和 Claude Code 里共用额度。

API（console.anthropic.com 拿 key 之后直接调）：面向产品开发的裸模型接口。按 token 计费，跟上面两个的订阅完全是两套账。你做一个产品给别人用，必走 API。

第三方客户端（比如 Chatbox、Cherry Studio、NextChat 这类）：自带 UI，但底层调用的是 API key。相当于你有一瓶矿泉水（API），这些客户端给你提供了更漂亮的杯子。

关键要理解：订阅和 API 是两套账。Pro 订阅不能让你的 API 变便宜，API 充值也不能让你用桌面端。

决策表：你到底要哪个

把你的需求对号入座：

最常被搞混的两项我展开一下。

常见误区一：以为 Claude Code 要单独付钱

我见过至少 5 个朋友这么理解过。实际上 Claude Code 是内置在 Pro/Max 订阅里的。你开了 Pro（20 美元/月），在终端 claude 命令装一下，登录同一个账号，就能直接用，没有额外费用。

如果你是重度代码用户，Max 订阅（100+ 美元/月）的额度更大，适合一天几小时都在 Claude Code 里泡着的人。

如果你不是订阅用户，也可以用 API key 跑 Claude Code，按 token 计费。这种方式在长时间密集使用时比订阅贵，但零散用比较灵活。

具体能力差异和跟 Cursor/Cline 的对比，我写过一篇 Claude Code 横向对比。

常见误区二：以为 MCP 只能在 Claude Code 里用

MCP（Model Context Protocol）这个协议，很多人第一次听说是从 Claude Code 那边，就以为只有 Claude Code 才支持。

实际情况是：桌面端现在也完全支持 MCP。你在桌面端配置 MCP server（比如接你本地的 Obsidian、Notion、GitHub、数据库），Claude 桌面端就能调用这些工具。

我自己的设置是桌面端接了 6 个 MCP server，一个日常查文件、一个查日历、一个查本地数据库、两个跟我自己产品后台打通、一个外部搜索。相当于把桌面端的 Claude 升级成了一个真正的”了解我的工作环境”的助手。

想搞清楚 MCP 跟 function calling 的区别、什么时候选哪个，可以看这篇 MCP vs Function Calling 对比。想看 MCP server 实战案例，内部工具用 MCP server 的思路里有几个可以直接抄的模板。

我自己一天怎么切换这几个入口

给你看一个具体的一天：

早上 8:30-10:00：开桌面端 Claude。今天要写一篇文章，先让 Claude 帮我梳理大纲、找论据、列潜在反驳。我开着 Projects，把相关的参考资料都挂在 project 上下文里。这个阶段用桌面端是因为它的 Artifacts 能直接预览写作效果，MCP 能让我连接本地笔记库。

上午 10:00-12:00：切到 Claude Code。有个项目要改一个鉴权模块的 bug，我用 Claude Code 跑在 repo 里，直接让它读代码、写测试、跑验证。这种活桌面端做不了——它没法直接动我的文件系统和 git。

下午 14:00-17:00：开 API 脚本。今天要把 500 篇客户反馈做情绪分类，写一个 Python 脚本调 API 批量跑。这种规模用桌面端会累死，用 Claude Code 也浪费——API + batch mode 跑一下，等 2 小时就出结果，而且是半价。

晚上：偶尔用第三方客户端（比如 Chatbox），因为我同时在测 Claude、GPT、Gemini 三家回答同一个问题，客户端能并排显示对比，方便。

所以四个入口不是互斥选一个，是互补。每个入口解决一类问题。

几个具体场景的推荐组合

个人学习/写作：桌面端 Pro，一个订阅够用。

独立开发者做小产品：桌面端 Pro（聊天/测试用）+ API key（产品调用）。订阅是你的”工作台”，API 是你产品的”发动机”。

公司团队写代码：每人一个 Pro 订阅 + Claude Code。如果要做产品内嵌 AI 就再加 API。

数据处理/批量任务：只需 API，不必订阅。充值好额度，用 batch 接口，定时跑。

给家人/朋友送礼：他们大概率用桌面端就够了，Pro 订阅当生日礼物最实在。

最后一点省钱提醒

Pro 订阅一个月 20 美元，上限大概相当于 API 充值 40-60 美元的用量。如果你每个月 API 消耗接近或超过这个水平、且主要是交互式使用，订阅会更划算。如果你只是零散用、或者用量很不稳定，API 按需付费更好。

搞清楚怎么选之后，具体到每次请求该用哪档模型，建议看Haiku/Sonnet/Opus 选型那篇，成本还能再挤下来一半。

这篇是完全按照”一个新手第一次碰 Claude API”的真实顺序来的，我自己按表计了时——从注册到第一个请求跑出来，熟手 5 分钟，生手大概 15 分钟。

Step 1：到 console.anthropic.com 注册

这个地址要认准。不是 claude.ai（那是聊天产品），是 console.anthropic.com（开发者后台）。

国内用户一个现实问题：注册需要一个能接收短信验证码的手机号，国内号码是收不到的，需要一个海外号或者能收海外短信的虚拟号。这不是 Claude 的问题，是 Anthropic 现在的注册门槛。解决方案我就不在这里展开了，网上方案很多。

注册完之后登录，左侧菜单找 Billing，先把付款方式加上。没有付款方式的账号有免费额度但很少，几次测试就花完了。

Step 2：创建一个 API Key

Dashboard 左侧 API Keys → Create Key，给它起个名字比如 local-dev，点生成。

关键：这个 key 只会显示一次。复制下来立刻存好，页面关了就看不到了，只能重新生成。

存到哪？别存到代码里。我见过不止三个朋友把 key 直接 commit 到 GitHub 公开仓库的——有人 20 分钟内就收到 Anthropic 的告警邮件说 key 已经泄漏自动禁用了，运气好没扣钱；有人没这么走运，被人刷了 300 多刀。

Step 3：把 key 存到环境变量

Mac/Linux，在 ~/.zshrc 或 ~/.bashrc 加一行：

1

export ANTHROPIC_API_KEY="sk-ant-xxx..."

然后 source ~/.zshrc。

Windows PowerShell：

1

[System.Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY","sk-ant-xxx...","User")

重开一下 terminal。

验证：echo $ANTHROPIC_API_KEY（Windows 是 echo $env:ANTHROPIC_API_KEY），能打出 sk-ant- 开头的字符串就 OK。

Step 4：第一个 curl 请求

测通这个说明网络+key 都没问题：

1
2
3
4
5
6
7
8
9

curl https://api.anthropic.com/v1/messages \
  --header "x-api-key: $ANTHROPIC_API_KEY" \
  --header "anthropic-version: 2023-06-01" \
  --header "content-type: application/json" \
  --data '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 100,
    "messages": [{"role": "user", "content": "用一句话介绍你自己"}]
  }'

正常情况下你会看到一个 JSON 返回，里面 content[0].text 就是 Claude 的回答。

跑不通？往下看 Step 7 的排错清单。

Step 5：Python 版

我假设你装了 Python 3.10+。

1

pip install anthropic

写一个 hello.py：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

from anthropic import Anthropic

client = Anthropic()  # 会自动读 ANTHROPIC_API_KEY

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=200,
    messages=[
        {"role": "user", "content": "用三句话介绍一下 Anthropic"}
    ]
)

print(response.content[0].text)
print(f"\n---\n输入 tokens: {response.usage.input_tokens}")
print(f"输出 tokens: {response.usage.output_tokens}")

python hello.py，看到回答就成了。注意最后两行——这是我强烈建议你第一天就加上去的，永远打印 token 用量，后面我会讲为什么。

Step 6：Node.js 版

1

npm install @anthropic-ai/sdk

hello.mjs：

1
2
3
4
5
6
7
8
9
10
11
12

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

const response = await client.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 200,
  messages: [{ role: "user", content: "用三句话介绍一下 Anthropic" }],
});

console.log(response.content[0].text);
console.log(`input: ${response.usage.input_tokens} / output: ${response.usage.output_tokens}`);

node hello.mjs。

Step 7：报错了怎么办

按出现频率排：

401 Unauthorized：key 错了。检查环境变量是不是真的生效了，有没有多余的空格或引号。最常见是 Windows 下 SetEnvironmentVariable 之后没重开 terminal。

429 Too Many Requests：限流。免费账号和刚加付款方式的账号初始限额很低。查 Anthropic console 里的 Limits 页面，看你当前等级。等几分钟重试，或者充值提升等级。

400 Invalid Request：参数有问题。最常见是 model 名字写错（比如写成 claude-4.6-sonnet 这种倒过来的），或者 max_tokens 忘了填，或者 messages 里 role 不是 user/assistant。错误返回 JSON 里通常会告诉你具体哪个字段有问题，认真看一眼。

500 / 529：Anthropic 自己的问题或者过载。重试，或者上 status.anthropic.com 看看。

ConnectionError：网络问题。国内访问需要稳定的出口，不然会很痛苦。

那个我刚开始不知道的计费小坑

讲几个官方文档写了但你不读就发现不了的事：

输出比输入贵 5 倍。Sonnet 4.6 输入 3 美元/百万 tokens，输出 15 美元/百万 tokens。意思是你生成 1000 字的成本比你输入 1000 字高得多。所以如果你在做”让 Claude 大段生成”的任务，成本主要在输出端。我有个朋友第一周账单爆了，就是因为他让 Claude 一次性生成 30K tokens 的长文，一天 200 次。

缓存 tokens 单独计费，但便宜很多。同一段 prompt（比如系统提示词）重复用的时候，Anthropic 允许你缓存它，缓存命中的 token 只收 10% 的价钱。我在这篇 prompt caching 深度指南里写得很细，如果你的系统 prompt 长、且重复调用——比如 RAG、客服 bot、Agent workflow——一定要配置它，能省 60% 以上。

**max_tokens 不是”期望输出”是”最多输出”**。但你设 8000 和设 200 的成本差异只体现在实际生成了多少——没生成的不收费。所以设大点没事。但如果你不设限，模型可能真的给你写 8000，一次把你一天的预算吃光。

batch API 打 50% 折扣。如果你不需要实时响应、可以异步等几小时，用 batch API 价格直接砍半。批量跑总结、分类、翻译这种活非常适合。

跑通之后的下一步

第一个请求跑通之后我建议你做三件事：

一是把 print(response.usage) 这行代码作为永久习惯留着。成本意识是用 API 的第一课。

二是去试试 streaming 模式（client.messages.stream(...)），用户体验完全不一样。

三是搞清楚 Claude 的三档模型价格差异，按任务选型——三档选型这篇我详细写过。

上线一个月后我想着优化一下，加了 <thinking> 让模型”先分析问题意图再选择答案”。心想这肯定更稳吧，结果一跑——84%。

整整掉了 8 个点。我反复看了很多 case 才搞明白：这类任务本质上是”语义相似度召回”，模型在 embedding 层面其实已经做对了判断，你硬让它”逐步推理”，它反而会被自己推出来的中间结论带偏。

这事给我上了一课。CoT（Chain of Thought）不是越多越好，更不是万能。这篇说一下我现在怎么判断。

什么时候 CoT 是神器

先说有用的场景。我经验里 CoT 确实能显著提升效果的几类任务：

一、数学和数值推理。不管多简单，只要涉及”一步算错全盘错”的计算，让它一步步来就对了。实测一个三步应用题，直接问正确率 73%，加 <thinking> 后 94%。这个提升是稳的。

二、多跳问答。“根据 A 文档里的 X 和 B 文档里的 Y 推出 Z”这种。模型需要先把中间结论落到纸面，不然容易幻觉。

三、合规 / 规则判断。比如”判断这份合同是否违反下面 7 条规则”。你不让它一条一条过，它会漏。让它显式地说”规则 1: 符合；规则 2: 不符合，因为…”准确率直接上去。

四、复杂决策树。客服分流、工单分类有 20 多种类别且存在嵌套层级的时候，CoT 能让模型稳得多。

这些任务的共同点：有可拆分的中间步骤、有客观验证路径、犯错代价高。给它展开的空间，它会自己纠偏。

什么时候 CoT 反而添乱

这些是我踩过坑的：

一、纯召回 / 纯匹配任务。像我开头说的那个 FAQ 项目。模型其实一眼就知道答案，你让它”分析再选”是在给它添乱。

二、简单分类。三到五个类别、边界清楚的那种。加 CoT 会让模型过度理由化——“这条评论包含了正面情绪但也有一丝失望所以应该是…”结果越想越歪。直接判断快又稳。

三、创作 / 生成任务。让它写一个故事前先 <thinking> 梳理一下人物？没必要。创作是发散的，强行收窄到”先想后写”反而让输出变得程式化。

四、高吞吐短响应场景。API 客服实时应答，延迟要求 500ms 以内，你加一段思考就是 500+ tokens 的开销，用户体验直接崩。这时候宁可损失 2-3 个点的准确率也要快。

判断逻辑大致是：任务能不能”一眼看出对错”？能的话，CoT 大概率添乱。需要”想一下才能判断对错”的，CoT 才有意义。

<thinking> 标签的正确用法

决定要用 CoT 之后，怎么用也有讲究。我看过太多人把这个标签用歪了。

错误用法一：标签里塞”万能咒语”。

1
2
3
4

<thinking>
请仔细思考这个问题，考虑所有可能的情况，
确保你的回答准确无误。
</thinking>

这种写法 Claude 看了基本等于没看。空洞的”请认真思考”对输出没任何指导作用。

错误用法二：要求固定的思考步骤但步骤不匹配任务。

1
2
3
4
5

<thinking>
1. 分析用户意图
2. 检索相关信息
3. 组织回答
</thinking>

这种模板如果和真实任务路径对不上，反而在限制模型。比如任务是个简单数值题，它会被迫走”分析用户意图”这一步，浪费 token 还可能走偏。

我现在的写法：任务依赖型，而不是通用型。

合规判断场景：

1
2
3
4
5

<thinking>
先把合同里所有可能涉及规则的条款列出来，
对每一条规则判断：符合 / 不符合 / 不适用。
所有规则过完再给最终结论。
</thinking>

数学题场景：

1
2
3
4

<thinking>
逐步列出计算过程，每一步明确说明依据的条件和得到的中间值。
算完后回头验算一遍。
</thinking>

具体、可执行、紧贴任务。不是给模型”打气”，是给它”操作手册”。

那个”让它思考反而更错”的 case

再讲个我印象深的反例。某金融客户要做”判断一条新闻是利好还是利空”。

0-shot 准确率 81%，我觉得还能更高，加了一段：

1
2
3
4

<thinking>
先分析这条新闻涉及的主体是谁、事件性质是什么、
短期影响和长期影响分别如何、最后综合判断利好利空。
</thinking>

测下来 76%。反复看了 case 之后我发现问题：金融新闻的”利好利空”很多时候是情感驱动的市场反应，不是严密因果推理的结果。

你让模型去分析”长期影响”，它经常会推出一个”虽然短期看是利空但长期利好”的结论，结果跟市场真实反应完全相反。真实市场就是看短期情绪，不看你的长期理性推理。

后来我把 thinking 拿掉，改成一条简短的 hint：”从市场短期情绪反应的角度判断”，准确率回到 81% 并稳定在那。

这个教训是：CoT 的前提是任务本身有”可推理”的结构。没有这个前提，你强行推理就是在制造噪声。

Extended Thinking 模式怎么看

Claude 后来出的 extended thinking 模式（就是那个可以看到完整思考链、token 消耗翻倍的那个）我也用过不少。

值得开的场景：

• 复杂代码生成（写一个有设计模式考虑的完整模块）
• 多文档综合分析
• 需要调试的 bug 排查
• 棋类 / 规则类博弈决策

不值得开的场景：

• 所有短平快任务
• 写营销文案、客服回复
• 文档抽取（大部分情况）
• 简单的代码 review

成本上，extended thinking 的 token 消耗能达到常规的 2-5 倍。我自己项目里的原则是：能用 Sonnet 常规模式解决的事，不开 thinking；必须开的时候，先用 Opus 试，效果 OK 再考虑降级。Claude 家族那篇里有更细的模型选型讨论。

还有个细节：extended thinking 模式下，prompt caching 的表现和常规模式有些差异，具体的我在缓存深度指南里提过。

我的决策树

简化一下我现在的判断流程：

1. 先 0-shot 跑 baseline，记录准确率和延迟
2. 分析错误 case：错的地方是”不会”还是”没想到”？
   • “不会”（知识 / 能力不够）→ 换更强的模型，或者加 few-shot，CoT 救不了
   • “没想到”（漏掉一步推理）→ 上 CoT 可能有效
3. 如果任务天然是”一眼看对错”的类型 → 跳过 CoT
4. 如果任务需要多步推理且每步可验证 → 上 CoT，写任务依赖型 thinking
5. CoT 之后再评估一次准确率和延迟，权衡是否值得

顺便说一句，CoT 和 few-shot 不是互斥的。有时候我会写 3 条带 thinking 过程的示例，让模型学会”怎么思考”。这种组合在复杂推理上特别猛。few-shot 的数量和顺序我在另一篇里细讲了。

最后

CoT 这个东西，两年前大家吹它是灵丹妙药，现在业内已经慢慢意识到它是一把双刃。用对了提升显著，用错了不但浪费 token 还损失精度。

核心就一句话：不是所有问题都需要”想一下”才能答。你问一个人”1+1 等于几”，他想 30 秒再回答你，你反而怀疑他是不是有啥毛病。模型也一样。

下面这 10 个场景是我带过十几个非技术朋友之后总结的，按他们实际使用的先后顺序排，不是按官方文档的功能分类。

1. 总结一篇读不下去的长文章

这是 90% 的人第一次用 Claude 干的活。丢一个链接或者粘贴一大段文字进去，让它告诉你在说什么。

可直接用的 prompt：帮我用 5 条以内总结重点，最后加一句作者立场

加那句”最后加一句作者立场”很关键，不然你拿到的就是流水账。Claude 对作者立场的判断比单纯总结好用得多。

2. 重写一封不好意思发的邮件

被客户怼了想回一封不失礼的，或者要跟老板请假又不想显得太随便的，都丢给它。

prompt：我想表达 XX 意思，但不要显得太弱/太硬，帮我写一版

头两周我没搞懂的坑：**不要直接让它”帮我写一封邮件”**。你得先把你想表达的核心诉求说清楚，Claude 再往上加语气层。你越具体它越好用。

3. 帮你 review 一段你写的代码

你不用是程序员也能用这个。写个 Excel 公式、一段 Shell 脚本、一段 SQL 查询都行。

prompt：这段代码是要做 XX 的，帮我看看有没有 bug 或者能简化的地方

关键是”是要做 XX 的”——光贴代码不说意图，Claude 只能猜，准确率会掉一半。

4. 给你已有的代码写测试

这个是 Claude 做得比我好很多倍的事。我会把一个函数贴过去，让它帮我列 edge case。

prompt：帮我为这个函数列出 10 个 edge case，按出现概率排序

去年我有个做支付的客户，让 Claude 帮他审一个结算函数，它列出来的 12 个 case 里有 3 个他们上线 8 个月都没考虑到——包括一个跨时区结算日期的 off-by-one bug。

5. 让它帮你啃一份长 PDF

这是 Claude 最强的主场之一。一份 80 页的投资协议、一本教材、一份财报，都能丢进去让它定向问答。

prompt：这份 PDF 里关于 XX 的部分在第几页，请把原文贴给我并翻译

让它贴原文是个很重要的小技巧。我头两周不知道这个，Claude 给我总结，我信了，结果一查原文根本不是那样。要它贴原文之后，幻觉率降了一大截。

6. CSV 数据快速分析

把一个 CSV 丢进去（桌面端支持，API 需要配合 code execution），让它告诉你”这份数据里最异常的是什么”。

prompt：这份数据有 XX 行，帮我找出前 5 个异常值并解释为什么异常

这里有个我一直在重复的提示：**不要问”你发现了什么”，要问”按 XX 标准找 5 个”**。开放式提问 Claude 给你的答案通常很平。

7. 读图表、读截图、读手写笔记

上传一张截图，让它帮你读。这个能力在我刚开始用的时候根本想不到会这么好用。我上个月用它读完一本我爷爷留下的中医笔记——手写繁体，识别率 90% 以上。

prompt：帮我识别这张图里的所有文字，如果有表格保留结构

8. 翻译不是翻译而是本地化

别用 Claude 做机械翻译，那样它还不如 Google。正确的用法是让它做”本地化”——带语气、带语境、带文化适配的转写。

prompt：把下面这段英文翻译成面向中国二线城市中年用户的中文，语气要像本地人写的

你会发现出来的东西跟直接翻译完全不是一个东西。我去年做一个出海反向落地项目，这种”反本地化”写法帮团队省了至少 40% 的本地内容生产成本。

9. 串起来做 Agent 工作流

到这一步你已经不是在”用 Claude”了，是在”让 Claude 帮你干活”。简单的 Agent 就是让它读邮件→判断优先级→起草回复→等你确认。

这块有门槛，涉及到 MCP、tool use 这些概念。入门可以先看我写的 MCP 跟 Function Calling 的对比，把底层机制摸清楚。真要落地的话，内部工具用 MCP server 的思路这篇给了我一个很具体的模板。

10. 搭自己的私人知识库

最终形态。你把自己的所有笔记、邮件、文档、书签都接到 Claude 里，让它成为”比你自己还了解你的那个助手”。

这条路要走深一点，涉及到 claude.md 项目配置 还有自定义 Skill。我自己也还在调，远没到完美——但是每隔两周我会发现新的玩法。

头两周我没搞懂的几件事

“上下文”不是越长越好。我早期什么都往 prompt 里塞，结果 Claude 开始走神。把不相关的删掉，回答质量立刻上来。这是我从 prompt 时代走到 context engineering 时代之后最大的认知更新。

“让 Claude 反问你”这个技巧。我头两周不知道这招，直到有一天 Claude 自己问我：”你确定要按 A 方案还是 B 方案？我默认 A 了。”那之后我写复杂 prompt 都会加一句”如果有关键信息缺失，请先问我再动手”。

桌面端和 API 不是同一个东西。桌面端有 Projects、有记忆、有 artifacts，API 是裸模型。新手建议先在桌面端玩明白了再碰 API。

最后一个小建议

别把 Claude 当 Google 用。Google 帮你找答案，Claude 帮你想问题。两种工具的使用节奏完全不一样——Claude 最擅长的是”你有一个模糊的想法，让它帮你把边缘磨清楚”。

我加了 3 条示例进去，升到 81%。再加到 5 条，到 89%。客户说够了够了，上线。

后来我自己出于好奇，又加到 10 条示例，心想应该能冲到 92%？结果掉回了 85%。

当时我特别费解。加示例不是应该让模型学得更好吗？为什么到一定程度后会倒退？

这个问题我花了大半年才摸清楚。这篇就说说我现在怎么定 few-shot 的数量。

先讲那个倒退曲线

这事其实有道理的。Few-shot 的本质是”上下文学习”（in-context learning），模型在推理时动态地从你给的例子里提炼模式。但提炼是有极限的——示例太多，会发生两件事：

第一，示例之间的细微不一致被放大。你自己写 10 条示例，总有几条风格或边界判断不完全一样。模型会把这些”不一致”也当成信号，结果反而变得犹豫。

第二，上下文长度增加，对任务本身的注意力被稀释。尤其在长文档场景下更明显。

所以 few-shot 不是”越多越好”。是有个甜蜜点，过了就掉头。

我现在用的 3/5/7 法则

这个法则不是啥标准答案，是我在实际项目里反复校准出来的经验值。不同任务类型，甜蜜点位置不一样：

3 条：分类任务 + 风格迁移

情感分类、意图识别、打标签、改写成某种特定文风——这类任务的特点是”模式相对简单，但边界需要锚定”。

3 条示例基本够了。一条典型正例、一条典型负例、一条边界模糊的。这样模型就明白了你的判定规则在哪。

再多加也没啥用。你加第四条、第五条多半是在重复前三条的模式，对模型来说是冗余信号。

5 条：结构化抽取

从长文本里抽字段、从邮件里提关键信息、从合同里找条款——这类任务需要模型学会”看哪里”和”怎么填”。

5 条示例里我通常这样配：2 条标准样例、2 条包含噪声或歧义的、1 条字段缺失或需要”填 null”的。覆盖主流情况 + 典型异常，再多就多余了。

7 条：复杂推理 / 多步决策

比如多跳问答、合规判断（需要组合多条规则）、代码评审这种需要”先看整体再判断细节”的任务。

7 条示例里，我会确保每条示例的”推理路径”都不一样——不是换输入，是换思考路径。让模型看到”哦原来这类问题可以这么想、也可以那么想”。

超过 7 条我基本就不加了。要么升级到带 <thinking> 的链式推理（这个在思考还是直接给答案那篇里细说），要么考虑微调或者上更强的模型。

示例顺序的讲究

这是个容易被忽略的点。同样 5 条示例，顺序不同效果能差 3-5 个百分点。

我摸出来的规律：最相关、最典型的那条放最后。Claude 的注意力对”刚刚看到的内容”是有偏向的（这事叫 recency bias），放最后的示例在生成时的权重明显更高。

所以我现在的排法大致是：

1. 先放几条”覆盖各种情况”的杂样例
2. 中间放”边界案例”
3. 最后放一条和当前待处理输入最相似的

有时候如果我能动态检索，还会做个”相似度召回”，用检索到的最相似 case 作为最后一条示例。这套手法在 RAG 项目里特别好使。

示例写太好，反而拉低平均

这点我踩过大坑。

有次给一个客服改写项目写示例，我特别认真地把每条都润色得又专业又亲切。结果上线一测，发现模型在处理比较随意的用户投诉时，输出也变得很客套很书面——用户反馈说”像在跟机器人讲话”。

把示例里两条换成稍微”粗糙”一点的真实样本，口吻立刻松下来了，用户满意度反而上去了。

所以：示例的质量是”代表性”，不是”完美”。你的真实输入有多杂，示例就该有多杂。不要把示例全写成你梦里希望的那种理想形态，模型会照着做，然后在处理现实世界输入时别扭得要命。

输入输出对齐的格式

Few-shot 的格式写法我建议用 XML 标签成对包装，比 “Q:… A:…” 这种冒号式更稳定。为啥 Claude 特别吃 XML，这篇专门讲过。

典型写法：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

<example>
  <input>用户评论：这破玩意儿用了三天就坏了</input>
  <output>负面</output>
</example>

<example>
  <input>用户评论：还行吧，没啥特别感觉</input>
  <output>中性</output>
</example>

<example>
  <input>用户评论：冲着品牌买的，用起来确实比便宜货强</input>
  <output>正面</output>
</example>

<task>
请判断下面这条评论的情感：
{用户输入}
</task>

格式统一、标签闭合、最后一条是最典型的。

0-shot vs Few-shot 怎么选

不是所有任务都需要 few-shot。我的判断标准：

能 0-shot 就 0-shot。Claude 的 zero-shot 能力本身就很强，简单任务加示例是浪费 token、拖慢响应。

什么时候需要 few-shot？

• 任务有”主观判断”的成分（比如风格分类）
• 期望输出有特定格式且不容易用自然语言描述清楚
• 边界情况多，光靠规则说不清楚
• 你试了 0-shot 结果准确率差 5 个百分点以上

先 0-shot 测一轮，拿到 baseline，再决定要不要加示例。有些人上来就怼 10 条例子，既浪费 token 也错过了真实性能评估。

我开头那个 68%→89% 到底怎么拆的

回到那个情感分类项目。我当时加示例的具体步骤，给大家看下：

• 第 1 条：一个明显负面但用词委婉的（让模型学会看”言外之意”）
• 第 2 条：一个表面夸实则讽刺的（中文里特别多这种）
• 第 3 条：一个情感混合的，判定为中性（教它怎么处理混合情感）
• 第 4 条：一个带脏话的负面（锚定”脏话≠一定是差评”的边界）
• 第 5 条：和当前测试集分布最接近的一条标准负面

每加一条都带来 2-5 个点的提升。到第 5 条时覆盖了主要 edge case，再往上加就开始触发前面说的”不一致被放大”现象。

一些零碎经验

• 示例里的输入尽量匿名化。别写真实用户名、真实公司名，容易让模型”记住”导致偏差。
• 输出格式在示例和最终任务里必须一致。你示例里是一个词，任务要求一段话，模型会精分。
• 示例本身也会走 prompt caching。如果你的示例长期固定，可以让它进缓存，省下不少钱。缓存机制我在这篇里拆过。
• 不同模型的甜蜜点不同。Haiku 对示例更敏感、可能 7 条都嫌少；Opus 自身推理强、3 条可能就够。Claude 家族那篇里有模型选型的讨论。

最后

Few-shot 这事说玄乎也玄乎——同样的示例换个顺序都能差好几个点。说朴素也朴素——你给模型看的就是它学到的，你示例写得糙，模型就糙。

3/5/7 不是铁律，是个起点。拿这个数字去试，根据你自己的评估集往上调或往下调 1-2 条。这个过程才是 prompt 工程的本体，不是套公式。

改天心血来潮，把同一个 prompt 的分区从 ## 文档内容 改成 <document>...</document>、## 抽取要求 改成 <instructions>...</instructions>，其它一个字没动。再跑一遍，准确率 91%。

17 个百分点。我当时就懵了，以为是哪里串了变量。反复对了三次，确实就是标签的差别。

从那以后我就开始系统地玩这套东西，到现在差不多大半年。这篇写一下我摸出来的规律。

这事的历史根源

先说个不那么技术的背景。Claude 的训练数据里，XML 出现的频率和使用方式跟 GPT 那边不太一样。Anthropic 官方在多份文档里直接推荐用 XML 标签组织 prompt——这不是一个说说而已的”最佳实践”，而是他们从训练阶段就在铺这条路。

具体表现是：Claude 对成对出现的 <tag>...</tag> 有非常强的”边界感知”。它会把标签内的内容视为一个语义独立的单元，而不是和周围文字融成一片。

反观 markdown 标题，## 某某某 只是一个软分界——视觉上清楚，但模型在注意力机制里并没有对它做特别处理。于是你的”文档内容”和”抽取要求”在它眼里可能是一碗汤里的两块肉，有时候分得清有时候分不清。

这个差别在任务复杂度低的时候不明显。越是长上下文、多段文本、多任务混排的场景，XML 的优势越明显。我那个 14 字段抽取就是典型长文档 + 多目标。

我实测过的几组对比

除了开头那个医疗文档，我后来又做了几组对照实验，数据大致是这样：

• 短对话（单轮、上下文 <500 字）：markdown 和 XML 几乎没差，都在 95%+，在误差范围内。
• 中等文档抽取（2k-5k 字 + 3-5 个字段）：XML 普遍高 5-10 个点。
• 长文档 + 多段指令（10k+ 字 + 多任务混排）：XML 优势 15-20 个点，甚至有任务从不可用变成可用。
• RAG 场景（多段检索结果 + 用户问题）：XML 把”检索内容”和”用户问题”隔开的效果明显，减少了幻觉引用。

所以不是什么情况都非得用 XML。短任务你爱用啥用啥。我现在的习惯是：只要 prompt 里有两段以上语义不同的内容块，就上 XML。一段的就 plain text 算了，别瞎包。

关于这个话题 XML 和 Markdown 的深度对比那篇有更细的版本对照，我不展开重复。

标签怎么起名是个学问

刚开始玩的时候我也犯过错。为了好看，标签名起得很文艺，<gorgeous_article>、<user_question_that_requires_thoughtful_answer>——这种不但没加分还减分。

摸到的规律是：标签名要语义化、短、尽量用通用词。

通用词是指 <document>、<context>、<instructions>、<example>、<input>、<output>、<question>、<answer>、<thinking> 这类。Claude 的训练数据里见得多，它一看到就知道”哦这是文档内容”。

自创词也不是不能用，但得让标签名本身传达清楚角色。<medical_report> 可以，<the_big_text_blob> 就很差。

还有一点，标签名本身就是一种提示。我做法律项目时试过把 <text> 改成 <contract>，没改其它任何东西，合同里的风险识别率微微上升了一点。模型会根据标签名调整对内部内容的”期待”。

嵌套别上头

见过有人把 XML 嵌套玩出六层的。<task><context><documents><document><metadata><author>... 这种。

这么写 Claude 不会报错，但会累。我实测过嵌套超过三层之后，模型对内层标签的”尊重程度”开始下降。三层以内是甜蜜区。

我现在的原则：扁平优先，能不嵌套就不嵌套。需要层级的时候也不超过三层。

比较健康的一种结构：

1
2
3
4
5
6
7
8
9
10
11
12

<context>
  <document id="1">...</document>
  <document id="2">...</document>
</context>

<instructions>
...
</instructions>

<output_format>
...
</output_format>

三层封顶，每层职责清楚。需要更细的分组，用属性（像上面那个 id="1"）比继续嵌套好。

闭合标签不要偷懒

我见过一些人写到后面懒了，只写 <document> 开标签不写闭合。这个我测过，不严重但确实会有损耗——大概降 2-3 个百分点，尤其是在多段内容的场景。

Claude 对成对标签的处理是优化过的。你不闭合，它会自己猜边界，猜得多数时候对，有时候不对。不对的那几次就是你损失的精度。

同理，<tag/> 这种自闭合标签在纯 prompt 场景里我建议少用，没啥必要，还可能引起歧义。

什么时候 XML 反而拖累

XML 不是万能药。有些场景它反而碍事：

一、纯创作任务。你让它写一首诗、编一个故事，前面包一堆 <poem_topic>、<style_preference>、<length> 标签，会让模型进入”分析模式”，输出反而板正。这种场景 plain text 自然语言就够了。

二、极短 prompt。system 里就一句”你是个客服助手”，包个 <role>你是个客服助手</role> 没意义，反而显得刻意。

三、需要模型自由展开的头脑风暴。标签会隐性收紧模型的发散范围。要创意的时候给它松绑。

Tool use 的响应里也有 XML 痕迹

顺便提一下。你用 Claude 的 tool use（function calling）时会发现，模型在推理阶段倾向用类 XML 的结构组织它的”思路”，最后才调用工具。这不是巧合——它的 thinking 模式就是在 <thinking>...</thinking> 标签里展开的。

这也反过来印证了 Claude 训练时 XML 的权重。你要让它”想一下再答”，用 <thinking> 标签比用”让我们一步步来”这种自然语言触发词要稳得多。相关细节我在思考还是直接给答案那篇里有说。

说到 tool use，它和 MCP 的区别和选型在这篇里有讲，感兴趣可以顺手看看。

我现在的默认模板

给一个我个人在中等复杂度任务上的骨架：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

<context>
[背景资料、检索结果、文档内容]
</context>

<task>
[这次要干的事，一两句话说清]
</task>

<constraints>
- [约束 1]
- [约束 2]
</constraints>

<output_format>
[期望的输出结构]
</output_format>

四个块、全闭合、不嵌套。90% 的项目这个骨架够用了。

最后说一句心里话。XML 这东西在 prompt 工程里被神化过也被踩过，我摸了大半年，结论还是那句：它不是魔法，是一个让你的意图传达得更准的工具。你意图本身就乱，再包多少标签都救不回来。但你想法清楚的时候，XML 能帮你把想法”原封不动”地送到模型面前，而不是在路上被稀释掉。

user 那边呢？就一句：”请帮我分析这份合同的风险点。”然后把合同全文贴上去。

我看完大概沉默了十秒。这不是一个 prompt，这是一份岗位说明书。

我先讲一下 system 和 user 的职责边界

这事其实 Anthropic 在官方文档里讲得挺清楚，但被大部分中文教程带偏了。中文圈子里流行的说法是”system 放人设，user 放问题”，听起来没毛病，但太笼统。

我现在理解的边界是这样：

system 管的是”约束”——不管这次来什么请求，这些规则都成立。比如你是什么角色、不能做什么、输出什么格式、用哪种语气、失败时怎么兜底。这些东西一旦写进 system，Claude 会把它当成整个会话的”重力场”。

user 管的是”指令”——这一次我具体要你干什么。输入数据、本次任务目标、这次特殊的限制。

所以”请确保你的回答准确无误”这种话放 system 是浪费 token。它对所有任务都成立，说了等于没说。Claude 又不会因为你没说就故意瞎编。

那个客户一开始不服气，说你看 OpenAI 官方示例里也会写”你要准确”。我说那是他们 GPT 的风格，Claude 对这种”空话”敏感度很高，你写多了它反而会把实际约束稀释掉。

我拆的三层模型

在他项目上我重写了一版，就砍到 320 字，结构长这样：

第一层是身份（Identity）。两三句说清你是谁、服务谁、核心任务。不要形容词堆叠。”你是一名为中国中小企业服务的合同审阅助手，用户通常是没有法务团队的创业者”——这一句比”专业严谨富有同理心”信息量大十倍。因为它锚定了读者画像。

第二层是规则（Rules）。必须做什么、绝对不能做什么、边界在哪。我一般用无序列表直接列出来，每条不超过 15 字。比如：

• 不提供具体诉讼策略
• 不引用未经查证的法条编号
• 发现高风险条款必须用 <alert> 标签标出
• 无法判断时直接说”建议咨询律师”，不要硬答

这层最怕的是写得像宪法——“应当秉持公正原则”这种话 Claude 看了会礼貌性点头然后该怎么错还怎么错。要具体、要可执行、要像红线。

第三层是示例（Examples）。1-2 个微型 in/out 对，展示典型场景的风格和格式。如果你的任务有固定输出结构，这一层几乎是救命的。不过示例别写太长，system 里的示例主要是”锚定风格”，不是”穷举用例”。穷举用例的活儿交给 user 里的 few-shot 做更合适，这个我在另一篇讲 few-shot 设计的文章里会细说。

客户那版为什么会失败

回头看他原来那 850 字，问题不是”写得不好”，是”层次混乱”。身份、规则、示例、自我吹捧全糊在一块儿。

Claude 这种大模型处理长 system 的时候，有个我观察到的规律：越靠前的内容权重越高，越具体的内容越容易被执行，越形容词化的内容越容易被忽略。

他原 prompt 开头那三行全是形容词，Claude 大致相当于收到一个”请你表现得很牛逼”的模糊信号。到第 400 字左右才出现”不要编造法条”这种硬约束——但这时候注意力已经被稀释了。

我重写后把身份压到两句、规则上提到前置位、形容词几乎全删。实测在同一批 200 个合同分析 case 上，合格率从 71% 涨到 88%。”合格”的标准是他们自己的 QA 团队打分，不是我定的。

Claude 到底多”听”system

这事我顺手测过。同一条硬约束，放 system 里和放 user 里，执行率差多少？

我拿一个简单规则：”输出必须是 JSON，不要任何解释文字”，跑了 100 次相同的抽取任务。

• 只写在 user 里：73 次合规
• 只写在 system 里：91 次合规
• 两边都写：96 次合规

差距挺明显的。Claude 对 system 的”服从度”确实更高，这也是为什么我倾向把格式约束、输出结构这类”每次都一样”的东西往 system 放。想稳住 JSON 输出还有一套组合拳，我在让 Claude 稳定吐 JSON 的 5 个套路里专门写了。

顺便提一句，如果你在用 CLAUDE.md 做项目级配置，那个文件本质上就是个持久化的 system 增强，相关的写法我在Claude Code 项目配置那篇里有更细的讨论。

一些容易踩的坑

坑一：把可能变化的东西写进 system。比如”今天是 2026 年 4 月 20 日”——明天就过期了。这种应该放 user 或者动态注入。

坑二：system 里塞大段背景资料。知识性内容该放 user 或者用 RAG。system 主要承载规则，不是知识库。放多了既浪费缓存命中率，又让模型分心。prompt caching 的机制我在另一篇深入讲过。

坑三：用 markdown 标题装饰 system。# 身份 ## 规则 这种写法不是不行，但 Claude 对 XML 标签更敏感，用 <identity> <rules> <examples> 这种语义标签效果更稳。为什么 Claude 特别吃 XML，这篇专门讨论过。

坑四：规则互相矛盾没察觉。比如一边说”回答要简洁”一边说”要引用具体法条并解释”。Claude 遇到矛盾约束时倾向挑软的执行，结果就是两头不讨好。写完规则自己过一遍，看有没有打架的。

我现在的 system 模板

给一个脱敏后的骨架，你可以照着改：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

<identity>
你是 [服务对象] 的 [核心角色]，主要帮他们 [核心任务]。
</identity>

<rules>
- [硬红线 1，越具体越好]
- [硬红线 2]
- [输出格式约束]
- [失败/不确定时的兜底行为]
</rules>

<style>
- 语气：[具体到"像资深同事一样"这种]
- 长度：[默认段落数或字数区间]
- 禁用：[明确不要的措辞]
</style>

<example>
输入：...
输出：...
</example>

基本上 200-400 字解决战斗。想加东西先问自己：”这条规则是不是每次都成立？”不是就挪去 user。

写 prompt 这事最怕的就是”越写越长、越长越虚”。砍到只剩骨头，反而是最快出效果的办法。

后来 ChatGPT 火了，我被推着去试了 GPT-3.5，然后有朋友从内测通道甩给我一个叫 Claude 的东西，让我试试。我记得那天晚上我把同一段写得很烂的需求文档分别喂给两个模型，让它们帮我重写。GPT 给我的东西结构很漂亮但逻辑是飘的，Claude 给我的第一版不好看，但它会主动指出”你第 3 条和第 5 条是矛盾的，我暂时按第 3 条来写了，你确认一下”。

就那一句话，我记到今天。

那群人为什么非要从 OpenAI 出来

Anthropic 的核心创始团队，基本上是 OpenAI 当年负责 GPT-2、GPT-3 研究和安全的那批人。Dario 之前是 OpenAI 的研究 VP，Daniela 管运营，Tom Brown 是 GPT-3 论文一作，Jared Kaplan 是 scaling law 那篇论文的作者之一。

他们出来的表面原因是”对公司方向有分歧”，但你跟在那个圈子里的人聊过就知道，真实原因没那么玄乎：他们觉得 OpenAI 在安全问题上往后退了，产品化压力越来越大，而他们想做的事——搞清楚”一个能力越来越强的模型，怎么才能持续可控”——在原来那个组织里推不动了。

所以 Anthropic 一开始不是一家产品公司，是一家研究公司。2021 年成立，头两年几乎没对外发布任何可用的东西，只发论文。这跟 OpenAI 一上来就憋大招搞 GPT-3 API 完全是两种打法。

顺便说一句，我去年跟一个在 Anthropic SF 办公室的朋友吃饭，他说他们内部开会还是把”Safety”放在产品节奏前面的，这跟外界的印象差不多能对上。

Constitutional AI 到底是什么，用白话讲

要理解 Claude 跟 GPT 的区别，绕不开 Constitutional AI（简称 CAI）。很多文章讲这玩意讲得云里雾里，我用一个我给非技术客户讲过的比喻：

RLHF，也就是 OpenAI 训 ChatGPT 那套主流做法，相当于雇了一群人类标注员去打分——模型生成 A 和 B 两个回答，人看完说 A 更好，模型就记住”要像 A 那样”。这种方式的问题在于，人工很贵，而且人会累、会不一致、会有偏见。

CAI 的做法是：先写一份”宪法”，大概几十条原则（比如”不要帮用户做违法的事””不要输出对特定群体不公平的表述””当你不确定的时候要说不确定”），然后让模型自己拿这份宪法去给自己的回答打分、改写、再打分。人类只在最开始参与，后面大部分工作模型自己循环。

好处是一致性高、可审计（宪法是明文的）、更便宜。缺点是如果宪法写歪了，模型会一本正经地把错误放大。Anthropic 这几年在改的主要就是这份宪法本身。

想展开看 Claude 和 GPT、Gemini 各自的路线差异，我之前写过一篇 2026 Q2 的横向对比，可以接着读。

Claude 家族这几年怎么长起来的

我简单捋一下，按我自己用过的版本为准：

• Claude 1（2023 初）：只在 Slack 里能用，反应慢，但长文本理解明显比当时的 GPT-3.5 好。
• Claude 2（2023 年中）：开放了 API，上下文窗口做到 100K，我当时拿来啃合同、翻法律文书，第一次感觉”这东西能干活”。
• Claude 3 系列（2024）：第一次分了 Haiku / Sonnet / Opus 三档，Opus 3 在推理和写作上当时是拉开同档 GPT 一截的。
• Claude 3.5 / 3.7（2024-2025）：Sonnet 3.5 开始真的好用，Claude Code 也是这一代起步的。
• Claude 4 系列（2025-2026）：现在线上是 Haiku 4.5、Sonnet 4.6、Opus 4.7。Sonnet 4.6 已经是我日常 80% 任务的主力。

三档模型怎么选，我在这篇 Haiku/Sonnet/Opus 选型笔记里写得很细，这里不重复。

和 GPT、Gemini 的定位差异

我尽量不贬低其他家，说几个我自己体感上的区别：

写长文、处理长文档：Claude 到现在为止还是我的首选。它在 50K 以上上下文里不容易丢信息，GPT-4 类在这种场景下常常会”中间段失忆”。

代码：以前 GPT 更强，2025 年之后 Claude Code + Sonnet 反超了，尤其是改大型代码库、做 refactor 这种活。我现在写代码 90% 用 Claude Code 这一套。

对话自然度：GPT 的”人味”更足一点，Claude 会稍微一本正经一些。写营销文案我反而会用 GPT 打草稿，再用 Claude 改逻辑。

安全边界：Claude 拒答率偏高，有时候你让它帮你写个对某个公司有点批评的分析，它会很谨慎。好处是不容易出事，坏处是有时候挺烦的。

价格：Haiku 做到 1 美元/百万 tokens 输入，这个价位段 Anthropic 比较卷。

Gemini 我用得少，主要在 Google Workspace 场景里当插件用，独立用它写东西我没习惯。

我印象最深的一次对话

2024 年夏天，我帮一个客户做合同风险审查，把一份 80 页的英文投资协议丢给 Claude 2，让它找出”对乙方明显不利的条款”。

它没直接列清单，先跟我说了一句：”这份合同里的不利条款有些是显性的（比如第 14.3 条违约金），有些是靠几条互相引用的条款组合出来的陷阱（比如 7.2+11.5+附件 C-3），你想要哪种？”

我当时愣了一下。那个”组合陷阱”它最后挑出来 3 条，其中 1 条我们的律师团队初审都没发现。

从那之后我对 Claude 的印象就定下来了——它不是最聪明的，但它是那个”会告诉你它在想什么、不确定的地方会说出来”的模型。我觉得这跟 Constitutional AI 这条技术路线是有关系的，不完全是运气。

后来在一次协作翻车之后我才意识到这东西有多重要。那次的情况是：我和同事在同一个 repo 里协作，我本地跑 Claude Code 改一个接口改得风生水起，他拉下来跑的时候却发现 Claude Code 一直把代码往完全错误的方向推。排查了俩小时才搞明白——我本地有一份 CLAUDE.md，里面写了一堆项目约定；他没有这份文件（我没 commit），所以他的 Claude 完全不知道这个项目的规矩，只能按通用最佳实践瞎写。

从那天起我开始认真研究 CLAUDE.md。这东西本质上是给 Claude Code 的项目说明书，写得好能让 AI 协作翻倍提效，写得不好能把 AI 带到沟里。这篇把我这半年的经验总结一下。

一、CLAUDE.md 是什么，为什么重要

简单说，CLAUDE.md 是 Claude Code 在启动时会自动读入、作为 system context 的一部分注入到模型的文件。它告诉 Claude：

• 这个项目用什么技术栈
• 代码风格有什么约定
• 哪些文件/目录不能动
• 常用命令是什么（跑测试、部署、lint）
• 有什么”坑”要提前知道

它解决的核心问题是：让 Claude 在一个陌生项目里不再按通用默认行事，而是按这个项目的规矩行事。

你可以理解成”给新人入职的 README，只不过读者是 AI”。

但和 README 有一个关键区别——README 是可选阅读，CLAUDE.md 是强制注入。意味着你写进去的每一个字都会消耗 token、都会影响模型行为。这就决定了 CLAUDE.md 不能当 README 写，它必须更精炼、更有指令性。

二、11 级优先级：从哪读到哪

这个东西官方文档藏得有点深，我整理一下我理解的顺序（从高到低，高优先级会覆盖低优先级）：

1. 当前命令的 CLI 参数 —— 最高优先级，临时强制
2. .claude/settings.local.json —— 本地机器的 Claude 配置（不入 git）
3. 项目根 CLAUDE.md —— 当前项目规则
4. **父目录 CLAUDE.md**（monorepo 场景）
5. 祖父目录 CLAUDE.md —— 依次往上找到 repo 根或 home
6. ~/.claude/CLAUDE.md —— 用户级全局配置
7. .claude/settings.json —— 项目共享配置
8. ~/.claude/settings.json —— 用户全局配置
9. 环境变量（如 ANTHROPIC_MODEL）
10. Claude Code 内置默认
11. 模型本身的 default behavior —— 最底层兜底

这个顺序不用硬记，但要理解两条核心原则：

• 越具体、越靠近当前文件的，优先级越高
• 项目级（CLAUDE.md）和用户级（~/.claude）会叠加，但冲突时项目级优先

实际用起来有一个容易忽略的细节——Claude Code 在启动时会自顶向下把所有层级的 CLAUDE.md 串联起来，不是只读最近的那一份。这意味着你在子目录里的 CLAUDE.md 不是”覆盖”祖父目录的，而是”追加”。如果祖父目录写了”代码注释用中文”，子目录里不写相关规则，那中文注释规则依然生效。

这个机制在 monorepo 场景下特别有用。你可以在 repo 根写通用规则（”所有包都用 TypeScript strict 模式”），然后在每个 package 子目录里写各自的特殊规则（”api 包禁止引入 zod 之外的 validation 库”）。

三、坑 1：写得太多，反而把 Claude 整懵了

这是我第一个大坑。发现 CLAUDE.md 好用之后，我开始往里面疯狂写东西——项目架构、技术栈细节、每个目录的作用、每个核心函数的职责、过往几次重构的历史……写到快 2000 行。

然后 Claude Code 开始变得又慢又飘。

原因很简单：CLAUDE.md 是要完整注入到每次请求的 context 里的。你写 2000 行，意味着每次 Claude 启动都要消化这 2000 行。问题是：

• 信息太多，重点被稀释。关键规则（比如”不要改 legacy_util.py”）被淹没在一堆描述性内容里
• Token 成本爆炸。2000 行大概 15K token，每次请求都是这个基础成本
• **模型开始”过度解读”**。写得越多，Claude 越容易从无关内容里脑补奇怪的推论
• 维护成本翻倍。项目演化时，你要同步更新 CLAUDE.md，内容越多越容易遗漏

我后来把 CLAUDE.md 砍到 150 行以内，执行规则、关键约束、常用命令——其他什么都不写。效果立刻恢复正常，而且 Claude 的判断更稳定了。

原则：CLAUDE.md 写关键信息，不写全部信息。详细架构文档放 docs/ 目录，让 Claude 需要的时候自己去读。你可以在 CLAUDE.md 里留一句：需要深入了解架构时，请先阅读 /docs/architecture.md，把”读不读”的判断权交给模型。

有人问过我具体怎么判断该不该写进 CLAUDE.md。我的标准是——如果 Claude 不知道这条规则就有可能写出错误代码，才写进去；如果只是”知道了更好”的背景信息，不写。这个筛选标准帮我砍掉了 80% 的冗余内容。

四、坑 2：user 级和项目级配置打架

第二个坑更隐蔽。

我在 ~/.claude/CLAUDE.md 里写了我个人的偏好——比如”回答我时默认用中文””代码注释用中文””import 顺序按 isort 风格”等等。这是我的个人习惯。

但有一次我接了一个外包项目，他们的 repo 里有自己的 CLAUDE.md，明确写了”代码注释一律英文”。结果：我本地 Claude 写出来的代码里，注释一会儿中文一会儿英文，完全不统一。

排查后发现问题是——两个文件的规则都被注入了，然后 Claude 自己做了一个折中：”一部分用中文，一部分用英文”。

解决思路：

**1. 把 user 级 CLAUDE.md 写成”偏好”而不是”规则”**。
用 “我通常更喜欢…” 这种语气，不用 “必须…” 这种硬性措辞。这样项目级规则能比较干净地覆盖它。

2. 项目级 CLAUDE.md 明确声明优先级。
我现在写项目级 CLAUDE.md 的第一行一般是：

1
2
3

# 项目规则

本文件中的所有规则优先于 user-level CLAUDE.md。冲突时以本文件为准。

显式写出来，模型会认账。

3. 真的要强制，用 --override-user-memory 启动参数（这个 flag 从某个版本开始支持，具体版本号我不确定，先试再说）

4. 做好 user 级配置的定期清理。
我现在每季度会把 ~/.claude/CLAUDE.md 重读一遍，删掉那些已经不符合自己当前工作习惯的老规则。这个文件一旦塞多了很容易被遗忘，时间一长就变成各种项目的”通用毒瘤”。

再补一个小技巧：如果你经常切换不同客户/团队的项目，可以在 ~/.claude/CLAUDE.md 里完全不写任何强规则，只写自己的语言偏好和沟通风格偏好。技术决策全部交给项目级 CLAUDE.md 去定，冲突就少了。

五、坑 3：@include 循环与隐式依赖

CLAUDE.md 支持 @path/to/file 语法，可以把其他文件的内容拉进来。这玩意儿很强大，但我踩过一个搞笑的坑。

当时我为了复用，把一些通用规则写在 ~/.claude/common.md 里，然后 user 级 CLAUDE.md 里写：

1

@~/.claude/common.md

项目级 CLAUDE.md 里也想复用，又写：

1

@~/.claude/common.md

结果 common.md 被 include 了两次，规则重复。Claude 看到”代码风格 A”出现两次，当作重要信号，反而开始过度强调这个规则。

更惨的情况是：我有一次 common.md 里 include 了 base.md，base.md 里又 include 了 common.md，形成循环。Claude Code 直接报错启动不了。

原则：

• @include 要有层级意识。下游 include 上游，不要互相 include
• 不要重复 include 同一个文件
• 深层嵌套尽量避免。一级 include 够用了，两级以上容易出事
• include 进来的内容也要算 token。有人以为 @include 是懒加载——错了，是 eager 的，启动就全部注入

一个实用建议：如果你想做规则复用，与其用 @include，不如用 shell script 在启动时生成 CLAUDE.md。把”规则碎片库”放在一个统一目录，写一个脚本根据当前项目类型拼装出定制化 CLAUDE.md。这比 @include 的控制力强一个数量级。

六、一个我实际在用的 CLAUDE.md 模板

这是我现在大部分 Node / TypeScript 项目的骨架：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

# [项目名] — CLAUDE.md

本文件优先于 user-level CLAUDE.md。

## 项目本质
一句话说明这个项目是做什么的。

## 技术栈
- Runtime: Node 20
- Framework: Fastify 5
- ORM: Drizzle
- Test: Vitest

## 关键约束
- 所有对外 API 必须有 zod schema 校验
- 禁止引入新的第三方 validation 库（我们用 zod）
- 数据库迁移走 drizzle-kit，不手动改 schema

## 不要改
- `/src/legacy/` 目录下所有文件（迁移中，容易出事）
- `package.json` 里的 node 版本

## 常用命令
- 跑测试：`pnpm test`
- 起开发：`pnpm dev`
- 数据库迁移：`pnpm db:migrate`

## 风格
- import 用绝对路径（`@/xxx`）
- 错误用 Result 类型，不 throw
- 文件名用 kebab-case

## 遇到不确定的时候
- 先看 `/docs/architecture.md`
- 新增 API 前先看 `/src/api/_template.ts`

这份大概 50 行左右。不追求完整，追求关键。

展开一下每个小节的写作原则：

• 项目本质：一句话就够，目的是给 Claude 一个定位锚点
• 技术栈：只列关键版本，不写”为什么选这个”
• 关键约束：写死的红线，违反了一定有问题
• 不要改：负面清单，明确点名
• 常用命令：Claude 要跑测试、lint 时直接复制这些命令，不用猜
• 风格：写 3-5 条最重要的风格偏好，多了反而模糊
• 遇到不确定的时候：告诉 Claude 要去哪看，相当于给它的”自助服务入口”

七、配合 Claude Code 的几个小技巧

1. 把 CLAUDE.md 放进 git。
这应该是常识但很多人不做。这东西不 commit，团队协作就废了。

2. 定期 review。
项目演化，CLAUDE.md 也要演化。我每两周会打开 CLAUDE.md 看一眼，删掉已经不适用的规则、补上新的坑。这东西不是一次性写完就完事的。

3. 新人加入项目时让 Claude 读一遍 CLAUDE.md 做导读。
这招挺好用——直接让 Claude 基于 CLAUDE.md 给新人做一次项目 walkthrough，省了半天时间。

**4. 结合 .claude/commands/**。
把常用的 prompt 做成 slash command，这块和 CLAUDE.md 配合使用效率爆炸。详细玩法我之前在 Claude-Code 分类 下的几篇文章里讲过。

**5. 给 CLAUDE.md 加一个”更新日期”**。
在文件顶部或底部写一行 最后更新：2026-04-15，Claude 看到会自动把这个时间点作为”当前项目约定的参考线”。老旧 CLAUDE.md 如果没标时间，很容易误导模型。

**6. 善用 CLAUDE.md 做 Claude 的”行为纠偏”**。
如果你发现 Claude 某个行为反复让你不爽（比如老是主动改你没让改的文件），就在 CLAUDE.md 里加一条明确禁止。这个文件不仅是项目说明，也是你和 Claude 之间的”行为协议”。

八、最后

CLAUDE.md 这个东西的价值，在于它让 AI 协作有了项目特化的能力。通用大模型有它的通用智能，但每个项目有每个项目的土规矩，这些土规矩靠 prompt 临时讲讲讲不完，靠文档让 AI 自己去读效率又低——CLAUDE.md 就是那个固化土规矩的载体。

写好它的核心心法就一句话：写关键信息，不写全部信息；写规则，不写描述。

想看更多 Claude Code 的实战玩法，claudecode.cocoloop.cn 是一个专门做深度内容聚合的站点，我平时也会去翻那边的更新；想看国内 AI 工程师社区的讨论可以去 ask.cocoloop.cn 看看。

再送一个彩蛋——CLAUDE.md 其实也适合用在非 Claude Code 的场景。我现在很多个人项目的仓库根目录都放一份 CLAUDE.md，哪怕我暂时不用 Claude Code，只是用网页版 Claude。需要让 AI 理解这个项目时，直接把 CLAUDE.md 内容贴进对话框作为 system prompt 就好了。这个文件正在慢慢变成一种跨工具的项目元信息标准。

我过去一年接过三四个 Agent 项目，踩过的架构坑可太多了。有个项目一开始把工具调用、Prompt 组装、状态管理全塞在一个类里，改到第三个功能的时候那个类已经 2000 多行，谁都不敢动。后来我照着 Agent SDK 的思路重构，砍到四个模块，才算活过来。

这篇文章把 Agent SDK 官方的四层架构拆开讲，每一层我尽量给出接口是什么样、扩展点在哪里、生产上怎么用。如果你正在从零搭一个 Agent，这套骨架可以直接抄。

架构总览：四层是哪四层

简单说就是：

1. 应用层（Application）：用户意图、任务定义、UI 对接
2. Agent 层（Agent）：规划、工具选择、对话管理
3. 运行时（Runtime）：执行循环、重试、超时、熔断
4. 服务层（Service）：模型 API、工具实现、持久化

每一层对下层依赖、对上层提供接口，之间用清晰的数据结构交互。下面挨个拆。

一、应用层：把”用户要什么”翻译成”Agent 能处理什么”

这一层最容易被忽视，因为它看起来”没什么技术含量”。但我踩坑最多的就是这里。

应用层的核心职责是任务定义——把用户的模糊需求翻译成 Agent 能吃的结构化输入。比如用户说”帮我把这个项目重构一下”，这在 Agent 眼里是完全不可执行的。应用层要做的是：

1. 识别意图（重构）
2. 约束范围（哪些文件？哪些不能动？）
3. 定义成功标准（测试全过？性能不降？代码行数减少？）
4. 配置资源上限（最多跑多久？最多多少次 LLM 调用？）

实际代码里一般长这样：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

from anthropic_agent_sdk import TaskSpec, ResourceBudget

task = TaskSpec(
    intent="refactor_module",
    scope={
        "target_files": ["src/payment/*.py"],
        "excluded_files": ["src/payment/legacy_bridge.py"],
    },
    success_criteria=[
        "pytest tests/payment passes",
        "line_count_delta <= 0",
    ],
    budget=ResourceBudget(
        max_llm_calls=50,
        max_duration_seconds=1800,
        max_tokens=1_000_000,
    ),
)

应用层的关键扩展点是意图分类器和成功判定器。意图分类器可以是一个小模型（Haiku 非常合适）做路由，不同意图走不同的 Agent 配置。成功判定器可以是纯代码（比如跑一下测试）、也可以是 LLM 自己判（LLM-as-judge）。

我的建议是：能用代码判的绝对不要用 LLM 判。LLM-as-judge 看起来灵活，但不稳定、还费钱。

二、Agent 层：规划、选工具、记状态

这是大家最熟的一层，但也是最容易写烂的一层。Agent 层对外只有一个核心接口：

1
2
3

class Agent:
    def run(self, task: TaskSpec) -> TaskResult:
        ...

它内部要做三件事：

1. Planning（规划）

拿到 task 之后，Agent 要先产出一个执行计划。Agent SDK 官方推荐的是分层规划——先出一个 high-level plan（3-5 步），每一步再在运行时动态展开成具体的子任务。

这比”一步到位画详细计划”好太多了。我之前试过让 Claude 一次性产出 50 步的详细计划，结果前 5 步执行完之后，环境已经和它最初假设的完全不一样了，后面 45 步全白搭。分层规划让 Agent 每次只需要对下一步做细节规划，灵活性高很多。

2. 工具选择

SDK 1.4 里引入了 ToolPicker 抽象。它的作用是：当你注册了 50 个工具的时候，不要把这 50 个工具的描述全塞进 prompt——那样既浪费 token 又会让模型 confused。ToolPicker 会根据当前任务阶段只暴露相关工具。

简化版长这样：

1
2
3
4
5
6
7
8

class ContextAwareToolPicker:
    def pick(self, task_context):
        if task_context.phase == "exploration":
            return [self.tools["read_file"], self.tools["grep"]]
        if task_context.phase == "modification":
            return [self.tools["edit"], self.tools["write"]]
        if task_context.phase == "verification":
            return [self.tools["run_tests"], self.tools["read_file"]]

3. 状态管理

Agent 的状态不只是对话历史。完整的状态应该包括：

• 已读取的文件及其内容快照（避免重复读）
• 已做的修改列表（方便回滚）
• 已失败的尝试（避免重复犯错）
• 资源消耗计数（token、时间、API 调用数）

这一层也是 Prompt Caching 落地的主战场。你可以设计成前面是不变的 system prompt + 任务定义 + 工具定义，后面是动态变化的对话历史，在”系统+任务+工具”的末尾打一个 cache_control，就能把最大的静态部分缓存起来。我在之前讲 成本优化 的时候详细写过这招。

三、运行时：核心循环 + 生产韧性

运行时是 Agent SDK 最”工程化”的一层。它不懂业务，只做三件事：跑循环、处理错误、管资源。

核心循环是这样的伪代码：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

while not task.is_done() and budget.has_remaining():
    # 1. 收集上下文
    context = agent.gather_context(task, state)

    # 2. 执行（模型调用或工具调用）
    try:
        step_result = agent.execute(context)
    except TransientError as e:
        retry(e)
        continue
    except FatalError as e:
        return TaskResult.failed(e)

    # 3. 验证
    verification = verify(step_result, task.success_criteria)
    state.update(step_result, verification)

    if verification.passed:
        return TaskResult.success(state)

三个阶段——收集上下文 → 执行 → 验证——这是 Agent SDK 官方文档反复强调的核心循环。我实操下来最大的心得是：**”验证”这一步绝对不能省**。

很多人写 Agent 就是”让模型说它做完了就算完了”。这是灾难。模型经常”幻觉性完成”——它告诉你测试过了，实际上它根本没跑测试。必须在 runtime 里显式验证。

熔断和指数退避的落地

生产环境最容易出问题的是两种情况：

• API 间歇性故障：模型服务偶发 5xx、429
• Agent 陷入死循环：同一个错误反复试

熔断器（Circuit Breaker）解决第一种。简化实现：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

class CircuitBreaker:
    def __init__(self, failure_threshold=5, reset_timeout=60):
        self.failures = 0
        self.threshold = failure_threshold
        self.reset_timeout = reset_timeout
        self.state = "CLOSED"
        self.opened_at = None

    def call(self, fn, *args, **kwargs):
        if self.state == "OPEN":
            if time.time() - self.opened_at > self.reset_timeout:
                self.state = "HALF_OPEN"
            else:
                raise CircuitOpenError()

        try:
            result = fn(*args, **kwargs)
            if self.state == "HALF_OPEN":
                self.state = "CLOSED"
                self.failures = 0
            return result
        except Exception:
            self.failures += 1
            if self.failures >= self.threshold:
                self.state = "OPEN"
                self.opened_at = time.time()
            raise

指数退避配合 jitter 解决重试风暴：

1
2
3
4

def backoff_with_jitter(attempt, base=1, max_delay=60):
    delay = min(base * (2 ** attempt), max_delay)
    jitter = random.uniform(0, delay * 0.3)
    return delay + jitter

我现在的生产配置一般是：熔断阈值 5 次、重置 60 秒；重试最多 3 次、base 1 秒、max 30 秒。这个参数在我跑的几个项目上稳定了半年没出过事。

死循环检测

Agent 陷死循环的特征是连续 N 步的 action 和 state 没有实质变化。简单做法是对每步的 action hash，如果相邻 3 步 hash 一样（或者语义相似度 > 0.95），就强制打断让 Agent 换思路。更彻底的做法是 runtime 里带一个 “review loop”——每 10 步停下来反思”我们在朝目标推进吗”，如果判断没进展就 abort。

四、服务层：模型、工具、持久化

服务层负责对接外部——LLM API、数据库、第三方工具。这一层的设计原则是可替换。

以模型为例，服务层暴露一个接口：

1
2

class ModelProvider(Protocol):
    def complete(self, messages, tools, **kwargs) -> ModelResponse: ...

然后可以有 AnthropicProvider、RouterProvider（同时挂多个模型、按场景路由）、MockProvider（测试用）。上层完全不知道下面是哪家。

我的 RouterProvider 实现里一般会挂两个策略：

• 按任务难度路由：简单任务 Haiku、中等 Sonnet、复杂 Opus
• 按失败降级：Opus 失败自动降到 Sonnet，Sonnet 再失败降到 Haiku

这种混搭可以把成本控制在一个相对稳定的区间。生产上我跑的 Agent 平均成本比”纯 Opus”低 60%，比”纯 Sonnet”还能再低 15-20%。

工具这一层也要注意——工具的实现和声明要分离。工具声明（名字、参数、描述）给 LLM 看；工具实现（实际代码）是服务层的职责。这样你可以在不同环境下用不同实现（开发环境用 mock、生产用真实 API），声明完全不变。

持久化我不展开了，Agent SDK 给了一个 StateStore 抽象接口，你可以接 Redis、Postgres、甚至本地 SQLite。核心是能随时把 Agent 的完整状态 dump 出来，出问题能复现。

写在最后

四层架构听起来工程味很重，但实际跑起来你会发现它省下的时间远大于额外的抽象成本。一个没分层的 Agent 遇到 bug，你得在两千行代码里大海捞针；一个分好层的 Agent，bug 的位置基本一眼能看出在哪层。

Agent SDK 现在还在快速演进，但四层这个骨架我觉得短期不会变。如果你在做 Agent 相关项目，openclaw.cocoloop.cn 上有一些开源实现可以参考，源码读下来很能启发架构思考。

最后给一个建议：**不要上来就追求”完美架构”**。第一版能跑就行，跑起来之后按痛点重构——哪一层经常要改，就说明那一层的抽象没做好，用痛点来驱动架构演进，比纸上谈兵画图靠谱得多。

我当时嘴里正嚼着东西，差点呛住。这误解在开发者圈里太常见了，甚至连一些写过相关代码的人也会这么觉得。但如果你真的在生产环境里把两种方式都用过，就会明白它们差的不是一点半点——维度根本不一样。

Function Calling 是工具；MCP 是给工具定一个标准插口。你可以说螺丝刀和螺丝的规范是一回事吗？当然不是。

这篇我想把五个最本质的差异一条一条拆给你看，最后说说实际项目选型怎么想。

差异一：协议层 vs 应用层

这是最根本的一条，想通了这一点其它四条都顺了。

Function Calling 是 OpenAI 2023 年 6 月发的一个 API 特性，它的本质是：模型输出结构化 JSON，你的应用代码去执行。Anthropic、Google、阿里、智谱……现在都有自己的 tool use / function calling API，但注意——这是每一家自己 API 里的一个功能。你的代码和 xx 家模型的 API 深度耦合。

MCP（Model Context Protocol）不一样。它是 Anthropic 2024 年 11 月开源出来的一个通信协议，基于 JSON-RPC 2.0，规定了 Client 和 Server 之间怎么发现工具、怎么调用工具、怎么传递上下文、怎么处理流式响应。它本身不绑定任何模型、任何厂商。

打个比方：

• Function Calling 像每个品牌充电器的私有接口。苹果 lightning、华为 Type-C 以前的自家协议、早期安卓的 micro USB——每家自己一套
• MCP 像 USB-C。协议标准化之后，任何设备对任何设备都能用

USB-C 这个比喻最早是 Anthropic 官方自己提的，我一开始觉得有营销味，用多了之后发现还挺贴切。

差异二：有状态 vs 无状态

Function Calling 是一次性交易。你给模型一个 tools 数组，模型决定调哪个、给你返回 JSON，你执行完把结果再塞回对话。工具本身没有”会话”概念，每次调用都是独立的。

MCP Server 是一个长连接的服务。它可以：

• 维护一个数据库连接池，整个会话期间复用
• 缓存用户身份信息，不用每次鉴权
• 推送 notifications/resources/updated 告诉客户端”我这边的资源变了”
• 在多次调用之间保持工作目录、临时文件这些状态

举个最实际的例子：你要做一个”代码仓库分析”工具，让 Claude 能读取项目结构、打开文件、跑测试。

• Function Calling 版本：每次调用 read_file 都要把完整路径当参数传进去，模型要自己记住当前在哪个仓库
• MCP 版本：Server 启动时 cd 到仓库根目录，之后所有调用都是相对路径；Server 还可以主动推送”文件变更”事件让模型知道有新的 commit

这个差异在 Agent 长时任务里会被放大。任务跑 30 分钟、跨越 200 轮对话，有状态和无状态是两种完全不同的编程模型。

差异三：可发现 vs 硬编码

你有没有写过这种代码：

1
2
3
4
5
6

tools = [
    {"name": "search_web", "description": "...", "parameters": {...}},
    {"name": "send_email", "description": "...", "parameters": {...}},
    {"name": "query_db", "description": "...", "parameters": {...}},
]
response = client.messages.create(tools=tools, ...)

这就是 Function Calling 的典型写法——工具列表写死在客户端代码里。你想加一个工具？改代码、重新部署。你想让不同用户看到不同的工具？自己写权限过滤逻辑。

MCP 的核心 API 之一是 tools/list——客户端启动时问 Server：”你都有啥工具？”Server 返回一个动态列表。这意味着：

• 在 Server 侧加一个新工具，所有连接的客户端不用改任何代码就能用
• Server 可以根据当前用户、当前权限，返回不同子集的工具列表
• 工具的描述、参数 schema 都可以在运行时更新

我最近在做的一个内部项目，用 MCP 接了 6 个 Server：知识库、CRM、邮件、日程、Git、监控。运营同学的客户端能看到前 3 个，工程师能看到全部 6 个，运维只看到监控——都是同一份客户端代码，只是 Server 侧发的工具清单不一样。换 Function Calling 的话，光这套权限逻辑就得写几百行。

差异四：跨 LLM vs 单家绑定

这点对做产品的人尤其重要。

我之前做过一个客户项目，用 GPT-4 的 Function Calling 做了一整套工具集成。后来客户要改成 Claude——工具定义格式不一样（OpenAI 用 JSON Schema，Anthropic 用的是类似但不完全一样的格式），消息结构也不一样（OpenAI 的 tool_calls vs Anthropic 的 tool_use content block），全部代码重写一遍，花了一周。

MCP 协议本身是厂商中立的。只要客户端实现了 MCP 协议，它就能连任何 MCP Server；你的 Server 也可以同时服务给 Claude Desktop、Cursor、Cline、甚至某些支持 MCP 的 OpenAI 兼容 Client。

对 Server 开发者来说，写一次，所有生态都能用。这是真正的网络效应，也是为什么我判断 MCP 会比 Function Calling 活得久。

当然现在阶段 OpenAI 自家还没有正式支持 MCP（2026 年初还是这个状态），但第三方适配层已经有一堆了，转换成本比当年重写 Function Calling 低多了。

差异五：服务端自治 vs 客户端编排

这条比较抽象但很关键。

Function Calling 模式下，所有编排逻辑都在你的客户端代码里：什么时候调工具、调哪个、失败重试、结果怎么传回模型——这些都是你写的应用代码在决定。模型只负责”生成 JSON”，你负责”真正做事”。

MCP 下，Server 有更多自主权。它可以：

• 定义自己的 resources（只读数据源），让模型直接引用而不是通过工具调用
• 定义 prompts（预制的 prompt 模板），让用户直接选用
• 通过 sampling API 主动反向请求客户端帮它跑一次 LLM 推理（比如 Server 自己需要做一次翻译）
• 发送 progress 通知告诉客户端”我这个任务进度 30%”

这些能力是 Function Calling 完全没有的。说白了，Function Calling 把模型当大脑、把工具当手；MCP 把 Server 也当作一个有智能的参与方，大家是协作关系。

选型建议：什么时候用哪个

拆完差异，回到实际问题——你到底该选哪个？

选 Function Calling 的场景：

• 单次 API 调用能搞定的任务，比如”帮我写邮件时调一次日历查空闲”
• 快速原型、一次性脚本
• 只给自己或少数内部工具用
• 模型厂商锁定不是问题（比如你们公司就认 OpenAI）

选 MCP 的场景：

• 要给非开发者终端用户用（他们装 Claude Desktop / Cursor 就能用你的工具）
• 工具需要共享给多个应用，一次开发多处复用
• 有长时任务、需要状态和流式响应
• 在搞 Agent 产品，希望兼容未来更多客户端

真实世界里，我现在新项目几乎都走 MCP 了。开发成本没高多少（FastMCP 这种框架已经很顺手），但获得的可移植性和生态红利很可观。关于 FastMCP 的具体用法，我在 Tool与MCP 分类 下面那篇”30 分钟手搓 MCP Server”里有完整的代码示例可以参考。

如果你正在做 Agent 方向的产品，还可以去 Agent开发 分类 看看那边关于 Skills 和 Agent 架构的文章，跟 MCP 组合起来用会有更多想象空间。

最后说点我的个人判断

MCP 现在还在早期——协议版本还在迭代（最新是 2025-06-18 draft），生态工具链不算成熟，debug 也比 Function Calling 麻烦（多一层协议就多一层坑）。

但我的感觉是：这波标准化是挡不住的。Function Calling 这种”每家一套 API”的做法，在行业成熟度低的时候是必然现象，就跟早期移动端充电器一样；但当生态规模到了一定阶段，标准化协议一定会胜出。苹果最后也上了 Type-C，对吧。

做选型决策的时候，我现在的默认选项是 MCP；只有在”真的只需要一次性、工具很少、没有复用需求”的场景才退回 Function Calling。

这不是什么信仰，是算过账的——多花 20% 的开发成本，换来 3 年后不用大重构，这买卖稳赚。

我随口问了一句：”你们公司没有品牌 tone & manner 手册吗？”

她一脸苦笑：”有啊，一份 40 页的 PDF。谁会每写一条文案就翻一遍？”

就这一句话点醒我了。这不就是 Claude Skills 完美适配的场景吗？——一套规则、需要严格遵守、人类执行起来很累、但对 AI 来说只是 reading task。那晚我就开始动手，花了大概两周（零碎时间）做了一个「品牌文案专家」Skill。现在她们市场部三个人日常都在用，实习生再也没犯过低级错误。

这篇想完整记录这个事儿——从需求分析到 SKILL.md 落地到上线后的反馈，给正在想给业务团队做 AI 工具的同学一个参考。

一、这个需求到底是个什么问题

先说清楚她们公司的情况。公司主营两条产品线：

• A 产品：给金融机构的合规审计 SaaS，B 端、客单价百万级、买家是银行风控总监。官网、白皮书、案例都要”稳重、专业、权威”
• B 产品：个人理财 App，C 端、年轻白领、社媒投放为主。需要”亲切、有梗、偶尔调皮”

问题出在同一套文案人马同时服务两条线。实习生写 A 产品的时候带着 B 产品的语气——“银行合规好难？让我们一起搞定！”——产品经理看到当场黑脸。反过来写 B 产品的时候又回到”本产品致力于为用户提供专业的理财解决方案”——运营看到又想哭。

传统解决方案？写 tone 手册、做培训、reviewer 卡稿。都试过，人工成本高、效果还不稳定。

二、为什么选 Skill，不选别的

最早我想到的其实是改系统 prompt——在她们 ChatGPT 企业账号的 default prompt 里塞一大段品牌规则。但有几个问题：

• 写一万字 prompt 成本吃不消，每次请求都烧
• 两条产品线混在一个 prompt 里，模型容易串味
• 规则一改全员得手动更新，没版本控制

然后想到 RAG——把品牌手册切片、embedding、按需检索。问题是 tone & manner 是个整体风格，按关键词检索出来都是断章，拼不出完整画面。

Skill 就很对路：

• 按需加载：用户说”写 A 产品文案”才激活 A 的 Skill，不混淆
• 完整上下文：主 SKILL.md 一次性把 tone 完整载入，不会断章
• 版本化：git 管理，改了一次全员同步
• 描述触发：description 里写清楚”什么时候用我”，模型自动选择

关于 Skills 的底层机制为啥适合这种场景，我在 Agent开发 分类 里那篇深度拆解讲得更细，这里就不重复了。

三、SKILL.md 到底怎么写

这是核心问题。我给她们做的那个 A 产品 Skill 完整结构：

1
2
3
4
5
6
7
8

brand-voice-product-a/
├── SKILL.md
├── references/
│   ├── banned-words.md         # 禁用词清单
│   ├── approved-tone-examples.md  # 20 个正例
│   ├── rejected-examples.md    # 20 个反例加点评
│   └── scenario-templates.md   # 5 类场景文案模板
└── .version

SKILL.md 我来完整贴一下（脱敏过，公司名换成了占位符）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49

---
name: brand-voice-product-a
description: 为 XX 金融合规 SaaS（产品 A）撰写或审阅营销文案。适用于官网 banner、白皮书摘要、客户案例、社媒、BD 邮件等场景。当用户提到"A 产品""合规审计 SaaS""XX 平台"并需要文案撰写或修改时使用。
---

# 产品 A 品牌文案专家

你正在为 XX 公司的合规审计 SaaS 产品线撰写营销文案。这是一个**严肃的 B 端产品**，目标读者是银行/证券/保险机构的风控、合规、审计部门负责人。

## 品牌基调（Brand Voice）

三个关键词：**专业、稳重、克制**。

- 避免所有"兴奋感"和"营销口吻"
- 不使用感叹号（极特殊场景除外）
- 不使用"革命性""颠覆""绝佳"这类夸张形容
- 不假设读者情绪，直接讲事实和价值

参照行业标杆：埃森哲、普华永道、Palantir 的官网文案。

## 三条铁律

1. **第一段必须给出核心价值**，不要铺垫行业背景
2. **数字比形容词优先**：能用"效率提升 47%"绝不用"大幅提升"
3. **案例用具体机构名**（已脱敏的情况下），不说"某大型银行"

## 必查清单

写完任何一段文案，自查：

- [ ] 有无感叹号？（除了致谢类场景全部改掉）
- [ ] 有无"让我们""一起""轻松"这类 C 端词汇？
- [ ] 有无夸张程度副词（非常、极其、最）？
- [ ] 有无数字支撑？
- [ ] 第一句话是否讲价值？

## 引用文件

详细的禁用词清单见 `references/banned-words.md`。
好文案正例看 `references/approved-tone-examples.md`。
常见翻车反例和点评看 `references/rejected-examples.md`。
不同场景（banner/邮件/案例）模板见 `references/scenario-templates.md`。

## 输出格式

根据任务类型返回：

- **撰写**：直接给最终文案，不给多版本（怕市场同事选困难症）
- **审阅**：先给出修改后的版本，再列 3-5 条"问题所在"

B 产品那个 Skill 结构一样，内容全反——个性化、有梗、允许偶尔玩谐音——就不单独贴了。

四、references 文件的几个关键点

主 SKILL.md 只是总纲，真正的”肌肉”在 references 里。几个我踩过的坑：

banned-words.md 不要只列禁用词

一开始我只列了”禁止用词”清单。后来发现模型会漏掉一些变体——比如禁了”让我们”，它会写成”我们一起来”，绕过检查但语气还是错的。

后来改成禁用词 + 禁用句式 + 语气关键词三类：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

## 禁用词

- 让我们、我们一起、不妨、来吧
- 超级、爆款、神器、救星
- 赶紧、立刻、马上（转化类除外）

## 禁用句式

- 反问句（"你还在为 XX 烦恼吗？"）
- 卖惨句式（"再也不用"）
- 召唤句式（"点击了解""立即咨询"——改成陈述"预约演示请访问..."）

## 禁用语气信号

- emoji（B 端全部禁用）
- 过度修辞（类比要克制）
- 网络流行语（出圈、破防、绝绝子……）

approved-examples 至少放 20 条

少于 20 条模型泛化能力不够。每条我都标了为什么这么写：

1
2
3
4
5
6
7
8
9

### 例 1 - 官网主 banner

原文：
"为金融机构构建全流程合规审计基础设施"

为什么好：
- 一句话把产品定义说清楚
- "基础设施"隐含了"深度集成、长期使用"
- 无情绪词、无感叹号

rejected-examples 比 approved 更重要

这个是我后来加的。模型看到”什么是好的”不一定记得住，但看到”什么是错的以及错在哪”效果好得多。

1
2
3
4
5
6
7
8
9
10
11
12
13

### 反例 1

错误文案：
"还在头疼合规审计报告？XX 来帮你搞定！"

错在哪：
- 反问句（营销口吻）
- "头疼"带情绪假设
- "搞定"过于口语
- 感叹号

正确版本：
"XX 支持合规审计全流程自动化，平均缩短人工报告编制时间 60%。"

五、测试怎么做

这步特别容易被忽略，但决定了 Skill 能不能真正上线。

我自己造了一批触发测试集——30 条各种各样的任务描述，一半该触发这个 Skill，一半不该触发：

• 应触发：「帮我写 A 产品官网 banner」「改一下这段合规审计 SaaS 的案例文案」「产品 A 的 BD 邮件开头怎么写」
• 不应触发：「帮我写一封请假邮件」「给 B 产品小红书笔记出个标题」

跑下来第一版触发准确率只有 73%。问题出在 description 写得太泛——“金融文案”这种词把 B 产品的理财 App 也套进来了。改了三版 description 才把准确率拉到 95% 以上。

description 字段是 Skill 能不能被正确选中的关键，值得花时间反复调。我的经验：

• 明确列产品名 / 关键词
• 说清楚场景边界
• 避免过于通用的词（”营销””内容”这种别单独用）

六、上线后的真实反馈

上线三周了，收集到一些真实用户（市场部三个人）的反馈：

正向反馈：

• 实习生那边，产品 PM 审稿打回率从约 40% 掉到 8%
• 我老婆自己写稿速度快了约 30%（因为不用反复核对 tone 手册）
• 最意外的：新入职的人上手时间从 2 周变成 2 天——因为 Skill 本身就是 onboarding 手册

负向反馈：

• 写「混合场景」（比如 A 产品在年轻人媒体投放）的时候，两个 Skill 都不太贴，需要人工裁剪
• 偶尔模型”太听话”，稍微有感情的地方也被它改得死板，需要人工回调一下
• Skill 覆盖不到的完全新场景（比如第一次做播客脚本），还是得人来主导

还没解决的问题：

• 不同 Claude 客户端对 Skills 的支持度不一致。Claude Desktop 原生支持最好，有些第三方 Client 触发不太稳
• Skill 更新后要让所有人同步，目前靠我老婆在群里发 git pull 命令（够土但有用）

七、给想做类似事情的你几个建议

如果你也想给业务团队做一个类似的 Skill，我的踩坑总结：

第一，别一上来写太完美。MVP 先跑起来，用户用起来之后反馈远比闭门造车值钱。我那个第一版只有 SKILL.md 一个文件，references 都是后续加的。

第二，description 是命脉。这一行决定 Skill 能不能被正确激活，花时间反复测。

第三，反例比正例更值钱。模型对”别怎么做”的记忆比”怎么做”更深。

第四，留个人工兜底。Skill 不是万能的，总有它不擅长的场景。告诉用户”遇到 XX 情况直接找人”比硬让模型发挥好。

第五，版本化管理。我用 git 管了这套 Skill 已经改了 18 个 commit，每次改动都能追溯。

想看更多 Claude 在企业落地的案例，可以去 www.cocoloop.cn 翻；想跟进 Skills 相关的最新功能更新，news.cocoloop.cn 上有不少一手信息。

最后说点感触。

以前我们做企业 AI 工具，总觉得要做一个”大脑”——能自动理解一切、自动决策。干了这个项目之后我反而觉得，更好的方式是把企业已有的隐性知识显性化、结构化，让模型当个靠谱的执行者。

你们公司一定有很多「老员工脑子里的规矩」没写下来——Skills 就是把这些东西沉淀下来的最好容器。做一个，就能让新人快速上手；做十个，就是整个团队的共享肌肉。

这事儿不酷炫，但特别管用。

我一开始写的 prompt 是很标准的 Markdown 风格：

1
2
3
4
5
6
7
8
9
10
11
12
13

## 任务
从下面的合同文本中抽取指定字段。

## 要求
- 返回 JSON 格式
- 找不到的字段返回 null
- 金额统一转成人民币数字

## 合同文本
（此处插入合同 3000 字）

## 输出字段
party_a, party_b, amount, date, penalty_clause

跑了 500 个样本，准确率 71%。老板看完脸色不太好。

我折腾了一下午改 prompt，换措辞、加例子、调顺序，最多也就爬到 75%。然后我想起 Anthropic 官方文档里反复强调的一句话：”Claude was fine-tuned with XML tags.”。我就死马当活马医，把整个 prompt 的结构改成 XML：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

<task>从合同文本中抽取指定字段</task>

<requirements>
- 返回 JSON 格式
- 找不到的字段返回 null  
- 金额统一转成人民币数字
</requirements>

<contract>
（此处插入合同 3000 字）
</contract>

<output_fields>
party_a, party_b, amount, date, penalty_clause
</output_fields>

同样的 500 个样本，准确率直接跳到 89%。我当时盯着屏幕看了很久，觉得不可思议——仅仅换了分隔符，效果差了将近 20 个百分点。

从那之后，我写 Claude 的 prompt 再也不用 Markdown 了。这篇把我理解的原因、可复制的模板、几个关键细节讲清楚。

一、为什么差这么多？训练数据的秘密

这个问题 Anthropic 没有官方给出技术解释，但从他们的文档、论文、和员工公开访谈里能拼出一个大概的图像。

Claude 在 Anthropic 内部训练时，大量使用 XML 标签作为结构分隔符。这是他们 Constitutional AI 训练流程里的一个工程习惯——用 <human>...</human> 和 <assistant>...</assistant> 分隔角色，用 <instruction>...</instruction> 分隔指令，用 <context>...</context> 分隔背景信息。

这些标签在训练数据里出现了数百万次，形成了强烈的分布偏好。模型看到 <xxx>...</xxx> 这种结构时，会非常明确地”知道”这是一段独立的、需要被单独对待的内容。

而 Markdown 的 # ## --- 这些符号呢？它们在训练数据里也出现很多，但它们同时出现在模型需要生成的文本里——模型在很多场景下就是在生成 Markdown 文档本身。这就导致了一个混淆：模型看到 ## 时，它不确定这是”输入的结构分隔符”还是”用户想让我生成的内容的一部分”。

相比之下，XML 标签在训练语料里几乎只作为结构分隔符出现，语义非常干净。这就是为什么 XML 的边界感更强。

GPT 系列的情况不太一样——OpenAI 训练时没有特别偏向 XML，所以对它来说 Markdown 和 XML 差别不大。这是 Claude 特有的属性。Gemini 的情况介于两者之间，XML 有一定效果但不如在 Claude 上显著。这也侧面说明了prompt 风格和模型是强绑定的，没有放之四海皆准的”最佳 prompt 格式”。

二、具体差在哪儿？我做过的消融实验

我后来做过一个小型消融实验，同一个任务分别用五种格式跑：

这个结果让我意识到几件事：

1. 任何结构都比没结构好。纯文本到 Markdown 就有 13 个百分点提升，说明”分段”本身就很重要。

2. XML 的优势主要体现在边界清晰。模型知道 <contract> 和 </contract> 之间的东西是一个完整的块，不会和外面的指令混起来。Markdown 的 ## 合同文本 开始了，但什么时候结束呢？下一个 ## 吗？模型要自己推断，容易出错。

3. 差距在输入越长时越明显。短 prompt（500 token 以内）Markdown 和 XML 差个 5-8 个百分点，长 prompt（3000+ token）就能拉到 15-20 个百分点。因为长输入里边界判断的重要性被放大。

4. 结构的语义信息也有加成。同样用 XML，把外层标签从 <data> 改成 <legal_contract>，准确率能再涨 2-3 个点。因为语义化的标签名本身给了模型关于内容性质的提示——模型知道”这是合同而不是随便的文本”，处理态度就不一样。

三、我现在用的标准 XML 模板

把这套经验固化一下，我现在写 Claude prompt 的基础模板长这样：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

<role>
你是一个 [具体角色描述]。
你的任务是 [一句话任务说明]。
</role>

<instructions>
1. [具体步骤 1]
2. [具体步骤 2]
3. [具体步骤 3]
</instructions>

<context>
[所有需要的背景信息、知识、数据]
</context>

<examples>
  <example>
    <input>[示例输入]</input>
    <output>[示例输出]</output>
  </example>
  <example>
    <input>[示例输入 2]</input>
    <output>[示例输出 2]</output>
  </example>
</examples>

<input>
[本次要处理的实际输入]
</input>

<output_format>
[明确的输出格式要求，最好给个 JSON schema]
</output_format>

这个模板有几个原则：

1. 标签名要有语义。不要用 <tag1> <tag2> 这种无意义的名字。<contract> <resume> <invoice> 这种直接点明内容类型的最好——模型能用标签本身获取额外信息。

2. 可以嵌套。<examples> 里套 <example>，<example> 里再套 <input> 和 <output>。Claude 对嵌套结构识别很稳定，两到三层嵌套都没问题。

3. 输入放靠后的位置。研究表明 Claude 对 prompt 末尾的内容注意力最强（recency bias）。所以真正要处理的 <input> 放在靠后位置，更稳定。

4. 指令和数据严格分离。<instructions> 里只写”怎么做”，不要混入具体数据。具体数据放 <context> 或 <input>。这条原则在做 prompt injection 防御时也格外重要——指令和数据混在一起，用户注入攻击就容易得手。

5. 用空行增加可读性。XML 标签之间加空行不影响模型理解，但能让 prompt 人类看着舒服、方便后续维护。

四、几个容易翻车的点

1. 标签不要和要处理的内容冲突。
比如你要处理一份 HTML 文档，HTML 本身就有大量 <div> <span> 标签。这时候你包装数据的标签名要用不会出现在 HTML 里的，比如 <html_document> 而不是 <content>，避免混淆。

2. 不要用自闭合标签。
Claude 对 <tag/> 这种自闭合形式识别率不如 <tag></tag>。老老实实开闭配对。

3. 中文标签会翻车。
我试过用中文标签名（比如 <角色>...</角色>），准确率不如英文标签。因为训练数据里 XML 标签绝大多数是英文，模型的偏好是在英文上建立的。内容可以中文，标签名一定英文。

4. 和 Markdown 混用没问题，但别混淆层级。
XML 包外层结构，内部 <instructions> 里可以用 Markdown 列表，这是没问题的。但不要一个任务一半用 XML 框一半用 Markdown 标题框，那样模型会懵。

5. 标签不要太多也不要太少。
我见过两种极端：一种是整个 prompt 就一对 <task>...</task> 把所有东西包进去，这等于没分块；另一种是每一句话都包一个标签，过度工程化。一般 4-8 对顶层标签是比较舒服的量。

6. 不要在 XML 标签里写 markdown 反引号代码块的开头。
很少人会撞上但确实存在：如果你在 <code>...</code> 里直接写代码，大部分时候没问题；但如果代码里本身含有 < > 符号（比如 Go 的泛型或 HTML 片段），模型可能会错乱。这时候要么用 CDATA 风格（<![CDATA[...]]>，Claude 认），要么外层标签改名绕开冲突。

五、不仅仅是输入，输出也能用 XML

有个更进一步的技巧：让 Claude 用 XML 组织它的输出，再解析出来。

比如我要求 Claude 先思考再回答：

1
2
3
4
5

<instructions>
请按以下格式输出：
<thinking>你的推理过程</thinking>
<answer>最终答案</answer>
</instructions>

这比让它用 “思考：… 答案：…” 这种 Markdown 风格要稳定得多。后端解析也很简单，正则一抓一个准。

这招在 Agent 场景里特别好用——你可以让模型输出 <tool_call>、<reasoning>、<plan> 这种结构化标签，程序化地拆开。这部分实战我另一篇讲 Agent 的文章里有更多例子，想看可以翻 Prompt工程分类。

延伸的一个小 trick：给 Claude 预设输出开头。比如你在 API 调用里把 assistant 的开头预填为 <answer>，Claude 会自动从那里续写，不会再输出啰嗦的开场白。配合 stop sequence </answer> 使用，一次调用就能稳定拿到干净的答案内容，适合做结构化抽取的生产环境。

六、进阶：XML + Tool Use 的组合拳

如果你用的是 Claude 的 tool use 功能，其实你已经在用 XML 了——Anthropic 的 tool call 格式底层就是 XML。你在 system prompt 里用 XML 组织指令，和工具调用的格式天然一致，模型处理起来更流畅。

我最近在做的一个 Agent 项目就是这个玩法：

• system prompt 用 XML 定义角色、规则、工具使用准则
• tool schema 按 Anthropic 的 XML tool 格式定义
• 中间步骤让模型输出 <scratchpad>...</scratchpad> 做思考
• 最终结果用 <final_answer>...</final_answer> 包装

整套 prompt 从头到尾都是 XML 结构，模型的一致性特别好。转战 Claude 之后我再也不想回去搞 GPT 那套花里胡哨的 function calling schema 了。

七、最后说两句

XML over Markdown 这个小技巧看着不起眼，但在生产环境里能直接拉高 10-15 个百分点的准确率，值回票价。这种”训练数据偏好”导致的工程 trick 还有不少，比如 Claude 对 “Here is the answer:” 这种引导句的敏感度、对 <system> 标签的权重倾斜、对 “step by step” 这种链式思考触发词的反应等等。我会持续把踩到的这类坑整理出来。

如果你是 Claude 新手，建议把上面那个标准模板存下来，下次写 prompt 直接填空。光这一点，你 prompt 的效果就会比 80% 的同行好。想看更多 Claude 实战内容可以顺带访问一下 www.cocoloop.cn 和 openclaw.cocoloop.cn，后者是专门聚焦 Anthropic 生态的一个子站。

最后分享一个心得：prompt 格式和模型版本是绑死的。Claude 3 Opus 时代最有效的 XML 模板，到了 Sonnet 4.6 上效果会微妙地变化，新模型对结构的宽容度更高一些。每次换模型版本，建议把自己最常用的几个 prompt 拉出来回归测一遍，别想当然。

那时候我正好看到 Anthropic 更新了 Prompt Caching 的文档，抱着试试的心态改了几行代码。改完跑了一天，第二天打开账单那一刻我真的惊了——单日成本从 $110 降到 $18。不是看错，是真的降了 83%。

从那天起我就成了 Prompt Caching 的重度用户，这东西在我这儿已经是”每个项目上线前必做的检查项”。这篇文章想把我这一年踩过的坑、摸出来的最佳实践全部摊开，给还没用过的人一个能直接照抄的参考。

一、先把价格结构讲清楚

很多文章讲 Prompt Caching 第一句就是”能省 90%”，但不告诉你是在什么条件下省的。先把价格表拉清楚：

以 Claude Sonnet 4.6 为例（Opus 4.7 按比例推算）：

• 普通 input：$3.00 / MTok
• cache write（5 分钟 TTL）：$3.75 / MTok（比普通贵 25%）
• cache write（1 小时 TTL）：$6.00 / MTok（比普通贵 100%）
• cache read：$0.30 / MTok（是普通的 1/10）
• output：$15.00 / MTok（这个不受影响）

读到这里你应该明白 Prompt Caching 的”生意逻辑”了——写入要额外多花钱，但读取便宜到惊人。关键问题是：你得读几次才划算？

算一下：以 5 分钟 TTL 为例，假设有 100K token 的 context。

• 不缓存：每次都花 $0.30，100 次就是 $30
• 用缓存：第一次写入 $0.375，后面 99 次每次 $0.03，总共 $0.375 + $2.97 = $3.345

也就是 **100 次调用省了 89%。但是——如果你只调用 1 次，反而多花了 25%**。这就是为什么 Prompt Caching 不是无脑开就好的。

我自己总结的一个记忆点是：2 次命中就回本。

• 1 次 write + 1 次 read = $0.375 + $0.03 = $0.405
• 2 次普通 = $0.60
• **省 33%**，够本还有赚

也就是说，只要你这段上下文在 5 分钟内至少会被读到 2 次，缓存就值得开。这个阈值极低，99% 的生产场景都能达到。

二、5 分钟 TTL 和 1 小时 TTL 怎么选

这是另一个容易被忽略的决策。

5 分钟 TTL 是默认的。它的逻辑是：每次成功命中，TTL 会被”续期”回 5 分钟。所以只要你的请求间隔不超过 5 分钟，这个缓存可以一直活着。

1 小时 TTL 是付费的——写入贵一倍。它的适用场景很具体：两次请求之间间隔会超过 5 分钟，但不会超过 1 小时。

实际项目里我这么判断：

• 聊天机器人场景：5 分钟绝对够，用户跑来跑去发消息，5 分钟之内大概率会有下一条
• 批量处理 job：看批量的节奏。如果是 1 分钟一批，5 分钟足够；如果是半小时跑一次，用 1 小时 TTL 更划算
• 客服工单 / 低频查询：1 小时 TTL 合适，因为用户第二次问可能间隔几十分钟
• 一次性任务：别用缓存，纯粹浪费那 25% 的写入溢价

有个反直觉的坑：不要觉得”1 小时肯定比 5 分钟保险”。1 小时 TTL 写入贵一倍，如果你的实际命中率不高，多花的写入钱会吃掉所有省的读取钱。我在一个项目上吃过这个亏——当时怕 cache miss 把 TTL 都设成 1 小时，结果实际命中率只有 35%，账单比 5 分钟 TTL 版本还贵了 40%。

三、cache_control 到底放哪里

这是实操里最容易错的地方。Anthropic 的 API 要求你在请求体里用 cache_control: {"type": "ephemeral"} 标记出哪些是要缓存的 block。但放的位置大有讲究。

核心规则只有一条：缓存从请求最开始一直延伸到标记位置。你标记的是”这段之前的所有内容都要缓存”的结束点。

举个例子，假设你的请求是这样结构：

1
2
3
4

[system prompt: 2K]
[大段文档 A: 50K]
[大段文档 B: 30K]
[用户当前的问题: 200]

你要问自己：哪些部分是多次请求之间不变的？

如果文档 A 是每次调用都一样的（比如产品手册），文档 B 也是，只有用户问题在变，那就在文档 B 末尾打标记：

1
2
3
4
5
6
7
8
9
10
11

messages = [
    {
        "role": "user",
        "content": [
            {"type": "text", "text": "<manual>...文档A...</manual>"},
            {"type": "text", "text": "<policy>...文档B...</policy>",
             "cache_control": {"type": "ephemeral"}},
            {"type": "text", "text": "用户问题：{question}"}
        ]
    }
]

system prompt 单独也可以标，这里不展开。

最多可以标 4 个缓存断点。这在”部分变部分不变”的场景特别有用。比如：

• 断点 1：system prompt（永远不变）
• 断点 2：用户档案（同一用户之内不变）
• 断点 3：会话历史前 N 轮（每轮往后推）
• 断点 4：当前轮工具调用结果

这种多断点设计我在做长会话 Agent 的时候用过，命中率能拉到 75% 以上。

四、什么样的请求适合缓存

不是所有 API 请求都值得开缓存。我总结了三个适合的场景：

第一，大段静态上下文 + 小段动态输入。典型代表是文档问答——每次上下文都是那几万字的手册，只有用户问题在变。这种场景缓存命中率天然就高。

第二，多轮对话。只要你的对话超过 3-4 轮，前面的历史 + system prompt 缓存起来就能省很多。我一个做客服机器人的朋友，把这个开了之后月账单从 $1800 降到 $460。

第三，批量并行调用。比如同一个 prompt 模板，不同的用户数据并行跑一百份。第一个请求写入缓存，后面 99 个全是 cache hit，省钱爽到飞起。

不适合缓存的场景也要明确：

• 上下文每次都变（比如每个请求都是独立的短问答）
• context 太短（低于 1024 token，Anthropic 有最小缓存长度限制）
• 高度敏感的数据不想留在服务端缓存里（虽然官方文档说缓存是隔离的，但合规要求严格的场景自己判断）

五、一个真实的 before/after 账单对比

回到开头那个 PDF 处理项目。我把优化前后的数据摊开：

优化前（每份 PDF 一次独立请求）：

• 每份 PDF 平均 context 40K token
• 每天 3000 份
• 每天 input 消耗：12000 万 token（120M）
• 日账单：约 120 × $3 = $360（实际因为输出 token，综合算下来 $110 左右按入口看）

优化后（相同的抽取模板用 caching）：

• system prompt + 抽取规范（约 8K token）整段缓存
• 每份 PDF 的正文还是要现读（不能缓存，因为每份不一样）
• 缓存命中率：~95%
• 日账单：$18

省了 83%。客户爽到直接给我加了一个模块的单。

这个数字的前提是我做了两件事：

1. 把所有”跨请求不变的”部分整合到 prompt 前半段。很多人一开始把”当前这份 PDF 内容”放在最前面，这样根本没法缓存——小改动
2. 用 5 分钟 TTL，因为 3000 份 PDF 基本是 7x24 在跑，请求间隔远小于 5 分钟

六、最后几个实操建议

1. 上线前先看 cache 命中率。Anthropic API 返回里有 cache_read_input_tokens 和 cache_creation_input_tokens 两个字段，监控这俩就知道缓存是不是真的在工作
2. 不要过度设计。一开始只标一个断点就行，跑起来有数据之后再看要不要加
3. 注意模型版本切换会让缓存失效。从 Sonnet 4.5 升到 4.6 的时候，所有缓存都要重建。这时候预热缓存的成本别忘了算
4. 本地调试先别开缓存。测试阶段频繁改 prompt，开了反而浪费写入费用

Prompt Caching 说白了就是把”重复的 context 只付一次近似全价，之后打 1 折”。这事儿技术上不难，但很多人根本没去看文档，默认就用普通 API。我在 Claude API 知识地图 里看到这块的关注度其实不高，大部分人还停留在”换模型省钱”的层面——其实单是把 Prompt Caching 开好，省的钱就比换模型多得多。

降本这件事，cocoloop.cn 主站之前整理过一批案例，如果你想系统了解 AI 应用的成本优化路径，可以去翻翻。

我们公司有个内部订单系统，MySQL 库里挂着几千万行数据。运营组的小姑娘几乎每天都要问技术：”帮我查一下昨天 XX 渠道的退款单数””帮我拉一下 3 月 GMV 按城市分组”。一开始还好，后来一天能来十几次，我们这边排期排不过来，她那边也急，经常下班前还在等一张报表。

上个月我心一横，花了一个下午给她搭了个 MCP Server，直接让 Claude Desktop 接到内网 MySQL 上。现在她自己用自然语言问，Claude 帮她写 SQL、跑 SQL、甚至画个简单的 Markdown 表格出来。这篇想把整个过程完整写一遍——不是教科书式的”hello world”，是真真正正上了生产、正在跑的那版。

一、为什么选 MCP，不选 Function Calling

先澄清一个事儿。这个需求技术上确实可以用 Function Calling 直接做——写个 Python 脚本，调 Claude API，把 execute_sql 定义成一个 tool，让模型生成 SQL 然后你本地执行。我一开始也是这么想的。

但有几个问题绕不开：

• 运营小姑娘不是程序员，她用的是 Claude Desktop 客户端，不可能让她打开终端跑你的脚本
• 公司之后还要接第二个工具（查 CRM）、第三个工具（发企业微信通知），每加一个都得改脚本
• 权限控制散在代码里，谁能查什么表、哪些字段要脱敏，改一次要重新部署

MCP 正好解决这几件事。它是协议层的东西，Server 一次写好，任何支持 MCP 的客户端都能接——Claude Desktop、Cursor、Continue、Cline，甚至自研的 Agent。关于 MCP 和 Function Calling 到底差在哪，我在 Tool与MCP 分类 里还有一篇专门拆过，这里就不展开了。

二、技术栈选型：为什么是 FastMCP

Anthropic 官方 SDK 是 mcp 这个包，能用但偏底层，你得自己处理 JSON-RPC 的细节。社区里有个叫 FastMCP 的封装，用起来就跟写 Flask 差不多，一个装饰器搞定一个 tool。生产项目我一律用 FastMCP，开发效率差了不止一个量级。

1

pip install fastmcp pymysql python-dotenv

就这么简单。Python 3.10+ 就行。

三、最小可运行版本：20 行代码接通数据库

先上最原始的版本，让整个链路跑通：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

# server.py
import os
import pymysql
from fastmcp import FastMCP
from dotenv import load_dotenv

load_dotenv()
mcp = FastMCP("internal-sql")

def get_conn():
    return pymysql.connect(
        host=os.getenv("DB_HOST"),
        user=os.getenv("DB_USER"),
        password=os.getenv("DB_PASS"),
        database=os.getenv("DB_NAME"),
        charset="utf8mb4",
        cursorclass=pymysql.cursors.DictCursor,
    )

@mcp.tool()
def query_sql(sql: str) -> list[dict]:
    """执行只读 SQL 查询，返回结果行列表"""
    with get_conn() as conn:
        with conn.cursor() as cur:
            cur.execute(sql)
            return cur.fetchall()

if __name__ == "__main__":
    mcp.run()

配上 .env：

1
2
3
4

DB_HOST=10.0.1.15
DB_USER=readonly_bot
DB_PASS=xxx
DB_NAME=orders

在 Claude Desktop 的配置文件里加一段（Mac 是 ~/Library/Application Support/Claude/claude_desktop_config.json）：

1
2
3
4
5
6
7
8

{
  "mcpServers": {
    "internal-sql": {
      "command": "python",
      "args": ["/path/to/server.py"]
    }
  }
}

重启 Claude Desktop，你就能在输入框看到一个小锤子图标，里面有 query_sql 这个工具。问它”帮我查最近 7 天退款最多的前 10 个订单”，它就会自己写 SQL 调用 tool，然后把结果整理成表格给你。

这一版能跑，但离生产还差十万八千里。下面是我真实踩过的坑。

四、坑一：权限——这玩意儿敢不敢让 Claude 随便写 SQL

这是我第一版上线当天就翻车的地方。

Claude 很聪明，但它不知道你公司的”业务约束”。运营小姑娘问了一句”把测试订单都删掉”，它还真就写了个 DELETE FROM orders WHERE ...。还好我当时用的是只读账号，SQL 执行直接报了权限错误。

教训是三层防御一个都不能少：

第一层，数据库账号只给 SELECT 权限。这是地板，永远不能塌。

1
2
3
4

CREATE USER 'readonly_bot'@'%' IDENTIFIED BY 'xxx';
GRANT SELECT ON orders.* TO 'readonly_bot'@'%';
-- 敏感表直接不给
REVOKE SELECT ON orders.user_identity FROM 'readonly_bot'@'%';

第二层，代码里白名单校验 SQL。用 sqlparse 解析，只允许 SELECT：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

import sqlparse

def is_readonly(sql: str) -> bool:
    parsed = sqlparse.parse(sql)
    if not parsed:
        return False
    stmt_type = parsed[0].get_type()
    return stmt_type == "SELECT"

@mcp.tool()
def query_sql(sql: str) -> list[dict]:
    if not is_readonly(sql):
        raise ValueError("仅支持 SELECT 查询")
    # ... 原逻辑

第三层，敏感字段在返回层脱敏。手机号、身份证、邮箱这类东西，数据库里有，但返回给 Claude 之前要处理：

1
2
3
4
5
6
7

SENSITIVE_COLS = {"phone", "id_card", "email"}

def mask_row(row: dict) -> dict:
    return {
        k: (v[:3] + "****" + v[-2:] if k in SENSITIVE_COLS and isinstance(v, str) and len(v) > 5 else v)
        for k, v in row.items()
    }

这三层加起来，运营组再怎么折腾也不会把线上数据搞挂。

五、坑二：超时——大表一跑就卡死整个 Claude

早期版本我没做超时控制。结果有一次她问”把去年所有订单按用户维度聚合”，Claude 写了个没加 LIMIT 的聚合 SQL，直接把 MCP Server 卡住了 40 秒。Claude Desktop 那边超时断开，整个会话都崩了。

修复方案两步走：

数据库层加 max_execution_time：

1
2
3
4
5
6
7
8
9
10
11

@mcp.tool()
def query_sql(sql: str, limit: int = 1000) -> list[dict]:
    if not is_readonly(sql):
        raise ValueError("仅支持 SELECT 查询")
    with get_conn() as conn:
        with conn.cursor() as cur:
            cur.execute("SET SESSION MAX_EXECUTION_TIME=10000")  # 10 秒
            if "limit" not in sql.lower():
                sql = f"SELECT * FROM ({sql}) t LIMIT {limit}"
            cur.execute(sql)
            return [mask_row(r) for r in cur.fetchall()]

行数上限硬编码。Claude 要是真给你返回 10 万行，上下文就爆了。默认 1000 行，需要更多的话让用户显式传参。

六、坑三：日志——出了事儿要能复盘

这个是我朋友血泪教训。他们那边有次数据被疑似”泄露”，老板要追查每一次查询，但 MCP Server 完全没打日志，只好翻 MySQL 的 general log，工作量巨大。

我的做法是每次调用都打结构化日志，包括 SQL、调用方、执行时间、返回行数：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

import logging
import json
import time
from pathlib import Path

log_path = Path("/var/log/mcp-sql/audit.log")
log_path.parent.mkdir(parents=True, exist_ok=True)

audit = logging.getLogger("audit")
audit.addHandler(logging.FileHandler(log_path))
audit.setLevel(logging.INFO)

@mcp.tool()
def query_sql(sql: str, limit: int = 1000) -> list[dict]:
    t0 = time.time()
    try:
        if not is_readonly(sql):
            raise ValueError("仅支持 SELECT 查询")
        # ... 执行
        elapsed = time.time() - t0
        audit.info(json.dumps({
            "ts": int(t0),
            "sql": sql,
            "rows": len(result),
            "ms": int(elapsed * 1000),
            "status": "ok",
        }, ensure_ascii=False))
        return result
    except Exception as e:
        audit.info(json.dumps({
            "ts": int(t0),
            "sql": sql,
            "status": "error",
            "error": str(e),
        }, ensure_ascii=False))
        raise

日志按天切，配合 Loki 或者直接 grep，出事追责分分钟。

七、Docker 化：让它能在公司服务器上稳定跑

本地跑是给自己用的，上生产给全运营组用就得容器化。Dockerfile 非常朴素：

1
2
3
4
5
6
7
8
9
10

FROM python:3.11-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY server.py .
COPY .env .

CMD ["python", "server.py", "--transport", "sse", "--port", "8080"]

MCP 官方支持两种 transport：stdio（本地进程间）和 SSE（HTTP 长连）。给团队用一定要选 SSE 模式，放内网服务器上，所有人客户端配一个 URL 就行：

1
2
3
4
5
6
7

{
  "mcpServers": {
    "internal-sql": {
      "url": "http://10.0.1.30:8080/sse"
    }
  }
}

八、上线之后的真实反馈

到现在用了快一个月。运营组的使用频率：日均 40-60 次查询，高峰期一小时 20 次。我这边完全不用管了，她自己跟 Claude 聊两句就拿到数据。

有几个没预料到的好处：

• 她开始学 SQL 了。看多了 Claude 生成的 SQL，她现在自己能读懂 JOIN 和 GROUP BY
• 需求被过滤了一轮。以前来找我们的需求十个有三个是”她想错了”，Claude 会在执行前复述一遍”你是想查 XX 对吧？”，经常她就发现自己问反了
• 跨部门传播。财务组听说了，现在在催我给她们也搞一个

下一步我打算把 CRM 客户查询、企业微信消息推送也做成 MCP Tool，塞进同一个 Server。想了解更多 MCP 实战案例的话，可以去 openclaw.cocoloop.cn 看看，那边有更多开源项目的分享。如果你对 Claude 在企业内部的深度集成感兴趣，claudecode.cocoloop.cn 也有不少相关内容。

写到这里差不多把我知道的坑都倒完了。MCP 这东西说难不难，三十分钟确实能跑起来；说简单也不简单，真要用在生产上，权限、超时、日志、脱敏，每一环都得踩一遍才放心。

到了 2025 年下半年做 Agent 项目的时候，我突然发现那套思路彻底不够用了——我可以把单次请求的 prompt 调到完美，但 Agent 跑几十轮之后照样翻车；我可以给模型写一个漂亮的 system prompt，但真正决定它表现的是每一步我塞给它的上下文。

这时候我才反应过来：过去两年大家琢磨的 “Prompt Engineering”，其实只是 “Context Engineering” 的一个子集，而且是最小的那一块。

这篇我把自己这一年半从 Prompt 调教转向 Context 工程的思路转变讲清楚，以及我现在实际在用的四个支柱：Writing、Selection、Compression、Isolation。

一、Prompt Engineering 的天花板在哪

先回到起点。Prompt Engineering 解决的问题是：同样的模型、同样的输入数据，换个问法就能让输出质量差一倍。这个观察本身没错，现在也依然成立。

但它有两个死穴：

第一个死穴：单轮视角。
Prompt Engineering 的训练场是 ChatGPT 这种对话框——我说一句，它回一句，我觉得不好，我改 prompt，再问一句。这套方法在信息已经齐全的场景下非常有效。但一旦进入 Agent、进入多轮、进入工具调用，你会发现模型表现好不好，已经不是”这句话怎么说”决定的了，而是”前面那 30 轮对话里它看到了什么“决定的。

第二个死穴：把模型当成一个黑箱说服对象。
Prompt Engineering 的潜台词是”我得用某种魔法咒语哄着模型好好干活”。但模型本质上是一个函数 f(context) -> output，它产出什么完全取决于你输入给它的 context。与其琢磨怎么把一句话说得更花，不如琢磨怎么把整个 context 组织得更好。

我自己的顿悟时刻是一次 debug——Agent 在第 25 轮突然开始胡说八道，我一开始以为是模型幻觉，仔细看日志才发现，它的 context 里已经有 180K token 了，其中 90% 是无关的旧工具调用结果，真正有用的信息被淹没在噪声里。这不是 prompt 的问题，这是 context 管理的问题。

还有一个更微妙的问题：Prompt Engineering 时代大家比的是”谁的 prompt 更巧”，结果是大家都在卷单 prompt 的极限，忽略了整个流水线的设计。真正生产级的 AI 系统，瓶颈不在于某个 prompt 能不能挤出最后 5% 的性能，而在于 context 流转的每一个环节是否稳定。这是两种完全不同的工程思维。

二、Context Engineering 的四个支柱

我现在脑子里的框架是这么四块。这不是我发明的，Anthropic 和一些国外团队的分享里反复出现过这个分类，但我想用自己的项目例子讲一遍。

支柱一：Writing（怎么写上下文）

这块是传统 Prompt Engineering 的地盘，但有几个新的工程化视角。

Context 要分层：system 层写不变的（角色、规则），tool 层写能力，user 层写本轮输入。不要把所有东西都堆在 system prompt 里——那样 Prompt Caching 都没法用。

Context 要版本化：我现在项目里的 prompt 模板都是 git 管理，每次改都要写 commit message。这听起来像废话，但你不版本化，你就没法 A/B test，就没法回滚。

Context 要分离配置和逻辑：模型叫什么名字、temperature 多少，这些是配置；”拿到用户问题后先做意图识别”这些是逻辑。两者混在一起写你会哭。

Context 要有 schema 意识：与其用自然语言让模型”输出 JSON”，不如直接定义 tool schema 或用 structured output 强约束。自然语言指令越精确，说明你越没把工程学做好。

我 Claude Code 项目里的 CLAUDE.md 就是这么组织的，具体写法我在 《CLAUDE.md 写法大全》 里讲。

支柱二：Selection（选什么进上下文）

这是最关键、也最被低估的一块。

思路很朴素：模型的上下文窗口是有限的，你得选最有用的信息塞进去，而不是一股脑全扔。听起来像废话，但 90% 的 Agent 项目都没做好这件事。

我现在的业务 Agent 里，Selection 层长这样：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

def build_context(user_query, history, tools_available):
    # 1. 基于语义相似度从历史中召回相关轮次
    relevant_history = semantic_search(
        query=user_query, 
        corpus=history, 
        top_k=5
    )
    
    # 2. 基于意图识别选要暴露的工具（而不是全部塞进去）
    intent = classify_intent(user_query)
    tools = filter_tools_by_intent(tools_available, intent)
    
    # 3. RAG 召回相关文档
    docs = rag_retrieve(user_query, top_k=3)
    
    return {
        "history": relevant_history,
        "tools": tools,
        "docs": docs
    }

几个反直觉的经验：

• 工具不是越多越好。我一开始给 Agent 塞了 40 多个 tool，发现它选错的概率很高。后来做了按意图筛选，每次只暴露 5-8 个最相关的，准确率反而上升
• 历史不是越全越好。全量历史往里塞，模型会被早期无关的信息带偏。最近 N 轮 + 语义相关召回 K 轮，效果最好
• RAG 返回的 chunk 要排序。不是按 similarity score 排，是按 “模型最容易注意到” 的顺序排——最重要的放最前或最后，中间段落会被忽视（Lost in the Middle 效应）
• 召回质量 > 召回数量。很多团队一上来就把 top_k 调到 20，结果噪声一堆，精度反而变差。我现在标配是 top_k=3~5，加一个 rerank 层

还有一个务实的点——Selection 需要可观测性。你得能 log 出”这一次 context 由哪些片段组成”，出问题时才有排查线索。我在项目里搞了一个 context tracer，每次构建 context 都记录下来，debug 效率提升一倍不止。

支柱三：Compression（怎么压缩）

当 Selection 做完，你可能还是有 80K 的 context 要处理。这时候需要 Compression。

我常用的三种压缩手段：

1. Summarization Cascade。
每 10 轮对话，用 Haiku 把前面的对话总结成 500 字以内的摘要，替换掉原文。这招在长对话场景里能把 context 压缩 90% 以上，信息损失在可接受范围。Haiku 做这种总结任务完全够用，不需要动 Sonnet。

2. Structured Representation。
把工具调用结果从”自然语言的一大段描述”换成结构化 JSON。同样的信息，JSON 比自然语言省 50-70% 的 token。更极端的做法是把长结果 “卸载” 到外部存储，context 里只保留一个引用 ID，下次需要再读——这是 Claude 最近出的 memory tool 的核心思路。

3. Prompt Caching。
这个严格来说不是压缩，是计费层面的压缩——固定的 context 部分命中 cache 之后，input token 成本降到 10%，等效于节省了 90% 的输入预算。Anthropic 家 cache TTL 是 5 分钟，高频 Agent 场景非常吃香。

4. 选择性遗忘。
不是所有历史都值得保留，有些中间态（比如失败的工具调用、无效的查询尝试）对后续决策毫无帮助，可以直接从 context 里删掉。我的一个 Agent 加了这个清理逻辑之后，context 平均长度降了 40%，稳定性还提升了。

支柱四：Isolation（怎么隔离上下文）

这块是我最近才开始重视的，也是 multi-agent 架构的核心。

朴素的做法是一个 Agent 一路跑到底，所有信息都在同一个 context 里。问题是：context 会越积越脏，不同子任务的中间产物会互相干扰。

Isolation 的思路是：不同职责拆成不同 sub-agent，每个 sub-agent 有自己独立的 context，主 Agent 只拿子 Agent 的最终结论，不碰它的过程。

比如我一个 research Agent 的架构：

1
2
3
4
5

主 Agent（规划 + 汇总）
   │
   ├── 搜索 sub-agent（专注搜索，自己的 context 里全是搜索结果）
   ├── 阅读 sub-agent（专注读长文，自己的 context 里是文档原文）
   └── 写作 sub-agent（专注组织输出，只看主 Agent 给的 brief）

每个 sub-agent 跑完之后，主 Agent 只把精炼后的结果拉回来。这样主 Agent 的 context 始终保持干净，几十轮跑下来都不会爆。

坏处是成本会增加（多次 API 调用），好处是稳定性和可观测性大幅提升——某个 sub-agent 翻车，你只调它自己的 prompt 就行，不会影响全局。

另一个隐藏收益是可以为不同 sub-agent 选不同模型。主 Agent 需要规划能力，用 Sonnet；搜索 sub-agent 做的是结构化任务，用 Haiku；写作 sub-agent 偶尔上 Opus 做深度生成。这种混合部署比单模型跑到底要划算得多。

三、这四个支柱怎么搭在一起

实际项目里这四块不是孤立的，是一个循环：

1
2
3
4
5
6
7
8
9

Writing（写基础 context）
   ↓
Selection（每轮动态挑）
   ↓  
Compression（太长了就压）
   ↓
Isolation（复杂任务分出去）
   ↓
新的输出又成为下一轮的 context → 回到 Selection

我的经验是：项目早期重点投 Writing 和 Selection，中后期重点投 Compression 和 Isolation。早期你 context 不会太大，关键是搭好基础结构；跑到后面规模上来了，压缩和隔离才成为瓶颈。

另一个维度的建议：投入顺序应该匹配业务规模。日活几百的 Agent 应用，Compression 和 Prompt Caching 能省下来的钱可能还不够你写这块代码的工时。日活过万之后，这些优化的 ROI 才开始体现。

四、一个常被忽视的点：Context 的”时效性”

上面讲的四个支柱都是空间维度的——怎么组织信息。但还有一个时间维度：**context 里的信息有”新鲜度”**。

举个例子：Agent 在 10 轮之前查过某用户的订单状态，当时是”已发货”。现在第 20 轮又需要这个信息，是直接从 context 里读？还是重新查？

不同场景答案不同：

• 用户基础信息（姓名、手机号）—— 缓存住，别重复查
• 订单状态、库存、价格 —— 最多用 5 分钟之前的缓存，再久就得重查
• 实时流数据（股价、监控指标）—— 每次都要重查

这种时效性管理不在 prompt 层，而是在你的工具调用和状态管理层。Context Engineering 不是纯 prompt 工程，它是系统工程。

五、工具和生态

这套思路背后其实已经有不少成熟工具了：

• LangGraph / AutoGen 这类框架核心就是帮你做 Isolation
• LlamaIndex 的 Context 管理是典型的 Selection
• Anthropic Claude 家族本身 Prompt Caching 就是 Compression
• MCP 协议的工具发现机制可以帮你做动态 Selection
• OpenAI Assistants API 的 threads 某种程度上也是一种 Context 存储抽象

关于 MCP 的使用细节，站内 Tool与MCP 分类 下有几篇专门的文章。想看国际上关于 Context Engineering 的更多一手讨论，可以看 hermes.cocoloop.cn 上整理的一些长文（那边偏英文内容聚合）。

六、一句话总结思路转变

过去我面对一个 AI 应用问题，第一反应是 “我怎么改 prompt 让模型答得对“。
现在我的第一反应是 “我要给模型看什么它才可能答得对“。

前者是说服，后者是供给。从说服到供给，这就是 Prompt Engineering 到 Context Engineering 的本质区别。

下一个范式升级是什么？我赌是 Memory Engineering——也就是怎么让模型跨会话、跨任务地积累和调用知识。这块 Anthropic 刚出的 Memory Tool 已经在铺路了，等我试得再深一点再写。

最后给一个务实建议：如果你现在还在靠一份几百字的 system prompt 撑着业务，就别继续卷 prompt 措辞了，往 Context Engineering 方向搬。工程化投入回报比那高一个数量级。