autonomous-loops

自律ループスキル (Autonomous Loops Skill)

Claude Code のループを自律的に実行するためのパターン、アーキテクチャ、リファレンス実装です。シンプルな claude -p パイプラインから、RFC 駆動の完全なマルチエージェント DAG オーケストレーションまで、あらゆる内容を網羅しています。

適用シーン

• 人手を介さずに実行できる自律開発ワークフローを設定する
• 課題に適したループアーキテクチャ（シンプルか複雑か）を選ぶ
• CI/CD スタイルの継続的な開発パイプラインを構築する
• マージ調整機構を備えた並列エージェントを実行する
• ループの反復間でコンテキストを永続化する
• 自律ワークフローに品質ゲートとクリーンアップ工程を追加する

ループパターンのスペクトラム (Loop Pattern Spectrum)

最もシンプルなものから最も複雑なものまで：

パターン	複雑さ	最適な用途
順次パイプライン (Sequential Pipeline)	低	日常的な開発手順、スクリプト化されたワークフロー
NanoClaw REPL	低	対話型の永続セッション
無限エージェントループ (Infinite Agentic Loop)	中	コンテンツの並列生成、仕様駆動の作業
継続的 Claude PR ループ (Continuous Claude PR Loop)	中	CI ゲートを備えた複数日にわたる反復プロジェクト
デスロッピファイパターン (De-Sloppify Pattern)	追加	あらゆる実装手順の後に行う品質クリーンアップ
Ralphinho / RFC 駆動の DAG	高	大規模な機能、マージキューを備えた複数単位の並列作業

---

1. 順次パイプライン (Sequential Pipeline, claude -p)

最もシンプルなループです。 日常的な開発作業を、非対話型の claude -p 呼び出しの連続に分解します。各呼び出しは、明確なプロンプトを指定した、焦点を絞ったステップです。

核心的な洞察

このようなループを理解できないのであれば、対話モードで LLM にコードを修正させることさえできないということです。

claude -p フラグは、プロンプトを指定して Claude Code を非対話的に実行し、完了後に終了します。呼び出しを連結してパイプラインを構築します：

#!/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 "运行完整的构建、代码检查（lint）、类型检查和测试套件。修复任何失败。不要添加新功能。"

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

主な設計原則

1. 各ステップは独立しています — claude -p を呼び出すたびに新しいコンテキストウィンドウが使われるため、ステップ間でコンテキストが混入しません。
2. 順序が重要です — ステップは順番に実行されます。各ステップは、前のステップが残したファイルシステムの状態を基に進みます。
3. 否定的な指示は危険です — 「型システムをテストしないで」と指示しないでください。代わりに、個別のクリーンアップステップを追加します（デスロッピファイパターンを参照）。
4. 終了コードは伝播します — set -e により、失敗時にパイプラインが停止します。

バリエーション

モデルルーティングを使用：

# 使用 Opus 进行调研（深度推理）
claude -p --model opus "分析代码库架构并编写添加缓存的计划..."

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

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

環境コンテキストを指定：

# 通过文件传递上下文，而不是增加提示词长度
echo "重点领域：auth 模块，API 速率限制" > .claude-context.md
claude -p "阅读 .claude-context.md 获取优先级信息。按顺序处理它们。"
rm .claude-context.md

--allowedTools による制限を指定：

# 只读分析阶段
claude -p --allowedTools "Read,Grep,Glob" "审计此代码库的安全漏洞..."

# 只写实现阶段
claude -p --allowedTools "Read,Write,Edit,Bash" "实现 security-audit.md 中的修复方案..."

---

2. NanoClaw REPL

ECC に組み込まれた永続ループです。 セッションを認識する REPL で、会話履歴全体を含めて claude -p を同期的に呼び出します。

# 启动默认会话
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 と順次パイプラインの比較

使用シーン	NanoClaw	順次パイプライン
対話型の探索	はい	いいえ
スクリプトによる自動化	いいえ	はい
セッションの永続化	組み込み	手動
コンテキストの蓄積	ターンごとに増加	ステップごとに新規
CI/CD との統合	不向き	優れている

詳細は /claw コマンドのドキュメントを参照してください。

---

