1. 为什么 Agent 调优总在“凭感觉”你大概遇到过这种场景给 Agent 加了一条约束比如“先读代码再动手”“不要重复造轮子”跑几个任务感觉好像顺了一点但到底顺了多少、是不是真的有效说不清楚。下次再改一版 CLAUDE.md又只能靠“这次好像更聪明了”来判断。问题不在于约束写得对不对而在于没有量化依据——改了约束却没有一个稳定的对照实验告诉你改前改后差在哪。Agent 调优和传统代码调优最大的区别是代码有单元测试改一行跑一遍就知道有没有回归而 Agent 的行为是概率性的同一个任务跑两次结果都可能不同。所以“感觉变好了”这件事在 Agent 场景里几乎不可信。你需要的是把主观感受换成可复现的指标通过率和Token 消耗。这篇要做的就是用 CLAUDE.md 定义 Subagent 的职责边界搭一套 A/B 评测骨架同一份任务集分别交给“改前约束”和“改后约束”两个 Subagent 盲跑再由独立 Evaluator 盲评最后汇总成通过率和 Token 对比。整套流程可以复制跑完你就能拿到一张“这次约束改动到底值不值”的表。适合已经在用 Claude Code 或类似 Agent 工具、想让调优有据可依的开发者。2. 前置准备统一 Key 与 API 通道在搭 A/B 骨架之前先把调用通道统一。原因很简单A/B 两组要跑同一批任务如果一组走这个通道、一组走那个通道Token 统计口径就不一致对比就失去意义。我习惯把所有 Agent 调用收敛到一个统一的 Key/API 入口这样用量核对、成本对比都在一个地方看。TaoToken 在这里的角色就是统一入口一个 Key 覆盖模型对话、编码类调用用量在控制台里能按时间段核对。接入地址用 API 端点https://taotoken.net/apiKey 在控制台的 API Keys 页面生成。如果你还没建过 Key先去 API Keys 页面 建一个再对照 接入文档 把 base_url 和鉴权头配好。配置方式就是标准的环境变量不涉及任何特殊网络设置export TAOTOKEN_API_KEYsk-你的key export TAOTOKEN_BASE_URLhttps://taotoken.net/api注意A/B 两组必须用同一个 Key、同一个 base_url。否则 Token 消耗的对比会被通道差异污染你分不清是约束改动带来的变化还是通道本身的开销差异。如果你打算长期跑这套评测尤其是要反复迭代约束、每次都跑几十个任务建议看一下 Coding Plan它更适合这种高频、批量的编码类调用场景成本比按次调用更可控。3. 用 CLAUDE.md 定义 Subagent 职责A/B 评测最容易翻车的地方是两组 Subagent 的职责边界不一致。比如改前臂顺手读了实际代码改后臂没读那对比的就不是约束差异而是信息差异。所以第一步是在 CLAUDE.md 里把每个 Subagent 的职责写死。下面是我用的骨架你可以直接复制改。核心是把“盲写”和“盲评”分开writer 只根据需求设计写方案不碰实际代码evaluator 可以看实际代码但不知道哪份方案对应哪版约束。# CLAUDE.md — A/B 评测骨架 ## 角色定义 ### writer盲写 Subagent - 输入一份需求设计文档 当前生效的约束版本 - 禁止读取实际代码仓库、读取另一组的输出 - 输出一份解决方案包含改动点、关键决策、风险说明 - 约束来源只读当前会话启动时的 CLAUDE.md 快照 ### evaluator盲评 Subagent - 输入两份匿名方案标记为 A / B 实际代码 - 禁止知道 A / B 分别对应哪版约束 - 输出每份方案的评分0-5、通过与否、主要问题 ### reviewer汇总 Subagent - 输入evaluator 的评分 两组的 Token 统计 - 输出对比表含通过率、平均 Token、结论 ## 约束文档规则 - 读代码就能搞清的东西不写进约束 - 约束只描述意图、设计原因和关键边界 - 每条约束必须可被验证禁止“尽量”“适当”这类模糊词这里有个关键点约束文档本身的规则也会被 Agent 泛化。我在 CLAUDE.md 里写了“读代码就能搞清的东西不写”结果 Agent 把这条规则泛化到了代码注释上——原本容易出现的重复描述变少了注释开始关注代码意图和设计原因。这是意外收获但也说明 CLAUDE.md 的措辞要谨慎你写的每条规则都可能被放大到别的场景。4. 可复制的 A/B 分组脚本职责定义好之后用脚本把两组跑起来。核心逻辑是同一份任务集分别用改前和改后的 CLAUDE.md 快照启动两个 writer输出匿名化后交给 evaluator。import os import json import subprocess API_KEY os.environ[TAOTOKEN_API_KEY] BASE_URL os.environ[TAOTOKEN_BASE_URL] TASKS [ task_001.md, task_002.md, task_003.md, ] def run_writer(task_file, claude_md_snapshot, arm_name): 启动一个 writer Subagent返回输出和 token 统计 result subprocess.run( [ claude, -p, f--claude-md{claude_md_snapshot}, f--task{task_file}, --output-formatjson, ], capture_outputTrue, textTrue, env{**os.environ, ANTHROPIC_BASE_URL: BASE_URL, ANTHROPIC_API_KEY: API_KEY}, ) data json.loads(result.stdout) return { arm: arm_name, task: task_file, output: data[result], tokens: data[usage][total_tokens], tool_uses: data.get(tool_uses, 0), } def run_ab(): results [] for task in TASKS: before run_writer(task, CLAUDE.before.md, before) after run_writer(task, CLAUDE.after.md, after) results.append({task: task, before: before, after: after}) return results if __name__ __main__: ab_results run_ab() with open(ab_results.json, w) as f: json.dump(ab_results, f, ensure_asciiFalse, indent2) print(f完成 {len(ab_results)} 组对照)跑完之后把每组的 output 匿名化成 A / B再交给 evaluator。匿名化这一步不能省否则 evaluator 会带着“改后应该更好”的预期去评结果就不可信了。import random def anonymize(ab_results): 把 before/after 随机映射成 A/B记录映射关系 mapping {} for item in ab_results: pair [(before, item[before]), (after, item[after])] random.shuffle(pair) mapping[item[task]] { A: pair[0][0], B: pair[1][0], A_output: pair[0][1][output], B_output: pair[1][1][output], } return mapping映射关系单独存一份evaluator 只拿到 A / B 的输出拿不到映射。等评分出来再对照映射还原这样盲评才成立。5. 验证请求与成功结果脚本跑通后先做一次最小验证确认通道和统计口径都对。用一条最简单的请求确认 Key 和 base_url 生效curl -s https://taotoken.net/api/v1/messages \ -H x-api-key: $TAOTOKEN_API_KEY \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-20250514, max_tokens: 64, messages: [{role: user, content: 回复 OK}] }返回里能看到usage.input_tokens和usage.output_tokens这就是后面 A/B 对比的统计来源。确认单次请求能通、Token 字段有值再跑完整任务集。跑完一组真实对照后输出大概长这样2 agents finished ├ 盲写 writer 改后臂 · 15 tool uses · 135.8k tokens │ ⎿ Done └ 盲写 writer 改前臂 · 18 tool uses · 153.8k tokens ⎿ Done这是我在一个真实案例里跑出来的改后版本的 Token 使用量从 153.8k 降到 135.8k优化占比约 11.7%工具调用次数也从 18 次降到 15 次。注意这个数字不是重点重点是它可复现——同样的任务集、同样的通道、同样的盲评流程换个人跑也能得到接近的对比。这才是把“感觉”变成“可验证”的意义。汇总表可以这样组织方便一眼看出改动是否值得指标改前臂改后臂变化平均 Token153.8k135.8k-11.7%平均工具调用1815-16.7%盲评通过率待填待填待填通过率那一列由 evaluator 的评分算出来Token 和工具调用由脚本自动统计。两列都拿到你才能判断这次约束改动是“真的更好”还是“只是更省”。6. 本篇常见错排查Subagent 看不到最新的 CLAUDE.md 改动。这是最容易踩的坑。Claude Code 在同一个会话里修改 CLAUDE.md 后本次会话派发的 Subagent 读到的还是主会话启动时的快照。所以 A/B 两组必须用两个独立的会话启动或者用--claude-md显式指定快照文件不能在一个会话里改完直接跑。两组 Token 统计口径不一致。检查是不是两组用了不同的 base_url 或不同的 Key。统一走https://taotoken.net/api用量在控制台按时间段核对确保对比的是同一通道下的开销。evaluator 猜到了 A/B 对应关系。如果改后臂的输出风格明显不同evaluator 可能靠风格猜出来。解决办法是让两组 writer 用同样的输出模板只让约束内容不同不让格式成为线索。任务集太小结论不稳。三个任务跑出来的 11.7% 可能只是噪声。任务集至少覆盖 10 个以上不同类型的需求再取平均结论才站得住。约束写得太模糊无法验证。如果 CLAUDE.md 里出现“尽量简洁”“适当抽象”这类词Agent 每次理解都不一样A/B 对比就没有基准。每条约束都要能被判定“满足”或“不满足”。7. 把评测接进日常迭代这套骨架跑顺之后约束迭代的流程就变了改完 CLAUDE.md先跑一遍 A/B看通过率和 Token 两张表再决定这版约束留不留。不再靠“感觉好像好了”而是有一组可复现的数字撑着。调用通道统一在 TaoToken 上A/B 两组的用量都在一个控制台里核对省得来回对账。如果你要长期跑这套评测Coding Plan 比按次调用更适合这种批量场景只是想先验证模型行为可以直接在 模型对话 里手动跑几条任务感受一下要正式接入脚本Key 在 API Keys 建参数对照 接入文档 配。最后一个实操建议把ab_results.json和映射关系一起存档每次约束改动都留一份。跑上五六轮之后你手里就有了一条 Agent 效果的量化曲线而不是一堆“感觉这次更好”的模糊记忆。
1. 为什么 Agent 调优总在“凭感觉”你大概遇到过这种场景给 Agent 加了一条约束比如“先读代码再动手”“不要重复造轮子”跑几个任务感觉好像顺了一点但到底顺了多少、是不是真的有效说不清楚。下次再改一版 CLAUDE.md又只能靠“这次好像更聪明了”来判断。问题不在于约束写得对不对而在于没有量化依据——改了约束却没有一个稳定的对照实验告诉你改前改后差在哪。Agent 调优和传统代码调优最大的区别是代码有单元测试改一行跑一遍就知道有没有回归而 Agent 的行为是概率性的同一个任务跑两次结果都可能不同。所以“感觉变好了”这件事在 Agent 场景里几乎不可信。你需要的是把主观感受换成可复现的指标通过率和Token 消耗。这篇要做的就是用 CLAUDE.md 定义 Subagent 的职责边界搭一套 A/B 评测骨架同一份任务集分别交给“改前约束”和“改后约束”两个 Subagent 盲跑再由独立 Evaluator 盲评最后汇总成通过率和 Token 对比。整套流程可以复制跑完你就能拿到一张“这次约束改动到底值不值”的表。适合已经在用 Claude Code 或类似 Agent 工具、想让调优有据可依的开发者。2. 前置准备统一 Key 与 API 通道在搭 A/B 骨架之前先把调用通道统一。原因很简单A/B 两组要跑同一批任务如果一组走这个通道、一组走那个通道Token 统计口径就不一致对比就失去意义。我习惯把所有 Agent 调用收敛到一个统一的 Key/API 入口这样用量核对、成本对比都在一个地方看。TaoToken 在这里的角色就是统一入口一个 Key 覆盖模型对话、编码类调用用量在控制台里能按时间段核对。接入地址用 API 端点https://taotoken.net/apiKey 在控制台的 API Keys 页面生成。如果你还没建过 Key先去 API Keys 页面 建一个再对照 接入文档 把 base_url 和鉴权头配好。配置方式就是标准的环境变量不涉及任何特殊网络设置export TAOTOKEN_API_KEYsk-你的key export TAOTOKEN_BASE_URLhttps://taotoken.net/api注意A/B 两组必须用同一个 Key、同一个 base_url。否则 Token 消耗的对比会被通道差异污染你分不清是约束改动带来的变化还是通道本身的开销差异。如果你打算长期跑这套评测尤其是要反复迭代约束、每次都跑几十个任务建议看一下 Coding Plan它更适合这种高频、批量的编码类调用场景成本比按次调用更可控。3. 用 CLAUDE.md 定义 Subagent 职责A/B 评测最容易翻车的地方是两组 Subagent 的职责边界不一致。比如改前臂顺手读了实际代码改后臂没读那对比的就不是约束差异而是信息差异。所以第一步是在 CLAUDE.md 里把每个 Subagent 的职责写死。下面是我用的骨架你可以直接复制改。核心是把“盲写”和“盲评”分开writer 只根据需求设计写方案不碰实际代码evaluator 可以看实际代码但不知道哪份方案对应哪版约束。# CLAUDE.md — A/B 评测骨架 ## 角色定义 ### writer盲写 Subagent - 输入一份需求设计文档 当前生效的约束版本 - 禁止读取实际代码仓库、读取另一组的输出 - 输出一份解决方案包含改动点、关键决策、风险说明 - 约束来源只读当前会话启动时的 CLAUDE.md 快照 ### evaluator盲评 Subagent - 输入两份匿名方案标记为 A / B 实际代码 - 禁止知道 A / B 分别对应哪版约束 - 输出每份方案的评分0-5、通过与否、主要问题 ### reviewer汇总 Subagent - 输入evaluator 的评分 两组的 Token 统计 - 输出对比表含通过率、平均 Token、结论 ## 约束文档规则 - 读代码就能搞清的东西不写进约束 - 约束只描述意图、设计原因和关键边界 - 每条约束必须可被验证禁止“尽量”“适当”这类模糊词这里有个关键点约束文档本身的规则也会被 Agent 泛化。我在 CLAUDE.md 里写了“读代码就能搞清的东西不写”结果 Agent 把这条规则泛化到了代码注释上——原本容易出现的重复描述变少了注释开始关注代码意图和设计原因。这是意外收获但也说明 CLAUDE.md 的措辞要谨慎你写的每条规则都可能被放大到别的场景。4. 可复制的 A/B 分组脚本职责定义好之后用脚本把两组跑起来。核心逻辑是同一份任务集分别用改前和改后的 CLAUDE.md 快照启动两个 writer输出匿名化后交给 evaluator。import os import json import subprocess API_KEY os.environ[TAOTOKEN_API_KEY] BASE_URL os.environ[TAOTOKEN_BASE_URL] TASKS [ task_001.md, task_002.md, task_003.md, ] def run_writer(task_file, claude_md_snapshot, arm_name): 启动一个 writer Subagent返回输出和 token 统计 result subprocess.run( [ claude, -p, f--claude-md{claude_md_snapshot}, f--task{task_file}, --output-formatjson, ], capture_outputTrue, textTrue, env{**os.environ, ANTHROPIC_BASE_URL: BASE_URL, ANTHROPIC_API_KEY: API_KEY}, ) data json.loads(result.stdout) return { arm: arm_name, task: task_file, output: data[result], tokens: data[usage][total_tokens], tool_uses: data.get(tool_uses, 0), } def run_ab(): results [] for task in TASKS: before run_writer(task, CLAUDE.before.md, before) after run_writer(task, CLAUDE.after.md, after) results.append({task: task, before: before, after: after}) return results if __name__ __main__: ab_results run_ab() with open(ab_results.json, w) as f: json.dump(ab_results, f, ensure_asciiFalse, indent2) print(f完成 {len(ab_results)} 组对照)跑完之后把每组的 output 匿名化成 A / B再交给 evaluator。匿名化这一步不能省否则 evaluator 会带着“改后应该更好”的预期去评结果就不可信了。import random def anonymize(ab_results): 把 before/after 随机映射成 A/B记录映射关系 mapping {} for item in ab_results: pair [(before, item[before]), (after, item[after])] random.shuffle(pair) mapping[item[task]] { A: pair[0][0], B: pair[1][0], A_output: pair[0][1][output], B_output: pair[1][1][output], } return mapping映射关系单独存一份evaluator 只拿到 A / B 的输出拿不到映射。等评分出来再对照映射还原这样盲评才成立。5. 验证请求与成功结果脚本跑通后先做一次最小验证确认通道和统计口径都对。用一条最简单的请求确认 Key 和 base_url 生效curl -s https://taotoken.net/api/v1/messages \ -H x-api-key: $TAOTOKEN_API_KEY \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-20250514, max_tokens: 64, messages: [{role: user, content: 回复 OK}] }返回里能看到usage.input_tokens和usage.output_tokens这就是后面 A/B 对比的统计来源。确认单次请求能通、Token 字段有值再跑完整任务集。跑完一组真实对照后输出大概长这样2 agents finished ├ 盲写 writer 改后臂 · 15 tool uses · 135.8k tokens │ ⎿ Done └ 盲写 writer 改前臂 · 18 tool uses · 153.8k tokens ⎿ Done这是我在一个真实案例里跑出来的改后版本的 Token 使用量从 153.8k 降到 135.8k优化占比约 11.7%工具调用次数也从 18 次降到 15 次。注意这个数字不是重点重点是它可复现——同样的任务集、同样的通道、同样的盲评流程换个人跑也能得到接近的对比。这才是把“感觉”变成“可验证”的意义。汇总表可以这样组织方便一眼看出改动是否值得指标改前臂改后臂变化平均 Token153.8k135.8k-11.7%平均工具调用1815-16.7%盲评通过率待填待填待填通过率那一列由 evaluator 的评分算出来Token 和工具调用由脚本自动统计。两列都拿到你才能判断这次约束改动是“真的更好”还是“只是更省”。6. 本篇常见错排查Subagent 看不到最新的 CLAUDE.md 改动。这是最容易踩的坑。Claude Code 在同一个会话里修改 CLAUDE.md 后本次会话派发的 Subagent 读到的还是主会话启动时的快照。所以 A/B 两组必须用两个独立的会话启动或者用--claude-md显式指定快照文件不能在一个会话里改完直接跑。两组 Token 统计口径不一致。检查是不是两组用了不同的 base_url 或不同的 Key。统一走https://taotoken.net/api用量在控制台按时间段核对确保对比的是同一通道下的开销。evaluator 猜到了 A/B 对应关系。如果改后臂的输出风格明显不同evaluator 可能靠风格猜出来。解决办法是让两组 writer 用同样的输出模板只让约束内容不同不让格式成为线索。任务集太小结论不稳。三个任务跑出来的 11.7% 可能只是噪声。任务集至少覆盖 10 个以上不同类型的需求再取平均结论才站得住。约束写得太模糊无法验证。如果 CLAUDE.md 里出现“尽量简洁”“适当抽象”这类词Agent 每次理解都不一样A/B 对比就没有基准。每条约束都要能被判定“满足”或“不满足”。7. 把评测接进日常迭代这套骨架跑顺之后约束迭代的流程就变了改完 CLAUDE.md先跑一遍 A/B看通过率和 Token 两张表再决定这版约束留不留。不再靠“感觉好像好了”而是有一组可复现的数字撑着。调用通道统一在 TaoToken 上A/B 两组的用量都在一个控制台里核对省得来回对账。如果你要长期跑这套评测Coding Plan 比按次调用更适合这种批量场景只是想先验证模型行为可以直接在 模型对话 里手动跑几条任务感受一下要正式接入脚本Key 在 API Keys 建参数对照 接入文档 配。最后一个实操建议把ab_results.json和映射关系一起存档每次约束改动都留一份。跑上五六轮之后你手里就有了一条 Agent 效果的量化曲线而不是一堆“感觉这次更好”的模糊记忆。
