autonomous-loops
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseAutonomous Loops Skill
自主循环技能
Patterns, architectures, and reference implementations for running Claude Code autonomously in loops. Covers everything from simple pipelines to full RFC-driven multi-agent DAG orchestration.
claude -p用于实现Claude Code自主循环运行的模式、架构和参考实现,覆盖从简单的流水线到完整RFC驱动的多Agent DAG编排的全场景方案。
claude -pWhen to Use
适用场景
- Setting up autonomous development workflows that run without human intervention
- Choosing the right loop architecture for your problem (simple vs complex)
- Building CI/CD-style continuous development pipelines
- Running parallel agents with merge coordination
- Implementing context persistence across loop iterations
- Adding quality gates and cleanup passes to autonomous workflows
- 搭建无需人工干预的自主开发工作流
- 为你的业务场景选择合适的循环架构(简单/复杂方案选型)
- 搭建类CI/CD的持续开发流水线
- 运行带合并协调能力的并行Agent
- 实现循环迭代间的上下文持久化
- 为自主工作流添加质量门禁与清理环节
Loop Pattern Spectrum
循环模式图谱
From simplest to most sophisticated:
| Pattern | Complexity | Best For |
|---|---|---|
| Sequential Pipeline | Low | Daily dev steps, scripted workflows |
| NanoClaw REPL | Low | Interactive persistent sessions |
| Infinite Agentic Loop | Medium | Parallel content generation, spec-driven work |
| Continuous Claude PR Loop | Medium | Multi-day iterative projects with CI gates |
| De-Sloppify Pattern | Add-on | Quality cleanup after any Implementer step |
| Ralphinho / RFC-Driven DAG | High | Large features, multi-unit parallel work with merge queue |
从最简单到最复杂的排序如下:
| 模式 | 复杂度 | 最佳适用场景 |
|---|---|---|
| 顺序流水线 | 低 | 日常开发步骤、脚本化工作流 |
| NanoClaw REPL | 低 | 交互式持久会话 |
| 无限Agent循环 | 中 | 并行内容生成、规格驱动的开发工作 |
| 持续Claude PR循环 | 中 | 带CI门禁的多日迭代项目 |
| 去冗余模式 | 附加项 | 任意实现步骤后的质量清理 |
| Ralphinho / RFC驱动DAG编排 | 高 | 大型功能、带合并队列的多单元并行开发工作 |
1. Sequential Pipeline (claude -p
)
claude -p1. 顺序流水线(claude -p
)
claude -pThe simplest loop. Break daily development into a sequence of non-interactive calls. Each call is a focused step with a clear prompt.
claude -p最简单的循环模式。将日常开发拆分为一系列非交互式的调用,每个调用都是一个目标清晰的聚焦步骤。
claude -pCore Insight
核心思路
If you can't figure out a loop like this, it means you can't even drive the LLM to fix your code in interactive mode.
The flag runs Claude Code non-interactively with a prompt, exits when done. Chain calls to build a pipeline:
claude -pbash
#!/bin/bash如果你连这类流水线都搭不出来,说明你甚至没法在交互模式下驱动LLM修复你的代码。
claude -pbash
#!/bin/bashdaily-dev.sh — Sequential pipeline for a feature branch
daily-dev.sh — 功能分支的顺序流水线
set -e
set -e
Step 1: Implement the feature
步骤1:实现功能
claude -p "Read the spec in docs/auth-spec.md. Implement OAuth2 login in src/auth/. Write tests first (TDD). Do NOT create any new documentation files."
claude -p "读取docs/auth-spec.md中的规格说明,在src/auth/路径下实现OAuth2登录功能,遵循TDD优先编写测试,不要创建任何新的文档文件。"
Step 2: De-sloppify (cleanup pass)
步骤2:去冗余(清理环节)
claude -p "Review all files changed by the previous commit. Remove any unnecessary type tests, overly defensive checks, or testing of language features (e.g., testing that TypeScript generics work). Keep real business logic tests. Run the test suite after cleanup."
claude -p "审查上一次提交修改的所有文件,删除不必要的类型测试、过度防御性校验,以及针对语言本身特性的测试(比如测试TypeScript泛型是否生效),保留真实的业务逻辑测试,清理完成后运行测试套件。"
Step 3: Verify
步骤3:验证
claude -p "Run the full build, lint, type check, and test suite. Fix any failures. Do not add new features."
claude -p "运行完整的构建、lint、类型检查和测试套件,修复所有失败项,不要添加新功能。"
Step 4: Commit
步骤4:提交
claude -p "Create a conventional commit for all staged changes. Use 'feat: add OAuth2 login flow' as the message."
undefinedclaude -p "为所有暂存的变更创建符合规范的提交,提交信息使用'feat: add OAuth2 login flow'。"
undefinedKey Design Principles
核心设计原则
- Each step is isolated — A fresh context window per call means no context bleed between steps.
claude -p - Order matters — Steps execute sequentially. Each builds on the filesystem state left by the previous.
- Negative instructions are dangerous — Don't say "don't test type systems." Instead, add a separate cleanup step (see De-Sloppify Pattern).
- Exit codes propagate — stops the pipeline on failure.
set -e
- 每个步骤相互隔离 — 每个调用都使用全新的上下文窗口,避免步骤间的上下文泄露。
claude -p - 顺序至关重要 — 步骤按顺序执行,每个步骤都基于上一步留下的文件系统状态继续执行。
- 否定指令存在风险 — 不要说“不要测试类型系统”这类指令,而是添加单独的清理步骤(参考去冗余模式)。
- 退出码自动传递 — 配置会在任意步骤失败时终止流水线。
set -e
Variations
变体用法
With model routing:
bash
undefined搭配模型路由:
bash
undefinedResearch with Opus (deep reasoning)
用Opus做研究(深度推理)
claude -p --model opus "Analyze the codebase architecture and write a plan for adding caching..."
claude -p --model opus "分析代码库架构,编写添加缓存的方案..."
Implement with Sonnet (fast, capable)
用Sonnet做实现(速度快、能力强)
claude -p "Implement the caching layer according to the plan in docs/caching-plan.md..."
claude -p "根据docs/caching-plan.md中的方案实现缓存层..."
Review with Opus (thorough)
用Opus做审查(全面细致)
claude -p --model opus "Review all changes for security issues, race conditions, and edge cases..."
**With environment context:**
```bashclaude -p --model opus "审查所有变更的安全问题、竞态条件和边界场景..."
**搭配环境上下文:**
```bashPass context via files, not prompt length
通过文件传递上下文,避免提示词过长
echo "Focus areas: auth module, API rate limiting" > .claude-context.md
claude -p "Read .claude-context.md for priorities. Work through them in order."
rm .claude-context.md
**With `--allowedTools` restrictions:**
```bashecho "重点关注:auth模块、API限流" > .claude-context.md
claude -p "读取.claude-context.md中的优先级说明,按顺序完成工作。"
rm .claude-context.md
**搭配`--allowedTools`权限限制:**
```bashRead-only analysis pass
只读分析环节
claude -p --allowedTools "Read,Grep,Glob" "Audit this codebase for security vulnerabilities..."
claude -p --allowedTools "Read,Grep,Glob" "审计代码库的安全漏洞..."
Write-only implementation pass
仅写实现环节
claude -p --allowedTools "Read,Write,Edit,Bash" "Implement the fixes from security-audit.md..."
---claude -p --allowedTools "Read,Write,Edit,Bash" "根据security-audit.md中的说明实现修复..."
---2. NanoClaw REPL
2. NanoClaw REPL
ECC's built-in persistent loop. A session-aware REPL that calls synchronously with full conversation history.
claude -pbash
undefinedECC内置的持久化循环。感知会话的REPL,会同步调用并保留完整的对话历史。
claude -pbash
undefinedStart the default session
启动默认会话
node scripts/claw.js
node scripts/claw.js
Named session with skill context
指定技能上下文的命名会话
CLAW_SESSION=my-project CLAW_SKILLS=tdd-workflow,security-review node scripts/claw.js
undefinedCLAW_SESSION=my-project CLAW_SKILLS=tdd-workflow,security-review node scripts/claw.js
undefinedHow It Works
工作原理
- Loads conversation history from
~/.claude/claw/{session}.md - Each user message is sent to with full history as context
claude -p - Responses are appended to the session file (Markdown-as-database)
- Sessions persist across restarts
- 从加载对话历史
~/.claude/claw/{session}.md - 每条用户消息都会带着完整历史作为上下文发送给
claude -p - 响应内容会追加到会话文件中(Markdown作为数据库)
- 会话在重启后依然保留
When NanoClaw vs Sequential Pipeline
NanoClaw与顺序流水线的选型对比
| Use Case | NanoClaw | Sequential Pipeline |
|---|---|---|
| Interactive exploration | Yes | No |
| Scripted automation | No | Yes |
| Session persistence | Built-in | Manual |
| Context accumulation | Grows per turn | Fresh each step |
| CI/CD integration | Poor | Excellent |
See the command documentation for full details.
/claw| 场景 | NanoClaw | 顺序流水线 |
|---|---|---|
| 交互式探索 | 是 | 否 |
| 脚本化自动化 | 否 | 是 |
| 会话持久化 | 内置 | 手动实现 |
| 上下文积累 | 每轮交互持续增长 | 每个步骤全新上下文 |
| CI/CD集成 | 差 | 极佳 |
完整细节参考命令文档。
/claw3. Infinite Agentic Loop
3. 无限Agent循环
A two-prompt system that orchestrates parallel sub-agents for specification-driven generation. Developed by disler (credit: @disler).
双提示词系统,编排并行子Agent实现规格驱动的生成能力,由disler开发(鸣谢:@disler)。
Architecture: Two-Prompt System
架构:双提示词系统
PROMPT 1 (Orchestrator) PROMPT 2 (Sub-Agents)
┌─────────────────────┐ ┌──────────────────────┐
│ Parse spec file │ │ Receive full context │
│ Scan output dir │ deploys │ Read assigned number │
│ Plan iteration │────────────│ Follow spec exactly │
│ Assign creative dirs │ N agents │ Generate unique output │
│ Manage waves │ │ Save to output dir │
└─────────────────────┘ └──────────────────────┘PROMPT 1 (编排器) PROMPT 2 (子Agent)
┌─────────────────────┐ ┌──────────────────────┐
│ 解析规格文件 │ │ 接收全量上下文 │
│ 扫描输出目录 │ 部署N个 │ 读取分配的编号 │
│ 规划迭代内容 │────────────│ 严格遵循规格执行 │
│ 分配创意方向 │ 子Agent │ 生成唯一输出内容 │
│ 管理批次执行 │ │ 保存到输出目录 │
└─────────────────────┘ └──────────────────────┘The Pattern
模式流程
- Spec Analysis — Orchestrator reads a specification file (Markdown) defining what to generate
- Directory Recon — Scans existing output to find the highest iteration number
- Parallel Deployment — Launches N sub-agents, each with:
- The full spec
- A unique creative direction
- A specific iteration number (no conflicts)
- A snapshot of existing iterations (for uniqueness)
- Wave Management — For infinite mode, deploys waves of 3-5 agents until context is exhausted
- 规格分析 — 编排器读取定义生成目标的规格文件(Markdown格式)
- 目录探查 — 扫描现有输出,找到最大的迭代编号
- 并行部署 — 启动N个子Agent,每个子Agent持有:
- 完整规格
- 唯一的创意方向
- 指定的迭代编号(无冲突)
- 现有迭代的快照(保证唯一性)
- 批次管理 — 无限模式下,每批次部署3-5个Agent,直到上下文耗尽为止
Implementation via Claude Code Commands
通过Claude Code命令实现
Create :
.claude/commands/infinite.mdmarkdown
Parse the following arguments from $ARGUMENTS:
1. spec_file — path to the specification markdown
2. output_dir — where iterations are saved
3. count — integer 1-N or "infinite"
PHASE 1: Read and deeply understand the specification.
PHASE 2: List output_dir, find highest iteration number. Start at N+1.
PHASE 3: Plan creative directions — each agent gets a DIFFERENT theme/approach.
PHASE 4: Deploy sub-agents in parallel (Task tool). Each receives:
- Full spec text
- Current directory snapshot
- Their assigned iteration number
- Their unique creative direction
PHASE 5 (infinite mode): Loop in waves of 3-5 until context is low.Invoke:
bash
/project:infinite specs/component-spec.md src/ 5
/project:infinite specs/component-spec.md src/ infinite创建:
.claude/commands/infinite.mdmarkdown
从$ARGUMENTS中解析以下参数:
1. spec_file — 规格Markdown文件路径
2. output_dir — 迭代结果保存路径
3. count — 1-N的整数或"infinite"
PHASE 1: 读取并深入理解规格说明。
PHASE 2: 列出output_dir内容,找到最高迭代编号,从N+1开始执行。
PHASE 3: 规划创意方向 — 每个Agent获得**不同**的主题/实现思路。
PHASE 4: 并行部署子Agent(使用Task工具),每个Agent接收:
- 完整规格文本
- 当前目录快照
- 分配的迭代编号
- 唯一的创意方向
PHASE 5 (infinite模式): 每批次3-5个循环执行,直到上下文不足为止。调用方式:
bash
/project:infinite specs/component-spec.md src/ 5
/project:infinite specs/component-spec.md src/ infiniteBatching Strategy
分批策略
| Count | Strategy |
|---|---|
| 1-5 | All agents simultaneously |
| 6-20 | Batches of 5 |
| infinite | Waves of 3-5, progressive sophistication |
| 数量 | 策略 |
|---|---|
| 1-5 | 所有Agent同时运行 |
| 6-20 | 每批5个分批运行 |
| infinite | 每批3-5个,逐步提升复杂度 |
Key Insight: Uniqueness via Assignment
核心思路:通过分配保证唯一性
Don't rely on agents to self-differentiate. The orchestrator assigns each agent a specific creative direction and iteration number. This prevents duplicate concepts across parallel agents.
不要依赖Agent自行区分差异,编排器主动分配每个Agent特定的创意方向和迭代编号,避免并行Agent生成重复的内容。
4. Continuous Claude PR Loop
4. 持续Claude PR循环
A production-grade shell script that runs Claude Code in a continuous loop, creating PRs, waiting for CI, and merging automatically. Created by AnandChowdhary (credit: @AnandChowdhary).
生产级Shell脚本,持续循环运行Claude Code,自动创建PR、等待CI完成、自动合并,由AnandChowdhary开发(鸣谢:@AnandChowdhary)。
Core Loop
核心循环
┌─────────────────────────────────────────────────────┐
│ CONTINUOUS CLAUDE ITERATION │
│ │
│ 1. Create branch (continuous-claude/iteration-N) │
│ 2. Run claude -p with enhanced prompt │
│ 3. (Optional) Reviewer pass — separate claude -p │
│ 4. Commit changes (claude generates message) │
│ 5. Push + create PR (gh pr create) │
│ 6. Wait for CI checks (poll gh pr checks) │
│ 7. CI failure? → Auto-fix pass (claude -p) │
│ 8. Merge PR (squash/merge/rebase) │
│ 9. Return to main → repeat │
│ │
│ Limit by: --max-runs N | --max-cost $X │
│ --max-duration 2h | completion signal │
└─────────────────────────────────────────────────────┘┌─────────────────────────────────────────────────────┐
│ 持续Claude迭代流程 │
│ │
│ 1. 创建分支 (continuous-claude/iteration-N) │
│ 2. 用增强提示词运行claude -p │
│ 3. (可选)审查环节 — 单独运行claude -p │
│ 4. 提交变更(Claude生成提交信息) │
│ 5. 推送并创建PR(gh pr create) │
│ 6. 等待CI检查完成(轮询gh pr checks) │
│ 7. CI失败?→ 自动修复环节(claude -p) │
│ 8. 合并PR(squash/merge/rebase) │
│ 9. 切回main分支 → 重复流程 │
│ │
│ 限制条件: --max-runs N | --max-cost $X │
│ --max-duration 2h | 完成信号 │
└─────────────────────────────────────────────────────┘Installation
安装
bash
curl -fsSL https://raw.githubusercontent.com/AnandChowdhary/continuous-claude/HEAD/install.sh | bashbash
curl -fsSL https://raw.githubusercontent.com/AnandChowdhary/continuous-claude/HEAD/install.sh | bashUsage
使用方法
bash
undefinedbash
undefinedBasic: 10 iterations
基础用法:10次迭代
continuous-claude --prompt "Add unit tests for all untested functions" --max-runs 10
continuous-claude --prompt "为所有未测试的函数添加单元测试" --max-runs 10
Cost-limited
成本限制
continuous-claude --prompt "Fix all linter errors" --max-cost 5.00
continuous-claude --prompt "修复所有linter错误" --max-cost 5.00
Time-boxed
时间限制
continuous-claude --prompt "Improve test coverage" --max-duration 8h
continuous-claude --prompt "提升测试覆盖率" --max-duration 8h
With code review pass
带代码审查环节
continuous-claude
--prompt "Add authentication feature"
--max-runs 10
--review-prompt "Run npm test && npm run lint, fix any failures"
--prompt "Add authentication feature"
--max-runs 10
--review-prompt "Run npm test && npm run lint, fix any failures"
continuous-claude
--prompt "添加认证功能"
--max-runs 10
--review-prompt "运行npm test && npm run lint,修复所有失败项"
--prompt "添加认证功能"
--max-runs 10
--review-prompt "运行npm test && npm run lint,修复所有失败项"
Parallel via worktrees
通过worktree并行执行
continuous-claude --prompt "Add tests" --max-runs 5 --worktree tests-worker &
continuous-claude --prompt "Refactor code" --max-runs 5 --worktree refactor-worker &
wait
undefinedcontinuous-claude --prompt "添加测试" --max-runs 5 --worktree tests-worker &
continuous-claude --prompt "重构代码" --max-runs 5 --worktree refactor-worker &
wait
undefinedCross-Iteration Context: SHARED_TASK_NOTES.md
跨迭代上下文:SHARED_TASK_NOTES.md
The critical innovation: a file persists across iterations:
SHARED_TASK_NOTES.mdmarkdown
undefined核心创新点:文件在迭代间持久化:
SHARED_TASK_NOTES.mdmarkdown
undefinedProgress
进度
- Added tests for auth module (iteration 1)
- Fixed edge case in token refresh (iteration 2)
- Still need: rate limiting tests, error boundary tests
- 为auth模块添加测试(迭代1)
- 修复token刷新的边界问题(迭代2)
- 待完成:限流测试、错误边界测试
Next Steps
下一步
- Focus on rate limiting module next
- The mock setup in tests/helpers.ts can be reused
Claude reads this file at iteration start and updates it at iteration end. This bridges the context gap between independent `claude -p` invocations.- 接下来重点关注限流模块
- 可以复用tests/helpers.ts中的模拟配置
Claude在迭代开始时读取该文件,迭代结束时更新该文件,打通了独立`claude -p`调用之间的上下文鸿沟。CI Failure Recovery
CI失败恢复
When PR checks fail, Continuous Claude automatically:
- Fetches the failed run ID via
gh run list - Spawns a new with CI fix context
claude -p - Claude inspects logs via , fixes code, commits, pushes
gh run view - Re-waits for checks (up to attempts)
--ci-retry-max
当PR检查失败时,持续Claude会自动执行以下操作:
- 通过获取失败的运行ID
gh run list - 启动新的传入CI修复上下文
claude -p - Claude通过查看日志,修复代码、提交、推送
gh run view - 重新等待检查完成(最多重试次)
--ci-retry-max
Completion Signal
完成信号
Claude can signal "I'm done" by outputting a magic phrase:
bash
continuous-claude \
--prompt "Fix all bugs in the issue tracker" \
--completion-signal "CONTINUOUS_CLAUDE_PROJECT_COMPLETE" \
--completion-threshold 3 # Stops after 3 consecutive signalsThree consecutive iterations signaling completion stops the loop, preventing wasted runs on finished work.
Claude可以通过输出指定魔法短语来发送“我已完成”的信号:
bash
continuous-claude \
--prompt "修复issue追踪器中的所有bug" \
--completion-signal "CONTINUOUS_CLAUDE_PROJECT_COMPLETE" \
--completion-threshold 3 # 连续收到3次信号后停止连续三次迭代发送完成信号后会停止循环,避免在已完成的工作上浪费资源。
Key Configuration
核心配置
| Flag | Purpose |
|---|---|
| Stop after N successful iterations |
| Stop after spending $X |
| Stop after time elapsed |
| squash, merge, or rebase |
| Parallel execution via git worktrees |
| Dry-run mode (no git operations) |
| Add reviewer pass per iteration |
| Auto-fix CI failures (default: 1) |
| Flag | 用途 |
|---|---|
| 成功执行N次迭代后停止 |
| 消费满$X后停止 |
| 运行指定时长后停止 |
| 合并策略:squash、merge或rebase |
| 通过git worktree实现并行执行 |
| 试运行模式(不执行git操作) |
| 每个迭代添加审查环节 |
| CI失败自动修复次数(默认:1) |
5. The De-Sloppify Pattern
5. 去冗余模式
An add-on pattern for any loop. Add a dedicated cleanup/refactor step after each Implementer step.
所有循环的附加模式。在每个实现步骤后添加专门的清理/重构环节。
The Problem
存在的问题
When you ask an LLM to implement with TDD, it takes "write tests" too literally:
- Tests that verify TypeScript's type system works (testing )
typeof x === 'string' - Overly defensive runtime checks for things the type system already guarantees
- Tests for framework behavior rather than business logic
- Excessive error handling that obscures the actual code
当你要求LLM用TDD实现功能时,它会过度字面化理解“编写测试”的要求:
- 测试TypeScript类型系统本身是否生效(测试这类逻辑)
typeof x === 'string' - 为类型系统已经保证的内容添加过度防御性的运行时校验
- 测试框架本身的行为而非业务逻辑
- 过度的错误处理遮蔽了真实代码逻辑
Why Not Negative Instructions?
为什么不用否定指令?
Adding "don't test type systems" or "don't add unnecessary checks" to the Implementer prompt has downstream effects:
- The model becomes hesitant about ALL testing
- It skips legitimate edge case tests
- Quality degrades unpredictably
在实现提示词中添加“不要测试类型系统”或者“不要添加不必要的校验”会带来负面效果:
- 模型会对所有测试产生犹豫
- 会跳过合法的边界场景测试
- 质量会出现不可预测的下降
The Solution: Separate Pass
解决方案:单独的清理环节
Instead of constraining the Implementer, let it be thorough. Then add a focused cleanup agent:
bash
undefined不要约束实现环节的Agent,让它尽可能输出全面的内容,然后添加专门的清理Agent:
bash
undefinedStep 1: Implement (let it be thorough)
步骤1:实现(让它尽可能全面输出)
claude -p "Implement the feature with full TDD. Be thorough with tests."
claude -p "用完整TDD流程实现功能,测试覆盖要全面。"
Step 2: De-sloppify (separate context, focused cleanup)
步骤2:去冗余(独立上下文,聚焦清理)
claude -p "Review all changes in the working tree. Remove:
- Tests that verify language/framework behavior rather than business logic
- Redundant type checks that the type system already enforces
- Over-defensive error handling for impossible states
- Console.log statements
- Commented-out code
Keep all business logic tests. Run the test suite after cleanup to ensure nothing breaks."
undefinedclaude -p "审查工作区的所有变更,删除以下内容:
- 验证语言/框架本身行为而非业务逻辑的测试
- 类型系统已经保证的冗余类型校验
- 针对不可能状态的过度防御性错误处理
- Console.log语句
- 注释掉的代码
保留所有业务逻辑测试,清理完成后运行测试套件确保没有功能损坏。"
undefinedIn a Loop Context
在循环场景中使用
bash
for feature in "${features[@]}"; do
# Implement
claude -p "Implement $feature with TDD."
# De-sloppify
claude -p "Cleanup pass: review changes, remove test/code slop, run tests."
# Verify
claude -p "Run build + lint + tests. Fix any failures."
# Commit
claude -p "Commit with message: feat: add $feature"
donebash
for feature in "${features[@]}"; do
# 实现
claude -p "用TDD实现$feature。"
# 去冗余
claude -p "清理环节:审查变更,删除测试/代码冗余,运行测试。"
# 验证
claude -p "运行构建 + lint + 测试,修复所有失败项。"
# 提交
claude -p "提交信息:feat: add $feature"
doneKey Insight
核心思路
Rather than adding negative instructions which have downstream quality effects, add a separate de-sloppify pass. Two focused agents outperform one constrained agent.
不要添加会带来后续质量问题的否定指令,而是添加单独的去冗余环节。两个聚焦的Agent表现优于一个被约束的Agent。
6. Ralphinho / RFC-Driven DAG Orchestration
6. Ralphinho / RFC驱动DAG编排
The most sophisticated pattern. An RFC-driven, multi-agent pipeline that decomposes a spec into a dependency DAG, runs each unit through a tiered quality pipeline, and lands them via an agent-driven merge queue. Created by enitrat (credit: @enitrat).
最复杂的模式。RFC驱动的多Agent流水线,将规格拆解为依赖DAG,每个工作单元经过分层质量流水线,通过Agent驱动的合并队列落地,由enitrat开发(鸣谢:@enitrat)。
Architecture Overview
架构概览
RFC/PRD Document
│
▼
DECOMPOSITION (AI)
Break RFC into work units with dependency DAG
│
▼
┌──────────────────────────────────────────────────────┐
│ RALPH LOOP (up to 3 passes) │
│ │
│ For each DAG layer (sequential, by dependency): │
│ │
│ ┌── Quality Pipelines (parallel per unit) ───────┐ │
│ │ Each unit in its own worktree: │ │
│ │ Research → Plan → Implement → Test → Review │ │
│ │ (depth varies by complexity tier) │ │
│ └────────────────────────────────────────────────┘ │
│ │
│ ┌── Merge Queue ─────────────────────────────────┐ │
│ │ Rebase onto main → Run tests → Land or evict │ │
│ │ Evicted units re-enter with conflict context │ │
│ └────────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────┘RFC/PRD 文档
│
▼
拆解环节(AI)
将RFC拆分为带依赖DAG的工作单元
│
▼
┌──────────────────────────────────────────────────────┐
│ RALPH循环(最多3次) │
│ │
│ 按依赖顺序逐层处理DAG: │
│ │
│ ┌── 质量流水线(每个单元并行执行) ─────────────────┐ │
│ │ 每个单元运行在独立的worktree中: │ │
│ │ 研究 → 规划 → 实现 → 测试 → 审查 │ │
│ │ (深度随复杂度等级调整) │ │
│ └────────────────────────────────────────────────┘ │
│ │
│ ┌── 合并队列 ─────────────────────────────────────┐ │
│ │ 变基到main → 运行测试 → 落地或驱逐 │ │
│ │ 被驱逐的单元携带冲突上下文重新进入流程 │ │
│ └────────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────┘RFC Decomposition
RFC拆解
AI reads the RFC and produces work units:
typescript
interface WorkUnit {
id: string; // kebab-case identifier
name: string; // Human-readable name
rfcSections: string[]; // Which RFC sections this addresses
description: string; // Detailed description
deps: string[]; // Dependencies (other unit IDs)
acceptance: string[]; // Concrete acceptance criteria
tier: "trivial" | "small" | "medium" | "large";
}Decomposition Rules:
- Prefer fewer, cohesive units (minimize merge risk)
- Minimize cross-unit file overlap (avoid conflicts)
- Keep tests WITH implementation (never separate "implement X" + "test X")
- Dependencies only where real code dependency exists
The dependency DAG determines execution order:
Layer 0: [unit-a, unit-b] ← no deps, run in parallel
Layer 1: [unit-c] ← depends on unit-a
Layer 2: [unit-d, unit-e] ← depend on unit-cAI读取RFC并生成工作单元:
typescript
interface WorkUnit {
id: string; // kebab-case格式的标识符
name: string; // 人类可读的名称
rfcSections: string[]; // 对应RFC的章节
description: string; // 详细描述
deps: string[]; // 依赖的其他单元ID
acceptance: string[]; // 具体的验收标准
tier: "trivial" | "small" | "medium" | "large";
}拆解规则:
- 优先更少的内聚单元(最小化合并风险)
- 最小化跨单元的文件重叠(避免冲突)
- 测试与实现放在一起(不要拆分“实现X”和“测试X”)
- 仅当存在真实代码依赖时才添加依赖关系
依赖DAG决定执行顺序:
Layer 0: [unit-a, unit-b] ← 无依赖,并行运行
Layer 1: [unit-c] ← 依赖unit-a
Layer 2: [unit-d, unit-e] ← 依赖unit-cComplexity Tiers
复杂度等级
Different tiers get different pipeline depths:
| Tier | Pipeline Stages |
|---|---|
| trivial | implement → test |
| small | implement → test → code-review |
| medium | research → plan → implement → test → PRD-review + code-review → review-fix |
| large | research → plan → implement → test → PRD-review + code-review → review-fix → final-review |
This prevents expensive operations on simple changes while ensuring architectural changes get thorough scrutiny.
不同等级对应不同的流水线深度:
| 等级 | 流水线阶段 |
|---|---|
| trivial | 实现 → 测试 |
| small | 实现 → 测试 → 代码审查 |
| medium | 研究 → 规划 → 实现 → 测试 → PRD审查 + 代码审查 → 审查修复 |
| large | 研究 → 规划 → 实现 → 测试 → PRD审查 + 代码审查 → 审查修复 → 最终审查 |
这种设计避免在简单变更上浪费资源,同时保证架构变更得到充分的审核。
Separate Context Windows (Author-Bias Elimination)
独立上下文窗口(消除作者偏见)
Each stage runs in its own agent process with its own context window:
| Stage | Model | Purpose |
|---|---|---|
| Research | Sonnet | Read codebase + RFC, produce context doc |
| Plan | Opus | Design implementation steps |
| Implement | Codex | Write code following the plan |
| Test | Sonnet | Run build + test suite |
| PRD Review | Sonnet | Spec compliance check |
| Code Review | Opus | Quality + security check |
| Review Fix | Codex | Address review issues |
| Final Review | Opus | Quality gate (large tier only) |
Critical design: The reviewer never wrote the code it reviews. This eliminates author bias — the most common source of missed issues in self-review.
每个阶段在独立的Agent进程中运行,使用独立的上下文窗口:
| 阶段 | 模型 | 用途 |
|---|---|---|
| 研究 | Sonnet | 读取代码库+RFC,生成上下文文档 |
| 规划 | Opus | 设计实现步骤 |
| 实现 | Codex | 按照规划编写代码 |
| 测试 | Sonnet | 运行构建+测试套件 |
| PRD审查 | Sonnet | 规格符合性检查 |
| 代码审查 | Opus | 质量+安全检查 |
| 审查修复 | Codex | 解决审查提出的问题 |
| 最终审查 | Opus | 质量门禁(仅大型等级需要) |
关键设计: 审查者永远不会审查自己写的代码,消除了作者偏见——这是自审查中遗漏问题的最常见原因。
Merge Queue with Eviction
带驱逐机制的合并队列
After quality pipelines complete, units enter the merge queue:
Unit branch
│
├─ Rebase onto main
│ └─ Conflict? → EVICT (capture conflict context)
│
├─ Run build + tests
│ └─ Fail? → EVICT (capture test output)
│
└─ Pass → Fast-forward main, push, delete branchFile Overlap Intelligence:
- Non-overlapping units land speculatively in parallel
- Overlapping units land one-by-one, rebasing each time
Eviction Recovery:
When evicted, full context is captured (conflicting files, diffs, test output) and fed back to the implementer on the next Ralph pass:
markdown
undefined质量流水线完成后,工作单元进入合并队列:
单元分支
│
├─ 变基到main
│ └─ 冲突?→ 驱逐(捕获冲突上下文)
│
├─ 运行构建+测试
│ └─ 失败?→ 驱逐(捕获测试输出)
│
└─ 通过 → 快进main分支,推送,删除分支文件重叠智能处理:
- 无文件重叠的单元并行 speculative 落地
- 有重叠的单元逐个落地,每次都重新变基
驱逐恢复:
被驱逐时,会捕获完整上下文(冲突文件、diff、测试输出),并在下一次Ralph循环中反馈给实现者:
markdown
undefinedMERGE CONFLICT — RESOLVE BEFORE NEXT LANDING
合并冲突 — 下次落地前解决
Your previous implementation conflicted with another unit that landed first.
Restructure your changes to avoid the conflicting files/lines below.
{full eviction context with diffs}
undefined你之前的实现与另一个先落地的单元产生冲突,请调整你的变更以避免下方的冲突文件/行。
{full eviction context with diffs}
undefinedData Flow Between Stages
阶段间数据流
research.contextFilePath ──────────────────→ plan
plan.implementationSteps ──────────────────→ implement
implement.{filesCreated, whatWasDone} ─────→ test, reviews
test.failingSummary ───────────────────────→ reviews, implement (next pass)
reviews.{feedback, issues} ────────────────→ review-fix → implement (next pass)
final-review.reasoning ────────────────────→ implement (next pass)
evictionContext ───────────────────────────→ implement (after merge conflict)research.contextFilePath ──────────────────→ plan
plan.implementationSteps ──────────────────→ implement
implement.{filesCreated, whatWasDone} ─────→ test, reviews
test.failingSummary ───────────────────────→ reviews, implement (next pass)
reviews.{feedback, issues} ────────────────→ review-fix → implement (next pass)
final-review.reasoning ────────────────────→ implement (next pass)
evictionContext ───────────────────────────→ implement (after merge conflict)Worktree Isolation
Worktree隔离
Every unit runs in an isolated worktree (uses jj/Jujutsu, not git):
/tmp/workflow-wt-{unit-id}/Pipeline stages for the same unit share a worktree, preserving state (context files, plan files, code changes) across research → plan → implement → test → review.
每个单元运行在独立的worktree中(使用jj/Jujutsu而非git):
/tmp/workflow-wt-{unit-id}/Pipeline stages for the same unit share a worktree, preserving state (context files, plan files, code changes) across research → plan → implement → test → review.
Key Design Principles
核心设计原则
- Deterministic execution — Upfront decomposition locks in parallelism and ordering
- Human review at leverage points — The work plan is the single highest-leverage intervention point
- Separate concerns — Each stage in a separate context window with a separate agent
- Conflict recovery with context — Full eviction context enables intelligent re-runs, not blind retries
- Tier-driven depth — Trivial changes skip research/review; large changes get maximum scrutiny
- Resumable workflows — Full state persisted to SQLite; resume from any point
- 确定性执行 — 前置拆解锁定并行度和执行顺序
- 高杠杆点人工审核 — 工作规划是最高杠杆的干预点
- 关注点分离 — 每个阶段在独立的上下文窗口中由独立的Agent执行
- 带上下文的冲突恢复 — 完整的驱逐上下文支持智能重跑,而非盲目的重试
- 等级驱动的深度 — 简单变更跳过研究/审查环节,大型变更获得最高级别的审核
- 可恢复工作流 — 完整状态持久化到SQLite,可从任意点恢复
When to Use Ralphinho vs Simpler Patterns
Ralphinho与简单模式的选型对比
| Signal | Use Ralphinho | Use Simpler Pattern |
|---|---|---|
| Multiple interdependent work units | Yes | No |
| Need parallel implementation | Yes | No |
| Merge conflicts likely | Yes | No (sequential is fine) |
| Single-file change | No | Yes (sequential pipeline) |
| Multi-day project | Yes | Maybe (continuous-claude) |
| Spec/RFC already written | Yes | Maybe |
| Quick iteration on one thing | No | Yes (NanoClaw or pipeline) |
| 信号 | 使用Ralphinho | 使用简单模式 |
|---|---|---|
| 多个相互依赖的工作单元 | 是 | 否 |
| 需要并行实现 | 是 | 否 |
| 合并冲突可能性高 | 是 | 否(顺序执行即可) |
| 单文件变更 | 否 | 是(顺序流水线) |
| 多日项目 | 是 | 可选(continuous-claude) |
| 已编写好规格/RFC | 是 | 可选 |
| 单功能快速迭代 | 否 | 是(NanoClaw或流水线) |
Choosing the Right Pattern
选择合适的模式
Decision Matrix
决策矩阵
Is the task a single focused change?
├─ Yes → Sequential Pipeline or NanoClaw
└─ No → Is there a written spec/RFC?
├─ Yes → Do you need parallel implementation?
│ ├─ Yes → Ralphinho (DAG orchestration)
│ └─ No → Continuous Claude (iterative PR loop)
└─ No → Do you need many variations of the same thing?
├─ Yes → Infinite Agentic Loop (spec-driven generation)
└─ No → Sequential Pipeline with de-sloppify任务是单个聚焦的变更吗?
├─ 是 → 顺序流水线或NanoClaw
└─ 否 → 有书面的规格/RFC吗?
├─ 是 → 需要并行实现吗?
│ ├─ 是 → Ralphinho(DAG编排)
│ └─ 否 → 持续Claude(迭代PR循环)
└─ 否 → 需要生成同一事物的多个变体吗?
├─ 是 → 无限Agent循环(规格驱动生成)
└─ 否 → 带去冗余的顺序流水线Combining Patterns
模式组合
These patterns compose well:
-
Sequential Pipeline + De-Sloppify — The most common combination. Every implement step gets a cleanup pass.
-
Continuous Claude + De-Sloppify — Addwith a de-sloppify directive to each iteration.
--review-prompt -
Any loop + Verification — Use ECC'scommand or
/verifyskill as a gate before commits.verification-loop -
Ralphinho's tiered approach in simpler loops — Even in a sequential pipeline, you can route simple tasks to Haiku and complex tasks to Opus:bash
# Simple formatting fix claude -p --model haiku "Fix the import ordering in src/utils.ts" # Complex architectural change claude -p --model opus "Refactor the auth module to use the strategy pattern"
这些模式可以很好地组合使用:
-
顺序流水线 + 去冗余 — 最常见的组合。每个实现步骤都搭配清理环节。
-
持续Claude + 去冗余 — 添加带去冗余指令到每个迭代。
--review-prompt -
任意循环 + 验证 — 使用ECC的命令或
/verify技能作为提交前的门禁。verification-loop -
简单循环中使用Ralphinho的等级化思路 — 即使在顺序流水线中,你也可以将简单任务路由到Haiku,复杂任务路由到Opus:bash
# 简单的格式修复 claude -p --model haiku "Fix the import ordering in src/utils.ts" # 复杂的架构变更 claude -p --model opus "Refactor the auth module to use the strategy pattern"
Anti-Patterns
反模式
Common Mistakes
常见错误
-
Infinite loops without exit conditions — Always have a max-runs, max-cost, max-duration, or completion signal.
-
No context bridge between iterations — Eachcall starts fresh. Use
claude -por filesystem state to bridge context.SHARED_TASK_NOTES.md -
Retrying the same failure — If an iteration fails, don't just retry. Capture the error context and feed it to the next attempt.
-
Negative instructions instead of cleanup passes — Don't say "don't do X." Add a separate pass that removes X.
-
All agents in one context window — For complex workflows, separate concerns into different agent processes. The reviewer should never be the author.
-
Ignoring file overlap in parallel work — If two parallel agents might edit the same file, you need a merge strategy (sequential landing, rebase, or conflict resolution).
-
无退出条件的无限循环 — 始终设置max-runs、max-cost、max-duration或完成信号。
-
迭代间无上下文桥接 — 每个调用都是全新上下文,使用
claude -p或文件系统状态打通上下文。SHARED_TASK_NOTES.md -
相同失败重复重试 — 如果迭代失败,不要直接重试,捕获错误上下文并反馈给下一次尝试。
-
用否定指令替代清理环节 — 不要说“不要做X”,添加单独的环节删除X。
-
所有Agent共享同一个上下文窗口 — 复杂工作流要将关注点拆分到不同的Agent进程,审查者永远不要是作者。
-
并行工作中忽略文件重叠 — 如果两个并行Agent可能编辑同一个文件,你需要合并策略(顺序落地、变基或冲突解决)。
References
参考
| Project | Author | Link |
|---|---|---|
| Ralphinho | enitrat | credit: @enitrat |
| Infinite Agentic Loop | disler | credit: @disler |
| Continuous Claude | AnandChowdhary | credit: @AnandChowdhary |
| NanoClaw | ECC | |
| Verification Loop | ECC | |
| 项目 | 作者 | 链接 |
|---|---|---|
| Ralphinho | enitrat | credit: @enitrat |
| Infinite Agentic Loop | disler | credit: @disler |
| Continuous Claude | AnandChowdhary | credit: @AnandChowdhary |
| NanoClaw | ECC | |
| Verification Loop | ECC | |