Claude Code 自主迭代循环:autoresearch 的 Modify → Verify → Keep/Discard 自动化调优协议详解
Claude Code 自主迭代循环:autoresearch 的 Modify → Verify → Keep/Discard 自动化调优协议详解
导读
本文基于 Autoresearch 插件最核心的 /autoresearch 命令协议展开。该命令在 Claude Code 中运行一个完全自主的目标导向迭代循环:给定目标、可修改的文件范围、一个输出数值指标的 Verify 命令,以及一个必须始终通过的 Guard 安全命令,Claude 会反复执行"修改 → 提交 → 验证 → 保留/回滚"的原子化循环,并依据自身的 git 历史与结果日志不断调整策略,直到迭代耗尽或目标达成。读完本文,你将掌握该命令的全部参数语义、七阶段迭代协议、TSV 结果记录格式、Eval 检查点机制、链式交接(chain handoff)规则,以及底层 orchestrate.sh 脚本如何为整个循环提供确定性路由与安全审查支撑。
一、命令定位:什么是 /autoresearch
/autoresearch 是 Autoresearch 技能的核心命令,对应仓库中的命令协议文件 claude-plugin/commands/autoresearch.md。它的设计哲学来自 Karpathy 的 autoresearch 思想,是一个典型的闭环优化器:
Modify → Verify → Keep/Discard → Repeat forever
默认情况下,该循环执行 25 次迭代(可用 Iterations: N 覆盖),也可通过 Iterations: unlimited 切换为无界模式。每次迭代 Claude 都要:
- 阅读代码库、git 历史和结果 TSV,判断"什么有效、什么失败、什么还没试过";
- 做出一个可在一句话内解释的原子化变更;
- 提交(保证回滚永远干净);
- 运行
Verify命令提取数值指标; - 运行
Guard(如配置); - 指标改善且 Guard 通过则 keep,指标恶化则
git revert; - 将结果追加到 TSV 日志,进入下一轮。
它最大的特点是从自己的历史中学习:前面迭代中"哪些变更真正提升了指标",会直接决定它下一步尝试的方向,而不是盲目随机修改。
1.1 与调度入口的关系
在技能总入口 claude-plugin/skills/autoresearch/SKILL.md 中,/autoresearch 被定义为三种调度模式的统一入口:
| 触发条件 | 模式 |
|---|---|
提供了 Metric: 或 Verify: |
Classic —— 本文讲解的经典指标循环,行为不变 |
| 只有自然语言目标,无 Metric/Verify | Orchestrator —— 目标编排器,见 SKILL.md 的 Orchestrator 章节 |
| 什么都没给 | Setup wizard —— 交互式配置向导 |
--classic 标志 |
无论目标文本如何,强制 Classic 模式 |
--auto 标志 |
无论目标文本如何,强制 Orchestrator 模式 |
每次调用都会打印横幅:<a href="https://link.gitcode.com/i/532b454771ef6254eca4e47cb2e3e3d5" target="_blank">autoresearch] mode: classic | orchestrator | wizard。本文聚焦 Classic 模式(即命令协议文件的主体内容);Orchestrator 的目标路由逻辑由 [claude-plugin/skills/autoresearch/scripts/orchestrate.sh 承载,后面单独展开。
二、参数解析:一次调用的完整语法
协议文件对 $ARGUMENTS 的解析顺序与语义如下(对应 argument-hint:[Goal: <text>] [Scope: <glob>] [Metric: <text>] [Verify: <cmd>] [Guard: <cmd>] [Iterations: N] [--evals]):
| 参数 | 关键字/标志 | 语义 | 默认值 |
|---|---|---|---|
Goal |
Goal: |
要改进的目标(自然语言描述) | 无(缺失则进入交互向导) |
Scope |
Scope: / --scope |
允许 Claude 修改的文件 glob | 无(缺失则进入交互向导) |
Metric |
Metric: |
追踪的指标名称 | 无 |
Direction |
Direction: |
指标方向:higher_is_better(默认)或 lower_is_better |
higher_is_better |
Verify |
Verify: |
输出一个数字的 shell 命令 | 无(缺失则进入交互向导) |
Guard |
Guard: |
可选安全命令,必须始终通过 | 无 |
Iterations |
Iterations: / --iterations |
有界模式下的迭代次数 N;"unlimited" 为无界 |
25 |
| Eval 检查点 | --evals |
开启循环中途的检查点分析 | 关闭 |
| Eval 频率 | --evals-interval N |
覆盖检查点频率 | floor(max/3),无界时固定 10 |
| 链式交接 | --chain <targets> |
逗号分隔的下游命令,循环结束后按序执行 | 无 |
2.1 交互式配置(Setup)
协议要求:如果 Goal、Scope、Metric、Verify 任一缺失,不得擅自猜测,而是使用 AskUserQuestion 一次性批量提问(单个 batched call):
- Q1 (Goal):"What do you want to improve?"
- Q2 (Scope):"Which files?" —— 从项目结构出发给出建议 glob
- Q3 (Metric+Verify):"How to measure? Provide a shell command that outputs a number"
- Q4 (Guard):"Safety command that must always pass?" —— 选项:测试命令、构建命令、跳过
如果所有参数都已内联提供,则跳过 Setup,直接进入前置检查。这与 claude-plugin/commands/autoresearch/plan.md 中 /autoresearch:plan 的职责衔接:plan 命令专门负责把模糊目标转化为经过验证的 Scope/Metric/Direction/Verify 配置块,输出一个可直接运行的 config block。
三、前置检查(Precondition Checks)
在进入任何修改之前,协议要求按顺序执行以下检查,关键问题快速失败(fail fast),非关键问题仅警告:
- 确认存在 git 仓库:
git rev-parse --git-dir; - 检查工作树是否干净:
git status --porcelain—— 若脏则警告(脏工作树会污染基线测量); - 检查是否存在陈旧的锁文件、是否处于 detached HEAD;
- 若配置了
Guard,先运行一次 Guard 建立 guard 基线(作为 iteration 0 的 guard-metric); - 任何关键问题立即中止。
四、Verify 安全审查(Safety Screen)
这是整个循环最重要的安全边界之一。协议要求在第一次 dry-run 之前,对 Verify 命令进行静态审查,拦截以下危险模式:
rm -rf类递归强制删除;- fork bomb(fork 炸弹);
curl|sh/wget|sh这类"远程内容直通解释器"模式;- 内嵌凭据(AWS key、密码、私钥);
- 对外写出的行为(出站写入)。
在底层,这个审查被实现为 orchestrate.sh 的 screen-cmd 子命令。查看 claude-plugin/skills/autoresearch/scripts/orchestrate.sh 的源码,可以看到一套精确定位、避免误杀的正则拦截矩阵:
| 拦截类别 | 关键匹配规则(源码提炼) |
|---|---|
rm -rf |
命令名锚定 rm + 递归标志(-r/-R/--recursive)+ 强制标志(-f/-F/--force)同时出现才拦截;支持路径限定形式 /bin/rm、./rm |
| curl/wget 直通解释器 | `curl |
| xargs 绕过 | curl ... | xargs sh/bash 这类绕过直接管道的变体也拦截 |
| 数据外泄 | 管道到 nc/ncat/netcat |
| 块设备写 | `of=/dev/sd* |
| 文件系统格式化 | mkfs/mke2fs(含路径限定 /sbin/mkfs.ext4) |
| 批量删除 | find ... -delete(两个 token 同时出现才拦,普通 find 搜索放行) |
| 不可恢复销毁 | shred、truncate -s 0 / --size=0 |
| 递归锁死 | `chmod -R 000 |
| fork bomb | `:(){ : |
| 凭据 | AKIA[0-9A-Z]{16}(AWS 访问密钥)、PASSWORD=、`BEGIN (RSA |
| 数据库 URL | postgres(ql):// 仅允许 host 为 localhost/127.0.0.1/无点容器主机名,否则数据库名必须以 _test/_ci 结尾(锚定后缀,latest、precision 这类包含 "test" 子串但非后缀的会被拒绝) |
对应的回归测试全部集中在 tests/test-orchestrator.sh,包括 /bin/rm -rf 路径限定变体、curl | zsh、curl|xargs sh、dd of=/dev/mmcblk0、truncate --size=0、chmod -R 0 等约 60 条拒绝用例,以及 pytest -q、go build ./...、curl -s api/health | jq .ok 等"已知安全命令必须放行"的反误杀用例。
五、建立基线(Iteration 0)
正式循环开始前必须先建立可复现的基线:
- 运行
Verify命令,从输出中提取数值指标; - 作为 iteration 0 写入 TSV,行格式为:
(即:迭代号、时间戳、提交、指标值、delta 恒为 0.0、guard 状态、guard 指标、状态为0\t{timestamp}\t{commit}\t{metric}\t0.0\t{guard}\t-\tbaseline\tinitial statebaseline、描述为initial state) - 创建输出目录:
autoresearch/loop-{YYMMDD}-{HHMM}/(例如autoresearch/loop-261008-2134/),所有循环产物都落在此目录; - 写入 TSV 表头:
第一行是带# metric_direction: {direction} iteration timestamp commit metric delta guard guard-metric status description#的指标方向注释,供后续/autoresearch:evals解析时恢复方向语义(详见 claude-plugin/commands/autoresearch/evals.md)。
六、迭代循环:七阶段协议
对每次迭代(从 1 到 max_iterations,或无界运行),协议定义了严格的七个阶段:
Phase 1:Review(把 git 历史当记忆读)
- 读取结果 TSV 的最后 10–20 行;
- 运行
git log --oneline -20,观察哪些提交有效、哪些被回滚; - 如果上一次迭代是 "keep",运行
git diff HEAD~1查看究竟哪个变更提升了指标; - 明确输出:什么有效、什么失败、什么尚未尝试。
Phase 2:Modify(单点修改)
- 基于 Review 结论,做出一个聚焦的变更以提升指标;
- 变更必须是原子的 —— 一个逻辑工作单元,可一句话解释。
Phase 3:Commit(提交)
- stage 并以
experiment: {description}前缀提交(例如experiment: add auth edge case tests); - 记录提交 SHA。
Phase 4:Verify(验证)
- 运行
Verify命令提取新的指标值; - 计算与上一迭代的 delta;
- 指标沿正确方向改善(higher_is_better 时增大 / lower_is_better 时减小)→ 成为 keep 候选。
Phase 5:Guard(安全门)
- 若配置了 Guard,运行 Guard;
- Guard 失败则无论指标是否改善,一律回滚(Guard 是硬约束,指标是软目标)。
Phase 6:Decide(决策)
协议定义了六种明确的结局:
| 状态 | 触发条件 | 动作 |
|---|---|---|
keep |
指标改善 + Guard 通过 | 保留提交 |
discard |
指标恶化 | git revert HEAD --no-edit |
crash |
Verify/Guard 命令本身执行失败 | git revert HEAD --no-edit |
no-op |
本轮未做任何变更 | 无动作 |
hook-blocked |
git hook 阻止了提交 | 记录状态 |
metric-error |
Verify 输出不是合法数字 | git revert HEAD --no-edit |
注意 --no-edit:回滚不弹出提交信息编辑器,保证无人值守循环不被交互卡死。
Phase 7:Log(记录)
将一行追加到结果 TSV:iteration、timestamp、commit/-、metric、delta、guard 状态、guard-metric、status、description。
有界检查(Bounded Check)
若为有界模式且 current_iteration >= max_iterations,退出循环并打印汇总。
七、Eval 检查点(--evals 标志)
协议要求:当 --evals 存在时,循环必须在固定间隔暂停并做检查点分析:
- 自适应间隔:
floor(max_iterations / 3),最小为 1;无界模式固定为 10;可用--evals-interval N覆盖; - 每隔
{interval}次迭代暂停,分析当前结果 TSV,打印格式(不超过 5 行):--- Eval Checkpoint (iterations {X}-{Y}) --- Metric: {start} → {end} ({delta}) | Kept: {n}/{total} | Trend: {up/flat/down} {one-line recommendation} --- - 连续 3+ 个检查点检测到平台期(plateau) → 推荐提前停止(early stop);
- 循环结束时,向输出目录写入完整的 evals 汇总
evals-summary.md。
不同子命令的默认检查点频率(来自 claude-plugin/commands/autoresearch/evals.md 的表格):
| 子命令 | 默认迭代数 | 间隔 | 检查点位置 |
|---|---|---|---|
| reason | 8 | 2 | 2, 4, 6, 8 |
| learn | 10 | 3 | 3, 6, 9, 最终 |
| debug/security | 15 | 5 | 5, 10, 15 |
| fix/scenario | 20 | 6 | 6, 12, 18, 最终 |
| 核心 loop | 25 | 8 | 8, 16, 24, 最终 |
| 无界 | unlimited | 10 | 每 10 次 |
八、循环结束后的汇总与链式交接
8.1 汇总输出
循环结束后打印:总迭代数、keep/discard 计数、起始指标 → 最终指标、改善百分比、效果最好的前 3 个变更(从 keep 迭代的描述中提取)。
8.2 Chain Handoff(链式交接)
协议要求把循环结果落盘为 handoff.json 写入输出目录,字段包括:
version:"2.1.0"(交接协议版本,多命令通用);source:"loop";timestamp;status:COMPLETE | USER_INTERRUPT | BOUNDED | ERROR之一;results_tsv:结果文件路径;findings[]:关键发现数组;config:{goal, scope, metric, direction, verify}(即本轮完整配置)。
随后按 --chain <targets> 指定的顺序调用下一个目标命令,并传播 --evals 标志,使下游命令保持相同的检查点行为。--<subcommand> 是 --chain <subcommand> 的简写形式。技能总入口 claude-plugin/skills/autoresearch/SKILL.md 为所有子命令定义了统一的交接不变量:所有结果写入 autoresearch/{subcommand}-{YYMMDD}-{HHMM}/ 目录;链式交接经由 handoff.json;evals 读取 *-results.tsv。
九、底层确定性接缝:orchestrate.sh 与循环的支撑
虽然 loop 命令自身是智能体驱动的,但整个 Autoresearch 家族有一个确定性接缝——claude-plugin/skills/autoresearch/scripts/orchestrate.sh,所有路由逻辑都在这个纯 bash 脚本中,全部子命令可用 exit code 在 CI 中使用:
| 子命令 | 输入 | 输出/语义 |
|---|---|---|
classify <goal> |
目标字符串 | 关键字启发式映射到 9 种 Goal 原型之一:harden / fix-broken / ship-ready / what-to-build / build-feature / optimize-metric / document / decide-design / explore(优先级排序:安全 > 修复 > 发布 > 产品方向 > 构建 > 优化 > 文档 > 决策 > 探索) |
next-hop <state.json> |
编排状态 | 廉价路由:errors_remaining>0 → fix;regression_verdict==UNSTABLE → regression;untested_gaps>0 → debug;pending_verify==true → verify;ship 原型全清 → ship;否则 DONE |
units <results.json> |
结果 JSON | Units-remaining 标量 = failing_tests + open_hard_regressions + (metric_delta/metric_target)(lower_is_better);缺字段或除零时输出 unknown 且 exit 2 |
plateau <history.txt> |
单元历史 | 窗口 N=5 内"末值严格低于首值"才算改善;震荡净持平也算平台期;5 个连续 unknown 视为 BLOCKED(exit 3)而非"仍在改善" |
screen-cmd <shell> |
shell 字符串 | 第四节的安全门,"ok" exit 0 / "refuse" exit 1 |
verdict <state.json> |
编排状态 | 综合 units/plateau/ceiling 输出 `CONVERGED |
validate-state <state.json> |
编排状态 | 用 Node 解析器做 schema 闸门:goal/archetype/predicate/terminal_choice 必须为非空字符串、cycle 为非负整数、units_remaining/pipeline_log 为数组;畸形账本不可用于路由 |
screen-state-predicate <state.json> |
编排状态 | 从持久化状态中提取 pin 住的谓词命令并重新过 screen-cmd——持久化命令永不被信任,恢复(resume)时必须重新审查 |
值得强调的是几个设计细节(均可从源码直接验证):
- classify 的优先级顺序是有意的:
fix and add the broken feature必须路由到fix-broken而不是build-feature,因为修复的优先级高于构建;"安全"高于"添加"同理。 - plateau 对震荡的处理:只要窗口内净变化为持平或更差就判定平台期,防止"反复横跳"的循环白白跑到上限。测试夹具
tests/fixtures/orchestrator/plateau-oscillate.txt专门验证了这一行为。 - unknown 不算零进展:
units返回unknown(如 runner 崩溃)的循环不计入平台期计数,但连续 unknown 会路由到BLOCKED。 - 恢复安全:从持久化状态恢复时,pin 住的谓词命令会被重新审查(
screen-state-predicate),即使状态文件被投毒(如转义引号截断、Unicode 转义的危险命令),审查也必须看到完整命令。对应测试用例见 tests/test-orchestrator.sh 中的state-escaped-quote-predicate.json与state-unicode-danger-predicate.json。
这些子命令的完整回归测试(约 200 条断言,覆盖 classify 优先级、next-hop 决策表、units 计算、plateau 收敛、screen-cmd 全矩阵、verdict、validate-state、screen-state-predicate)都位于 tests/test-orchestrator.sh。
十、实战配置示例
下面是从配套指南 guide/autoresearch.md 中提取的完整可用示例。核心经验是:Verify 命令必须"一个数字、干净提取",通常用 grep/awk/jq 从工具输出中切出指标值。
10.1 提升测试覆盖率(有界)
/autoresearch
Iterations: 20
Goal: Increase test coverage from 72% to 90%
Scope: src/**/*.test.ts, src/**/*.ts
Metric: coverage % (higher is better)
Verify: npm test -- --coverage | grep "All files"
10.2 降低打包体积(带 Guard)
/autoresearch
Iterations: 15
Goal: Reduce production bundle size below 200KB
Scope: src/**/*.tsx, src/**/*.ts
Metric: bundle size in KB (lower is better)
Verify: npm run build 2>&1 | grep "First Load JS"
Guard: npm test
10.3 消灭 TypeScript any(自定义 grep 指标)
/autoresearch
Iterations: 25
Goal: Eliminate all TypeScript `any` types
Scope: src/**/*.ts
Metric: count of `any` occurrences (lower is better)
Verify: grep -r ":\s*any" src/ --include="*.ts" | wc -l
Guard: tsc --noEmit
10.4 API 性能(p95 延迟)
/autoresearch
Iterations: 20
Goal: API response time under 100ms (p95)
Scope: src/api/**/*.ts, src/services/**/*.ts
Metric: p95 response time in ms (lower is better)
Verify: npm run bench:api | grep "p95"
Guard: npm test
10.5 Python(pytest 覆盖率)
/autoresearch
Iterations: 30
Goal: Increase pytest coverage from 68% to 90%
Scope: tests/**/*.py, app/**/*.py
Metric: coverage % (higher is better)
Verify: pytest --cov=app --cov-report=term-missing 2>&1 | grep "TOTAL" | awk '{print $4}'
10.6 Go(覆盖率)
/autoresearch
Iterations: 25
Goal: Increase test coverage to 85%
Scope: **/*.go
Metric: coverage % (higher is better)
Verify: go test ./... -coverprofile=cover.out && go tool cover -func=cover.out | grep "total:" | awk '{print $3}'
10.7 ML 训练损失(无界 + awk 取末行最后一列)
/autoresearch
Iterations: unlimited
Goal: Reduce validation loss (val_bpb)
Scope: train.py, model.py
Metric: val_bpb (lower is better)
Verify: uv run train.py --epochs 1 2>&1 | grep "val_bpb" | tail -1 | awk '{print $NF}'
10.8 带 Eval 检查点(每 5 次)
/autoresearch
Iterations: 25
Goal: Reduce lint errors to zero
Scope: src/**/*.ts
Metric: lint error count (lower is better)
Verify: npx eslint src/ 2>&1 | grep -c "error"
--evals
--evals-interval 5
10.9 Guard 模式速查
Guard 的作用是"优化某个指标的同时防止其他方面回归":
# 优化体积但不弄坏测试
Guard: npm test
# 优化性能但不破坏类型与测试
Guard: tsc --noEmit && npm test
# 优化指标但不破坏端到端
Guard: npx playwright test
Guard 失败恢复流:指标改善但 Guard 失败 → 立即回滚 → 阅读 Guard 输出定位破坏点 → 重做优化(最多 2 次尝试)→ 都失败则放弃该变更,进入下一迭代。这一"rework max 2 attempts"上限在协议和 guide/autoresearch.md 中均有明确约定,防止陷入单点修复的局部死循环。
十一、结果 TSV 的可读性:阅读与复用
一次典型运行结束后,autoresearch/loop-*/results.tsv 看起来像这样(列省略了 timestamp/guard-metric 以聚焦语义):
iteration commit metric delta guard status description
0 a1b2c3d 85.2 0.0 - baseline initial state
1 b2c3d4e 87.1 +1.9 pass keep add auth edge case tests
2 - 86.5 -0.6 - discard refactor helpers
3 c3d4e5f 88.3 +1.2 pass keep add error handling tests
commit列回滚的迭代为-(无提交保留);status列完整枚举了第五节定义的六种结局(baseline/keep/discard/crash/no-op/hook-blocked/metric-error),也兼容 v2.0.03 的keep (reworked)历史值;- 运行后用
/autoresearch:evals分析趋势、平台期与改进速率,其列级分析规则(metric趋势、delta效率、status胜率、guard失败率、commit热点等)见 claude-plugin/commands/autoresearch/evals.md。
十二、有界 vs 无界:选择策略
| 维度 | 有界(Iterations: N) |
无界(Iterations: unlimited) |
|---|---|---|
| 停止条件 | N 次迭代完成 | 目标达成或 Ctrl+C |
| 适用场景 | 冲刺(sprint)、CI、固定预算 | 过夜运行 |
| CI 中使用 | 可以 | 仅在外部设置超时的情况下 |
| 默认值 | 25 | 不适用 |
实践建议(来自 guide/autoresearch.md):在不熟悉的代码库上先跑 Iterations: 10 校准,结果满意再放大或去掉上限。git log 可以看到每次实验提交(experiment: ... 前缀),git revert <hash> 可以单独撤销任意一次变更。
十三、何时该用其他子命令
/autoresearch 面向"指标可度量"的场景;指标不明、需求不清、错误待修等场景应切换到家族内的其他命令:
| 场景 | 命令 |
|---|---|
| 有可度量的指标要提升 | /autoresearch(本文) |
| 不知道该用什么指标 | /autoresearch:plan |
| 需求不清楚 | /autoresearch:probe |
| 测试挂、类型坏、lint 红 | /autoresearch:fix |
| 有 bug 但不知在哪 | /autoresearch:debug |
| 发布前安全审查 | /autoresearch:security |
| 准备上线 | /autoresearch:ship |
| 构建前探索边界情况 | /autoresearch:scenario |
| 想先听专家意见 | /autoresearch:predict |
这些命令共享同一套安全不变量与交接协议(见 claude-plugin/skills/autoresearch/SKILL.md 的子命令总表),并可通过 --chain 组合成完整流水线;组合玩法可参考 guide/chains-and-combinations.md。
十四、安全不变量:贯穿所有子命令的红线
最后,把安全设计总结为三条贯穿性不变量(均可在 claude-plugin/skills/autoresearch/SKILL.md 中直接确认):
- 未经用户明确批准,绝不 push、publish、deploy。循环只能在本地产出提交与回滚;
- 默认有界,无界必须显式
Iterations: unlimited选择; - 所有结果必须落盘日志:
autoresearch/{subcommand}-{YYMMDD}-{HHMM}/,链式交接经由handoff.json,evals 读取*-results.tsv。
加上 Verify/Guard 命令的双重审查(第四节 screen-cmd 矩阵)与 git 提交/回滚机制,/autoresearch 得以在"全自动反复修改代码"的前提下保持可追溯、可回滚、可中断,这正是它区别于普通批量修改工具的核心设计。