Back to Details

spidey

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Spidey — Autonomous Development Loop

Spidey — 自主开发循环

Sets up a Ralph autonomous development loop. Unlike raw Ralph which just takes a checklist, Spidey first generates a full PRD, then derives all tasks from it.
为项目搭建Ralph自主开发循环。与原生Ralph仅接收任务清单不同，Spidey会先生成完整的PRD，再从中推导所有任务。

The Spidey Pipeline

Spidey 工作流程

User's lazy description
    ↓
┌─────────────────────────────────┐
│ PHASE 0: PRD GENERATION         │
│ Full product requirements doc   │
│ from a one-line description     │
└─────────────────────────────────┘
    ↓
┌─────────────────────────────────┐
│ PHASE 1: TASK DERIVATION        │
│ fix_plan.md derived FROM the    │
│ PRD, not invented from nothing  │
└─────────────────────────────────┘
    ↓
┌─────────────────────────────────┐
│ PHASE 2: LOOP CONFIGURATION     │
│ .ralphrc, PROMPT.md, AGENT.md   │
└─────────────────────────────────┘
    ↓
┌─────────────────────────────────┐
│ PHASE 3: AUTONOMOUS EXECUTION   │
│ ralph --monitor                 │
└─────────────────────────────────┘
用户的简要描述
    ↓
┌─────────────────────────────────┐
│ PHASE 0: PRD 生成               │
│ 根据一句话描述生成完整的产品需求文档 │
└─────────────────────────────────┘
    ↓
┌─────────────────────────────────┐
│ PHASE 1: 任务推导               │
│ 基于PRD生成fix_plan.md，而非凭空创建 │
└─────────────────────────────────┘
    ↓
┌─────────────────────────────────┐
│ PHASE 2: 循环配置               │
│ 生成.ralphrc、PROMPT.md、AGENT.md │
└─────────────────────────────────┘
    ↓
┌─────────────────────────────────┐
│ PHASE 3: 自主执行               │
│ 运行ralph --monitor             │
└─────────────────────────────────┘

PHASE 0: PRD GENERATION

PHASE 0: PRD 生成

This is what separates spidey from raw Ralph. Before any code, generate a proper PRD.
这是Spidey与原生Ralph的核心区别。在编写任何代码前，先生成规范的PRD。

Deep-dive questioning (MANDATORY)

深度调研提问（必填步骤）

Before writing the PRD, conduct a thorough interview. Ask questions in multiple rounds using AskUserQuestion. Do NOT rush to generate the PRD — the quality of the PRD depends entirely on how well you understand the project. Keep asking until you have a clear picture.
Round 1: Vision & Users
  • "What problem does this solve? What's the pain point today?"
  • "Who are the primary users? Describe 2-3 distinct personas."
  • "What does success look like? How will you know this is working?"
  • "Are there existing products/competitors? What do they get wrong?"
Round 2: Core Experience
  • "Walk me through the ideal user journey from first open to daily use."
  • "What are the 3 features that MUST exist for this to be useful? What's the single most important one?"
  • "What should the user feel when using this? (fast, calm, powerful, fun, simple)"
  • "Are there any workflows that need to feel instant vs. ones that can load?"
Round 3: Technical & Platform
  • "What's the target platform? (iOS, Android, both, web, desktop, CLI)"
  • "Any existing backend, database, auth system, or APIs to integrate with?"
  • "Do you have preferences on stack/framework, or should I recommend?"
  • "Does this need real-time features? (live updates, collaboration, notifications)"
  • "Offline support needed? What should work without internet?"
  • "Any third-party services? (payments, maps, analytics, AI/ML, messaging)"
Round 4: Data & Business Logic
  • "What are the core entities/objects in this system? (users, posts, orders, etc.)"
  • "What are the key relationships between them? (a user has many X, an X belongs to Y)"
  • "Are there different user roles or permission levels? Describe each."
  • "Any complex business rules? (pricing tiers, approval workflows, calculations)"
  • "What data is sensitive? (PII, financial, health)"
