autonomous-loop

自主循环

概述

自主循环实现了 Ralph 的迭代式开发方法。每次迭代都会加载相同的上下文（PROMPT + AGENTS 文件），执行一项专注任务，报告结构化状态，并将状态持久化到磁盘，以供下一次迭代使用。循环会持续进行，直到满足双重条件退出门槛。其核心创新在于，确定性条件使 Claude 能够在无需人工介入的情况下自主规划、构建并迭代，从而不断提升质量。

启动时请说明：“我将启动自主循环。正在加载上下文并开始 PLANNING 模式。”

触发条件

• 调用 /ralph 或 /loop 命令
• 项目已有规格说明，且已准备好进行迭代式自主开发
• 适合通过自主迭代完成的多任务实现
• 用户要求自主执行，无需逐项任务审批

---

架构

+--------------------------------------------------+
|                 AUTONOMOUS LOOP                    |
|                                                    |
|  +----------+    +----------+    +-----------+    |
|  | PLANNING |---→| BUILDING |---→|  STATUS   |    |
|  |   MODE   |    |   MODE   |    |  CHECK    |    |
|  +----------+    +----------+    +-----+-----+    |
|       ^                               |           |
|       |            +-----------+      |           |
|       +------------|  EXIT GATE|←-----+           |
|                    |  (dual)   |                   |
|                    +-----+-----+                   |
|                          |                         |
|                    PASS: EXIT                      |
|                    FAIL: LOOP                      |
+--------------------------------------------------+

---

阶段 1：PLANNING 模式（差距分析）

目标： 对照实现分析规格说明，识别并确定剩余工作的优先级。

PLANNING 模式不产出任何实现代码。仅进行分析和规划。

步骤

