autonomous-loop

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Autonomous Loop

自主循环

Overview

概述

The autonomous loop implements Ralph's iterative development methodology. Each iteration loads identical context (PROMPT + AGENTS files), executes one focused task, reports structured status, and persists state to disk for the next iteration. The loop continues until the dual-condition exit gate is satisfied. The core innovation is that deterministic conditions allow Claude to autonomously plan, build, and iterate toward quality without human intervention in the loop.
Announce at start: "I'm starting the autonomous loop. Loading context and beginning PLANNING mode."
自主循环实现了Ralph迭代开发方法论。每次迭代会加载完全相同的上下文(PROMPT + AGENTS文件),执行一项聚焦的任务,上报结构化状态,并将状态持久化到磁盘供下一次迭代使用。循环会持续运行,直到满足双条件退出闸门要求。其核心创新点在于,确定性的运行规则使得Claude可以在循环全程无需人工干预的情况下,自主完成规划、构建和迭代,最终交付高质量成果。
启动时需声明: "我将启动自主循环,正在加载上下文并进入规划模式。"

Trigger Conditions

触发条件

  • /ralph
    or
    /loop
    command invoked
  • Project has specs and is ready for iterative autonomous development
  • Multi-task implementation that benefits from autonomous iteration
  • User requests autonomous execution without per-task approval

  • 调用了
    /ralph
    /loop
    命令
  • 项目已完成需求规范编写,可启动自主迭代开发
  • 多任务实现场景,可通过自主迭代提升效率
  • 用户要求无需逐任务审批的自主执行模式

Architecture

架构

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

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

Phase 1: PLANNING MODE (Gap Analysis)

第一阶段:规划模式(差距分析)

Goal: Analyze specs against implementation to identify and prioritize remaining work.
<HARD-GATE> Planning mode produces NO implementation code. It is analysis and planning ONLY. </HARD-GATE>
目标: 对比需求规范与现有实现,识别并排定剩余工作的优先级。
<HARD-GATE> 规划模式不产出任何实现代码,仅用于分析和制定计划。 </HARD-GATE>

Steps

