Claude Autoresearch

将 Claude Code 转化为永不停歇的改进引擎。

基于 Karpathy 的 autoresearch —— 约束 + 机械化指标 + 自主迭代 = 复利增长。

"设定目标 → Claude 运行循环 → 你醒来时收获结果"

你不需要 AGI。你需要的是一个目标、一个指标，和一个永不放弃的循环。

为什么创建这个项目

Karpathy 的 autoresearch 证明了：一个 630 行的 Python 脚本可以自主地在一夜之间改进 ML 模型 —— 每晚 100 次实验 —— 通过遵循简单的原则：一个指标、受限范围、快速验证、自动回滚、git 作为记忆。

Claude Autoresearch 将这些原则推广到任何领域。 不仅仅是 ML —— 代码、内容、营销、销售、人力资源、DevOps，或任何可以用数字衡量的领域。

工作原理

循环（无限 或 N 次）:
  1. 审查当前状态 + git 历史 + 结果日志
  2. 选择下一个变更（基于有效的、失败的、未尝试的）
  3. 进行一次聚焦的变更
  4. Git 提交（验证之前）
  5. 运行机械化验证（测试、基准测试、评分）
  6. 如果改进 → 保留。如果变差 → git revert。如果崩溃 → 修复或跳过。
  7. 记录结果
  8. 重复。永不停止，直到你中断（或完成 N 次迭代）。

每一次改进都会累积。每一次失败都会自动回滚。进度以 TSV 格式记录。

设置阶段

在循环开始之前，Claude 会执行一次性的设置：

读取上下文 —— 读取所有范围内的文件
定义目标 —— 提取或询问一个机械化指标
定义范围 —— 哪些文件可以修改，哪些只读
建立基线 —— 在当前状态下运行验证（迭代 #0）
确认并开始 —— 显示设置，然后开始循环

8 条关键规则

#	规则
1	循环直到完成 —— 无限：永远。有限：N 次后总结
2	写前先读 —— 修改前理解完整上下文
3	每次迭代一个变更 —— 原子性变更。如果出错，你知道原因
4	仅机械化验证 —— 不要主观的"看起来不错"。使用指标
5	自动回滚 —— 失败的变更立即回滚
6	简洁至上 —— 相同结果 + 更少代码 = 保留
7	Git 是记忆 —— 实验以 `experiment:` 前缀提交，`git revert` 在历史中保留失败的实验，代理必须在每次迭代前读取 `git log` + `git diff`
8	卡住时，深度思考 —— 重读、组合接近成功的尝试、尝试激进的变更

命令

命令	功能
`/autoresearch`	运行自主迭代循环（无限）
`Iterations: N`	添加到内联配置以精确运行 N 次迭代后停止
`/autoresearch:plan`	交互式向导：目标 → 范围、指标、验证配置
`/autoresearch:security`	自主 STRIDE + OWASP + 红队安全审计
`/autoresearch:ship`	通用发布工作流（代码、内容、营销、销售、研究、设计）
`/autoresearch:debug`	自主漏洞搜寻循环 —— 科学方法 + 迭代调查
`/autoresearch:fix`	自主修复循环 —— 迭代修复错误直到零错误
`/autoresearch:scenario`	场景驱动的用例生成器 —— 探索情况、边缘情况、衍生场景
`Guard: <command>`	可选安全网 —— 必须通过才能保留变更

所有命令在无参数调用时使用 AskUserQuestion 进行交互式设置。 只需输入命令 —— Claude 会根据你的代码库逐步询问你需要什么，并提供智能默认值。高级用户可以通过内联提供标志来跳过向导。

快速决策指南

