Ralph 最小化 PROMPT.md 实战用一份指令文件驱动 Claude Code 自主开发 CLI 待办工具【免费下载链接】ralph-claude-codeAutonomous AI development loop for Claude Code with intelligent exit detection项目地址: https://gitcode.com/GitHub_Trending/ra/ralph-claude-code本篇技术指南以 ralph-claude-code 仓库中的真实示例examples/simple-cli-tool/.ralph/PROMPT.md为主体剖析 Ralph面向 Claude Code 的自主 AI 开发循环中.ralph/PROMPT.md的编写方法它承载项目愿景、技术栈、命令规格、数据格式与质量标准的完整闭环。读完本文你将掌握用一份刚刚好的 PROMPT.md 驱动 Ralph 自主完成一个 Node.js CLI 待办工具的开发并理解它与fix_plan.md、specs/、AGENT.md的分工边界以及何时该为项目补充更多配置文件。示例项目是什么一个最小可跑的 Ralph 配置examples/simple-cli-tool/是仓库内置的最小化示例展示的是一个基于 Node.js 的命令行待办应用todo app。它的整套 Ralph 配置只有两个文件构成少即是多的示范simple-cli-tool/ ├── .ralph/ │ ├── PROMPT.md # 项目目标与原则 │ └── fix_plan.md # 任务清单 ├── .ralphrc # 配置自动生成 └── README.md # 示例说明示例的 README 明确点出它想证明的三件事最小化的 PROMPT.md——只需为聚焦项目提供恰到好处的上下文具体的 fix_plan.md——可执行、有优先级的任务列表不需要 specs/ 目录——项目足够简单PROMPT.md 已经覆盖全部需求。这份.ralph/PROMPT.md之所以能独立撑起一个项目是因为它完整覆盖了 Ralph 每轮循环决策所需的五类信息角色定位Context、目标Current Objectives、技术约束Technology Stack、设计原则Key Principles、行为规格Command Specifications 与 Data Format以及验收标准Quality Standards。下面逐节拆解。PROMPT.md 在 Ralph 循环中的位置与作用在深入逐节讲解之前先明确这个文件在整套系统中的位置。Ralph 是一个持续循环调用 Claude Code 的自主开发循环见 CLAUDE.md而.ralph/PROMPT.md正是每一轮循环都要读一遍的主提示词。从 ralph_loop.sh 的源码可以确认它的核心地位循环脚本在第 52 行定义PROMPT_FILE$RALPH_DIR/PROMPT.md即默认指向项目.ralph/目录下的PROMPT.md执行每一轮 Claude Code 调用时脚本把该文件作为 stdin 喂给 CLI见ralph_loop.sh中portable_timeout ... $CLAUDE_CODE_CMD $PROMPT_FILE的调用链命令行提供-p, --prompt FILE选项可以覆盖默认提示词文件ralph_loop.sh中解析-p|--prompt)默认值即.ralph/PROMPT.md详见 CLI_OPTIONS.md。此外lib/file_protection.sh将.ralph/PROMPT.md列为受保护文件——Ralph 的自动化清理、重构流程绝不会删除或覆盖它因为它一旦损坏整个循环就会停摆。而lib/enable_core.sh在ralph enable时会用智能默认值生成该文件供你在此基础上定制。用户指南 02-understanding-ralph-files.md 用一张表概括了它的读写关系文件自动生成谁写谁读你应该…….ralph/PROMPT.md是带智能默认值你定制Ralph 每轮循环都读审阅并定制项目目标同一个文档还给出了内容边界该放什么项目描述与目标、关键原则或约束、技术栈与框架、质量标准不该放什么逐步实现任务 → 放 fix_plan.md详细 API 规格 → 放 specs/构建命令 → 放 AGENT.md。逐节拆解示例 PROMPT.md 的写法下面按原文结构逐节分析说明每一节解决什么问题、为什么这样写并标注可复用的写法要点。Context一句话定位 AI 的角色与项目## Context You are Ralph, building a command-line todo application in Node.js. This is a personal productivity tool that stores tasks locally and provides simple commands for task management.这里做两件事第一确立身份——你是 Ralph正在构建……第二一句话说明项目是什么、为谁服务个人生产力工具、数据存在哪里本地存储。这为后续所有决策提供了判断基准任何实现都应服务于本地、简单、命令行这三个隐含约束。对比仓库默认模板 templates/PROMPT.md 中的 ContextYou are Ralph, an autonomous AI development agent working on a [YOUR PROJECT NAME] project.可以看到示例正是把模板占位符替换成具体信息的范本。Current Objectives用 4 条可验证目标锁定范围## Current Objectives 1. Create a CLI that supports add, list, complete, and delete commands 2. Store todos in ~/.todos.json with automatic file creation 3. Provide clear, helpful output for all operations 4. Handle errors gracefully with actionable messages四条目标没有一条是做得更好这类空话而是可验证的功能承诺四个命令、一个数据文件路径~/.todos.json且要自动创建、输出可读性、错误处理策略。目标即验收线索——Ralph 每轮循环都能对照它判断是否已经做到。Technology Stack用技术选型消灭自由发挥## Technology Stack - Node.js 18 - commander.js for CLI argument parsing - Native fs/promises for file operations - Jest for testing技术栈是约束力最强的部分。指定commander.js而非随便挑一个参数解析库指定fs/promises而非引入数据库依赖指定 Jest 统一测试框架——这直接决定代码风格、依赖清单与测试命令让 AI 不必在技术选型上反复试探。写作指南 03-writing-requirements.md 也强调明确技术选型是好需求的核心特征之一。Key Principles用 4 条原则约束实现风格## Key Principles - Single responsibility: each command does one thing well - Fail gracefully: missing file empty list, not an error - Clear output: users should always know what happened - Testable: core logic separated from CLI layer原则解决怎么做的问题单一职责约束每个命令只做一件事文件缺失 空列表而非报错直接规定了容错语义用户永远知道发生了什么约束输出设计核心逻辑与 CLI 层分离约束代码架构为 Jest 单测铺路。这些原则会在 Ralph 无从决策时成为默认答案。Command Specifications把四条命令写成可验收规格规格部分是文档的行为合同逐条规定了命令的输入、行为与输出todo add task description新增任务ID 自动递增输出格式Added task #3: Buy groceries——注意它同时给出了输出模板Added task #id: text与真实示例AI 可以据此精确复刻输出风格。todo list展示所有任务并带状态标记待办显示[ ]已完成显示[x]空列表时输出No tasks yet。todo complete id将任务标记为完成若 ID 不存在必须报错——这是显式的错误处理要求。todo delete id永久删除任务若 ID 不存在必须报错。这四条规格合起来定义了完整的功能面增、查、改、删全齐且每条都有输出或错误语义。这正是写作指南中所说的具体任务好于模糊任务的实例——Add user auth这种模糊表述会被todo complete id这样的规格完胜。Data Format用 JSON 样例钉死数据结构{ nextId: 4, tasks: [ {id: 1, text: Buy groceries, completed: false}, {id: 2, text: Call mom, completed: true} ] }数据格式是存储层的事实标准其设计有讲究顶层nextId字段解决了ID 自动递增的实现难题——删除任务后 ID 不回退靠游标值而非最大 ID 1实现每条任务只有三个字段id数值、text字符串、completed布尔结构极简天然可 JSON 序列化示例数据同时演示了completed: false与completed: true两种状态以及nextId与现存任务 ID 的关系现存最大 ID 为 2nextId为 4说明中间曾删除过 ID 为 3 的任务——这本身就是对ID 递增不回退语义的隐性验证。这份样例可以直接作为单元测试的 fixture也符合fs/promises JSON 文件的存储方案。Quality Standards定义完成的验收线## Quality Standards - All commands have --help documentation - Unit tests for storage module - Integration tests for CLI commands三条标准分别覆盖文档完备性--help、存储层单测、CLI 层集成测试与 Technology Stack 中 Jest 的选择闭环呼应。值得一提的是默认模板 templates/PROMPT.md 对测试有更强的策略性约束——每轮循环约 20% 精力用于测试、只为新功能写测试、不把补充覆盖率当忙碌工作而示例针对小项目选择了更简明的表述体现配置与项目复杂度匹配的思想。示例如何与 fix_plan.md、specs/ 协同示例刻意没有附带specs/目录并说明理由项目简单到 PROMPT.md 已覆盖全部需求时specs/ 就是过度设计。与之形成对比的是仓库中另一个示例 examples/rest-api/README.md——bookstore REST API 需要精确的请求/响应格式、校验规则、错误码、分页行为于是把specs/api.md加进.ralph/specs/而 PROMPT.md 保持高层。何时该补充更多文件示例 README 给出了判断标准需要复杂命令行为文档时需要数据格式规范时需要外部服务集成细节时满足其一就考虑在.ralph/specs/下添加规格文件。而对 todo 应用这种规模fix_plan.md按优先级分三组任务即可驱动开发P1 打地基、P2 做核心功能、P3 打磨具体结构可参考模板 templates/fix_plan.md。文件之间的关系可以用 02-understanding-ralph-files.md 中的链路概括PROMPT.md高层目标与原则→specs/需要时的详细需求→fix_plan.mdRalph 逐条执行的具体任务→AGENT.md构建/测试命令Ralph 自动维护。在真实项目中使用这份配置将示例落地为真实项目的步骤源自 examples/simple-cli-tool/README.md# 1. 复制示例目录到新位置 cp -r examples/simple-cli-tool ~/my-todo-app cd ~/my-todo-app # 2. 初始化 git 与 npm git init npm init -y # 3. 运行 Ralph监视模式 ralph --monitor运行前需确认已按 01-quick-start.md 完成ralph enable或在复制后重新 enable以生成项目专属.ralphrc。开启循环后Ralph 会在每轮读取这份 PROMPT.md对照 Command Specifications 与 Data Format 逐步实现add/list/complete/delete四个命令、~/.todos.json存储与错误处理并通过输出格式、--help与测试要求完成自检。如果需要为其他项目定制模板 templates/PROMPT.md 提供了完整的超集结构含状态上报块---RALPH_STATUS---、退出场景、受保护文件声明等示例则是删到只剩必要内容的最小形态——两者对比阅读可以帮你把握该留多少的尺度。小结一份优秀 PROMPT.md 的检查清单综合本示例与仓库写作指南一份合格的 PROMPT.md 应满足角色与项目一句话说清——Context 让 AI 知道自己在做什么、为谁做目标是可验证的功能承诺——而非做得更好这类模糊表述技术栈明确——消灭选型自由发挥统一依赖与测试框架原则约束实现风格——容错语义、输出要求、架构要求都写清楚行为规格到输出模板级——命令的输入、行为、报错、输出格式全部可验收数据格式给真实样例——可直接作测试 fixture质量标准呼应技术栈——测试、文档要求闭环与 fix_plan.md、specs/ 边界清晰——任务放计划、细节放规格、构建命令放 AGENT.md。按这份清单即使是一个全新的 CLI 工具项目也能像示例一样用一份 PROMPT.md就驱动 Ralph 进入自主开发循环——这正是本示例想传达的核心方法论。【免费下载链接】ralph-claude-codeAutonomous AI development loop for Claude Code with intelligent exit detection项目地址: https://gitcode.com/GitHub_Trending/ra/ralph-claude-code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Ralph 最小化 PROMPT.md 实战：用一份指令文件驱动 Claude Code 自主开发 CLI 待办工具
Ralph 最小化 PROMPT.md 实战用一份指令文件驱动 Claude Code 自主开发 CLI 待办工具【免费下载链接】ralph-claude-codeAutonomous AI development loop for Claude Code with intelligent exit detection项目地址: https://gitcode.com/GitHub_Trending/ra/ralph-claude-code本篇技术指南以 ralph-claude-code 仓库中的真实示例examples/simple-cli-tool/.ralph/PROMPT.md为主体剖析 Ralph面向 Claude Code 的自主 AI 开发循环中.ralph/PROMPT.md的编写方法它承载项目愿景、技术栈、命令规格、数据格式与质量标准的完整闭环。读完本文你将掌握用一份刚刚好的 PROMPT.md 驱动 Ralph 自主完成一个 Node.js CLI 待办工具的开发并理解它与fix_plan.md、specs/、AGENT.md的分工边界以及何时该为项目补充更多配置文件。示例项目是什么一个最小可跑的 Ralph 配置examples/simple-cli-tool/是仓库内置的最小化示例展示的是一个基于 Node.js 的命令行待办应用todo app。它的整套 Ralph 配置只有两个文件构成少即是多的示范simple-cli-tool/ ├── .ralph/ │ ├── PROMPT.md # 项目目标与原则 │ └── fix_plan.md # 任务清单 ├── .ralphrc # 配置自动生成 └── README.md # 示例说明示例的 README 明确点出它想证明的三件事最小化的 PROMPT.md——只需为聚焦项目提供恰到好处的上下文具体的 fix_plan.md——可执行、有优先级的任务列表不需要 specs/ 目录——项目足够简单PROMPT.md 已经覆盖全部需求。这份.ralph/PROMPT.md之所以能独立撑起一个项目是因为它完整覆盖了 Ralph 每轮循环决策所需的五类信息角色定位Context、目标Current Objectives、技术约束Technology Stack、设计原则Key Principles、行为规格Command Specifications 与 Data Format以及验收标准Quality Standards。下面逐节拆解。PROMPT.md 在 Ralph 循环中的位置与作用在深入逐节讲解之前先明确这个文件在整套系统中的位置。Ralph 是一个持续循环调用 Claude Code 的自主开发循环见 CLAUDE.md而.ralph/PROMPT.md正是每一轮循环都要读一遍的主提示词。从 ralph_loop.sh 的源码可以确认它的核心地位循环脚本在第 52 行定义PROMPT_FILE$RALPH_DIR/PROMPT.md即默认指向项目.ralph/目录下的PROMPT.md执行每一轮 Claude Code 调用时脚本把该文件作为 stdin 喂给 CLI见ralph_loop.sh中portable_timeout ... $CLAUDE_CODE_CMD $PROMPT_FILE的调用链命令行提供-p, --prompt FILE选项可以覆盖默认提示词文件ralph_loop.sh中解析-p|--prompt)默认值即.ralph/PROMPT.md详见 CLI_OPTIONS.md。此外lib/file_protection.sh将.ralph/PROMPT.md列为受保护文件——Ralph 的自动化清理、重构流程绝不会删除或覆盖它因为它一旦损坏整个循环就会停摆。而lib/enable_core.sh在ralph enable时会用智能默认值生成该文件供你在此基础上定制。用户指南 02-understanding-ralph-files.md 用一张表概括了它的读写关系文件自动生成谁写谁读你应该…….ralph/PROMPT.md是带智能默认值你定制Ralph 每轮循环都读审阅并定制项目目标同一个文档还给出了内容边界该放什么项目描述与目标、关键原则或约束、技术栈与框架、质量标准不该放什么逐步实现任务 → 放 fix_plan.md详细 API 规格 → 放 specs/构建命令 → 放 AGENT.md。逐节拆解示例 PROMPT.md 的写法下面按原文结构逐节分析说明每一节解决什么问题、为什么这样写并标注可复用的写法要点。Context一句话定位 AI 的角色与项目## Context You are Ralph, building a command-line todo application in Node.js. This is a personal productivity tool that stores tasks locally and provides simple commands for task management.这里做两件事第一确立身份——你是 Ralph正在构建……第二一句话说明项目是什么、为谁服务个人生产力工具、数据存在哪里本地存储。这为后续所有决策提供了判断基准任何实现都应服务于本地、简单、命令行这三个隐含约束。对比仓库默认模板 templates/PROMPT.md 中的 ContextYou are Ralph, an autonomous AI development agent working on a [YOUR PROJECT NAME] project.可以看到示例正是把模板占位符替换成具体信息的范本。Current Objectives用 4 条可验证目标锁定范围## Current Objectives 1. Create a CLI that supports add, list, complete, and delete commands 2. Store todos in ~/.todos.json with automatic file creation 3. Provide clear, helpful output for all operations 4. Handle errors gracefully with actionable messages四条目标没有一条是做得更好这类空话而是可验证的功能承诺四个命令、一个数据文件路径~/.todos.json且要自动创建、输出可读性、错误处理策略。目标即验收线索——Ralph 每轮循环都能对照它判断是否已经做到。Technology Stack用技术选型消灭自由发挥## Technology Stack - Node.js 18 - commander.js for CLI argument parsing - Native fs/promises for file operations - Jest for testing技术栈是约束力最强的部分。指定commander.js而非随便挑一个参数解析库指定fs/promises而非引入数据库依赖指定 Jest 统一测试框架——这直接决定代码风格、依赖清单与测试命令让 AI 不必在技术选型上反复试探。写作指南 03-writing-requirements.md 也强调明确技术选型是好需求的核心特征之一。Key Principles用 4 条原则约束实现风格## Key Principles - Single responsibility: each command does one thing well - Fail gracefully: missing file empty list, not an error - Clear output: users should always know what happened - Testable: core logic separated from CLI layer原则解决怎么做的问题单一职责约束每个命令只做一件事文件缺失 空列表而非报错直接规定了容错语义用户永远知道发生了什么约束输出设计核心逻辑与 CLI 层分离约束代码架构为 Jest 单测铺路。这些原则会在 Ralph 无从决策时成为默认答案。Command Specifications把四条命令写成可验收规格规格部分是文档的行为合同逐条规定了命令的输入、行为与输出todo add task description新增任务ID 自动递增输出格式Added task #3: Buy groceries——注意它同时给出了输出模板Added task #id: text与真实示例AI 可以据此精确复刻输出风格。todo list展示所有任务并带状态标记待办显示[ ]已完成显示[x]空列表时输出No tasks yet。todo complete id将任务标记为完成若 ID 不存在必须报错——这是显式的错误处理要求。todo delete id永久删除任务若 ID 不存在必须报错。这四条规格合起来定义了完整的功能面增、查、改、删全齐且每条都有输出或错误语义。这正是写作指南中所说的具体任务好于模糊任务的实例——Add user auth这种模糊表述会被todo complete id这样的规格完胜。Data Format用 JSON 样例钉死数据结构{ nextId: 4, tasks: [ {id: 1, text: Buy groceries, completed: false}, {id: 2, text: Call mom, completed: true} ] }数据格式是存储层的事实标准其设计有讲究顶层nextId字段解决了ID 自动递增的实现难题——删除任务后 ID 不回退靠游标值而非最大 ID 1实现每条任务只有三个字段id数值、text字符串、completed布尔结构极简天然可 JSON 序列化示例数据同时演示了completed: false与completed: true两种状态以及nextId与现存任务 ID 的关系现存最大 ID 为 2nextId为 4说明中间曾删除过 ID 为 3 的任务——这本身就是对ID 递增不回退语义的隐性验证。这份样例可以直接作为单元测试的 fixture也符合fs/promises JSON 文件的存储方案。Quality Standards定义完成的验收线## Quality Standards - All commands have --help documentation - Unit tests for storage module - Integration tests for CLI commands三条标准分别覆盖文档完备性--help、存储层单测、CLI 层集成测试与 Technology Stack 中 Jest 的选择闭环呼应。值得一提的是默认模板 templates/PROMPT.md 对测试有更强的策略性约束——每轮循环约 20% 精力用于测试、只为新功能写测试、不把补充覆盖率当忙碌工作而示例针对小项目选择了更简明的表述体现配置与项目复杂度匹配的思想。示例如何与 fix_plan.md、specs/ 协同示例刻意没有附带specs/目录并说明理由项目简单到 PROMPT.md 已覆盖全部需求时specs/ 就是过度设计。与之形成对比的是仓库中另一个示例 examples/rest-api/README.md——bookstore REST API 需要精确的请求/响应格式、校验规则、错误码、分页行为于是把specs/api.md加进.ralph/specs/而 PROMPT.md 保持高层。何时该补充更多文件示例 README 给出了判断标准需要复杂命令行为文档时需要数据格式规范时需要外部服务集成细节时满足其一就考虑在.ralph/specs/下添加规格文件。而对 todo 应用这种规模fix_plan.md按优先级分三组任务即可驱动开发P1 打地基、P2 做核心功能、P3 打磨具体结构可参考模板 templates/fix_plan.md。文件之间的关系可以用 02-understanding-ralph-files.md 中的链路概括PROMPT.md高层目标与原则→specs/需要时的详细需求→fix_plan.mdRalph 逐条执行的具体任务→AGENT.md构建/测试命令Ralph 自动维护。在真实项目中使用这份配置将示例落地为真实项目的步骤源自 examples/simple-cli-tool/README.md# 1. 复制示例目录到新位置 cp -r examples/simple-cli-tool ~/my-todo-app cd ~/my-todo-app # 2. 初始化 git 与 npm git init npm init -y # 3. 运行 Ralph监视模式 ralph --monitor运行前需确认已按 01-quick-start.md 完成ralph enable或在复制后重新 enable以生成项目专属.ralphrc。开启循环后Ralph 会在每轮读取这份 PROMPT.md对照 Command Specifications 与 Data Format 逐步实现add/list/complete/delete四个命令、~/.todos.json存储与错误处理并通过输出格式、--help与测试要求完成自检。如果需要为其他项目定制模板 templates/PROMPT.md 提供了完整的超集结构含状态上报块---RALPH_STATUS---、退出场景、受保护文件声明等示例则是删到只剩必要内容的最小形态——两者对比阅读可以帮你把握该留多少的尺度。小结一份优秀 PROMPT.md 的检查清单综合本示例与仓库写作指南一份合格的 PROMPT.md 应满足角色与项目一句话说清——Context 让 AI 知道自己在做什么、为谁做目标是可验证的功能承诺——而非做得更好这类模糊表述技术栈明确——消灭选型自由发挥统一依赖与测试框架原则约束实现风格——容错语义、输出要求、架构要求都写清楚行为规格到输出模板级——命令的输入、行为、报错、输出格式全部可验收数据格式给真实样例——可直接作测试 fixture质量标准呼应技术栈——测试、文档要求闭环与 fix_plan.md、specs/ 边界清晰——任务放计划、细节放规格、构建命令放 AGENT.md。按这份清单即使是一个全新的 CLI 工具项目也能像示例一样用一份 PROMPT.md就驱动 Ralph 进入自主开发循环——这正是本示例想传达的核心方法论。【免费下载链接】ralph-claude-codeAutonomous AI development loop for Claude Code with intelligent exit detection项目地址: https://gitcode.com/GitHub_Trending/ra/ralph-claude-code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考