Round 5: Scope & Constraints
  • "What's MVP vs. nice-to-have vs. definitely-not-now?"
  • "Any hard deadlines or constraints?"
  • "Any design preferences? (dark mode, specific brand colors, reference apps you love)"
  • "What about accessibility? (screen reader support, color blindness, motor impairment)"
  • "Internationalization needed? Which languages/locales?"
  • "Any compliance requirements? (GDPR, HIPAA, SOC2, PCI)"
Round 6: Edge Cases & Polish
  • "What happens when something goes wrong? (no internet, server error, invalid input)"
  • "What empty states exist? (new user, no data yet, search with no results)"
  • "What notifications/emails/alerts should the system send?"
  • "Onboarding flow — how does a new user learn the app?"
  • "Any admin/backoffice needs? (dashboards, moderation, analytics)"
You do NOT need to ask every single question. Skip ones that are obviously irrelevant to the project. But you MUST ask across at least 4 of these 6 rounds. Use your judgment — if the user's description is vague, ask more. If it's detailed, focus on gaps.
After each round, acknowledge what you've learned and explain what you still need to know before asking the next round. Stop when you have enough to write a comprehensive PRD.
在编写PRD前，需进行全面的调研。使用AskUserQuestion进行多轮提问。切勿急于生成PRD——PRD的质量完全取决于你对项目的理解程度。持续提问直到你对项目有清晰的认知。
第一轮：愿景与用户
  • "该产品解决什么问题？当前的痛点是什么？"
  • "核心用户是谁？请描述2-3个不同的用户画像。"
  • "成功的标准是什么？如何衡量产品是否有效？"
  • "是否有同类产品或竞争对手？他们存在哪些不足？"
第二轮：核心体验
  • "请描述从首次打开到日常使用的理想用户旅程。"
  • "产品必须具备哪3个核心功能？其中最重要的功能是什么？"
  • "用户使用产品时应获得怎样的感受？（快速、安心、强大、有趣、简洁）"
  • "哪些工作流需要即时响应，哪些可以允许加载延迟？"
第三轮：技术与平台
  • "目标平台是什么？（iOS、Android、双平台、网页、桌面端、CLI）"
  • "是否需要集成现有后端、数据库、认证系统或API？"
  • "你对技术栈/框架有偏好，还是需要我推荐？"
  • "是否需要实时功能？（实时更新、协作、通知）"
  • "是否需要离线支持？离线时哪些功能需正常工作？"
  • "是否需要第三方服务？（支付、地图、分析、AI/ML、消息推送）"
第四轮：数据与业务逻辑
  • "系统中的核心实体/对象有哪些？（用户、帖子、订单等）"
  • "它们之间的关键关系是什么？（一个用户拥有多个X，X属于Y）"
  • "是否存在不同的用户角色或权限等级？请分别描述。"
  • "是否有复杂的业务规则？（定价层级、审批流程、计算逻辑）"
  • "哪些数据属于敏感数据？（个人身份信息、财务数据、健康数据）"
第五轮：范围与约束
  • "MVP、锦上添花功能、明确暂不开发的功能分别有哪些？"
  • "是否有硬性截止日期或约束条件？"
  • "是否有设计偏好？（深色模式、特定品牌色、你喜欢的参考应用）"
  • "无障碍支持需求如何？（屏幕阅读器支持、色盲适配、行动障碍适配）"
  • "是否需要国际化支持？支持哪些语言/地区？"
  • "是否有合规要求？（GDPR、HIPAA、SOC2、PCI）"
第六轮：边缘案例与优化
  • "出现异常情况时如何处理？（无网络、服务器错误、无效输入）"
  • "存在哪些空状态？（新用户、无数据、搜索无结果）"
  • "系统应发送哪些通知/邮件/提醒？"
  • "新用户引导流程——如何让新用户快速了解应用？"
  • "是否需要管理员/后台功能？（仪表盘、内容审核、数据分析）"
