Ralph Development Instructions【免费下载链接】ralph-claude-codeAutonomous AI development loop for Claude Code with intelligent exit detection项目地址: https://gitcode.com/GitHub_Trending/ra/ralph-claude-codeContextYou are Ralph, an autonomous AI development agent building a CLI todo application in Node.js.Current ObjectivesCreate a command-line todo app with add, list, complete, and delete commandsStore todos in a JSON file (~/.todos.json)Use commander.js for argument parsingInclude helpful --help outputWrite unit tests with JestKey PrinciplesKeep the code simple and readableUse async/await for file operationsProvide clear error messagesFollow Node.js best practices注意仓库模板 [templates/PROMPT.md](https://link.gitcode.com/i/28ea31d933ec765cc974a43cf30fa2ca) 还内置了 Claude 必须遵守的 ---RALPH_STATUS--- 状态块规范与 EXIT_SIGNAL 退出语义详见第五节启用后生成的 PROMPT.md 默认即包含这些约定。 ### 2.5 Step 4定义任务fix_plan.md 编辑 .ralph/fix_plan.md按优先级列出具体任务 markdown # Fix Plan - Todo CLI ## Priority 1: Core Structure - [ ] Set up package.json with dependencies (commander, jest) - [ ] Create src/index.js entry point with commander setup - [ ] Create src/storage.js for JSON file operations ## Priority 2: Commands - [ ] Implement todo add task description command - [ ] Implement todo list command with status indicators - [ ] Implement todo complete id command - [ ] Implement todo delete id command ## Priority 3: Polish - [ ] Add --help documentation for all commands - [ ] Handle edge cases (empty list, invalid IDs) - [ ] Write unit tests for storage module2.6 Step 5启动 Ralph 并监控ralph --monitor这会打开一个 tmux 会话左窗格Ralph 循环输出Claude 正在做什么右窗格实时监控仪表盘。启动后 Ralph 的行为链条为读取 PROMPT.md 与 fix_plan.md → 按优先级实现任务 → 创建文件、运行测试、更新 fix_plan.md → 持续循环直到退出条件满足。监控技巧CtrlB然后按D从 tmux 分离Ralph 继续后台运行tmux attach -t todo-cli重新挂载查看进度ralph --status查看当前循环状态。2.7 Step 6验收结果# 查看创建的文件 ls -la src/ # 检查更新后的 fix_plan.md cat .ralph/fix_plan.md # 运行 Ralph 写的测试 npm test # 试用新 CLI node src/index.js add Buy groceries node src/index.js list2.8 循环原理Read → Implement → Test → Update → Repeat官方文档给出的循环模型是Read加载 PROMPT.md 获取上下文、fix_plan.md 获取任务Implement实现优先级最高的未勾选任务Test运行测试并修复失败Update在 fix_plan.md 中勾选完成任务Repeat持续直到 EXIT_SIGNAL 被置为 true。在源码中这一循环由 ralph_loop.sh 驱动退出判定依赖.ralph/.exit_signals文件中的信号计数test_only_loops、done_signals、completion_indicators三类信号并叠加了三重安全网见第五节连续 5 次 EXIT_SIGNALtrue 时触发强制退出、强完成指标判定、以及电路熔断器兜底。2.9 常见问题官方 FAQRalph 提前停止了为什么检查.ralph/logs/中最近的日志常见原因包括达到速率限制等待重置、电路熔断器打开检测到卡死循环、所有任务已标记完成。Ralph 一直在跑测试却不实现功能fix_plan.md 可能太模糊。任务要具体、可执行差Improve the code好Add error handling for missing ~/.todos.json file之后如何添加新功能只需向.ralph/fix_plan.md追加新任务再次运行ralph --monitorRalph 会从上次停止的地方继续。三、Understanding Ralph Files.ralph/目录文件全解运行ralph-enable、ralph-import或ralph-setup后项目下会出现.ralph/目录。本节完整复现 02-understanding-ralph-files.md 的文件参考表并逐文件深入。3.1 文件参考总表文件自动生成谁写入谁读取你应当…….ralph/PROMPT.md是带智能默认值你定制Ralph 每个循环都读审阅并定制项目目标.ralph/fix_plan.md是可导入任务你 Ralph 更新Ralph 读并更新添加/修改具体任务.ralph/AGENT.md是检测构建命令Ralph 维护Ralph 读取构建/测试方式很少编辑自动维护.ralph/specs/创建空目录你按需添加文件Ralph 读取上下文当 PROMPT.md 不够详细时添加.ralph/specs/stdlib/创建空目录你添加可复用模式Ralph 读取约定添加共享模式与约定.ralphrc是项目感知通常保持原样Ralph 启动时读取很少编辑默认值合理.ralph/logs/自动创建Ralph 写日志你调试用不要编辑只读.ralph/status.json运行时创建Ralph 更新监控工具不要编辑只读3.2 PROMPT.md项目愿景目的Ralph 每个循环开始时读取的高层指令。应当包含项目描述与目标、关键原则或约束、技术栈与框架、质量标准。不应包含分步实现任务放 fix_plan.md、详细 API 规格放 specs/、构建命令放 AGENT.md。示例## Context You are Ralph, building a REST API for a bookstore inventory system. ## Key Principles - Use FastAPI with async database operations - Follow REST conventions strictly - Every endpoint needs tests - Document all API endpoints with OpenAPI从模板 templates/PROMPT.md 可以看到生成版本还包含两条对自主循环至关重要的硬性约定受保护文件Protected Files.ralph/整个目录与.ralphrc是 Ralph 的基础设施控制文件模板明确要求 Claude 在任何清理、重构、重构任务中都不得删除、移动、重命名或覆盖它们——删除这些文件会直接中断自主开发循环状态上报块---RALPH_STATUS---每次响应末尾必须输出固定格式的状态块Ralph 依赖它做退出判定详见第五节。3.3 fix_plan.md任务清单目的Ralph 逐个攻克的有序检查清单。关键特征Ralph 完成任务后把[ ]勾选为[x]Ralph 可能在工作中发现并追加新任务你可以随时添加、重排、删除任务任务越具体效果越好。良好任务结构## Priority 1: Foundation - [ ] Create database models for Book and Author - [ ] Set up SQLAlchemy with async support - [ ] Create Alembic migration for initial schema ## Priority 2: API Endpoints - [ ] POST /books - create a new book - [ ] GET /books - list all books with pagination - [ ] GET /books/{id} - get single book with author details糟糕的任务结构- [ ] Make the API work - [ ] Add features - [ ] Fix bugs模板 templates/fix_plan.md 给出了更完整的默认骨架High/Medium/Low Priority 分层、Completed 区、Notes 区以及一个特别的Optional 区——官方注释指出对应 Issue #239Optional / Future / Nice to Have 区中未勾选的条目不会阻塞 Ralph 退出这是防止永远有可选任务所以永不退出的关键设计。3.4 specs/详细规格用途当 PROMPT.md 对某个功能的描述不够时使用。何时使用需要详细需求的复杂特性、必须精确遵守的 API 契约、带特定校验规则的数据模型、外部系统集成。何时不用简单 CRUD、PROMPT.md 已充分说明的功能、通用编码规范放入 PROMPT.md。示例结构.ralph/specs/ ├── api-contracts.md # OpenAPI-style endpoint definitions ├──># Error Handling Standard All API errors must return: { error: { code: BOOK_NOT_FOUND, message: No book with ID 123 exists, details: {} } } Use HTTPException with these codes: - 400: Validation errors - 404: Resource not found - 409: Conflict (duplicate) - 500: Internal errors (log full trace)3.6 AGENT.md构建与测试说明目的告诉 Ralph 如何构建、测试、运行项目。维护者主要是 Ralph——它在循环中逐步发现并沉淀构建命令。你何时需要编辑为复杂项目设定初始构建命令、补充环境准备步骤、记录部署命令。模板 templates/AGENT.md 内置了很强的质量门禁这些内容由启用向导带默认值生成新代码覆盖率不低于 85%、测试必须 100% 通过、Git 提交遵循 conventional commits 规范、功能完成前必须跑完一份包含 14 项的完成检查清单测试通过、覆盖率达标、代码格式化、提交推送、文档同步、fix_plan.md 勾选等。3.7 .ralphrc项目配置目的项目级 Ralph 设置。默认内容通常无需修改来自 templates/ralphrc.templatePROJECT_NAMEmy-project PROJECT_TYPEtypescript MAX_CALLS_PER_HOUR100 ALLOWED_TOOLSWrite,Read,Edit,Bash(git *),Bash(npm *),Bash(pytest)何时编辑出于安全限制工具权限、调整速率限制、修改会话超时。值得展开的是ALLOWED_TOOLS的默认值设计模板注释中有明确说明默认并非笼统的Bash(git *)而是逐个列出Bash(git add *)、Bash(git commit *)、Bash(git diff *)等安全子命令因为git clean、git rm、git reset等破坏性命令可能误删.ralph/对应 Issue #149。模板还提醒带管道、重定向、;或的复合命令可能无法匹配Bash(cmd *)这类通配模式Claude CLI 的限制对应 Issue #243Ralph 会自动检测这种情况并以警告继续循环你也可以改用Bash(*)绕过。MAX_CALLS_PER_HOUR100对应每小时 API 调用上限速率限制CLAUDE_TIMEOUT_MINUTES15控制单次 Claude Code 调用的超时超时后记日志并进入下一轮迭代。此外模板还提供可选的高级配置SESSION_CONTINUITY/SESSION_EXPIRY_HOURS跨循环上下文保持、CB_*系列电路熔断阈值无进展 3 轮、同错误 5 轮、输出下滑 70% 熔断冷却 30 分钟、任务源TASK_SOURCESlocal / beads / github、以及可选的 Docker / E2B 沙箱执行配置见 docs/DOCKER_SANDBOX.md 与 docs/E2B_SANDBOX.md。3.8 文件关系图官方用一张结构图说明四份核心文件的协作关系┌─────────────────────────────────────────────────────────────┐ │ PROMPT.md │ │ (High-level goals and principles) │ │ │ │ │ ▼ │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ specs/ │ │ │ │ (Detailed requirements when needed) │ │ │ │ │ │ │ │ specs/api.md ──────▶ Informs fix_plan.md tasks │ │ │ │ specs/stdlib/ ─────▶ Conventions Ralph follows │ │ │ └─────────────────────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ fix_plan.md │ │ │ │ (Concrete tasks Ralph executes) │ │ │ │ │ │ │ │ [ ] Task 1 ◄────── Ralph checks off when done │ │ │ │ [x] Task 2 │ │ │ │ [ ] Task 3 ◄────── Ralph adds discovered tasks │ │ │ └─────────────────────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ AGENT.md │ │ │ │ (How to build/test - auto-maintained) │ │ │ └─────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────┘信息流可以概括为PROMPT.md 定义做什么、为什么、按什么标准→ specs/ 在需要时补充精确细节 → fix_plan.md 承载具体任务并随循环演化Ralph 勾选完成项、追加新发现任务→ AGENT.md 提供怎么构建与测试。3.9 三个常见场景场景 1简单功能新增——只编辑 fix_plan.md- [ ] Add a /health endpoint that returns {status: ok}场景 2带具体需求的复杂功能——先写 spec 再写任务创建.ralph/specs/search-feature.md# Search Feature Specification ## Requirements - Full-text search on book titles and descriptions - Must support: - Exact phrase matching: lord of the rings - Boolean operators: fantasy AND epic - Fuzzy matching for typos然后在 fix_plan.md 中引用- [ ] Implement search per specs/search-feature.md场景 3建立团队约定——写入 specs/stdlib/# Logging Conventions All service methods must log: - Entry with parameters (DEBUG level) - Exit with result summary (DEBUG level) - Errors with full context (ERROR level)3.10 成功要点从简开始先用 PROMPT.md fix_plan.md确有需要再加 specs/保持具体模糊需求产生模糊结果。Add user auth 不如 Add JWT authentication with /login and /logout endpoints让 fix_plan.md 演化Ralph 会追加发现的任务定期审阅并重新排序不要过度规格化Claude 能根据上下文推断的内容就不必写明复盘日志出问题时.ralph/logs/记录了 Ralph 当时的思考过程。四、Writing Effective Requirements写出高质量需求本节完整展开 03-writing-requirements.md给出可复用的写作范式。4.1 PROMPT.md好例与坏例坏例# Project Make a good API for managing stuff. Use best practices. Should be fast and work well.问题什么是 stuff太模糊best practices 是什么Claude 只能猜测fast、work well 不可度量。好例# Ralph Development Instructions ## Context You are Ralph, building a REST API for a pet adoption shelter. The API manages animals, adopters, and adoption records. ## Technology Stack - Python 3.11 with FastAPI - PostgreSQL with SQLAlchemy (async) - pytest for testing - Pydantic for validation ## Key Principles - RESTful endpoints following standard conventions - All endpoints require authentication except GET /animals - Soft delete for all entities (is_deleted flag, not actual deletion) - Pagination on all list endpoints (default 20, max 100) ## Data Entities - Animal: name, species, breed, age, status (available/adopted/pending) - Adopter: name, email, phone, approved (boolean) - Adoption: animal_id, adopter_id, date, status ## Quality Standards - Every endpoint needs at least one happy-path test - Input validation with clear error messages - OpenAPI documentation for all endpoints为什么有效领域清晰宠物收养站技术选型明确约束可度量分页上限数据模型具体质量标准被明确定义。4.2 fix_plan.md任务写作的金发姑娘原则任务应当不大不小、恰到好处。太大Ralph 不知从何下手- [ ] Build the entire authentication system太小浪费循环迭代- [ ] Create the auth folder - [ ] Create the auth/__init__.py file - [ ] Create the auth/routes.py file刚好一轮循环完成有意义的产出- [ ] Create auth routes with POST /login and POST /logout endpoints - [ ] Add JWT token generation and validation middleware - [ ] Create refresh token endpoint POST /auth/refresh4.3 任务结构模板# Fix Plan - [Project Name] ## Priority 1: [Foundation/Critical Path] - [ ] [Specific, actionable task] - [ ] [Another specific task] ## Priority 2: [Core Features] - [ ] [Feature task] - [ ] [Feature task] ## Priority 3: [Polish/Nice-to-have] - [ ] [Enhancement] - [ ] [Documentation] ## Discovered !-- Ralph adds tasks it discovers here --4.4 fix_plan.md 如何演化初始状态你写的## Priority 1: Database - [ ] Set up database models for Animal, Adopter, Adoption ## Priority 2: API - [ ] Create CRUD endpoints for animals第 1 轮循环后Ralph 更新## Priority 1: Database - [x] Set up database models for Animal, Adopter, Adoption ## Priority 2: API - [ ] Create CRUD endpoints for animals ## Discovered - [ ] Add database migration with Alembic - [ ] Create pytest fixtures for test database第 3 轮循环后## Priority 1: Database - [x] Set up database models for Animal, Adopter, Adoption ## Priority 2: API - [x] Create CRUD endpoints for animals - [ ] Create CRUD endpoints for adopters ## Discovered - [x] Add database migration with Alembic - [x] Create pytest fixtures for test database - [ ] Add pagination to GET /animals endpoint可见 Ralph 会勾选完成项、把循环中发现的新工作追加到 Discovered 区。你可以随时把任务移动到不同优先级区进行重排、删除不再相关的任务、或添加新任务。4.5 何时使用 specs/复杂功能用 specs/。当 PROMPT.md 只能说一句Add a matching algorithm that suggests animals to adopters.时请创建.ralph/specs/matching-algorithm.md把需求说清楚# Animal Matching Algorithm ## Inputs - Adopter preferences: species, max_age, size_preference - Available animals list ## Algorithm 1. Filter by species (required match) 2. Score by age preference (0-100 points) - Within range: 100 points - Within 2 years: 50 points - Outside: 0 points 3. Score by size preference (0-50 points) 4. Return top 5 by total score ## Output Format [ {animal_id: 1, score: 145, reasons: [species match, age within preference]}, {animal_id: 3, score: 120, reasons: [species match]} ] ## Edge Cases - No matches: return empty array - Tie scores: sort by animal.created_at (oldest first)然后在 fix_plan.md 中引用- [ ] Implement matching algorithm per specs/matching-algorithm.md约定用 specs/stdlib/。需要全项目一致性时文档化它——.ralph/specs/stdlib/error-responses.md# Error Response Standard All API errors return this structure: { error: { code: ANIMAL_NOT_FOUND, message: No animal with ID 42 exists, field: null, details: {} } } ## Error Codes | Code | HTTP Status | When | |------|-------------|------| | VALIDATION_ERROR | 400 | Invalid input | | NOT_FOUND | 404 | Resource doesnt exist | | ALREADY_ADOPTED | 409 | Animal not available | | UNAUTHORIZED | 401 | Missing/invalid token |不要滥用 specs/。一行能说清的就别建文件# User Password Requirements Passwords must be at least 8 characters.直接写进 PROMPT.md## Authentication - Passwords: minimum 8 characters, at least one number - JWT tokens expire after 1 hour4.6 四个常见错误错误 1假设 Claude 知道你的偏好差Use standard authentication.好Use JWT authentication with 1-hour token expiry. Refresh tokens last 7 days and rotate on use.错误 2把实现细节混进需求差写在 PROMPT.md 里Create a file called auth.py and add these imports: import jwt ...好Use JWT for authentication. Tokens should expire after 1 hour.让 Ralph 自己去推导实现细节。错误 3过度指定测试差- [ ] Write test_create_animal_success - [ ] Write test_create_animal_invalid_species - [ ] Write test_create_animal_missing_name - [ ] Write test_create_animal_negative_age好- [ ] Write tests for animal creation (success and validation errors)Ralph 知道怎么写测试告诉它测什么而不是怎么测。错误 4忘了交代为什么差Add a 100ms delay to all API responses.好Add a 100ms delay to all API responses (required for rate limiting compliance with external payment API).当 Ralph 理解why时它才能做出更好的决策。4.7 运行前检查清单在ralph --monitor之前逐项确认PROMPT.md 有清晰的上下文——Ralph 知道自己在构建什么吗技术栈已指定——你选定框架了吗关键约束已文档化——认证方案API 约定fix_plan.md 有具体任务——Ralph 能立即开始任务 1 吗复杂功能有 specs/——有没有 PROMPT.md 说不清的东西4.8 需求归属速查想做什么……写到哪里……设定项目愿景与原则PROMPT.md定义技术栈PROMPT.md列出具体实现任务fix_plan.md记录复杂功能需求specs/feature-name.md建立编码约定specs/stdlib/convention-name.md配置 Ralph 行为.ralphrc五、源码纵深Ralph 如何读懂这些文件并决定退出为了让你理解为什么上述写作规范如此重要这里从源码视角解释文件如何驱动循环与退出判定。5.1 状态上报块循环与退出判定的核心契约templates/PROMPT.md 要求 Claude 每次响应末尾输出固定格式状态块---RALPH_STATUS--- STATUS: IN_PROGRESS | COMPLETE | BLOCKED TASKS_COMPLETED_THIS_LOOP: number FILES_MODIFIED: number TESTS_STATUS: PASSING | FAILING | NOT_RUN WORK_TYPE: IMPLEMENTATION | TESTING | DOCUMENTATION | REFACTORING EXIT_SIGNAL: false | true RECOMMENDATION: one line summary of what to do next ---END_RALPH_STATUS---【免费下载链接】ralph-claude-codeAutonomous AI development loop for Claude Code with intelligent exit detection项目地址: https://gitcode.com/GitHub_Trending/ra/ralph-claude-code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考