我想要...	使用
提高测试覆盖率 / 减少包体积 / 任何指标	`/autoresearch`（添加 `Iterations: N` 进行有限运行）
不知道用什么指标	`/autoresearch:plan`
运行安全审计	`/autoresearch:security`
发布 PR / 部署 / 版本	`/autoresearch:ship`
优化但不破坏现有测试	添加 `Guard: npm test`
搜寻代码库中的所有漏洞	`/autoresearch:debug`（添加 `Iterations: 20` 进行有限运行）
修复所有错误（测试、类型、lint）	`/autoresearch:fix`
调试然后自动修复	`/autoresearch:debug --fix`
检查是否准备好发布	`/autoresearch:ship --checklist-only`
探索功能的边缘情况	`/autoresearch:scenario`
生成测试场景	`/autoresearch:scenario --domain software --format test-scenarios`
压力测试用户旅程	`/autoresearch:scenario --depth deep`

快速开始

1. 安装

选项 A —— 插件安装（推荐）：

步骤 1： 注册 autoresearch 市场（一次性）。将此条目添加到 ~/.claude/plugins/known_marketplaces.json：

{
  "autoresearch": {
    "source": { "source": "github", "repo": "uditgoenka/autoresearch" },
    "installLocation": "<HOME>/.claude/plugins/marketplaces/autoresearch",
    "lastUpdated": "2026-03-16T00:00:00.000Z"
  }
}

将 <HOME> 替换为你的主目录路径（例如，macOS 上是 /Users/yourname，Windows 上是 C:\\Users\\yourname，Linux 上是 /home/yourname）。如果文件已有条目，将 "autoresearch": { ... } 作为新键添加到现有条目旁边。

步骤 2： 重启 Claude Code，然后运行：

/plugin install autoresearch@autoresearch

就这样。所有 6 个命令立即可用。

选项 B —— 手动复制：

git clone https://github.com/uditgoenka/autoresearch.git
# 或者
将下载后的 autoresearch 目录复制到你的项目中

# 将 skill 和子命令复制到你的项目
cp -r autoresearch/skills/autoresearch .claude/skills/autoresearch
cp -r autoresearch/commands/autoresearch .claude/commands/autoresearch

或全局安装：

cp -r autoresearch/skills/autoresearch ~/.claude/skills/autoresearch
cp -r autoresearch/commands/autoresearch ~/.claude/commands/autoresearch

注意： commands/ 目录是子命令（/autoresearch:ship、/autoresearch:plan、/autoresearch:security）工作所必需的。

2. 运行

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

3. 离开

Claude 读取所有文件，建立基线，并开始迭代 —— 一次一个变更。保留改进，自动回滚失败，记录一切。永不停止，直到你中断（或完成 N 次迭代）。

/autoresearch:plan —— 目标 → 配置向导

最难的部分不是循环 —— 而是正确定义范围、指标和验证。/autoresearch:plan 将你的自然语言目标转换为经过验证的、可执行的配置。

/autoresearch:plan
Goal: Make the API respond faster

向导会引导你完成 5 个步骤：捕获目标 → 定义范围 → 定义指标 → 定义方向 → 验证验证命令（干运行）。每个门槛都是机械化的 —— 范围必须解析为文件，指标必须输出数字，验证必须通过干运行。

/autoresearch:security —— 自主安全审计

使用 STRIDE 威胁建模、OWASP Top 10 扫描和 4 个对抗性角色的红队分析的只读安全审计。

/autoresearch:security
Iterations: 10

它做什么： 代码库侦察 → 资产清单 → 信任边界 → STRIDE 威胁模型 → 攻击面映射 → 自主测试循环 → 结构化报告。

每个发现都需要代码证据（file:line + 攻击场景）。没有理论空谈。

标志	用途
`--diff`	仅审计自上次审计以来变更的文件
`--fix`	自动修复确认的严重/高危发现
`--fail-on <severity>`	对 CI/CD 门控返回非零退出码

输出： 创建 security/{date}-{slug}/，包含 7 个结构化报告文件。

/autoresearch:ship —— 通用发布工作流

通过 8 个阶段发布任何东西：识别 → 盘点 → 检查清单 → 准备 → 干运行 → 发布 → 验证 → 日志。

/autoresearch:ship --auto

自动检测你正在发布什么（代码 PR、部署、博客文章、邮件活动、销售演示文稿、研究论文、设计资源）并生成特定领域的检查清单 —— 每个项目都可机械化验证。