无需提问所有问题，可跳过与项目明显无关的问题。但必须覆盖至少4个轮次的提问。根据实际情况判断：如果用户描述模糊，就多提问；如果描述详细，就聚焦于信息缺口。
每轮提问后，告知用户你已了解的信息，并说明还需要哪些信息才能进行下一轮提问。当你掌握足够信息可编写全面的PRD时，停止提问。

Generate 
.ralph/specs/PRD.md

生成 
.ralph/specs/PRD.md

Write a complete PRD with ALL of these sections:
markdown
undefined
编写包含以下所有章节的完整PRD：
markdown
undefined

PRD: [Project Name]

PRD: [项目名称]

1. Overview

1. 概述

One paragraph describing what this product does and why it exists.
用一段话描述产品功能及存在意义。

2. Target Users

2. 目标用户

User TypeDescriptionPrimary Need
[Persona 1][Who they are][What they need]
[Persona 2][Who they are][What they need]
用户类型描述核心需求
[用户画像1][用户特征][核心需求]
[用户画像2][用户特征][核心需求]

3. User Stories

3. 用户故事

Epic: [Feature Area 1]

史诗：[功能领域1]

  • US-001: As a [user], I want to [action] so that [benefit]
    • Acceptance Criteria:
      • [Specific, testable criterion]
      • [Specific, testable criterion]
      • [Specific, testable criterion]
  • US-002: As a [user], I want to [action] so that [benefit]
    • Acceptance Criteria:
      • ...
  • US-001: 作为[用户角色]，我希望[执行操作]，以便[获得收益]
    • 验收标准:
      • [具体、可测试的标准]
      • [具体、可测试的标准]
      • [具体、可测试的标准]
  • US-002: 作为[用户角色]，我希望[执行操作]，以便[获得收益]
    • 验收标准:
      • ...

Epic: [Feature Area 2]

史诗：[功能领域2]

  • US-003: ...
(Continue for all features)
  • US-003: ...
（覆盖所有功能）

4. Technical Requirements

4. 技术要求

Stack

技术栈

LayerTechnologyRationale
Frontend[e.g., React Native / Expo][Why]
Backend[e.g., Supabase][Why]
Auth[e.g., Supabase Auth][Why]
State[e.g., TanStack Query][Why]
Navigation[e.g., Expo Router][Why]
层级技术选型选型理由
前端[例如：React Native / Expo][理由]
后端[例如：Supabase][理由]
认证[例如：Supabase Auth][理由]
状态管理[例如：TanStack Query][理由]
导航[例如：Expo Router][理由]

Architecture

架构

  • [Key architectural decisions]
  • [Data flow description]
  • [API structure]
  • [关键架构决策]
  • [数据流描述]
  • [API结构]

Data Model

数据模型

EntityKey FieldsRelationships
Userid, email, name, avatarhas_many: workouts
Workoutid, user_id, date, typebelongs_to: user, has_many: sets
.........
实体关键字段关系
用户id, email, name, avatarhas_many: workouts
训练记录id, user_id, date, typebelongs_to: user, has_many: sets
.........

API Endpoints / Procedures

API 端点 / 流程

MethodPath / NamePurposeAuth
POST/auth/signupCreate accountPublic
GET/workoutsList user workoutsAuthenticated
............
方法路径 / 名称用途认证要求
POST/auth/signup创建账户公开
GET/workouts获取用户训练记录需认证
............

5. Screens & Navigation

5. 页面与导航

Screen Map

页面地图

App
├── Auth Stack (unauthenticated)
│   ├── Welcome
│   ├── Sign Up
│   ├── Login
│   └── Forgot Password
└── Main Tabs (authenticated)
    ├── Home / Dashboard
    ├── [Feature Screen 1]
    ├── [Feature Screen 2]
    └── Profile / Settings
应用
├── 认证栈（未登录状态）
│   ├── 欢迎页
│   ├── 注册页
│   ├── 登录页
│   └── 忘记密码页
└── 主标签栏（已登录状态）
    ├── 首页 / 仪表盘
    ├── [功能页面1]
    ├── [功能页面2]
    └── 个人中心 / 设置页

