AI 知识库

Claude Code 有效性追踪：从 Trace 到 Evals 的个人落地方案

Properties2
description结合 Langfuse AI Engineering Loop 与 bohutang「Trace 即 Evals」方法论，基于 Claude Code 自带 OTel 遥测（含 beta traces）设计的个人级有效性评估系统——回答「换模型、换工具、改流程之后，到底变好还是变坏」。
tagsai/claude-code, ai/agent, ai/工作流, ai/observability, ai/evals

12分钟阅读

核心思想

要优化 Claude Code 的使用有效性，先得有数据；要有数据，就得 trace。Claude Code 的「数据生产端」官方已经造好（OTel metrics / events / traces 三信号），缺的只是「沉淀 + 计算 + 评估」三层。个人规模的答案：OTel Collector 双路分发 → Langfuse 看单条轨迹 + DuckDB 算聚合指标 → 标签化在线准实验 + headless 离线 A/B 回归。

一、问题定义

Agent 跑了 3 小时，花了 $12。失败了，不知道哪一步跑偏；成功了，也不知道哪一步做对。下次换模型、改 prompt、加 tool，效果变好还是变坏，没人说得清。
——bohutang《Trace 即 Evals》开篇

这已经不是 prompt tuning 的问题，而是 harness engineering 的问题（演进：Prompt Engineering 2022-2024 → Context Engineering 2025 → Harness Engineering 2026）。要回答的三个问题：

  1. 我用 Claude Code 的基线有效性如何？
  2. 换了模型 / 工具 / 流程后，效果变好还是变坏？（对比与归因）
  3. 数据指向哪里，harness（CLAUDE.md、skills、MCP、权限配置）就改哪里。

相关笔记：Claude Code Harness：契约先行的交付闭环、反馈循环：让 Claude Code 少盯着也能完成有野心的任务

二、方法论框架：两篇文章是同一闭环的两半

Langfuse：AI Engineering Loop（方法论骨架）

五步循环，所有后续步骤都建立在 trace 之上：

Trace →（在线）Monitor →（离线）Datasets → Experiments → Evaluate

  • Trace 结构：trace（一次系统调用）→ observations（generation / tool / retriever / span / event），层级树；每个 observation 带 input/output、start/end time、cost、latency、token usage。
  • Trace vs Session 切分原则：一次调用 = 一条 trace，多轮对话 = 一个 session。切太碎丢失叙事，切太大失败被淹没。
  • 起步建议：先对一条真实工作流端到端插桩，人工读一批真实 trace 确认结构有用，再谈监控与评估。

bohutang：Trace 即 Evals（数据工程落地）

三个核心论点：

  1. Agent 是路径依赖系统——一次 tool 选择、一次上下文裁剪都会改变后续所有步骤。只看 pass/fail 和总成本说不清好坏，必须下钻到 tool call 序列找分叉点。Demo 证据：同一任务同一模型只换 harness，成本差 67%（0.02 vs 0.07）、耗时差 63%（6m10s vs 16m34s）、token 差 68%、调用次数差 52%。
  2. Trace 必须可计算——存下来只是第一步：清洗脏 JSON → 拆解嵌套结构 → 抽取热点字段（model/tokens/cost/tool/error）→ 索引聚合，才能支撑归因、回放、评测。
  3. 三步走：① 数据先沉下来（原始 trace 长期保留）→ ② 计算能力跟上 → ③ 上层（评测/回放/归因）按需构建，一份数据多种用途。

规模换算

bohutang 的架构（Databend + 对象存储 + VARIANT 加速列，日均几百 TB）是模型公司规模。个人场景每天几 MB~几十 MB，DuckDB 直接查 JSONL/NDJSON 文件就是等价平替：零运维、SQL 全功能、文件即数据库。

三、Claude Code 遥测能力盘点（数据生产端已造好）

官方 OTel 遥测覆盖三层信号，无需自己插桩：

