structure｜1️⃣ 三级笔记、思想框架

Ralph：自主 Agent 循环，直到 PRD 全部完成

核心定义：Ralph 是一个自主 AI Agent 循环框架，反复运行 Amp 实例，直到 PRD（产品需求文档）中的所有 user story 全部完成。每次迭代都是一个全新的 Amp 实例，上下文干干净净。记忆通过 git history、progress.txt 和 prd.json 持久化。

基于 Geoffrey Huntley 的 Ralph 模式。

一、工作流程（三步走）

• Step 1：创建 PRD
  • 用 PRD skill 生成详细需求文档
  • 回答 clarifying questions，输出保存为 tasks/prd-[feature-name].md
• Step 2：PRD 转 Ralph 格式
  • 用 Ralph skill 将 markdown PRD 转换为 JSON（prd.json）
  • JSON 中的 user stories 结构化，为自主执行而设计
• Step 3：运行 Ralph 循环
  • 执行 ./scripts/ralph/ralph.sh [max_iterations]（默认 10 轮）
  • 每轮循环做什么：
    1. 创建 feature branch
    2. 挑选最高优先级、passes: false 的 story
    3. 实现这一个 story
    4. 跑质量检查（typecheck + tests）
    5. 检查通过 → commit
    6. 更新 prd.json，标记 passes: true
    7. 把学到的东西追加写入 progress.txt
    8. 重复，直到全部 story 完成或达到最大迭代次数

二、关键文件

• ralph.sh：bash 循环脚本，每轮生成新的 Amp 实例
• prompt.md：给每个 Amp 实例的指令
• prd.json：user stories + passes 状态（任务清单）
• progress.txt：append-only 的学习记录，供后续迭代使用
• skills/prd/：生成 PRD 的 skill
• skills/ralph/：将 PRD 转 JSON 的 skill

三、核心设计理念（Critical Concepts）

• 每轮迭代 = 全新上下文（Fresh Context）
  • 每轮都启动一个全新的 Amp 实例，context 是干净的
  • 迭代之间的唯一记忆：git history + progress.txt + prd.json
  • 这意味着：不依赖长上下文，靠外部持久化传递知识
• 任务必须足够小（Small Tasks）
  • 每个 PRD item 必须小到一个 context window 内能完成
  • 任务太大 → LLM 上下文耗尽 → 产出低质量代码
  • 合适的颗粒度：加一个数据库字段、加一个 UI 组件、更新一个 server action
  • 太大了（需拆分）："搭建整个 dashboard"、"加上认证"、"重构 API"
• **AGENTS.md 更新至关重要**
  • 每轮结束后，Ralph 会更新 AGENTS.md，写入本轮学到的东西
  • Amp 自动读取这些文件 → 后续迭代（和人类开发者）都能受益
  • 写什么：发现的模式、踩过的坑、有用的上下文信息
• 反馈循环（Feedback Loops）是 Ralph 运转的前提
  • Typecheck 捕获类型错误
  • Tests 验证行为正确性
  • CI 必须保持绿色——坏掉的代码会在迭代间复利累积
• 停止条件（Stop Condition）
  • 当所有 story 的 passes 都为 true 时，Ralph 输出 <promise>COMPLETE</promise>，循环退出
• UI 故事需浏览器验证
  • 前端 story 的验收标准必须包含"用 dev-browser skill 在浏览器中验证"

四、设计哲学提炼

• "每轮干净启动 + 外部记忆持久化" 是 Ralph 的核心架构选择——用最简单的方式解决 LLM 上下文有限的问题
• 任务拆分是 Agent 成功的前提——不是 Agent 不行，是你给的任务太大了
• **AGENTS.md 是跨迭代的知识传递机制**——让 Agent 从自己的经验中学习，也让人类受益
• 没有 feedback loop 的 Agent 循环是盲人骑瞎马——typecheck、test、CI 是 Ralph 的眼睛

concepts｜2️⃣ 关键概念、概念网络

一、核心概念解析 (Core Concepts)

