autonomous-loops

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Autonomous Loops Skill

自主循环技能

Patterns, architectures, and reference implementations for running Claude Code autonomously in loops. Covers everything from simple
claude -p
pipelines to full RFC-driven multi-agent DAG orchestration.
用于实现Claude Code自主循环运行的模式、架构和参考实现,覆盖从简单的
claude -p
流水线到完整RFC驱动的多Agent DAG编排的全场景方案。

When 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:
PatternComplexityBest For
Sequential PipelineLowDaily dev steps, scripted workflows
NanoClaw REPLLowInteractive persistent sessions
Infinite Agentic LoopMediumParallel content generation, spec-driven work
Continuous Claude PR LoopMediumMulti-day iterative projects with CI gates
De-Sloppify PatternAdd-onQuality cleanup after any Implementer step
Ralphinho / RFC-Driven DAGHighLarge features, multi-unit parallel work with merge queue

从最简单到最复杂的排序如下:
模式复杂度最佳适用场景
顺序流水线日常开发步骤、脚本化工作流
NanoClaw REPL交互式持久会话
无限Agent循环并行内容生成、规格驱动的开发工作
持续Claude PR循环带CI门禁的多日迭代项目
去冗余模式附加项任意实现步骤后的质量清理
Ralphinho / RFC驱动DAG编排大型功能、带合并队列的多单元并行开发工作

1. Sequential Pipeline (
claude -p
)

1. 顺序流水线(
claude -p

The simplest loop. Break daily development into a sequence of non-interactive
claude -p
calls. Each call is a focused step with a clear prompt.
最简单的循环模式。将日常开发拆分为一系列非交互式的
claude -p
调用,每个调用都是一个目标清晰的聚焦步骤。

Core 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
claude -p
flag runs Claude Code non-interactively with a prompt, exits when done. Chain calls to build a pipeline:
bash
#!/bin/bash
如果你连这类流水线都搭不出来,说明你甚至没法在交互模式下驱动LLM修复你的代码。
claude -p
参数可以让Claude Code基于指定提示词非交互式运行,完成后自动退出。你可以串联多个调用搭建流水线:
bash
#!/bin/bash

daily-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."
undefined
claude -p "为所有暂存的变更创建符合规范的提交,提交信息使用'feat: add OAuth2 login flow'。"
undefined

Key Design Principles

核心设计原则

  1. Each step is isolated — A fresh context window per
    claude -p
    call means no context bleed between steps.
  2. Order matters — Steps execute sequentially. Each builds on the filesystem state left by the previous.
  3. Negative instructions are dangerous — Don't say "don't test type systems." Instead, add a separate cleanup step (see De-Sloppify Pattern).
  4. Exit codes propagate
    set -e
    stops the pipeline on failure.
  1. 每个步骤相互隔离 — 每个
    claude -p
    调用都使用全新的上下文窗口,避免步骤间的上下文泄露。
  2. 顺序至关重要 — 步骤按顺序执行,每个步骤都基于上一步留下的文件系统状态继续执行。
  3. 否定指令存在风险 — 不要说“不要测试类型系统”这类指令,而是添加单独的清理步骤(参考去冗余模式)。
  4. 退出码自动传递
    set -e
    配置会在任意步骤失败时终止流水线。

Variations

变体用法

With model routing:
bash
undefined
搭配模型路由:
bash
undefined

Research 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:**
```bash
claude -p --model opus "审查所有变更的安全问题、竞态条件和边界场景..."

**搭配环境上下文:**
```bash

Pass 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:**
```bash
echo "重点关注:auth模块、API限流" > .claude-context.md claude -p "读取.claude-context.md中的优先级说明,按顺序完成工作。" rm .claude-context.md

**搭配`--allowedTools`权限限制:**
```bash

Read-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
claude -p
synchronously with full conversation history.
bash
undefined
ECC内置的持久化循环。感知会话的REPL,会同步调用
claude -p
并保留完整的对话历史。
bash
undefined

Start 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
undefined
CLAW_SESSION=my-project CLAW_SKILLS=tdd-workflow,security-review node scripts/claw.js
undefined

How It Works

工作原理

  1. Loads conversation history from
    ~/.claude/claw/{session}.md
  2. Each user message is sent to
    claude -p
    with full history as context
  3. Responses are appended to the session file (Markdown-as-database)
  4. Sessions persist across restarts
  1. ~/.claude/claw/{session}.md
    加载对话历史
  2. 每条用户消息都会带着完整历史作为上下文发送给
    claude -p
  3. 响应内容会追加到会话文件中(Markdown作为数据库)
  4. 会话在重启后依然保留

When NanoClaw vs Sequential Pipeline

NanoClaw与顺序流水线的选型对比

Use CaseNanoClawSequential Pipeline
Interactive explorationYesNo
Scripted automationNoYes
Session persistenceBuilt-inManual
Context accumulationGrows per turnFresh each step
CI/CD integrationPoorExcellent
See the
/claw
command documentation for full details.

场景NanoClaw顺序流水线
交互式探索
脚本化自动化
会话持久化内置手动实现
上下文积累每轮交互持续增长每个步骤全新上下文
CI/CD集成极佳
完整细节参考
/claw
命令文档。

3. 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

模式流程

  1. Spec Analysis — Orchestrator reads a specification file (Markdown) defining what to generate
  2. Directory Recon — Scans existing output to find the highest iteration number
  3. 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)
  4. Wave Management — For infinite mode, deploys waves of 3-5 agents until context is exhausted
  1. 规格分析 — 编排器读取定义生成目标的规格文件(Markdown格式)
  2. 目录探查 — 扫描现有输出,找到最大的迭代编号
  3. 并行部署 — 启动N个子Agent,每个子Agent持有:
    • 完整规格
    • 唯一的创意方向
    • 指定的迭代编号(无冲突)
    • 现有迭代的快照(保证唯一性)
  4. 批次管理 — 无限模式下,每批次部署3-5个Agent,直到上下文耗尽为止

