Claude Code 自主迭代循环:autoresearch 的 Modify → Verify → Keep/Discard 自动化调优协议详解

原创2026-10-08 21:35:551,429 阅读
文章标签:AI 技能AI 插件代码质量开发工具

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 都要:

  1. 阅读代码库、git 历史和结果 TSV,判断"什么有效、什么失败、什么还没试过";
  2. 做出一个可在一句话内解释的原子化变更;
  3. 提交(保证回滚永远干净);
  4. 运行 Verify 命令提取数值指标;
  5. 运行 Guard(如配置);
  6. 指标改善且 Guard 通过则 keep,指标恶化则 git revert;
  7. 将结果追加到 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),非关键问题仅警告:

  1. 确认存在 git 仓库:git rev-parse --git-dir;
  2. 检查工作树是否干净:git status --porcelain —— 若脏则警告(脏工作树会污染基线测量);
  3. 检查是否存在陈旧的锁文件、是否处于 detached HEAD;
  4. 若配置了 Guard,先运行一次 Guard 建立 guard 基线(作为 iteration 0 的 guard-metric);
  5. 任何关键问题立即中止。

四、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)

正式循环开始前必须先建立可复现的基线:

  1. 运行 Verify 命令,从输出中提取数值指标;
  2. 作为 iteration 0 写入 TSV,行格式为:
    0\t{timestamp}\t{commit}\t{metric}\t0.0\t{guard}\t-\tbaseline\tinitial state
    
    (即:迭代号、时间戳、提交、指标值、delta 恒为 0.0、guard 状态、guard 指标、状态为 baseline、描述为 initial state)
  3. 创建输出目录:autoresearch/loop-{YYMMDD}-{HHMM}/(例如 autoresearch/loop-261008-2134/),所有循环产物都落在此目录;
  4. 写入 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 中直接确认):

  1. 未经用户明确批准,绝不 push、publish、deploy。循环只能在本地产出提交与回滚;
  2. 默认有界,无界必须显式 Iterations: unlimited 选择;
  3. 所有结果必须落盘日志:autoresearch/{subcommand}-{YYMMDD}-{HHMM}/,链式交接经由 handoff.json,evals 读取 *-results.tsv。

加上 Verify/Guard 命令的双重审查(第四节 screen-cmd 矩阵)与 git 提交/回滚机制,/autoresearch 得以在"全自动反复修改代码"的前提下保持可追溯、可回滚、可中断,这正是它区别于普通批量修改工具的核心设计。

登录后查看全文
autoresearch