3. 無限エージェントループ (Infinite Agentic Loop)

仕様駆動の生成に向けて、並列サブエージェントを調整する二重プロンプトシステムです。disler が開発しました（謝辞：@disler）。

アーキテクチャ：二重プロンプトシステム

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

パターン

1. 仕様分析 — オーケストレーターが、生成するコンテンツを定義した仕様ファイル（Markdown）を読み込みます。
2. ディレクトリの調査 — 既存の出力をスキャンし、最も大きな反復番号を見つけます。
3. 並列デプロイ — N 個のサブエージェントを起動します。各サブエージェントには以下が渡されます：
   • 仕様全体
   • 固有の創造的な方向性
   • 特定の反復番号（競合なし）
   • 既存の反復のスナップショット（一意性を確保するため）
4. ウェーブ管理 — 無限モードでは、コンテキストが尽きるまで、3～5 個のエージェントを1ウェーブとしてデプロイします。

Claude Code コマンドによる実装

.claude/commands/infinite.md を作成します：

从 $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 个为一波次循环，直到上下文过低。

呼び出し：

/project:infinite specs/component-spec.md src/ 5
/project:infinite specs/component-spec.md src/ infinite

バッチ戦略

数量	戦略
1-5	すべてのエージェントを同時に実行
6-20	1バッチ5個
infinite	3～5個ずつウェーブ状に実行し、複雑さを段階的に高める

核心的な洞察：割り当てによって一意性を確保する

エージェントが自ら差別化することを期待しないでください。オーケストレーターが、各エージェントに特定の創造的な方向性と反復番号を割り当てます。これにより、並列エージェント間で概念が重複するのを防げます。

---

4. 継続的 Claude PR ループ (Continuous Claude PR Loop)

Claude Code を継続的なループで実行し、PR の作成、CI の待機、自動マージを行う本番環境向けのシェルスクリプトです。AnandChowdhary が開発しました（謝辞：@AnandChowdhary）。

コアループ

┌─────────────────────────────────────────────────────┐
│  持续 CLAUDE 迭代 (CONTINUOUS CLAUDE ITERATION)     │
│                                                     │
│  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 | 完成信号             │
└─────────────────────────────────────────────────────┘

インストール

curl -fsSL https://raw.githubusercontent.com/AnandChowdhary/continuous-claude/HEAD/install.sh | 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，修复任何失败"

# 通过工作树 (worktrees) 并行运行
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 ファイルです：

## 进度
- [x] 为 auth 模块添加了测试 (迭代 1)
- [x] 修复了 token 刷新的边界情况 (迭代 2)
- [ ] 仍需：速率限制测试，错误边界测试

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

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 は特別なフレーズを出力して、「完了しました」と伝えることができます：

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

3回連続で完了シグナルが出力されるとループが停止し、完了済みの作業にクレジットを無駄に使うのを防ぎます。

主な設定

フラグ	用途
--max-runs N	N 回の反復が成功した後に停止します
--max-cost $X	$X を費やした後に停止します
--max-duration 2h	指定時間が経過した後に停止します
--merge-strategy squash	マージ戦略：squash、merge、または rebase
--worktree <name>	git ワークツリーを使って並列実行します
--disable-commits	ドライランモード（git 操作は行いません）
--review-prompt "..."	各反復にレビュアーのステージを追加します
--ci-retry-max N	CI の失敗を自動修正します（デフォルト：1）

---

5. デスロッピファイパターン (The De-Sloppify Pattern)

あらゆるループに追加できるパターンです。 各実装者ステップの後に、専用のクリーンアップ／リファクタリングステップを追加します。

問題点

LLM に TDD で機能を実装するように頼むと、「テストを書く」という指示を文字どおりに受け取りすぎる場合があります：

• TypeScript の型システムが機能することをテストする（typeof x === 'string' をテストする）
• 型システムですでに保証されていることに対して、過度に防御的なランタイムチェックを書く
• ビジネスロジックではなく、テストフレームワークの動作をテストする
• 過剰なエラー処理で実際のコードを覆い隠す

なぜ否定的な指示を使わないのか？

実装者向けのプロンプトに「型システムをテストしない」や「不要なチェックを追加しない」といった指示を加えると、副作用が生じます：