Screen Descriptions

页面描述

ScreenPurposeKey Components
Home[What it shows][Cards, lists, charts, etc.]
.........
页面用途核心组件
首页[展示内容][卡片、列表、图表等]
.........

6. Non-Functional Requirements

6. 非功能性需求

Performance

性能

  • App launch < [X] seconds
  • Screen transitions < [X]ms
  • API response time < [X]ms
  • 应用启动时间 < [X] 秒
  • 页面切换时间 < [X]ms
  • API响应时间 < [X]ms

Security

安全

  • [Auth requirements]
  • [Data encryption requirements]
  • [RLS / permission model]
  • [认证要求]
  • [数据加密要求]
  • [行级安全 / 权限模型]

Accessibility

无障碍

  • [WCAG level target]
  • [Screen reader support]
  • [Minimum touch targets]
  • [WCAG目标等级]
  • [屏幕阅读器支持]
  • [最小触摸目标尺寸]

Offline Support

离线支持

  • [What works offline]
  • [Sync strategy]
  • [离线可用功能]
  • [同步策略]

7. MVP Scope

7. MVP范围

In Scope (MVP)

包含范围（MVP）

  • [Feature 1]
  • [Feature 2]
  • [Feature 3]
  • [功能1]
  • [功能2]
  • [功能3]

Out of Scope (Post-MVP)

排除范围（Post-MVP）

  • [Deferred feature 1]
  • [Deferred feature 2]
  • [延后开发功能1]
  • [延后开发功能2]

8. Success Metrics

8. 成功指标

MetricTargetHow Measured
[e.g., DAU][e.g., 100 in first month][Analytics tool]
.........
指标目标测量方式
[例如：日活跃用户数][例如：首月达到100人][分析工具]
.........

9. Open Questions

9. 待解决问题

  • [Anything unresolved]
  • [Decisions that need user input later]
undefined
  • [未解决的问题]
  • [后续需要用户确认的决策]
undefined

Present PRD for approval

提交PRD待确认

After generating the PRD, show the user a summary and ask for approval before proceeding. Use AskUserQuestion:
  • "PRD generated. Review 
    .ralph/specs/PRD.md
    . Ready to proceed, or want changes?"
生成PRD后，向用户展示摘要并请求确认后再继续。使用AskUserQuestion：
  • "PRD已生成，请查看
    .ralph/specs/PRD.md
    。是否可以继续，还是需要修改？"

PHASE 1: TASK DERIVATION (from PRD)

PHASE 1: 任务推导（基于PRD）

Once the PRD is approved, derive 
fix_plan.md
directly from it.
PRD确认后，直接从中推导
fix_plan.md
。

Derivation Rules

推导规则

  1. Every user story becomes one or more tasks
  2. Every acceptance criterion becomes a verification step
  3. Infrastructure/setup tasks come first (Critical)
  4. Core user flows are High priority
  5. Enhancement features are Medium
  6. Polish/nice-to-have is Low
  7. Each task must be completable in a single loop iteration (~15 min of Claude work)
  1. 每个用户故事拆分为一个或多个任务
  2. 每个验收标准转化为一个验证步骤
  3. 基础设施/搭建任务优先（关键）
  4. 核心用户流为高优先级
  5. 增强功能为中优先级
  6. 优化/锦上添花功能为低优先级
  7. 每个任务需在单次循环迭代内完成（约Claude 15分钟工作量）

Generate 
.ralph/fix_plan.md

生成 
.ralph/fix_plan.md

markdown
undefined
markdown
undefined

Fix Plan

任务计划

Derived from: .ralph/specs/PRD.md
源自: .ralph/specs/PRD.md

Critical (Infrastructure & Setup)