1. 收集知识 — 通过 Agent 工具（使用 subagent_type="Explore" 和 model="sonnet"）部署最多 250 个并行子 Agent，研究规格说明、现有实现计划和工具库
2. 代码分析 — 通过 Agent 工具（使用 subagent_type="Explore"）部署最多 500 个并行子 Agent，对照 specs/* 研究 src/*，找出规格说明与实现之间的差距
3. 综合分析 — 通过 Agent 工具部署一个综合分析子 Agent（使用 model="opus"），汇总发现并确定未完成工作的优先级
4. 刷新计划 — 将 IMPLEMENTATION_PLAN.md 更新为条理清晰、按优先级排列的要点列表

PLANNING 模式约束

约束	原因
通过代码搜索验证所有假设	切勿假定某项内容不存在
将 src/lib 视为权威标准库	应整合，而非重复实现
输出为按优先级排列的任务列表	不是代码，也不是设计，只包含任务
识别缺失的规格说明	规格说明缺失会阻碍工作，不能靠猜测解决

PLANNING 模式输出

IMPLEMENTATION_PLAN.md updated:
- [x] Completed tasks (checked off)
- [ ] Remaining task 1 (highest priority)
- [ ] Remaining task 2
- [ ] Remaining task 3
...
Missing specs identified: [list or "none"]

停止——在进入阶段 2 之前，必须：

• 阅读并分析所有规格说明
• 对照规格说明检查代码
• 更新 IMPLEMENTATION_PLAN.md，列出按优先级排列的任务
• 识别缺失的规格说明（如有）

---

阶段 2：BUILDING 模式（实现）

目标： 每次迭代恰好选择并完成一项任务。

“每次循环一项任务”原则

每次迭代都会从 IMPLEMENTATION_PLAN.md 中选择并完成恰好一项任务。这样可以减少上下文切换，便于清晰衡量进度，也让调试更容易。

步骤

1. 研究 — 阅读规格说明和当前的 IMPLEMENTATION_PLAN.md
2. 选择 — 选择最重要的剩余任务
3. 搜索 — 查找现有代码模式（切勿假定缺少实现）
4. 实现 — 编写完整、达到生产质量的代码（无占位符，无存根）
5. 测试 — 实现后立即运行测试
6. 更新 — 根据发现和进度刷新 IMPLEMENTATION_PLAN.md
7. 提交 — 使用带有理由说明的描述性 Conventional Commit 提交信息

任务选择决策表

条件	选择哪项任务
存在阻碍其他任务的阻塞项	选择该阻塞项任务
存在测试失败	选择修复失败的任务
所有任务相互独立	选择优先级最高的任务
多项任务优先级相同	选择规格说明最明确的任务
最高优先级任务缺少规格说明	运行 PLANNING 模式以识别差距

构建期间的子 Agent 规则

资源	预算	原因
读取/搜索子 Agent	最多 500 个并行 Sonnet	快速收集上下文
构建子 Agent	同一时间仅限 1 个 Sonnet	串行构建以检测故障
主上下文	40-60% 的利用率	“智能区”——留出足够空间进行思考

构建模式约束

约束	原因
不得使用占位符或存根	每一行代码都必须达到生产级质量
实现前先搜索	代码可能已存在于其他位置
立即运行测试	尽早通过反压发现错误
每完成一项任务后更新计划	使计划始终符合实际情况
每完成一项任务后提交	小型原子提交，易于回滚

停止——在进入第 3 阶段前，不得继续：

• 任务已完整实现（没有存根）
• 已运行测试
• 已更新 IMPLEMENTATION_PLAN.md
• 已提交更改

---

第 3 阶段：状态检查

目标： 生成 RALPH_STATUS 块并评估退出条件。

每次 BUILD 迭代后，调用 ralph-status 技能以生成结构化状态块。

退出评估

检查项	条件	结果
还有剩余任务吗？	IMPLEMENTATION_PLAN.md 中有未勾选的项目	继续循环
测试通过了吗？	完整测试套件通过	退出的必要条件
本次迭代有错误吗？	执行干净，没有未解决的异常	退出的必要条件
还有有意义的工作吗？	没有 TODO，也没有未完成的功能	退出的必要条件

循环决策

状态	剩余任务	测试	操作
IN_PROGRESS	有	任意	返回第 1 或第 2 阶段
IN_PROGRESS	无	未通过	继续循环——先修复故障
BLOCKED	任意	任意	报告阻塞问题，等待输入
COMPLETE	无	通过	评估退出门槛

---

退出条件——双条件门槛

必须同时满足以下两个条件才能退出循环：

条件	阈值	验证方式
完成指标	最近至少 2 次出现表示“完成”的措辞	对输出进行启发式检测
显式 EXIT_SIGNAL	状态块中为 EXIT_SIGNAL: true	有意声明

只有在以下所有条件均满足时，EXIT_SIGNAL 才可设为 true

• IMPLEMENTATION_PLAN.md 中没有剩余任务
• 所有测试均通过
• 最新一次迭代没有错误
• 没有剩余的有意义工作

这样可以避免出现误报：即使出现表示完成的措辞，实际工作仍在继续。

退出决策表

完成措辞	EXIT_SIGNAL	操作
少于 2 次	false	继续循环
至少 2 次	false	继续——可能只是随口一说
少于 2 次	true	继续——有信号但缺少依据
至少 2 次	true	退出循环

---

上下文效率

资源	预算	策略
主上下文	窗口的 40-60%	保持专注；将繁重工作委派出去
读取子 Agent	最多 500 个并行	搜索、读取文件、匹配模式
构建子 Agent	一次 1 个	实现、执行测试
Token 格式	Markdown 优于 JSON	效率约高 30%

---

引导机制

上游引导（塑造输入）

机制	目的
开始时约 5,000 个 Token 用于详细规范	将规范上下文前置
每次迭代使用相同文件	确保上下文加载具有确定性
以现有代码模式为指南	生成一致的代码

下游引导（验证门槛）

门槛	可发现的问题
测试	无效实现
构建	编译错误
代码检查器	风格不一致
类型检查器	契约违规
LLM-as-judge	主观质量问题

---

状态持久化

各次迭代之间唯一持久化的状态是文件系统：

文件	用途	管理方
IMPLEMENTATION_PLAN.md	任务列表和进度	Planning 和 Building 模式
specs/*.md	规范文件	spec-writing 技能
AGENTS.md	操作说明和经验总结	Building 模式
源代码 + 测试	实际实现	Building 模式

IMPLEMENTATION_PLAN.md 可以丢弃——随时可以通过运行一次 Planning 迭代，从规范中重新生成。

---

反模式 / 常见错误

反模式	失败原因	正确做法
每次迭代处理多个任务	上下文切换，进度不明确	每个循环只处理一个任务
假设代码不存在	代码可能存在于别处，导致重复实现	始终先搜索
实现后跳过测试	Bug 不断累积，缺少反馈压力	立即运行测试
只在 Planning 期间修改计划	计划与实际情况脱节	在 Planning 和 Building 期间都更新
保留过时计划	任务基于过时假设	及时重新生成——规划成本很低
手动管理上下文	主上下文溢出	信任子 Agent 委派
未满足双重条件就退出	提前退出，工作未完成	两个条件都必须满足
每个任务完成后不提交	变更集过大，难以回退	每次迭代都提交
占位符或桩代码	不完整的实现不断累积	只编写达到生产质量的代码
跳过 STATUS CHECK	未评估是否退出，循环会永远运行	每次迭代都以状态检查结束

---

防合理化措施

双重条件门槛通过前，切勿退出循环。每次迭代切勿实现多个任务。切勿编写占位符或桩代码。切勿跳过 STATUS CHECK。

如果你发现自己在想：

• “我可以在这次迭代里快速完成两个任务……”——不行。每个循环只处理一个任务。
• “计划大概没问题，可以跳过 Planning 模式……”——先核实。计划会偏离实际情况。
• “测试可以等到下一次迭代再跑……”——现在就运行测试。反馈压力至关重要。
• “所有事情都做完了，可以退出……”——检查双重条件门槛。两个条件都必须满足。

---

子 Agent 调度机会

任务模式	调度到	时机
跨代码库读取独立文件	Agent 工具，使用 subagent_type="Explore"	循环迭代需要从多个区域获取上下文时
构建阶段执行测试	Bash 工具，设置 run_in_background=true	测试可以在不阻碍进度的情况下验证工作时
迭代间代码审查	Agent 工具，调度 code-reviewer Agent	完成一次 Building 迭代后、下一次 Planning 前

调度时遵循 dispatching-parallel-agents 技能协议。

---

集成点

技能	关系	时机
ralph-status	每次迭代——生成状态块	第 3 阶段：STATUS CHECK
circuit-breaker	安全网——监控循环健康状况	停滞时停止
spec-writing	上游——创建 Planning 所用的规范	循环开始前
acceptance-testing	验证——验证行为结果	Building 模式期间
resilient-execution	每项任务——失败时重试	任务实现失败时
task-management	跟踪——跟踪单个任务	各次迭代中
llm-as-judge	质量——评估主观标准	下游引导
verification-before-completion	最终门槛——核实完成声明	EXIT_SIGNAL: true 之前

---

具体示例

示例：Planning 模式输出

IMPLEMENTATION_PLAN.md:
- [x] Set up project structure
- [x] Implement core data types
- [ ] Implement user authentication (P0 — blocks 3 other tasks)
- [ ] Add API rate limiting (P1)
- [ ] Implement webhook handlers (P1)
- [ ] Add monitoring and logging (P2)

Missing specs: Rate limiting spec needs error response format defined.

示例：Building 模式迭代

Task selected: Implement user authentication
Searched: Found existing password hashing in src/lib/crypto.ts
Implemented: src/auth/service.ts, src/auth/middleware.ts
Tests: 8 passing, 0 failing
Committed: feat(auth): implement JWT-based user authentication

Updated IMPLEMENTATION_PLAN.md:
- [x] Implement user authentication

示例：状态块

---RALPH_STATUS---
STATUS: IN_PROGRESS
TASKS_COMPLETED_THIS_LOOP: 1
FILES_MODIFIED: 4
TESTS_STATUS: PASSING
WORK_TYPE: IMPLEMENTATION
EXIT_SIGNAL: false
RECOMMENDATION: Next: implement API rate limiting (P1)
---END_RALPH_STATUS---

---

技能类型

RIGID — 严格遵循此流程。循环的确定性取决于执行的一致性。每次循环只处理一项任务。每次迭代都要输出状态块。退出门槛需同时满足两个条件。无一例外。