信号内容最有价值的字段
Metrics（8 个）聚合计数器cost.usage / token.usage（带 model、query_source、effort 维度）；code_edit_tool.decision（accept/reject）；lines_of_code.count、commit.count、active_time.total
Events/Logs（27 个）结构化事件流api_request（model、cost_usd、duration_ms、四类 tokens）；tool_result（tool_name、success、duration_ms、error_type）；tool_decision（accept/reject 及来源）；compaction（pre/post_tokens）；api_error。prompt.id 把一次提示触发的所有事件串成链
Traces（beta）层级 span 树claude_code.interaction（一轮）→ llm_request / tool（→ blocked_on_user 权限等待 + execution）；子 agent 的 spans 嵌套在父 agent 的 tool span 下，委托链是一棵完整的树

关键环境变量

CLAUDE_CODE_ENABLE_TELEMETRY=1          # 总开关
OTEL_METRICS_EXPORTER=otlp
OTEL_LOGS_EXPORTER=otlp
OTEL_TRACES_EXPORTER=otlp               # traces 需额外加 ↓
CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1   # traces beta 开关
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
OTEL_RESOURCE_ATTRIBUTES=harness.variant=baseline   # 实验标注钩子！
# 内容级捕获（隐私敏感，self-host 才开）：
# OTEL_LOG_USER_PROMPTS=1 / OTEL_LOG_TOOL_DETAILS=1 / OTEL_LOG_TOOL_CONTENT=1

可写进 settings.json 的 env 字段，比系统环境变量干净。

两个兜底数据源

  • 本地 transcript JSONL：~/.claude/projects/<project>/<session-id>.jsonl，含完整消息内容，是最全的原始数据。⚠️ 默认 30 天清理（cleanupPeriodDays），要调大。
  • Headless 模式：claude -p "task" --output-format json 直接返回 total_cost_usd、duration_ms、分类 token 数、session_id——离线实验跑批的天然接口。

Langfuse 对接的坑

Langfuse 的 OTel 端点（/api/public/otel）只接收 traces 信号，不收 logs/metrics。Claude Code 早期只发 logs，直连 Langfuse 看不到东西（GitHub discussion #9088 有人踩坑）。Traces beta 解决了主要矛盾，但 edit accept 率、compaction 等聚合指标仍在 metrics/events 里——所以必须 Collector 双路，不能直连。

四、推荐架构

graph LR
    A[Claude Code 日常会话<br/>开启 OTel 遥测] -->|OTLP| C[OTel Collector]
    B[claude -p 离线实验<br/>固定任务集] -->|结果 JSON| E
    C -->|traces| D[Langfuse self-host<br/>轨迹树状展开 / 人工 review / 标注]
    C -->|全量信号 file exporter| E[NDJSON 落盘]
    E --> F[DuckDB<br/>SQL 视图 / 周报 / A/B 对比 / 归因]
    G[transcript JSONL<br/>~/.claude/projects/] -.兜底原始层.-> F

选型理由：

  • Langfuse self-host 而非自写 UI：trace→observation→session 数据模型与 Claude Code 的 span 层级天然同构；树状展开、成本聚合、人工标注、datasets/experiments 都现成；docker compose 一条命令，免费。
  • DuckDB 而非 Databend/ClickHouse：个人数据量下满足 bohutang 列的全部数据库能力需求（JSON 原生、清洗变换、聚合检索）。
  • 原始数据落盘是底座而非可选项：traces 是 beta（span 名可能变），transcript schema 也会漂移。落了原始 NDJSON，分析层随时重算——「数据先沉下来」的本地版。
  • 隐私边界：默认遥测只有结构化数据（耗时、模型名、工具名）。OTEL_LOG_USER_PROMPTS / OTEL_LOG_TOOL_CONTENT 会把提示词和代码内容发出去——Collector 在本机没问题，放 VPS 要想清楚。

