文档怎么才能被编码 Agent 正确使用？用 Gauge 做闭环实测与改进
文档写得完整，不代表 Claude Code、Codex 等编码 Agent 真能按它完成任务。它们可能误读命令、沿用过时 API，或在交互式提示处卡住。Gauge 是一款开源 CLI：在隔离环境中让真实编码 Agent 执行任务，收集会话证据，再据此改进文档、Skill、CLI 或 SDK，并重新测试。它关注的不是文档字数，而是 Agent 是否能完成用户要做的事。
从“写完文档”转向“测量任务是否成功”
Gauge 将过程组织成一个迭代回路：先定义真实任务及成功标准，再运行 Agent，分析会话记录里的阻塞点，修改产品或说明，最后用同一任务复测。比如给一个 SDK 写了 Quickstart，可以设置“从空项目接入 SDK 并调用一次接口”为任务，检查 Agent 是否选对初始化方式、参数和后续步骤。
这与只做静态拼写检查不同。Agent 可能读懂每个句子，却仍无法判断多个命令的正确顺序；也可能因错误信息含糊而反复尝试。Gauge README 列出的典型摩擦包括交互命令阻塞、Agent 使用已弃用命令、Skill 没有被发现，以及 Agent 错误地断言某项能力不存在。会话轨迹能帮助定位问题，但分析仍需结合任务证据，不能把一次模型输出当作普遍结论。
本地快速开始
项目以 npm CLI 发布，当前 README 要求 Node.js 22.13 及以上、npm、运行 Linux 容器的 Docker，以及被测 Agent 的凭据。README 列出 Claude Code、Codex、Pi 和 OpenCode。推理仍由相应模型提供方完成，因此本地执行并不等于完全离线。
npm install -g @withgauge/cli gauge local runtime pull cd my-project gauge init --local
gauge init --local 会建立私有的 .gauge/ 工作区，其中包括 SQLite 数据库和本地后端偏好设置；普通初始化不会改动已跟踪文件。若准备共享 Markdown 测试案例，可使用 gauge init --local --cases，但它还会创建 gauge.json、gauge-cases/ 和 AGENTS.md 指引，应先检查这些生成文件再提交。
安装 CLI 后，可以安装项目提供的 Gauge Skill：
gauge install-skill
之后可让编码 Agent 阅读仓库并协助启动评估。也可以按 README 示例显式创建任务，例如用 gauge eval create --local 指定名称、Agent、样本数、任务描述和验收标准。先运行 dry-run 检查本地运行环境与凭据，再启动实际测试。具体选项应以当前版本的 CLI 帮助和文档为准；不要把示例中的 eval ID 占位符原样当成真实 ID。
怎样让对比结果有意义
最重要的是保持任务和判定标准稳定。第一次运行建立基线，修改文档或 Skill 后，用同一任务复测；否则无法区分改善来自内容变更还是任务本身变化。测试任务要贴近用户目标，验收标准则尽量可观察，例如“生成指定文件，包含必需字段，并通过项目测试”，而不是“回答得清楚”。
建议按小步迭代：
- 从一项高频任务开始，保存任务描述与成功标准。
- 阅读会话证据，找出 Agent 实际卡住的位置，而非先猜文档哪里不好。
- 一次只改一类因素，例如参数说明或错误信息。
- 使用相同任务和输入重跑，并检查成功率之外是否引入新问题。
- 记录模型、凭据模式与环境差异，避免把单次结果外推到所有 Agent。
Gauge 的本地模式以 Docker 容器运行新会话，并通过网络网关处理文档变体与凭据替换；README 特别指出网关会终止 TLS，并透明替换文档版本。运行前应确认信任边界、网络访问和密钥管理符合团队要求。.gauge/ 含持久测量数据，仓库建议保持私有；共享的案例文件则应避免写入令牌、个人资料或生产数据。
适合谁，以及它不保证什么
如果团队维护面向编码 Agent 的 Skill、CLI、SDK 或文档，Gauge 提供了一种从真实任务轨迹发现摩擦的办法。它适合在发布前验证预发布包或说明变更，而不是替代单元测试、安全审查和人工文档审核。基于有限任务得到的结果也不代表所有模型、版本和用户环境都会有相同行为；稳定的任务设计与重复实验比漂亮的单次演示更重要。
从实用角度看，可以先选一个最常见的集成流程，建立可重复的最小评测，再逐步扩展到更多 Agent 和任务。只有当复测能够解释“改了什么、证据如何变化、是否出现副作用”，这种闭环才真正有价值。