拉尔夫行动手册

2025年12月，拉尔夫 那张强大却略显“傻气”的小脸一下子冲上了大多数与AI相关的时间线的榜首。

我一向很关注@GeoffreyHuntley 分享的那些极其聪明的洞见，但今年夏天拉尔夫并没有真正让我眼前一亮。如今，围绕它的各种热议让我不再能视而不见。

@mattpocockuk 和 @ryancarson 的概述帮了大忙——直到杰夫亲自出马，来了句 “算了吧”。

那么，究竟怎样才是使用拉尔夫的最佳方式呢？

许多人似乎通过不同的方法都取得了不错的效果——但我更想尽可能贴近最初提出这一方法的人，也就是那位不仅捕捉到了这套思路、而且还在实践中反复打磨它的人，来解读其中的奥秘。

于是，我深入研究了最近的视频以及杰夫的原始文章，试图理清到底哪种做法最有效。

以下是我的成果——一份（可能有点强迫症驱动的）拉尔夫行动手册，将各种零散的细节整理成一套可操作的流程，希望能尽量保留其核心价值，而不是在实践过程中将其削弱。

在深入研究的过程中，我还想到一些对核心方法可能有价值的补充改进，这些改进旨在遵循让拉尔夫如此出色运作的指导原则。

[!TIP] 以📖 格式化指南 → 查看

希望这份手册对你有所帮助——@ClaytonFarr

---

目录

• 工作流程
• 关键原则
• 循环机制
• 许可证
• 文件
• 有哪些改进？

---

工作流程

一张图胜过千条推文和一小时的视频。杰夫的这篇概述（订阅他的邮件列表即可查看完整文章）确实帮助我理清了从 1) 创意 → 2) 与JTBD对齐的具体规格 → 3) 全面的实施计划 → 4) 拉尔夫工作循环的详细流程。

🗘 三阶段、两份提示、一个循环

这张图让我明白，拉尔夫不仅仅是一个“会写代码的循环”。它更像是一个包含3个阶段、2份提示和1个循环的漏斗。

第一阶段：明确需求（LLM对话）

• 讨论项目创意，识别待完成的工作（JTBD）
• 将每个JTBD分解为具体的关注主题
• 使用子代理从URL加载信息并纳入上下文
• LLM理解JTBD的关注主题：子代理为每个主题编写 specs/FILENAME.md

第二阶段 / 第三阶段：运行拉尔夫循环（两种模式，根据需要切换 PROMPT.md）

虽然机制相同，但针对不同目标使用不同的提示：

模式	适用场景	提示重点
规划	尚无计划，或计划已过时/错误	仅生成或更新 IMPLEMENTATION_PLAN.md
构建	已有计划	根据计划实施，提交代码，并顺带更新计划

各模式下的提示差异：

• “规划”模式的提示会进行差距分析（规格与代码对比），并输出一个优先级排序的任务清单——不涉及实际实现，也不提交代码。
• “构建”模式的提示则假定已有计划，从中挑选任务，执行实现，运行测试（反压机制），然后提交代码。

为什么两种模式都要用这个循环呢？

• “构建”模式离不开它：因为开发本身就是迭代式的（大量任务 × 新鲜上下文 = 孤立效应）。
• “规划”模式则为了保持一致性：采用相同的执行模型，尽管通常只需1-2轮就能完成。
• 灵活性：如果计划需要调整，循环可以多次读取自身输出。
• 简洁性：一套机制搞定所有事情；文件I/O清晰；随时可以停止或重启。

每次迭代都会加载的上下文： PROMPT.md + AGENTS.md

“规划”模式的循环流程：