备选：不想跑 Langfuse 的话，官方 claude-code-monitoring-guide 有 Prometheus + Grafana 的 docker compose 模板，但那是监控视角（聚合曲线），做不了「展开单条 trace 找分叉点」。

五、指标体系：看什么

结果层（有效性本身）

  • code_edit_tool.decision accept/reject 率——被低估的指标：每次接受/拒绝编辑都是对模型产出的即时人工标注，等于免费的 human eval 数据流。按 model、语言、项目分组看。
  • commit.count / pull_request.count（产出落地信号）。
  • 会话是否以「重述任务 / 放弃」收尾（从 transcript 推断）。

效率层（成本视角）

  • 每任务 cost、duration、token（input/output/cacheRead 分拆）、tool call 总次数。
  • 同样完成任务，直达还是绕路——对照 bohutang demo 的对比表。

过程层（归因用：定位「哪一步开始坏」）

  • 工具失败率：tool_result 按 tool_name 分组的 success=false 占比与 error_type 分布（某个 MCP 工具老失败 → 它在拖累整体）。
  • compaction 频率与压缩比：频繁 compact = 任务切分太大或上下文被垃圾填满。
  • blocked_on_user span 时长：权限摩擦信号——allowlist 该不该扩。
  • 绕路信号：同一文件反复 Read、失败→重试链长度（从 events 序列或 transcript 计算）。
  • 人工纠偏次数：一个任务内追加澄清/纠正的 prompt 数——「harness 没把约束前置」的信号，往往指向 CLAUDE.md / skill 该改了。

六、实验方法：回答「换了 X 之后效果如何」

1. 在线准实验（观察性，低成本，看趋势）

改 harness 时（换模型、加 skill、改 CLAUDE.md、换 MCP），改一个标签：

OTEL_RESOURCE_ATTRIBUTES=harness.variant=skill-v2

标签自动附在之后每一条 span/metric/event 上，日常使用自然积累，周度按 variant 对比指标分布。局限：任务难度不受控，只能看大趋势，不能下因果结论。

2. 离线 A/B（控制实验，下结论靠它）

对应 Langfuse loop 的 Datasets → Experiments，bohutang 对比表的个人复刻：

  1. 沉淀任务集：从真实会话挑 10~20 个代表性任务（修过的 bug、写过的功能），每个带可执行验收标准（测试通过 / 输出含特定内容 / exit code）。
  2. 跑矩阵：claude -p × 模型 × harness 配置 × 重复 3~5 次——Agent 是不确定系统，单次对比毫无意义，必须看分布。
  3. 入库对比：输出 JSON（cost/duration/tokens）+ 验收脚本结果直接进 DuckDB。
  4. 评分优先级：可执行断言 > LLM-as-judge（把 transcript 喂给另一个模型评「是否绕路 / 是否达成」）> 人工抽看。

七、落地路线图

  • 第 0 步（5 分钟，纯赚不亏）：调大 cleanupPeriodDays + settings.json 开遥测变量、Collector 先用 file exporter 纯落盘——分析系统没建好之前，数据先开始积累。
  • 第 1 步（半天）：docker compose 起 OTel Collector + Langfuse；DuckDB 建 4~5 个 SQL 视图（周成本、edit accept 率、工具失败率、compaction 趋势）；人工读一周真实 trace，先建立「正常轨迹长什么样」的直觉。
  • 第 2 步（持续迭代）：沉淀任务集 → 每次 harness 改动打 variant 标签 + 跑一轮离线回归 → 数据驱动地改 CLAUDE.md / skills / 工具配置。

两个已知风险

  1. Traces 是 beta：官方明说 span 名和 attributes 可能随版本变化。缓解：原始数据落盘，分析层重算。
  2. 交互式会话的 traces 导出：官方文档对此着墨少于 SDK 模式（交互式会话会忽略入站 TRACEPARENT，但应正常导出自己的 span）。第 1 步搭好后先实测验证，以 Monitoring 文档 Traces (beta) 节为权威参考。

参考来源

反向链接