by smallnest

我把 Karpathy 的 AutoResearch 搬到了软件开发领域，效果炸了

像 Karpathy 训模型一样开发软件。

Andrej Karpathy 的 AutoResearch 项目于 2026 年 3 月发布，短短几天内在 GitHub 收获 5 万+ 星标，介绍视频播放量达 860 万次。这是一款开源 Python 工具，代码量仅 600 行左右，可让 AI 智能体在无需人工干预的情况下，于单张 GPU 上自主运行机器学习实验。它通过修改训练代码文件（train.py）生成实验方案，以固定 5 分钟训练时长和验证比特率（val_bpb）为统一评估指标，自动筛选并保留效果更优的代码修改，形成「假设生成 → 训练执行 → 指标判断 → 结果回滚/保留」的循环机制。

这个项目的精髓在于三点：① 量化目标（val loss 是唯一判断标准）、② 自主循环（Agent 不需要人类每轮介入）、③ 只保留改进（退化就回滚，绝不将就）。预计每小时可完成约 12 次实验，一觉醒来就能收获上百轮自动优化的结果。

这套思路在 ML 研究领域验证有效后，我开始思考：软件开发领域能否复刻同样的魔法？把"修改 train.py → 跑 5 分钟实验 → val loss 改善才保留"，替换成"实现 GitHub Issue → 跑测试 → 多维评分达标才合并"——这就是本项目的起点。实测下来，10 分钟完成一个中等复杂 Issue，全程零人工干预，最终评分 9.0/10。

写这篇文章时，正好看到花叔写的一个 Skill：达尔文.skill，可谓殊途同归——他在 Skill 开发 领域同样应用 AutoResearch 方法实现对 Skill 技能的优化。后来花叔把这个经验总结到他的另外一个 Skill 项目上：auto-optimize-skill。

为什么做这个

传统的"人类写代码 → 运行测试 → 修复问题"流程，在 GitHub Issues 有几十上百个待处理项时不再可行。

即使用 Claude Code / Codex 等 AI 编程工具（所谓的 vibe coding），你仍然需要：

  • 一轮一轮地 chat 交互，告诉 AI 做什么
  • 人工检查输出、发现问题、再告诉 AI 改什么
  • 人始终被绑在循环里，离开就不转了

2025 年底流行的 Ralph Wiggum 方法（while true; do cat PROMPT.md | claude; done）更进一步：写好 SPEC，让单 Agent 在循环里自主干活。解决了人的 chat 交互问题，但本质是单个 Agent 的自我循环——自己写、自己测、自己改，没有外部审核视角，质量全靠测试 backpressure 和 prompt 工夫。

2026 年 3 月 Karpathy 发布了 autoresearch，把同样的循环思路用到了 ML 研究领域：写一个 program.md 定义目标和约束，AI 自主修改训练代码、跑 5 分钟快速实验，只有 val loss 改善时才 commit，否则 git revert。核心创新是把"什么是改进"量化成了一个明确的 metric。

本项目的 AutoResearch 在 Karpathy 思想基础上做了三个关键改进：

1. 多 Agent 交叉审核，替代单 Agent 自审。 Ralph Wiggum 和 Karpathy AutoResearch 都是单 Agent 自己改自己评，缺少外部视角。本项目让 Codex 和 Claude 轮流担任实现者和审核者：A 写完 B 审，B 写完 A 审。不同模型有不同的盲区和强项，交叉审核能发现单 Agent 发现不了的问题。实践中也发现，单 Agent 效果远不如双 Agent 对抗。本项目创造性地使用两个 Agent 轮流审核和开发，大幅提升了代码质量。

2. 5 维度加权评分，替代单一 metric。 Karpathy 用 val loss 一个数字判断好坏，ML 场景下够用。但软件工程的质量是多维的——功能正确、测试充分、代码规范、安全无漏洞、性能没坑。本项目用 5 维度加权评分（正确性 35% + 测试 25% + 代码质量 20% + 安全 10% + 性能 10%），总分 ≥ 9.0 才算通过，把"代码好不好"从主观判断变成量化指标。

3. 审核反馈驱动下一轮实现，替代盲循环。 Ralph Wiggum 的每轮循环是独立的——新上下文重新开始，不记得上轮犯过什么错。本项目的审核反馈直接传入下一轮 Agent 的提示词，Agent 看到上一轮的具体问题后针对性改进，而不是漫无目的地重试。