标志	用途
`--dry-run`	验证一切但不发布
`--auto`	如果检查清单通过则自动批准
`--force`	跳过非关键项目（阻塞项仍然执行）
`--rollback`	撤销上次发布操作
`--monitor N`	发布后监控 N 分钟
`--type <type>`	覆盖自动检测
`--checklist-only`	仅检查就绪状态

支持的 9 种类型： code-pr、code-release、deployment、content、marketing-email、marketing-campaign、sales、research、design。

/autoresearch:debug —— 自主漏洞搜寻器 (v1.3.0)

科学方法与 autoresearch 循环的结合。不会止步于一个漏洞 —— 使用可证伪假设、基于证据的调查和 7 种调查技术迭代搜寻所有漏洞。

/autoresearch:debug
Scope: src/api/**/*.ts
Symptom: API returns 500 on POST /users
Iterations: 20

工作原理： 收集症状 → 侦察（映射错误表面）→ 假设（具体、可测试）→ 测试（每次迭代一个实验）→ 分类（确认/证伪/不确定）→ 日志 → 重复。

每个发现都需要代码证据（file:line + 复现步骤）。每个被证伪的假设都会被记录 —— 同样有价值。使用 7 种技术：二分查找、差异调试、最小复现、追踪执行、模式搜索、逆向推理、小黄鸭。

标志	用途
`--fix`	搜寻后，自动切换到 `/autoresearch:fix`
`--scope <glob>`	限制调查范围
`--symptom "<text>"`	预填症状
`--severity <level>`	报告的最低严重级别

/autoresearch:fix —— 自主错误粉碎机 (v1.3.0)

接收一个损坏的状态并迭代修复它，直到一切通过。每次迭代一个修复。原子性、提交、验证、失败时自动回滚。

/autoresearch:fix

工作原理： 自动检测损坏的部分（测试、类型、lint、构建）→ 优先排序（阻塞项优先）→ 修复一件事 → 提交 → 验证错误数量减少 → 守护检查（无回归）→ 保留/回滚 → 重复直到零错误。

当错误数量归零时自动停止 —— 即使在无限模式下。

标志	用途
`--target <command>`	显式验证命令
`--guard <command>`	必须始终通过的安全命令
`--category <type>`	仅修复特定类型（test、type、lint、build）
`--from-debug`	从最新的调试会话读取发现

链式调用： 运行 /autoresearch:debug 并设置 Iterations: 15，然后运行 /autoresearch:fix --from-debug 并设置 Iterations: 30

/autoresearch:scenario —— 场景探索器 (v1.6.0)

自主场景探索引擎。接收一个种子场景，在 12 个维度上迭代生成情况 —— 正常路径、错误、边缘情况、滥用、规模、并发、时间、数据变化、权限、集成、恢复和状态转换。

/autoresearch:scenario
Scenario: User attempts to checkout with multiple payment methods
Iterations: 25

工作原理： 种子分析 → 分解为 12 个维度 → 每次迭代生成一个情况 → 分类（新情况/变体/重复）→ 扩展边缘情况 → 日志 → 重复直到探索完所有维度。

自适应设置：根据你提供的上下文量提供 4-8 个问题。只需输入 /autoresearch:scenario 而不带其他任何内容，它会引导你完成所有步骤。

标志	用途
`--domain <type>`	领域：software、product、business、security、marketing
`--depth <level>`	深度：shallow（10）、standard（25）、deep（50+）
`--format <type>`	输出：use-cases、user-stories、test-scenarios、threat-scenarios
`--focus <area>`	优先：edge-cases、failures、security、scale
`--scope <glob>`	限制到特定文件/功能

支持 5 个领域，具有定制的维度优先级和输出格式。与 /autoresearch:debug 链式调用以搜寻发现的边缘情况中的漏洞，或 /autoresearch:security 以审计发现的威胁场景。

Guard —— 防止回归 (v1.0.4)

在优化指标时，循环可能会破坏现有行为。Guard 是一个可选的安全网。

