重大更新！我的 Claude Loop 和 Codex Loop 现已支持并行波次，让你的开发更流畅，更重要的是……更快！免费获取这些技能：
https://github.com/aronprins/claude-loop…
https://github.com/aronprins/codex-loop…

aronprins/claude-loop

来源：https://github.com/aronprins/claude-loop

Claude Loop

交给 Claude 一份 PRD，拿回一个可工作的功能。一个子 Agent 处理一个故事，每次都是全新上下文。

Claude Loop 是一个 Claude Code (https://docs.anthropic.com/en/docs/claude-code) 技能，驱动自主编码工作流。你编写一个 prd.json 列出要交付的用户故事；Claude 逐个处理它们，为每个故事通过 Task 工具生成一个全新的子 Agent。每个子 Agent 实现其故事、运行测试、提交工作并退出——这样上下文永远不会在长时间运行中堆积。运行的状态保存在 claude-loop/ 中。技能代码位于 .claude/skills/claude-loop/。仅此而已——无需脚本、守护进程或外部编排器。

为什么？

自主编码会话随着上下文填满而退化。长时间运行会忘记早期决策、重复错误，并在窗口拉伸时产生更潦草的代码。常见的变通方法——分块工作、中途总结、希望最好——无论如何都会泄露上下文。

Claude Loop 完全避开了这个问题。每个故事都获得一个全新的子 Agent。内存通过三个持久通道持续存在：

• Git 历史——每个故事产生一个干净、聚焦的提交
• progress.txt——仅追加的学习日志（顶部有一个 ## Codebase Patterns 部分，用于通用规则）
• 源树中的 AGENTS.md 文件——Claude 在它工作的任何目录中自动读取，因此每模块的知识在最有用的地方累积

结果：任意长的运行不会退化。

前提条件

• 已安装并认证的 Claude Code (https://docs.anthropic.com/en/docs/claude-code)
• 你的项目的一个 git 仓库
• 加分项：你的项目有类型检查和/或测试命令（自动检测 npm、pip、cargo、go）

安装

针对项目：

git clone https://github.com/YOUR-USER/claude-loop.git .claude/skills/claude-loop  
mkdir -p claude-loop  

全局安装（跨所有项目使用）：

git clone https://github.com/YOUR-USER/claude-loop.git ~/.claude/skills/claude-loop  

该技能会在任何安装了它的项目中的 Claude Code 会话中自动加载。对于全局安装，claude-loop/ 会在你首次在项目中运行循环时创建。

快速开始

1. 在项目根目录创建 claude-loop/prd.json。参见 prd.example.json 了解格式。
2. 在你的项目中打开 Claude Code。
3. 说出以下之一：
   • “运行 claude loop”
   • “处理 prd”
   • “处理 prd.json”
   • 或者，用于并发执行：“并行运行循环”（参见 并行模式（波次））
4. Claude 读取 PRD，检测你的技术栈，签出 branchName 分支，并开始生成子 Agent。
5. 当所有故事通过后，运行会归档到 claude-loop/archive/YYYY-MM-DD--complete/，Claude 输出 COMPLETE。

工作原理

flowchart TD  
    Start([用户：“运行循环”]) --> Read[读取 claude-loop/prd.json + progress.txt]  
    Read --> Setup[检测技术栈 / 签出分支]  
    Setup --> Check{是否有故事 passes: false？}  
    Check -->|是| Spawn[通过 Task 生成子 Agent，处理最高优先级故事]  
    Spawn --> Work[子 Agent：实现 → 测试 → 提交 → 更新 PRD → 记录学习]  
    Work --> Verify{编排器验证工作}  
    Verify -->|通过| Check  
    Verify -->|阻塞| Stop([停止并报告])  
    Check -->|否| Archive[归档 claude-loop/ 到 archive/YYYY-MM-DD/]  
    Archive --> Done([输出 COMPLETE])  

同一个 Claude Code 会话中有两个角色：

• 编排器（主 Claude 会话）：读取 PRD，管理 git 分支，通过 Task 生成子 Agent，验证输出，完成时归档。从不碰应用代码。
• 子 Agent（每个故事一次全新的 Task 调用）：实现一个故事，运行检查，提交，更新 PRD，记录学习，然后退出。

默认情况下，子 Agent 顺序 运行——故事通常接触重叠的文件，而朴素的并行执行会在 git、PRD 和 progress.txt 上产生竞态。对于独立的故事，你可以选择 并行波次模式，它增加了隔离（git worktree）和协调（合并+验证屏障）来并发运行一个波次而不出现那些竞态。

PRD

claude-loop/prd.json 是任务列表。最小格式：

{  
  "project": "MyApp",  
  "branchName": "feat/wagering-history",  
  "description": "用户下注历史 - 持久化并显示每个用户过去的下注",  
  "userStories": [  
    {  
      "id": "WAGER-001",  
      "title": "向数据库模式添加下注表",  
      "description": "作为开发人员，我需要一个数据库表来存储下注记录，以便跨会话持久化用户下注。",  
      "acceptanceCriteria": [  
        "迁移创建一个 `wagers` 表，包含 id、userId、amount、outcome、createdAt",  
        "外键指向 users 表",  
        "userId 上的索引",  
        "类型检查通过"  
      ],  
      "priority": 1,  
      "passes": false,  
      "notes": ""  
    }  
  ]  
}  

格式与 Ryan Carson 的 Ralph (https://github.com/snarktank/ralph) prd.json 类似，因此 PRD 可在两个工具之间移植。

• project — 简短的项目名称（自由格式）
• branchName — 工作所在的 git 分支（如果缺失，从 main 自动创建）
• description（顶层）— 一行功能摘要
• userStories[].description — 单个字符串，通常采用“作为 X，我想要 Y，以便 Z”的形式
• priority — 数字越小优先级越高，先处理
• dependsOn (可选) — 一个故事 ID 数组，在这些故事通过之前此故事不会开始。顺序循环忽略此项；由 并行模式 用于计算独立故事的波次。省略或留空 [] 表示无前置条件。
• passes — 初始为 false，故事提交后翻转为 true
• notes — 自由格式的记事板；子 Agent 可能在此追加上下文（例如阻塞项、部分进度）
• acceptanceCriteria — 明确且可测试。这些条件越丰富，实现越好。 如果某个约束不在这里，子 Agent 不会强制执行。

参见 prd.example.json 获取包含三种不同类型故事的完整示例。

状态存储在哪里

项目内部三个不同的位置——请区分清楚：

AGENTS.md 文件位于它们描述的代码旁边（项目根目录、模块目录）——永远不会在 .claude/ 内部。这种放置方式使它们自动加载。

为什么 claude-loop/ 位于仓库根目录，而不是在 .claude/ 中： Claude Code 将对 .claude/ 下的每次写入视为敏感并要求你确认（那里存放设置、钩子和技能）。循环在 每个 故事上都重写 prd.json 并追加 progress.txt，因此将运行时状态放在 .claude/ 中意味着每个故事都有一个确认提示——在长时间自主运行中就是成千上万次点击。顶层的 claude-loop/ 受正常的 Read/Edit/Write 权限保护，因此运行可无中断进行。技能代码留在 .claude/skills/claude-loop/ 中，因为在循环运行时它是只读的。

一个填充好的项目看起来像：

your-project/  
├── .claude/  
│   └── skills/claude-loop/   # 技能代码（一次性安装）  
├── claude-loop/               # 运行时状态（首次运行时创建）  
│   ├── prd.json               # 你的任务列表  
│   ├── progress.txt           # 学习日志  
│   ├── .last-branch           # 状态跟踪  
│   └── archive/               # 过去的运行  
├── AGENTS.md                  # 项目级约定  
├── src/  
│   ├── auth/AGENTS.md         # 模块约定  
│   └── ...  

关键原则

小故事。 每个故事必须能放在一个子 Agent 的上下文窗口中。“添加一列和一个迁移”、“添加一个服务器动作”、“添加一个 UI 列表组件”都可行。“构建仪表板”和“重构 API”不行——先拆分它们。如果子 Agent 报告故事太大，编排器会停止；需要先修订 PRD 再重试。

CI 必须保持绿色。 如果检查失败，子 Agent 拒绝提交。编排器在第一个阻塞项处停止，而不是跨迭代累积错误。一次损坏的提交会毒害所有未来的子 Agent。

AGENTS.md 是知识累积的地方。 当子 Agent 发现一个不明显的约定或陷阱（例如，“当修改 X 时，也要更新 Y 以保持同步”），它会将其记录在源树中最接近的 AGENTS.md 中。未来的子 Agent 会自动读取这些。这比将其埋没在 progress.txt 中更持久。

默认顺序；并行需显式请求。 故事在文件上重叠，因此默认是逐个执行——这样无需任何仪式即可保持 git、PRD 和 progress.txt 的一致性。当故事真正独立时（通过 dependsOn 声明），并行波次模式 会在隔离的 git worktree 中并发运行它们并在屏障处合并。并行度受依赖图的限制，而不是由你启动的 Agent 数量决定——一条深层链几乎无法并行化；一个宽 PRD 可以大量并行化。

并行模式（波次）

默认情况下循环是顺序的。如果你的故事独立，你可以并发运行它们：

1. 为 prd.json 中的每个故事添加一个 dependsOn 数组（必须首先完成的 ID）。
2. 使用并行措辞调用——“并行运行循环”、“同步运行故事”、“作为波次运行”或“扇出循环”。

然后编排器：

• 从依赖图中计算波次。 一个波次是所有尚未完成且其依赖均已满足的故事的集合，受并发限制（默认 4）约束。
• 将每个故事隔离在自己的 git worktree 中（claude-loop/.worktrees/），全部从你的功能分支分出——因此并发子 Agent 不会在文件或 git 状态上冲突。
• 并发运行波次，然后命中一个屏障：等待所有波次完成，将每个 worktree 分支逐个合并回功能分支，并在启动下一个波次之前对集成结果重新运行类型检查/测试。
• 拥有共享状态。 在并行模式下，子 Agent 从不写入 prd.json/progress.txt（那样会产生竞态）；它们返回结果，编排器在每个波次后记录一次。

波次 1: AUTH-001  
波次 2: AUTH-002, AUTH-003, AUTH-004  # 一起运行，在屏障处合并  
波次 3: AUTH-005  # 波次 2 合并后解除阻塞  

需要了解的权衡：

• 加速受依赖图的限制。 一个线性的故事链几乎无法并行化；一个包含许多独立故事的 PRD 则能很好地并行化。
• 合并冲突是失败模式。 编排器只自动解决简单的增量冲突；任何语义冲突它会中止并报告，而不是猜测。通过偏好增量模式（每条路由/注册一个新文件，而不是编辑一个共享文件）以及在第一个脚手架故事中安装所有依赖来最小化此问题。
• 需要干净的工作树和 Git ≥ 2.5（用于 git worktree）。
• 随时停止仍然安全。 PRD 仍然是真相来源；恢复时从下一个准备好的波次开始。

对于短 PRD 或几乎每个故事都建立在前一个之上的 PRD，首选顺序模式——协调开销不值得。

技术栈支持

编排器自动检测项目的类型检查和测试命令，并将其嵌入到子 Agent 提示中：

如果你的项目使用自定义构建系统（Bazel、Buck、Makefile、justfile），编排器会读取它能读取的内容，如果不确定会询问你正确的命令。要硬编码它们，编辑 subagent-prompt.md 并将 [TYPECHECK_CMD] / [TEST_CMD] 占位符替换为字面命令。

何时停止

• 所有故事通过 → 归档运行，输出 COMPLETE。
• 子 Agent 阻塞（检查失败、缺少工具、需求模糊、故事太大）→ 编排器停止，总结阻塞项，等待你的指示。
• 你手动停止 Claude → 无状态损坏。下次调用会从下一个 passes: false 的故事继续。PRD 是真相来源；运行可随时恢复。

编排器不会自动重试失败的子 Agent。清晰报告后的干净停止优于累积错误。

自定义

大多数项目无需任何配置。要调整：

• 代码库约定： 在项目根目录添加一个 AGENTS.md，包含全局规则。子 Agent 每次迭代都会读取它。
• 技术栈命令： 如果自动检测不合适，编辑 subagent-prompt.md。
• 子 Agent 契约： 向 subagent-prompt.md 添加项目特定规则（提交消息约定、强制 linter、必需审阅者等）。

Git：提交什么

合理的默认值：

• 提交 .claude/skills/claude-loop/，以便你的团队自动获得该技能。
• 提交 claude-loop/prd.json，以便 PRD 与功能分支一起进行版本控制。
• 提交 claude-loop/progress.txt 和 claude-loop/archive/，如果你想共享学习成果。
• Gitignore claude-loop/.last-branch（本地状态）和 claude-loop/.worktrees/（并行模式创建的临时每故事签出）。或者完全 gitignore claude-loop/ 并将其视为个人工作空间——两种方法都可行。

常见问题

为什么不直接在一个长会话中运行 Claude Code？
随着上下文填满，它会退化。每个故事使用全新的子 Agent，无论你交付了多少故事，每个实现都保持清晰。编排器的上下文也很小——它只持有高级状态，而非实现细节。

我能为了速度并行运行子 Agent 吗？
可以——选择 并行波次模式。它之所以不是默认，是因为故事通常接触重叠的文件，而朴素的并行性会在 git、PRD 和 progress.txt 上产生竞态。并行模式通过 git worktree（隔离）和编排器拥有的合并+验证屏障（协调）消除了这些竞态，并且只运行其 dependsOn 已满足的故事。顺序保持默认，因为它更简单且不需要依赖图。

我的 PRD 有 30 个故事。这样行吗？
可以——故事数量没有上限。每个故事都是独立的。限制在于单个故事的大小，而非总故事数量。

我能在停止后恢复吗？
可以。PRD 是真相来源。下次调用时，编排器会从下一个 passes: false 的故事继续。如果你在运行中途切换了分支，编排器会在开始新运行前将放弃的运行归档到 claude-loop/archive/。

这能直接与 Claude API 一起工作吗？
不能——它需要 Task 工具，这是 Claude Code（以及带有子 Agent 的 Claude.ai）特有的。该技能在这些环境中自动加载。

如果一个故事一直失败会怎样？
编排器在阻塞项处停止并报告；它不会自动重试。通常的修复方法是拆分故事或完善验收标准，然后重新运行。

文件

• SKILL.md — 编排器指令（技能触发时由 Claude 自动读取）
• subagent-prompt.md — 通过 Task 传递给每个子 Agent 的模板（顺序模式）
• parallel-subagent-prompt.md — 用于并行波次模式的 worktree 感知模板
• prd.example.json — 参考 PRD 格式
• README.md — 本文件

许可证