• モデルがすべてのテストに対して慎重になりすぎます
• 妥当な境界値テストを省略するようになります
• 品質が予測不能な形で低下します

解決策：独立したクリーンアップ段階

実装者を制限するのではなく、能力を存分に発揮させます。その後、クリーンアップに特化したエージェントを追加します：

# 第 1 步：实现（让它彻底发挥）
claude -p "通过完整的 TDD 实现该功能。测试要彻底。"

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

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

ループのコンテキストで使用する

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

  # 去杂质
  claude -p "清理阶段：审查更改，删除测试/代码杂质，运行测试。"

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

  # 提交
  claude -p "提交并附带消息：feat: add $feature"
done

重要な洞察

下流の品質に影響する否定的な指示を追加するより、独立した不純物除去の段階を追加するほうが効果的です。制限されたエージェントを1つ使うより、特化したエージェントを2つ使うほうが優れています。

---

6. Ralphinho / RFC 主導の DAG オーケストレーション (RFC-Driven DAG Orchestration)

最も複雑なパターンです。 RFC 主導のマルチエージェントパイプラインで、仕様を依存関係 DAG（有向非巡回グラフ）に分解し、各単位を階層型品質パイプラインで実行して、エージェント主導のマージキュー（Merge queue）を通じて取り込みます。enitrat が開発しました（謝辞：@enitrat）。

アーキテクチャの概要

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

RFC の分解

AI が RFC を読み取り、作業単位を生成します：

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

複雑さの階層 (Complexity Tiers)

階層ごとにパイプラインの深さが異なります：

階層	パイプラインの段階
trivial（ごく小規模）	実装 → テスト
small（小規模）	実装 → テスト → コードレビュー
medium（中規模）	調査 → 計画 → 実装 → テスト → PRD レビュー + コードレビュー → レビュー対応
large（大規模）	調査 → 計画 → 実装 → テスト → PRD レビュー + コードレビュー → レビュー対応 → 最終レビュー

これにより、単純な変更に対するコストの高い作業を防ぎながら、アーキテクチャの変更を徹底的にレビューできます。

独立したコンテキストウィンドウ (作者バイアスの排除)

各段階は、それぞれ独自のコンテキストウィンドウを持つ別個のエージェントプロセスで実行されます：

段階	モデル	用途
調査	Sonnet	コードベースと RFC を読み、コンテキスト文書を生成します
計画	Opus	実装手順を設計します
実装	Codex	計画に従ってコードを記述します
テスト	Sonnet	ビルドとテストスイートを実行します
PRD レビュー	Sonnet	仕様への準拠を確認します
コードレビュー	Opus	品質とセキュリティを確認します
レビュー対応	Codex	レビューで見つかった問題に対応します
最終レビュー	Opus	品質ゲート（大規模階層のみ）

設計の核： レビュー担当者がコードの作成者を兼ねることは決してありません。これにより、自己レビューで最もよくある見落としの原因である作者バイアス（author bias）を排除します。

追い出し機能付きマージキュー (Merge Queue with Eviction)

品質パイプラインが完了すると、単位はマージキューに入ります：

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

ファイル重複の処理：

• ファイルが重複しない単位は、推測的に並行して取り込みます
• ファイルが重複する単位は、毎回リベースしながら1つずつ取り込みます

追い出しからの復旧： 追い出された場合、完全なコンテキスト（競合ファイル、diff、テスト出力）が取得され、次回の Ralph ループで実装者に渡されます：

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

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

{带有 diff 的完整剔除上下文}

段階間のデータフロー

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 Isolation)

各単位は、隔離されたワークツリーで実行されます（git ではなく、jj/Jujutsu を使用します）：

/tmp/workflow-wt-{unit-id}/

同じ単位のパイプライン段階は、1つのワークツリーを共有します。そのため、調査 → 計画 → 実装 → テスト → レビューの全過程で、コンテキストファイル、計画ファイル、コード変更などの状態が保持されます。

主要な設計原則