/autoresearch
Goal: Reduce API response time to under 100ms
Verify: npm run bench:api | grep "p95"
Guard: npm test

Verify = "指标是否改进？"（目标）
Guard = "其他东西是否损坏？"（安全网）

如果指标改进但守护失败，Claude 会重新设计优化方案（最多 2 次尝试）。Guard/测试文件永远不会被修改。

致谢： Guard 由 @pronskiy (JetBrains) 在 PR #7 中贡献。

结果跟踪

每次迭代都以 TSV 格式记录：

iteration  commit   metric  delta   status    description
0          a1b2c3d  85.2    0.0     baseline  initial state
1          b2c3d4e  87.1    +1.9    keep      add tests for auth edge cases
2          -        86.5    -0.6    discard   refactor test helpers (broke 2 tests)
3          c3d4e5f  88.3    +1.2    keep      add error handling tests

每 10 次迭代，Claude 会打印进度摘要。有限循环会打印包含基线 → 当前最佳的最终摘要。

崩溃恢复

故障	响应
语法错误	立即修复，不计入迭代
运行时错误	尝试修复（最多 3 次），然后继续
资源耗尽	回滚，尝试更小的变体
无限循环 / 挂起	超时后终止，回滚
外部依赖	跳过、记录、尝试不同方法

仓库结构

autoresearch/
├── README.md
├── EXAMPLES.md                                    ← 按领域分类的真实示例
├── LICENSE
├── .claude-plugin/
│   ├── marketplace.json                           ← 插件市场清单
│   └── plugin.json                                ← 插件元数据
├── commands/
│   └── autoresearch/
│       ├── ship.md                                ← /autoresearch:ship 注册
│       ├── plan.md                                ← /autoresearch:plan 注册
│       ├── security.md                            ← /autoresearch:security 注册
│       ├── debug.md                               ← /autoresearch:debug 注册
│       ├── fix.md                                 ← /autoresearch:fix 注册
│       └── scenario.md                            ← /autoresearch:scenario 注册
└── skills/
    └── autoresearch/
        ├── SKILL.md                               ← 主技能（由 Claude Code 加载）
        └── references/
            ├── autonomous-loop-protocol.md        ← 8 阶段循环协议
            ├── core-principles.md                 ← 7 条通用原则
            ├── plan-workflow.md                   ← 计划向导协议
            ├── security-workflow.md               ← 安全审计协议
            ├── ship-workflow.md                   ← 发布工作流协议
            ├── debug-workflow.md                  ← 调试循环协议
            ├── fix-workflow.md                    ← 修复循环协议
            ├── scenario-workflow.md               ← 场景探索协议
            └── results-logging.md                 ← TSV 跟踪格式

常见问题

问：我不知道用什么指标。 答：运行 /autoresearch:plan —— 它会分析你的代码库，建议指标，并在启动前干运行验证命令。

问：这适用于任何项目吗？ 答：是的。任何语言、框架或领域。将 skill 复制到 .claude/skills/autoresearch/，将 commands 复制到 .claude/commands/autoresearch/。

问：如何停止循环？ 答：Ctrl+C 或在内联配置中添加 Iterations: N 以精确运行 N 次迭代。Claude 在验证前提交，所以你最后的成功状态始终在 git 中。

问：我可以用于非代码任务吗？ 答：当然。销售邮件、营销文案、人力资源政策、运维手册 —— 任何有可衡量指标的事物。参见 EXAMPLES.md。

问：/autoresearch:security 会修改我的代码吗？ 答：不会。它是只读的 —— 分析代码并生成结构化报告。使用 --fix 以选择自动修复确认的严重/高危发现。

问：我可以使用 MCP 服务器吗？ 答：可以。在 Claude Code 中配置的任何 MCP 服务器在循环期间都可用于数据库查询、API 调用、分析等。参见 EXAMPLES.md。

许可证

MIT —— 参见 LICENSE。

致谢

Andrej Karpathy —— 创造了 autoresearch
Anthropic —— 提供了 Claude Code 和 skills 系统