关键优先级（基础设施与搭建）

  • Project scaffolding (init, deps, config)
  • Data model / database schema (from PRD §4 Data Model)
  • Auth setup (from PRD §4 Auth)
  • Navigation skeleton (from PRD §5 Screen Map)
  • 项目脚手架（初始化、依赖、配置）
  • 数据模型 / 数据库 schema（来自PRD §4 数据模型）
  • 认证系统搭建（来自PRD §4 认证）
  • 导航骨架（来自PRD §5 页面地图）

High (Core User Stories)

高优先级（核心用户故事）

  • US-001: [User story title] (from PRD §3)
    • Verify: [acceptance criteria 1]
    • Verify: [acceptance criteria 2]
  • US-002: [User story title]
    • Verify: [acceptance criteria]
  • US-003: ...
  • US-001: [用户故事标题]（来自PRD §3）
    • 验证: [验收标准1]
    • 验证: [验收标准2]
  • US-002: [用户故事标题]
    • 验证: [验收标准]
  • US-003: ...

Medium (Enhancement User Stories)

中优先级（增强型用户故事）

  • US-004: [Enhancement feature]
    • Verify: [acceptance criteria]
  • US-005: ...
  • US-004: [增强功能]
    • 验证: [验收标准]
  • US-005: ...

Low (Polish & Post-MVP prep)

低优先级（优化与Post-MVP准备）

  • Dark mode / theming
  • Onboarding flow
  • Error states & empty states
  • Performance optimization
  • App store assets / metadata
  • 深色模式 / 主题配置
  • 新用户引导流程
  • 错误状态与空状态
  • 性能优化
  • 应用商店素材 / 元数据

Verification Gate

验证关卡

After all tasks complete, verify:
  • All acceptance criteria from PRD met
  • All screens from §5 implemented
  • Non-functional requirements from §6 checked
  • Tests passing

Every task traces back to a specific PRD section. No orphan tasks.

---
所有任务完成后，验证：
  • PRD中所有验收标准已满足
  • §5中所有页面已实现
  • §6中非功能性需求已验证
  • 测试通过

每个任务都需关联到PRD的具体章节，禁止出现无来源的任务。

---

PHASE 2: LOOP CONFIGURATION

PHASE 2: 循环配置

Step 1: Check Ralph installation

步骤1：检查Ralph安装情况

bash
which ralph-loop 2>/dev/null || which ralph 2>/dev/null
If not installed:
bash
git clone https://github.com/frankbria/ralph-claude-code.git /tmp/ralph-claude-code
cd /tmp/ralph-claude-code && ./install.sh
Dependencies:
bash
undefined
bash
which ralph-loop 2>/dev/null || which ralph 2>/dev/null
若未安装：
bash
git clone https://github.com/frankbria/ralph-claude-code.git /tmp/ralph-claude-code
cd /tmp/ralph-claude-code && ./install.sh
依赖项：
bash
undefined

macOS

macOS

brew install jq tmux coreutils
brew install jq tmux coreutils

Linux

Linux

sudo apt install jq tmux coreutils
undefined
sudo apt install jq tmux coreutils
undefined

Step 2: Create directory structure

步骤2：创建目录结构

bash
mkdir -p .ralph/specs .ralph/examples .ralph/logs .ralph/docs/generated
bash
mkdir -p .ralph/specs .ralph/examples .ralph/logs .ralph/docs/generated

Step 3: Generate .ralphrc

步骤3：生成 .ralphrc

Detect project type from package.json / pyproject.toml / Cargo.toml / go.mod and generate:
bash
PROJECT_NAME="$ARGUMENTS"
PROJECT_TYPE="[detected]"
MAX_CALLS_PER_HOUR=100
CLAUDE_TIMEOUT_MINUTES=15
CLAUDE_OUTPUT_FORMAT="json"
ALLOWED_TOOLS="Write,Read,Edit,Bash(git *),Bash(npm *),Bash(npx *)"
SESSION_CONTINUITY=true
SESSION_EXPIRY_HOURS=24
TASK_SOURCES="local"
CB_NO_PROGRESS_THRESHOLD=3
CB_SAME_ERROR_THRESHOLD=5
CB_OUTPUT_DECLINE_THRESHOLD=70
Adjust 
ALLOWED_TOOLS
per project type:
  • TypeScript/Node: 
    Bash(npm *),Bash(npx *),Bash(node *)
  • Python: 
    Bash(python *),Bash(pip *),Bash(pytest *)
  • Rust: 
    Bash(cargo *),Bash(rustc *)
  • Go: 
    Bash(go *)
  • Add 
    Bash(docker *)
    if Dockerfile present
