Autonomous Loops

---
name: autonomous-loops
description: "自主 Claude Code 循环的模式和架构 —— 从简单的顺序管道到 RFC 驱动的多代理 DAG 系统。"
origin: ECC
---

# 自主循环技能 (Autonomous Loops Skill)

> 兼容性说明 (v1.8.0)：`autonomous-loops` 将保留一个版本。
> 规范技能名称现已改为 `continuous-agent-loop`。新的循环指南
> 应在何处编写，而此技能仍可用，以避免破坏现有工作流。

用于在循环中自主运行 Claude Code 的模式、架构和参考实现。涵盖了从简单的 `claude -p` 管道到完整的 RFC 驱动的多代理 DAG 编排的所有内容。

## 何时使用

- 设置无需人工干预即可运行的自主开发工作流
- 为您的问题选择正确的循环架构（简单 vs 复杂）
- 构建 CI/CD 风格的持续开发管道
- 运行带有合并协调的并行代理
- 在循环迭代中实现上下文持久化
- 为自主工作流添加质量门禁和清理环节

## 循环模式频谱

从最简单到最复杂：

| 模式 | 复杂度 | 最适合 |
|---------|-----------|----------|
| [顺序管道](#1-顺序管道-claude--p) | 低 | 日常开发步骤、脚本化工作流 |
| [NanoClaw REPL](#2-nanoclaw-repl) | 低 | 交互式持久会话 |
| [无限代理循环](#3-无限代理循环) | 中 | 并行内容生成、规范驱动型工作 |
| [持续 Claude PR 循环](#4-持续-claude-pr-循环) | 中 | 带有 CI 门禁的多日迭代项目 |
| [去碎片化模式 (De-Sloppify)](#5-去碎片化模式-de-sloppify-pattern) | 插件 | 任何实现者步骤后的质量清理 |
| [Ralphinho / RFC 驱动的 DAG](#6-ralphinho--rfc-驱动的-dag-编排) | 高 | 大型功能、带合并队列的多单元并行工作 |

---

## 1. 顺序管道 (`claude -p`)

**最简单的循环。** 将日常开发分解为一系列非交互式的 `claude -p` 调用。每次调用都是一个重点明确、提示词清晰的步骤。

### 核心见解

> 如果你无法搞定像这样的循环，那意味着你甚至无法驱动 LLM 在交互模式下修复你的代码。

`claude -p` 标志以非交互方式运行 Claude Code 并带有提示词，完成后退出。通过链接调用来构建管道：

```bash
#!/bin/bash
# daily-dev.sh — 功能分支的顺序管道

set -e

# 第 1 步：实现功能
claude -p "读取 docs/auth-spec.md 中的规范。在 src/auth/ 中实现 OAuth2 登录。先写测试 (TDD)。不要创建任何新的文档文件。"

# 第 2 步：去碎片化 (De-sloppify)（清理环节）
claude -p "审查上一次提交更改的所有文件。删除任何不必要的类型测试、过度防御性的检查或对语言特性的测试（例如，测试 TypeScript 泛型是否工作）。保留真实的业务逻辑测试。清理后运行测试套件。"

# 第 3 步：验证
claude -p "运行完整构建、代码检查、类型检查和测试套件。修复任何失败。不要添加新功能。"

# 第 4 步：提交
claude -p "为所有暂存的更改创建约定式提交。使用 'feat: add OAuth2 login flow' 作为消息。"
```

### 关键设计原则

1. **每个步骤都是隔离的** — 每次 `claude -p` 调用都有一个新的上下文窗口，这意味着步骤之间没有上下文污染。
2. **顺序很重要** — 步骤按顺序执行。每一步都建立在前一步留下的文件系统状态之上。
3. **否定指令是危险的** — 不要说“不要测试类型系统”。相反，添加一个单独的清理步骤（参见 [去碎片化模式](#5-去碎片化模式-de-sloppify-pattern)）。
4. **退出码传播** — `set -e` 会在失败时停止管道。

### 变体

**带有模型路由：**
```bash
# 使用 Opus 进行研究（深度推理）
claude -p --model opus "分析代码库架构并编写添加缓存的计划..."

# 使用 Sonnet 进行实现（快速且能力强）
claude -p "根据 docs/caching-plan.md 中的计划实现缓存层..."

# 使用 Opus 进行审查（彻底）
claude -p --model opus "审查所有更改的安全问题、竞态条件和边界情况..."
```

**带有环境上下文：**
```bash
# 通过文件传递上下文，而不是提示词长度
echo "重点领域：认证模块、API 速率限制" > .claude-context.md
claude -p "读取 .claude-context.md 获取优先级。按顺序处理它们。"
rm .claude-context.md
```

**带有 `--allowedTools` 限制：**
```bash
# 只读分析环节
claude -p --allowedTools "Read,Grep,Glob" "审计此代码库的安全漏洞..."

# 只写实现环节
claude -p --allowedTools "Read,Write,Edit,Bash" "实现 security-audit.md 中的修复..."
```

---

## 2. NanoClaw REPL

**ECC 内置的持久循环。** 一个具有会话感知能力的 REPL，它同步调用 `claude -p` 并带有完整的对话历史记录。

```bash
# 启动默认会话
node scripts/claw.js

# 带有技能上下文的命名会话
CLAW_SESSION=my-project CLAW_SKILLS=tdd-workflow,security-review node scripts/claw.js
```

### 工作原理

1. 从 `~/.claude/claw/{session}.md` 加载对话历史记录
2. 每个用户消息都发送到 `claude -p`，并将完整历史记录作为上下文
3. 响应被追加到会话文件（Markdown 作为数据库）
4. 会话在重启后仍然存在

### NanoClaw vs 顺序管道

| 使用场景 | NanoClaw | 顺序管道 |
|----------|----------|-------------------|
| 交互式探索 | 是 | 否 |
| 脚本化自动化 | 否 | 是 |
| 会话持久化 | 内置 | 手动 |
| 上下文累积 | 每一轮都会增长 | 每一步都是全新的 |
| CI/CD 集成 | 差 | 极佳 |

有关完整详细信息，请参阅 `/claw` 命令文档。

---

## 3. Infinite Agentic Loop

**一个双提示词系统**，用于编排并行子代理进行规范驱动的生成。由 disler 开发（致谢：@disler）。

### 架构：双提示词系统

```
提示词 1 (编排者)                    提示词 2 (子代理)
┌─────────────────────┐             ┌──────────────────────┐
│ 解析规范文件         │             │ 接收完整上下文        │
│ 扫描输出目录         │    部署     │ 读取分配的编号        │
│ 计划迭代             │────────────│ 严格遵循规范          │
│ 分配创意方向         │   N 个代理  │ 生成唯一输出          │
│ 管理波次             │             │ 保存到输出目录        │
└─────────────────────┘             └──────────────────────┘
```

### 模式

1. **规范分析** — 编排者读取定义要生成内容的规范文件 (Markdown)
2. **目录侦察** — 扫描现有输出以查找最高的迭代编号
3. **并行部署** — 启动 N 个子代理，每个代理都有：
   - 完整的规范
   - 唯一的创意方向
   - 特定的迭代编号（无冲突）
   - 现有迭代的快照（用于唯一性）
4. **波次管理** — 对于无限模式，部署 3-5 个代理的波次，直到上下文耗尽

### 通过 Claude Code 命令实现

创建 `.claude/commands/infinite.md`：

```markdown
从 $ARGUMENTS 解析以下参数：
1. spec_file — 规范 markdown 的路径
2. output_dir — 迭代保存的位置
3. count — 整数 1-N 或 "infinite"

第 1 阶段：读取并深入理解规范。
第 2 阶段：列出 output_dir，查找最高的迭代编号。从 N+1 开始。
第 3 阶段：计划创意方向 — 每个代理获得不同的主题/方法。
第 4 阶段：并行部署子代理 (Task 工具)。每个代理接收：
  - 完整规范文本
  - 当前目录快照
  - 他们分配的迭代编号
  - 他们唯一的创意方向
第 5 阶段 (无限模式)：以 3-5 个为一波循环，直到上下文变低。
```

**调用：**
```bash
/project:infinite specs/component-spec.md src/ 5
/project:infinite specs/component-spec.md src/ infinite
```

### 批处理策略

| 计数 | 策略 |
|-------|----------|
| 1-5 | 所有代理同时运行 |
| 6-20 | 每 5 个一组 |
| infinite | 3-5 个为一波，逐步精细化 |

### 核心见解：通过分配确保唯一性

不要指望代理会自动区分。编排者为每个代理**分配**特定的创意方向和迭代编号。这可以防止并行代理之间出现重复的概念。

---

## 4. 持续 Claude PR 循环

**一个生产级 shell 脚本**，它循环运行 Claude Code，创建 PR、等待 CI 并自动合并。由 AnandChowdhary 创建（致谢：@AnandChowdhary）。

### 核心循环

```
┌─────────────────────────────────────────────────────┐
│  持续 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 | 完成信号                  │
└─────────────────────────────────────────────────────┘
```

### 安装

> **警告：** 在审查代码后从其仓库安装 continuous-claude。不要直接将外部脚本通过管道传输到 bash。

### 用法

```bash
# 基础：10 次迭代
continuous-claude --prompt "为所有未测试的函数添加单元测试" --max-runs 10

# 成本限制
continuous-claude --prompt "修复所有 linter 错误" --max-cost 5.00

# 时间限制
continuous-claude --prompt "提高测试覆盖率" --max-duration 8h

# 带有代码审查环节
continuous-claude \
  --prompt "添加身份认证功能" \
  --max-runs 10 \
  --review-prompt "运行 npm test && npm run lint，修复任何失败"

# 通过 worktree 并行运行
continuous-claude --prompt "添加测试" --max-runs 5 --worktree tests-worker &
continuous-claude --prompt "重构代码" --max-runs 5 --worktree refactor-worker &
wait
```

### 跨迭代上下文：SHARED_TASK_NOTES.md

关键创新：一个跨迭代持久存在的 `SHARED_TASK_NOTES.md` 文件：

```markdown
## 进度
- [x] 为认证模块添加了测试（第 1 次迭代）
- [x] 修复了令牌刷新中的边缘情况（第 2 次迭代）
- [ ] 仍然需要：速率限制测试、错误边界测试

## 下一步
- 下一步专注于速率限制模块
- tests/helpers.ts 中的模拟设置可以重复使用
```

Claude 在迭代开始时读取此文件，并在迭代结束时更新它。这弥补了独立 `claude -p` 调用之间的上下文差距。

### CI 失败恢复

当 PR 检查失败时，Continuous Claude 会自动：
1. 通过 `gh run list` 获取失败的运行 ID
2. 启动一个新的带有 CI 修复上下文的 `claude -p`
3. Claude 通过 `gh run view` 检查日志，修复代码，提交并推送
4. 重新等待检查（最多重试 `--ci-retry-max` 次）

### 完成信号

Claude 可以通过输出一个魔术短语来发出“我完成了”的信号：

```bash
continuous-claude \
  --prompt "修复问题跟踪器中的所有 bug" \
  --completion-signal "CONTINUOUS_CLAUDE_PROJECT_COMPLETE" \
  --completion-threshold 3  # 在连续 3 次信号后停止
```

连续三次迭代发出完成信号将停止循环，防止在完成的工作上浪费运行次数。

### 关键配置

| 标志 | 用途 |
|------|---------|
| `--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. 去碎片化模式 (De-Sloppify Pattern)

**适用于任何循环的插件模式。** 在每个实现者步骤之后添加一个专门的清理/重构步骤。

### 问题所在

当你要求 LLM 通过 TDD 实现功能时，它对“编写测试”的理解过于字面：
- 验证 TypeScript 类型系统是否工作的测试（测试 `typeof x === 'string'`）
- 对类型系统已经保证的内容进行过度防御性的运行时检查
- 对框架行为而非业务逻辑进行测试
- 掩盖了实际代码的过度错误处理

### 为什么不使用否定指令？

在实现者提示词中添加“不要测试类型系统”或“不要添加不必要的检查”会产生下游效应：
- 模型对所有测试都变得犹豫不决
- 它跳过了合法的边缘情况测试
- 质量以不可预测的方式下降

### 解决方案：单独的环节

与其限制实现者，不如让它彻底。然后添加一个专注的清理代理：

```bash
# 第 1 步：实现（让它彻底）
claude -p "通过完整的 TDD 实现功能。在测试方面要彻底。"

# 第 2 步：去碎片化 (De-sloppify)（独立上下文，专注清理）
claude -p "审查工作树中的所有更改。删除：
- 验证语言/框架行为而非业务逻辑的测试
- 类型系统已经强制执行的冗余类型检查
- 对不可能状态的过度防御性错误处理
- Console.log 语句
- 被注释掉的代码

保留所有业务逻辑测试。清理后运行测试套件以确保没有任何损坏。"
```

### 在循环上下文中

```bash
for feature in "${features[@]}"; do
  # 实现
  claude -p "通过 TDD 实现 $feature。"

  # 去碎片化
  claude -p "清理环节：审查更改，删除测试/代码碎片，运行测试。"

  # 验证
  claude -p "运行构建 + lint + 测试。修复任何失败。"

  # 提交
  claude -p "提交，消息为：feat: add $feature"
done
```

### 核心见解

> 与其添加具有下游质量影响的否定指令，不如添加一个单独的去碎片化环节。两个专一的代理胜过一个受限的代理。

---

## 6. Ralphinho / RFC 驱动的 DAG 编排

**最复杂的模式。** 一个由 RFC 驱动的多代理管道，它将规范分解为依赖 DAG，通过分级质量管道运行每个单元，并通过代理驱动的合并队列将其落地。由 enitrat 创建（致谢：@enitrat）。

### 架构概览

```
RFC/PRD 文档
       │
       ▼
  分解 (AI)
  将 RFC 分解为具有依赖 DAG 的工作单元
       │
       ▼
┌──────────────────────────────────────────────────────┐
│  RALPH 循环 (最多 3 个环节)                          │
│                                                      │
│  对于每个 DAG 层（按依赖关系顺序）：                 │
│                                                      │
│  ┌── 质量管道 (每个单元并行) ─────────────────────┐  │
│  │  每个单元在自己的 worktree 中：                │  │
│  │  研究 → 计划 → 实现 → 测试 → 审查              │  │
│  │  (深度因复杂度层级而异)                        │  │
│  └────────────────────────────────────────────────┘  │
│                                                      │
│  ┌── 合并队列 ────────────────────────────────────┐  │
│  │  变基到 main → 运行测试 → 落地或剔除            │  │
│  │  被剔除的单元带着冲突上下文重新进入            │  │
│  └────────────────────────────────────────────────┘  │
│                                                      │
└──────────────────────────────────────────────────────┘
```

### RFC 分解

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 决定执行顺序：
```
第 0 层: [unit-a, unit-b]     ← 无依赖，并行运行
第 1 层: [unit-c]             ← 依赖于 unit-a
第 2 层: [unit-d, unit-e]     ← 依赖于 unit-c
```

### 复杂度层级

不同的层级获得不同的管道深度：

| 层级 | 管道阶段 |
|------|----------------|
| **trivial** (琐碎) | 实现 → 测试 |
| **small** (小) | 实现 → 测试 → 代码审查 |
| **medium** (中) | 研究 → 计划 → 实现 → 测试 → PRD 审查 + 代码审查 → 审查修复 |
| **large** (大) | 研究 → 计划 → 实现 → 测试 → PRD 审查 + 代码审查 → 审查修复 → 最终审查 |

这可以防止在简单的更改上进行昂贵的操作，同时确保架构更改得到彻底的审查。

### 独立的上下文窗口（消除作者偏见）

每个阶段都在自己的代理进程中运行，并具有自己的上下文窗口：

| 阶段 | 模型 | 用途 |
|-------|-------|---------|
| 研究 | Sonnet | 读取代码库 + RFC，生成上下文文档 |
| 计划 | Opus | 设计实现步骤 |
| 实现 | Codex | 按照计划编写代码 |
| 测试 | Sonnet | 运行构建 + 测试套件 |
| PRD 审查 | Sonnet | 规范合规性检查 |
| 代码审查 | Opus | 质量 + 安全检查 |
| 审查修复 | Codex | 处理审查发现的问题 |
| 最终审查 | Opus | 质量门禁（仅限 large 层级） |

**关键设计：** 审查者永远不会审查它自己编写的代码。这消除了作者偏见 —— 这是自我审查中最常见的遗漏源。

### 带有剔除机制的合并队列

在质量管道完成后，单元进入合并队列：

```
单元分支
    │
    ├─ 变基到 main
    │   └─ 冲突？ → 剔除 (EVICT)（捕获冲突上下文）
    │
    ├─ 运行构建 + 测试
    │   └─ 失败？ → 剔除 (EVICT)（捕获测试输出）
    │
    └─ 通过 → 快速合并到 main，推送，删除分支
```

### 文件重叠智能

- 非重叠单元并行试探性落地
- 重叠单元逐个落地，每次都进行变基

### 剔除恢复

当被剔除时，会捕获完整的上下文（冲突文件、差异、测试输出），并在下一次 Ralph 环节中反馈给实现者：

```markdown
## 合并冲突 — 在下一次落地前解决

你之前的实现与另一个先落地的单元发生了冲突。
请重组你的更改，以避开下面冲突的文件/行。

{带有差异的完整剔除上下文}
```

### 阶段间的数据流

```
research.contextFilePath ──────────────────→ 计划 (plan)
plan.implementationSteps ──────────────────→ 实现 (implement)
implement.{filesCreated, whatWasDone} ─────→ 测试 (test), 审查 (reviews)
test.failingSummary ───────────────────────→ 审查 (reviews), 实现 (implement) (下一轮)
reviews.{feedback, issues} ────────────────→ 审查修复 (review-fix) → 实现 (implement) (下一轮)
final-review.reasoning ────────────────────→ 实现 (implement) (下一轮)
evictionContext ───────────────────────────→ 实现 (implement) (合并冲突后)
```

### Worktree 隔离

每个单元都在隔离的 worktree 中运行（使用 jj/Jujutsu，而不是 git）：
```
/tmp/workflow-wt-{unit-id}/
```

同一单元的管道阶段**共享**一个 worktree，在研究 → 计划 → 实现 → 测试 → 审查的过程中保留状态（上下文文件、计划文件、代码更改）。

### 关键设计原则

1. **确定性执行** — 预先分解锁定并行性和顺序
2. **在关键点进行人工审查** — 工作计划是单一最高杠杆的干预点
3. **关注点分离** — 每个阶段都在独立的上下文窗口中由独立的代理运行
4. **带上下文的冲突恢复** — 完整的剔除上下文实现了智能重跑，而非盲目重试
5. **层级驱动的深度** — 琐碎的更改跳过研究/审查；大型更改获得最大程度的审视
6. **可恢复的工作流** — 完整状态持久化到 SQLite；可从任何点恢复

### 何时使用 Ralphinho vs 更简单的模式

| 信号 | 使用 Ralphinho | 使用更简单的模式 |
|--------|--------------|-------------------|
| 多个相互依赖的工作单元 | 是 | 否 |
| 需要并行实现 | 是 | 否 |
| 合并冲突可能性大 | 是 | 否 (顺序执行即可) |
| 单文件更改 | 否 | 是 (顺序管道) |
| 多日项目 | 是 | 也许 (continuous-claude) |
| 规范/RFC 已编写 | 是 | 也许 |
| 在一件事上快速迭代 | 否 | 是 (NanoClaw 或管道) |

---

## 选择正确的模式

### 决策矩阵

```
任务是单一、专注的更改吗？
├─ 是 → 顺序管道或 NanoClaw
└─ 否 → 是否有书面规范/RFC？
         ├─ 是 → 是否需要并行实现？
         │        ├─ 是 → Ralphinho (DAG 编排)
         │        └─ 否 → Continuous Claude (迭代 PR 循环)
         └─ 否 → 是否需要同一事物的许多变体？
                  ├─ 是 → 无限代理循环 (规范驱动型生成)
                  └─ 否 → 带有去碎片化的顺序管道
```

### 模式组合

这些模式可以很好地组合：

1. **顺序管道 + 去碎片化** — 最常见的组合。每个实现步骤都有一个清理环节。

2. **Continuous Claude + 去碎片化** — 在每次迭代中添加带有去碎片化指令的 `--review-prompt`。

3. **任何循环 + 验证** — 使用 ECC 的 `/verify` 命令或 `verification-loop` 技能作为提交前的门禁。

4. **简单循环中的 Ralphinho 分级方法** — 即使在顺序管道中，你也可以将简单的任务路由到 Haiku，将复杂的任务路由到 Opus：
   ```bash
   # 简单的格式修复
   claude -p --model haiku "修复 src/utils.ts 中的导入排序"

   # 复杂的架构更改
   claude -p --model opus "将认证模块重构为使用策略模式"
   ```

---

## 反面模式 (Anti-Patterns)

### 常见错误

1. **没有退出条件的死循环** — 始终设定 max-runs、max-cost、max-duration 或完成信号。

2. **迭代之间没有上下文桥梁** — 每次 `claude -p` 调用都是全新的。使用 `SHARED_TASK_NOTES.md` 或文件系统状态来桥接上下文。

3. **重试同样的失败** — 如果一次迭代失败，不要只是重试。捕获错误上下文并将其反馈给下一次尝试。

4. **使用否定指令而非清理环节** — 不要说“不要做 X”。添加一个专门删除 X 的环节。

5. **所有代理共用一个上下文窗口** — 对于复杂的工作流，将关注点分离到不同的代理进程中。审查者永远不应该是作者。

6. **在并行工作中忽略文件重叠** — 如果两个并行代理可能会编辑同一个文件，你需要一个合并策略（顺序落地、变基或冲突解决）。

---

## 参考资料

| 项目 | 作者 | 链接 |
|---------|--------|------|
| Ralphinho | enitrat | 致谢: @enitrat |
| Infinite Agentic Loop | disler | 致谢: @disler |
| Continuous Claude | AnandChowdhary | 致谢: @AnandChowdhary |
| NanoClaw | ECC | 本仓库中的 `/claw` 命令 |
| 验证循环 (Verification Loop) | ECC | 本仓库中的 `skills/verification-loop/` |