1. 決定的な実行 — 事前の分解によって、並列性と実行順序が確定します。
2. 要所での人間によるレビュー — 作業計画は、最も効果の高い介入ポイントです。
3. 関心の分離 — 各段階は、独立したエージェントが独立したコンテキストウィンドウで実行します。
4. コンテキスト付きの競合復旧 — 追い出し時の完全なコンテキストにより、盲目的な再試行ではなく、的確な再実行が可能になります。
5. 階層に応じた深さ — ごく小規模な変更では調査とレビューを省略し、大規模な変更には最大限の精査を行います。
6. 復旧可能なワークフロー — 状態全体を SQLite に永続化し、どの時点からでも再開できます。

Ralphinho とシンプルなパターンの使い分け

目安	Ralphinho を使用	シンプルなパターンを使用
相互依存する複数の作業単位	はい	いいえ
並行実装が必要	はい	いいえ
マージ競合が発生する可能性が高い	はい	いいえ（順次実行で十分です）
単一ファイルの変更	いいえ	はい（順次パイプライン）
数日間にわたるプロジェクト	はい	場合によります（continuous-claude）
仕様/RFC が作成済み	はい	場合によります
何かを素早く反復する	いいえ	はい（NanoClaw またはパイプライン）

---

適切なパターンの選択

判断マトリックス

任务是否为单个专注的更改？
├─ 是 → 顺序流水线 (Sequential Pipeline) 或 NanoClaw
└─ 否 → 是否有书面的规约/RFC？
         ├─ 是 → 是否需要并行实现？
         │        ├─ 是 → Ralphinho (DAG 编排)
         │        └─ 否 → Continuous Claude (迭代式 PR 循环)
         └─ 否 → 是否需要同一事物的多个变体？
                  ├─ 是 → 无限智能体循环 (Infinite Agentic Loop, 规约驱动生成)
                  └─ 否 → 带去杂质阶段的顺序流水线

パターンの組み合わせ

これらのパターンは、組み合わせて効果的に使えます：

1. 順次パイプライン + 不純物除去 — 最も一般的な組み合わせです。実装の各段階にクリーンアップ段階を設けます。

2. Continuous Claude + 不純物除去 — 各反復で --review-prompt に不純物除去の指示を追加します。

3. 任意のループ + 検証 — コミット前のゲートとして、ECC の /verify コマンドまたは verification-loop スキルを使います。

4. シンプルなループで Ralphinho の階層型手法を活用する — 順次パイプラインでも、単純なタスクは Haiku に、複雑なタスクは Opus に割り当てられます：

   # 简单的格式化修复
   claude -p --model haiku "修复 src/utils.ts 中的导入顺序"
   
   # 复杂的架构更改
   claude -p --model opus "重构 auth 模块以使用策略模式"
   

---

アンチパターン (Anti-Patterns)

よくある間違い

1. 終了条件のない無限ループ — 必ず max-runs、max-cost、max-duration、または完了シグナルを設定してください。

2. 反復間のコンテキストの橋渡しがない — claude -p の呼び出しは毎回新規に開始します。SHARED_TASK_NOTES.md またはファイルシステムの状態を使って、コンテキストを引き継いでください。

3. 同じ失敗を繰り返す — 反復が失敗した場合、ただ再試行してはいけません。エラーのコンテキストを取得し、次の試行に渡してください。

4. クリーンアップ段階の代わりに否定的な指示を使う — 「X をしないでください」と指示するのではなく、X を削除する独立した段階を追加してください。

5. すべてのエージェントで1つのコンテキストウィンドウを共有する — 複雑なワークフローでは、関心を別々のエージェントプロセスに分離してください。レビュー担当者が作成者を兼ねることは決して避けてください。

6. 並行作業でファイルの重複を無視する — 2つの並行エージェントが同じファイルを編集する可能性がある場合は、マージ戦略（順次取り込み、リベース、または競合解決）が必要です。

---

参考資料

プロジェクト	作者	リンク
Ralphinho	enitrat	謝辞：@enitrat
Infinite Agentic Loop	disler	謝辞：@disler
Continuous Claude	AnandChowdhary	謝辞：@AnandChowdhary
NanoClaw	ECC	このリポジトリ内の /claw コマンド
Verification Loop	ECC	このリポジトリ内の skills/verification-loop/