Implementation via Claude Code Commands

通过Claude Code命令实现

Create
.claude/commands/infinite.md
:
markdown
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.md
markdown
从$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/ infinite

Batching Strategy

分批策略

CountStrategy
1-5All agents simultaneously
6-20Batches of 5
infiniteWaves 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 | bash
bash
curl -fsSL https://raw.githubusercontent.com/AnandChowdhary/continuous-claude/HEAD/install.sh | bash

Usage

使用方法

bash
undefined
bash
undefined

Basic: 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"
continuous-claude
--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
undefined
continuous-claude --prompt "添加测试" --max-runs 5 --worktree tests-worker & continuous-claude --prompt "重构代码" --max-runs 5 --worktree refactor-worker & wait
undefined

Cross-Iteration Context: SHARED_TASK_NOTES.md

跨迭代上下文:SHARED_TASK_NOTES.md

The critical innovation: a
SHARED_TASK_NOTES.md
file persists across iterations:
markdown
undefined
核心创新点:
SHARED_TASK_NOTES.md
文件在迭代间持久化:
markdown
undefined

Progress

进度

  • 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:
  1. Fetches the failed run ID via
    gh run list
  2. Spawns a new
    claude -p
    with CI fix context
  3. Claude inspects logs via
    gh run view
    , fixes code, commits, pushes
  4. Re-waits for checks (up to
    --ci-retry-max
    attempts)
当PR检查失败时,持续Claude会自动执行以下操作:
  1. 通过
    gh run list
    获取失败的运行ID
  2. 启动新的
    claude -p
    传入CI修复上下文
  3. Claude通过
    gh run view
    查看日志,修复代码、提交、推送
  4. 重新等待检查完成(最多重试
    --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 signals
Three 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

核心配置

FlagPurpose
--max-runs N
Stop after N successful iterations
--max-cost $X
Stop after spending $X
--max-duration 2h
Stop after time elapsed
--merge-strategy squash
squash, merge, or rebase
--worktree <name>
Parallel execution via git worktrees
--disable-commits
Dry-run mode (no git operations)
--review-prompt "..."
Add reviewer pass per iteration
--ci-retry-max N
Auto-fix CI failures (default: 1)

Flag用途
--max-runs N
成功执行N次迭代后停止
--max-cost $X
消费满$X后停止
--max-duration 2h
运行指定时长后停止
--merge-strategy squash
合并策略:squash、merge或rebase
--worktree <name>
通过git worktree实现并行执行
--disable-commits
试运行模式(不执行git操作)
--review-prompt "..."
每个迭代添加审查环节
--ci-retry-max N
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
undefined

Step 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."
undefined
claude -p "审查工作区的所有变更,删除以下内容:
  • 验证语言/框架本身行为而非业务逻辑的测试
  • 类型系统已经保证的冗余类型校验
  • 针对不可能状态的过度防御性错误处理
  • Console.log语句
  • 注释掉的代码
保留所有业务逻辑测试,清理完成后运行测试套件确保没有功能损坏。"
undefined

In 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"
done
bash
for feature in "${features[@]}"; do
  # 实现
  claude -p "用TDD实现$feature。"

  # 去冗余
  claude -p "清理环节:审查变更,删除测试/代码冗余,运行测试。"

  # 验证
  claude -p "运行构建 + lint + 测试,修复所有失败项。"

  # 提交
  claude -p "提交信息:feat: add $feature"
done

Key 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-c
AI读取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-c

Complexity Tiers

复杂度等级

Different tiers get different pipeline depths:
TierPipeline Stages
trivialimplement → test
smallimplement → test → code-review
mediumresearch → plan → implement → test → PRD-review + code-review → review-fix
largeresearch → 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:
StageModelPurpose
ResearchSonnetRead codebase + RFC, produce context doc
PlanOpusDesign implementation steps
ImplementCodexWrite code following the plan
TestSonnetRun build + test suite
PRD ReviewSonnetSpec compliance check
Code ReviewOpusQuality + security check
Review FixCodexAddress review issues
Final ReviewOpusQuality 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 branch
File 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
undefined

MERGE 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}
undefined

