autonomous-loop
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseAutonomous 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
触发条件
- or
/ralphcommand invoked/loop - 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
执行步骤
- Knowledge Gathering — Deploy up to 250 parallel subagents via the tool (with
Agentandsubagent_type="Explore") to study specs, existing implementation plans, and utility librariesmodel="sonnet" - Code Analysis — Deploy up to 500 parallel subagents via the tool (with
Agent) to studysubagent_type="Explore"againstsrc/*, identifying gaps between specification and implementationspecs/* - Synthesis — Deploy a synthesis subagent via the tool (with
Agent) to synthesize findings and prioritize incomplete workmodel="opus" - Plan Refresh — Update as organized, prioritized bullet list
IMPLEMENTATION_PLAN.md
- 信息收集 — 通过工具部署最多250个并行子代理(参数为
Agent、subagent_type="Explore"),梳理需求规范、现有实现计划和工具库model="sonnet" - 代码分析 — 通过工具部署最多500个并行子代理(参数为
Agent),对比subagent_type="Explore"与src/*的差异,识别需求与实现之间的缺口specs/* - 结果汇总 — 通过工具部署汇总子代理(参数为
Agent),整合分析结果并排定未完成工作的优先级model="opus" - 计划更新 — 将更新为结构化、按优先级排序的任务列表
IMPLEMENTATION_PLAN.md
Planning Mode Constraints
规划模式约束
| Constraint | Rationale |
|---|---|
| Verify ALL assumptions through code search | Never assume something is absent |
Treat | Consolidate, do not duplicate |
| Output is a prioritized task list | Not code, not designs — tasks only |
| Identify missing specs | Specs gaps are blockers, not things to guess about |
| 约束 | 设计逻辑 |
|---|---|
| 通过代码搜索验证所有假设 | 永远不要默认某功能不存在 |
将 | 做能力聚合,不要重复实现 |
| 输出仅为按优先级排序的任务列表 | 不包含代码、设计内容,仅输出任务 |
| 识别缺失的需求规范 | 需求缺口是阻塞项,不可自行猜测补全 |
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.mdSteps
执行步骤
- Study — Read specs and current IMPLEMENTATION_PLAN.md
- Select — Choose the most important remaining task
- Search — Find existing code patterns (do NOT assume implementations are missing)
- Implement — Write complete, production-quality code (no placeholders, no stubs)
- Test — Run tests immediately after implementation
- Update — Refresh IMPLEMENTATION_PLAN.md with findings and progress
- Commit — Descriptive conventional commit message with rationale
- 梳理信息 — 阅读需求规范和当前的
IMPLEMENTATION_PLAN.md - 选择任务 — 选取优先级最高的剩余任务
- 代码检索 — 查找现有代码模式(不要默认某功能尚未实现)
- 功能实现 — 编写完整的生产级代码(无占位符、无存根)
- 测试验证 — 实现完成后立即运行测试
- 计划更新 — 同步更新的进度和发现的问题
IMPLEMENTATION_PLAN.md - 代码提交 — 编写包含设计逻辑的约定式提交说明
Task Selection Decision Table
任务选择决策表
| Condition | Which Task to Select |
|---|---|
| Blocker exists for other tasks | Select the blocker task |
| Test failures exist | Select task that fixes the failure |
| All tasks independent | Select highest priority task |
| Multiple tasks at same priority | Select the one with clearest spec |
| Spec is missing for top task | Run PLANNING mode to identify gap |
| 条件 | 应选择的任务 |
|---|---|
| 存在阻塞其他任务的依赖项 | 选择阻塞项对应的任务 |
| 存在测试失败用例 | 选择修复失败用例的任务 |
| 所有任务相互独立 | 选择优先级最高的任务 |
| 多个任务优先级相同 | 选择需求规范最清晰的任务 |
| 最高优先级任务缺失需求规范 | 返回规划模式识别缺口 |
Subagent Rules During Building
构建阶段子代理规则
| Resource | Budget | Rationale |
|---|---|---|
| Read/search subagents | Up to 500 parallel Sonnet | Fast context gathering |
| Build subagent | Only 1 Sonnet at a time | Serialize builds to detect failures |
| Main context | 40-60% utilization | The "smart zone" — enough room to think |
| 资源 | 预算 | 设计逻辑 |
|---|---|---|
| 读/检索子代理 | 最多500个并行Sonnet实例 | 快速完成上下文收集 |
| 构建子代理 | 同一时间仅运行1个Sonnet实例 | 串行化构建流程,便于快速发现失败 |
| 主上下文 | 利用率保持40-60% | "智能区间" — 预留足够的思考空间 |
Building Mode Constraints
构建模式约束
| Constraint | Rationale |
|---|---|
| No placeholders or stubs | Every line of code is production-quality |
| Search before implementing | Code may already exist elsewhere |
| Run tests immediately | Backpressure catches errors early |
| Update plan after every task | Keep plan current with reality |
| Commit after every task | Small 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 skill to produce a structured status block.
ralph-status目标: 生成RALPH_STATUS块并评估退出条件。
每次构建迭代完成后,调用 skill生成结构化状态块。
ralph-statusExit Evaluation
退出评估
| Check | Condition | Result |
|---|---|---|
| Tasks remaining? | IMPLEMENTATION_PLAN.md has unchecked items | Continue loop |
| Tests passing? | Full test suite passes | Required for exit |
| Errors in iteration? | Clean execution, no unresolved exceptions | Required for exit |
| Meaningful work remains? | No TODOs, no incomplete features | Required for exit |
| 检查项 | 判定条件 | 结果 |
|---|---|---|
| 是否有剩余任务? | | 继续循环 |
| 测试是否通过? | 全量测试集运行通过 | 退出必要条件 |
| 迭代是否存在错误? | 执行过程干净,无未解决异常 | 退出必要条件 |
| 是否仍有有效工作待完成? | 无TODO项、无未完成功能 | 退出必要条件 |
Loop Decision
循环决策表
| Status | Tasks Remaining | Tests | Action |
|---|---|---|---|
| IN_PROGRESS | Yes | Any | Loop back to Phase 1 or 2 |
| IN_PROGRESS | No | FAILING | Loop — fix failures first |
| BLOCKED | Any | Any | Report blocker, wait for input |
| COMPLETE | No | PASSING | Evaluate exit gate |
| 状态 | 剩余任务 | 测试结果 | 执行动作 |
|---|---|---|---|
| 进行中 | 是 | 任意 | 回到第一或第二阶段继续循环 |
| 进行中 | 否 | 失败 | 继续循环 — 优先修复测试失败问题 |
| 阻塞 | 任意 | 任意 | 上报阻塞问题,等待输入 |
| 已完成 | 否 | 通过 | 进入退出闸门评估 |
Exit Conditions — Dual-Condition Gate
退出条件 — 双条件闸门
<HARD-GATE>
Both conditions must be true simultaneously to exit the loop:
</HARD-GATE>
| Condition | Threshold | Verification |
|---|---|---|
| Completion indicators | >= 2 recent occurrences of "done" language | Heuristic detection in output |
| Explicit EXIT_SIGNAL | | Intentional declaration |
<HARD-GATE>
必须同时满足两个条件才可退出循环:
</HARD-GATE>
| 条件 | 阈值 | 验证方式 |
|---|---|---|
| 完成标识 | 最近输出中出现≥2次"完成"类表述 | 输出内容启发式检测 |
| 显式退出信号 | 状态块中存在 | 主动声明 |
EXIT_SIGNAL May Only Be true
When ALL Of:
true仅当满足以下所有条件时,EXIT_SIGNAL
才可设为true
:
EXIT_SIGNALtrue- 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 Language | EXIT_SIGNAL | Action |
|---|---|---|
| < 2 occurrences | false | Continue loop |
| >= 2 occurrences | false | Continue — may be casual language |
| < 2 occurrences | true | Continue — signal without evidence |
| >= 2 occurrences | true | EXIT the loop |
| 完成类表述 | EXIT_SIGNAL | 执行动作 |
|---|---|---|
| 出现次数 < 2次 | false | 继续循环 |
| 出现次数 ≥ 2次 | false | 继续循环 — 可能为随意表述 |
| 出现次数 < 2次 | true | 继续循环 — 仅有信号无实质证据 |
| 出现次数 ≥ 2次 | true | 退出循环 |
Context Efficiency
上下文效率优化
| Resource | Budget | Strategy |
|---|---|---|
| Main context | 40-60% of window | Keep focused; delegate heavy lifting |
| Read subagents | Up to 500 parallel | Searching, file reading, pattern matching |
| Build subagents | 1 at a time | Implementation, test execution |
| Token format | Markdown over JSON | ~30% more efficient |
| 资源 | 预算 | 优化策略 |
|---|---|---|
| 主上下文 | 窗口的40-60% | 保持内容聚焦, heavy lifting类工作委派给子代理 |
| 读操作子代理 | 最多500个并行 | 执行搜索、文件读取、模式匹配类工作 |
| 构建子代理 | 每次1个 | 执行实现、测试运行类工作 |
| Token格式 | 优先使用Markdown而非JSON | 效率提升约30% |
Steering Mechanisms
管控机制
Upstream Steering (Shaping Inputs)
上游管控(输入塑形)
| Mechanism | Purpose |
|---|---|
| First ~5,000 tokens for detailed specs | Front-load specification context |
| Identical files each iteration | Deterministic context loading |
| Existing code patterns as guides | Generate consistent code |
| 机制 | 用途 |
|---|---|
| 前约5000个Token用于存储详细需求规范 | 前置加载需求上下文 |
| 每次迭代加载完全相同的文件 | 实现确定性上下文加载 |
| 以现有代码模式为参考 | 生成风格统一的代码 |
Downstream Steering (Validation Gates)
下游管控(校验闸门)
| Gate | What It Catches |
|---|---|
| Tests | Invalid implementations |
| Builds | Compilation errors |
| Linters | Style inconsistencies |
| Typecheckers | Contract violations |
| LLM-as-judge | Subjective quality issues |
| 闸门 | 拦截问题类型 |
|---|---|
| 测试 | 无效实现 |
| 构建 | 编译错误 |
| Lint检查 | 风格不一致 |
| 类型检查 | 契约违反 |
| LLM-as-judge | 主观质量问题 |
State Persistence
状态持久化
The only persistent state between iterations is the file system:
| File | Purpose | Managed By |
|---|---|---|
| Task list and progress | Planning and Building modes |
| Specification files | |
| Operational notes and learnings | Building mode |
| Source code + tests | The actual implementation | Building mode |
IMPLEMENTATION_PLAN.md is disposable — it can be regenerated from specs at any time by running a planning iteration.
迭代之间唯一的持久化状态存储是文件系统:
| 文件 | 用途 | 管理方 |
|---|---|---|
| 任务列表与进度 | 规划与构建模式 |
| 需求规范文件 | |
| 运行说明与经验沉淀 | 构建模式 |
| 源代码 + 测试 | 实际实现产物 | 构建模式 |
IMPLEMENTATION_PLAN.mdAnti-Patterns / Common Mistakes
反模式 / 常见错误
| Anti-Pattern | Why It Fails | Correct Approach |
|---|---|---|
| Multiple tasks per iteration | Context switching, unclear progress | ONE task per loop |
| Assuming code is missing | May exist elsewhere, leads to duplication | Always search first |
| Skipping tests after implementation | Bugs accumulate, no backpressure | Run tests IMMEDIATELY |
| Modifying plan only during planning | Plan drifts from reality | Update during BOTH planning and building |
| Keeping stale plans | Tasks based on outdated assumptions | Regenerate liberally — planning is cheap |
| Manual context management | Main context overflows | Trust subagent delegation |
| Exiting without dual-condition | Premature exit, work incomplete | Both conditions must be true |
| Not committing after each task | Large changesets, hard to revert | Commit every iteration |
| Placeholder or stub code | Incomplete implementations accumulate | Production-quality code only |
| Skipping STATUS CHECK | No exit evaluation, loop runs forever | Every 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 Pattern | Dispatch To | When |
|---|---|---|
| Independent file reads across codebase | | When loop iteration needs context from multiple areas |
| Test execution during build phase | | When tests can validate work without blocking progress |
| Code review between iterations | | After completing a build iteration, before next planning |
Follow the skill protocol when dispatching.
dispatching-parallel-agents| 任务模式 | 分派目标 | 触发时机 |
|---|---|---|
| 跨代码库的独立文件读取 | 配置 | 循环迭代需要多个领域的上下文时 |
| 构建阶段的测试执行 | 配置 | 测试可验证成果、且不会阻塞进度时 |
| 迭代间的代码评审 | 派发 | 构建迭代完成后、下一次规划开始前 |
分派子代理时需遵循 skill协议。
dispatching-parallel-agentsIntegration Points
集成点
| Skill | Relationship | When |
|---|---|---|
| Per-iteration — produces status blocks | Phase 3: STATUS CHECK |
| Safety net — monitors loop health | Halts on stagnation |
| Upstream — creates specs consumed by planning | Before loop starts |
| Validation — validates behavioral outcomes | During building mode |
| Per-task — retry on failure | When task implementation fails |
| Tracking — tracks individual tasks | Within iterations |
| Quality — evaluates subjective criteria | Downstream steering |
| Final gate — verifies completion claim | Before EXIT_SIGNAL: true |
| Skill | 关系 | 触发时机 |
|---|---|---|
| 迭代级依赖 — 生成状态块 | 第三阶段:状态检查 |
| 安全网 — 监控循环健康度 | 运行停滞时终止循环 |
| 上游依赖 — 生成规划阶段使用的需求规范 | 循环启动前 |
| 校验依赖 — 验证行为结果 | 构建模式运行期间 |
| 任务级依赖 — 失败时重试 | 任务实现失败时 |
| 跟踪依赖 — 跟踪单任务进度 | 迭代运行期间 |
| 质量依赖 — 评估主观标准 | 下游管控环节 |
| 最终闸门 — 验证完成声明 | 设置 |
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 authenticationTask 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 authenticationExample: 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项任务、每次迭代都生成状态块、双条件退出闸门,无任何例外。",