drivelineresearch/autoresearch-claude-code

这是什么

autoresearch‑claude‑code 是一个基于 Python 的实验框架，可让您使用 Anthropic 的 Claude Code 或 OpenAI 的 Codex 代理运行 自动研究 循环。您为代理提供一个具体目标（例如，“减少测试套件运行时间”）、一个固定基准以及它可能编辑的源文件列表。该框架会创建一个临时 Git 分支，逐轮运行代理，衡量每个更改的影响，并仅自动提交那些在用户定义的预算（最大运行次数、时间或计算量）内显示出统计显著改进的编辑。所有状态都存储在 JSONL 文件中，可以检查或回滚。

适用对象

希望评估代码生成代理优化现有代码库能力的研究人员或工程师。
需要可重现、预算受限的“自我改进”循环，而无需构建自定义服务器或 MLOps 管道的团队。
任何有兴趣衡量 Claude Code 或 Codex 在具体软件任务上的实际影响的人。

核心概念

概念	作用
目标定义	一条简短的自然语言命令（例如，`优化测试套件运行时间`）告诉代理要优化什么。
基准	一个确定性评分脚本（例如，测试运行器），返回一个数值指标。
预算	对轮数、总挂钟时间以及可选地对 Codex 调用的限制。
噪声处理	框架在基线运行上校准测量噪声，只接受超出该噪声底限的指标改进。
原子状态	所有实验元数据原子地写入 JSONL；并发写入被锁定以避免损坏。
暂停/恢复	一个哨兵文件（`.autoresearch‑off`）可以暂停循环；系统可以从最后一个有效检查点恢复。
锁定评分器	使用 `--protect` 列出的文件每轮都会被哈希；代理无法修改它们，从而防止评估脚本意外损坏。

安装（快速）

# 克隆仓库
gh repo clone drivelineresearch/autoresearch-claude-code
cd autoresearch-claude-code

# 安装 Claude 技能（默认）或 Codex 技能
./install.sh --claude   # 在 ~/.agents/skills/autoresearch 下安装 Claude 钩子
# 或
./install.sh --codex    # 安装 Codex 技能
# 或同时安装两者
./install.sh --all

该脚本会创建符号链接；请保留检出目录，以便链接保持有效。使用相应的 ./uninstall.sh 标志卸载。

运行循环（Claude 示例）

初始化 – 在目标项目中，运行技能命令：
```
$ autoresearch optimize test suite runtime with at most 20 runs
```
代理会创建一个 autoresearch 工作树，记录基线，然后暂停等待您审查。
审查 – 检查 status 或 report 以查看基线指标。

恢复 – 启动自动循环：

python3 ~/.agents/skills/autoresearch/scripts/claude_loop.py \
  --max-turns 20 --max-seconds 3600 --protect path/to/scorer.py

根据评分器依赖的文件调整 --protect。

监控 – 循环会打印每轮摘要；您可以通过创建 .autoresearch‑off 来中止。
结果 – 预算用尽后，autoresearch report 会显示保留了哪些提交以及最终指标。

相同的工作流程也适用于 Codex，使用 codex_loop.py 脚本和 Codex IDE 中的 autoresearch CLI。

示例用例

该仓库附带一个 OpenBiomechanics 演示，用于预测棒球快球速度。它展示了：

如何定义输出 METRIC name=R2 的自定义评分器。
如何通过 uv sync --extra … 插入可选的後端（torch、boost、tabpfn 等）。
一个可重现的运行（./autoresearch.sh 42），记录整个搜索历史。

开发与测试

核心单元测试仅需要 Python 标准库：python -m unittest discover -s tests -v。
示例测试需要科学包；可以在 uv sync --project examples 之后运行。
Shell 脚本使用 shellcheck 进行 lint。
CI 在 Linux/macOS 上运行，并验证核心和示例套件。

限制与注意事项

噪声模型很简单；它只检查改进是否超过测量的基线方差。它不提供统计显著性检验。
该框架不对代理进行沙箱化；它依赖“锁定评分器”哈希和 Git 分支隔离来保护原始代码。
预算以轮和秒计算，而不是令牌使用量或货币成本。
OpenBiomechanics 示例的历史性 R² 跃升（0.44 → 0.78）使用了数据泄漏；仓库注明这不是一个经过验证的说法。
仅支持 Claude Code 和 Codex；添加新代理需要编写技能包装器和钩子脚本。

许可证

MIT – 您可以自由使用、修改和重新分发代码。

底线： autoresearch-claude-code 为您提供了一个现成的、可重现的循环，让 Claude Code 或 Codex 在严格的预算和安全约束下迭代改进代码库，并内置日志记录、暂停/恢复和基线噪声处理。