Autoresearch for Software Development

全自动化软件开发工具，你只需负责喝茶和睡觉。 一觉醒来，Features 全自动高质量的实现了。

基于 karpathy/autoresearch 思想实现的通用的基于 GitHub Issue 管理的全自动化开发工具。支持任意 Git + GitHub 项目（Go、Node.js、Python、Rust、Java 等）。

使用 autoresearch 实现本项目 Issue#2：

---

目录

• 快速开始
• 前置条件
• 项目架构
• 工作流程
• 工具配置
• 与 ralph 对比

---

快速开始

# 下载项目
git clone git@github.com:smallnest/autoresearch.git

# 处理当前目录项目的 Issue#10
autoresearch/run.sh 10

# 处理指定目录项目的 Issue#10
autoresearch/run.sh -p /path/to/project 10

# 指定最大迭代次数为 16 次
autoresearch/run.sh -p /path/to/project 10 16

# 调整达标线为 90 分
PASSING_SCORE=90 autoresearch/run.sh 10

# 指定启用的 agents 及顺序（首个 agent 做初始实现）
autoresearch/run.sh -a claude,codex 10

# 继续处理 Issue#42，追加 10 次迭代
autoresearch/run.sh -c 42 10

前置条件

需要安装以下工具（按需安装）：

gh auth status          # GitHub CLI
which claude            # Claude Code CLI
which codex             # OpenAI Codex CLI
which opencode          # OpenCode CLI

项目需有对应语言的构建工具（Go/Node/Python/Rust/Java）。

---

项目架构

核心流程：

组件	说明
GitHub Issue	触发输入
run.sh	核心运行器
Claude / Codex / OpenCode	三个 Agent 轮转审核
Score ≥ 85?	评分门控
PASS	自动创建 PR → 合并 → 关闭 Issue
FAIL	进入下一轮迭代修复

Agent 轮转公式：(iter − 1) % N

---

工作流程

单 Issue 流程

Issue → 首个 Agent 实现 → 轮转审核+修复 → 自动 PR → 合并 → 关闭 Issue

• 迭代 1: -a 列表中的第一个 agent 初始实现
• 迭代 2+: 所有启用的 agents 按顺序轮流审核并修复
• 评分达标（默认 ≥ 85）后自动创建 PR、合并、评论并关闭 Issue

推荐工作流：从 PRD 到自动实现

完整端到端工作流：PRD 生成 → Issue 拆分 → autoresearch 实现

PRD 生成 → Issue 拆分与创建 → 选择 Issue → autoresearch 实现 → 选择下一个 Issue → ...

Step 1: 生成 PRD

使用 /prd skill 生成交付需求文档：

/prd 为本项目创建一个桌面 app

Step 2: 拆分为 GitHub Issues

让智能体基于 PRD 拆分 Issue：

基于 PRD 中的 User Stories 拆分为细粒度 Issue，并在 GitHub 上创建这些 issue。

拆分原则：
- 每个 Issue 可在单次开发会话中完成
- 有明确的验收标准（checkbox）
- 标注依赖关系

Step 3: 选择 Issue 并自动实现

./run.sh 22

autoresearch 会：

1. 规划阶段：拆分 subtasks（如需要）
2. 迭代实现：首个 agent 实现 → 轮转审核 → 修复 → 评分
3. 质量门禁：Build/Lint/Test + LLM 评分 ≥ 85
4. 自动收尾：创建 PR → 合并 → 评论 Issue → 关闭 Issue

完整示例

以本项目 Desktop App 为例：19 个 Issues (#22 ~ #40) 从 PRD 到全部实现。

详细过程见 docs/desktop-app-prd-to-issues.md。

---

工具配置

项目自定义配置

在项目目录下创建 .autoresearch/：

.autoresearch/
├── agents/
│   ├── codex.md          # 自定义 Codex 指令
│   ├── claude.md         # 自定义 Claude 指令
│   └── opencode.md       # 自定义 OpenCode 指令
├── program.md            # 自定义实现规则与约束
├── workflows/            # 各 Issue 详细记录（自动生成）
└── results.tsv           # 处理结果日志（自动生成）

命令行参数

参数	默认值	说明
-p <path>	当前目录	项目路径
-a <agents>	claude,codex,opencode	指定启用 agents 及顺序
-c	关闭	继续模式，从上次中断的迭代继续
PASSING_SCORE	85	达标评分线（百分制）
MAX_CONSECUTIVE_FAILURES	3	连续失败停止阈值
MAX_RETRIES	5	单次 agent 调用重试次数

裁剪 program.md

program.md 包含多种语言的规范模板。使用前应根据目标项目语言裁剪，只保留相关规范以减少 token 消耗。

示例：Go 后端项目只需保留「通用规范」和「Go 代码规范」章节，删除 Python/TypeScript/Rust/前端等无关章节。

文件说明

文件	用途
run.sh	主脚本
lib/agent_logic.sh	agent 列表解析与轮转共享逻辑
program.md	默认实现规则与约束
agents/*.md	Agent 提示词模板
tests/test_agent_logic.sh	agent 选择与顺序逻辑测试

---

与 ralph 对比

ralph 是类似的自动化开发工具。

核心差异

维度	autoresearch	ralph
驱动方式	GitHub Issue	PRD（prd.json）
Agent 模型	多 Agent 轮转交叉审核	单 Agent 反复迭代
质量门禁	硬门禁（Build/Lint/Test）+ 软门禁（LLM 评分）	纯工具链检查
审核机制	不同 Agent 交叉审核	无独立审核
端到端	Issue → PR → 合并 → 关闭（全自动闭环）	止步于代码完成
Continue 模式	支持 -c 恢复	无
UI 验证	浏览器截图 + LLM 视觉验证	dev-browser skill

各自优势

autoresearch 优势：

• 双轨质量门禁覆盖更广
• 多 Agent 交叉审核提供不同视角
• GitHub 端到端自动化闭环
• 上下文溢出自动交接
• Continue 模式支持中断恢复

ralph 优势：

• PRD 驱动，语义更丰富
• 四通道记忆形成完整知识体系
• 确定性质量门禁更稳定
• Skills 插件系统可扩展
• 内置流程序可视化

---

类似项目

• snarktank/ralph
• karpathy/autoresearch（原版思想）
• 达尔文.skill: 使用 autoresearch 优化Skill, 花叔出品