不管你的 Agent 跑在哪,你敲的第一个字都不是它读到的第一个字。系统提示、记忆文件、工具描述、环境信息,这些先进窗口,然后才轮到你。
Claude Code 把这笔账公开算过一次,开场大约 7850 个 token,而你自己打的那句话大概 45 个。换成 Cursor、Codex,或者你用 SDK 自己搭的 Agent,数字不一样,结构完全一样。
大部分人一整年都在琢磨那 45 个字怎么写得更好,从来没打开过前面那 7850。
再看两个数。SWE-bench Verified 上,前沿模型一年之内从 30% 冲过了 80%,编码 Agent 是真的变强了,而且是可测量地变强。同一段时间,Gartner 问了 2501 位 CIO 和技术高管,组织里真正把 Agent 部署上线的只有 17%。榜单上能修 issue,公司里跑不起来,中间差的那部分不在模型里。
0xMovez 把差的那部分拆成了 12 步,归到七个名字底下。Context、Tools、Memory、Loops、Graphs、Harness、Evals。排序有讲究,地基在前,执行居中,可靠性压后。
这七块没办法拆开单独学。Context 烂了循环就跑不动,循环没有评测你就不知道它收敛到了哪里,Memory 没有 Harness,会话一断就全蒸发。所以下面 12 步是按依赖关系走的,不是按重要性。
整张地图长这样,你可以先存下来,看完再回来对一遍。
AI Agent 12 步依赖顺序图
一、Context
1、读窗口里真正加载了什么
Karpathy 那个比方到现在还是最好用的。模型是 CPU,上下文窗口是内存。上下文工程要干的事,就是把下一步刚好需要的东西装进内存,多一点都不要。
问题是绝大多数人根本不知道自己的内存里现在装着什么。
Claude Code 里有现成的命令。/context 把当前占用按类别打印出来,告诉你哪几个记忆文件被加载了,也会标出哪次工具调用吃掉的 token 最多。你先盯两个数就够了。一个是记忆文件那一栏,它偏重,基本可以断定项目里的指令文件超重了。另一个是剩余可用空间,它决定你这次会话还能撑多久。配合 /memory 一起看,能直接列出正在生效的具体文件。
别的环境没有这么方便的入口,但这件事到哪儿都能做。用 SDK 自己搭的 Agent,把一次完整请求的消息体打出来,按字段数一遍就有了。Cursor、Codex 这类带项目规则文件的,先量一下规则文件本身有多长,那通常就是最大的一块。
这一步花不了五分钟,但它是后面十一步的前提。你没法优化一个从来没测量过的东西。
2、先砍掉,再分层放回去
Anthropic 在 Claude 5 这一代把 Claude Code 的系统提示删掉了 80% 以上,在自家编码评测上没测出损失。
能删掉这么多还不掉分,是因为大部分上下文的内容本身没错,它只是写给一个更弱的模型看的。模型变强之后,那些叮嘱不再提供任何信息,只消耗 token,而且会逼着模型先花力气去调和其中互相矛盾的地方,然后才能开始干活。
砍的时候有两条规矩能保证安全。
第一条,成块地删,不要一行一行删。删掉一句话带来的差异落在你评测的噪声底线以内,跑完你什么都学不到。
第二条,把绝对命令改写成原则。与其写「永远不要写多行注释」,不如写「代码风格跟着周围的代码走,注释密度、命名、惯用写法都对齐」。规则给的是一个固定答案,原则给的是一个让模型读你仓库自己找答案的办法。仓库会变,固定答案会过期,原则不会。
活下来的内容要放进一棵树,而不是摊成一卷长轴。Anthropic 给的是硬数字,项目级指令文件控制在 200 行以内,只留模型读仓库读不出来的坑。剩下的东西各有各的去处。能封装成 Skill 的做成 Skill,描述在启动时加载,正文等调用时才进来。只跟某类文件有关的规则,就绑定到那个路径上,读到匹配的文件才加载。
这里说的指令文件不止 CLAUDE.md 一种。Cursor 的规则文件、Codex 读的 AGENTS.md、各家自建 Agent 里那份系统级说明,占的是同一个位置,200 行这个上限对它们一样成立。
# payments-api
面向 Web 端的订阅计费与开票。
## Gotchas
// 只写模型读仓库读不出来的东西
- 所有共享类型都在 `src/types.ts`,一个巨型文件,别拆。
- `Money` 是整数分,永远不是浮点。
- Webhook 重试必须幂等,服务商会重放 72 小时。
- `db/legacy/` 已冻结,可以读,不许改。
## 更深的说明
- 验证流程 → `.claude/skills/verify/`
- 发布流程 → `.claude/skills/deploy/`
// 不写这些:目录树、框架名、测试运行器、语言版本。
// 这些模型自己读仓库就知道。
我顺手数了下手上这个写作仓库。根目录 CLAUDE.md 513 行,旁边给 Codex 备的 AGENTS.md 又是 513 行,两份内容几乎重复。「永远不要 / 必须 / 禁止 / 绝不」这类硬话散在其中 17 行里。按 Anthropic 那个 200 行的口径,这份文件超标一倍半,而超出来的部分,大多正是那种写给弱模型的绝对命令。
二、Tools 和 MCP
3、让 Agent 够得着,也挑得中
Agent 通过工具接触真实世界,而工具的描述本身就占着上下文。所以这一步是个铰链,一边连着 Agent 能干成什么,另一边连着它为了知道这些要付出多少窗口。
顺带说清楚一件事,MCP 是开放协议,不是某一家的功能。Claude Code、Cursor、Codex 以及一大批自建 Agent 用的是同一套东西,所以这一节的做法不挑宿主。
以前教工具的做法是给例子。这条建议现在反过来了。面对当前这代模型,例子会把它约束在例子描述的那片探索空间里,反而变窄。更好的做法是把参数设计得有表达力。一个取值为 pending | in_progress | completed 的状态枚举,不用任何例子就讲清了一整套生命周期,类型本身就是文档。Anthropic 在 SWE-bench Verified 上拿到当时的最好成绩,有一部分功劳来自对工具描述的精确打磨,而不是换了模型。
另一件事是延迟加载胜过一次性倒进来。Claude Code 只加载 MCP 工具的名字,大约 120 token,真正的 schema 等到工具搜索命中时再按需取。把检索这套思路用在工具描述上,而不是把所有描述全塞进窗口,选择准确率大约能提到三倍。
这也就决定了描述该怎么写。写清楚这个工具什么时候该用,而不只是写它是什么。 那句「什么时候用」才是被搜到的入口,Agent 找不到的工具,等于你没交付。
@mcp.tool()
def find_stalled_shipments(hours: int = 24) -> list[dict]:
"""N 小时内没有任何扫描记录的运单。
当运营问「哪些卡住了」,或者升级评审开始之前,用这个。"""
return query(STALLED_SQL, hours)
@mcp.tool()
def reroute(shipment_id: str, hub: str, reason: str) -> dict:
"""改派一张运单,会写一条审计记录。
合规要求每次人工干预都得有理由。"""
return post_with_audit(shipment_id, hub, reason)
# 「当……时用这个」是工具搜索的发现面。
# reason 是必填参数,所以审计链路没法被跳过。
# 类型能强制的事,写一整段说明也只能是请求。
你手上那些接进来却几乎没被选中过的工具,问题大概率就在描述的第一句话。
三、Memory
4、窗口之外还剩下什么
任何长任务最终都会超出一个窗口。窗口边界上发生什么,是一个设计决策,而大多数人从来没做过这个决策。他们让自动压缩去猜,然后奇怪为什么 Agent 忘掉了一小时前刚说过的约束。
下面这套机制是 Claude Code 公开出来的版本,各家实现的细节不一样,但边界上到底保留什么、丢掉什么,每个跑长任务的 Agent 都得自己回答一遍。拿它当参照,去查你手上那个的对应行为。
项目根目录的指令文件和自动记忆是从磁盘重新注入的,压缩之后还在。但用 paths: 限定作用域的规则,以及嵌套在子目录里的 CLAUDE.md,活在消息历史里,会被摘要掉,而且不会自己回来,要等到再次读取匹配的文件才重新加载。被调用过的 Skill 正文会回来,但有上限,单个 Skill 5k,总共 25k,超了就丢最旧的,而且是从尾部截断。所以关键内容要放在 SKILL.md 的最上面,放末尾等于放在最容易被切掉的位置。
最靠得住的办法很土,也是计算机里最古老的那个,写到文件里。
一份计划文件,一份进度日志,一些让 Agent 边干边改的笔记。它不占窗口,它在磁盘上,所以压缩杀不掉它。压缩本身也可以主动做,/compact focus on the auth bug 能保住你指定的东西,而 /clear 被严重低估了,下一个任务跟前面二十条消息没关系的时候,清掉就好。
四、Loops
5、停止条件必须写在模型外面
一个 Agent 循环是行动、观察、判断、再来一遍。全部工程难度都在最后那步,它怎么知道自己干完了。
放任模型自己判断,它会朝两个方向出错。一个方向是活干了一半就宣布胜利,另一个方向是三轮之前就已经做完的事还在那儿磨。
这两种都不是换个更好的提示词能修的,因为它们是结构性的。停止条件应该写在代码里,放在模型的判断力之外。任务边界清楚的时候,那就是一道测试门禁或者一次 schema 校验。规模未知的探索型任务,收敛靠的是「跑到没东西为止」,也就是连续 K 轮都没有发现新东西才停。
这里有个细节决定成败,几乎所有人第一次都写反。去重要对着「所有见过的」去重,不是对着「已确认的」。 反过来写的话,被否掉的发现每一轮都会重新冒出来,循环永远跑不干,你造出来的是一台永远在付钱重新发现同一批死胡同的机器。
const seen = new Set(); const confirmed = []; let dry = 0;
while (dry < 2) { // 连续两轮空,停
const found = await runFinders();
const fresh = found.filter((b) => !seen.has(key(b)));
if (!fresh.length) { dry++; continue; }
dry = 0;
fresh.forEach((b) => seen.add(key(b)));
// ↑ 对 seen 去重,不是对 confirmed。
// 写反了,这个循环永远不会终止。
confirmed.push(...(await verify(fresh)));
}
6、谁来验证答案
一个会收敛的循环,收敛到的仍然是模型自己相信的东西。
补这个洞要靠验证者,一个站在模型判断之外、唯一职责就是试图杀掉这条发现的东西。活下来才算通过,没活下来就根本到不了最终答案里。
有三种模式值得随手拿来用。
对抗式验证,给每条发现派 N 个互相独立的怀疑者,唯一任务就是驳倒它,多数没驳倒才保留。
视角分离式验证,给每个验证者一个不同的镜头,正确性、安全性、能不能复现。视角多样能抓到的失败模式,N 个一模一样的检查永远抓不到。
评审团,从不同角度生成 N 个方案,用并行的评审打分,从赢的那个往下做,同时把亚军里的好东西移植过来。
› 每条发现派三个验证者,正确性、安全性、可复现性。三中过二才收。
● 6 条发现 → 18 个验证 Agent 并行
✓ /invoices/:id 缺鉴权 3/3 收
✓ webhook 重试存在竞态 2/3 收
● 「校验器里的不安全正则」 0/3 杀
● 「dashboard 的 N+1 查询」 1/3 杀
六条里有两条是自信且错误的。抓住它们的是循环,不是你的评审同事,也不是你的用户。
注意这一步指向哪里。验证者其实就是一个内联跑的评测,跟第 11 步是同一套纪律,只不过一个按结果跑,一个按发布跑。把验证者做扎实的团队,后面做评测会轻松很多,因为「什么算好」他们已经写下来过一次了。
五、Graphs
7、哪些活其实能同时干
大部分人写 Agent 是写成一条直线的。一个节点跑完才轮到下一个,后面的礼貌地等着前面的。然后才发现,其中一半的等待压根没必要。
节点是一个工作单元,边的意思是这个输出喂给那个输入。没有数据穿过去,就没有边,那个等待就是纯粹的浪费。
最常用的形状是菱形。扇出去铺开广度,用普通代码做归并,最后交给一个 Agent 做综合。归并这一步值得单独强调,因为钱通常漏在这儿。摊平和去重是 flatMap 加一个 Set 就能干的事,不是一个 Agent 该干的事。边不要钱,Agent 要钱,钱要花在判断上,不要花在管道上。
上限比想象中高得多。Claude Code 的动态工作流能在一次运行里协调最多 1000 个并行子 Agent,而且编排本身不消耗任何模型 token,因为它是一段脚本,不是一场对话。
有个团队用这套架构,六天里把 Bun 运行时大约 96 万行代码从 Zig 迁到了 Rust,测试套件仍有 99.8% 通过。
8、形状会让你花多少钱
拓扑不是装饰,它是你手上对延迟和开销影响最大的那根杠杆,而且主要由两个选择决定。
第一个是 parallel() 还是 pipeline()。parallel() 是一道栅栏,所有东西都得等最慢的那个节点跑完,下一阶段才开始。pipeline() 让每个条目独立地穿过所有阶段,A 可以已经在第三阶段,B 还在第一阶段。默认应该用 pipeline,只有当某个阶段确实需要一次性拿到全部先前结果时才上栅栏,比如做跨集合去重。「感觉这样更整齐」不是理由,栅栏带来的延迟是实打实的、可测量的浪费时间。
第二个是按节点分配模型档位。每个子 Agent 默认继承你会话的模型,脚本不覆盖的话,一次大规模运行会整个按你的最高档计费。那些边界清楚、重复性高的节点,抽个字段、给工单分类这种,应该放在便宜的模型上,而真正需要判断力的归并节点留在高档。一百个便宜的扇出节点喂给一个高档的综合节点,成本只是同一个任务平铺跑的一个零头,最终质量却没有区别。
六、Harness
9、开工之前先把环境搭好
Anthropic 对这个问题的描述很准确。一个长任务像一个轮班制的软件项目,每来一个新工程师,都完全不记得上一班发生了什么。
光靠压缩解决不了。哪怕是前沿模型,跨着多个上下文窗口去做「造一个 claude.ai 的克隆」,最后也做不成,而且失败方式是两种具体的、可重复出现的形态。
第一种,Agent 想一口气把整个应用做完,做到一半上下文用光,留给下一次会话一个做了半截、没有任何文档的功能,等着被考古。第二种发生在项目中后期,Agent 环顾四周,看到确实有不少进展,于是宣布任务完成。
这两种都要在写第一行代码之前就解决掉,靠的是一个只跑一次的初始化 Agent,它负责把环境建起来。一个能拉起开发服务器的 init.sh,一份进度日志,一次初始的 git 提交,还有一份 JSON 格式的功能清单。claude.ai 那个克隆项目的清单有 200 多条,每一条初始状态都是不通过。
{
"category": "functional",
"description": "新建对话按钮能开出一个全新会话",
"steps": [
"进入主界面",
"点击「New Chat」按钮",
"确认新会话已创建",
"检查聊天区域显示欢迎态"
],
"passes": false
}
这样的条目 200 多条,全部从 false 开始,Agent 只被允许把 passes 翻成 true。原文里那句「删除或修改测试是不可接受的」措辞故意写得很重,因为一个能改规格的模型,就一定会去改规格。
还有一个细节值得直接抄走。他们给这份清单选了 JSON 而不是 Markdown,因为模型不恰当地重写 JSON 的概率明显更低。
10、一次会话只推进一个增量
环境搭好之后,每一次编码会话都拿到同一份契约。先搞清楚现状,挑出恰好一个功能,像用户那样验证它,最后把仓库留干净。
这里的「干净」跟真实团队里的意思一样。没有重大 bug,代码有条理,下一个人接手时不需要先替别人擦屁股。
进场那套动作是机械的,但每次都省 token。pwd,读进度文件,读 git log,读功能清单,跑 init.sh,然后在动任何东西之前先测一遍基础功能还正常。最后这一项比听起来重要得多,少了它,Agent 会在一个已经坏掉的应用上开始新功能,只会把窟窿捅得更深。
关于「标记完成」还有一条。模型的天然倾向是改完代码,跑几个单元测试,然后就宣布搞定,从头到尾没有端到端地看过这个功能。所以要给它真正的测试工具,并且要求它像人类用户那样验证,浏览器自动化,真实点击。Anthropic 的实验里,光是加上这一条要求,表现就有大幅提升,抓到了很多只看代码根本发现不了的 bug。
七、Evals
11、先做 20 到 50 个任务
崩盘的时刻永远是同一句话。用户反馈说改完之后 Agent 变差了,而团队除了猜和试之外没有任何验证手段。
没有评测,调试就是被动的。等投诉,手动复现,修掉,然后祈祷没有别的地方跟着退化。真实的退化和随机噪声,你分不出来。
起步规模可以比你想的小得多。很多团队一直拖着不做,是因为想象中需要几百个任务,实际上从真实故障里挑 20 到 50 个就是很好的开始,因为早期的改动效果量很大,几十个任务足够把信号打出来。
素材从你已经在手动测的东西里拿,从 bug 追踪系统里拿,从客服工单里拿。写的时候要保证两位领域专家分别去判,能独立得出同一个结论,任务里的歧义会原封不动变成指标里的噪声。集合还要平衡,既要测某个行为该触发的场景,也要测它不该触发的场景,否则你会优化出一个见什么都要搜一遍的 Agent。
评分器要有意识地混着用三种。代码判定快、便宜、客观,能用就用。模型判定用来处理代码抓不住的细微差别,评分标准要拿人类结果校准过,最好一个维度一个独立评审,而不是一个评审给所有维度打分。人工判定是金标准,省着用,用来校准前面两种。
还有一条,判产出,不判路径。去检查工具调用是不是走了某个精确序列,这种判定极其脆弱,因为 Agent 经常会找到你没预料到但完全成立的做法。
task:
id: "fix-auth-bypass_1"
desc: "修复密码字段为空时的鉴权绕过"
graders:
- type: deterministic_tests # 快、客观、可复现
required: [test_empty_pw_rejected.py]
- type: llm_rubric # 测试抓不到的细微差别
rubric: prompts/code_quality.md
- type: static_analysis
commands: [ruff, mypy, bandit]
- type: state_check # 看结果,不看它怎么说
expect: { security_logs: { event_type: "auth_blocked" } }
tracked_metrics:
- type: transcript
metrics: [n_turns, n_toolcalls, n_total_tokens]
Agent 说「修好了」,state_check 决定它到底有没有修好。
12、别让这个数字骗你
一套没人读的评测,产出的是一个不该被信任的数字。
你不读多次运行的完整轨迹,就不会知道自己的评分器有没有问题。一个任务失败的时候,轨迹会告诉你,是 Agent 真的犯了错,还是你的评分器拒绝了一个本来成立的解法。失败应该让人觉得公道,一眼能看出错在哪、为什么错。
有两个陷阱专门让好 Agent 显得很差。
第一个是通过率 0%。多次试验全军覆没,通常意味着任务本身是坏的,而不是 Agent 没能力。Opus 4.5 在 CORE-Bench 上最初只有 42%,后来有研究者去查,发现评分僵硬到期望值是「96.124991…」时会把「96.12」判错,另外还有描述含糊的任务和根本无法复现的任务。这些修完之后,分数是 95%。
第二个陷阱方向相反,叫饱和。评测跑到 100% 之后,它还能追踪退化,但不再给你任何可爬的坡,真实的能力提升会开始表现为噪声。
然后要把两个指标分清楚。pass@k 是 k 次尝试里至少成功一次的概率,k 越大它越高。pass^k 是 k 次全都成功的概率,它掉得很快。单次 75% 的成功率,连着三次全过只剩大约 42%。一次成功就够的场景用 pass@k,任何面向客户的东西都要用 pass^k,因为用户的预期是每次都能用。
最后一步是把它变成例行公事。把评测套件接进 CI,每次改动跑一遍,每次模型升级跑一遍。一个新模型发布,从此不再是几周的手工测试,而是跑一遍套件、读一下差异的一个下午。
八、七条可以直接粘的提示词
七个部分各挑一件今天就能做的事。第一条是 Claude Code 的命令,其余六条是普通提示词,粘到哪个 Agent 里都能跑。
打开你从来没看过的那个窗口,先量再砍。记忆文件那一栏偏重,基本就是项目指令文件超重了。
/context 然后 /doctor
审一遍工具描述。每条描述都得说清什么时候该用它,不能只说它是什么。
把这个 MCP 服务里每条工具描述都过一遍,每条补一句「当……时用这个」,同时把参数类型收紧。
把状态挪到文件系统上。让 Agent 维护一份自己边干边改的计划文件,它在磁盘上,所以压缩杀不掉它。
开工前先把计划写进 plan.md,每完成一步就更新它。任何时候恢复工作,先重新读一遍。
给循环加一个验证者。挑一个 Agent 自己判断「我干完了」的任务,加一道外部检查,看看第一版答案有多少经不起三个怀疑者。
每修完一处,派三个验证者,分别看正确性、安全性、可复现性。三中过二才算通过。
把一条直线任务改成扇出。找一个你现在还在挨个循环处理文件或数据源的任务,改成一项一个 Agent 同时跑,最后归并一次。墙钟时间的差别就是全部要讲的东西。
跑一个工作流,审计 src/routes/ 下的每个路由。一个文件一个 Agent,每条发现先验证再汇报,最后综合。
给多会话项目搭脚手架。开始长期开发之前,先让 Agent 把环境建好。
以初始化 Agent 的身份工作,写出 init.sh、claude-progress.txt,以及覆盖全部需求的 feature_list.json,所有条目 passes 都设为 false。
把上周的 bug 变成一套评测。打开你的 bug 追踪系统,把真实故障改写成 20 个判定标准明确的任务。
这里是 20 个真实故障。把每一个写成评测任务,能用确定性评分器的就用,不能的写评分标准。
九、模型会自己变强,别的不会
Demo 谁都能跑起来,难的是 Demo 之后的所有事情。
模型按它自己的节奏在变强,这部分改进是免费的,你做不做都会到。不会免费到来的是模型外面那套系统。上下文保持精简,工具让 Agent 挑得出来,记忆能活过窗口,循环会收敛而且有人验,图是扇出去的而不是排队的,Harness 让下一次会话接得上上一次,最后有一个数告诉你这一切到底有没有变好。
很多人会继续等一个好到不需要这些东西的模型。
要是只挑一件今天做,就挑第一步。不管你手上是 Claude Code、Cursor、Codex 还是自己搭的那套,去看一眼你敲字之前窗口里已经装了什么,五分钟出结果,而且大概率会让你意外。
参考链接
- AI Agent Engineer in 2026:12 steps roadmap(0xMovez):https://movez.substack.com
- Anthropic — Claude Code Best Practices:https://www.anthropic.com/engineering/claude-code-best-practices
- Anthropic — Writing effective tools for agents:https://www.anthropic.com/engineering/writing-tools-for-agents
- Anthropic — Demystifying evals:https://www.anthropic.com/engineering/demystifying-evals
- Gartner 2026 CIO and Technology Executive Survey(n=2501):https://www.gartner.com/en/newsroom
- Model Context Protocol 官方规范(开放标准,多工具共用):https://modelcontextprotocol.io