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 の生成

通常の Ralph と Spidey の違いはここにあります。コードを書く前に、適切な PRD を生成します。

詳細な質問（必須）

PRD を作成する前に、十分な聞き取りを行います。AskUserQuestion を使用して、複数のラウンドに分けて質問してください。急いで PRD を生成してはいけません。PRD の品質は、プロジェクトをどれだけ理解できているかに全面的に左右されます。全体像が明確になるまで質問を続けてください。

ラウンド 1：ビジョンとユーザー

• 「どのような問題を解決しますか？ 現在の課題は何ですか？」
• 「主なユーザーは誰ですか？ 異なるペルソナを 2〜3 つ説明してください。」
• 「成功とはどのような状態ですか？ うまく機能していると、どうすればわかりますか？」
• 「既存の製品や競合はありますか？ それらの問題点は何ですか？」

ラウンド 2：コア体験

• 「初めて開いてから日常的に使うまでの理想的なユーザージャーニーを説明してください。」
• 「役に立つために必ず必要な機能は何ですか？ 3 つ挙げてください。その中で最も重要なものは何ですか？」
• 「使うとき、ユーザーにどのように感じてほしいですか？（速い、落ち着く、パワフル、楽しい、シンプル）」
• 「即座に表示する必要があるワークフローと、読み込みに時間がかかってもよいワークフローはありますか？」

ラウンド 3：技術とプラットフォーム

• 「対象プラットフォームは何ですか？（iOS、Android、両方、ウェブ、デスクトップ、CLI）」
• 「連携が必要な既存のバックエンド、データベース、認証システム、API はありますか？」
• 「使用するスタックやフレームワークに希望はありますか？ それともこちらから提案しましょうか？」
• 「リアルタイム機能が必要ですか？（ライブ更新、コラボレーション、通知）」
• 「オフライン対応は必要ですか？ インターネット接続がなくても使える必要がある機能は何ですか？」
• 「サードパーティーサービスは必要ですか？（決済、地図、アナリティクス、AI/ML、メッセージング）」

ラウンド 4：データとビジネスロジック

• 「このシステムの主なエンティティやオブジェクトは何ですか？（ユーザー、投稿、注文など）」
• 「それらの主な関係は何ですか？（あるユーザーが複数の X を持つ、X が Y に属するなど）」
• 「ユーザーの役割や権限レベルは複数ありますか？ それぞれ説明してください。」
• 「複雑なビジネスルールはありますか？（料金プラン、承認ワークフロー、計算など）」
• 「機密データは何ですか？（個人情報、財務情報、健康情報）」

ラウンド 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 generated. Review .ralph/specs/PRD.md. Ready to proceed, or want changes?"

---

PHASE 1: タスクの導出（PRD に基づく）

PRD の承認後、そこから直接 fix_plan.md を導出します。

導出ルール

1. 各ユーザーストーリーを 1 つ以上のタスクにします
2. 各受け入れ基準を検証ステップにします
3. インフラストラクチャ／セットアップタスクを最初に配置します（Critical）
4. コアユーザーフローは High 優先度にします
5. 機能強化は Medium にします
6. 仕上げ／あれば便利な機能は Low にします
7. 各タスクは 1 回のループ反復（Claude の作業で約 15 分）で完了できるようにします

.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 セクションに対応している必要があります。対応する PRD セクションのないタスクを作成してはいけません。

---

PHASE 2: ループの設定

Step 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

Step 2: ディレクトリー構造を作成する

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

Step 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 *) を追加します

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

Step 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]

Step 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 件と報告されます。その結果、数回のループでサーキットブレーカーが作動します。

Step 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 ループ続く	OPEN（停止）
同じエラーが 5 ループ続く	OPEN（停止）
進捗なしが 2 ループ続く	HALF_OPEN（監視中）
HALF_OPEN 中に進捗がある	CLOSED（復旧）

セッションの継続性

• セッションは --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

---

Spidey を次の対象としてセットアップしています：$ARGUMENTS