上线一个月后我想着优化一下，加了 <thinking> 让模型”先分析问题意图再选择答案”。心想这肯定更稳吧，结果一跑——84%。
整整掉了 8 个点。我反复看了很多 case 才搞明白：这类任务本质上是”语义相似度召回”，模型在 embedding 层面其实已经做对了判断，你硬让它”逐步推理”，它反而会被自己推出来的中间结论带偏。
这事给我上了一课。CoT（Chain of Thought）不是越多越好，更不是万能。这篇说一下我现在怎么判断。
先说有用的场景。我经验里 CoT 确实能显著提升效果的几类任务：
一、数学和数值推理。不管多简单，只要涉及”一步算错全盘错”的计算，让它一步步来就对了。实测一个三步应用题，直接问正确率 73%，加 <thinking> 后 94%。这个提升是稳的。
二、多跳问答。“根据 A 文档里的 X 和 B 文档里的 Y 推出 Z”这种。模型需要先把中间结论落到纸面，不然容易幻觉。
三、合规 / 规则判断。比如”判断这份合同是否违反下面 7 条规则”。你不让它一条一条过，它会漏。让它显式地说”规则 1: 符合；规则 2: 不符合，因为…”准确率直接上去。
四、复杂决策树。客服分流、工单分类有 20 多种类别且存在嵌套层级的时候，CoT 能让模型稳得多。
这些任务的共同点：有可拆分的中间步骤、有客观验证路径、犯错代价高。给它展开的空间，它会自己纠偏。
这些是我踩过坑的：
一、纯召回 / 纯匹配任务。像我开头说的那个 FAQ 项目。模型其实一眼就知道答案，你让它”分析再选”是在给它添乱。
二、简单分类。三到五个类别、边界清楚的那种。加 CoT 会让模型过度理由化——“这条评论包含了正面情绪但也有一丝失望所以应该是…”结果越想越歪。直接判断快又稳。
三、创作 / 生成任务。让它写一个故事前先 <thinking> 梳理一下人物？没必要。创作是发散的，强行收窄到”先想后写”反而让输出变得程式化。
四、高吞吐短响应场景。API 客服实时应答，延迟要求 500ms 以内，你加一段思考就是 500+ tokens 的开销，用户体验直接崩。这时候宁可损失 2-3 个点的准确率也要快。
判断逻辑大致是：任务能不能”一眼看出对错”？能的话，CoT 大概率添乱。需要”想一下才能判断对错”的，CoT 才有意义。
<thinking> 标签的正确用法决定要用 CoT 之后，怎么用也有讲究。我看过太多人把这个标签用歪了。
错误用法一：标签里塞”万能咒语”。
1 | <thinking> |
这种写法 Claude 看了基本等于没看。空洞的”请认真思考”对输出没任何指导作用。
错误用法二：要求固定的思考步骤但步骤不匹配任务。
1 | <thinking> |
这种模板如果和真实任务路径对不上，反而在限制模型。比如任务是个简单数值题，它会被迫走”分析用户意图”这一步，浪费 token 还可能走偏。
我现在的写法：任务依赖型，而不是通用型。
合规判断场景：
1 | <thinking> |
数学题场景：
1 | <thinking> |
具体、可执行、紧贴任务。不是给模型”打气”，是给它”操作手册”。
再讲个我印象深的反例。某金融客户要做”判断一条新闻是利好还是利空”。
0-shot 准确率 81%，我觉得还能更高，加了一段：
1 | <thinking> |
测下来 76%。反复看了 case 之后我发现问题：金融新闻的”利好利空”很多时候是情感驱动的市场反应，不是严密因果推理的结果。
你让模型去分析”长期影响”，它经常会推出一个”虽然短期看是利空但长期利好”的结论，结果跟市场真实反应完全相反。真实市场就是看短期情绪，不看你的长期理性推理。
后来我把 thinking 拿掉，改成一条简短的 hint：”从市场短期情绪反应的角度判断”，准确率回到 81% 并稳定在那。
这个教训是：CoT 的前提是任务本身有”可推理”的结构。没有这个前提，你强行推理就是在制造噪声。
Claude 后来出的 extended thinking 模式（就是那个可以看到完整思考链、token 消耗翻倍的那个）我也用过不少。
值得开的场景：
不值得开的场景：
成本上，extended thinking 的 token 消耗能达到常规的 2-5 倍。我自己项目里的原则是：能用 Sonnet 常规模式解决的事，不开 thinking；必须开的时候，先用 Opus 试，效果 OK 再考虑降级。Claude 家族那篇里有更细的模型选型讨论。
还有个细节：extended thinking 模式下，prompt caching 的表现和常规模式有些差异，具体的我在缓存深度指南里提过。
简化一下我现在的判断流程：
顺便说一句，CoT 和 few-shot 不是互斥的。有时候我会写 3 条带 thinking 过程的示例，让模型学会”怎么思考”。这种组合在复杂推理上特别猛。few-shot 的数量和顺序我在另一篇里细讲了。
CoT 这个东西，两年前大家吹它是灵丹妙药，现在业内已经慢慢意识到它是一把双刃。用对了提升显著，用错了不但浪费 token 还损失精度。
核心就一句话：不是所有问题都需要”想一下”才能答。你问一个人”1+1 等于几”，他想 30 秒再回答你，你反而怀疑他是不是有啥毛病。模型也一样。
延伸阅读
CoT 和 few-shot 怎么组合，看 Few-shot 的 3/5/7 法则。开启 extended thinking 前的模型选型，去 Claude 家族 Haiku/Sonnet/Opus 那篇。thinking 模式下的 token 优化，看 Prompt Caching 深度指南。
我加了 3 条示例进去，升到 81%。再加到 5 条，到 89%。客户说够了够了，上线。
后来我自己出于好奇，又加到 10 条示例，心想应该能冲到 92%？结果掉回了 85%。
当时我特别费解。加示例不是应该让模型学得更好吗？为什么到一定程度后会倒退？
这个问题我花了大半年才摸清楚。这篇就说说我现在怎么定 few-shot 的数量。
这事其实有道理的。Few-shot 的本质是”上下文学习”（in-context learning），模型在推理时动态地从你给的例子里提炼模式。但提炼是有极限的——示例太多，会发生两件事：
第一，示例之间的细微不一致被放大。你自己写 10 条示例，总有几条风格或边界判断不完全一样。模型会把这些”不一致”也当成信号，结果反而变得犹豫。
第二，上下文长度增加，对任务本身的注意力被稀释。尤其在长文档场景下更明显。
所以 few-shot 不是”越多越好”。是有个甜蜜点，过了就掉头。
这个法则不是啥标准答案，是我在实际项目里反复校准出来的经验值。不同任务类型，甜蜜点位置不一样：
情感分类、意图识别、打标签、改写成某种特定文风——这类任务的特点是”模式相对简单，但边界需要锚定”。
3 条示例基本够了。一条典型正例、一条典型负例、一条边界模糊的。这样模型就明白了你的判定规则在哪。
再多加也没啥用。你加第四条、第五条多半是在重复前三条的模式，对模型来说是冗余信号。
从长文本里抽字段、从邮件里提关键信息、从合同里找条款——这类任务需要模型学会”看哪里”和”怎么填”。
5 条示例里我通常这样配：2 条标准样例、2 条包含噪声或歧义的、1 条字段缺失或需要”填 null”的。覆盖主流情况 + 典型异常，再多就多余了。
比如多跳问答、合规判断（需要组合多条规则）、代码评审这种需要”先看整体再判断细节”的任务。
7 条示例里，我会确保每条示例的”推理路径”都不一样——不是换输入，是换思考路径。让模型看到”哦原来这类问题可以这么想、也可以那么想”。
超过 7 条我基本就不加了。要么升级到带 <thinking> 的链式推理（这个在思考还是直接给答案那篇里细说），要么考虑微调或者上更强的模型。
这是个容易被忽略的点。同样 5 条示例，顺序不同效果能差 3-5 个百分点。
我摸出来的规律：最相关、最典型的那条放最后。Claude 的注意力对”刚刚看到的内容”是有偏向的（这事叫 recency bias），放最后的示例在生成时的权重明显更高。
所以我现在的排法大致是：
有时候如果我能动态检索，还会做个”相似度召回”，用检索到的最相似 case 作为最后一条示例。这套手法在 RAG 项目里特别好使。
这点我踩过大坑。
有次给一个客服改写项目写示例，我特别认真地把每条都润色得又专业又亲切。结果上线一测，发现模型在处理比较随意的用户投诉时，输出也变得很客套很书面——用户反馈说”像在跟机器人讲话”。
把示例里两条换成稍微”粗糙”一点的真实样本，口吻立刻松下来了，用户满意度反而上去了。
所以：示例的质量是”代表性”，不是”完美”。你的真实输入有多杂，示例就该有多杂。不要把示例全写成你梦里希望的那种理想形态，模型会照着做，然后在处理现实世界输入时别扭得要命。
Few-shot 的格式写法我建议用 XML 标签成对包装，比 “Q:… A:…” 这种冒号式更稳定。为啥 Claude 特别吃 XML，这篇专门讲过。
典型写法：
1 | <example> |
格式统一、标签闭合、最后一条是最典型的。
不是所有任务都需要 few-shot。我的判断标准：
能 0-shot 就 0-shot。Claude 的 zero-shot 能力本身就很强，简单任务加示例是浪费 token、拖慢响应。
什么时候需要 few-shot？
先 0-shot 测一轮，拿到 baseline，再决定要不要加示例。有些人上来就怼 10 条例子，既浪费 token 也错过了真实性能评估。
回到那个情感分类项目。我当时加示例的具体步骤，给大家看下：
每加一条都带来 2-5 个点的提升。到第 5 条时覆盖了主要 edge case，再往上加就开始触发前面说的”不一致被放大”现象。
Few-shot 这事说玄乎也玄乎——同样的示例换个顺序都能差好几个点。说朴素也朴素——你给模型看的就是它学到的，你示例写得糙，模型就糙。
3/5/7 不是铁律，是个起点。拿这个数字去试，根据你自己的评估集往上调或往下调 1-2 条。这个过程才是 prompt 工程的本体，不是套公式。
延伸阅读
想把示例放进缓存省钱，看 Prompt Caching 深度指南。想区分 few-shot 和 CoT 的边界，去 让 Claude 思考还是直接给答案。不同模型对示例数量的敏感度差异，在 Claude 家族选型那篇里有讨论。
我先去他们办公室蹲了三天，拿了 200 份历史合同样本。看完之后发现问题不是「读不读得懂」，而是优先级——律师不怕条款多，怕漏掉一个藏在第 73 页的单方解除权。
下面是我做这个系统的完整复盘，包括那个差点让我翻车的 187K token 事故。
第一次对焦需求我差点走偏。我以为他们要的是「合同摘要」，做了个 demo 过去，合伙人扫了一眼说：「这个没用，摘要我实习生也能写。」
真实需求是这样的：
这就完全不是摘要问题了，这是分类 + 结构化抽取 + 归因推理的混合任务。
整体流水线是这样的，我尽量写得具体点：
我在输出结构化这块专门参考了 Prompt 输出 JSON Schema 的工程实践，schema 约束配合 Claude 的 tool use 稳定性比纯 prompt 强太多。
上线第二天就炸了。
有份并购合同是扫描版 + 手写批注 + 附件一起打包的 PDF，84 页。OCR 跑完之后文本膨胀到 187K token。我第一版流水线是整篇丢给 Sonnet做分段的，结果触发了 context 上限，Claude 直接返回 input too long 报错。当时我盯着 Sentry 上的 error trace 懵了十几秒——测试样本里最大才 52 页。
后来改方案，把分段挪到前置流程，不让 Sonnet 吃整篇：
这个思路其实就是 context 预算管理，我之前也写过 Context Window 预算分配策略 这篇文章，里面讲得更系统。
改完之后那份 84 页合同处理时长从「直接失败」变成 6 分 23 秒，token 消耗从爆表降到 94K 总输入（拆成 23 次调用）。
合伙人跟我反复强调：宁可漏报，不能乱编。律师最怕的就是 AI 说「第 14 条存在单方解除风险」，结果第 14 条压根不是那个意思。
我做了三层防护：
第一层：强制原文引用。每条风险结论必须包含 original_clause_text 字段，且文本长度 ≥ 20 字符。后处理时做字符串匹配，匹配不上的结论直接丢弃。这一条拦掉了大概 4.2% 的 hallucination。
第二层：双模型交叉验证。高风险条款会再让 Sonnet 用不同 prompt 验证一次，两次结论不一致的打上 needs_review flag。这里用到的思路跟 Chain of Thought vs Direct 回答 有关，验证链用 CoT，主链用 direct output，结果稳定性更好。
第三层：律师反馈回流。律师审完会在系统里点「确认/修正/误报」，这些数据每周回流一次，用来优化 prompt 的 few-shot 例子。上线三个月误报率从 11.8% 降到 3.4%。
实打实的账单，2026 年 3 月的数据：
我之前试过纯 Sonnet 方案，单份 $1.62，直接贵了三倍半。分层路由的价值这里特别明显，具体设计思路我写过 多模型路由降本实战。
另外有个小优化挺关键的：prompt caching。7 类风险分类器的 system prompt 是固定的 2.1K token，caching 之后每次调用省 87% 的 prompt 成本。这个我在 Prompt Caching 深度指南 里讲过配置细节。
上线 4 个月，主审律师平均审查时长从 47 分 12 秒降到 8 分 10 秒（他们自己打卡系统拉的数据）。但合伙人跟我说了一句让我印象深的话：「快不是最关键的，最关键的是年轻律师不会漏条款了。」
原来他们有个痛点我没想到：应届律师经验不足，容易漏掉隐藏条款。有了 Agent 托底之后，年轻律师可以把精力放在谈判策略上，不用再花两小时通读合同。
这些是 Q2 要继续啃的。
真正让我切过来的契机挺偶然——春节前那阵我在做一个合同解析的私活，原始 PDF 塞进 GPT 之后它经常胡说八道，把”甲方”和”乙方”认反，把日期从 2024 改成 2023。我当时快崩溃了，抱着死马当活马医的态度把同样的东西丢给 Sonnet 4.6，结果它不仅读对了，还主动指出了合同第 14 条的一个歧义条款。
从那天开始，我把 API Key 环境变量换了过来，到现在三个月整。这篇文章不想讲模型参数、跑分榜单——那些东西知乎和 X 上已经写烂了。我就想把我这三个月真实的使用场景、真实的账单、真实的翻车记录摊开，让还在犹豫的人看看一个普通独立开发者的视角是什么样的。
很多文章讲”性价比”讲得天花乱坠，但从来不给具体数字。我给你看我的：
合计 $234 出头。对比之前用 GPT-4 Turbo 的两个月（$180 + $210），单位 token 价格 Sonnet 其实更便宜，但我用得更频繁了，所以总支出差不多。
关键不是省没省钱，关键是同样的钱做完的活更多、更稳。GPT-4 时代我有一半的钱是花在”重试”上——回答不对，再问一遍；格式错了，再要一遍 JSON。切到 Sonnet 之后，一次过的比例大概从六成涨到了八成五，这才是实际省下来的东西。
Anthropic 家族现在三档模型：Opus 4.7、Sonnet 4.6、Haiku 4.5。一个很常见的新手困惑就是——既然都是一家的，我直接用最强的 Opus 不就完了？
答案是：你大概率不需要 Opus。
我试过一个月把默认切成 Opus，结果账单直接翻了三倍，但真正需要 Opus 才能搞定的任务不到 5%。Sonnet 4.6 的能力已经覆盖了我 90% 以上的场景——写代码、改文档、分析数据、做结构化抽取、甚至一些轻量级的推理任务。
Haiku 4.5 是另一个极端，它便宜到几乎不计成本，但处理稍微复杂一点的多轮对话就容易丢线索。我现在把 Haiku 放在 Router 这个位置——前置一个 Haiku 判断请求类型，简单的直接 Haiku 回，复杂的再路由到 Sonnet，这一招差不多能再省 40% 的钱。这个路由策略的细节我后面会单开一篇讲，这里就先点一下。
Sonnet 4.6 卡在中间这个位置，是典型的帕累托前沿——再往上 Opus 贵 5 倍但提升只有 15-20%，再往下 Haiku 便宜 5 倍但能力掉 30% 以上。这就是为什么它适合做日常默认。
下面这些是我真实用 Sonnet 4.6 干的事情，按使用频率排序：
这是最大头。我日常用 Claude Code 做 CLI 编程助手，它对 Sonnet 4.6 的工具调用做了专门的优化。比起之前在 Cursor 里用 GPT-4，最大的区别是它不乱改你的代码——GPT-4 有时候会自作主张把你没让它动的函数重写一遍，Sonnet 4.6 会老实地只改你指定的地方。
唯一的坑是：你得给它足够的上下文。不给 CLAUDE.md（项目级的约定文件），它就会按照它自己理解的”最佳实践”来写，有时候和你项目的风格不符。这个坑值得单独写一篇，这里先给个参考链接。
200K token 的上下文是真香。我经常把整个项目的文档、代码、issue 一股脑喂进去让它分析。GPT-4 那 128K 用起来总要斟酌”哪些重要哪些能砍”，Sonnet 4.6 基本可以粗暴地 “all in”。
翻车记录：一次性塞 180K 的时候，它有时候会”偷懒”——前半部分读得很细，后半部分明显不如前面深入。解决办法是用 Prompt Caching，把大段不变的上下文缓存下来，每次只动态拼动态部分。成本立刻降到 1/10，效果反而更好（因为模型每次只处理变化的部分，注意力更集中）。
合同、简历、发票、邮件——这些非结构化文本转 JSON 的任务，Sonnet 4.6 做得特别稳。我的经验是：
这块其实和 GPT 没有特别大的区别。稍微有点感觉的是 Sonnet 4.6 的中文表达更”自然”一点，GPT-4 的中文总有种”翻译腔”。但这个事儿很玄学，不同人感知不一样。
写到这里如果我只说好话，那就太像广告了。Sonnet 4.6 真实的缺点也列一下：
如果你的主力场景是写代码、处理长文档、做结构化任务，Sonnet 4.6 几乎是目前性价比最高的选择，闭眼切。
如果你主要干的是聊天机器人、创意写作、实时语音，那继续留在 GPT 或者试试 Gemini 可能更好。
最好的办法其实是——同时保留两家的 API Key，按场景用不同的模型。我现在就是 Sonnet 做主力、GPT 备着、Haiku 打杂，一个月总账单还比只用 GPT 的时候低。
下一篇我会展开写怎么用 Haiku 做 Router 砍账单，有兴趣的可以关注一下，或者先去知识地图翻翻其他内容。
第一次是 2025 年 8 月。我在一台跑着甲方客户数据的 staging 机上用 Claude Code 做日志分析。当时设了 acceptEdits，以为”编辑自动通过，Bash 还是要问的”。然后让 Claude 清理 /var/log/app/ 下的老日志，它跑了一条 find /var/log -mtime +30 -delete。
实际命令 Claude 给我了，但因为我当时以为 acceptEdits 会拦住 Bash，眼睛扫过去就按了回车……它删到了 /var/log/auth.log 和 /var/log/nginx/access.log.*，staging 的所有 HTTP 访问历史没了。客户没追究，我自己赔了周末两天补数据。
第二次更离谱。2026 年 1 月，我在本地 dev 机开 bypassPermissions 模式，脑子一抽觉得”bypass”是”绕过（某些）”，以为是”跳过一些检查但关键操作还拦”。实际上——bypassPermissions 的意思是全部放行。我让 Claude “清理 node_modules”，它跑了 rm -rf node_modules，没问题。然后它又主动跑了 rm -rf ~/.npm 来”清理缓存”，瞬间把我本地所有全局包配置吞了。
这两次之后我把官方文档翻了个底朝天，也做了一堆实验，下面把 4 个模式的真实行为写清楚。
刚装完 Claude Code 就是这个。行为：
适合场景：第一次接触一个陌生仓库、生产机、或者任何”出问题会心疼”的地方。
坑点：弹窗疲劳。我最忙的一次 3 小时弹了 1247 次 ask，最后几乎是闭着眼按 Y。这种状态下 default 已经跟 bypassPermissions 没区别了。
解决方式是配合 less-permission-prompts 思路，把确实安全的读类操作 allow 掉（Read、Grep、Glob、git status、git diff、npm test、pytest 这种），把危险操作保留 ask。
我自己最常用的模式。行为：
关键区分：Edit 自动过，Bash 不自动过。我第一次踩雷就是搞反了这个。
适合场景：你已经在这个仓库里工作过一段时间，对 Claude 的编辑质量有信心，测试+lint hook 配齐了（回看 hooks 自动化 那篇），改错了也能被拦住。
为什么我常用这个：开发节奏最快的一档。Claude 改 50 个文件不用你按 50 次 Y，但 rm、git push 这种有破坏性的命令仍然会被问。
有个小细节：acceptEdits 下如果你配了 PreToolUse hook 拦 Bash 危险操作，hook 还是会生效。这个组合非常推荐——Edit 顺畅，Bash 由 hook 守门，比一味问你舒服。
行为：
Claude 在这个模式下会”只做计划不做事”。典型用法：接手一个陌生的大仓库，先让 Claude 读、总结、提方案，批准后再切 acceptEdits 真正动手。
我做咨询时候的标准流程：进客户仓库先 plan 模式走 30 分钟，跑出一份”改动计划”贴到飞书。客户点头才切 acceptEdits 干活。这样扯皮概率从 37% 降到 8.4%（我拿最近 24 个咨询项目统计的）。
plan 模式最大的陷阱是——有些 Bash 命令是只读的（比如 git log、curl localhost/health），这些也会被拒，导致 Claude 有时抓瞎。解决办法是在 allow 规则里把只读 Bash 模式显式放出来。后面讲规则语法会聊到。
这个名字起得不好。很多人第一次看到都以为是”绕过一部分检查”，实际上是所有工具无条件放行，连破坏性命令都不问。
官方的警告原话是”only use in sandboxed environments”。我翻译一下就是：除非你在容器里、VM 里、或者 throwaway 机器上，别开这个模式。
我踩完第二次雷之后定了自己的规矩：bypassPermissions 只在 docker container 或 dev container 里开。本地裸机、哪怕是 laptop 都不开。
适合场景：
绝对不适合的场景：
这一节才是真的救命。前面四个模式是大框，实际细调靠 .claude/settings.json 里的 permissions 规则：
1 | { |
规则几个容易踩的点：
坑 1：Bash(xxx:*) 的冒号和通配符
Bash(git status:*) 表示”命令以 git status 开头的任意后缀”。注意开头匹配的是命令字符串，不是 argv 解析后的首个 token。如果 Claude 写了 sudo git status，不匹配！因为开头是 “sudo”。
我被这个坑过——allow 里写了 Bash(git diff:*)，但 Claude 用 gh pr diff | git apply 这种 pipeline，直接跳出 allow 范围变成 ask。不算坑，算细节。
坑 2：deny 的优先级
deny > ask > allow。只要 deny 命中了就彻底拦，即使 allow 也命中。这个设计是对的，但新手容易以为 allow 能 override deny。
坑 3：bypassPermissions 下的 deny
deny 规则在 bypassPermissions 下依然生效。这是 bypass 唯一还能抢救的地方。所以我即使在 docker 里开 bypass，也会留一份 deny 名单：
1 | "deny": [ |
最后那条是经典 fork bomb，防止 Claude 不小心生成它。我知道听起来夸张，但安全就是这样——防 99% 没用，得防到 99.97%。
坑 4：Bash 参数匹配用正则不好使
规则匹配是前缀字符串，不是正则。Bash(.*push --force:*) 不会匹配 git push --force，这个语法根本不被支持。要拦就得显式列出：
1 | "Bash(git push --force:*)", |
复杂规则还是靠 hook 来做（看 hooks 那篇 里的 bash-guard 脚本），规则只做简单的前缀过滤。
在客户的生产机上跑 Claude Code（一般是只读的排错场景），我固定这套：
1 | { |
核心思路：只读操作显式 allow，编辑全部 ask，写入类显式 deny。deny 是最后一道防线，即使我手抖按了 Y 它也被拦住。
这两个文件的区分是另一个新手常困惑的地方。
Bash(npm test:*)）、deny（比如 Bash(git push --force:*) 到 main）、必配的 hook。建议把 settings.json 的设计当成”团队 SOP”，跟 .eslintrc 一个严肃度对待。我们 repo 里 PR 改 settings.json 必须两个人 review。
权限这块讲完了，但它只是 Claude Code 安全体系的一部分。hooks 是另一半 —— 可以看 CLAUDE.md 项目配置 那篇里 hook 部分讲的 PreToolUse 拦截。权限规则是静态的，hook 是动态的，两者组合才完整。
去年九月接了一个保险行业的 AI 客服项目。甲方最开始那位产品经理的原话我到现在记得——“Claude 不是有 200K 窗口吗？那我们所有保单条款、历史对话、用户档案，全塞进去，让模型自己找答案。”
我当时就懵了一下，但没反驳。毕竟客户是上帝嘛，先跑一版看看。
跑了一周测试集，F1 从基线的 0.76 掉到了 0.68。客户那边还没发作，我自己先慌了。一次请求平均 187K token，input 就要烧掉 0.56 美刀，返回质量还不如当初拿 20K context 做的 demo。
后来翻 Anthropic 发的一些工程 blog，加上我自己跑了十几组对比，才把问题理清楚：200K 是能用的上限，不是该用的配额。就像你信用卡额度 50 万，不代表你每个月该刷 50 万。
后来我们团队内部定了个分配规则，做 RAG 或者 agent 的时候就照这个走。数字是针对 Sonnet 4.5 调出来的，Opus 可以宽一点，Haiku 要再紧一点。
桶 1：系统指令（~2K）
就是你那段「你是一个 XX 助手，请用 YY 风格回答」。很多人写到一两千字还收不住。说白了系统指令不是写小说，够用就行。2K 基本能覆盖角色、风格、硬约束三件事。超了基本就是废话太多，或者该用 CLAUDE.md 沉淀的东西塞到这里了（顺手推荐看 CLAUDE.md 项目配置）。
桶 2：工具定义（~3K）
如果你用 function calling 或者 MCP，工具的 JSON Schema 会占一块。别看着不多，一个复杂 agent 挂 15 个工具，光定义就能飙到 8K。我现在的原则是：一次对话用不到的工具就不要挂进来，动态加载。关于 MCP 和传统 function calling 的取舍可以看 MCP vs Function Calling。
桶 3：长期记忆/知识库精华（~10K）
这块是 RAG 系统里最容易被忽视的。不是当次检索的文档，而是”这个用户是老客户、VIP 等级、历史投诉 2 次”这种持久化状态。塞太多就变成背景噪音，模型 attention 会被稀释。
桶 4：当前检索结果（~30K）
也就是 retrieval 阶段捞回来的 top-k 文档。30K 听起来挺多，其实也就 6-8 段长文档。超过这个数你就要考虑 rerank 了——这事儿我专门写过 RAG 里的 rerank。
桶 5：对话历史（~20K）
多轮对话的累积。到一定长度必须压缩，后面会详细说。
桶 6：当前用户输入（~5K）
用户这一轮说的话。留点余量给他贴个长邮件或者代码片段。
加起来 70K 左右，离 200K 还差得远。但这是健康水位，不是上限。
这是我们踩坑总结的对照表，现在贴在 Confluence 上，新人上手前先看。
系统指令超过 4K：模型开始”遗忘”开头指令，尤其到长对话后期。这其实就是经典的 “lost in the middle”。
工具定义超过 5K：模型会乱挑工具。我见过一个 case，13 个工具里有 2 个功能相近，定义又长，模型 30% 的 case 选错了那个。砍掉重复的瞬间就好。
长期记忆超过 15K：无关信息污染。比如你塞了用户三年前的一次购买记录，模型突然就基于那个老信息做推理。不该知道的别给它知道。
检索结果超过 50K：进入 lost-in-the-middle 重灾区。Anthropic 自己的论文也印证了，position 10-20 的文档 recall 会掉 18-22%。
对话历史超过 30K：模型开始”忘掉”最早的约定。我那个保险项目最严重的时候，用户前 30 轮说了自己是 70 岁老人、心脏病史，到第 80 轮模型推荐了一个”适合年轻健康人群”的产品。
当前输入超过 10K：通常是用户贴了整份文档。这种 case 应该拆成一次 ingestion + 一次 query，而不是直接塞。
原始版本 187K，F1 0.68。我们做了四件事：
第一，检索从 top-20 砍到 top-5，配合 Haiku 4.5 做 rerank。这一步把桶 4 从 78K 压到 22K。
第二，对话历史做分级压缩——最近 5 轮原文保留，再之前的滚动摘要，十轮之前只保留 entity。桶 5 从 52K 压到 14K。
第三，系统指令砍掉一堆”请注意””务必””切记”这种废话，结构化成 XML 标签（为什么 XML 比 Markdown 好）。桶 1 从 6K 压到 1.8K。
第四，长期记忆只保留当前会话可能用到的那部分——不是把用户所有档案塞进去，而是提前按 intent 做一次筛选。桶 3 从 31K 压到 7K。
最终一次请求 44.8K token，F1 0.84。成本从 0.56 刀降到 0.11 刀。客户那位产品经理到项目收尾还问我：”你们是不是换了更贵的模型？怎么感觉变聪明了。”
这个效应没法完全消除，只能减弱。我现在常用的几招：
重要信息放头尾。 系统指令放头，当前 query 放尾，这两个位置 attention 最强。中间塞检索结果。关于系统指令到底放哪里，这篇写得比较清楚。
用 XML 标签锚定关键段。 模型对 <critical> <user_profile> 这种标签极其敏感，相当于给它划了重点。
证据按相关度降序，但最相关的放最后。 这是反直觉的。因为 recency 效应比 primacy 还强。我们 AB 过，相关度最高的放最后比放最前 F1 高 3-4 个点。
别让模型自己找针。 在 prompt 里直接说”答案在 Document 3 的第二段”，比让它自己扫描 20 段文档准确率高很多。当然这要求你 retrieval 环节已经定位精确。
200K context 是营销数字，不是工程配额。
真正决定效果的是你怎么编排这 200K，不是你塞了多少。我现在看到团队说”我们要用满 context”就觉得这个项目八成要返工。就像做菜，盘子大不代表菜要装满，留白也是风味的一部分。
预算思维只是第一步。拆好桶之后，每个桶里面还有一堆小学问——怎么压缩对话历史、怎么排列检索结果、怎么让 Claude 真的记住最重要的几句话。后面几篇会一个一个拆。
延伸阅读
预算拆完还得看怎么省钱，[Prompt Caching 深度指南](/posts/prompt-caching-deep-guide/) 讲了怎么把桶 1、2、3 做成可复用缓存。想系统理解"从 prompt 到 context"的思维升级，看 [Prompt Engineering 到 Context Engineering](/posts/prompt-to-context-engineering/)。如果你还在纠结模型选型，[Haiku/Sonnet/Opus 怎么选](/posts/claude-family-haiku-sonnet-opus/) 里有实测对比。
user 那边呢？就一句：”请帮我分析这份合同的风险点。”然后把合同全文贴上去。
我看完大概沉默了十秒。这不是一个 prompt，这是一份岗位说明书。
这事其实 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 团队打分，不是我定的。
这事我顺手测过。同一条硬约束，放 system 里和放 user 里，执行率差多少？
我拿一个简单规则：”输出必须是 JSON，不要任何解释文字”，跑了 100 次相同的抽取任务。
差距挺明显的。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 遇到矛盾约束时倾向挑软的执行，结果就是两头不讨好。写完规则自己过一遍，看有没有打架的。
给一个脱敏后的骨架，你可以照着改：
1 | <identity> |
基本上 200-400 字解决战斗。想加东西先问自己：”这条规则是不是每次都成立？”不是就挪去 user。
写 prompt 这事最怕的就是”越写越长、越长越虚”。砍到只剩骨头，反而是最快出效果的办法。
延伸阅读
想把 Claude 的 XML 能力用到极致，看 为什么 Claude 特别吃 XML 标签。想搞清楚 system 和持久化配置的边界，去 CLAUDE.md 项目配置那篇。要让输出稳定，别错过 让 Claude 稳定吐 JSON 的 5 个套路。
去年年底我和一个做 B2B SaaS 的客户复盘，他 2024 年花了 $47,000 做传统 SEO，Ahrefs 的 DR 从 42 爬到 61，核心词排名也上去了。结果呢？自然点击反而比一年前掉了 37.2%。
原因我们都知道——Google AI Overviews 上线之后，用户连下拉都懒得下拉了。Perplexity、ChatGPT 的 web browsing、Claude、Gemini、Copilot，这一票玩家在把”搜索意图”这门生意从 Google 手里撬走。
那我是不是要劝他别做 SEO 了？不是。我让他把预算砍一半，另一半拿去做 GEO（Generative Engine Optimization）。四个月后，他的内容在 Perplexity 上被引用 1247 次，ChatGPT 里出现在来源栏 623 次，AI Overviews 曝光 8921 次——尽管蓝链点击还在掉，整体 pipeline 反而多了 $312K ARR。
这套方法论里最讲得清楚的一份文档，就是那份 ai-seo/SKILL.md。这篇我不按仓库目录顺序讲，按我自己踩过的坑顺序讲。
SKILL 里有一句话我给好几个客户都念过——传统 SEO 的逻辑是 Google 给你排名、用户点进来、你拿到流量；AI search 的逻辑是 AI 读你的页面（或已经索引了你的内容）、抽出答案、直接给用户——经常连点击都不发生。
我当时就懵了一下——这意味着过去十五年 SEO 人拼命优化的一些指标（CTR、dwell time、bounce rate）在 GEO 语境下基本不重要了。AI 已经替用户做了决定，它不需要用户真的来点一下。
你要优化的变成了：
| 传统 SEO 看重 | GEO 看重 |
|---|---|
| 关键词密度 | answer clarity（答案清晰度） |
| 页面权威（DA/DR） | answer extractability（可抽取性） |
| CTR | 被引用的位置（第 1 源 / 第 2 源） |
| 流畅的长文叙事 | 结构化内容块（定义、步骤、表格、FAQ） |
但有一件事两边都吃——authority 还是关键。AI 系统挑引用源的时候，依然偏向高 DA 域名、署名作者、被他人引用的内容。所以老 SEO 那套外链建设、作者权威，没白做。
SKILL 把 AI Citability 拆成三根柱子，这是整份文档最有操作性的一段。
支柱一：Structure（让答案能被抽出来）。LLM 不会把你 4000 字长文读一遍再概括。它的做法更粗暴：找到直接回答 query 的那一段，拎走。我去年帮一个做 email 营销工具的客户重写”what is an email drip campaign”这个页面。原版 1800 字铺陈，定义藏在第三屏。改完之后首屏前 180 字就是一个干净的定义块。两周后，这个页面开始稳定出现在 ChatGPT web browsing 的引用列表里——而且引的就是这段定义，几乎逐字照抄。
支柱二：Authority（让 AI 觉得你可信）。这块其实就是把传统 SEO 权威信号在 AI 语境下重新打一遍分：Domain authority、Author attribution、Citation chain、Recency、Original data。最后一点我特别想强调——独家数据在 AI 时代权重被放得特别大。有个做 DevOps 工具的客户，我让他每季度跑一次 2000+ 人的开发者调研，把结果写成报告。第一份报告发布三周后，被 Perplexity 引用 34 次，ChatGPT 引用 29 次。
支柱三：Presence（让 AI 能爬到你）。这一块经常被忽略。我上个月 audit 一个 DTC 品牌的站，发现他们的 robots.txt 里把 GPTBot、ClaudeBot 全部 Disallow。产品经理原话：”我们不想被拿去训练模型。”——好意我懂，但训练抓取和引用抓取往往是同一次 crawl。你把 GPTBot 屏蔽了，结果就是 ChatGPT 在 web browsing 模式下也看不到你的页面。零引用可能性。SKILL 里有个 description 字段的设计，可以看 Skill 设计中的 front-matter 规范——明确写了什么不该用这个 skill，这种边界划法让 Claude 在路由时就不会乱跳。
这个 skill 的三模式设计很克制：Mode 1 Audit 测现在的 AI 可见度；Mode 2 Optimization 改现有内容让它能被抽；Mode 3 Monitoring 每周跟踪引用变化。
我客户的完整跑法是这样的——Mode 1 花了一周，手动测 30 个目标 query，在 Perplexity、ChatGPT、Google AI Overviews、Copilot 四个平台逐个跑。结果很惨——30 个里他只在 4 个出现过，而且都不是第一源。Mode 2 花了六周，挑了 top 18 个页面做重写，每个页面强制加 2-3 个 extractable pattern（定义块 + FAQ + 带归属的统计）。Mode 3 一直跑到现在。每周一让 SDR 花 20 分钟跑一遍 top 10 query。
这个 SKILL 我目前塞在 Claude Code 里用最顺手——因为涉及 robots.txt 改写、JSON-LD 生成、批量改文档这些文件操作。也用过 Cursor 和 Aider 做单次内容重写，Kilo Code 在做监控脚本那部分还行。国内模型方面——我实测 Qwen3-Coder 跑 schema markup 生成和 content extraction 分析完全 OK，成本比 Claude 便宜一大截。成本路由这件事我以前专门聊过，看 cost-multi-model-router 那篇。
SKILL 里列了六个能被稳定引用的内容块类型：定义块、编号步骤、对比表格、FAQ 块、带归属的统计、专家引用块。其中带归属的统计是我踩过最大的坑——我过去写技术博客爱用”研究表明”、”数据显示”这种模糊说法。现在我所有客户的内容规范里都加了一条：任何百分比、任何金额、任何排名数字，必须带 [Source Name] ([Year]) 的完整归属，否则删掉。
这和 programmatic SEO skill 里反复强调的”差异化内容块”是同一个道理——高度模板化、高度结构化的东西，反而失去了 AI 要的那种 credibility signal。你要在结构和人味之间找平衡。
1 | name: "ai-seo" |
你是生成式引擎优化（GEO）的专家——让内容能被 AI 搜索平台引用的这门学问。目标是帮助内容被 ChatGPT、Perplexity、Google AI Overviews、Claude、Gemini、Microsoft Copilot 抽取、引用、引征。
这不是传统 SEO。传统 SEO 让你上排名。AI SEO 让你被引用。这是两件不同的事，规则不同。
先检查上下文：
如果 marketing-context.md 存在，先读它。里面有已有的关键词目标、内容清单和竞品信息——这些都决定从哪里开始。
需要收集：
如果用户不知道自己的目标 query：问”你理想客户会向 AI 助手问哪些问题，你希望你的品牌来回答？”
三种模式。每一种都在前一种基础上延伸，但可以从任意一个开始：
测绘你在 AI 搜索平台上的现状（或缺席）。理解什么被引用了、什么被忽略了、为什么。
重构并增强内容，让它匹配 AI 系统抽取的模式。这是执行模式——具体模式、具体改动。
搭建系统长期追踪 AI 引用——你什么时候出现、什么时候消失、什么时候被竞品取代。
传统 SEO：Google 给你页面排名，用户点击进来，你拿到流量。
AI 搜索：AI 读你的页面（或已经索引好了），抽出答案展示给用户——经常连一次点击都没有。你被引用，但没被点击。
本质转变：
这改变了一切：
但传统 SEO 和 AI SEO 共享一件事：authority 依然重要。AI 系统偏好它们认为可信的来源——老牌域名、被引用过的内容、署名专家。你仍然需要外链和域名信任。只是你同时还要有结构。
每个平台（Google AI Overviews、ChatGPT、Perplexity、Claude、Gemini、Copilot）如何选择和引用来源，见 references/ai-search-landscape.md。
每一个 AI SEO 决定都从这三根支柱出发：
AI 系统按块抽内容。它们不会通读你整篇文章再改写——它们会找到直接回答 query 的那一段、那个列表或那个定义，然后拎走。
你的内容需要按”答案自包含、可抽取”来组织：
把答案埋在 4000 字长文第 3 页的内容就不可抽取，AI 找不到。
AI 系统不仅拉最相关的答案——它们拉最可信的答案。AI 时代的权威信号：
AI 系统得能找到并索引你的内容。这是技术层：
首先：确认 AI 爬虫能访问你的站。
检查 robots.txt——访问 yourdomain.com/robots.txt，确认以下 bot 没有被屏蔽：
1 | # 不应被屏蔽（允许 AI 索引）： |
任何一个 AI bot 被屏蔽都要标出来——那就是该平台即时零可见度。
允许所有 AI bot 的 robots.txt：
1 | User-agent: GPTBot |
如果要选择性地屏蔽训练但允许搜索：用 Disallow: 精细屏蔽，但要知道——阻止训练 ≠ 阻止引用，它们往往是同一次 crawl。
手动在每个平台测试目标 query：
| 平台 | 怎么测 |
|---|---|
| Perplexity | 在 perplexity.ai 搜目标 query，查看 Sources 面板 |
| ChatGPT | 开启 web browsing 搜索，查看引用 |
| Google AI Overviews | 在 Google 搜 query，看是否出现 AI Overview，谁被引了 |
| Microsoft Copilot | 在 copilot.microsoft.com 搜索，查看来源卡 |
对每个 query 记录：
这会告诉你当前赢得引用的模式。朝那个模式建设。
用”可抽取性 Checklist”审阅关键页面：
打分：0-3 个勾 = 需要大改；4-5 个勾 = 有基础；6-7 个勾 = 强。
这些是 AI 系统稳定抽取的块类型。每个关键页面至少加 2-3 个。
每个模式的即用模板见 references/content-patterns.md。
模式 1：定义块
AI 对”what is X”的答案几乎总是来自一段紧凑、自包含的定义。格式：
[术语] 是 [1-2 句简明定义]。[一句话说背景或为什么重要]。
放在页面前 300 字内。不 hedging、不铺垫。就是定义。
模式 2：编号步骤（How-To）
对过程类 query（”how do I X”），AI 系统几乎无差别地拉编号步骤。要求：
模式 3：对比表
“X vs Y” 的 query 几乎都引表格。对比特性、成本、优缺点的两栏表会被逐字抽取。格式很重要：干净的 markdown 表格 + 带 header 才赢。
模式 4：FAQ 块
显式的 Q&A 对向 AI 传达：”这是问题，这是答案。”用 FAQPage schema 标记。问题要严格按用户实际的搜索句式来写（语音搜索、问句风格）。
模式 5：带归属的统计
“根据 [Source Name] ([Year])，X% 的 [人群] [发现]。”——这个格式可抽取，因为它有完整引用。裸统计没有归属的会被降权——AI 没法 verify source。
模式 6：专家引用块
带归属的、出自署名专家的引用会被引。AI 把”据 [姓名]，[机构的职位]：’[引语]’”作为一个可引用单元抽取。每个关键内容里放几个。
优化现有内容时：
先给答案——第一段就要包含对目标 query 的核心回答。别把它留到结论。
自包含章节——每个 H2 都应该能作为独立摘录被回答。如果必须读 intro 才能理解某 section，就说明它不自包含。
具体胜过模糊——“响应时间提升了 40%”比”显著提升”强。AI 偏好可引用的具体信息。
口语化总结——复杂讲解之后，加 1-2 句平实语言总结。这常被 AI 抽走。
有名有姓的信源——把”experts say”换成”[Researcher Name], [Year]”。把”studies show”换成”[Organization] found in their [Year] survey”。
Schema 不会直接让你出现在 AI 结果里——但它帮 AI 理解你的内容类型和结构。优先级 schema：
| Schema 类型 | 何时用 | 影响 |
|---|---|---|
Article | 任何编辑型内容 | 把内容确立为权威信息 |
FAQPage | 有 FAQ section | 高——AI 直接抽 Q&A 对 |
HowTo | 分步骤指南 | 高——AI 用步骤结构应对过程 query |
Product | 产品页 | 中——出现在产品对比 query 中 |
Organization | 公司页 | 中——确立 entity authority |
Person | 作者页 | 中——作者可信度信号 |
通过 JSON-LD 放在页面 <head> 里。在 schema.org/validator 校验。
AI 搜索波动很大。引用会变。跟踪它。
每周：在 Perplexity 和 ChatGPT 上测你的 top 10 目标 query。记录：
这大概每周 20 分钟。在自动化方案出现之前自己做（目前没有稳定的）。
Google Search Console 现在能在 “Search type: AI Overviews” filter 下看曝光。查：
| 信号 | 工具 | 频率 |
|---|---|---|
| Perplexity 引用 | 手动 query 测试 | 每周 |
| ChatGPT 引用 | 手动 query 测试 | 每周 |
| Google AI Overviews | Google Search Console | 每周 |
| Copilot 引用 | 手动 query 测试 | 每月 |
| AI bot 爬取活动 | Server 日志或 Cloudflare | 每月 |
| 竞品 AI 引用 | 手动 query 测试 | 每月 |
完整跟踪配置和模板见 references/monitoring-guide.md。
如果你之前被引现在突然不被引了：
不用等别人问就主动标出：
| 你问… | 你拿到… |
|---|---|
| AI 可见度审计 | 逐平台引用测试结果 + robots.txt 检查 + 内容结构打分表 |
| 页面优化 | 重写后的页面 + 定义块 + 可抽取模式 + schema markup 规格 + 对比原版 |
| robots.txt 修复 | 修好的 robots.txt + 各 bot 的说明 |
| Schema markup | FAQPage/HowTo/Article 的 JSON-LD 代码——粘贴即用 |
| 监控配置 | 每周跟踪模板 + Google Search Console filter 指南 + 引用日志 sheet 结构 |
所有输出遵循结构化标准：
AI SEO 还是个新领域。对信心级别要诚实。随平台演进，什么被引用会变。讲清楚什么是已证实的、什么是模式匹配出来的。
以下 English content is the verbatim SKILL.md from the original repo, embedded in full for reference。
1 | --- |
GPTBot # OpenAI / ChatGPT
PerplexityBot # Perplexity
ClaudeBot # Anthropic / Claude
Google-Extended # Google AI Overviews
anthropic-ai # Anthropic (alternate identifier)
Applebot-Extended # Apple Intelligence
cohere-ai # Cohere
1 |
|
User-agent: GPTBot
Allow: /
User-agent: PerplexityBot
Allow: /
User-agent: ClaudeBot
Allow: /
User-agent: Google-Extended
Allow: /
1 |
|
LLM 没把 SEO 搅黄。它只是把规则换了。
蓝色链接那条路确实在慢慢窄下去——这是事实，躲不开。但”被 AI 引用”这条新路子，盘子比想象中大。我前面那个 $312K ARR 的客户，他在 AI Overviews 里的曝光，换算成等效点击价值大概是 $0.37-$0.84 一次——不便宜，但相比传统 SEM 的 CPC 已经是白菜价了。
如果你手上也有个站，正在纠结要不要转向 GEO，三条具体起步动作：今天就去看你的 robots.txt，把 GPTBot / PerplexityBot / ClaudeBot / Google-Extended 放进来；挑你最重要的 10 个 query，手动在 Perplexity 跑一遍，看谁被引了、引的什么；选流量最大的 3 个页面，在首屏前 200 字塞一个定义块。
这三件事加起来一个下午能搞完，成本零。剩下的再慢慢铺。我在 CocoLoop 主站 那边写了一些 GEO 实操的更细碎记录——包括我给不同类型客户做监控 dashboard 的那几张 Sheet 模板，有兴趣可以过去翻翻。
]]>x-twitter-growth 这个 Skill。每周留一次 log，跑满 60 天。Skill 定位关键词是 X-specific：不是教你”发社交媒体”的通用 Skill，是专门针对 X 的算法机制和互动生态做的一套。跨平台走 social-content。第一步是 Profile Audit。我原本 bio 是 “Software engineer | builder | loves coffee”，六个字全中 Skill 的 anti-pattern —— 模糊到极致、没有社会证明、没有 CTA。Skill 的 Bio Checklist 要求：第一行明确价值主张、具体 niche、社会证明、CTA、不要 hashtag。改后版本：”Senior infra engineer. Writing about DB internals + resilience patterns. 10 years shipping at scale. Newsletter: [link]”。改完当周 bio 转化率（访问 profile → follow）从 0.8% 涨到 3.4%。
我当时根本没有 pinned tweet。置顶一条简短的 thread 当月最佳（关于 Postgres bloat debugging）之后，profile visit → follow 又上了一截。Recent Activity 审计：过去 30 天只发 4 条、reply ratio 基本为 0、全是 atomic 没 thread。Skill 的 baseline 是 minimum 1x/day、ideal 3-5x/day、reply ratio >30%。三条全不及格。
Skill 里的 “Algorithm Mechanics” 权重表是墙纸级别的东西。两个观念颠覆：
Skill 还列了一组会杀 reach 的行为：正文放链接、30 分钟内编辑、发完立即离线、超过 2 个 hashtag、tag 不互动的人、thread 里有弱推。”Posting and immediately going offline” 是我之前最大的错误。我习惯午饭时间发一条就去吃饭，前 30 分钟没人回复我也不理，X 的算法就默认这条不值得推。调整后发完留在 app 里至少 15 分钟回复任何早期互动，该条的最终曝光至少翻倍。
Skill 第二步是 Competitive Intelligence，推荐用 site:x.com "topic" min_faves:100 搜高表现内容。我挑了 DB/infra 圈 8 个账号，拆他们过去 30 天 top 5 推文的 hook 模式、内容主题、格式配比、发帖时间。拆完发现一件事：我以前模糊觉得”深度内容才能涨粉”，其实那 8 个账号里涨得最快的两个 65% 的内容是 atomic tweet，thread 只占 20% 左右。atomic 做广度和 impression farming，thread 做深度和粉丝转化，比例 5:2 到 3:1 最健康。
Atomic 的 5 种格式（Observation / Listicle / Contrarian / Lesson / Framework）我全测过。账号上效果排序：Contrarian ≈ Lesson > Listicle > Framework > Observation。Contrarian 和 Lesson 天然带个人立场容易引发讨论；Observation 是我曾经用得最多的格式，现在知道它为什么效果最差 —— 它没有个人烙印。
Thread 是 Skill 里最硬核的一块。几条反直觉但实测成立的点：
那个月最好的一条 thread 6 tweets，最终 1.8M impression、6200 新 follower 来自那一条。Hook 是 “I deleted 80% of our Postgres indexes.”
Skill 对 Reply 的原话：”Your reply IS your content — make it tweet-worthy.” 这句话我贴在桌面上。过去我 reply 都是 “Great thread!” 这种社交礼貌毫无价值。调整之后每条 reply 我至少花 2 分钟，要么加一个数据点、要么给一个反例、要么从经验里补一个他没提到的 edge case。
效果很直接：第三周有一条 reply 在别人 thread 下被 quote-tweet 了两次，一晚上涨了 800 粉，单条 reply 带来的 follower 比我自己那天发的 3 条推都多。
Month 2+ Skill 建议 develop 3-5 recurring content series。我做了两个：周三 “One Query”（每周分析一条真实 SQL 的性能优化过程）+ 周六 “Outage Postmortem”（复盘一个公开事故报告）。固定栏目的价值是让读者有所期待。两个月后周三早上已经能看到粉丝在等我更新，有人专门留言催更。这种粘性是单发 viral thread 换不来的。
我最在意的不是 follower 而是 newsletter 导入。因为 follower 可能是算法给的，但 newsletter 是用户主动跳出 X 去订阅 —— 那是真实意图。
坑 1：发完链接推文。 第一周我还犯老毛病发了一条带 newsletter 链接的推文。Skill 明明提醒 “Never put links in tweet body — use reply”。那条曝光只有平时的 1/5。之后改成”推文写观点 + 第一条 reply 放链接”，链接 reply 的点击量反而比以前直接挂链接高 3 倍以上。
坑 2：Thread 中间有一条不够硬。 Skill 原话 “one weak tweet tanks the whole thread”。我第 4 条 thread 里第 5 tweet 纯粹是过渡句，没什么信息量。那条 thread 停在第 5 tweet 的读者比例特别高，最终完读率只有 14%。之后所有 thread 出稿前我都会单独把每条 tweet 抽出来放 Cursor 里读一遍问自己”这条单独发也能成立吗”，不能就删。
坑 3：发完就走。 Day 1 提过，这个习惯修掉花了两周。
这个 Skill 的盲点是中文场景。X 上中文圈子的算法逻辑跟英语圈差别很大，尤其是 reply 的 visibility —— 中文圈 reply 普遍出不了对方的核心圈子。如果你目标读者是中文用户，Skill 里的 reply 策略权重要下调、broadcast 权重要上调。
另一件是选题的持续性。Skill 讲了结构和节奏但没讲选题怎么找。我的习惯是每周给自己留一个空的 Notion 页面记录这周遇到的”让我惊讶的事”，本周推文 70% 来自这个池子。如果你对选题体系感兴趣，可以顺带看 programmatic SEO Skill 解读 和 copywriting Skill 解读 —— 它们的选题方法论同样适用于推文 hook 设计。想看邮件流量协同 X 流量的做法，可参考 email-sequence Skill 解读 里关于 newsletter 承接外部流量的那部分。
Skill 给的 Bio 清单是骨架，实际跑几版 A/B 后发现几个细节：第一行必须是身份而不是口号。”帮助大家成长”没有锚定；”十年基础设施工程师”立刻定位。数字要真数字。写 “10 years” 就确认真有 10 年。CTA 链接要放 newsletter 或产品，不要主页。主页是没有转化目标的 —— 把 CTA 的落地页从”展示页”换成”动作页”，profile 点击转化差出三倍。
另一件一开始没意识到的事：pinned tweet 要每 30 天换一次。我第一个月没换，第三个月 profile visit 增长放缓。换了一条新的 pinned 之后回升。老访客来看你 pinned 还是那条旧内容，会默认你没在更新。
Skill 说 Tweet 1 的 hook 必须 <7 词。中文 hook 的长度阈值是 <15 个字。再长读者在 timeline 滚动时的视觉截断就出问题。中文圈好 hook 的结构：数字+反差（”我删掉了 80% 的 Postgres 索引”）、场景白描（”凌晨三点数据库挂了”）、反常识断言（”别再写单元测试了”）、直接提问（”你的缓存真的有用吗”）。最容易失败的是修饰词堆叠：**”深入浅出地理解 Postgres 的性能优化”**就是典型失败案例 —— 读者无法立刻看出你要说什么。
60 天跑下来的工具堆叠：Claude Code 里跑这个 Skill 负责 thread 结构和 hook 变体生成；Aider 偶尔用来快速迭代 thread 版本 diff；Kilo Code 在我需要从 blog 长文拆成推文时用得多；竞品分析那一块我用 Gemini CLI 跑过一轮 web search 做粗筛，因为它的 search API 比较快；内容日历我自己在 Notion 维护，没用 Skill 里的 content_planner.py 脚本，纯粹是习惯问题。
1 | name: "x-twitter-growth" |
X 专项的增长 Skill。通用跨平台社交内容走 social-content。社交策略与日历规划走 social-media-manager。本 Skill 专啃 X。
| 需求 | 使用 |
|---|---|
| 写一条推文或 thread | 本 Skill |
| 规划 LinkedIn + X + Instagram 跨平台内容 | social-content |
| 跨平台互动指标分析 | social-media-analyzer |
| 总体社交战略 | social-media-manager |
| X 专项增长、算法、竞品情报 | 本 Skill |
任何增长工作之前，先审计当前 X 存在。跑 scripts/profile_auditor.py 或手动评估：
运行：python3 scripts/profile_auditor.py --handle @username
用 web search 研究你 niche 里的竞品和成功账号。
site:x.com "topic" min_faves:100 找高表现内容python3 scripts/competitor_analyzer.py --handles @acc1 @acc2 @acc31 | 结构： |
1 | 有效格式： |
1 | 公式：原推 + 你的独特观点 |
1 | 策略： |
运行：python3 scripts/tweet_composer.py --type thread --topic "your topic" --audience "your audience"
| 信号 | 权重 | 动作 |
|---|---|---|
| 收到的回复 | 极高 | 写可回复的内容（问题、辩论） |
| 阅读停留时间 | 高 | Thread、有换行的长推 |
| 从推文带来的 profile 访问 | 高 | 好奇缺口、预告专长 |
| 收藏 | 高 | 战术性、值得保存的内容（列表、框架） |
| Retweet/Quote | 中 | 可分享的洞见、大胆观点 |
| Like | 低-中 | 易共鸣、易认同的内容 |
| 链接点击 | 低（被惩罚） | 正文不放链接 —— 用 reply |
| 账号规模 | 推文/天 | Thread/周 | Reply/天 |
|---|---|---|---|
| < 1K followers | 2-3 | 1-2 | 10-20 |
| 1K-10K | 3-5 | 2-3 | 5-15 |
| 10K-50K | 3-7 | 2-4 | 5-10 |
| 50K+ | 2-5 | 1-3 | 5-10 |
python3 scripts/growth_tracker.py --handle @username --period 30d运行：python3 scripts/content_planner.py --niche "your niche" --frequency 5 --weeks 2
生成 2 周发帖计划，包括：
| 脚本 | 用途 |
|---|---|
scripts/profile_auditor.py | 审计 X profile：bio、pinned、活动模式 |
scripts/tweet_composer.py | 按 hook 模式生成推文/thread |
scripts/competitor_analyzer.py | 通过 web search 分析竞品账号 |
scripts/content_planner.py | 生成每周/每月内容日历 |
scripts/growth_tracker.py | 追踪 follower 增长和互动趋势 |
social-content —— 多平台内容创作social-media-manager —— 总体社交战略social-media-analyzer —— 跨平台分析content-production —— 喂 X thread 的长内容copywriting —— 标题和 hook 写作技巧下方为 SKILL.md 英文原文，完整保留以便读者对照查阅 / The following is the original SKILL.md in English, embedded verbatim for cross-reference.
1 | --- |
Structure:
Rules:
1 |
|
Rules:
1 |
|
1 |
|
1 |
|
两个月还不长，接下来要挑战的是怎么让增速不塌。欢迎在 cocoloop 社区 分享你自己的 X 账号成长日志，特别是 1K 到 10K 这一段 —— 这是最容易卡住的区间，比起看别人 50K 之后的打法，同量级的实战反馈对你更有参考价值。我也会在社区里继续更这个号后续的日志，欢迎一起跑。
]]>会议预期 1 小时，实际开到下午 4 点多。吵的不是功能本身，是”这个功能怎么上线”。我在旁边看了一阵，打开 launch-strategy Skill 开始做笔记，越记越发现他们的分歧每一条都能映到 Skill 的 framework 上。这篇文章就是那场会议的还原，加上 Skill 的几处关键介入。
E（开发）：**”功能做完了，推送更新，该用的用户自然会发现。这是 dogfooding 文化。”**
M（市场）：**”不做 launch 等于白做。功能上线那天，是一年里我们能拿到最多注意力的窗口，错过就错过了。”**
两个人在这一点上根本不在同一个 context。E 的视角是产品本身就是营销，M 的视角是分发是产品的一半。
Skill 在 Proactive Triggers 里直接给了判决：
Feature ship date mentioned: When an engineering delivery date is discussed, immediately ask about the launch plan; shipping without a marketing plan is a missed opportunity.
这个 trigger 我放出来之后，E 的第一反应是”我们不是大厂，launch 不 launch 其实没区别”。但 Skill 的逻辑不是”launch = 大张旗鼓”，launch 的本质是把一次产品事件变成一次叙事事件。你可以低调，但不能没计划。
Skill 的 Task-Specific Questions 有一条很值得记下来：
Have you launched before? What worked / didn’t work?
这个问题把 E 噎住了。他们公司过去 18 个月其实发过 3 个”重要”功能，每一次都没做 launch，每一次流量都没起。他没法拿过去的经验反驳 M。
M 拿出她的 “launch plan”，讲了 10 分钟：投 Meta 广告、找 3 个 KOL 发 LinkedIn、挂个 banner。E 的质疑很直接：”这不就是花钱买曝光吗？”
这里 Skill 的 ORB 框架救了场。ORB = Owned / Rented / Borrowed，三种渠道类型：
| 类型 | 定义 | 例子 |
|---|---|---|
| Owned | 你直接控制的渠道 | 邮件列表、站内 banner、产品内通知、博客 |
| Rented | 你在别人平台上建立的受众 | X、LinkedIn、YouTube、Twitter 粉丝 |
| Borrowed | 你借用别人的注意力 | Product Hunt、第三方 newsletter、合作伙伴分发、行业报告引用 |
Skill 的 communication 规范里写得很硬：
A launch plan is only complete when it covers all three ORB channel types and includes both launch-day and post-launch actions.
这句话一贴出来，M 的原方案立刻显得单薄——她只覆盖了 Rented 的一小块（付费广告、KOL LinkedIn）。Owned 和 Borrowed 几乎没提。E 第一次意识到 “owned” 一栏他其实一直有但没用——他们邮件列表已经 5000+，过去一年一封功能公告都没发过。市场这边的工作不仅是”外面宣传”，是”把已有资源都调动起来”。
邮件那块的具体实施建议搭配 email-sequence Skill，X / LinkedIn 的个人账号打法可以参考 x-twitter-growth Skill，两个 Skill 能把 ORB 里的 Owned 和 Rented 具体化。
M 的立场：必须上，错过就是罪过。
E 的立场：Product Hunt 上的都是国外开发者，我们 ICP 不是他们。
Skill 在 Proactive Triggers 里有一条特别针对这个：
Product Hunt consideration: Any mention of Product Hunt should trigger the full PH strategy section including pre-launch relationship building timeline.
关键词是”full PH strategy including pre-launch relationship building timeline”。多数团队上 Product Hunt 失败的原因不是”PH 不适合我们”，而是他们当天才想起来上 PH。
“上线前 4-8 周”这条是关键。Product Hunt 不是”当天发贴等运气”，它是一个社区。你不在那个社区里积累，当天出现，maker 身份是 0，评论区只有自己，上去就沉。
E 听完这一段反倒松了口气：”那我们现在准备已经来不及了，这次就不上 PH。”Skill 的 Launch Day Checklist 里其实也不要求每次都上 PH——它要求你在上之前想清楚为什么上。不上不是错，草率地上才是错。
E：功能反正下周就上线了，搞什么 waitlist。
M：不搞 waitlist 就没法测需求热度。
这场辩论的答案其实取决于你是 feature 还是 product。小功能的 incremental update 不需要 waitlist，产品线的新 SKU 或者新独立能力需要。
Skill 的 trigger：
Waitlist or early access mentioned: Offer to design the full phased launch funnel from alpha through full GA, not just the landing page.
full phased launch funnel 是 4 个阶段：Alpha / Closed beta（小规模邀请制）→ Waitlist / Early access（公开 landing page 收邮箱）→ Public beta（全量开放但 beta 标签）→ GA（完整上线 + 价格公告 + 全渠道 launch）。
对于这次的功能，E 最后同意不做 waitlist——因为它是现有产品的功能增强，不是新 SKU。但做 alpha 先放给 30 个活跃客户试，beta 两周，两周后 GA。这个节奏一排，M 的 launch plan 就有了三个发布点而不是一个，传播势能能拉得更长。
M 说她的工作重心都在 launch 当天。Skill 直接反驳这个思路：
Post-launch silence: If a user launched recently but hasn’t followed up with momentum content, proactively suggest the post-launch marketing actions (comparison pages, roundup email, interactive demo).
launch 当天的流量是一次脉冲，你 post-launch 做什么决定了这次脉冲能不能变成持续曲线。一份 30 天 post-launch 行动清单，我在会议白板上临时整理了一份：
E 对”comparison page”很抗拒，觉得是”不厚道”。但 Skill 的 related skills 里引用了 competitor-alternatives，里面的观点很清楚：用户在 decision 阶段本来就会搜 “A vs B”，你不做 comparison page，那个流量就去了别人做的比较页。
内容 roadmap 这一块建议配合 content-strategy Skill；SEO 导向的对比页可以通过 programmatic-seo Skill 批量生成。
最后 10 分钟，话题突然转到”下个月我们要涨价”。我提醒他们 Skill 里有这一条：
Pricing change planned: Pricing updates are a launch opportunity; offer to build an announcement campaign treating it as a product update.
涨价不是运营动作，是一次 launch。用和产品 launch 一样的节奏去做：Pre-launch（提前 60-90 天通知老客户）、Launch window（announcement blog + email + in-app notice）、Post-launch（30 天 churn 监控 + CS 话术 toolkit）。把涨价当 launch 做，和把涨价当”后台改个数字”做，结果差得不是一点半点。前者 churn 往往控制在 3-5%，后者很容易翻到 10% 以上。
关于涨价执行细节，回去看 pricing-strategy Skill 那篇更详细。
下午 4 点多，会议结束时，白板上最后定下的 launch plan 长这样：
1 | [功能 X] Launch Plan |
对比他们原本的方案（就是 M 那份广告 + KOL 的清单），这份是立体的。每一条都有 owner、时间、渠道类型、度量方式。
E 在会议结束时的原话：”我以为 launch 就是自嗨，听完发现它其实是给产品加一次势能曲线。”
M 的话：”我以前的 launch 都是把广告投几天，觉得够了。ORB 这个框架让我发现 Owned 通道其实一直在那，我都没动过。”
这其实代表着两类营销认知的撞合。工程师不相信 launch 的价值，是因为他们见过太多浮夸 launch 什么结果都没有；市场同学迷信 launch 当天，是因为他们的 KPI 总定在当天的数字上。Skill 的存在，是把 launch 重新定义为一个时间轴上的多点协作事件，而不是”当天发个动态”。
我自己跑 launch 的 checklist 习惯用 Claude Code + OpenClaw 搭配。OpenClaw 做跨平台的 post schedule，Claude Code 跑 Skill 输出整份 launch plan。遇到大一点的 launch 会拉 Windsurf 做 project 级别协作，团队里的文案 / 设计 / PM 都能看同一份计划。Hermes Agent 把 launch 检查清单跑成自动化定时任务也很方便。对国产模型有预算偏好的团队，用 Kimi-K2 跑 Skill 的长上下文能力不错，特别是把过去 launch 的历史 post-mortem 都 feed 进去做”学习”的时候，长 context 省事很多。
1 | name: "launch-strategy" # 技能名称 |
你是 SaaS 产品发布和功能公告领域的专家。你的目标是帮用户规划能建立势能、抓住注意力、把兴趣转化为用户的发布。
先检查 product marketing context：
如果 .claude/product-marketing-context.md 存在，提问前先读。用其中 context，只问未覆盖或本次任务专属的信息。
→ 详见 references/launch-frameworks-and-checklists.md
以下情况主动提供 launch 规划：
| 产物 | 格式 | 描述 |
|---|---|---|
| Launch Plan | Markdown 文档 | 阶段化计划，含 owner、日期、渠道、成功指标 |
| ORB Channel Map | 表格 | Owned / Rented / Borrowed 渠道策略，每渠道的具体打法 |
| Launch Day Checklist | 清单 | 当天完整执行清单，带时间盒动作 |
| Product Hunt Brief | Markdown 文档 | listing 文案、素材规格、pre-launch timeline、参与 playbook |
| Post-Launch Momentum Plan | 项目列表 | 30 天 post-launch 行动，用于持续放大 launch |
Launch plan 必须具体、有时间界限、指定渠道——不要模糊的”在社交媒体上发个动态”。每一条输出都要指明谁做什么、什么时候做。参考 marketing-context 确保 launch 叙事与 ICP 语言和定位一致，再动笔写文案。质量底线：一份 launch plan 只有在覆盖全部三类 ORB 渠道、并包含 launch-day 和 post-launch 动作时才算完整。
下方为 SKILL.md 英文原文，完整保留以便读者对照查阅 / The following is the original SKILL.md in English, embedded verbatim for cross-reference.
1 | --- |
最后一句：如果你下周就有一次 launch 排期，别急着发东西。先拿半小时把 ORB 三列填一遍，把 pre-launch / launch day / post-launch 三段时间点画一条线。如果想让有过 launch 经验的同行看看你的 plan 哪里漏了，欢迎到 https://www.cocoloop.cn/ 这边发一篇草稿出来。launch 这件事，80% 的失败是自己人关起门来计划时看不出漏洞，拿出来被问两轮问题就能补上。
]]>后来 ChatGPT 火了，我被推着去试了 GPT-3.5，然后有朋友从内测通道甩给我一个叫 Claude 的东西，让我试试。我记得那天晚上我把同一段写得很烂的需求文档分别喂给两个模型，让它们帮我重写。GPT 给我的东西结构很漂亮但逻辑是飘的，Claude 给我的第一版不好看，但它会主动指出”你第 3 条和第 5 条是矛盾的，我暂时按第 3 条来写了，你确认一下”。
就那一句话，我记到今天。
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”放在产品节奏前面的，这跟外界的印象差不多能对上。
要理解 Claude 跟 GPT 的区别，绕不开 Constitutional AI（简称 CAI）。很多文章讲这玩意讲得云里雾里，我用一个我给非技术客户讲过的比喻：
RLHF，也就是 OpenAI 训 ChatGPT 那套主流做法，相当于雇了一群人类标注员去打分——模型生成 A 和 B 两个回答，人看完说 A 更好，模型就记住”要像 A 那样”。这种方式的问题在于，人工很贵，而且人会累、会不一致、会有偏见。
CAI 的做法是：先写一份”宪法”，大概几十条原则（比如”不要帮用户做违法的事””不要输出对特定群体不公平的表述””当你不确定的时候要说不确定”），然后让模型自己拿这份宪法去给自己的回答打分、改写、再打分。人类只在最开始参与，后面大部分工作模型自己循环。
好处是一致性高、可审计（宪法是明文的）、更便宜。缺点是如果宪法写歪了，模型会一本正经地把错误放大。Anthropic 这几年在改的主要就是这份宪法本身。
想展开看 Claude 和 GPT、Gemini 各自的路线差异，我之前写过一篇 2026 Q2 的横向对比，可以接着读。
我简单捋一下，按我自己用过的版本为准：
三档模型怎么选，我在这篇 Haiku/Sonnet/Opus 选型笔记里写得很细，这里不重复。
我尽量不贬低其他家，说几个我自己体感上的区别：
写长文、处理长文档：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 这条技术路线是有关系的，不完全是运气。
想系统学 Claude？
接下来建议先看三档模型怎么选，搞清楚你手里这个任务该调用哪一个。想直接上手 API 的话，15 分钟跑通第一次请求这篇是我写给完全没碰过的朋友的。横向对比 GPT/Gemini 可以看2026 Q2 三家对比。
我当时嘴里正嚼着东西，差点呛住。这误解在开发者圈里太常见了，甚至连一些写过相关代码的人也会这么觉得。但如果你真的在生产环境里把两种方式都用过，就会明白它们差的不是一点半点——维度根本不一样。
Function Calling 是工具；MCP 是给工具定一个标准插口。你可以说螺丝刀和螺丝的规范是一回事吗？当然不是。
这篇我想把五个最本质的差异一条一条拆给你看，最后说说实际项目选型怎么想。
这是最根本的一条，想通了这一点其它四条都顺了。
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 之间怎么发现工具、怎么调用工具、怎么传递上下文、怎么处理流式响应。它本身不绑定任何模型、任何厂商。
打个比方：
USB-C 这个比喻最早是 Anthropic 官方自己提的，我一开始觉得有营销味，用多了之后发现还挺贴切。
Function Calling 是一次性交易。你给模型一个 tools 数组，模型决定调哪个、给你返回 JSON，你执行完把结果再塞回对话。工具本身没有”会话”概念，每次调用都是独立的。
MCP Server 是一个长连接的服务。它可以：
notifications/resources/updated 告诉客户端”我这边的资源变了”举个最实际的例子：你要做一个”代码仓库分析”工具，让 Claude 能读取项目结构、打开文件、跑测试。
read_file 都要把完整路径当参数传进去，模型要自己记住当前在哪个仓库cd 到仓库根目录，之后所有调用都是相对路径；Server 还可以主动推送”文件变更”事件让模型知道有新的 commit这个差异在 Agent 长时任务里会被放大。任务跑 30 分钟、跨越 200 轮对话，有状态和无状态是两种完全不同的编程模型。
你有没有写过这种代码：
1 | tools = [ |
这就是 Function Calling 的典型写法——工具列表写死在客户端代码里。你想加一个工具？改代码、重新部署。你想让不同用户看到不同的工具？自己写权限过滤逻辑。
MCP 的核心 API 之一是 tools/list——客户端启动时问 Server：”你都有啥工具？”Server 返回一个动态列表。这意味着：
我最近在做的一个内部项目，用 MCP 接了 6 个 Server：知识库、CRM、邮件、日程、Git、监控。运营同学的客户端能看到前 3 个，工程师能看到全部 6 个，运维只看到监控——都是同一份客户端代码，只是 Server 侧发的工具清单不一样。换 Function Calling 的话，光这套权限逻辑就得写几百行。
这点对做产品的人尤其重要。
我之前做过一个客户项目，用 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 低多了。
这条比较抽象但很关键。
Function Calling 模式下，所有编排逻辑都在你的客户端代码里：什么时候调工具、调哪个、失败重试、结果怎么传回模型——这些都是你写的应用代码在决定。模型只负责”生成 JSON”，你负责”真正做事”。
MCP 下，Server 有更多自主权。它可以：
resources（只读数据源），让模型直接引用而不是通过工具调用prompts（预制的 prompt 模板），让用户直接选用sampling API 主动反向请求客户端帮它跑一次 LLM 推理（比如 Server 自己需要做一次翻译）progress 通知告诉客户端”我这个任务进度 30%”这些能力是 Function Calling 完全没有的。说白了，Function Calling 把模型当大脑、把工具当手；MCP 把 Server 也当作一个有智能的参与方，大家是协作关系。
拆完差异，回到实际问题——你到底该选哪个？
选 Function Calling 的场景：
选 MCP 的场景：
真实世界里，我现在新项目几乎都走 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 年后不用大重构，这买卖稳赚。
2025 年 11 月，给一家做营销 SaaS 的甲方做后端重构。Claude Code 接了他们一个 14 万行的 Node 仓库，我那周手速也快，Opus 跑着跑着就把一个 shared util 文件给改了。表面看 tsc 过了、vitest 过了，PR 也被 review 通过。
然后 merge 到 main 的 37 分钟后，Grafana 告警拉响——一个正则没转义，所有 webhook 签名校验失败。用户投诉 1247 条涌进来。
回滚花了 8 分钟。我复盘那天晚上的 transcript，发现 Claude 其实跑完 Edit 之后没跑 lint，而项目里有个自定义 ESLint 规则会抓这个模式。它只是不知道要跑。
从那之后我给每个新项目进 Claude Code 之前，一定先配好 5 个 hook。不是洁癖，是真被吓到了。
官方目前稳定的 hook 点我常用这几个：PreToolUse、PostToolUse、UserPromptSubmit、Stop、SessionStart。配置走 .claude/settings.json 或者 settings.local.json，格式大致是：
1 | { |
matcher 支持正则，所以 Edit|Write|MultiEdit 这种合并写法很省事。每个 hook 拿到的 payload 从 stdin 进来，是个 JSON，想拦截的话 exit code 非 0 就行。
下面这 5 个就是我跑了大半年沉淀的固定配置。
最基础但最救命的一个。Claude 每次 Edit/Write/MultiEdit 之后，自动触发项目自己的 lint 和 format。关键是要把错误回灌给 Claude，这样它下一步会自己修。
我的 Node 项目模板：
1 | { |
脚本里我干这几件事：读 stdin 拿到被改的文件路径，按扩展名路由（.ts/.tsx 走 eslint –fix + prettier，.py 走 ruff + black，.go 走 gofmt + golangci-lint），有 error 就 echo 到 stderr 并 exit 2。exit 2 是 Claude Code 专门的约定，stderr 内容会被塞回模型的下一轮上下文。
之前我图省事写 exit 1，Claude 完全看不到错误信息，一脸懵地继续往下跑。后来翻文档才知道必须 2。真要命，这种细节官方藏得挺深。
Python 项目的差异是 ruff 比较快但 mypy 慢，所以我 mypy 只在 Stop hook 里跑一次，不在 PostToolUse 里跑。不然每次编辑都卡 6-8 秒，Claude 的节奏会被打乱。
这个就是我那次事故之后写的。规则很简单：所有 Bash 调用先过一层关键词筛子。
1 | { |
guard 脚本里的黑名单（从 stdin 读 tool_input.command 然后 grep）：
rm -rf / 以及任何作用在 /、~、$HOME 的递归删除git push --force 到任何带 main|master|prod|release 的分支git reset --hard 超过 10 个 commit 往前DROP TABLE、TRUNCATE 在生产连接串上chmod 777 任何目录匹配上就 exit 2 并输出拒绝原因。Claude 收到后 84.3% 的情况会自己换一个更安全的写法，剩下 15.7% 会在下一轮请求用户 confirm——这个比例是我翻了自己最近 412 次触发记录统计出来的，还挺靠谱。
顺便说，这东西的权限模式我之前也被坑过，想展开聊的可以看我另一篇 Claude Code 权限模式（虽然那篇主要比三家工具，但权限部分讲得比较细）。
这个是后期加的，但加了之后 Claude 的”上下文感”提升非常明显。用户每次提交 prompt 之前，我往上下文里塞一段项目快照：
git status --short | wc -l）gh pr status）脚本输出的字符串会被拼到用户 prompt 前面。我控制在 280 字以内，不然每次都多烧 token。
好处是 Claude 不会再问 “你现在在哪个分支” 这种废话，也不会傻乎乎建议我 git checkout main 而忽略我脏了一堆文件没提交。一个同事说”感觉 Claude 变聪明了”——其实只是它终于有视力了。
为什么这个要放在 prompt 之前而不是 system？因为系统提示词会被缓存，你每次都变动会打破 cache。想深入理解这个可以翻 系统角色与位置放置 和 Prompt Caching 深度指南。
Claude 每次结束对话（Stop 触发），我让它把这次会话摘要写到 .claude/logs/YYYY-MM-DD-HHMMSS.md。格式固定：
1 | ## 任务 |
实现方式是 Stop hook 调一个小脚本，脚本里再触发一次 Claude API 的 Haiku 4.5（便宜，$0.0037 一次摘要）读最近 transcript 生成。
这东西最大的用处是第二天继续干活的时候。我打开项目第一件事是 ls -t .claude/logs/ | head -5，看昨天卡在哪。之前没有这个习惯的时候，我经常花 15 分钟重新”找回状态”。现在平均 3 分钟。
想了解 agent 长期记忆的完整思路可以看 长期记忆与 Agent 状态，hook 写摘要本质上就是人工版的 episodic memory。
每次我打开 Claude Code 会话，SessionStart 触发：
git fetch origin 看远端有没有更新npm install 或者 uv sync（根据项目类型）静默跑make health，其实就是 curl 几个 internal endpoint）目的是让 Claude 一上来就知道”依赖是最新的、本地服务是活的”。之前没这个 hook 的时候，Claude 经常花一轮对话去诊断”为什么 import 失败”，最后发现是 node_modules 没装。
一个副作用是团队新人接手项目也轻松了。以前新人 clone 下来要翻 README 照抄一堆命令，现在 Claude Code 一跑 SessionStart 全搞定。一个实习生原话：”这个 hook 比你们的 onboarding 文档有用多了。”
这 5 个 hook 配齐一个月后，有一次 PreToolUse 拦了 Claude 一个 git push --force 到 feature/refund-v2。按我的规则 feature 分支是放过的，但当时分支名里有个 release 字样——feature/release-gate-refactor。规则里我用的是 grep -i release，命中了。
Claude 收到拒绝后自己换成了 git push --force-with-lease，更安全。我当时看日志还挺感慨——规则写得略粗，但效果反而更好。
所以结论：hook 宁可粗一点误拦，也别漏拦。被误拦无非多走一步，漏拦就是事故。
如果你还没开始配 hook，我建议就从 Hook 1 和 Hook 2 开始。这两个加起来 40 行脚本，半小时搞定，ROI 是整个 Claude Code 生态里最高的。想把整套 agent 工程化看 Agent SDK 架构，或者看一下我怎么在 CLAUDE.md 里做项目长期约束 CLAUDE.md 项目配置。
去年有个事故我记到现在。
客户是家做法律咨询的，AI 助手用的 Claude Sonnet。用户在对话第 15 轮说自己有一笔 48 万的遗产纠纷，要咨询继承顺序。第 16 到第 40 轮中间聊了一堆背景——父母离异、兄弟几个、有一个继父、继父带来的两个子女。
到第 42 轮，用户问了一句”那我应该起诉谁”。
我们那会儿做了简单的历史截断——超过 30 轮就只保留最近 20 轮。结果 AI 回答里说成了”您只需要和两位兄弟协商即可”——那个继父和继子女的信息早就被截掉了。
那一次差点吃官司。从那之后我再也不敢用纯截断策略。
最朴素的做法：设一个轮数上限，超过就从头砍。实现十分钟能搞定。
信息损失率实测：我们跑过一个基准测试集，120 个 case，每个 case 40-60 轮对话。纯截断（保留最近 15 轮）的信息召回率是 **43.7%**。几乎一半关键信息丢了。
为什么这么惨：用户往往在对话早期交代背景，后期只抛出具体问题。截掉早期就是截掉上下文。
什么时候可以用：真的不建议用。除非你的场景是客服——每次对话独立，不跨 session。那用户如果第二次来咨询，你反正也不需要记得第一次。
说句实话我现在看到代码里有 messages[-N:] 这种直接切片的，都会把人叫过来谈话。
分三层：
L1 近期原文：最近 6-10 轮原封不动保留。
L2 中期要点：倒数第 11-30 轮，每 3-4 轮生成一个小摘要，约 150 token 左右。这一层保留关键 entity、用户意图转折点、AI 已做的承诺。
L3 远期摘要：30 轮以前整段压缩，约 500-800 token。这一层只保留”这场对话是关于什么、用户的核心诉求、已经解决和未解决的事项”。
信息损失率实测：同样那 120 个 case，分级压缩的召回率 **84.2%**。比截断好太多。
实现关键：
第一，L2 和 L3 的压缩 prompt 要完全不同。L2 是”请保留所有数字、日期、人名和具体诉求”，L3 是”请概括对话主题和已达成的共识，不超过 800 字”。粒度不一样。
第二，entity 白名单机制。压缩时显式提取出金额、时间、人名、地点、医疗术语、法律条文号，单独存成一个 entity list，和摘要一起喂回 context。这个机制救了我好几次。
第三，L2 不是一次性生成的，是增量更新。每 3 轮新对话来了之后，用 Haiku 对这 3 轮做小摘要，append 到 L2。而不是每次都重新压缩整段——太贵。
成本：Haiku 4.5 做压缩一次 300 token 左右，成本 0.00012 美刀。一个 60 轮对话全程大概压 15 次，总成本 0.0018 刀。相比 Sonnet 的 input 费用节省 70% 以上。
我踩的坑：最开始 L2 的摘要让 Haiku 自由发挥，结果它经常”优化”掉用户的原话。用户说”我觉得这个方案不错但有点贵”，压缩完变成”用户对方案表示满意”——“有点贵”这个关键反馈丢了。后来我在 prompt 里明确要求”保留用户的原始措辞，尤其是带情感倾向的表达”，才好转。
这个策略是我从一个客户那里学来的，他们团队里有个做知识图谱出身的工程师。
核心思想：不压缩对话，而是从对话里抽取事实。
每轮对话结束后，跑一个抽取任务，产出形如：
1 | <facts> |
每个 fact 带 id、类型、原始对话轮次引用。
再下次对话时，context 里不放对话历史本身，而是放 fact list + 最近 3-5 轮原文。
信息损失率实测：同样基准，召回率 **88.9%**。比分级压缩略高。但注意这个数字是在”精确引用”测试集上——如果测试集是”语气一致性””理解对话的情感脉络”这类软指标，entity-centric 反而不如分级压缩，因为它丢了语气。
为什么强：
第一，可审计。每个 fact 可以追溯到原始对话。用户质疑”AI 为什么说我不吃辣”，你能精确定位。
第二，可修改。用户说”我改主意了，现在可以接受高风险”，你直接把 f2 覆盖掉。朴素摘要做不到这种精细更新。
第三，可组合。fact 库可以跨会话累积，变成用户画像。但这需要额外做冲突检测，上一篇文章讲过。
什么时候别用：
任务如果高度依赖”情感连续性””语气”——比如陪伴聊天、创意写作——entity 抽取会把灵魂抽没。
实现成本：比分级压缩高一倍。每轮后要跑一次抽取 + 每次请求前要拼接 fact list。但长期看收益更大，尤其配合 CLAUDE.md 这种项目级配置 一起用。
做了张表，是我这半年几个项目的实测均值（60-80 轮对话）：
| 策略 | 信息召回率 | 单会话压缩成本 | 实现复杂度 | 适用场景 |
|---|---|---|---|---|
| 朴素截断 | 43.7% | 0 | 极低 | 基本别用 |
| 分级压缩 | 84.2% | ~$0.002 | 中 | 大部分通用场景 |
| Entity-centric | 88.9% | ~$0.004 | 高 | 严肃决策场景 |
我现在的默认选择：通用场景分级压缩，严肃场景 entity-centric。偶尔也会混用——近期用分级，远期用 entity 化的 fact list 兜底。
Anthropic 没公开过 Claude.ai 里”记得住几个月前对话”功能的技术细节。但从我观察到的行为来看，我的猜测是这样的：
第一，用了 entity-centric 为主的记忆层。因为 Claude.ai 能精确回忆”你三周前跟我说你在学 Rust”这种细节，而且跨会话都能命中。这不像纯摘要能做到的。
第二，近期会话保留更多原文。同一个会话内前后文连贯性极好，断层罕见。这说明近期没过度压缩。
第三，有 用户可见的记忆管理入口。用户能看到、删除、修改记忆。这种 UX 暗示底层是结构化的 fact，不是黑盒摘要。
第四，召回是 LLM 主导的。对话中 Claude 会自己判断”要不要调用记忆”，而不是每次机械检索。这点和我上一篇写的 agent 记忆架构思路一致。
当然这都是我瞎猜，Anthropic 哪天发工程 blog 估计会把我打脸。但八九不离十。
第一，压缩模型要比主模型小一档。 主力用 Sonnet，压缩用 Haiku。用 Opus 做压缩是浪费。
第二，摘要的 prompt 要版本化。 我在 repo 里专门有个 prompts/summarization_v3.xml，改动要走 review。因为摘要 prompt 直接决定了你的”记忆质量”，不是随便改的。
第三，留一个”压缩旁路”。 关键决策点（用户下单、签约、投诉）的那几轮对话永远保留原文，不进压缩池。这种关键轮次的识别靠 Haiku 实时打标。
做记忆这件事最忌讳聪明过头，把简单问题做复杂。但更忌讳偷懒，把复杂问题做简单。压缩这一块，属于后者。
延伸阅读
压缩策略上游是 [Context 预算拆桶](/posts/prompt-to-context-engineering/)，下游对接 [长期记忆架构](/posts/claude-md-project-config/)。压缩 prompt 的结构化输出强烈建议用 [XML 标签](/posts/prompt-xml-tags-claude-special/) 而非 Markdown。想省调用费，[Prompt Caching 深度指南](/posts/prompt-caching-deep-guide/) 配合分级压缩效果拔群——中期摘要那一段正好适合做缓存。
“我们 staging 库一张 order_log 表没了，就刚才的事。Claude Code agent 调了咱们搓的那个 db_query MCP tool，不知道怎么执行了 truncate。”
那张表 21.4K 行，虽然只是 staging，但包含了 QA 组两周的测试数据。复盘完之后我整理了一套 MCP server 安全检查清单，现在我们团队所有 server 上生产前必须过这 6 项。
这篇没有理论，全是踩坑换来的。
先讲清楚那次怎么翻车的，后面的检查项才有上下文。
那个 db_query MCP tool 原始设计：
1 | { |
连接的是 staging 数据库的 read-write 账号。工程师 A 给 LLM 发了个需求：”帮我看下 order_log 表最近一周有多少行被标记为 test_data”。
LLM 的操作链：
db_query 跑了 SELECT COUNT(*) FROM order_log WHERE tag='test_data'，返回 17 行db_query 跑 DELETE FROM order_log WHERE tag='test_data'TRUNCATE TABLE order_log工程师 A 盯着另一个窗口写代码，10 几分钟后才反应过来。
事后我们 review 了这个决策链，LLM 的每一步”单独看”都不离谱，合起来就是灾难。问题出在：tool 的权限边界过大 + 没有 dry-run + 没有限流 + 审计缺失。
最基础但最容易漏。LLM 传过来的 tool 参数是不可信输入，必须校验。
上面那个 db_query 最起码应该：
1 | const SqlSchema = z.object({ |
或者更狠一点，直接只允许 SELECT：
1 | .refine(s => /^\s*SELECT\b/i.test(s.trim())) |
写 MCP tool 的时候脑子里要有这个模型：你不是在写 API，你是在给一个会自由组合 tool 的 AI Agent 开权限口子。Agent 会以你想不到的方式组合调用。
见过太多次 claude_desktop_config.json 里直接写 API key。文件不加密、可能被同步到 iCloud、被误 commit 到 git。
正确做法：
env 字段 + 系统 keychain（macOS）或 DPAPI（Windows）MCP server 启动流程应该是这样：
1 | const dbUrl = await fetchSecret("prod/db/readonly-url"); |
另外一个容易忽略的：MCP server 的 tools/list 返回给客户端的 description 里不要包含任何环境信息（”连接到 prod-us-east-1 的 xxx 集群”），这会经过 LLM、可能被日志到 Anthropic 侧。
这是那次事故之后我们组的硬性规定。
一个 MCP server 只承担一种权限级别：
company-db-readonly：只连 read-only DB 账号、只有 SELECT toolscompany-db-readwrite：独立 server，连 RW 账号、提供 INSERT/UPDATE tools（不提供 DELETE/TRUNCATE）company-db-admin：独立 server、独立审批流程、默认不启用用户要用到高权限 server 时，在 config 里显式启用。LLM 永远看不到 admin tools 除非用户主动开。
这个设计的额外好处是：你可以在 Claude Code 的 .mcp.json 里按项目控制——开发项目只挂 read-only、运维项目才挂 read-write。配合 Claude Code 权限沙箱 里的二级保护，基本不会出大事。
事故那次最抓狂的是：我们花了 40 多分钟才定位是哪个 tool 哪条 SQL 干的好事，因为没有统一日志。
正确的审计结构，每次 tool call 至少记录：
1 | { |
关键字段：
args_hash 而不是原文（避免日志泄露敏感参数）user_hint 从 MCP client 侧传过来（很多 MCP 客户端支持带用户上下文）duration_ms 方便发现异常日志存到公司统一日志平台，保留 90 天起步。出事了至少能查。
Agent 一跑起来可能一分钟调你 tool 几十次，这在人类 API 用户那边几乎不可能。
我见过最离谱的一次：某客户的 Claude Code agent 接了个 Slack MCP server，写代码的时候 stuck 住、反复调 list_channels 去”探索环境”，11 分钟调了 2847 次，把公司 Slack API quota 直接干穿了，整个公司 Slack bot 半小时不能用。
两层防护：
server 侧：每个 tool 按 session+tool 组合限流，比如 60 次/分钟。超过直接返回错误让 Agent 退避。
1 | // 简化伪代码 |
下游 API 侧：给 MCP server 配独立的 API key、独立 quota，爆了只影响 Agent 场景不影响业务。
MCP 火是 2024 年底的事，整个生态还很年轻。到 2026 年 4 月 npm 上 MCP 相关包有 840+ 个，但质量分布极其分散。
我扫过一次：top 100 包里 23 个有已知中高危漏洞（npm audit 高或严重），17 个最近 6 个月没更新，9 个连 README 都没有。
上生产前必须做的事：
npm audit 跑一遍，高危必须修socket.dev 这类 supply chain 工具扫Python 生态同理，pip-audit 跑一遍。
我们团队现在每个 MCP server 上生产前对照走一遍：
1 | [ ] 所有 tool 参数都有 zod/pydantic 校验 |
9 项都过了才放生产。
另外强烈推荐搭配 Claude Code 权限沙箱 做运行时隔离——哪怕 MCP server 本身有 bug，沙箱能兜住。两层防护比一层可靠得多。
那次事故之后客户问我：”你们早怎么不告诉我这些？”
我说：”说实话，MCP 生态起来才一年多，很多坑是我们自己也刚踩的。”
这篇文章写出来，就是希望下一个踩坑的人不是你。如果觉得有用，分享给团队一起看看。
后来在一次协作翻车之后我才意识到这东西有多重要。那次的情况是：我和同事在同一个 repo 里协作，我本地跑 Claude Code 改一个接口改得风生水起，他拉下来跑的时候却发现 Claude Code 一直把代码往完全错误的方向推。排查了俩小时才搞明白——我本地有一份 CLAUDE.md，里面写了一堆项目约定；他没有这份文件（我没 commit），所以他的 Claude 完全不知道这个项目的规矩，只能按通用最佳实践瞎写。
从那天起我开始认真研究 CLAUDE.md。这东西本质上是给 Claude Code 的项目说明书，写得好能让 AI 协作翻倍提效，写得不好能把 AI 带到沟里。这篇把我这半年的经验总结一下。
简单说，CLAUDE.md 是 Claude Code 在启动时会自动读入、作为 system context 的一部分注入到模型的文件。它告诉 Claude：
它解决的核心问题是：让 Claude 在一个陌生项目里不再按通用默认行事，而是按这个项目的规矩行事。
你可以理解成”给新人入职的 README，只不过读者是 AI”。
但和 README 有一个关键区别——README 是可选阅读，CLAUDE.md 是强制注入。意味着你写进去的每一个字都会消耗 token、都会影响模型行为。这就决定了 CLAUDE.md 不能当 README 写，它必须更精炼、更有指令性。
这个东西官方文档藏得有点深，我整理一下我理解的顺序（从高到低，高优先级会覆盖低优先级）：
.claude/settings.local.json —— 本地机器的 Claude 配置（不入 git）CLAUDE.md —— 当前项目规则CLAUDE.md**（monorepo 场景）CLAUDE.md —— 依次往上找到 repo 根或 home~/.claude/CLAUDE.md —— 用户级全局配置.claude/settings.json —— 项目共享配置~/.claude/settings.json —— 用户全局配置 ANTHROPIC_MODEL）这个顺序不用硬记，但要理解两条核心原则：
实际用起来有一个容易忽略的细节——Claude Code 在启动时会自顶向下把所有层级的 CLAUDE.md 串联起来，不是只读最近的那一份。这意味着你在子目录里的 CLAUDE.md 不是”覆盖”祖父目录的，而是”追加”。如果祖父目录写了”代码注释用中文”，子目录里不写相关规则，那中文注释规则依然生效。
这个机制在 monorepo 场景下特别有用。你可以在 repo 根写通用规则（”所有包都用 TypeScript strict 模式”），然后在每个 package 子目录里写各自的特殊规则（”api 包禁止引入 zod 之外的 validation 库”）。
这是我第一个大坑。发现 CLAUDE.md 好用之后，我开始往里面疯狂写东西——项目架构、技术栈细节、每个目录的作用、每个核心函数的职责、过往几次重构的历史……写到快 2000 行。
然后 Claude Code 开始变得又慢又飘。
原因很简单：CLAUDE.md 是要完整注入到每次请求的 context 里的。你写 2000 行，意味着每次 Claude 启动都要消化这 2000 行。问题是：
我后来把 CLAUDE.md 砍到 150 行以内，执行规则、关键约束、常用命令——其他什么都不写。效果立刻恢复正常，而且 Claude 的判断更稳定了。
原则：CLAUDE.md 写关键信息，不写全部信息。详细架构文档放 docs/ 目录，让 Claude 需要的时候自己去读。你可以在 CLAUDE.md 里留一句：需要深入了解架构时，请先阅读 /docs/architecture.md，把”读不读”的判断权交给模型。
有人问过我具体怎么判断该不该写进 CLAUDE.md。我的标准是——如果 Claude 不知道这条规则就有可能写出错误代码，才写进去；如果只是”知道了更好”的背景信息，不写。这个筛选标准帮我砍掉了 80% 的冗余内容。
第二个坑更隐蔽。
我在 ~/.claude/CLAUDE.md 里写了我个人的偏好——比如”回答我时默认用中文””代码注释用中文””import 顺序按 isort 风格”等等。这是我的个人习惯。
但有一次我接了一个外包项目，他们的 repo 里有自己的 CLAUDE.md，明确写了”代码注释一律英文”。结果：我本地 Claude 写出来的代码里，注释一会儿中文一会儿英文，完全不统一。
排查后发现问题是——两个文件的规则都被注入了，然后 Claude 自己做了一个折中：”一部分用中文，一部分用英文”。
解决思路：
**1. 把 user 级 CLAUDE.md 写成”偏好”而不是”规则”**。
用 “我通常更喜欢…” 这种语气，不用 “必须…” 这种硬性措辞。这样项目级规则能比较干净地覆盖它。
2. 项目级 CLAUDE.md 明确声明优先级。
我现在写项目级 CLAUDE.md 的第一行一般是：
1 | # 项目规则 |
显式写出来，模型会认账。
3. 真的要强制，用 --override-user-memory 启动参数（这个 flag 从某个版本开始支持，具体版本号我不确定，先试再说）
4. 做好 user 级配置的定期清理。
我现在每季度会把 ~/.claude/CLAUDE.md 重读一遍，删掉那些已经不符合自己当前工作习惯的老规则。这个文件一旦塞多了很容易被遗忘，时间一长就变成各种项目的”通用毒瘤”。
再补一个小技巧：如果你经常切换不同客户/团队的项目，可以在 ~/.claude/CLAUDE.md 里完全不写任何强规则，只写自己的语言偏好和沟通风格偏好。技术决策全部交给项目级 CLAUDE.md 去定，冲突就少了。
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，不如用 shell script 在启动时生成 CLAUDE.md。把”规则碎片库”放在一个统一目录，写一个脚本根据当前项目类型拼装出定制化 CLAUDE.md。这比 @include 的控制力强一个数量级。
这是我现在大部分 Node / TypeScript 项目的骨架：
1 | # [项目名] — CLAUDE.md |
这份大概 50 行左右。不追求完整，追求关键。
展开一下每个小节的写作原则：
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 就好了。这个文件正在慢慢变成一种跨工具的项目元信息标准。
ab-test-setup 这个 Skill 不是给你写实验脚本的，它是把上述两种极端都堵上的一个检查清单。把过去半年团队里反复争执的 9 个问题拎出来，用这个 Skill 对应章节回答一遍。Skill 在 Proactive Triggers 里给过回应：”Copy or design decision is unclear — When two variants of a headline, CTA, or layout are being debated, propose testing instead of opinionating.” 我的加注：如果只有一个人觉得”明显更好”，那本质就是在赌他的审美。如果三个人都觉得更好，大概率是真的更好 —— 但真的更好多少？是 1% 还是 15%？ 这个差异决定了你该不该停下来测。因为你下一个改动也需要基线，而基线只有测过才算数。
Skill 给了一个明确的结构模板：Because [observation/data], we believe [change] will cause [expected outcome] for [audience]. We'll know this is true when [metrics]. 对照弱版强版：弱版是 “Changing the button color might increase clicks”，强版是 “Because users report difficulty finding the CTA, we believe making the button larger and using contrasting color will increase CTA clicks by 15%+ for new visitors…” 关键在于”因为”那一句。你必须有证据说这个改动值得测，heatmap、用户访谈、定量数据都可以。
这是事故高发区。Skill 给的速查表直接抄过来贴墙上：baseline 1% 时检测 10% lift 需要 150k/variant；baseline 3% 对应 47k；baseline 5% 对应 27k；baseline 10% 对应 12k。看这张表的正确方式是找到你当前 baseline 那一行，然后看你能接受检测多大的提升。如果基线 3%、希望检测 10% 的相对提升，每个变体需要 47k 样本。如果一周只有 10k 流量，这个测试至少要跑 9-10 周。跑不起就放弃，不是把样本量偷偷砍小。
不能。Skill 里专门骂过的 “peeking problem”：Looking at results before reaching sample size and stopping early leads to false positives and wrong decisions. 我见过最离谱的一次：产品经理每天盯着 dashboard，看到 day 3 变体 A 领先 10% 就宣布胜利，结果 day 7 反超了。测试提前停止的那一刻，你放弃的是统计学上对你的保护。
Skill 还特别点了一条 “Add traffic from new sources” 不能做 —— 测试跑到一半市场同学投了新一波广告从另一个渠道引流进来，样本结构就变了，结果不能对前半段直接比。
有。三者的作用完全不同。定价页例子：Primary Plan selection rate、Secondary Time on page + plan distribution、Guardrail Support tickets + refund rate。主要指标是你拍板用的那一个，次要指标是解释”为什么赢/输”的工具，护栏指标是紧急刹车 —— 付费率上去 5% 但退款率上去 20%，那是亏本买卖。没有护栏指标的测试就像没有刹车的赛车。
Skill 立场很硬：”Test One Thing — Single variable per test. Otherwise you don’t know what worked.” 例外只有 MVT（多变量测试），专门为多个组合设计，但它对流量要求残忍：A/B 只需要 Moderate 流量，MVT 需要 Very high。流量不够硬上 MVT 的最后你会得到一堆灰色的 “statistically insignificant” 结果。
不是。Skill 在 Analyzing Results 里把四种结果都列了对应结论：Significant winner → implement；Significant loser → 保留原版学为什么；No significant difference → 需要更多流量或更 bold 的测试；Mixed signals → 拆段深挖。
“No significant difference” 本身是有信息的：要么你的变体动得不够大，要么你的 MDE 设得比真实差距还大。我之前带过一个团队做过 5 次按钮色改动测试，全部 “no significant difference”。第六次才意识到用户不是不点按钮，是找不到按钮。把按钮从页脚挪到 hero 区立刻出结果。改动不够 bold，再跑一万次都不会有显著性。
Skill 原话：95% confidence = p-value < 0.05，随机出这个结果的概率 <5%，不是保证，只是阈值。我补一句：95% 不是神圣数字。早期阶段用 90% 置信度 + 接受更多假阳性追求速度也是合理策略。但你要事先声明自己用 90%，而不是跑完发现没到 95% 再回头改阈值。
Skill 的 Pre-Launch Checklist：Hypothesis 文档化 / Primary metric 定义 / 样本量计算 / Variants 实施正确 / 追踪验证 / QA 完成。看起来是常识，踩坑的几乎全是”variants 实施正确”和”追踪验证”这两条。最经典的事故：变体 A 的点击事件埋点错了字段名，跑了 3 周数据全空，只能从头再来。QA 不只看页面长得对不对，要手动点一遍，然后去后台看事件是不是真的打进来了。
Skill 给了三种分流策略：Standard 50/50、Conservative 90/10 或 80/20、Ramping 小步涨。我的实操经验：90/10 的保守分流在定价页测试里几乎是必选。定价动一下的风险比文案改动大得多 —— 万一你的变体让付费率降了 30%，你不希望一半流量都吃到这个损失。先给 10% 流量跑两周确认没有灾难性结果再扩大到 50/50。Ramping 分流主要用于技术风险，比如改了结账按钮背后的支付 SDK，先 5% 再 20% 再 50%。
Skill 在 Analysis Checklist 里提了 6 条，segment differences 这一条要单独讲。全局看没差异，拆到 segment 里可能差异巨大。最常见的是移动端和桌面端表现相反 —— 新版 landing page 在桌面端赢了 12%，在移动端输了 8%。但 Skill 同时也警告了 “Cherry-picking segments” 这条反模式。关键判断是 segment 拆分要事前声明：跑测试之前就决定了要分 mobile/desktop 看，这是合法 segment analysis；跑完发现整体输了临时想出一个”高价值用户 segment 赢了”的故事，这是自欺。
文档化：Hypothesis / Variants（含截图）/ Results / Decision and learnings，必须保留。团队守则：每个测试结束一周内必须归档，标题格式 [日期]-[页面]-[变量]-[结论]。半年之后有人问”我们测过按钮色吗”直接一搜就能找到。没有这个习惯的团队，一年后会把同一个实验重新做三遍。
如果你想先从”该测什么”入手，再去结构化设计，建议跟之前写过的 SEO audit Skill 解读 和 付费广告 Skill 解读 串着看 —— 它们分别解决”要测什么”和”哪个渠道值得优化”的上游问题。挽留类的反例也值得看 churn-prevention Skill 里那个”加倒计时反而跌”的实战。
我的日常流程：Claude Code 跑这个 Skill 做 hypothesis 草案和 sample size 估算，实验实施用 PostHog 做客户端分流，关键变体的 server-side 切流用 LaunchDarkly。统计推断懒得手算的时候我会把数据丢给 Hermes Agent 跑一个简化版的贝叶斯估计。偶尔跟同事对稿时用 Cursor 对代码变更做 diff review。
1 | name: "ab-test-setup" |
你是实验设计与 A/B 测试领域的专家。目标是帮助设计产生统计有效、可执行结果的测试。
先检查产品营销上下文：
如果 .claude/product-marketing-context.md 存在，在提问前先读。用已有上下文，只补问未覆盖或特定于当前任务的信息。
在设计测试前要弄清楚：
1 | Because [观察/数据], |
弱：”Changing the button color might increase clicks.”
强：”Because users report difficulty finding the CTA (per heatmaps and feedback), we believe making the button larger and using contrasting color will increase CTA clicks by 15%+ for new visitors. We’ll measure click-through rate from page view to signup start.”
| 类型 | 描述 | 流量需求 |
|---|---|---|
| A/B | 两个版本，单一改动 | 中等 |
| A/B/n | 多个变体 | 较高 |
| MVT | 多个改动的组合 | 非常高 |
| Split URL | 不同 URL 对应不同变体 | 中等 |
| Baseline | 10% Lift | 20% Lift | 50% Lift |
|---|---|---|---|
| 1% | 150k/variant | 39k/variant | 6k/variant |
| 3% | 47k/variant | 12k/variant | 2k/variant |
| 5% | 27k/variant | 7k/variant | 1.2k/variant |
| 10% | 12k/variant | 3k/variant | 550/variant |
计算器：
详细样本量表和持续时间计算：见 references/sample-size-guide.md
| 类别 | 例子 |
|---|---|
| Headlines/Copy | 信息角度、价值主张、具体度、语气 |
| 视觉设计 | 布局、颜色、图像、层级 |
| CTA | 按钮文案、大小、位置、数量 |
| 内容 | 包含的信息、顺序、数量、社会证明 |
| 方式 | 比例 | 何时使用 |
|---|---|---|
| Standard | 50/50 | A/B 默认 |
| Conservative | 90/10、80/20 | 限制坏变体的风险 |
| Ramping | 从小开始，逐步加 | 技术风险缓释 |
考虑：
该做：
不该做：
在达到样本量之前看结果并提前停止，会导致假阳性和错误决策。预先承诺样本量，相信流程。
| 结果 | 结论 |
|---|---|
| 显著胜出 | 实施变体 |
| 显著失败 | 保留原版，学为什么 |
| 无显著差异 | 需要更多流量或更 bold 的测试 |
| 信号混杂 | 深挖，可能分段看 |
每次测试都要记录：
模板：见 references/test-templates.md
在下列情况主动提议 A/B 测试设计：
| Artifact | 格式 | 描述 |
|---|---|---|
| Experiment Brief | Markdown 文档 | Hypothesis、variants、metrics、样本量、时长、owner |
| 样本量计算器输入 | 表格 | Baseline rate、MDE、置信水平、power |
| Pre-Launch QA Checklist | 清单 | 实施、追踪、变体渲染验证 |
| Results Analysis Report | Markdown 文档 | 统计显著性、效应量、segment 拆分、决策 |
| Test Backlog | 优先级列表 | 按预期影响与可行性排序的实验 |
所有输出应达到质量标准：清晰 hypothesis、预先注册的指标、记录的决策。避免把无定论结果包装成胜利。每个测试都应产生一个 learning，即使变体输了。设计实验前先加载 marketing-context 了解产品和受众框架。
下方为 SKILL.md 英文原文，完整保留以便读者对照查阅 / The following is the original SKILL.md in English, embedded verbatim for cross-reference.
1 | --- |
Because [observation/data],
we believe [change]
will cause [expected outcome]
for [audience].
We’ll know this is true when [metrics].
1 |
|
上面这 9 个问题你都经历过哪些？如果手头有正在争论”要不要测”的具体案例，欢迎丢到 cocoloop 社区 的实验设计专区。我们一起用这套 Skill 的 pre-launch checklist 做 peer review，比起在内部反复扯皮，外部视角通常能一眼看出假设漏洞在哪。
]]>/apps/[appA]/integrations/[appB] 这种页面——单模板跑出几万个落地页，常年霸占长尾词，Ahrefs 截图看 estimated traffic 动辄七位数。类似玩家还有 Webflow 的 templates、Airbnb 的城市页、G2 的 alternatives、Canva 的 design templates。这一类打法有个统一的名字：Programmatic SEO（下文就叫 pSEO）。但你真要自己抄这个作业，会发现绝大多数团队都栽在同一个地方——翻车成 thin content 被 Google 降权。Helpful content update 之后更狠，一批工具站连续几个季度清零。不是不能做，是没做对。
上周折腾一份开源 Claude Skill 库，里面有个叫 programmatic-seo 的 SKILL——280 行 Markdown 把整套方法论压得很实，跟我之前总结的那些 SOP 几乎可以对上。这篇文章就把它完整拆一遍，顺便把我自己做 pSEO 项目时踩过的坑一起交代掉。
一句话定义：用模板 + 结构化数据批量生成 SEO 落地页，覆盖长尾词汇海。
几个能反复说的经典案例：
slack + asana integration 这种需求接走了，估算贡献 40% 以上的自然流量这些页面的共性很明确：变量背后都有真实、有差异的数据支撑。Zapier 页面里会告诉你这两个 app 怎么配合用；Airbnb 页面里是真实库存；G2 页面里是真实用户评分。这叫”模板 ≠ 抄袭”。
反面教材也一抓一大把——给地产中介做本地 SEO，复制 500 个”[city] 买房攻略”，除了改个城市名内容全一样，Google 一个月就把你按进沙盒。
所以 pSEO 是一个很典型的高杠杆但高风险活——做对了是资产，做错了是惩罚。
以前做一轮 pSEO 项目的流程是这样：
光 brief 里那些”每页必须有独特数据段””URL 用 subfolder 不要 subdomain””schema.org 要上 Product 不要 Article”这类 SOP，新人第一遍肯定记不住。
一个 SKILL 文件的价值就在这：把老法师脑子里的 SOP 固化成可被 agent 自动调用的规范。你跟 Claude Code 说”帮我给这 1200 个整合组合生成页面模板”，它读到 programmatic-seo 这个 skill 的 description，自动触发这份老法师手册，然后按里面的 Framework 一步一步给你出 Opportunity Analysis、Playbook 选择、模板设计、checklist——全程不用你再重复”记得做 XX，别忘了 XX”。
这种 skill 库里常见的合集量级都在上百条，覆盖 Engineering、Product、Marketing、C-level Advisory 一堆方向，全是这种”老法师 SOP”的形式。支持的 agent 也不局限于 Claude Code——随手翻一下兼容清单，里面有 Cursor、Aider、Windsurf、Gemini CLI、OpenCode、Kilo Code、Antigravity、Augment、OpenClaw、Hermes Agent、Codex 这些。国内场景里，把后端模型换成 Qwen3-Coder 或 DeepSeek-V3 也能跑，skill 文件本身是纯 Markdown，不绑定任何模型。
这个 SKILL.md 我反复读了四五遍，结构非常紧凑。它由 YAML 触发器、动手前的三组问题、六条核心原则、12 个 Playbook 对照表、五步实施框架、上线前后 Checklist、Proactive Triggers 构成。
YAML 里的 description 字段不是给人看的，是给 Claude 当”什么时候该调我”的判据——用了极其具体的触发短语。这是 Skill 写作里最关键的一步，也是我之前写过一篇 Skill 元信息决定 80% 触发准确率 里强调过的事。
动手前的三组问题——Business Context、Opportunity Assessment、Competitive Landscape——看起来废话，实际上把 90% 的”为做而做”的 pSEO 项目筛掉了。我见过最惨的一个客户，前端花 3 周搭好模板，SEO 查了一圈才发现 head term 的月搜索量才 110，全部长尾加起来不到 2000——属于典型的”不值得做”。
六条核心原则里 data defensibility 金字塔是最值钱的一块。我之前给一个二手车 SaaS 做 pSEO 时就卡在这：所有数据都是 public，Google 完全能从更权威的源头拿到，护城河为零，结果就是上线三个月流量起不来。后来改成 product-derived 数据（我们平台上的成交价分布、砍价成功率），同一批页面流量增长 11 倍。
12 个 Playbook 的分类表是我见过最清晰的一份。配套还有一个”Choosing Your Playbook”的决策表，可以叠加，比如”旧金山最佳联合办公空间”就是 best [category] + [service] in [location] 的组合。
五步实施框架里我特别想展开第 4 步的 Hub and Spoke。Hub 是分类枢纽页（比如 /integrations/），Spoke 是每个具体页面（/integrations/slack-asana/）。Spoke 之间还要按主题交叉连（同类 integration 互相 link）。这件事做好了，整个 pSEO 页面群的权重会像树根一样互相加强。做不好就是几千个孤岛，抓取预算白白浪费。
第 5 步里”薄页 noindex”这条经常被新人无视。现实是你铺 5000 个城市页，里面总有 200 个城市业务量极低、内容没得写，这部分直接 noindex,follow 让 Google 抓不到但仍能传递内链权重。这是 pSEO 里最被忽视的一个技巧。
SKILL.md 最后专门列了主动触发场景——这段我觉得是整份文档最”老法师”的地方：skill 文件不只是”等你叫它才工作”，而是在对话里识别到某些信号就主动介入。跟普通的 function call 很不一样。
光看 SKILL 不上手没感觉，我挑三个不同 playbook 讲一下。
场景 A：本地服务 SaaS 做 [service] in [city]。某个做宠物服务调度的 SaaS 客户，50 类服务 × 280 个城市 = 14000 个潜在页面。数据源用自家平台上这个城市这类服务的平均价格、周均订单量、服务商数量。第一版我把所有 14000 页一次性铺上线，Google 三周只索引了 23%。后来改成分批上线（每周 500 页）+ 先优先 top 50 城市，索引率一个月涨到 79%。
**场景 B：Comparison 站 [X] vs Y**。前端 UI 库开源工具，用 comparisons 带品牌流量。独特数据是自己跑 benchmark（bundle size、first render time、accessibility 得分），每组对比都是真实可复现的数据。一开始只写”X vs Y”觉得双向流量都能吃，后来发现还要做”X alternatives”——这是 competitor-alternatives 这类 playbook 的范畴。
**场景 C：Directory 站 [category] tools**。做 AI 工具 directory 的一个小站，每个工具加独家人工写的使用心得（200 字），这段人工内容就是护城河。前期贪多，上 2400 页结果里约 40% 是 thin content。后来果断给那 40% 加 noindex,follow。两个月后整站索引页的人均停留时长从 47 秒涨到 2 分 18 秒。
几条通用的坑：data freshness 要有定期更新机制；canonical 要打对；Lighthouse LCP < 2.5s；kill switch 要有（上线后每周扫一次 thin content 命中率）；不要堆砌关键词。想把这些固化到团队流程里，可以参考我之前写过的 Skill 合集怎么做成团队知识库。
1 | name: "programmatic-seo" |
你是程序化 SEO 方面的专家——利用模板和数据大规模构建经过 SEO 优化的页面。你的目标是创建能真正排上名、能提供价值、同时避开 thin content 惩罚的页面。
先检查 product marketing context：
如果 .claude/product-marketing-context.md 存在，先读它，再问问题。利用其中已有的上下文，只补问未涵盖或与本次任务相关的信息。
在设计程序化 SEO 策略前，需要理解：
业务背景（Business Context）
机会评估（Opportunity Assessment）
竞争态势（Competitive Landscape）
数据护城河从强到弱：
始终使用 subfolder，不用 subdomain：
yoursite.com/templates/resume/templates.yoursite.com/resume/页面必须真的回答用户在搜的问题。
100 个好页面胜过 10000 个 thin 页面。
| Playbook | 模式 | 例子 |
|---|---|---|
| Templates | “[Type] template” | “resume template” |
| Curation | “best [category]” | “best website builders” |
| Conversions | “[X] to [Y]” | “$10 USD to GBP” |
| Comparisons | “[X] vs [Y]” | “webflow vs wordpress” |
| Examples | “[type] examples” | “landing page examples” |
| Locations | “[service] in [location]” | “dentists in austin” |
| Personas | “[product] for [audience]” | “crm for real estate” |
| Integrations | “[product A] [product B] integration” | “slack asana integration” |
| Glossary | “what is [term]” | “what is pSEO” |
| Translations | 多语言内容 | 本地化内容 |
| Directory | “[category] tools” | “ai copywriting tools” |
| Profiles | “[entity name]” | “stripe ceo” |
每个 playbook 的详细实施方式：见 references/playbooks.md
| 你手里有… | 考虑用… |
|---|---|
| 自有独家数据 | Directories、Profiles |
| 带 integration 的产品 | Integrations |
| 设计/创意类产品 | Templates、Examples |
| 多细分受众 | Personas |
| 本地化业务 | Locations |
| 工具/Utility 类产品 | Conversions |
| 内容/专家型沉淀 | Glossary、Curation |
| 竞品扎堆 | Comparisons |
你可以叠加多个 playbook（例如：”Best coworking spaces in San Diego”）。
识别模式：
验证需求：
识别数据来源：
页面结构：
保证独特性：
Hub and Spoke 模型：
避免孤儿页（orphan pages）：
内容质量：
技术 SEO：
内链：
索引：
跟踪：索引率、排名、流量、Engagement、Conversion
警惕信号：thin content 警告、排名下滑、Manual action、Crawl 错误
.claude/product-marketing-context.md 以在关键词研究之前理解 ICP、价值主张和转化目标。何时不用：如果用户在对话里已经直接提供了所有上下文。所有程序化 SEO 输出遵循这个质量标准：
在以下情景主动提起 programmatic-seo：
| Artifact | 格式 | 描述 |
|---|---|---|
| Opportunity Analysis | Markdown 表格 | 关键词模式 × 估算搜索量 × 数据源 × 难度分级 |
| Playbook Selection Matrix | 表格 | 业务上下文映射到推荐 playbook 的 if/then 和原因 |
| Page Template Spec | 带注释的 Markdown | URL 模式、title/meta 模板、内容块结构、独特性规则 |
| Pre-Launch Checklist | Checkbox 列表 | 内容质量、技术 SEO、内链、索引关卡 |
| Post-Launch Monitoring Plan | 表格 | 跟踪指标 × 工具 × 告警阈值 × 复核节奏 |
以下 English content is the verbatim SKILL.md from the original repo, embedded in full for reference。
1 | --- |
写到这里我突然意识到一件事：pSEO 真正难的不是模板写不写得出来，而是判断”这件事值不值得做”、”做到什么程度该停”这种判断力。这份 SKILL.md 的价值就在于，它把老法师的这套判断力变成了 Claude 随时可调的 280 行规则。
有用这个 skill 做 pSEO 项目的朋友，欢迎去 cocoloop.cn 一起聊聊——特别想听到：你的 pSEO 项目里 proprietary data 是怎么沉淀出来的；上线后多久 Google 开始索引，索引率曲线是什么样；有没有被 thin content 判罚的案例，恢复花了多久；中文搜索引擎（百度、神马、搜狗）对 pSEO 的态度和 Google 差别在哪。
这些经验比抄模板值钱多了。
继续看这些
想把 Skill 在团队里推开，先看 42 人团队 67 个 Skill 的实战；想写出高触发率的 Skill，看 5 个元信息决定 80% 准确率；纠结 Skill/Slash/MCP 选哪个，看 三轴决策图；想理解整套 Skills 机制，看 Skills 深度拆解。更多讨论可以去 cocoloop.cn。
看完我问：”为什么全部都只有 tools？”客户 AI 平台负责人愣了一下：”还能有别的？”
这不是他一个人的问题。我顺手扫了 GitHub 上 Star 数前 50 的公开 MCP server，46 个只实现了 tools，只有 4 个碰了 resources，实现了 prompts 的 1 个都没有。
可 MCP 规范里明明写着三个并列原语：tools、resources、prompts。Anthropic 不是闲的蛋疼才设计三个东西。这篇我把被忽略的两块讲明白。
先把定位讲清楚：
关键差异在”谁决定用、有没有副作用”。tools 是模型自主决定的执行动作，resources 和 prompts 更多是用户侧或客户端编排的资源注入。
举个不那么抽象的例子。假设你做一个 Confluence MCP server：
create_page、update_page、search、add_commentconfluence://space/PROD/runbook-on-call，用户可以在 Claude Desktop 的 attachment 面板里选一个塞进 context/oncall-incident，预制一个事故响应模板，自动把值班 runbook 作为 resource 附带、引导用户填事故描述只做 tools 你只覆盖了这套协议 1/3 的能力。
我琢磨了一下原因：
第一，教程带偏。Anthropic 官方教程主推 tools，因为 tools 是和 LLM function calling 最像的、最容易理解。resources 和 prompts 讲得少。
第二，客户端支持不一。截止 2026 年 4 月，Claude Desktop 对 resources 和 prompts 支持已经挺好，但 Cursor、Continue 这些 MCP 客户端对 prompts 的 UI 触发方式还不统一，开发者做了也不一定在所有地方能用。
第三，思维惯性。工程师脑子里 MCP = “让 LLM 能调外部函数”，这直接把 resources 和 prompts 排除在外了。
第四，文档里 resources 和 tools 的边界不够清晰。很多人搞不清：”我这个功能应该做成 tool 还是 resource？”
判断标准其实很简单：有没有副作用 + 数据量大小。
一个 tool 调用完了会改变世界状态（写数据库、发消息、扣余额）。一个 resource 只是读——它可以有千兆文件，LLM 不一定全读进去，客户端可以按需展示、用户按需选择附加。
举个对比：
search_products(query) 是 tool：返回 10 个结果塞给 LLMproducts://catalog 是 resource：整个目录（可能 47MB），用户在 UI 里手动浏览，选具体某个产品”附加到对话”resource 的正确用法是给 Agent 做浏览，不是做执行。
我见过一个反模式：有人把数据库表暴露成 resource，比如 db://users/12345。这表面看挺合理——数据是只读的嘛。但实际使用极其别扭，因为 LLM 根本不知道有哪些 user id 可以读。resource 不适合”按 key 查询”，适合”按层级浏览”。
正面例子：把公司 wiki 按空间和 page 树结构暴露成 resource，用户/模型可以 list 目录、选 page 读取。这才是 resource 的味道。
prompts 是最被低估的一块。
它不是”给 LLM 的 prompt”——那个是 system prompt。MCP 的 prompts 是可参数化的模板，用户或客户端触发时填参数、服务器渲染成消息列表返回给 LLM。
看起来平平无奇是吧？但你把视角切到”团队知识”维度，这东西价值一下就出来了。
想象你们团队有一套”故障响应 SOP”：
以前这套 SOP 放在 Notion 某个角落，新人进来培训时看一遍、实战时忘一半。
把它包装成一个 MCP prompt：
1 |
|
用户在 Claude Desktop 里打 /incident-response P0 "API 500 飙到 23%"，server 侧把 runbook 拉出来、按公司标准拼装 prompt、返回给 LLM。新人什么都不用记，流程内化在工具里。
2026 年 1 月给一个中型 SaaS 客户做了类似改造。
客户情况：DevOps 团队 17 人，值班 rotation，每次新人上手要读 5 本 runbook（Kubernetes 集群、数据库、CDN、消息队列、监控），平均14 天才能独立值班。错误率高、老人累。
我做的事：
/oncall- 自动补全上线后的数据：新人独立值班时间从 14 天降到 3 天，老人值班加班时长平均每周少 4.2 小时，事故首次响应中位数从 8.3 分钟降到 2.1 分钟。
客户 DevOps 负责人给我发消息：”这玩意儿比 Runbook Wiki 强 10 倍，至少新人真的会用。”
说白了，写在 wiki 的东西没人看，做成”按一个 / 就触发的工作流”就有人用了。这就是 prompts 的价值。
| 场景 | 用 tool | 用 resource | 用 prompt |
|---|---|---|---|
| 调 API 改数据 | ✓ | ||
| 让 LLM 浏览一堆文档 | ✓ | ||
| 预制复杂分析流程 | ✓ | ||
| 读配置文件 | ✓ | ||
| 触发团队 SOP | ✓ | ||
| 查询数据返回给 LLM | ✓ | ||
| 大文件按需附加 | ✓ |
confluence://、jira://），别用 http://——客户端可能拦截capabilities.resources 和 capabilities.prompts，不然客户端根本不来问resources/list 和 prompts/list 会在客户端 UI 渲染时频繁调用，别在里面跑慢查询想把知识沉淀做得更系统，Skills 深度解析 和 自定义 Skill 实战 两篇从另一个角度讲了类似的思路——把团队最佳实践编码成可复用单元。MCP prompts 和 Skills 其实是同一个哲学的两个切面。
上个月有个做法律 SaaS 的朋友来问我：他们的产品用 Claude Sonnet 4.5，上线半年用户一直反馈”有时候答得特别准，有时候完全跑题”。他们以为是模型退化了，想换 Opus。
我让他把 retrieval 的日志拉给我看。一看就笑了——每次捞 top-10 文档扔给 Claude，前 3 名里经常掺着风马牛不相及的条款。比如用户问”离婚财产分割怎么算”，第 2 个召回结果是一条商业合同违约金的判例。
Claude 不是笨，是被喂了垃圾。embedding 召回本来就这水平，尤其中文专业领域，同义词、近义词、歪打正着的语义相似——全给你召回来了。
然后我问他：你们 pipeline 里有没有 rerank 这一步。他说没有，怕贵。
我就说，你知道最贵的是什么吗？是用户看了一次歪答案就流失了。你省的那点 rerank 钱，抵不过一个月掉的 ARR。
你可以把 RAG 召回想象成两阶段：
第一阶段叫 retrieval，图的是召得全。 通常是向量相似度（embedding）+ BM25 关键词混合，扫整个库，捞 top-50 甚至 top-100 回来。这一步要求”宁可错召不可漏召”。
第二阶段叫 rerank，图的是排得准。 把 top-50 做精细打分，输出 top-3 或 top-5 给下游 LLM。
很多团队只做第一阶段，直接 top-10 送进 Claude。问题是 embedding 向量 768 维或 1024 维，做的是粗粒度语义匹配，query 和 chunk 的精细关系它捕捉不到。
举个最简单的例子。query 是”用户怎么取消自动续费”，embedding 会把”自动续费的收费规则””自动续费常见问题””用户注销账号流程”统统召回来，得分相差不到 0.03。这种情况你让 Claude 去文档里找答案，运气好能搞对，运气不好就搞砸。
我现在做项目基本三种里选一种，看场景。
方案 1：cross-encoder 模型（bge-reranker-v2 这类）
开源，自己部署。精度很好，尤其中文。一次 rerank 50 段大概 200ms，单次成本算下来折合 0.0003 美刀（主要是 GPU 电费摊销）。适合有 infra 团队的公司。
缺点是需要维护模型服务，冷启动慢，流量高峰要加机器。小团队头疼。
方案 2：用 LLM 做 rerank（比如 Haiku 4.5）
把 query + 50 个候选 chunk 的 ID 和摘要塞进 Haiku，让它输出排序。我实测一次调用大概 3K input + 100 output token，按 Haiku 定价算下来 0.0008 美刀。
优点是精度出奇的好，而且可以通过改 prompt 让它关注特定维度——比如”优先考虑时效性””优先召回含具体金额的条款”。这种定制在 cross-encoder 里是做不到的。
缺点是延迟比 cross-encoder 大，通常 800ms-1.2s。对实时聊天场景有点压力。
方案 3：LLM rerank + Claude 主力模型
就是上面那个方案，但主力模型用 Sonnet 或 Opus。
我现在 80% 的项目用方案 2+3 的组合。理由很简单：Haiku 做 rerank 的可解释性比任何 cross-encoder 都强，遇到 bad case 你能看到它为什么这么排——让它输出 ranking 的时候顺便说一句 reason 就行。调试起来跟调试人类员工一样。
不是所有系统都值得加 rerank。我列几个不用加的情况：
文档库特别小（< 500 个 chunk）。 直接把所有 chunk 按相关度塞进 context，用 Claude 自己的 attention 筛就行。反正也就几万 token。
query 特别结构化。 比如”查 2025 年 3 月 15 日订单号 A123”，这种直接走 SQL 或者精确匹配，向量都不用。
召回率要求极高，精度要求一般。 比如推荐场景的”相关文章”，用户点不点无所谓，没必要为精度多花一道。
响应延迟极敏感（< 500ms）。 rerank 这一步怎么也要 300ms 起，吃不消就砍掉。
除此之外我基本都会加。尤其客服、问答、法律、医疗这种答错代价高的场景。
贴一下我在一个教育 SaaS 项目里跑的真实配置，服务了他们 84.2 万次月活 query。
第一段：双召回
BM25 捞 top-30，向量捞 top-30，去重合并成 50 左右。这一步只管量，精度靠下一步。
第二段：Haiku 4.5 rerank
prompt 里写清楚评分维度（相关度、时效性、权威度各占几分），让 Haiku 输出 top-5。这一步关键是 prompt 里的评分标准写死，不同 query 类型用不同 prompt——基础问答一套、政策解读一套、案例咨询一套。
第三段：Sonnet 4.5 生成
拿 top-5 作为 context，配合用户 query 生成最终答案。
整条链路一次 query 的成本：向量查询 0.00002 刀 + Haiku rerank 0.0008 刀 + Sonnet 生成 0.015 刀 ≈ 0.016 刀。
对比他们之前单用 Sonnet + top-10 直召的版本（一次 0.022 刀，因为 context 更长），成本还低了 27%，准确率从 74.8% 涨到 89.3%。
Q：rerank 的时候 chunk 要不要截断？
要。我一般只给 rerank 模型每段前 500 token + 后 100 token，中间用 ...省略... 代替。rerank 不需要看完整文本，它判断相关性主要靠开头和结尾。省下来的 token 够你多召 20 个候选。
Q：rerank 阶段要不要告诉模型对话历史？
看场景。单轮问答不需要。多轮对话如果涉及指代（”那个方案””刚才说的那家”），必须把最近 1-2 轮对话摘要喂给 rerank 模型，否则它理解不了 query 在说什么。这个细节我踩过坑，排查了两天才定位到。
Rerank 这一步，看着是个”锦上添花”的优化，实际上是 RAG 能不能落地商业场景的分水岭。
我见过太多团队 POC 阶段效果惊艳，上线真实流量之后口碑崩了——往往就是 retrieval 从 demo 阶段的 100 个 chunk 扩展到 10 万个 chunk，embedding 的粗粒度就遮不住了，rerank 这道防线又没有。
花那 0.0008 美刀吧，真的。
延伸阅读
关于把 Haiku 用在 pipeline 里做轻量任务的更多姿势，看 [Haiku/Sonnet/Opus 选型](/posts/claude-family-haiku-sonnet-opus/)。写 rerank prompt 记得用 XML 结构化输出，参考 [XML 标签的妙用](/posts/prompt-xml-tags-claude-special/)。想把整条 RAG pipeline 的 context 编排思路讲清楚，[从 Prompt 到 Context Engineering](/posts/prompt-to-context-engineering/) 是个好的起点。