1. 子代理研究 specs/* 和现有的 /src
2. 对比规格与代码（差距分析）
3. 创建或更新带有优先级任务的 IMPLEMENTATION_PLAN.md
4. 不进行任何实现

“构建”模式的循环流程：

1. 定位 – 子代理研究 specs/*（需求）
2. 阅读计划 – 研究 IMPLEMENTATION_PLAN.md
3. 选择 – 挑选最重要的任务
4. 调查 – 子代理研究相关的 /src（不要假设未实现）
5. 实现 – 多个子代理负责文件操作
6. 验证 – 1个子代理负责构建和测试（反压机制）
7. 更新 IMPLEMENTATION_PLAN.md – 标记任务已完成，记录发现的问题或新情况
8. 更新 AGENTS.md – 如果有新的操作经验
9. 提交
10. 循环结束 → 清除上下文 → 下一轮从头开始

概念

术语	定义
待完成的工作（JTBD）	用户的高层次需求或期望结果
关注主题	JTBD 中的一个独立的方面或组成部分
规格	针对某一关注主题的需求文档 (specs/FILENAME.md)
任务	由规格与代码对比得出的工作单元

关系：

• 1个JTBD → 多个关注主题
• 1个关注主题 → 1份规格
• 1份规格 → 多个任务（规格往往比任务更宏观）

举例：

• JTBD：“帮助设计师创建情绪板”
• 关注主题：图片收集、色彩提取、布局、分享
• 每个主题对应一个规格文件
• 每份规格又会衍生出许多实施任务

主题范围测试：“一句话不带‘和’”

• 你能用一句话描述这个关注主题，而不把不相关的功能混在一起吗？
  • ✓ “色彩提取系统会分析图片，找出主导颜色”
  • ✗ “用户系统负责身份验证、个人资料和计费” → 这是3个主题
• 如果需要用“和”来描述它的功能，那很可能就是多个主题。

---

关键原则

⏳ 上下文就是一切

• 当广告宣称有 20 万+ 个 token 时，真正可用的却只有约 17.6 万个。
• 而“智能区域”的上下文利用率通常在 40% 到 60% 之间。
• 对于紧凑的任务，每次循环只执行一个任务，就能实现 100% 的智能区域上下文利用率。

这决定了并驱动着其他所有方面：

• 将主代理/上下文用作调度器
  • 不要将昂贵的工作分配给主上下文；尽可能改用子代理来处理。
• 将子代理用作内存扩展
  • 每个子代理拥有约 156KB 的内存空间，并且会进行垃圾回收。
  • 通过分散任务来避免污染主上下文。
• 简单与简洁胜出
  • 这适用于系统中的组件数量、循环配置以及内容本身。
  • 冗长的输入会降低确定性。
• 优先使用 Markdown 而不是 JSON
  • 用于定义和跟踪工作，以提高 token 使用效率。

🧭 引导 Ralph：模式与反压

创造正确的信号和门控机制，以引导 Ralph 产生成功的结果，是至关重要的。你可以从两个方向进行引导：

• 上游引导
  • 确保确定性的设置：
    • 分配前约 5,000 个 token 用于规格说明。
    • 每次循环的上下文都加载相同的文件，使模型从已知状态开始（PROMPT.md + AGENTS.md）。
  • 你现有的代码决定了哪些内容会被使用和生成。
  • 如果 Ralph 生成了错误的模式，就添加或更新工具和现有代码模式，以引导它走向正确的方向。
• 下游引导
  • 通过测试、类型检查、lint 工具、构建等手段创建反压机制，从而拒绝无效或不可接受的工作。
  • 提示中只是笼统地提到“运行测试”。而 AGENTS.md 中则具体指定了实际的命令，使反压机制更具项目针对性。
  • 反压机制不仅限于代码验证：有些验收标准难以通过程序化方式检验——例如创意质量、美学设计、用户体验等。可以利用 LLM 作为“裁判”，对这些主观标准进行二元化的通过/失败判断，从而提供反压。（关于如何用 Ralph 处理此类问题，请参阅下方的【非确定性反压】部分。）
• 提醒 Ralph 创建/使用反压
  • 在实施过程中提醒 Ralph 使用反压：“重要提示：编写文档时，请记录下背后的原因——包括测试及其在实现中的重要性。”

🙏 让 Ralph 做自己擅长的事

Ralph 的有效性取决于你对其最终能够做出正确决策的信任程度，以及你为它创造这种能力所付出的努力。

• 让 Ralph 做自己擅长的事
  • 充分发挥 LLM 自我识别、自我修正和自我改进的能力。
  • 这适用于实施计划、任务定义及优先级排序。
  • 通过迭代逐步实现最终的一致性。
• 采取保护措施
  • 为了实现自主运行，Ralph 需要使用 --dangerously-skip-permissions 参数——如果每次调用工具都要请求批准，循环就会中断。这种方式完全绕过了 Claude 的权限系统，因此沙箱就成了唯一的安全边界。
  • 哲学理念是：“被攻破不是会不会的问题，而是何时会发生。那么破坏范围又有多大呢？”
  • 如果不使用沙箱运行，你的机器上存储的凭据、浏览器 Cookie、SSH 密钥和访问令牌都将面临风险。
  • 应该在隔离的环境中运行，并仅授予最低限度的必要权限：
    • 仅提供完成任务所需的 API 密钥和部署密钥。
    • 不允许访问超出需求范围的任何私密数据。
    • 尽可能限制网络连接。
  • 可选方案包括本地 Docker 沙箱、远程/生产环境中的 Fly Sprites 或 E2B 等。（更多信息请参见参考资料中的【沙箱环境】部分。）
  • 此外，还有一些应急措施：按下 Ctrl+C 可以停止循环；使用 git reset --hard 可以撤销未提交的更改；如果轨迹出现偏差，可以重新生成计划。

🚦 走出循环之外

要想充分发挥 Ralph 的作用，就必须让他自由地工作。Ralph 应该负责完成所有任务，包括决定接下来要实施哪项计划以及如何实施。你的职责不再是参与循环，而是置身其外——搭建合适的环境和条件，帮助 Ralph 取得成功。

• 观察并适时调整——尤其是在初期，静下心来仔细观察。哪些模式逐渐显现？Ralph 哪里出现了问题？它需要什么样的提示？你最初使用的提示很可能不会是你最终使用的提示——它们会随着观察到的失败模式不断演变。
• 像调吉他一样微调——不要一开始就事无巨细地规定好一切，而是通过观察和反应式调整来进行优化。当 Ralph 以某种特定方式失败时，就增加相应的提示，帮助它下次做得更好。

然而，提示并不仅仅局限于文本形式，它可以是 Ralph 能够发现的任何信息：

• 提示中的约束条件——例如明确指示“不要假设尚未实现”。
• AGENTS.md 文件——其中包含关于如何构建和测试的实际经验。
• 你代码库中的实用工具——当你添加一种新模式时，Ralph 会自动发现并遵循它。
• 其他可被发现的相关输入……

[!TIP]

1. 可以先尝试在 AGENTS.md 中什么都不写（即空文件，不含任何最佳实践等内容）。
2. 通过小规模测试来观察期望的行为，并找出其中的不足之处。（参考 Geoff 的操作示例：https://x.com/ClaytonFarr/status/2010780371542241508）
3. 观察最初的几次循环，看看哪些环节存在空白。
4. 仅根据需要，通过更新 AGENTS.md 或修改代码模式（如共享工具等）来调整行为。

记住一点：计划是可以丢弃的：

• 如果计划有问题，就直接抛弃，重新开始。
• 重新生成计划的成本仅相当于一次规划循环，相比 Ralph 陷入无休止的重复要便宜得多。
• 应该在以下情况时重新生成计划：
  • Ralph 的行动偏离了轨道（实施了错误的任务或重复工作）。
  • 计划显得过时或与当前状态不符。
  • 已完成事项过多导致混乱。
  • 你对项目的规格进行了重大调整。
  • 你对自己已经完成的工作感到困惑。

---

循环机制

I. 任务选择

loop.sh 实际上充当了一个“外层循环”，其中每一次循环对应一项独立的任务（在不同的会话中执行）。当一项任务完成后，loop.sh 会启动一个新的会话，以选择下一项任务，前提是仍有未完成的任务存在。

Geoff 最初采用的最简版 loop.sh 脚本如下：

while :; do cat PROMPT.md | claude ; done

注意：同样的方法也可以应用于其他 CLI 工具，例如 amp、codex、opencode 等。

是什么控制着任务的持续进行呢？

其机制非常简单而巧妙：

1. Bash 循环运行 → 将 PROMPT.md 输入给 Claude。
2. PROMPT.md 指示 → “研究 IMPLEMENTATION_PLAN.md 并选择最重要的事情……”
3. 代理完成一项任务 → 更新磁盘上的 IMPLEMENTATION_PLAN.md 文件，提交更改后退出。
4. Bash 循环立即重启 → 新的上下文窗口。
5. 代理读取更新后的计划 → 选择下一项最重要的任务……

关键洞察：IMPLEMENTATION_PLAN.md 文件会在每次迭代之间持久化保存在磁盘上，作为原本相互隔离的循环执行之间的共享状态。每次迭代都会以确定性的方式加载相同的文件（PROMPT.md、AGENTS.md 和 specs/*），并从磁盘上读取当前的状态。

无需复杂的编排系统——只需一个简单的 Bash 循环不断重启代理，而代理每次都会通过读取计划文件来决定下一步该做什么。

II. 任务执行

每个任务都会在反压机制（如测试等）的驱动下持续工作，直到通过为止——从而在一个会话中形成一个伪内部“循环”。

这个内部循环只是模型单次响应内的自我修正与迭代推理过程，由反压提示、工具使用和子代理共同推动。它并非编程意义上的循环。

单个任务的执行没有硬性技术限制。其控制依赖于以下几点：

• 范围约束：PROMPT.md 指示“一次只做一项任务”，并在“测试通过后提交”。
• 反压机制：测试或构建失败会迫使代理先修复问题再进行提交。
• 自然结束：代理在成功提交后退出。

Ralph 可能会陷入循环、忽略指令或走错方向——这是预期的行为，也是调优过程的一部分。当 Ralph 以特定方式失败来“试探你”时，你可以通过调整提示词或优化反压机制来增加约束条件。这种非确定性可以通过观察和迭代逐步管理。

增强版 loop.sh 示例

该脚本封装了核心循环，并增加了模式选择功能（规划/构建），同时设置了最大迭代次数以限制可完成的任务数量，并在每次迭代后执行 Git 推送。

此增强版本使用了两个保存的提示文件：

• PROMPT_plan.md —— 规划模式（差距分析，生成/更新计划）
• PROMPT_build.md —— 构建模式（根据计划实施）

#!/bin/bash
# 使用方法：./loop.sh [plan|build] [max_iterations]
# 示例：
#   ./loop.sh              # 构建模式，无限制任务数
#   ./loop.sh 20           # 构建模式，最多20个任务
#   ./loop.sh build 20     # 构建模式，最多20个任务
#   ./loop.sh plan         # 规划模式，无限制任务数
#   ./loop.sh plan 5       # 规划模式，最多5个任务

# 解析参数
if [ "$1" = "plan" ]; then
    # 规划模式
    MODE="plan"
    PROMPT_FILE="PROMPT_plan.md"
    MAX_ITERATIONS=${2:-0}
elif [ "$1" = "build" ]; then
    # 显式构建模式（可选最大迭代次数）
    MODE="build"
    PROMPT_FILE="PROMPT_build.md"
    MAX_ITERATIONS=${2:-0}
elif [[ "$1" =~ ^[0-9]+$ ]]; then
    # 构建模式，指定最大任务数（仅数字）
    MODE="build"
    PROMPT_FILE="PROMPT_build.md"
    MAX_ITERATIONS=$1
else
    # 默认为构建模式，无限制（无参数或输入无效）
    MODE="build"
    PROMPT_FILE="PROMPT_build.md"
    MAX_ITERATIONS=0
fi

ITERATION=0
CURRENT_BRANCH=$(git branch --show-current)

echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo "模式:   $MODE"
echo "提示:   $PROMPT_FILE"
echo "分支:   $CURRENT_BRANCH"
[ $MAX_ITERATIONS -gt 0 ] && echo "最大:    $MAX_ITERATIONS 次迭代（任务数量）"
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"

# 验证提示文件是否存在
if [ ! -f "$PROMPT_FILE" ]; then
    echo "错误：$PROMPT_FILE 未找到"
    exit 1
fi

while true; do
    if [ $MAX_ITERATIONS -gt 0 ] && [ $ITERATION -ge $MAX_ITERATIONS ]; then
        echo "已达到最大迭代次数（任务数量）：$MAX_ITERATIONS"
        break
    fi

    # 运行 Ralph 迭代，使用选定的提示
    # -p：无头模式（非交互式，从标准输入读取）
    # --dangerously-skip-permissions：自动批准所有工具调用（YOLO 模式）
    # --output-format=stream-json：结构化输出，便于日志记录和监控
    # --model opus：主代理使用 Opus 处理复杂推理（任务选择、优先级排序）
    # 在构建模式下，若计划清晰且任务明确，也可使用 'sonnet' 以提高速度
    # --verbose：详细执行日志
    cat "$PROMPT_FILE" | claude -p \
        --dangerously-skip-permissions \
        --output-format=stream-json \
        --model opus \
        --verbose

    # 每次迭代后推送更改
    git push origin "$CURRENT_BRANCH" || {
        echo "推送失败。正在创建远程分支..."
        git push -u origin "$CURRENT_BRANCH"
    }

    ITERATION=$((ITERATION + 1))
    echo -e "\n\n======================== LOOP $ITERATION ========================\n"
done

模式选择：

• 不提供关键字 → 使用 PROMPT_build.md 进行构建（实现）
• 提供 plan 关键字 → 使用 PROMPT_plan.md 进行规划（差距分析、计划生成）

最大迭代次数：

• 限制的是_任务选择循环_（尝试执行的任务数量；而非单个任务内的工具调用次数）
• 每次迭代代表一个新的上下文窗口，对应于 IMPLEMENTATION_PLAN.md 中的一项任务，以及一次提交
• ./loop.sh 会无限运行（可通过 Ctrl+C 手动停止）
• ./loop.sh 20 则会在执行 20 次迭代后停止

Claude CLI 标志位：

• -p（无头模式）：启用非交互式操作，从标准输入读取提示
• --dangerously-skip-permissions：跳过所有权限提示，实现完全自动化运行
• --output-format=stream-json：输出结构化 JSON，便于日志记录、监控和可视化
• --model opus：主代理使用 Opus 处理任务选择、优先级排序和协调工作（若任务明确，也可使用 sonnet 以提升速度）
• --verbose：提供详细的执行日志

流式输出版本

另一种 loop_streamed.sh 脚本会将 Claude 的原始 JSON 输出通过 parse_stream.js 进行处理，以在终端上显示可读、带颜色编码的内容，包括工具调用、结果和执行统计信息。

与基础 loop.sh 的区别：

• 将提示作为参数传递（-p "$FULL_PROMPT"），而非通过标准输入管道
• 添加了 --include-partial-messages 以实现实时流式传输
• 将输出通过 parse_stream.js（Node.js，无需依赖）进行处理
• 在提示内容末尾添加了“执行上述指令。”字样

文件： loop_streamed.sh · parse_stream.js

— 由 @terry-xyz 和 @blackrosesxyz 贡献

许可证

本仓库采用 MIT 许可证 开放使用。

第三方截图及外部来源的图片除外，除非另有说明。详情请参阅 NOTICE 文件。

---

文件结构

project-root/
├── loop.sh                         # Ralph 循环脚本
├── PROMPT_build.md                 # 构建模式指令
├── PROMPT_plan.md                  # 规划模式指令
├── AGENTS.md                       # 每次迭代加载的操作指南
├── IMPLEMENTATION_PLAN.md          # 优先级任务列表（由 Ralph 生成/更新）
├── specs/                          # 需求规格文档（每个 JTBD 主题一份）
│   ├── [jtbd-topic-a].md
│   └── [jtbd-topic-b].md
├── src/                            # 应用程序源代码
└── src/lib/                        # 共享工具与组件

loop.sh

主要的循环脚本，负责编排 Ralph 的迭代过程。

有关详细的实现示例和配置选项，请参阅【循环机制】部分。

设置： 首次使用前需赋予脚本可执行权限：

chmod +x loop.sh

核心功能： 不断向 Claude 输入提示文件，管理迭代次数限制，并在每项任务完成后推送更改。

提示词

每个循环迭代的指令集。根据需要在规划和构建版本之间切换。

提示词结构：

部分	用途
阶段 0 (0a, 0b, 0c)	定向：研究规格、源代码位置、当前计划
阶段 1-4	主要指令：任务、验证、提交
999... 编号	安全保障/不变量（数字越大越关键）

关键语言模式（Geoff 的特定措辞）：

• “研究”（而不是“阅读”或“查看”）
• “不要假设未实现”（至关重要——阿喀琉斯之踵）
• “使用并行子代理” / “最多 N 个子代理”
• “构建/测试仅使用 1 个子代理”（背压控制）
• “格外深入思考”（现为“超深度思考”）
• “捕捉原因”
• “保持更新”
• “如果功能缺失，则由你负责添加”
• “解决它们或记录下来”

PROMPT_plan.md 模板

注：

• 更新下方的 [项目特定目标] 占位符。
• 当前子代理名称假定使用 Claude。

0a. 使用最多 250 个并行 Sonnet 子代理研究 `specs/*`，以了解应用程序的规格说明。
0b. 研究 @IMPLEMENTATION_PLAN.md（如果存在），以理解迄今为止的计划。
0c. 使用最多 250 个并行 Sonnet 子代理研究 `src/lib/*`，以了解共享的工具和组件。
0d. 作为参考，应用程序源代码位于 `src/*`。

1. 研究 @IMPLEMENTATION_PLAN.md（如果存在；它可能不正确），并使用最多 500 个 Sonnet 子代理研究 `src/*` 中的现有源代码，将其与 `specs/*` 进行比较。使用 Opus 子代理分析发现，确定任务优先级，并创建/更新 @IMPLEMENTATION_PLAN.md，将其整理成按待实现事项优先级排序的要点列表。超深度思考。考虑搜索 TODO、最小化实现、占位符、被跳过或不稳定测试，以及不一致的模式。研究 @IMPLEMENTATION_PLAN.md 以确定研究起点，并持续用子代理更新已完成/未完成的事项。

重要提示：仅制定计划，切勿实施任何内容。不要假设功能缺失；请先通过代码搜索确认。将 `src/lib` 视为项目的标准库，用于共享工具和组件。优先选择其中整合的、符合语言习惯的实现，而非临时复制的内容。

最终目标：我们希望实现 [项目特定目标]。考虑缺失的元素，并据此制定计划。如果某个元素缺失，请先搜索确认其确实不存在，然后如有必要，在 specs/FILENAME.md 中编写该规范。如果你创建了新元素，则需使用子代理在 @IMPLEMENTATION_PLAN.md 中记录其实现计划。

PROMPT_build.md 模板

注意： 当前子代理名称假定使用 Claude。

0a. 使用最多 500 个并行 Sonnet 子代理研究 `specs/*`，以了解应用程序的规格说明。
0b. 研究 @IMPLEMENTATION_PLAN.md。
0c. 作为参考，应用程序源代码位于 `src/*`。

1. 你的任务是按照规格说明，使用并行子代理实现功能。遵循 @IMPLEMENTATION_PLAN.md，选择最重要的事项进行处理。在做出更改之前，使用 Sonnet 子代理搜索代码库（不要假设未实现）。你可以使用最多 500 个并行 Sonnet 子代理进行搜索和读取，但构建/测试时仅使用 1 个 Sonnet 子代理。当需要复杂推理时（调试、架构决策），使用 Opus 子代理。
2. 实现功能或解决问题后，运行该代码单元的测试。如果功能缺失，则需根据应用程序规格说明自行添加。超深度思考。
3. 发现问题时，立即使用子代理更新 @IMPLEMENTATION_PLAN.md，记录你的发现。问题解决后，更新并移除相关条目。
4. 测试通过后，更新 @IMPLEMENTATION_PLAN.md，然后执行 `git add -A` 和 `git commit`，并在提交信息中描述所做的更改。提交完成后，执行 `git push`。

99999. 重要提示：撰写文档时，务必说明原因——包括测试和实现的重要性。
999999. 重要提示：单一事实来源，禁止迁移或适配器。若与你工作无关的测试失败，应将其作为本次增量的一部分一并解决。
9999999. 一旦没有构建或测试错误，就创建一个 Git 标签。如果没有 Git 标签，则从 0.0.0 开始，每次补丁版本加 1，例如 0.0.1，前提是 0.0.0 不存在。
99999999. 如有需要，可添加额外的日志以调试问题。
999999999. 使用子代理保持 @IMPLEMENTATION_PLAN.md 的最新状态——未来的开发工作依赖于此，以避免重复劳动。尤其在你完成本轮任务后，务必及时更新。
9999999999. 如果你了解到关于如何运行应用程序的新知识，使用子代理更新 @AGENTS.md，但内容应简明扼要。例如，如果你在掌握正确命令之前多次尝试运行某些指令，那么该文件就应该相应更新。
99999999999. 对于你注意到的任何 bug，即使与当前工作无关，也应使用子代理将其解决或记录在 @IMPLEMENTATION_PLAN.md 中。
999999999999. 功能必须完整实现。占位符和桩代码会浪费精力和时间，导致重复劳动。
9999999999999. 当 @IMPLEMENTATION_PLAN.md 变得过于冗长时，应定期使用子代理清理已完成的条目。
99999999999999. 如果发现 `specs/*` 中存在不一致之处，则使用 Opus 4.6 子代理，并要求其进行“超深度思考”，以更新规格说明。
999999999999999. 重要提示：保持 @AGENTS.md 的实用性——状态更新和进度说明应放在 `IMPLEMENTATION_PLAN.md` 中。臃肿的 AGENTS.md 会污染未来每次循环的上下文。

AGENTS.md

单一、规范的“循环核心”——一份简洁实用的“如何运行/构建”指南。

• 不是变更日志或进度日记
• 描述如何构建/运行项目
• 记录能改进循环的实用经验
• 内容应简短（约 60 行）

状态、进度和计划应放在 IMPLEMENTATION_PLAN.md 中，而非此处。

循环回溯 / 即时自我评估：

AGENTS.md 应包含使 Ralph 能够在同一循环内即时评估其工作的项目特定命令——即循环回溯能力。这包括：

• 构建命令
• 测试命令（定向测试和完整套件）
• 类型检查/代码风格检查命令
• 任何其他验证工具

BUILDING 提示词笼统地提到“运行测试”；而 AGENTS.md 则具体指定了实际命令。这就是如何为每个项目配置背压机制的方式。

示例

## 构建与运行

关于如何构建项目的简明规则：

## 验证

实现后运行以下命令以获得即时反馈：

- 测试：`[测试命令]`
- 类型检查：`[类型检查命令]`
- 代码风格检查：`[代码风格检查命令]`

## 操作注意事项

关于如何运行项目的简明经验：

...

### 代码库模式

...

IMPLEMENTATION_PLAN.md

由拉尔夫生成的、基于差距分析（规格与代码对比）得出的优先级任务列表——以项目符号形式呈现。

• 创建于 规划模式下
• 更新于 构建模式中（标记完成、添加新发现、记录缺陷）
• 可重新生成 ——杰夫：“我已经多次删除了待办清单” → 切换回规划模式
• 自我修正 ——如果缺少规格，构建模式甚至可以创建新的规格

这种循环设计是刻意为之：通过迭代实现最终一致性。

• 无预设模板 ——让拉尔夫/大模型自行决定并管理最适合其工作的格式。

specs/*

每个关注主题对应一个 Markdown 文件。这些文件是关于应构建内容的事实来源。

• 在需求阶段创建（人类与大模型的对话）

• 被规划模式和构建模式共同使用

• 如发现不一致，可进行更新（较为罕见，宜使用子代理处理）

• 无预设模板 ——让拉尔夫/大模型自行决定并管理最适合其工作的格式。

src/ 和 src/lib/

应用源代码及共享工具/组件。

在 PROMPT.md 模板中被引用，用于引导步骤。

---

改进方案？

我仍在评估这些方案的价值与可行性，但听起来机会颇为诱人：

• 利用 Claude 的 AskUserQuestionTool 进行规划 —— 使用 Claude 内置的访谈工具，系统性地澄清 JTBD、边缘情况及规格中的验收准则。
• 基于验收的反压机制 —— 在规划阶段根据验收准则推导测试需求。这能防止“作弊”——如果没有通过适当的测试，就不能宣称已完成。
• 非确定性反压机制 —— 对于主观性任务（语气、美学、用户体验等），使用大模型作为评判者进行测试。采用二元通过/失败的评审方式，并不断迭代直至通过。
• 适合拉尔夫的工作分支 —— 在运行时要求拉尔夫“筛选到功能 X”并不可靠。相反，应在一开始就为每个分支创建明确范围的计划。
• JTBD → 故事地图 → SLC 发布 —— 将“让拉尔夫做拉尔夫该做的事”的理念延伸至将 JTBD 中的目标用户及其活动与简单/可爱/完整的发布版本相连接。
• 规格审计 —— 专门设立一种模式，用于按照质量规则生成和维护规格：仅关注行为结果、明确主题范围、统一命名规范。
• 将现有项目逆向工程为规格 —— 通过将现有代码库逆向转化为规格，再开始规划新工作，从而将旧项目纳入拉尔夫的工作流。

---

利用 Claude 的 AskUserQuestionTool 进行规划

在第一阶段（定义需求）中，使用 Claude 内置的 AskUserQuestionTool 工具，通过结构化访谈系统地探索 JTBD、关注主题、边缘情况以及验收准则，然后再编写规格文档。

适用场景： 初始需求模糊或极少，需要明确约束条件，或者存在多种可行方案时。

调用方式： “请使用 AskUserQuestion 工具采访我，以了解 [JTBD/主题/验收准则/...]”

Claude 将提出有针对性的问题，以澄清需求并确保各方达成一致，随后生成 specs/*.md 文件。

流程：

1. 从已知信息出发 →
2. Claude 通过 AskUserQuestion 进行访谈 →
3. 反复迭代直至清晰 →
4. Claude 编写包含验收准则的规格文档 →
5. 继续进入规划与构建阶段

无需修改代码或提示词——此方法仅利用现有的 Claude Code 功能来增强第一阶段的工作。

灵感来源 —— Thariq 的 X 平台帖子：

---

接受驱动的反压机制

Geoff 的 Ralph 通过渐进式的迭代过程，隐式地 将需求规格、实现和测试连接起来。而这一增强功能将使这种连接变得_显式_，即在规划阶段就推导出测试需求，从而建立一条从“成功的样子”到“如何验证它”的直接路径。

该增强功能将需求规格中的验收准则与实现计划中的测试要求直接关联起来，从而提升反压的质量，具体体现在：

• 防止“作弊”：如果没有根据验收准则推导出的必要测试，则无法宣称任务完成。
• 支持 TDD 工作流：在开始实现之前，测试要求就已经明确。
• 提高收敛性：以“必要测试全部通过”作为明确的完成信号，而非模糊的“看起来完成了？”。
• 保持确定性：测试要求存在于计划中（已知状态），而不是在运行时才逐渐显现（概率性）。

与核心理念的兼容性

原则	是否保持？	如何体现
单体运作	✅ 是	每次只有一个代理、一项任务、一个循环
反压至关重要	✅ 是	测试是反压机制，只是现在以显式方式推导出来
上下文效率	✅ 是	规划阶段一次性决定测试，避免重复构建和重新发现
确定性设置	✅ 是	测试要求在计划中（已知状态），而非运行时动态生成
让 Ralph 自主决断	✅ 是	Ralph 仍然负责优先级排序并选择实现方案
计划可丢弃	✅ 是	如果测试要求有误，可以重新生成计划
“捕捉为什么”	✅ 是	测试意图在实现前就记录在计划中
杜绝作弊	✅ 是	必要的测试能够防止仅占位的实现

规范性的平衡

关键区别在于：

验收准则（来自需求规格）= 行为结果、可观察的结果，即成功的定义。

• ✅ “从任何上传的图片中提取 5-10 种主导颜色”
• ✅ “处理小于 5MB 的图片耗时不超过 100 毫秒”
• ✅ “处理边缘情况：灰度图、单色图、透明背景”

测试要求（来自实现计划）= 由验收准则推导出的验证点。

• ✅ “必要测试：提取 5-10 种颜色、性能低于 100 毫秒、处理灰度边缘情况”

实现方案（由 Ralph 决定）= 关于如何实现的具体技术决策。

• ❌ “使用 K-means 聚类算法，迭代 3 次，并进行 LAB 颜色空间转换”

关键在于：明确要验证什么（结果），而不是如何实现（方案）

这保持了“让 Ralph 自主决断”的原则——Ralph 在拥有清晰成功信号的情况下，自主决定实现细节。

架构：三阶段连接

阶段 1：需求定义
    specs/*.md + 接受验准则
    ↓
阶段 2：规划（推导测试要求）
    IMPLEMENTATION_PLAN.md + 必要测试
    ↓
阶段 3：构建（带测试的实现）
    实现 + 测试 → 反压

第一阶段：需求定义

在生成需求规格的人机对话过程中：

• 讨论用户目标，并将其分解为关注的主题。
• 根据需要使用子代理加载外部上下文。
• 讨论并定义验收准则——哪些可观察、可验证的结果表明任务成功。
• 准则应聚焦于行为层面（结果），而非实现细节（如何构建）。
• LLM 会根据需求规格的逻辑编写包含验收准则的内容。
• 验收准则将成为规划阶段推导测试要求的基础。

第二阶段：规划模式增强

修改 PROMPT_plan.md 的第一条指令，加入测试推导的内容。在第一句后添加：

对于计划中的每一项任务，根据需求规格中的验收准则推导出必要的测试——需要验证的具体结果（行为、性能、边缘情况）。测试验证的是“做什么”，而非“怎么做”。请将这些测试纳入任务定义中。

第三阶段：构建模式增强

修改 PROMPT_build.md 的指令：

指令 1： 在“选择最重要的事项来处理”之后添加：

任务应包含必要的测试——将测试作为任务范围的一部分一起实现。

指令 2： 将“运行该代码单元的测试”替换为：

运行任务定义中指定的所有必要测试。所有必要测试必须存在且通过，任务才算完成。

新增约束条件（置于第 9 步序列中）：

999. 必须先确保根据验收准则推导出的必要测试存在并全部通过，才能提交代码。测试是实现范围的一部分，而非可选项。采用测试驱动开发方法：测试可以先写，也可以与实现同步进行。

---

非确定性反压

有些验收准则难以通过程序化的方式进行验证：

• 创作质量——写作风格、叙事流畅性、内容吸引力。
• 审美判断——视觉和谐、设计平衡、品牌一致性。
• 用户体验质量——导航是否直观、信息层级是否清晰。
• 内容适宜性——信息是否符合场景、是否适合目标受众。

这些都需要类似人类的判断力，但在构建循环中仍需反压机制来确保满足验收准则。

解决方案： 添加 LLM 作为评判者的测试作为反压手段，采用二元通过/失败判定。

LLM 的评审是非确定性的（同一产物在不同运行中可能得到不同的评价）。这符合 Ralph 的哲学：“在不确定的世界里，以确定的方式应对问题”。循环通过迭代提供最终的一致性——评审将持续进行，直到通过为止，同时接受自然的差异。

需要创建的内容（第一步）

在 src/lib/ 目录下创建两个文件：

src/lib/
  llm-review.ts          # 核心工具——单一函数，简洁 API
  llm-review.test.ts     # 参考示例，展示模式（Ralph 从中学习）

llm-review.ts - Ralph 发现的二元通过/失败 API：

interface ReviewResult {
  pass: boolean;
  feedback?: string; // 仅当不通过时存在
}

function createReview(config: {
  criteria: string; // 评估的内容（行为、可观察）
  artifact: string; // 文本内容或截图路径
  intelligence?: "fast" | "smart"; // 可选，默认为 'fast'
}): Promise<ReviewResult>;

多模态支持： 两种智能级别都将使用多模态模型（文本+视觉）。自动检测产物类型：

• 文本评估：artifact: "Your content here" → 作为文本输入处理。
• 视觉评估：artifact: "./tmp/screenshot.png" → 作为视觉输入处理（检测 .png、.jpg、.jpeg 等扩展名）。

智能级别（指判断质量，而非能力类型）：

• fast（默认）：快速、经济高效的模型，适用于简单的评估
  • 示例：Gemini 3.0 Flash（多模态、快速、便宜）
• smart：更高质量的模型，适合进行细致入微的美学或创意判断
  • 示例：GPT 5.1（多模态、判断更佳、成本更高）

测试夹具会自动选择合适的模型。（示例为当前可用选项，并非强制要求。）

llm-review.test.ts - 展示 Ralph 如何使用它（文本和视觉示例）：

import { createReview } from "@/lib/llm-review";

// 示例 1：文本评估
test("欢迎信息语气", async () => {
  const message = generateWelcomeMessage();
  const result = await createReview({
    criteria:
      "信息采用温暖、对话式的语气，适合设计专业人士，同时清晰传达价值主张",
    artifact: message, // 文本内容
  });
  expect(result.pass).toBe(true);
});

// 示例 2：视觉评估（截图路径）
test("仪表板视觉层次结构", async () => {
  await page.screenshot({ path: "./tmp/dashboard.png" });
  const result = await createReview({
    criteria:
      "布局展现出清晰的视觉层次，主要操作一目了然",
    artifact: "./tmp/dashboard.png", // 截图路径
  });
  expect(result.pass).toBe(true);
});

// 示例 3：智能模式用于复杂判断
test("品牌视觉一致性", async () => {
  await page.screenshot({ path: "./tmp/homepage.png" });
  const result = await createReview({
    criteria:
      "视觉设计保持专业品牌形象，适合金融服务行业，同时避免过于刻板的企业化风格",
    artifact: "./tmp/homepage.png",
    intelligence: "smart", // 复杂的美学判断
  });
  expect(result.pass).toBe(true);
});

Ralph 从这些示例中学习到： 文本和截图都可以作为评估对象。根据需要评估的内容来选择即可。其余工作由测试夹具内部自动处理。

未来的扩展性： 目前的设计为了简单起见，使用单一的 artifact: string。如果后续出现需要多个评估对象的明确模式（如前后对比、跨项目一致性检查、多角度评估等），可以扩展为 artifact: string | string[]。对于大多数多项目需求，可以通过组合截图或拼接文本的方式来实现。

与 Ralph 工作流的集成

规划阶段 - 更新 PROMPT_plan.md：

在以下内容之后：

...研究 @IMPLEMENTATION_PLAN.md 以确定研究的起点，并利用子代理持续更新已完成和未完成的事项。

插入如下内容：

从验收标准推导测试需求时，需明确验证是需要程序化的校验（可测量、可检查）还是类似人类的判断（感知质量、语气、美学）。这两种方式都是同样有效的反压机制。对于难以通过程序化方式验证的主观标准，请探索 src/lib 中的非确定性评估模式。

构建阶段 - 更新 PROMPT_build.md：

在第 9 步序列中新增一条约束：

9999. 创建测试以验证实现是否符合验收标准，包括常规测试（行为、性能、正确性）以及感知质量测试（针对主观标准，参见 src/lib 中的相关模式）。

发现而非文档化： 在 src/lib 探索过程中（Phase 0c），Ralph 通过 llm-review.test.ts 中的示例学习 LLM 评审模式。无需更新 AGENTS.md——代码示例本身就是文档。

与核心理念的兼容性

原则	是否保持？	如何实现
反压至关重要	✅ 是	将反压机制扩展至非程序化的验收环节
确定性设置	⚠️ 部分	计划中的标准是确定性的，而评估过程是非确定性的，但可通过迭代逐步收敛。这是为了兼顾主观质量而有意做出的权衡。
上下文效率	✅ 是	通过 src/lib 复用测试夹具，测试定义简洁精炼
让 Ralph 自主决策	✅ 是	Ralph 发现模式，自行决定何时使用，并编写评估标准
计划可丢弃	✅ 是	评审需求作为计划的一部分，若不准确可重新生成
简单至上	✅ 是	单一函数、二元结果，无复杂的评分机制
为 Ralph 提供指引	✅ 是	仅需少量提示补充，Ralph 可通过代码探索自主学习

---

适合 Ralph 的工作分支

关键原则： Geoff 的 Ralph 基于一个一次性计划工作，其中 Ralph 会挑选“最重要的”任务。要在保持这一模式的同时使用分支，必须在创建计划时进行范围限定，而不是在选择任务时。

为什么这很重要：

• ❌ 错误做法： 先创建完整计划，再让 Ralph 在运行时“过滤”任务 → 不可靠（70-80%），违反确定性
• ✅ 正确做法： 为每个工作分支提前创建一个限定范围的计划 → 确定性、简单，且保持“计划是一次性的”

解决方案： 添加 plan-work 模式，在当前分支上生成一个针对特定工作的 IMPLEMENTATION_PLAN.md。用户创建工作分支后，使用自然语言描述工作重点来运行 plan-work。LLM 会根据这个描述来限定计划的范围。规划完成后，Ralph 将基于这个已经限定范围的计划进行构建，无需任何语义过滤——只需像往常一样挑选“最重要的”任务。

术语： “工作”一词有意宽泛——它可以指功能、关注点、重构工作、基础设施变更、缺陷修复，或任何连贯的相关更改集合。您传递给 plan-work 的工作描述是提供给 LLM 的自然语言文本，可以是散文形式，不受 Git 分支命名规则的限制。

设计原则

• ✅ 每个 Ralph 会话都以单体方式 处理每个分支上的单一工作内容
• ✅ 用户手动创建分支 —— 完全掌控命名规范和策略（如工作树）
• ✅ 自然语言工作描述 —— 向 LLM 传递散文，不受 Git 命名规则限制
• ✅ 在计划创建时进行范围限定（确定性），而非在任务选择时（概率性）
• ✅ 每个分支仅有一个计划 —— 每个分支对应一个 IMPLEMENTATION_PLAN.md
• ✅ 计划仍具有一次性 —— 当某个分支的计划不正确或过时时，可重新生成限定范围的计划
• ✅ 循环会话内不允许动态切换分支
• ✅ 维持了简单性和确定性
• ✅ 可选——主分支的工作流仍然有效
• ✅ 构建时无需语义过滤——Ralph 只需挑选“最重要的”任务

工作流程

1. 完整规划（在主分支上）

./loop.sh plan
# 为整个项目生成完整的 IMPLEMENTATION_PLAN.md

2. 创建工作分支

用户执行：

git checkout -b ralph/user-auth-oauth
# 使用您喜欢的任何命名规范创建分支
# 建议：工作分支以 ralph/* 开头

3. 限定范围规划（在工作分支上）

./loop.sh plan-work "带有 OAuth 和会话管理的用户认证系统"
# 传递自然语言描述——LLM 将据此限定计划范围
# 生成只包含该工作相关任务的聚焦型 IMPLEMENTATION_PLAN.md

4. 基于计划构建（在工作分支上）

./loop.sh
# Ralph 基于限定范围的计划进行构建（无需过滤）
# 直接从已限定范围的计划中挑选最重要的任务

5. 创建 PR（工作完成后）

用户执行：

gh pr create --base main --head ralph/user-auth-oauth --fill

针对工作范围的 Loop 脚本

扩展基础增强版 Loop 脚本，增加对工作分支的支持及限定范围规划功能：

#!/bin/bash
set -euo pipefail

# 使用方法：
#   ./loop.sh [plan|build] [max_iterations]  # 在当前分支上进行规划或构建
#   ./loop.sh plan-work "工作描述"  # 在当前分支上创建限定范围的计划
# 示例：
#   ./loop.sh                               # 构建模式，无上限
#   ./loop.sh 20                            # 构建模式，最多 20 次
#   ./loop.sh build 20                      # 构建模式，最多 20 次
#   ./loop.sh plan 5                        # 完整规划，最多 5 次
#   ./loop.sh plan-work "用户认证"         # 限定范围规划

# 解析参数
MODE="build"
PROMPT_FILE="PROMPT_build.md"

if [ "$1" = "plan" ]; then
    # 完整规划模式
    MODE="plan"
    PROMPT_FILE="PROMPT_plan.md"
    MAX_ITERATIONS=${2:-0}
elif [ "$1" = "build" ]; then
    # 显式构建模式（可选最大迭代次数）
    MAX_ITERATIONS=${2:-0}
elif [ "$1" = "plan-work" ]; then
    # 限定范围规划模式
    if [ -z "$2" ]; then
        echo "错误：plan-work 需要提供工作描述"
        echo "用法：./loop.sh plan-work '工作描述'"
        exit 1
    fi
    MODE="plan-work"
    WORK_DESCRIPTION="$2"
    PROMPT_FILE="PROMPT_plan_work.md"
    MAX_ITERATIONS=${3:-5}  # 工作规划默认 5 次
elif [[ "$1" =~ ^[0-9]+$ ]]; then
    # 构建模式，指定最大迭代次数（纯数字）
    MAX_ITERATIONS=$1
else
    # 构建模式，无上限
    MAX_ITERATIONS=0
fi

ITERATION=0
CURRENT_BRANCH=$(git branch --show-current)

# 校验 plan-work 模式下的分支
if [ "$MODE" = "plan-work" ]; then
    if [ "$CURRENT_BRANCH" = "main" ] || [ "$CURRENT_BRANCH" = "master" ]; then
        echo "错误：plan-work 应在工作分支上运行，而非 main/master"
        echo "请先创建工作分支：git checkout -b ralph/your-work"
        exit 1
    fi

    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
    echo "模式：    plan-work"
    echo "分支：  $CURRENT_BRANCH"
    echo "工作：    $WORK_DESCRIPTION"
    echo "提示词：  $PROMPT_FILE"
    echo "计划：    将创建限定范围的 IMPLEMENTATION_PLAN.md"
    [ "$MAX_ITERATIONS" -gt 0 ] && echo "上限：     $MAX_ITERATIONS 次"
    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"

    # 提醒未提交的 IMPLEMENTATION_PLAN.md 更改
    if [ -f "IMPLEMENTATION_PLAN.md" ] && ! git diff --quiet IMPLEMENTATION_PLAN.md 2>/dev/null; then
        echo "警告：IMPLEMENTATION_PLAN.md 存在未提交的更改，这些更改将被覆盖"
        read -p "继续吗？[y/N] " -n 1 -r
        echo
        [[ ! $REPLY =~ ^[Yy]$ ]] && exit 1
    fi

    # 导出工作描述供 PROMPT_plan_work.md 使用
    export WORK_SCOPE="$WORK_DESCRIPTION"
else
    # 普通规划/构建模式
    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
    echo "模式：   $MODE"
    echo "分支：   $CURRENT_BRANCH"
    echo "提示词： $PROMPT_FILE"
    echo "计划：   IMPLEMENTATION_PLAN.md"
    [ "$MAX_ITERATIONS" -gt 0 ] && echo "上限：    $MAX_ITERATIONS 次"
    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
fi

# 验证提示词文件是否存在
if [ ! -f "$PROMPT_FILE" ]; then
    echo "错误：$PROMPT_FILE 未找到"
    exit 1
fi

# 主循环
while true; do
    if [ "$MAX_ITERATIONS" -gt 0 ] && [ "$ITERATION" -ge "$MAX_ITERATIONS" ]; then
        echo "达到最大迭代次数：$MAX_ITERATIONS"

        if [ "$MODE" = "plan-work" ]; then
            echo ""
            echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
            echo "已创建限定范围的计划：$WORK_DESCRIPTION"
            echo "要构建，请运行："
            echo "  ./loop.sh 20"
            echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
        fi
        break
    fi

    # 使用选定的提示词运行Ralph迭代
    # -p: 无头模式（非交互式，从标准输入读取）
    # --dangerously-skip-permissions: 自动批准所有工具调用（YOLO模式）
    # --output-format=stream-json: 结构化输出，便于日志记录和监控
    # --model opus: 主代理使用Opus模型进行复杂推理（任务选择、优先级排序）
    #               如果计划清晰且任务定义明确，也可使用‘sonnet’以提高速度
    # --verbose: 详细执行日志记录

    # 对于计划-工作模式，在管道前先替换提示词中的${WORK_SCOPE}
    if [ "$MODE" = "plan-work" ]; then
        envsubst < "$PROMPT_FILE" | claude -p \
            --dangerously-skip-permissions \
            --output-format=stream-json \
            --model opus \
            --verbose
    else
        cat "$PROMPT_FILE" | claude -p \
            --dangerously-skip-permissions \
            --output-format=stream-json \
            --model opus \
            --verbose
    fi

    # 推送到当前分支
    CURRENT_BRANCH=$(git branch --show-current)
    git push origin "$CURRENT_BRANCH" || {
        echo "推送失败。正在创建远程分支..."
        git push -u origin "$CURRENT_BRANCH"
    }

    ITERATION=$((ITERATION + 1))
    echo -e "\n\n======================== 第 $ITERATION 次循环 ========================\n"
done

PROMPT_plan_work.md 模板

注意： 与 PROMPT_plan.md 完全相同，但加入了范围限定说明，并替换了环境变量 WORK_SCOPE（由循环脚本自动完成）。

0a. 使用最多250个并行的Sonnet子代理研究`specs/*`，以了解应用程序的规格说明。
0b. 研究@IMPLEMENTATION_PLAN.md（如果存在），以理解目前的计划。
0c. 使用最多250个并行的Sonnet子代理研究`src/lib/*`，以理解共享的实用工具和组件。
0d. 作为参考，应用程序源代码位于`src/*`。

1. 您正在为工作“${WORK_SCOPE}”制定一个限定范围的实施计划。研究@IMPLEMENTATION_PLAN.md（如果存在；它可能是不正确的），并使用多达500个Sonnet子代理来研究`src/*`中的现有源代码，将其与`specs/*`进行比较。使用一个Opus子代理分析结果，确定任务的优先级，并创建或更新@IMPLEMENTATION_PLAN.md，将其整理成按未实现事项优先级排序的项目列表。务必深入思考。考虑搜索TODO标记、最小化实现、占位符、被跳过或不稳定的功能测试，以及不一致的模式。研究@IMPLEMENTATION_PLAN.md以确定研究的起点，并持续使用子代理更新已完成或未完成的条目。

重要提示：这仅是针对“${WORK_SCOPE}”的限定范围规划。请仅包含与此工作范围直接相关的任务。保持保守态度——如果不确定某项任务是否属于此工作范围，则将其排除。如果计划过于狭窄，可以重新生成。仅做规划，切勿实施任何内容。不要假设功能缺失；应先通过代码搜索确认。将`src/lib`视为项目的标准库，用于共享实用工具和组件。优先选择其中统一、符合语言习惯的实现方式，而非临时复制的版本。

最终目标：我们希望实现限定范围的工作“${WORK_SCOPE}”。请考虑与此工作相关的缺失部分，并据此制定计划。如果发现某项缺失内容，首先搜索确认其确实不存在，然后在必要时编写规格说明文件至`specs/FILENAME.md`。如果您创建了新元素，请使用子代理在@IMPLEMENTATION_PLAN.md中记录其实现计划。

与核心理念的兼容性

原则	是否保持？	如何保持
单体操作	✅ 是	Ralph 仍然在分支内以单进程运行
每次循环一项任务	✅ 是	未发生变化
新鲜上下文	✅ 是	未发生变化
确定性	✅ 是	规划阶段的范围限定是确定性的，而运行时则是概率性的
简单	✅ 是	可选增强功能，主流程仍可正常工作
计划驱动	✅ 是	每个分支只有一个IMPLEMENTATION_PLAN.md
单一事实来源	✅ 是	每个分支只有一个计划——限定范围的计划会取代分支上的完整计划
计划可丢弃	✅ 是	随时可重新生成限定范围的计划：./loop.sh plan-work "工作描述"
Markdown优于JSON	✅ 是	仍然是Markdown格式的计划
让Ralph自己做决定	✅ 是	Ralph 从已经限定范围的计划中挑选出“最重要”的内容——无需额外筛选

---

JTBD → 故事地图 → SLC发布

关注点 → 活动

Geoff提出的建议工作流已经将规划与“待完成的工作”相结合——将JTBD分解为关注点，这些关注点又转化为规格说明。我非常喜欢这一点，我认为还有机会进一步利用这种方法所带来的产品优势，将“关注点”重新定义为“活动”。

活动是旅程中的动词（如“上传照片”、“提取颜色”），而不是能力（如“颜色提取系统”）。它们天然地由用户意图来界定。

关注点：“颜色提取”、“布局引擎”→ 能力导向 活动：“上传照片”、“查看提取的颜色”、“排列布局”→ 旅程导向

活动 → 用户旅程

活动及其构成步骤自然地串联成用户流程，形成一种“旅程结构”，使其中的空白和依赖关系变得清晰可见。借助_用户故事地图_，可以将活动按列排列（即旅程的主干），并将能力深度按行排列——从而全面展示可能构建的内容：

上传    →   提取    →   排列     →   分享

基础         自动           手动          导出
批量         调色板        模板        合作
批处理         AI主题      自动布局      嵌入

用户旅程 → 发布切片

地图上的水平切片会成为候选发布版本。并非每个活动都需要在每个版本中都具备新功能——有些单元格可以留空，只要该切片仍然保持连贯性即可：

                  上传    →   提取    →   排列     →   分享

发布1：        基本         自动                           导出
                  ───────────────────────────────────────────────────
发布2：                      调色板        手动
                  ───────────────────────────────────────────────────
发布3：        批量         AI主题      模板       嵌入

发布切片 → SLC 发布

故事地图为你提供了切分的_结构_。Jason Cohen 的 简单、可爱、完整 (SLC) 则给出了判断一个切片是否优秀的_标准_：

• 简单 — 范围狭窄，能够快速交付。不需要涵盖所有活动或所有深度。
• 完整 — 在该范围内完整地完成一项任务。而不是一个不完整的预览版。
• 可爱 — 用户真正愿意使用它。在其限定范围内令人愉悦。

为什么选择 SLC 而不是 MVP？ MVP 以牺牲用户体验为代价来优化学习效果——“最小”往往意味着功能残缺或令人沮丧。而 SLC 则颠覆了这一点：在市场中学习的同时，持续交付真正的价值。如果成功，你将拥有更多的选择；即使失败，你也已经善待了用户。

每个切片都可以成为一个具有明确价值和身份的发布版本：

                  上传    →   提取    →   排列     →   分享

调色板选择器：   基本         自动                           导出
                  ───────────────────────────────────────────────────
情绪板：                     调色板        手动
                  ───────────────────────────────────────────────────
设计工作室：    批量         AI主题      模板       嵌入

• 调色板选择器 — 上传、提取、导出。从第一天起就能立即产生价值。
• 情绪板 — 增加了排列功能。创意表达融入了整个流程。
• 设计工作室 — 提供专业级功能：批量处理、AI 主题、可嵌入的输出。

---

使用 Ralph 实现

上述概念——活动、故事地图、SLC 发布——是我们的_思维工具_。那么如何将其转化为 Ralph 的工作流程呢？

默认的 Ralph 方法：

1. 定义需求：人类与 LLM 共同确定用户想要解决的 JTBD 主题 → specs/*.md
2. 创建任务计划：LLM 分析所有规格文档及现有代码 → IMPLEMENTATION_PLAN.md
3. 开发：Ralph 按照完整范围进行开发。

这种方法非常适合以功能为中心的工作（如新特性、重构或基础设施建设）。但它并不能自然地产生有价值的（SLC）产品发布——它只会按照规格文档的内容进行开发。

活动 → SLC 发布方法：

要实现 SLC 发布，我们需要将活动置于目标用户的上下文中。用户群体决定了谁有 JTBD，进而明确了哪些活动是关键，以及什么才是“可爱”的含义。

用户群体（谁）
    └── 拥有 JTBD（期望的结果）
            └── 由活动（实现结果的手段）来满足

工作流程

I. 需求阶段（2 步）：

仍由 LLM 与人类对话完成，类似于默认的 Ralph 方法。

1. 定义用户群体及其 JTBD — 我们为谁构建？他们希望达成什么_成果_？

   • 人类与 LLM 讨论并确定目标用户群体及其 JTBD（期望达成的成果）。
   • 可能包含多个相关联的用户群体（例如，“设计师”负责创作，“客户”负责评审）。
   • 生成 AUDIENCE_JTBD.md 文件。

2. 定义活动 — 用户为了实现其 JTBD 需要做些什么？

   • 根据 AUDIENCE_JTBD.md 文件制定。
   • 对于每个 JTBD，识别完成它所需的活动。
   • 对于每个活动，确定：
     • 功能深度（基础 → 增强）——复杂程度的不同层次。
     • 每个层次下期望达成的成果——成功的具体表现是什么？
   • 生成 specs/*.md 文件（每个活动对应一个文件）。

   活动中的具体步骤是隐含的，LLM 可以在规划过程中推断出来。

II. 规划阶段：

在 Ralph 循环中使用_更新后的_规划提示执行。

• LLM 分析：
  • AUDIENCE_JTBD.md（用户是谁、期望达成的成果）
  • specs/*（可以构建的内容）
  • 当前代码状态（已有的功能）
• LLM 确定下一个 SLC 切片（哪些活动、处于何种功能深度），并为该切片规划任务。
• LLM 生成 IMPLEMENTATION_PLAN.md 文件。
• _人类验证_计划后再进行开发：
  • 该范围是否代表一个连贯的 SLC 发布？
  • 是否包含了正确的活动，并且处于恰当的功能深度？
  • 如果有问题，则重新运行规划循环以生成新的计划，必要时可更新输入或规划提示。
  • 如果正确，则进入开发阶段。

III. 开发阶段：

在 Ralph 循环中使用标准的开发提示执行。

更新后的规划提示

这是 PROMPT_plan.md 的变体，增加了用户背景信息和面向 SLC 的切片建议。

注意事项：

• 与默认模板不同，此模板没有 [项目特定目标] 占位符——因为目标是隐含的：为用户群体推荐最有价值的下一个发布版本。
• 目前的子代理名称假设使用的是 Claude 模型。

0a. 研究 @AUDIENCE_JTBD.md，了解我们要为谁构建以及他们的待完成工作。
0b. 使用最多 250 个 Sonnet 子代理并行研究 `specs/*`，以了解与 JTBD 相关的活动。
0c. 研究 @IMPLEMENTATION_PLAN.md（如有），以了解迄今为止的计划。
0d. 使用最多 250 个 Sonnet 子代理并行研究 `src/lib/*`，以了解共享的工具和组件。
0e. 作为参考，应用程序源代码位于 `src/*`。

1. 将 `specs/*` 中的活动按顺序排列成针对 @AUDIENCE_JTBD.md 中用户群体的用户旅程图。考虑各活动之间的流转关系及依赖性。

2. 确定下一个 SLC 发布版本。使用最多 500 个 Sonnet 子代理比较 `src/*` 和 `specs/*`。再用一个 Opus 子代理分析结果。深入思考。结合已实现的功能，推荐哪些活动（处于何种功能深度）构成最有价值的下一个发布版本。优先选择较薄的水平切片——即能在提供实际价值的前提下，尽可能缩小范围。一个好的切片应具备以下特点：简单（范围小、可实现）、可爱（用户愿意使用）和完整（完整地完成有意义的任务，而非不完整的预览）。

3. 使用一个 Opus 子代理（深入思考）分析并综合上述发现，对任务进行优先级排序，并创建或更新 @IMPLEMENTATION_PLAN.md，以要点列表的形式列出针对推荐的 SLC 发布版本尚未实施的任务。计划开头应概述推荐的 SLC 发布版本（包含哪些内容以及原因），然后按优先级列出该范围内的任务。需考虑待办事项、占位符、最小化实现、未完成的测试等，但仅限于本次发布的范围。对于超出范围的发现，则记录为后续工作。

重要提示：仅进行规划，不要执行任何操作。不要假设某些功能缺失；应先通过代码搜索确认。将 `src/lib` 视为项目的标准库，用于共享工具和组件。优先采用其中的整合、规范化的实现方式，而非临时复制的做法。

终极目标：我们希望在 @AUDIENCE_JTBD.md 中为受众实现最具价值的下一次发布。请考虑缺失的元素，并据此进行规划。如果某个元素缺失，请先搜索确认其不存在，然后再根据需要在 specs/FILENAME.md 中编写该规范。如果你创建了一个新元素，则需使用子代理将其实施计划记录在 @IMPLEMENTATION_PLAN.md 中。

备注

为什么将 AUDIENCE_JTBD.md 作为单独的文档：

• 单一事实来源——防止各规范之间出现偏差
• 支持整体性思考：“这个受众最需要什么？”
• 将 JTBD 与受众信息一同记录（“为什么”的部分与“谁”的部分紧密相连）
• 在规范制定和 SLC 规划阶段都会被引用两次
• 使活动规范聚焦于“做什么”，而非重复描述“谁”

基数关系：

• 一个受众对应多个 JTBD（例如，“设计师”有“捕捉空间”、“探索概念”、“向客户展示”等需求）
• 一个 JTBD 可分解为多个活动（例如，“捕捉空间”包括上传、测量、房间检测等操作）
• 一个活动可以服务于多个 JTBD（例如，“上传照片”既可用于“捕捉”需求，也可用于“收集灵感”）

---

规范审核

一种专门的循环模式，用于生成和维护规范文件，并强制执行质量规则。确保规范专注于行为结果（而非实现细节），主题范围恰当（“一句话不含‘和’”），以及文件命名规范一致。

何时使用： 在编写或更新规范后，运行规范模式以确保所有规范文件的一致性和整洁性。

具体功能：

• 遍历现有的 specs/* 文件
• 强制执行质量规则：仅关注行为结果，不得包含代码块或实现细节
• 使用“一句话不含‘和’”测试验证主题范围是否恰当
• 根据 specs/README.md 的要求，在必要时创建新的规范文件
• 统一文件命名格式：<整数>-文件名.md（如 01-range-optimization.md）

使用方法： 在你的循环脚本中添加 specs 参数，选择 PROMPT_specs.md：

./loop.sh specs        # 规范模式，无限次迭代
./loop.sh specs 3      # 规范模式，最多迭代3次

如何将规范模式加入 loop.sh： 在参数解析部分插入一个新的 elif 分支：

# 解析参数
if [ "$1" = "plan" ]; then
    # 计划模式
    MODE="plan"
    PROMPT_FILE="PROMPT_plan.md"
    MAX_ITERATIONS=${2:-0}
elif [ "$1" = "specs" ]; then        # ← 添加这一段
    # 规范模式
    MODE="specs"
    PROMPT_FILE="PROMPT_specs.md"
    MAX_ITERATIONS=${2:-0}
elif [[ "$1" =~ ^[0-9]+$ ]]; then
    # 构建模式，设置最大迭代次数
    ...

如何将规范模式加入 loop_streamed.sh： 同样在相同位置添加 elif 分支。其余部分（流式处理、parse_stream.js 管道）保持不变。

相关文件： PROMPT_specs.md

PROMPT_specs.md 模板

备注：

• 规范定义的是要验证的“内容”（即结果），而不是“如何实现”（即方法）。实现细节由 Ralph 在构建阶段决定。

0a. 使用最多250个并行的 Sonnet 子代理研究 `specs/*` 文件，以了解应用程序的规范。

1. 确定待完成的工作（JTBD）→ 将每个 JTBD 分解为相关的主题 → 利用子代理从 URL 加载信息到上下文中 → LLM 理解 JTBD 的相关主题：子代理为每个主题撰写 specs/FILENAME.md。

## 规则（不适用于 `specs/README.md`）

999. 切勿添加代码块或建议变量应如何命名。这些将由 Ralph 决定。
9999.
- 接受标准（在规范中）= 行为结果，可观察到的结果
例如：
✓ “从任何上传的图像中提取5-10种主色调”
✓ “在100毫秒内处理小于5MB的图像”
✓ “处理特殊情况：灰度图、单色图、透明背景”
- 测试要求（在计划中）= 由接受标准推导出的验证点
例如：
✓ “所需测试：提取5-10种颜色，性能<100ms”
- 实现方案（由 Ralph 决定）= 技术决策
避免的例子：
✗ “使用K-means聚类算法，迭代3次”

99999. 主题范围测试：“一句话不含‘和’”
你能用一句话描述相关主题，而不将不相关的功能混在一起吗？
推荐示例：
✓ “色彩提取系统分析图像以识别主色调”
避免示例：
✗ “用户系统负责身份验证、个人资料管理和计费” → 这涉及3个主题
如果需要用“和”来描述功能，那很可能就是多个主题了

99999999. 关键：明确要验证的内容（结果），而不是实现方式（方法）。这遵循“让Ralph做Ralph”的原则——Ralph在拥有清晰成功信号的情况下决定实现细节。
99999999999. 对所有现有文件应用上述规则，使用最多100个并行的 Sonnet 子代理在 @specs 中执行（除 README.md 外），并根据 `specs/README.md` 的要求创建新文件。文件名应遵循以下命名规范：<整数>-文件名.md，例如 01-range-optimization.md、02-adaptive-behavior.md 等。

— 由 @terry-xyz · @blackrosesxyz 贡献

---

逆向工程旧项目以生成规范

在全新项目中直接使用规范很容易，但在已有项目的环境中工作时，就需要采取不同的方法。因此，你需要将现有代码的实现逆向转化为规范，才能开始运用 Ralph 的工作流程。

何时使用： 你接手或加入了一个没有规范的代码库。你想在原本未使用 Ralph 构建的项目上使用 Ralph。你需要为现有的旧项目添加新功能。

调用方法： “使用 PROMPT_reverse_engineer_specs.md 逆向工程 [主题/领域] 的规范”

流程：

1. 使用 PROMPT_reverse_engineer_specs.md 指令代理指向现有代码库 →
2. 代理调查代码（具备实现知识）→
3. 代理编写描述实际行为的规范（不涉及实现细节）→
4. 规范存入 specs/ 目录 →
5. 根据需要重复此过程，直至所有规范完成 →
6. 按照常规的 Ralph 流程（计划→构建）基于已记录的基准继续推进

你可以采用代理编排模式，其中子代理负责逆向工程，而编排者熟悉“关注主题”理念：

• 覆盖整个领域： 告诉编排者识别领域内的所有主题，然后启动子代理为每个主题创建完整的规范。
• 按任务范围覆盖： 提供你即将执行的具体任务，让代理分析代码库，找出相关主题，然后为每个主题创建或更新相应的规范。

无需修改现有的提示文件——这只是额外的补充。生成的规范与 Ralph 在计划和构建阶段已经使用的格式相同。

考虑事项

• 单体仓库结构： 可能需要将逆向工程的范围限定在特定的包或服务上，而不是整个仓库。请将代理指向相关的子目录。
• 整个领域的规格生成： 为整个领域生成规格是一项较大的投入——如果你们团队正在将 Ralph 作为标准工作流程采用，则值得这样做。
• 快速开发或小规模变更： 小规模的代码变更可能会与生成的规格产生偏差。需提前决定团队是重新运行逆向工程以保持规格的最新状态，还是接受暂时的偏差。
• 重构后规格过时： 一旦 Ralph 基于逆向工程生成的规格构建新功能，重大重构可能会悄然使这些规格失效。对于改动频繁的区域，应定期重新运行逆向工程。
• 主题粒度： 该提示严格要求“每份规格只描述一个主题”。在大型代码库中，如何划定主题边界是一个需要权衡的问题——划分得太宽会导致规格过于臃肿，而划分得太细则会陷入文件过多的困境。可以先从粗略的划分开始，再根据需要进行拆分。
• Bug 成为规格： 该提示有意将有缺陷的行为记录为定义行为。逆向工程生成的规格描述的是“现状”，而非“应有的状态”。对于期望的行为变更，应单独编写新的规格。
• 大型代码库的 Token 成本： 使用子代理进行全面的代码追踪可能会消耗大量 Token。建议首先将范围限定在你实际计划修改的区域。

与核心理念的兼容性

原则	是否保持？	如何实现
确定性设置	✅ 是	规格是书面化的产物（已知状态），而非临时性的上下文；它包含了代码中的所有缺陷。
上下文效率	⚠️ 部分	必须在整个团队的文化中全面推行
记录“为什么”	⚠️ 部分	并非所有已实现的代码都包含背后的“为什么”，只有明确表达“为什么”的注释才会被记录下来。
让 Ralph 来做 Ralph	✅ 是	关注的主题仍然由 Ralph 选择。
计划是可丢弃的	✅ 是	规格提供了稳定的基线；计划会基于已记录的事实重新生成
简洁至上	✅ 是	提供了对整个规格的概览视图。

PROMPT_reverse_engineer_specs.md 模板

说明：

• 记录的是代码的实际行为（包括 Bug），而非预期行为
• 分两阶段进行：第一阶段在完全访问代码的情况下进行调研，第二阶段在不包含任何实现细节的情况下编写规格
• 每份规格只描述一个主题，通过“一句话中不含‘和’”的测试来强制执行
• 当前的子代理名称假定使用 Claude

文件： PROMPT_reverse_engineer_specs.md

0a. 使用最多 250 个并行的 Sonnet 子代理研究 `specs/*`，以了解现有的规格文档。
0b. 研究 `src/*` 以理解代码库。使用最多 500 个并行的 Sonnet 子代理进行读取和搜索。将 `src/lib` 视为项目的标准库，用于共享工具和组件。

1. 对于每个分配（或发现）的主题，逆向工程源代码并在 `specs/` 中生成一份规格文档。对于复杂的追踪任务，使用 Opus 子代理，并尽量做到精简。在编写规格之前，务必先搜索确认是否已经存在针对该主题的规格。
2. 每份规格仅描述一个主题。必须通过“一句话中不含‘和’”的测试。如果“和”连接了不相关的能力，则应将其拆分为多个规格。
3. **两阶段流程：** 第一阶段（调研）——追踪每一个入口点、分支和代码路径，直到其终止。绘制数据流、副作用、状态变化、错误处理、并发控制、配置驱动的路径以及隐式行为。第二阶段（输出）——完全不包含任何实现细节。不得出现函数、类、变量名、文件路径、库或框架引用。即使是由不同团队在不同技术栈上实现，也应能够仅凭这份规格完成复现。
4. **记录现实，而非意图。** Bug 也是功能的一部分。绝不能添加代码本身并未实现的行为，也不得提出改进建议。如果源代码中的注释与其行为相矛盾，则应记录代码的实际行为，忽略该注释。
5. **范围边界：** 当追踪过程超出当前主题范围时，应立即停止。仅记录跨越边界的输入和输出。测试方法：“如果不改变我的主题结果，这件事能否发生？”如果答案是肯定的，则说明它超出了当前主题范围。
6. **共享行为：** 在每份规格中完整内联描述（自包含）。记录共享主题以便跨规格跟踪。共享行为还应拥有其独立的规范文档。
7. **规格格式：** 使用 Markdown 格式，保存在 `specs/` 目录下。每份规格应包括：主题陈述、范围（包含的内容及边界）、数据契约、行为（按执行顺序排列）以及状态转换。在文中标注值得注意或出乎意料的行为、不可达路径以及跨主题的共享行为。从源代码注释中提取理由（去除实现相关的引用）。文件命名格式为：`specs/NN-kebab-case.md`（例如：`01-session-management.md`）。
8. 规格完成后并经过验证后，执行 `git add -A`，然后提交一条描述新增或更新了哪些规格的提交信息。提交完成后，执行 `git push`。
99999. **最终确认前的全面检查清单：** 每一个入口点都已被记录；每一处分支都被追踪至终点；每一个数据契约都已明确；所有的副作用均按执行顺序列出；每一条错误路径（被捕获、传播或忽略）都已记录；所有配置驱动的路径均已追踪；并发行为的结果也被记录；不可达路径已被标记；值得注意或出乎意料的行为也被标记；输出中没有任何实现细节。若有任何一项缺失，需重新进行追踪。
999999. 代码才是事实的唯一来源。如果规格与代码不一致，需使用 Opus 4.6 子代理更新规格。
9999999. 维护单一的事实来源，避免重复规格。应优先更新现有规格，而非创建新规格。
99999999. 每当了解到关于项目的新信息时，应使用子代理更新 @AGENTS.md 文件，但内容应简明扼要，仅限于操作层面——不得包含状态更新或进度报告。
999999999. 对于解释为何必须保留某些行为的源代码注释（如出于法规、兼容性或故意设计等原因），应提取其理由，同时去除实现相关的引用。过时的注释不应纳入规格。
9999999999. 应记录所有配置驱动的路径，而不仅仅是当前生效的那一条。
99999999999. 如果发现 `specs/*` 中存在不一致之处，则应使用带有“ultrathink”模式的 Opus 4.6 子代理来更新规格。

— 由 Jake Cukjati 贡献 · @Byte0fCode · @jackstine

Ralph Playbook 快速上手指南

Ralph Playbook 是一套基于 Geoffrey Huntley 提出的 "Ralph" 模式优化的 AI 编程工作流。它通过“规划”与“构建”双模式循环，利用子代理（Subagents）管理上下文，实现从需求定义到代码落地的自动化闭环。

环境准备

在开始之前，请确保你的开发环境满足以下要求：

• 操作系统：macOS 或 Linux（Windows 用户建议使用 WSL2）。
• 核心依赖：
  • Claude Code (或兼容的 CLI 工具)：需已安装并配置好 API Key。
  • git：用于版本控制和回滚。
  • bash：用于运行循环脚本。
• 沙箱环境（强烈推荐）：
  • 由于 Ralph 需要以 --dangerously-skip-permissions 模式运行以绕过权限确认，必须在隔离环境中执行以防安全风险。
  • 本地方案：Docker Desktop。
  • 云端方案：E2B、Fly Sprites 或其他支持临时沙箱的服务。
• 项目结构：建议在一个空的或现有的 Git 仓库根目录下操作。

安装步骤

Ralph Playbook 本质上是一组约定和规范，而非单一安装包。请按以下步骤初始化：

1. 克隆或创建项目结构 在项目根目录下创建必要的配置文件和目录结构：

   mkdir -p specs src
   touch PROMPT.md AGENTS.md IMPLEMENTATION_PLAN.md
   git init
   

2. 配置核心文件 根据当前阶段（规划或构建），编辑 PROMPT.md。

   • 规划模式 (PLANNING)：提示词应侧重于差距分析（Specs vs Code）并生成待办列表。
   • 构建模式 (BUILDING)：提示词应侧重于从计划中选取任务、实施代码、运行测试并提交。

   同时，保持 AGENTS.md 初始为空或仅包含基础构建/测试命令，随迭代动态更新。

3. 创建循环脚本 (loop.sh) 在项目根目录创建 loop.sh，这是驱动 Ralph 的核心引擎。最简版本如下：

   #!/bin/bash
   while :; do 
     cat PROMPT.md | claude --dangerously-skip-permissions
     # 在此处添加逻辑判断任务是否完成，若完成则跳出循环或重新加载上下文
     # 实际生产中建议增加错误处理和上下文清理逻辑
   done
   

   赋予执行权限：

   chmod +x loop.sh
   

4. 设置沙箱（可选但推荐） 如果使用 Docker，请创建一个包含必要构建工具（Node.js, Python, Go 等）的基础镜像，并在其中运行上述脚本。

基本使用

Ralph 的工作流分为两个主要阶段：定义需求 和 运行循环。

第一阶段：定义需求 (Phase 1)

在与 LLM 的对话中（非自动循环模式下），将高层级的用户需求（JTBD）拆解为具体的关注点（Topic of Concern），并为每个关注点生成规范文档。

1. 拆分任务：将一个大的 JTBD 拆分为多个独立的主题（例如：“图片收集”、“颜色提取”）。
   • 原则：每个主题应能用不含“和/与”的一句话描述。
2. 生成规范：让 AI 为每个主题编写 Markdown 规范文件，保存至 specs/ 目录。

   # specs/color-extraction.md
   ## 目标
   分析上传的图片并识别主导颜色...
   

第二阶段：运行 Ralph 循环 (Phase 2 & 3)

根据当前是否有有效的实施计划，切换 PROMPT.md 的内容来启动循环。

模式 A：规划模式 (PLANNING)

适用场景：项目初期或计划已过时。

1. 更新 PROMPT.md 为规划指令（侧重差距分析，不写代码）。
2. 运行循环：

   ./loop.sh
   

3. 结果：AI 将读取 specs/* 和现有代码，生成或更新 IMPLEMENTATION_PLAN.md，列出优先级的待办任务列表。此时不会修改源代码。

模式 B：构建模式 (BUILDING)

适用场景：已有明确的 IMPLEMENTATION_PLAN.md。

1. 更新 PROMPT.md 为构建指令（侧重执行任务、运行测试、提交代码）。
2. 确保 AGENTS.md 中包含项目特定的构建/测试命令（如 npm test, go build），以形成“背压”（Backpressure）机制。
3. 运行循环：

   ./loop.sh
   

4. 循环内部流程：
   • 定向：子代理读取 specs 和 IMPLEMENTATION_PLAN.md。
   • 选择：挑选下一个最高优先级的任务。
   • 调查：检查相关源码（不假设未实现）。
   • 实施：编写代码。
   • 验证：运行测试/构建（若失败则自我修正）。
   • 更新：标记任务完成，更新计划和 AGENTS.md。
   • 提交：Git Commit。
   • 重置：清空上下文，开始下一次迭代。

关键操作提示

• 观察与调整：初次运行时，请密切观察输出。如果 Ralph 重复犯错，不要直接干预代码，而是更新 AGENTS.md 或添加辅助工具函数来引导它。
• 计划重置：如果发现 Ralph 偏离轨道或计划混乱，直接删除 IMPLEMENTATION_PLAN.md 并重新运行规划模式循环。成本很低，但能纠正方向。
• 紧急停止：随时按 Ctrl+C 终止循环。使用 git reset --hard 可快速回滚到上一次成功提交的状态。