执行步骤

  1. Knowledge Gathering — Deploy up to 250 parallel subagents via the
    Agent
    tool (with
    subagent_type="Explore"
    and
    model="sonnet"
    ) to study specs, existing implementation plans, and utility libraries
  2. Code Analysis — Deploy up to 500 parallel subagents via the
    Agent
    tool (with
    subagent_type="Explore"
    ) to study
    src/*
    against
    specs/*
    , identifying gaps between specification and implementation
  3. Synthesis — Deploy a synthesis subagent via the
    Agent
    tool (with
    model="opus"
    ) to synthesize findings and prioritize incomplete work
  4. Plan Refresh — Update
    IMPLEMENTATION_PLAN.md
    as organized, prioritized bullet list
  1. 信息收集 — 通过
    Agent
    工具部署最多250个并行子代理(参数为
    subagent_type="Explore"
    model="sonnet"
    ),梳理需求规范、现有实现计划和工具库
  2. 代码分析 — 通过
    Agent
    工具部署最多500个并行子代理(参数为
    subagent_type="Explore"
    ),对比
    src/*
    specs/*
    的差异,识别需求与实现之间的缺口
  3. 结果汇总 — 通过
    Agent
    工具部署汇总子代理(参数为
    model="opus"
    ),整合分析结果并排定未完成工作的优先级
  4. 计划更新 — 将
    IMPLEMENTATION_PLAN.md
    更新为结构化、按优先级排序的任务列表

Planning Mode Constraints

规划模式约束

ConstraintRationale
Verify ALL assumptions through code searchNever assume something is absent
Treat
src/lib
as authoritative standard library
Consolidate, do not duplicate
Output is a prioritized task listNot code, not designs — tasks only
Identify missing specsSpecs gaps are blockers, not things to guess about
约束设计逻辑
通过代码搜索验证所有假设永远不要默认某功能不存在
src/lib
视为权威标准库
做能力聚合,不要重复实现
输出仅为按优先级排序的任务列表不包含代码、设计内容,仅输出任务
识别缺失的需求规范需求缺口是阻塞项,不可自行猜测补全

Planning Mode Output

规划模式输出

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"]
STOP — Do NOT proceed to Phase 2 until:
  • All specs have been read and analyzed
  • Code has been compared against specs
  • IMPLEMENTATION_PLAN.md is updated with prioritized tasks
  • Missing specs are identified (if any)

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"]
暂停 — 满足以下条件前不得进入第二阶段:
  • 所有需求规范已阅读并分析完成
  • 代码已与需求规范完成比对
  • IMPLEMENTATION_PLAN.md
    已更新为按优先级排序的任务列表
  • 已识别所有缺失的需求规范(如有)

Phase 2: BUILDING MODE (Implementation)

第二阶段:构建模式(实现)

Goal: Select and complete exactly ONE task per iteration.
目标: 每次迭代仅选择并完成一项任务。

"ONE Task Per Loop" Principle

"单次循环一项任务"原则

Each iteration selects and completes exactly one task from IMPLEMENTATION_PLAN.md. This reduces context switching, enables clear progress measurement, and makes debugging easier.
每次迭代仅从
IMPLEMENTATION_PLAN.md
中选择并完成一项任务,可减少上下文切换、实现清晰的进度度量,同时降低调试难度。

Steps

执行步骤

  1. Study — Read specs and current IMPLEMENTATION_PLAN.md
  2. Select — Choose the most important remaining task
  3. Search — Find existing code patterns (do NOT assume implementations are missing)
  4. Implement — Write complete, production-quality code (no placeholders, no stubs)
  5. Test — Run tests immediately after implementation
  6. Update — Refresh IMPLEMENTATION_PLAN.md with findings and progress
  7. Commit — Descriptive conventional commit message with rationale
  1. 梳理信息 — 阅读需求规范和当前的
    IMPLEMENTATION_PLAN.md
  2. 选择任务 — 选取优先级最高的剩余任务
  3. 代码检索 — 查找现有代码模式(不要默认某功能尚未实现)
  4. 功能实现 — 编写完整的生产级代码(无占位符、无存根)
  5. 测试验证 — 实现完成后立即运行测试
  6. 计划更新 — 同步更新
    IMPLEMENTATION_PLAN.md
    的进度和发现的问题
  7. 代码提交 — 编写包含设计逻辑的约定式提交说明

Task Selection Decision Table

任务选择决策表

ConditionWhich Task to Select
Blocker exists for other tasksSelect the blocker task
Test failures existSelect task that fixes the failure
All tasks independentSelect highest priority task
Multiple tasks at same prioritySelect the one with clearest spec
Spec is missing for top taskRun PLANNING mode to identify gap
条件应选择的任务
存在阻塞其他任务的依赖项选择阻塞项对应的任务
存在测试失败用例选择修复失败用例的任务
所有任务相互独立选择优先级最高的任务
多个任务优先级相同选择需求规范最清晰的任务
最高优先级任务缺失需求规范返回规划模式识别缺口

Subagent Rules During Building

构建阶段子代理规则

ResourceBudgetRationale
Read/search subagentsUp to 500 parallel SonnetFast context gathering
Build subagentOnly 1 Sonnet at a timeSerialize builds to detect failures
Main context40-60% utilizationThe "smart zone" — enough room to think
资源预算设计逻辑
读/检索子代理最多500个并行Sonnet实例快速完成上下文收集
构建子代理同一时间仅运行1个Sonnet实例串行化构建流程,便于快速发现失败
主上下文利用率保持40-60%"智能区间" — 预留足够的思考空间

Building Mode Constraints

构建模式约束

ConstraintRationale
No placeholders or stubsEvery line of code is production-quality
Search before implementingCode may already exist elsewhere
Run tests immediatelyBackpressure catches errors early
Update plan after every taskKeep plan current with reality
Commit after every taskSmall atomic commits, easy to revert
STOP — Do NOT proceed to Phase 3 until:
  • Task is fully implemented (no stubs)
  • Tests have been run
  • IMPLEMENTATION_PLAN.md is updated
  • Changes are committed

约束设计逻辑
不允许占位符或存根代码每行代码都要达到生产级质量
实现前先做代码检索所需能力可能已在其他位置实现
立即运行测试通过背压机制尽早发现错误
每项任务完成后都更新计划保持计划与实际进度同步
每项任务完成后都提交代码原子化的小提交,便于回滚
暂停 — 满足以下条件前不得进入第三阶段:
  • 任务已完全实现(无存根)
  • 已运行测试
  • IMPLEMENTATION_PLAN.md
    已更新
  • 变更已提交

Phase 3: STATUS CHECK

第三阶段:状态检查

Goal: Produce a RALPH_STATUS block and evaluate exit conditions.
After each BUILD iteration, invoke the
ralph-status
skill to produce a structured status block.
目标: 生成RALPH_STATUS块并评估退出条件。
每次构建迭代完成后,调用
ralph-status
skill生成结构化状态块。

Exit Evaluation

退出评估

CheckConditionResult
Tasks remaining?IMPLEMENTATION_PLAN.md has unchecked itemsContinue loop
Tests passing?Full test suite passesRequired for exit
Errors in iteration?Clean execution, no unresolved exceptionsRequired for exit
Meaningful work remains?No TODOs, no incomplete featuresRequired for exit
检查项判定条件结果
是否有剩余任务?
IMPLEMENTATION_PLAN.md
存在未勾选项
继续循环
测试是否通过?全量测试集运行通过退出必要条件
迭代是否存在错误?执行过程干净,无未解决异常退出必要条件
是否仍有有效工作待完成?无TODO项、无未完成功能退出必要条件

Loop Decision

循环决策表

StatusTasks RemainingTestsAction
IN_PROGRESSYesAnyLoop back to Phase 1 or 2
IN_PROGRESSNoFAILINGLoop — fix failures first
BLOCKEDAnyAnyReport blocker, wait for input
COMPLETENoPASSINGEvaluate exit gate

状态剩余任务测试结果执行动作
进行中任意回到第一或第二阶段继续循环
进行中失败继续循环 — 优先修复测试失败问题
阻塞任意任意上报阻塞问题,等待输入
已完成通过进入退出闸门评估

Exit Conditions — Dual-Condition Gate

退出条件 — 双条件闸门

<HARD-GATE> Both conditions must be true simultaneously to exit the loop: </HARD-GATE>
ConditionThresholdVerification
Completion indicators>= 2 recent occurrences of "done" languageHeuristic detection in output
Explicit EXIT_SIGNAL
EXIT_SIGNAL: true
in status block
Intentional declaration
<HARD-GATE> 必须同时满足两个条件才可退出循环: </HARD-GATE>
条件阈值验证方式
完成标识最近输出中出现≥2次"完成"类表述输出内容启发式检测
显式退出信号状态块中存在
EXIT_SIGNAL: true
主动声明

EXIT_SIGNAL May Only Be
true
When ALL Of:

仅当满足以下所有条件时,
EXIT_SIGNAL
才可设为
true

  • IMPLEMENTATION_PLAN.md has no remaining tasks
  • All tests pass
  • No errors in latest iteration
  • No meaningful work remains
This prevents false positives where completion language appears while productive work continues.
  • IMPLEMENTATION_PLAN.md
    无剩余任务
  • 所有测试运行通过
  • 最近一次迭代无错误
  • 无有效工作待完成
该规则可避免出现输出中出现完成类表述、但实际仍有可推进工作的误判情况。

Exit Decision Table

退出决策表

Completion LanguageEXIT_SIGNALAction
< 2 occurrencesfalseContinue loop
>= 2 occurrencesfalseContinue — may be casual language
< 2 occurrencestrueContinue — signal without evidence
>= 2 occurrencestrueEXIT the loop

完成类表述EXIT_SIGNAL执行动作
出现次数 < 2次false继续循环
出现次数 ≥ 2次false继续循环 — 可能为随意表述
出现次数 < 2次true继续循环 — 仅有信号无实质证据
出现次数 ≥ 2次true退出循环

Context Efficiency

上下文效率优化

ResourceBudgetStrategy
Main context40-60% of windowKeep focused; delegate heavy lifting
Read subagentsUp to 500 parallelSearching, file reading, pattern matching
Build subagents1 at a timeImplementation, test execution
Token formatMarkdown over JSON~30% more efficient

资源预算优化策略
主上下文窗口的40-60%保持内容聚焦, heavy lifting类工作委派给子代理
读操作子代理最多500个并行执行搜索、文件读取、模式匹配类工作
构建子代理每次1个执行实现、测试运行类工作
Token格式优先使用Markdown而非JSON效率提升约30%

Steering Mechanisms

管控机制

Upstream Steering (Shaping Inputs)

上游管控(输入塑形)

MechanismPurpose
First ~5,000 tokens for detailed specsFront-load specification context
Identical files each iterationDeterministic context loading
Existing code patterns as guidesGenerate consistent code
机制用途
前约5000个Token用于存储详细需求规范前置加载需求上下文
每次迭代加载完全相同的文件实现确定性上下文加载
以现有代码模式为参考生成风格统一的代码

Downstream Steering (Validation Gates)

下游管控(校验闸门)

GateWhat It Catches
TestsInvalid implementations
BuildsCompilation errors
LintersStyle inconsistencies
TypecheckersContract violations
LLM-as-judgeSubjective quality issues

闸门拦截问题类型
测试无效实现
构建编译错误
Lint检查风格不一致
类型检查契约违反
LLM-as-judge主观质量问题

State Persistence

状态持久化

The only persistent state between iterations is the file system:
FilePurposeManaged By
IMPLEMENTATION_PLAN.md
Task list and progressPlanning and Building modes
specs/*.md
Specification files
spec-writing
skill
AGENTS.md
Operational notes and learningsBuilding mode
Source code + testsThe actual implementationBuilding mode
IMPLEMENTATION_PLAN.md is disposable — it can be regenerated from specs at any time by running a planning iteration.

迭代之间唯一的持久化状态存储是文件系统:
文件用途管理方
IMPLEMENTATION_PLAN.md
任务列表与进度规划与构建模式
specs/*.md
需求规范文件
spec-writing
skill
AGENTS.md
运行说明与经验沉淀构建模式
源代码 + 测试实际实现产物构建模式
IMPLEMENTATION_PLAN.md
可随时重构
— 任意时间运行规划迭代,都可以基于需求规范重新生成该文件。

Anti-Patterns / Common Mistakes

反模式 / 常见错误

Anti-PatternWhy It FailsCorrect Approach
Multiple tasks per iterationContext switching, unclear progressONE task per loop
Assuming code is missingMay exist elsewhere, leads to duplicationAlways search first
Skipping tests after implementationBugs accumulate, no backpressureRun tests IMMEDIATELY
Modifying plan only during planningPlan drifts from realityUpdate during BOTH planning and building
Keeping stale plansTasks based on outdated assumptionsRegenerate liberally — planning is cheap
Manual context managementMain context overflowsTrust subagent delegation
Exiting without dual-conditionPremature exit, work incompleteBoth conditions must be true
Not committing after each taskLarge changesets, hard to revertCommit every iteration
Placeholder or stub codeIncomplete implementations accumulateProduction-quality code only
Skipping STATUS CHECKNo exit evaluation, loop runs foreverEvery iteration ends with status

反模式失败原因正确做法
单次迭代完成多项任务上下文切换频繁,进度不清晰单次循环仅完成1项任务
默认代码缺失可能已在其他位置存在,导致重复实现始终先做代码检索
实现后跳过测试Bug累积,无背压约束立即运行测试
仅在规划阶段修改计划计划与实际进度脱节规划和构建阶段都要更新计划
保留过时的计划任务基于过时的假设制定可灵活重构计划 — 规划成本很低
手动管理上下文主上下文溢出信任子代理委派机制
未满足双条件就退出提前退出,工作未完成必须同时满足两个条件
每项任务完成后不提交变更集过大,难以回滚每次迭代都提交代码
编写占位符或存根代码不完整实现累积仅编写生产级质量代码
跳过状态检查无退出评估,循环永久运行每次迭代都以状态检查收尾

Anti-Rationalization Guards

反合理化防护

<HARD-GATE> Do NOT exit the loop without the dual-condition gate passing. Do NOT implement more than one task per iteration. Do NOT write placeholder or stub code. Do NOT skip the STATUS CHECK. </HARD-GATE>
If you catch yourself thinking:
  • "I can do two quick tasks in this iteration..." — No. ONE task per loop.
  • "The plan is probably fine, skip planning mode..." — Verify. Plans drift.
  • "Tests can wait until the next iteration..." — Run tests NOW. Backpressure is essential.
  • "Everything is done, I can exit..." — Check the dual-condition gate. Both must be true.

<HARD-GATE> 未通过双条件闸门不得退出循环;单次迭代不得实现超过1项任务;不得编写占位符或存根代码;不得跳过状态检查。 </HARD-GATE>
如果你出现以下想法:
  • "这次迭代我可以快速完成两个小任务..." — 不行,单次循环仅完成1项任务。
  • "计划应该没问题,跳过规划模式吧..." — 先验证,计划会与实际脱节。
  • "测试可以等下次迭代再跑..." — 现在就跑测试,背压机制至关重要。
  • "所有工作都做完了,我可以直接退出..." — 检查双条件闸门,必须同时满足两个条件。

Subagent Dispatch Opportunities

子代理分派场景

Task PatternDispatch ToWhen
Independent file reads across codebase
Agent
tool with
subagent_type="Explore"
When loop iteration needs context from multiple areas
Test execution during build phase
Bash
tool with
run_in_background=true
When tests can validate work without blocking progress
Code review between iterations
Agent
tool dispatching
code-reviewer
agent
After completing a build iteration, before next planning
Follow the
dispatching-parallel-agents
skill protocol when dispatching.

任务模式分派目标触发时机
跨代码库的独立文件读取配置
subagent_type="Explore"
Agent
工具
循环迭代需要多个领域的上下文时
构建阶段的测试执行配置
run_in_background=true
Bash
工具
测试可验证成果、且不会阻塞进度时
迭代间的代码评审派发
code-reviewer
代理的
Agent
工具
构建迭代完成后、下一次规划开始前
分派子代理时需遵循
dispatching-parallel-agents
skill协议。

Integration Points

集成点

SkillRelationshipWhen
ralph-status
Per-iteration — produces status blocksPhase 3: STATUS CHECK
circuit-breaker
Safety net — monitors loop healthHalts on stagnation
spec-writing
Upstream — creates specs consumed by planningBefore loop starts
acceptance-testing
Validation — validates behavioral outcomesDuring building mode
resilient-execution
Per-task — retry on failureWhen task implementation fails
task-management
Tracking — tracks individual tasksWithin iterations
llm-as-judge
Quality — evaluates subjective criteriaDownstream steering
verification-before-completion
Final gate — verifies completion claimBefore EXIT_SIGNAL: true

Skill关系触发时机
ralph-status
迭代级依赖 — 生成状态块第三阶段:状态检查
circuit-breaker
安全网 — 监控循环健康度运行停滞时终止循环
spec-writing
上游依赖 — 生成规划阶段使用的需求规范循环启动前
acceptance-testing
校验依赖 — 验证行为结果构建模式运行期间
resilient-execution
任务级依赖 — 失败时重试任务实现失败时
task-management
跟踪依赖 — 跟踪单任务进度迭代运行期间
llm-as-judge
质量依赖 — 评估主观标准下游管控环节
verification-before-completion
最终闸门 — 验证完成声明设置
EXIT_SIGNAL: true

Concrete Examples

具体示例

Example: Planning Mode Output

示例:规划模式输出

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

Example: Building Mode Iteration

示例:构建模式迭代

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

Example: Status Block

示例:状态块

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

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

Skill Type

Skill类型

RIGID — Follow this process exactly. The determinism of the loop depends on consistent execution. ONE task per loop. Status block every iteration. Dual-condition exit gate. No exceptions.
刚性(RIGID) — 严格遵循本流程执行。循环的确定性依赖于一致的执行逻辑:单次循环仅完成1项任务、每次迭代都生成状态块、双条件退出闸门,无任何例外。",