ralph（自主循环 agent）
Ralph 是一个自主 AI agent 循环：bash 脚本反复启动全新上下文的 Amp/Claude Code 实例，每轮只实现 PRD 中的一条用户故事，状态通过 prd.json、progress.txt 和 git 历史在迭代间持久化，直到全部故事 passes:true 自动完成整个功能开发。
仓库：snarktank/ralph
热度证据：21,458 star,自主执行类技能代表
五维评分
热度5/5
质量4/5
创新4/5
易用4/5
文档5/5
优秀点拆解
- 文件系统状态机：每轮全新上下文实例，记忆全部外置到 prd.json（passes 状态）+ progress.txt（学习日志）+ git 历史，破解上下文窗口天花板，支持几十轮无人值守运行
- 哨兵完成协议：agent 完成全部任务时输出 <promise>COMPLETE</promise> 标记，ralph.sh 用 grep 精确判定退出，编排器与 LLM 可靠握手，杜绝假完成
- 经验沉降双通道：progress.txt 只追加日志且可复用模式置顶汇总到 Codebase Patterns 区，同时把发现的模式写回 AGENTS.md，后见之明自动变成未来迭代与人类开发者的前见
- 验收标准纪律前置：每条故事强制可验证的验收标准（Typecheck passes 兜底、UI 故事必须浏览器验证、2-3 句话讲不清就算太大），质量门禁在任务定义层生效，防止逐轮劣化
- 双 skill 流水线 + marketplace 分发：prd skill（澄清问题生成 PRD）→ ralph skill（转 prd.json）→ ralph.sh（执行）三段闭环，打包为 Claude Code marketplace 一键安装，产品化完整
可复用的设计模式
- 无状态 agent + 有状态文件：每次迭代全新实例，任务清单/学习日志/提交历史全部用文件承载（Stateless agent, stateful files）
- 哨兵标记完成协议：让 agent 输出独特标记（如 <promise>COMPLETE</promise>），编排脚本 grep 它决定循环退出
- 置顶汇总的学习日志：append-only 日志 + 文件顶部放高频模式总结区，每次新迭代必读顶部，知识只增不覆盖
- 任务定义层内建质量门禁：为每条任务预置可验证验收标准模板，把「什么算完成」在开工前钉死
适用场景
无人值守的增量功能开发：挂上 prd.json 后自动跑完加字段、加组件、改逻辑等一串小故事把大功能拆成依赖有序的小任务分批自动交付（schema → backend → UI）演示/教学「agent 自主交付」流程（自带交互式 flowchart 讲解）已有 typecheck/test/CI 反馈环的工程中做自主编码跑批
边界与注意：故事必须小到能在一个上下文窗口内完成，超出即产出劣质代码；没有自动化质量检查的仓库会逐轮劣化；全自动运行依赖 --dangerously-skip-permissions/--dangerously-allow-all 危险权限，且强依赖 git、jq、Amp/Claude Code 前置环境。
完整拆解分析文档
本页为摘要版，完整精读分析（核心机制、逐条优秀点拆解、写作过程）见本地 Markdown 文档：
analysis/community-ralph.md