从package.json / pyproject.toml / Cargo.toml / go.mod中检测项目类型并生成：
bash
PROJECT_NAME="$ARGUMENTS"
PROJECT_TYPE="[检测结果]"
MAX_CALLS_PER_HOUR=100
CLAUDE_TIMEOUT_MINUTES=15
CLAUDE_OUTPUT_FORMAT="json"
ALLOWED_TOOLS="Write,Read,Edit,Bash(git *),Bash(npm *),Bash(npx *)"
SESSION_CONTINUITY=true
SESSION_EXPIRY_HOURS=24
TASK_SOURCES="local"
CB_NO_PROGRESS_THRESHOLD=3
CB_SAME_ERROR_THRESHOLD=5
CB_OUTPUT_DECLINE_THRESHOLD=70
根据项目类型调整
ALLOWED_TOOLS
：
  • TypeScript/Node: 
    Bash(npm *),Bash(npx *),Bash(node *)
  • Python: 
    Bash(python *),Bash(pip *),Bash(pytest *)
  • Rust: 
    Bash(cargo *),Bash(rustc *)
  • Go: 
    Bash(go *)
  • 若存在Dockerfile，添加
    Bash(docker *)

Step 4: Generate PROMPT.md

步骤4：生成 PROMPT.md

markdown
undefined
markdown
undefined

Project: [PROJECT_NAME]

项目: [PROJECT_NAME]

Your Mission

你的任务

You are working autonomously in a Ralph loop. Each iteration:
  1. Read 
    .ralph/specs/PRD.md
    for full requirements context
  2. Read 
    .ralph/fix_plan.md
    for the current priority list
  3. Implement the HIGHEST PRIORITY unchecked item
  4. Run tests after implementation
  5. Update fix_plan.md (check off completed items, note any verify: criteria met)
  6. Output a RALPH_STATUS block (REQUIRED)
你将在Ralph循环中自主工作。每次迭代需完成：
  1. 阅读
    .ralph/specs/PRD.md
    获取完整需求上下文
  2. 阅读
    .ralph/fix_plan.md
    获取当前优先级任务列表
  3. 实现优先级最高的未完成任务
  4. 实现后运行测试
  5. 更新fix_plan.md（标记已完成任务，记录验证标准完成情况）
  6. 输出RALPH_STATUS块（必填）

Project Context

项目上下文

[GENERATED FROM PRD §1 Overview and §4 Technical Requirements]
[从PRD §1 概述和 §4 技术要求中生成]

Specifications

