spidey

Spidey — 自主开发循环

搭建一个 Ralph 自主开发循环。与只接收检查清单的原始 Ralph 不同，Spidey 会先生成完整的 PRD，再据此推导出所有任务。

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                 │
└─────────────────────────────────┘

---

阶段 0：PRD 生成

这正是 Spidey 与原始 Ralph 的区别所在。在编写任何代码之前，先生成一份规范的 PRD。

深入提问（必须）

编写 PRD 之前，先进行全面访谈。使用 AskUserQuestion 分多轮提问。不要急着生成 PRD——PRD 的质量完全取决于你对项目的理解程度。持续提问，直到你对项目有了清晰的认识。

第 1 轮：愿景与用户

• “这个项目要解决什么问题？目前的痛点是什么？”
• “主要用户有哪些？请描述 2-3 种不同的用户画像。”
• “怎样才算成功？你会如何判断项目是否有效？”
• “是否有现成产品或竞争对手？它们有哪些不足？”

第 2 轮：核心体验

• “请描述从首次打开到日常使用的理想用户旅程。”
• “要让产品实用，必须具备哪 3 项功能？其中最重要的一项是什么？”
• “你希望用户使用时有什么感受？（快速、安心、强大、有趣、简单）”
• “哪些工作流需要即时响应，哪些可以等待加载？”

第 3 轮：技术与平台

• “目标平台是什么？（iOS、Android、两者、Web、桌面端、CLI）”
• “是否有需要集成的现有后端、数据库、身份验证系统或 API？”
• “你对技术栈或框架有偏好吗？还是需要我给出建议？”
• “是否需要实时功能？（实时更新、协作、通知）”
• “是否需要离线支持？哪些功能应在没有网络时仍可使用？”
• “是否涉及第三方服务？（支付、地图、分析、AI/ML、消息）”

第 4 轮：数据与业务逻辑

• “系统中的核心实体或对象有哪些？（用户、帖子、订单等）”
• “它们之间有哪些关键关系？（用户拥有多个 X，X 属于 Y）”
• “是否有不同的用户角色或权限级别？请分别说明。”
• “是否有复杂的业务规则？（定价层级、审批工作流、计算）”
• “哪些数据属于敏感数据？（PII、财务、健康）”

第 5 轮：范围与限制

• “哪些内容属于 MVP、哪些是锦上添花、哪些明确暂不考虑？”
• “是否有硬性截止日期或限制？”
• “是否有设计偏好？（深色模式、特定品牌色、喜欢的参考应用）”
• “无障碍方面有何要求？（屏幕阅读器支持、色盲、运动障碍）”
• “是否需要国际化？需要支持哪些语言或地区？”
• “是否有合规要求？（GDPR、HIPAA、SOC2、PCI）”

第 6 轮：边缘情况与打磨

• “出现问题时会怎样处理？（没有网络、服务器错误、输入无效）”
• “有哪些空状态？（新用户、暂无数据、搜索无结果）”
• “系统应发送哪些通知、电子邮件或提醒？”
• “新用户如何通过引导流程了解应用？”
• “是否需要管理后台？（仪表盘、内容审核、分析）”

无需提出每一个问题。对于明显与项目无关的问题，可以跳过。但必须至少涵盖以上 6 轮中的 4 轮。请自行判断：如果用户的描述模糊，就多问一些；如果描述详细，就重点询问尚不明确的部分。

每轮结束后，先确认你了解到的信息，并说明在进入下一轮之前还需要了解什么。掌握足够信息、能够编写完整 PRD 后即可停止提问。

生成 .ralph/specs/PRD.md

编写完整 PRD，并包含以下所有章节：

# PRD: [Project Name]

## 1. Overview
One paragraph describing what this product does and why it exists.

## 2. Target Users
| User Type | Description | Primary Need |
|-----------|-------------|--------------|
| [Persona 1] | [Who they are] | [What they need] |
| [Persona 2] | [Who they are] | [What they need] |

## 3. User Stories

### Epic: [Feature Area 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:
    - [ ] ...

### Epic: [Feature Area 2]
- **US-003**: ...

(Continue for all features)

## 4. Technical Requirements

### Stack
| Layer | Technology | Rationale |
|-------|-----------|-----------|
| 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] |

### Architecture
- [Key architectural decisions]
- [Data flow description]
- [API structure]

### Data Model
| Entity | Key Fields | Relationships |
|--------|-----------|---------------|
| User | id, email, name, avatar | has_many: workouts |
| Workout | id, user_id, date, type | belongs_to: user, has_many: sets |
| ... | ... | ... |

### API Endpoints / Procedures
| Method | Path / Name | Purpose | Auth |
|--------|------------|---------|------|
| POST | /auth/signup | Create account | Public |
| GET | /workouts | List user workouts | Authenticated |
| ... | ... | ... | ... |

## 5. Screens & Navigation

### Screen Map

应用 ├── 身份验证流程（未验证身份） │ ├── 欢迎页 │ ├── 注册 │ ├── 登录 │ └── 忘记密码 └── 主选项卡（已验证身份） ├── 首页 / 仪表盘 ├── [功能界面 1] ├── [功能界面 2] └── 个人资料 / 设置