最终效果：人只提供 Issue 号，剩下的全自动——自动实现、自动测试、自动审核、自动迭代、评分达标后自动 PR + 合并。

下面的全景图展示了从传统开发到本项目的演进路径：

不是所有 Issue 都适合交给 Agent 处理。系统通过排除规则、优先级计算和复杂度评估三个维度来筛选。

排除规则： 以下 Issue 不处理：wontfix / duplicate / invalid / blocked / needs discussion / on hold / external，标题含 [WIP] [DRAFT]，正文含 DO NOT IMPLEMENT，已有 PR 关联。

优先级计算：

1
分数 = 基础权重(15) + 标签权重 + 类型权重 + 时间因子
  • 标签权重：critical(100) > high(50) > medium(20) > low(10)
  • 类型权重：bug(30) > feature(20) > refactor(10) > test(5) > docs(3)
  • 时间因子：新 Issue +10 / 陈年 Issue +15 / 近期更新 +5

复杂度评估：

复杂度 信号 迭代预算 时间预算
简单 fix/typo/update、<100 字、单文件 3 次 10m
中等 add/implement/refactor、100-500 字、2-3 模块 5 次 30m
复杂 redesign/migrate/architecture、>500 字、多模块 5 次 60m

program.md 要点

program.md 是整个系统的"宪法"，定义了 Agent 的权限边界和代码规范。以下以 Go 项目为例展示其核心内容。

权限边界：

1
2
3
4
5
6
7
8
9
10
11
12
13
Agent 可以:
  ✓ 修改 internal/, cmd/
  ✓ 创建/修改测试文件
  ✓ 运行测试和 lint
  ✓ 创建本地分支和 commit
  ✓ 在 workflows/ 记录日志

Agent 不可以:
  ✗ 修改 go.mod, .github/, Makefile, CI/CD
  ✗ 删除任何现有文件
  ✗ 推送到远程仓库（由 run.sh 统一处理）
  ✗ 关闭 Issue
  ✗ 修改 autoresearch/ 规则文件

代码规范（Go）：

1
2
3
4
5
1. 遵循 Effective Go + Go Code Review Comments
2. gofmt + goimports + golangci-lint
3. 包名小写、文件名下划线、导出大写
4. 接口用 er 后缀 (Reader, Handler)
5. 错误用 fmt.Errorf 包装，提供上下文

测试规范：

1
2
3
4
5
1. 所有新功能必须有单元测试
2. 覆盖率 ≥ 70%
3. 表格驱动测试
4. 命名 Test<Function>_<Scenario>
5. 禁止 time.Sleep、外部依赖、全局状态、硬编码端口

错误处理

自动化流程离不开健壮的错误处理，系统设计了三层保护机制。

退火重试： API 调用失败时使用指数退避 + 随机抖动（delay = 2^retry × base_delay + random_jitter，最大等待 60 秒，最多重试 10 次）。

连续失败保护： Agent 执行失败 → 连续失败计数 +1，连续失败 ≥ 3 次 → 停止运行，记录日志。

测试失败： 测试失败 → 反馈"测试失败" → 下一轮 Agent 针对性修复。

运行结果

results.tsv 格式：

1
2
3
timestamp   issue_number  issue_title  status     iterations  tests_passed  score  branch_name
2026-04-01  15            event proto  completed  2           true          9.1    feature/issue-15
2026-04-01  6             web UI       completed  5           true          9.5    feature/issue-6

状态定义：

状态 含义
completed 达标，已自动 PR + 合并
blocked 遇到阻塞，需人工介入
impossible Issue 无法实现
agent_failed Agent 连续失败

快速开始

1. 前置条件

因为需要自动化处理 GitHub 的 Issue，所以需要安装 GitHub CLI。
因为直接调用 Codex 和 Claude，所以需要安装 Codex CLI 和 Claude Code。
因为本项目使用 Go 语言开发，所以需要安装 Go 环境。

1
2
3
4
5
6
7
8
9
10
11
# GitHub CLI (gh)
gh auth status

# Codex CLI
which codex

# Claude Code
which claude

# Go 环境
go version

2. 运行