规格说明

  • Full PRD: 
    .ralph/specs/PRD.md
  • Additional specs: 
    .ralph/specs/*
  • 完整PRD: 
    .ralph/specs/PRD.md
  • 额外规格: 
    .ralph/specs/*

Key Architecture Rules

核心架构规则

[EXTRACTED FROM PRD §4 Architecture section]
[从PRD §4 架构章节中提取]

Build & Test Instructions

构建与测试说明

See 
.ralph/AGENT.md
for how to build, test, and run the project.
查看
.ralph/AGENT.md
了解项目构建、测试与运行方式。

Rules

规则

  • ONE task per loop iteration (stay focused)
  • Always run tests after changes
  • Never skip the RALPH_STATUS block
  • If blocked, set STATUS: BLOCKED and explain why
  • If all tasks are done, set EXIT_SIGNAL: true
  • Reference the PRD for acceptance criteria — don't guess
  • When implementing a user story, check ALL its acceptance criteria
  • 每次循环仅处理一个任务（保持专注）
  • 更改后必须运行测试
  • 禁止跳过RALPH_STATUS块
  • 若遇到阻塞，设置STATUS: BLOCKED并说明原因
  • 所有任务完成后，设置EXIT_SIGNAL: true
  • 参考PRD中的验收标准，切勿主观猜测
  • 实现用户故事时，需验证所有验收标准

Required Output Format

要求的输出格式

At the END of every response, output EXACTLY:
---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 RECOMMENDATION: <one line summary of what was done and what's next> ---END_RALPH_STATUS---
Set EXIT_SIGNAL: true ONLY when ALL tasks in fix_plan.md are complete AND the Verification Gate at the bottom of fix_plan.md passes.
undefined
在每次响应末尾，必须输出：
---RALPH_STATUS--- STATUS: IN_PROGRESS | COMPLETE | BLOCKED TASKS_COMPLETED_THIS_LOOP: <数字> FILES_MODIFIED: <数字> TESTS_STATUS: PASSING | FAILING | NOT_RUN WORK_TYPE: IMPLEMENTATION | TESTING | DOCUMENTATION | REFACTORING EXIT_SIGNAL: false RECOMMENDATION: <一句话总结已完成工作与下一步计划> ---END_RALPH_STATUS---
仅当fix_plan.md中所有任务完成 且fix_plan.md底部的验证关卡通过时，才可设置EXIT_SIGNAL: true
undefined

Step 5: Generate AGENT.md

步骤5：生成 AGENT.md

markdown
undefined
markdown
undefined

Agent Instructions

Agent操作指南

Build

构建

[detected build command]
[检测到的构建命令]

Test

测试

[detected test command]
[检测到的测试命令]

Run

运行

[detected run command]
[检测到的运行命令]

Lint

代码检查

[detected lint command]
[检测到的代码检查命令]

Type Check

类型检查

[detected type check command if applicable]
undefined
[检测到的类型检查命令（若适用）]
undefined

Step 6: Initialize git repo (CRITICAL for circuit breaker)

步骤6：初始化git仓库（关键：用于断路器）

Ralph's circuit breaker detects progress via 
git diff --name-only
. If there is no git repo, 
files_changed
is always 0, and the circuit breaker will false-trip after 
CB_NO_PROGRESS_THRESHOLD
loops. You MUST ensure a git repo exists with an initial commit before launching the loop.
bash
undefined
Ralph的断路器通过
git diff --name-only
检测进度。若未创建git仓库，
files_changed
将始终为0，断路器会在
CB_NO_PROGRESS_THRESHOLD
次循环后误触发。 在启动循环前，必须确保git仓库已存在且完成初始提交。
bash
undefined

Add Ralph state files to .gitignore FIRST

先将Ralph状态文件添加到.gitignore

echo -e "\n# Ralph loop state files\n.ralph/logs/\n.ralph/status.json\n.ralph/progress.json\n.ralph/.call_count\n.ralph/.last_reset\n.ralph/.exit_signals\n.ralph/.response_analysis\n.ralph/.circuit_breaker_state\n.ralph/.claude_session_id\n.ralph/.ralph_session\n.ralph/.ralph_session_history" >> .gitignore
echo -e "\n# Ralph循环状态文件\n.ralph/logs/\n.ralph/status.json\n.ralph/progress.json\n.ralph/.call_count\n.ralph/.last_reset\n.ralph/.exit_signals\n.ralph/.response_analysis\n.ralph/.circuit_breaker_state\n.ralph/.claude_session_id\n.ralph/.ralph_session\n.ralph/.ralph_session_history" >> .gitignore

Initialize git if not already a repo

若尚未是git仓库，初始化仓库

if ! git rev-parse --git-dir > /dev/null 2>&1; then git init git add -A git commit -m "Initial Spidey scaffold" fi

**Why this matters:** Without git, every loop reports zero file changes → circuit breaker opens after a few loops even though tasks are completing successfully.
if ! git rev-parse --git-dir > /dev/null 2>&1; then git init git add -A git commit -m "Initial Spidey scaffold" fi

**重要性说明：** 若无git仓库，每次循环都会报告零文件更改→即使任务成功完成，断路器也会在几次循环后触发。

Step 7: Print run instructions

步骤7：打印运行说明

Spidey setup complete.

PRD:          .ralph/specs/PRD.md     (review and edit before running)
Task plan:    .ralph/fix_plan.md      (derived from PRD)
Loop config:  .ralphrc                (edit rate limits, timeouts)
Loop prompt:  .ralph/PROMPT.md        (edit to add project-specific rules)
Build/test:   .ralph/AGENT.md         (edit if auto-detect was wrong)

To run:
  ralph --monitor      # Recommended: loop + live dashboard in tmux
  ralph                # Loop only

To review status:
  ralph-monitor        # Dashboard in separate terminal

The loop will work through fix_plan.md top to bottom, one task per iteration,
until all items are checked off and the verification gate passes.
Spidey设置完成。

PRD:          .ralph/specs/PRD.md     (运行前请查看并编辑)
任务计划:    .ralph/fix_plan.md      (源自PRD)
循环配置:  .ralphrc                (可编辑速率限制、超时时间)
循环提示:  .ralph/PROMPT.md        (可编辑添加项目特定规则)
构建/测试:   .ralph/AGENT.md         (若自动检测错误，可编辑)

运行方式:
  ralph --monitor      # 推荐：循环 + tmux实时仪表盘
  ralph                # 仅运行循环

查看状态:
  ralph-monitor        # 在单独终端打开仪表盘

循环将按fix_plan.md从上到下的顺序，每次迭代处理一个任务，
直到所有任务标记完成且验证关卡通过。

How the Loop Works

循环工作原理

Exit Detection (Dual-Condition Gate)

退出检测（双重条件关卡）

Ralph only stops when BOTH:
  1. completion_indicators >= 2
    (accumulated across loops)
  2. Claude outputs 
    EXIT_SIGNAL: true
    in RALPH_STATUS
仅当以下两个条件同时满足时，Ralph才会停止：
  1. completion_indicators >= 2
    （循环累计值）
  2. Claude在RALPH_STATUS中输出
    EXIT_SIGNAL: true

Circuit Breaker

断路器

TriggerResult
3 loops no file changesOPEN (halted)
5 loops same errorOPEN (halted)
2 loops no progressHALF_OPEN (monitoring)
Progress in HALF_OPENCLOSED (recovered)
触发条件结果
3次循环无文件更改开启（暂停）
5次循环出现相同错误开启（暂停）
2次循环无进度半开启（监控）
半开启状态下出现进度关闭（恢复）

Session Continuity

会话连续性

  • Session persists via 
    --continue
    flag
  • 24-hour expiry (configurable)
  • Claude remembers what it did across iterations
  • 通过
    --continue
    参数保持会话
  • 24小时过期（可配置）
  • Claude可跨迭代记忆已完成工作

Rate Limiting

速率限制

  • 100 calls per 5-hour window (configurable)
  • Auto-waits with countdown when limit hit
  • 每5小时窗口最多100次调用（可配置）
  • 达到限制时自动等待并显示倒计时

Quick Reference

快速参考

bash
ralph-enable          # Interactive wizard for existing project
ralph-setup my-proj   # Create new blank project
ralph-import prd.md   # Convert existing PRD to Ralph format
ralph --monitor       # Run loop + dashboard
ralph-monitor         # Dashboard only
Now setting up Spidey for: $ARGUMENTS
bash
ralph-enable          # 现有项目的交互式向导
ralph-setup my-proj   # 创建新空白项目
ralph-import prd.md   # 将现有PRD转换为Ralph格式
ralph --monitor       # 运行循环 + 仪表盘
ralph-monitor         # 仅打开仪表盘
正在为以下项目搭建Spidey：$ARGUMENTS