### Screen Descriptions
| Screen | Purpose | Key Components |
|--------|---------|----------------|
| Home | [What it shows] | [Cards, lists, charts, etc.] |
| ... | ... | ... |

## 6. Non-Functional Requirements

### Performance
- App launch < [X] seconds
- Screen transitions < [X]ms
- API response time < [X]ms

### Security
- [Auth requirements]
- [Data encryption requirements]
- [RLS / permission model]

### Accessibility
- [WCAG level target]
- [Screen reader support]
- [Minimum touch targets]

### Offline Support
- [What works offline]
- [Sync strategy]

## 7. MVP Scope

### In Scope (MVP)
- [Feature 1]
- [Feature 2]
- [Feature 3]

### Out of Scope (Post-MVP)
- [Deferred feature 1]
- [Deferred feature 2]

## 8. Success Metrics
| Metric | Target | How Measured |
|--------|--------|--------------|
| [e.g., DAU] | [e.g., 100 in first month] | [Analytics tool] |
| ... | ... | ... |

## 9. Open Questions
- [Anything unresolved]
- [Decisions that need user input later]

提交 PRD 以供审批

生成 PRD 后，向用户展示摘要，并在继续之前征求批准。使用 AskUserQuestion：

• “PRD 已生成。请查看 .ralph/specs/PRD.md。准备继续，还是需要修改？”

---

阶段 1：任务推导（基于 PRD）

PRD 获得批准后，直接据此推导 fix_plan.md。

推导规则

1. 每个用户故事都要转化为一个或多个任务
2. 每条验收标准都要转化为一个验证步骤
3. 基础设施/设置任务优先（关键）
4. 核心用户流程为高优先级
5. 增强功能为中优先级
6. 润色/锦上添花为低优先级
7. 每个任务都必须能在单次循环迭代中完成（约 15 分钟的 Claude 工作时间）

生成 .ralph/fix_plan.md

# Fix Plan
Derived from: .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)

## 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: ...

## Medium (Enhancement User Stories)
- [ ] US-004: [Enhancement feature]
  - Verify: [acceptance criteria]
- [ ] US-005: ...

## Low (Polish & Post-MVP prep)
- [ ] 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

每项任务都必须追溯到 PRD 中的具体章节。不得存在无归属任务。

---

阶段 2：循环配置

步骤 1：检查 Ralph 是否已安装

which ralph-loop 2>/dev/null || which ralph 2>/dev/null

如果未安装：

git clone https://github.com/frankbria/ralph-claude-code.git /tmp/ralph-claude-code
cd /tmp/ralph-claude-code && ./install.sh

依赖项：

# macOS
brew install jq tmux coreutils
# Linux
sudo apt install jq tmux coreutils

步骤 2：创建目录结构

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

步骤 3：生成 .ralphrc

从 package.json / pyproject.toml / Cargo.toml / go.mod 检测项目类型并生成：

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

根据项目类型调整 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 *)

步骤 4：生成 PROMPT.md

# Project: [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)

## Project Context
[GENERATED FROM PRD §1 Overview and §4 Technical Requirements]

## Specifications
- Full PRD: `.ralph/specs/PRD.md`
- Additional specs: `.ralph/specs/*`

## Key Architecture Rules
[EXTRACTED FROM PRD §4 Architecture section]

## Build & Test Instructions
See `.ralph/AGENT.md` for how to build, test, and run the project.

## 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

## 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.

步骤 5：生成 AGENT.md

# Agent Instructions

## Build
[detected build command]

## Test
[detected test command]

## Run
[detected run command]

## Lint
[detected lint command]

## Type Check
[detected type check command if applicable]

步骤 6：初始化 git 仓库（对熔断器至关重要）

Ralph 的熔断器通过 git diff --name-only 检测进度。**如果没有 git 仓库，files_changed 始终为 0，熔断器会在 CB_NO_PROGRESS_THRESHOLD 次循环后误触发。**启动循环前，必须确保 git 仓库已创建并包含初始提交。

# Add Ralph state files to .gitignore FIRST
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

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

**这很重要的原因：**没有 git 时，每次循环都会报告文件更改数为 0 → 即使任务已成功完成，熔断器也会在几次循环后开启。

步骤 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.

---

循环的工作原理

退出检测（双条件门槛）

只有同时满足以下两项，Ralph 才会停止：

1. completion_indicators >= 2（在多次循环中累计）
2. Claude 在 RALPH_STATUS 中输出 EXIT_SIGNAL: true

熔断器

触发条件	结果
连续 3 次循环没有文件更改	开启（已暂停）
连续 5 次循环出现相同错误	开启（已暂停）
连续 2 次循环没有进展	半开（监控中）
半开状态下取得进展	关闭（已恢复）

会话连续性

• 通过 --continue 标志保留会话
• 24 小时后过期（可配置）
• Claude 会记住它在各次迭代中的工作内容

速率限制

• 每 5 小时窗口内最多 100 次调用（可配置）
• 达到限制时自动等待并显示倒计时

---

快速参考

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

---

正在为 $ARGUMENTS 设置 Spidey