Data 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

核心设计原则

  1. Deterministic execution — Upfront decomposition locks in parallelism and ordering
  2. Human review at leverage points — The work plan is the single highest-leverage intervention point
  3. Separate concerns — Each stage in a separate context window with a separate agent
  4. Conflict recovery with context — Full eviction context enables intelligent re-runs, not blind retries
  5. Tier-driven depth — Trivial changes skip research/review; large changes get maximum scrutiny
  6. Resumable workflows — Full state persisted to SQLite; resume from any point
  1. 确定性执行 — 前置拆解锁定并行度和执行顺序
  2. 高杠杆点人工审核 — 工作规划是最高杠杆的干预点
  3. 关注点分离 — 每个阶段在独立的上下文窗口中由独立的Agent执行
  4. 带上下文的冲突恢复 — 完整的驱逐上下文支持智能重跑,而非盲目的重试
  5. 等级驱动的深度 — 简单变更跳过研究/审查环节,大型变更获得最高级别的审核
  6. 可恢复工作流 — 完整状态持久化到SQLite,可从任意点恢复

When to Use Ralphinho vs Simpler Patterns

Ralphinho与简单模式的选型对比

SignalUse RalphinhoUse Simpler Pattern
Multiple interdependent work unitsYesNo
Need parallel implementationYesNo
Merge conflicts likelyYesNo (sequential is fine)
Single-file changeNoYes (sequential pipeline)
Multi-day projectYesMaybe (continuous-claude)
Spec/RFC already writtenYesMaybe
Quick iteration on one thingNoYes (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:
  1. Sequential Pipeline + De-Sloppify — The most common combination. Every implement step gets a cleanup pass.
  2. Continuous Claude + De-Sloppify — Add
    --review-prompt
    with a de-sloppify directive to each iteration.
  3. Any loop + Verification — Use ECC's
    /verify
    command or
    verification-loop
    skill as a gate before commits.
  4. 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"

这些模式可以很好地组合使用:
  1. 顺序流水线 + 去冗余 — 最常见的组合。每个实现步骤都搭配清理环节。
  2. 持续Claude + 去冗余 — 添加
    --review-prompt
    带去冗余指令到每个迭代。
  3. 任意循环 + 验证 — 使用ECC的
    /verify
    命令或
    verification-loop
    技能作为提交前的门禁。
  4. 简单循环中使用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

常见错误

  1. Infinite loops without exit conditions — Always have a max-runs, max-cost, max-duration, or completion signal.
  2. No context bridge between iterations — Each
    claude -p
    call starts fresh. Use
    SHARED_TASK_NOTES.md
    or filesystem state to bridge context.
  3. Retrying the same failure — If an iteration fails, don't just retry. Capture the error context and feed it to the next attempt.
  4. Negative instructions instead of cleanup passes — Don't say "don't do X." Add a separate pass that removes X.
  5. All agents in one context window — For complex workflows, separate concerns into different agent processes. The reviewer should never be the author.
  6. 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).

  1. 无退出条件的无限循环 — 始终设置max-runs、max-cost、max-duration或完成信号。
  2. 迭代间无上下文桥接 — 每个
    claude -p
    调用都是全新上下文,使用
    SHARED_TASK_NOTES.md
    或文件系统状态打通上下文。
  3. 相同失败重复重试 — 如果迭代失败,不要直接重试,捕获错误上下文并反馈给下一次尝试。
  4. 用否定指令替代清理环节 — 不要说“不要做X”,添加单独的环节删除X。
  5. 所有Agent共享同一个上下文窗口 — 复杂工作流要将关注点拆分到不同的Agent进程,审查者永远不要是作者。
  6. 并行工作中忽略文件重叠 — 如果两个并行Agent可能编辑同一个文件,你需要合并策略(顺序落地、变基或冲突解决)。

References

参考

ProjectAuthorLink
Ralphinhoenitratcredit: @enitrat
Infinite Agentic Loopdislercredit: @disler
Continuous ClaudeAnandChowdharycredit: @AnandChowdhary
NanoClawECC
/claw
command in this repo
Verification LoopECC
skills/verification-loop/
in this repo
项目作者链接
Ralphinhoenitratcredit: @enitrat
Infinite Agentic Loopdislercredit: @disler
Continuous ClaudeAnandChowdharycredit: @AnandChowdhary
NanoClawECC
/claw
command in this repo
Verification LoopECC
skills/verification-loop/
in this repo