• 【Ralph Loop】(Ralph 循环 / 自主 Agent 循环)

  • context：

    Ralph is an autonomous AI agent loop that runs Amp repeatedly until all PRD items are complete. Each iteration is a fresh Amp instance with clean context. Memory persists via git history, progress.txt, and prd.json.

  • 费曼一下：Ralph Loop 是一种让 AI Agent 像流水线工人一样工作的模式：给它一份任务清单（PRD），它就一项一项地做，做完一个勾一个，直到全部完成。每次做新任务时，它的“工作台”是干净的，但它能通过外部文件记住之前的经验教训。核心思想：与其让 Agent 在一个无限增长的上下文里越做越乱，不如每轮重新开始、只传递必要的记忆。基于 Geoffrey Huntley 的原始概念。

• 【Fresh Context】(全新上下文 / 干净启动)

  • context：

    Each iteration spawns a new Amp instance with clean context. The only memory between iterations is: Git history, progress.txt, prd.json.

  • 费曼一下：Fresh Context 是 Ralph 的核心架构决策。每轮迭代都启动一个全新的 LLM 实例，没有前一轮的历史对话。这解决了一个关键问题：LLM 的 context window 有限，工作时间越长、上下文越混乱，输出质量越差。Fresh Context 的代价是必须通过外部文件显式传递记忆，但换来的是每轮都能保持高质量输出。

• 【External Memory Persistence】(外部记忆持久化)

  • context：

    Memory persists via git history, progress.txt, and prd.json. After each iteration, Ralph updates the relevant AGENTS.md files with learnings.

  • 费曼一下：既然每轮都是全新启动，记忆怎么传递？Ralph 用三个外部文件做“记忆体”：prd.json（任务清单，记录哪些做完了）、progress.txt（append-only 的经验日志）、git history（代码变更记录）。这是一种特别简洁的设计——不需要复杂的向量数据库或 RAG，用最原始的文件系统就够了。

• 【Small Tasks】(任务拆分 / 小颗粒度任务)

  • context：

    Each PRD item should be small enough to complete in one context window. If a task is too big, the LLM runs out of context before finishing and produces poor code.

  • 费曼一下：Ralph 能跑起来的前提是：你得把任务拆得足够小。每个 user story 必须小到一个 context window 内能完成。这不是 Ralph 的缺陷，而是当前 LLM Agent 的工作原理决定的——任务太大，上下文耗尽，代码质量就崩了。所以问题往往不是“Agent 不行”，而是“任务太大了”。

• 【Feedback Loops】(反馈循环)

  • context：

    Ralph only works if there are feedback loops: Typecheck catches type errors, Tests verify behavior, CI must stay green (broken code compounds across iterations).

  • 费曼一下：Ralph 每轮做完之后，必须有东西告诉它“做对了没有”，否则就是盲人骑瞎马。Typecheck、单元测试、CI 就是这些反馈信号。没有反馈循环的 Agent 循环是危险的——坏代码会在迭代间复利累积，越滩越大。

• 【AGENTS.md】(跨迭代知识传递文件)
• 【PRD-driven Development】(PRD 驱动开发)

二、概念网络 (Concept Network)

• Ralph Loop 是整个框架的顶层概念，它的核心架构选择是 Fresh Context（每轮干净启动）
• Fresh Context 带来了一个必然问题：记忆怎么传递？答案是 External Memory Persistence（prd.json + progress.txt + git + AGENTS.md）
• Fresh Context 也决定了 Small Tasks 是必要条件——每个任务必须在一个 context window 内完成
• Feedback Loops 是 Ralph Loop 可靠运行的守护者——没有反馈，Agent 就无法知道自己做对了没有
• AGENTS.md 是 External Memory Persistence 的特殊形式——它不只是记录进度，而是累积经验和知识，供后续迭代和人类共同受益
• PRD-driven Development 是 Ralph Loop 的输入规范——PRD 定义了任务边界、优先级和完成标准
• 总结：Ralph Loop = Fresh Context + External Memory + Small Tasks + Feedback Loops + PRD，五者缺一不可

agentic reading｜3️⃣ 费曼 x3