这是完整的 12 步路线图，涵盖真正决定智能体能否工作的七大支柱：上下文、工具、记忆、循环、图、开发框架、评估——每一步都有验证其有效性的 Claude 工作流。
前沿模型在 SWE-bench Verified 上的成绩一年内从 30% 提升到超过 80%。编码智能体取得了显著且可衡量的进步。
与此同时，只有 17% 的高管表示他们已在公司全面采用 AI 智能体。
智能体失败的根源在于上下文膨胀。因为循环永远无法收敛。因为没有人能衡量上周的改动是否让任何方面变得更好。演示在你的机器上能跑。生产环境则是另一回事。
这是 12 步路线图，贯穿将两者区分开的七大支柱——每一步都有各自的失败模式、各自的 Claude 工作流，以及如果你跳过它就会悄然毁掉你的智能体的方式。
这是一个重新框架，让其余内容变得连贯。这不是七种独立的技能，而是同一种技能在七个维度上的投影。
- 糟糕的上下文会破坏循环。
- 没有评估的循环永远不会收敛到你能信任的任何东西上。
- 没有评估的图会放大你的错误，而不是提升你的吞吐量。
- 没有开发框架的记忆会在会话结束时瞬间蒸发。
- 没有上下文管理的工具会在工作开始前就让窗口过载。
这意味着孤立地学习它们没有用处——但存在一个依赖顺序，先打基础，再执行，最后才考虑可靠性。这正是这十二步的排列方式。
01. Context（上下文）——读取真正加载的内容
卡帕西的框架值得铭记：模型是 CPU，上下文窗口是 RAM。上下文工程的艺术在于，用下一步恰好需要的内容填充那段 RAM——不多不少。
一个重新定义一切的数值：在 Claude Code 中，在你输入第一个字符之前，大约会加载 7,850 个 token——系统提示词、自动记忆、技能描述、CLAUDE.md、环境信息、MCP 工具名称。
你实际的提示词只有大约 45 个 token。所有人都在优化那 45 个，却从未打开那 7,850 个。
/context 会按类别打印你的真实细分，告诉你哪些记忆文件被加载，并标记哪个工具调用消耗了最多 token。
两个需要关注的数值：记忆文件（过大意味着 CLAUDE.md 过于臃肿）和可用空间。将其与 / memory 配对，就能看到具体涉及哪些文件。
02. Context（上下文）——先精简，再分层
Anthropic 为 Claude 5 一代删除了 Claude Code 系统提示词中超过 80% 的内容，而他们的编码评估没有出现任何损失。
大多数上下文并非错误——而是为更弱的模型编写的指导，如今只会消耗 token，并迫使 Claude 在开始前先调和矛盾。
两条规则让精简变得安全：
- 按块删除，而不是按行删除——单独一句话淹没在评估的噪声中，无法提供任何信息。
并将绝对规则转化为原则：与其说 “永远不要写多行注释”，不如说*写出像周围代码一样易读的代码——匹配其注释密度、命名习惯和惯用风格。
*规则给出固定答案，而原则让 Claude 通过阅读你的仓库找到正确答案。
- 留存下来的内容应放入树形结构，而不是一长条滚动文本。Anthropic 的指导是一个硬性数字：保持项目 CLAUDE.md 在 200 行以内，只包含 Claude 无法推断的陷阱。
其余内容全部变成技能（描述在启动时加载，正文在调用时加载）或路径限定规则（仅在读取匹配文件时加载）。
# payments-api
Subscription billing and invoicing for the web app.
## Gotchas
// Non-obvious. Claude cannot infer these by reading the repo.
- All shared types live in `src/types.ts` — one monolithic file.
- `Money` is integer cents, never a float.
- Webhook retries must stay idempotent — provider replays for 72h.
- `db/legacy/` is frozen. Read it, never edit it.
## Deeper guides
- Verification → `.claude/skills/verify/`
- Releases → `.claude/skills/deploy/`
// NOT here: directory tree, framework, test runner, language
// version. Claude reads those from the repo itself.03. Tools & MCP（工具与 MCP）——智能体能够触及的范围
工具是智能体接触世界的方式，而它们的描述也是上下文——这就让这成为智能体能做什么和它负担得起了解什么之间的枢纽。
旧建议是用示例来教授工具。
这已反转：对于当前模型，示例会把 Claude 限制在它们所描述的探索空间内。应设计富有表达力的参数。
一个包含 pending | in_progress | completed 的状态枚举，无需任何示例就能教会整个生命周期——类型本身就是文档。
Anthropic 在 SWE-bench Verified 上达到最先进水平，部分归功于对工具描述的精准优化，而非模型改动。
而且延迟加载胜过一次倾倒。Claude Code 只加载 MCP 工具名称——约 120 个 token——通过工具搜索按需获取模式。
对工具描述应用检索而不是全部加载，可将选择准确率提升大约三倍。
这使描述成为发现界面：要说工具何时适用，而不仅仅是它做什么。一个 Claude 找不到的工具，就是你没有交付的工具。
@mcp.tool()
def find_stalled_shipments(hours: int = 24) -> list[dict]:
"""Shipments with no scan event in N hours.
Use when ops asks what is stuck, or before an escalation review."""
return query(STALLED_SQL, hours)
@mcp.tool()
def reroute(shipment_id: str, hub: str, reason: str) -> dict:
"""Reroute a shipment. Writes an audit row — compliance
requires a reason on every manual intervention."""
return post_with_audit(shipment_id, hub, reason)
# "Use when..." is the discovery surface for tool search.
# `reason: str` is required, so the audit trail cannot be skipped.
# The type enforces what a paragraph of instructions would only ask for.04. Memory（记忆）——什么能在窗口之外存活
每个长任务最终都会超出单个窗口。
在那个边界发生什么，是一个大多数人从未做出的设计决策——他们让自动压缩去猜测，然后奇怪为什么智能体忘记了在一小时前明确陈述的约束。
具体机制值得牢记。项目根目录的 CLAUDE.md 和自动记忆会从磁盘重新注入。
但使用路径作用域的规则和嵌套的 CLAUDE.md 文件存在于消息历史中——它们会被摘要清除，并且直到再次读取匹配文件前不会回来。
调用的技能正文会返回，上限为每个技能 5k，总计 25k，最旧的先丢弃，并从末尾截断——因此任何关键内容都应放在 SKILL.md 的顶部。
可靠的做法是计算领域最古老的那招：写到文件里。
计划文件、进度日志、智能体在过程中重写的笔记。它持久存在且不占用上下文窗口，因为它在磁盘上，所以能挺过压缩。
也要有意识地压缩——/compact focus on the auth bug 会保留你选择的内容，而当下一个任务不依赖最后二十条消息时，/clear 被严重低估了。
05. Loops（循环） - 何时停止
智能体循环是行动→观察→决定→重复。整个工程问题就在最后一步：它怎么知道自己完成了？
放任不管的话，模型会在两个方向上表现糟糕——在完成一半的工作上宣布胜利，或者在三个迭代前已完成的事情上永远磨蹭。
这两者都不是靠更好的提示词能解决的，因为都是结构性的。停止条件应放在模型判断之外的代码中。对于有界的工作，那是测试门或模式检查。
对于未知规模的探索，收敛模式是循环直到枯竭（loop-until-dry）：持续进行，直到连续 K 轮都没有新内容。
一个细节决定成败，几乎每个人第一次都会搞错：对看到的一切去重，而不是对已确认的结果去重。
否则被拒绝的发现每一轮都会重现，循环永远不会枯竭，你就造了一台永远为重新发现同样的死胡同而付费的机器。
const seen = new Set(); const confirmed = []; let dry = 0;
while (dry < 2) { // stop after 2 empty rounds
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)));
// ^ dedupe against SEEN, not against confirmed.
// Backwards, and this loop never terminates.
confirmed.push(...(await verify(fresh)));
}06. Loops（循环） - 谁检查答案
收敛循环仍然收敛于模型所相信的内容。解决方案是一个验证器——一个独立于模型自身判断的东西，它的唯一任务就是试图推翻发现。
如果它存活下来，就通过。如果没有，就永远不会到达答案。
有三种值得掌握的范式：
- 对抗性验证：对于每个发现，生成 N 个独立的怀疑者，提示他们反驳它；只有当多数存活时才保留。
- 视角多样性验证：给每个验证器一个不同的视角——正确性、安全性、是否可复现——因为多样性能够捕获 N 次相同检查永远无法捕获的失败模式。
- 评审团：从不同角度生成 N 个尝试，用并行评审打分，从获胜者中综合，同时嫁接亚军的精华。
› For each finding, spawn three verifiers - correctness, security, reproducibility. Accept only what survives two of three.
● 6 findings → 18 verifier agents, running in parallel
✓ missing auth on /invoices/:id 3/3 — accepted ✓ race in webhook retry 2/3 — accepted
● "unsafe regex in validator" 0/3 — killed
● "N+1 query in dashboard" 1/3 — killed 2 of 6 findings were confident and wrong. The loop caught them, not your reviewer, and not your users.注意这指向哪里。验证器是一个内联运行的评估——与第三层的纪律相同，应用于每个结果而不是每次发布。构建良好验证器的团队会发现第 11 步容易得多，因为他们已经写下了 “好” 意味着什么。
07. Graphs（图） - 什么并行运行
大多数人把智能体写成一条直线——第一步、第二步、第三步，每一步都礼貌地等待上一步。然后他们发现其中一半步骤根本不需要等待。
节点是工作单元，边意味着这个输出流入那个输入。 如果没有数据交叉，就不存在边——等待就是纯粹的浪费。
主力形状是菱形：扇出以收集广度，用普通代码归约，用一个智能体综合。
归约步骤值得强调，因为那是花钱的地方——展平和去重是 flatMap 和 Set，而不是智能体。
边是免费的。把智能体花在判断上，而不是管道上。
上限确实很高。Claude Code 的动态工作流一次运行可协调多达 1,000 个并行子智能体，编排成本为零模型 token，因为它是脚本，不是对话。
› Run a workflow to audit every route under src/routes/ for missing
auth. One agent per route file, verify each finding before reporting. ●
Claude wrote an orchestration script · launching… ✓ Scope 1/1 ✓ Fan-
out 18/18 one agent per file ◯ Verify 11/18 3-vote skeptics per finding
○ Synthesize 0/1 your session stays responsive — the fleet runs in the
background正是这种架构让一个团队在六天内将约 96 万行 Bun 运行时从 Zig 移植到 Rust，且 99.8% 的测试套件仍然通过。
08. Graphs（图） - 形状让你付出什么代价
拓扑不是装饰性的——它是你在延迟和花费上最大的杠杆，两个选择承担了大部分。
第一，parallel () 与 pipeline ()。一个 parallel () 屏障让所有等待最慢的节点，然后下一阶段才开始。
pipeline () 让每个项目独立地流过所有阶段——项目 A 可以在阶段 3，而 B 还在阶段 1。
默认使用 pipeline。只有当某个阶段确实需要所有先前结果同时可用时，才使用屏障，比如跨集去重。“感觉更干净” 不是理由；屏障延迟是真实的、可测量的、浪费时间。
第二，每个节点的模型分层。每个子智能体都继承你的会话模型，除非脚本覆盖它，所以一次大规模运行默认全部按你的最高层级计费。
有界的、重复的节点——提取这个字段、分类这个工单——应该放在更便宜的模型上，而真正需要判断的合并节点保持高端。
一百个便宜的扇出节点喂给一个顶级综合，成本只是同一任务平铺运行的一小部分，最终质量相同。
09. Harness（驾驭） - 在会话死亡中幸存
Anthropic 完美地表述了这个问题：一个长任务是一个由轮班工作的工程师组成的软件项目，每个新工程师到达时都没有上一班的记忆。
仅靠压缩并不能解决。即使是前沿模型在上下文窗口上循环执行 “构建 claude.ai 的克隆” 也会失败——而且它以两种具体的、可重复的方式失败。
首先，智能体尝试一次完成应用，在实现中途耗尽上下文，留给下一个会话一个半成品、没有文档的功能去逆向工程。
第二，在项目后期，智能体环顾四周，看到真正的进展，然后宣布工作完成。
两者都在编码开始前固定，由一个初始化智能体运行一次并构建环境：一个启动开发服务器的 init.sh、进度日志、初始 git 提交，以及一个 JSON 格式的功能列表——对于 claude.ai 克隆有超过 200 个条目，每个都标记为失败。
{
"category": "functional",
"description": "New chat button creates a fresh conversation",
"steps": [
"Navigate to main interface",
"Click the 'New Chat' button",
"Verify a new conversation is created",
"Check that chat area shows welcome state"
],
"passes": false
}
// 200+ of these, all starting false. Agents may ONLY flip `passes`.
// "It is unacceptable to remove or edit tests" — deliberately strong
// wording, because a model that CAN edit the spec WILL edit the spec.一个值得直接借鉴的细节：他们选择 JSON 而非 Markdown 来存储该列表，因为模型被测量出不太可能不当地改写 JSON。
10. Harness（每次会话一个增量）
环境搭建好后，每次编码会话都有一个契约：定位、只挑选一个功能、像用户一样验证、保持仓库干净。
“干净” 的意思和真实团队中的一样——没有重大 bug、代码有序、下一个工程师无需清理别人的烂摊子就能开始工作。
定位仪式是机械性的，每次都节省 token：pwd、读取进度文件、读取 git 日志、读取功能列表、运行 init.sh，以及在改动任何东西之前测试基本功能是否仍然正常。
最后一项检查比听起来更重要——没有它，在损坏的应用之上开始新功能的智能体只会让破坏更严重。
关于标记完成：Claude 的倾向是完成一个更改、运行一些单元测试，然后宣布完成，从不端到端地检查功能。
[Assistant] Getting my bearings on the current state. [Tool] bash —
pwd [Tool] read — claude-progress.txt [Tool] read — feature_list.json
[Tool] bash — git log --oneline -20 [Tool] bash — ./init.sh start the dev
server [Assistant] Verifying fundamentals before touching anything… ✓
core chat, theme switching, conversation loading all pass [Assistant]
Picking the highest-priority failing feature. no guessing. no
archaeology. the previous shift left notes.给它真实的测试工具，并要求它像人类用户那样验证——浏览器自动化、实际点击。
这一单一要求在 Anthropic 的实验中显著提升了性能，捕获了仅从代码中看不到的 bug。
11. Evals（一个数字，而非一种感觉）
突破点总是同一句话：用户报告智能体在更改后感觉更差，而团队除了猜测和检查外无法验证。
没有评估，调试就是被动的——等待投诉、手动复现、修复、希望没有其他回归。你无法区分真正的回归和噪声。
从比你想象的小开始。团队之所以拖延，是因为他们想象需要数百个任务；从真实失败中提取的 20–50 个就是一个很好的起点，因为早期更改的效应量很大。
![图片展示了单轮与Agent评估的对比。单轮评估中，提示“一只\[动物\]有多少只脚？”数据为“ANIMAL = Cat”，LLM生成“18”，评分逻辑为“18”。Agent评估中，工具包括web_search_tool()等，环境为python安装、dev环境设置等，任务是写一个MCP服务器连接应用，Agent执行read_file()等操作，最后评分逻辑为“运行大量测试以确保MCP服务器正常工作”。该图直观呈现了两种评估方式的差异。](https://media.fange-kb.cn/assets/b5/b5c84487016764bce2eeffbfaaf987c9449c3a1e5e8dd15aa35a619dfb2e96cf/original.jpg)
从你已经在手动测试的内容、你的 bug 追踪器、你的支持队列中提取它们。编写它们，使得两位领域专家会独立得出相同的结论——任务中的模糊性会变成指标中的噪声。
并构建平衡集合：测试行为应该触发和不应该触发的地方，否则你会优化一个什么都搜索的智能体。
故意组合三种评分器类型。
- 基于代码——快速、廉价、客观；尽可能使用。
- 基于模型——用于细微差别的评分标准，根据人类进行校准，理想情况下每个维度一个独立的评判者，而不是一个评判者给所有东西评分。
- 人工——黄金标准，谨慎使用以校准其他方法。
并且评分智能体产生的结果，而不是它采取的路径：检查工具调用的确切序列是脆弱的，因为智能体经常找到你未预料到的有效方法。
task:
id: "fix-auth-bypass_1"
desc: "Fix authentication bypass when password field is empty"
graders:
- type: deterministic_tests # fast, objective, reproducible
required: [test_empty_pw_rejected.py]
- type: llm_rubric # nuance tests can't capture
rubric: prompts/code_quality.md
- type: static_analysis
commands: [ruff, mypy, bandit]
- type: state_check # the OUTCOME, not the claim
expect: { security_logs: { event_type: "auth_blocked" } }
tracked_metrics:
- type: transcript
metrics: [n_turns, n_toolcalls, n_total_tokens]
# The agent says "fixed". The state_check decides whether it was.
# Grade outcomes, not announcements.12. Evals（保持数字的真实性）
没人读的测试套件就是没人该信的数字。除非你阅读多次试验的记录，否则你不会知道你的评分器是否有效——当任务失败时，记录会告诉你智能体是犯了真正的错误，还是你的评分器拒绝了一个有效的解决方案。
失败应该让人感到公平：清楚哪里出错了以及为什么。
两个陷阱会让好的智能体看起来很差。
- 多次试验中 0% 的通过率通常意味着任务损坏，而不是智能体无能。 Opus 4.5 最初在 CORE-Bench 上得分为 42%——然后一位研究人员发现僵化的评分标准拒绝了 “96.12”（而预期是 “96.124991…”）、模糊的规格说明和不可复现的任务。修复之后：95%。
- 相反的陷阱是饱和——一个 100% 的评估可以追踪回归，但不会给你攀登的山丘，真正的能力提升开始表现为噪声。
然后区分两个指标。pass@k 是 k 次尝试中至少成功一次的概率——它随 k 上升。pass^k 是所有 k 次都成功的概率——它迅速下降。每次尝试 75% 时，三次尝试全部通过仅为约 42%。
在只需要一次成功的地方使用 pass@k；对于任何面向客户的内容，使用 pass^k，因为用户期望它每次都有效。
› Run the suite against the new model and compare to baseline. ● 47
tasks × 3 trials · 141 runs · parallel capability suite pass@1 61% → 74%
+13 regression suite pass@1 99% → 99% held consistency pass^3
52% → 68% +16 ● 2 regressions: refund_partial, escalation_tone →
transcripts written to ./eval-results/failures/ the upgrade decision
took an afternoon, not three weeks最后，让它成为日常。将套件接入 CI，使其在每次更改和每次模型升级时运行。
这能将新模型发布从数周的手动测试变成一天内运行你的套件并阅读差异——这是没有评估的团队永远无法追赶的复利优势。
7 jobs to run with Claude（每个支柱一个）
- *打开你从未看过的窗口。* 先测量，再削减。大量的内存文件数字意味着 CLAUDE.md 过重——一个命令就能诊断，一个下午就能修复。
› /context 然后 /doctor
- *审计你的工具描述。 每个描述都应说明工具何时适用*，而不仅仅是它做什么。这句话是发现面——没有它，一个已连接的工具就是 Claude 永远不会选择的。
› 审查这个 MCP 服务器中的每个工具描述。为每个添加一个 “使用时机” 句子，并收紧参数类型。
- *将状态移到文件系统上。 让 Claude 维护一个它在工作时重写的计划文件。它因存在于磁盘上而能抵御压缩*——长任务不再中途迷失方向。
› 开始前，将计划写入 plan.md，并在每一步后更新。每当恢复时重新阅读。
- *在你的循环中放置一个验证器。 选择任何由 Claude 自行决定完成的任务。添加一个外部检查*，看看第一个答案在三个怀疑者中存活的频率有多低。
› 每次修复后，生成三个验证器——正确性、安全性、可复现性。只接受三个中存活两个的结果。
- *将一个线性任务变成扇出。 找到一个你顺序循环处理文件或源的任务。每个项目一个智能体，同时运行*，然后一次合并。墙钟时间差异就是全部教训。
› 运行一个工作流来审计 src/routes/ 下的每个路由。每个文件一个智能体，验证每个发现，然后综合。
- *搭建一个多会话项目。 在长构建之前，让 Claude 编写 init.sh、进度日志，以及一个 JSON 功能列表，所有项都标记为失败。*
› 充当初始化智能体：编写 init.sh、claude-progress.txt 和 feature_list.json，覆盖所有需求，全部 pass:false。
- *将上周的 bug 变成一个套件。 打开你的 bug 追踪器，将真实失败转化为 20 个具有明确通过标准的任务。* 那个套件比你这个季度能采用的任何框架都更有价值。
› 这里有 20 个真实失败。将每个编写为评估任务，可能时使用确定性评分器，否则使用评分标准。
Conclusion: （结论）
任何人都能做出一个能跑的演示。真正的活儿全在那之后。
模型会按自己的节奏不断变好，而这种进步是免费的——无论你做了什么，它都会到来。
不免费的是模型周围的系统。
- 保持精简的上下文。智能体能真正从中选择的工具。
- 能跨越窗口的记忆。能收敛并被检查的循环。
- 能扇出而非排队等待的图。能让下一个会话继续上一个会话的框架。以及一个能告诉你这一切是否有改善的数字。
大多数人会继续等待一个足够好、好到不需要这一切的模型。
那些搭建出这十二个步骤的人，会在模型状态不佳的日子里也交付能工作的智能体——而在生产环境中，这才是唯一要紧的可靠性。