调用run.sh脚本，直接输入issue号即可运行。

1
2
3
4
5
6
7
8
# 进入你要处理的 GitHub 项目目录
cd /path/to/your/github/project

# 处理单个 Issue
/path/to/autoresearch/run.sh 21

# 指定最大迭代次数
/path/to/autoresearch/run.sh 21 10

脚本会自动：检查环境 → 获取 Issue → 创建分支 → 轮流 Codex/Claude 实现+审核 → 达标后自动 PR + 合并。

3. 自定义配置

在项目根目录创建 .autoresearch/ 目录可覆盖默认配置：

1
2
3
4
5
6
.autoresearch/
├── agents/
│   ├── codex.md     # 自定义 Codex 指令
│   └── claude.md    # 自定义 Claude 指令
├── workflows/       # 自动生成
└── results.tsv      # 自动生成

实战案例

以下是我实际开发中的真实案例。特别值得一提的是 Issue #21，我专门使用 asciinema 记录了它自动开发的全过程。

Issue #21: feat: enhance job execution with agent selection and timeout

我只需提供一个 Issue 号，剩下的就由 AutoResearch 脚本自动完成：

1
./docs/autoresearch/run.sh 21

默认设置最多执行 42 轮迭代，但基本几轮之后代码质量就达到了标准。下面是 Issue #21 的迭代过程，大约 10 分钟就完成了开发，总共迭代 3 轮。

你可以点击回放链接查看完整过程，以下是录制截图：

关键日志：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
复杂度：中等（涉及 Job 结构体扩展、超时控制、API 增强）
Issue 内容：为 Job 添加 AgentName/Timeout/MaxRetries 字段，超时自动取消，失败自动重试

迭代 1 (Codex):  评分 1.0   → Codex 只读取了代码就结束，功能完全未实现
迭代 2 (Claude): 评分 5.0   → Codex 实现了超时控制和 API 增强，但 Claude 审核发现不足
迭代 3 (Codex):  评分 9.0   → 达标！
→ 自动 commit + PR + 合并 ✓

代码改动：
  - internal/job/job.go: 添加 Timeout 字段和 context.WithTimeout 超时控制
  - internal/job/job_test.go: 新增 TestExecuteJob_Timeout 等测试用例
  - internal/gateway/server.go: REST API 和 JSON-RPC 支持 timeout 参数

总耗时：约 10 分钟（17:38 → 17:47）
总迭代次数：3 轮
最终评分：9.0/10
回放链接：https://asciinema.org/a/896260

Issue #15: feat: define source-of-truth event protocol

Issue #15 只迭代了两轮就达标，关键日志如下：

1
2
3
4
5
迭代 1 (Codex):  评分 5.0  → 反馈：设计方向问题
迭代 1 (Claude): 评分 7.0  → 反馈：改进实现细节
迭代 2 (Codex):  评分 9.1  → 达标！
→ 自动 commit + PR + 合并 ✓
总迭代次数：2 轮（奇数轮 Codex 实现 + Claude 审核，Claude 补充实现 + Codex 审核）

Issue #6: feat: add web UI for sessions

Issue #6 迭代了 5 轮达标，关键日志如下：

1
2
3
4
复杂度：高（涉及多个模块、需要设计决策）
迭代次数：5 轮
最终评分：9.5/10（Claude 和 Codex 均给出高分）
→ 自动 PR + 合并 ✓

最佳实践

基于实际运行经验，总结以下几点实践建议：

  1. 从小 Issue 开始：先用简单的 Issue（bug fix）测试流程
  2. 保持 program.md 更新：根据运行情况调整规则和约束
  3. 关注评分趋势：每次迭代的评分记录在 log.md 中，观察是否稳步上升
  4. 利用多 Agent 对抗：Codex/Claude 轮流实现+审核，交叉验证减少盲区
  5. 退火重试：API 不稳定时脚本自动退避重试，无需人工干预

设计灵感

  • karpathy/autoresearch — 核心循环：只保留可测量的改进，其余全部回滚
  • Codex — OpenAI Codex CLI，直接调用进行代码实现和审核
  • Claude Code — Anthropic Claude Code CLI，直接调用进行代码审核和实现
  • imclaw — 本项目的开源仓库，包含完整的 AutoResearch for Development 实现