Ralph Wiggum 入门指南 第四部分：高级模式与故障排除

# BUILDING MODE

## Pre-Constraints (What to consider first)
- Read IMPLEMENTATION_PLAN.md
- Check progress.txt for prior learnings
- Study existing patterns in the codebase
- Verify dependencies are installed

## Core Task
[Your main instruction here]

## Quality Gates (Must pass before proceeding)
- All tests pass: npm test
- Type check passes: npm run type-check
- Linter passes: npm run lint
- No console.logs or debugger statements remain

## Post-Task Actions
- Commit with semantic message
- Update IMPLEMENTATION_PLAN.md
- Append learning to progress.txt

Implement caching for the API.

We need to improve API performance. Before implementing:

1. What are the slowest endpoints currently? (Analyze with profiler)
2. Which data changes frequently vs rarely?
3. What caching strategy best fits this access pattern?
4. Where should the cache layer live (app, Redis, CDN)?

After analysis, implement the most appropriate solution with tests.

## If You Encounter a Blocker

1. Document the issue in progress.txt
2. Create a TODO.md file with:
   - What you tried
   - Why it didn't work
   - What needs human decision
3. Mark the current task as "blocked" in IMPLEMENTATION_PLAN.md
4. Move to the next independent task

DO NOT spin indefinitely on unsolvable problems.

After completing each task, append:

## [TIMESTAMP] [TASK-ID]: [Task Title]

### What Was Built
- Feature/change summary

### Technical Decisions
- Why this approach over alternatives

### Challenges & Solutions
- What went wrong and how it was fixed

### Learnings for Next Tasks
- Patterns to reuse
- Pitfalls to avoid

### Dependencies/Prerequisites for Related Tasks
- What's now available for other tasks

project-root/
├── ralph/                    # Ralph-specific files
│   ├── phases/
│   │   ├── PROMPT_plan.md
│   │   ├── PROMPT_build.md
│   │   └── PROMPT_refactor.md  # Optional: separate refactor mode
│   ├── IMPLEMENTATION_PLAN.md
│   ├── progress.txt
│   ├── blockers.md             # Current blockers needing human input
│   └── loop.sh                 # Orchestrator script
├── specs/                    # Requirements
│   ├── architecture.md
│   ├── features/
│   │   ├── auth.md
│   │   └── api.md
│   └── non-functional.md     # Performance, security, etc.
├── docs/                     # Generated documentation
├── src/                      # Application code
└── tests/                    # Test suite

# ralph/checkpoints/checkpoint-YYYY-MM-DD-description.md

## Project State
- Branch: feature/user-management
- Commit: abc123
- Tasks completed: 15/30
- Blockers: None

## Ralph Configuration
- Mode: Building
- Max iterations: 100
- Completion promise: "MILESTONE COMPLETE"

## Next Steps
1. Complete user role management (TASK-016 to TASK-020)
2. Then regenerate plan for Phase 2 features
3. Consider splitting into separate Ralph session

## Learnings So Far
- Database schema changes require migration strategy
- Test data setup takes 2-3 iterations
- Auth patterns now stable and reusable

{
  "project": "Todo API",
  "schema_version": "2.0",
  "final_tests": ["npm test", "npm run type-check", "npm run lint"],
  "stories": [
    {
      "id": "S001",
      "priority": 1,
      "title": "User Authentication",
      "category": "backend",
      "description": "Implement JWT-based authentication with login/logout",
      "acceptance": [
        "User can register with email/password",
        "User can login and receive JWT token",
        "Protected routes require valid JWT",
        "User can logout and invalidate token"
      ],
      "steps_to_verify": [
        "Run: npm test -- auth.test.ts",
        "Verify all 12 auth tests pass",
        "Check JWT is stored in httpOnly cookie",
        "Verify token expiry works correctly"
      ],
      "tests": ["npm test -- auth.test.ts"],
      "estimated_complexity": "medium",
      "depends_on": [],
      "passes": false
    },
    {
      "id": "S002",
      "priority": 2,
      "title": "Todo CRUD Endpoints",
      "category": "backend",
      "description": "Create POST, GET, PUT, DELETE endpoints for todos",
      "acceptance": [
        "POST /api/todos creates a todo",
        "GET /api/todos returns user's todos only",
        "PUT /api/todos/:id updates a todo",
        "DELETE /api/todos/:id deletes a todo"
      ],
      "steps_to_verify": [
        "Run: npm test -- todos.test.ts",
        "Test with Postman or curl",
        "Verify authorization works"
      ],
      "tests": ["npm test -- todos.test.ts"],
      "estimated_complexity": "medium",
      "depends_on": ["S001"],
      "passes": false
    }
  ]
}

// Bad: Vague assertion
expect(result).toBeTruthy();

// Good: Specific assertion
expect(result).toEqual({
  id: expect.any(String),
  email: 'test@example.com',
  createdAt: expect.any(Date)
});

If tests fail:
1. Read the test output carefully
2. Identify the specific assertion that failed
3. Check if you're testing the wrong behavior
4. Try a different approach if current one fails twice

Before implementing:
1. Add console.log to see actual vs expected values
2. Run test in isolation: npm test -- --testNamePattern="specific test"
3. Verify mock data matches what code expects

## Security Checklist (MUST verify before committing)

Authentication:
- [ ] Passwords hashed with bcrypt (min 12 rounds)
- [ ] JWTs signed with secure secret (min 32 chars)
- [ ] httpOnly cookies for token storage
- [ ] No secrets in code (use env variables)

Authorization:
- [ ] All protected routes have auth middleware
- [ ] User can only access own resources
- [ ] Admin endpoints check role

Input Validation:
- [ ] All user input validated with Zod/Joi
- [ ] SQL/NoSQL injection prevented (use ORMs)
- [ ] XSS prevention (sanitize HTML)
- [ ] Rate limiting on sensitive endpoints

CORS:
- [ ] Specific origins only (not "*")
- [ ] Credentials: true only with specific origin

# loop.sh - Fresh context each iteration
while true; do
  claude < PROMPT_build.md

  # Check if done
  if grep -q "ALL TASKS COMPLETE" progress.txt; then
    echo "Build complete!"
    break
  fi

  sleep 2
done

Every 10 iterations, before continuing:

1. Run: /compact to compress context
2. Summarize current state:
   - Tasks completed
   - Current task in progress
   - Key patterns established
3. Continue with fresh focus

# Session 1: Core features (Tasks 1-10)
/ralph-loop "$(cat PROMPT_build.md)" --max-iterations 30

# Review, commit, take a break

# Session 2: Advanced features (Tasks 11-20)
/ralph-loop "$(cat PROMPT_build.md)" --max-iterations 30

[14:30] Trying approach A...
[14:35] Approach A failed, trying approach B...
[14:40] Approach B failed, trying approach A again...

Track attempts in progress.txt:

[Iteration X] TASK-005: Attempt #1 - Trying JWT with RSA
[Iteration Y] TASK-005: Attempt #2 - Trying JWT with HS256
[Iteration Z] TASK-005: Attempt #3 - Adding fallback

If task has 3 failed attempts:
1. Mark task as "blocked"
2. Document in blockers.md
3. Move to next task

# Too complex (causes thrashing)
- API must be performant, secure, and scalable

# Specific (Ralph can verify)
- API responds in <200ms (verified by tests)
- All endpoints require authentication (verified by tests)
- Can handle 100 concurrent requests (load test passes)

## Test Requirements (STRICT)

Every commit MUST include tests for:
1. Happy path (success case)
2. Error cases (4xx, 5xx)
3. Edge cases (empty input, missing fields)
4. Authorization (access control)

Before committing, run: npm test -- --coverage

MINIMUM COVERAGE REQUIRED:
- Statements: 80%
- Branches: 75%
- Functions: 80%
- Lines: 80%

If coverage drops below threshold:
- DO NOT commit
- Add missing tests
- Re-run coverage

## Codebase Patterns (MUST FOLLOW)

Before implementing any feature:
1. Study existing features as reference (e.g., the user module)
2. Follow the same directory structure and file organization
3. Reuse established naming conventions and code patterns
4. Only deviate if specs explicitly require it

If unsure about a pattern, check how similar features are implemented
in the codebase before writing new code.

{
  "taskPriority": {
    "TASK-001": 10,
    "TASK-005": 9,
    "TASK-002": 8
  }
}

{
  "logFilters": {
    "exclude": ["Reading", "Skipping"],
    "include": ["✓", "✗", "completed", "failed"]
  }
}

{
  "exportFormat": "markdown"
}

# Ralph-TUI Log Export
**Project:** my-saas-app
**Duration:** 2h 15m
**Tasks Completed:** 12 / 15

## Iteration 1
[10:05:12] Reading specs...
...

{
  "webhooks": {
    "taskComplete": "https://myapp.com/api/ralph-task-complete",
    "testFailure": "https://myapp.com/api/ralph-test-failed"
  }
}

{
  "event": "taskComplete",
  "taskId": "TASK-003",
  "timestamp": "2026-01-16T10:30:45Z",
  "iteration": 12
}

ralph-tui run --pid 12345

{
  "sessionBackups": {
    "enabled": true,
    "interval": 300
  }
}

{
  "logRotation": {
    "maxLines": 10000,
    "archiveOld": true
  }
}

ralph-tui run --port 9999

{
  "port": 9999
}

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest", "--headless", "--output-dir", "screenshots"]
    }
  }
}

After implementing, use Playwright to:
1. Navigate to the local server URL
2. Take a screenshot: screenshots/[task-name].png

Include the screenshot filename in your progress.txt entry.

# Developer A
git checkout -b feature/auth
# Run Ralph for auth tasks
./loop.sh build --tasks "TASK-001 to TASK-005"

# Developer B (different branch)
git checkout -b feature/payments
# Run Ralph for payment tasks
./loop.sh build --tasks "TASK-010 to TASK-015"

# Merge both when complete

# team-progress.md

## Active Ralph Sessions

### Developer: Alice
- Branch: feature/auth
- Tasks: TASK-001 to TASK-005
- Status: In Progress (3/5 complete)
- ETA: 2 hours

### Developer: Bob
- Branch: feature/payments
- Tasks: TASK-010 to TASK-015
- Status: Complete
- Ready for: Code review

## Blocked Tasks Needing Team Discussion
- TASK-008: Payment provider API unclear
- TASK-014: Architecture decision needed

# .github/workflows/ralph-build.yml
name: Ralph Autonomous Build

on:
  workflow_dispatch:
    inputs:
      tasks:
        description: 'Task range (e.g., TASK-001 to TASK-005)'
        required: true

jobs:
  ralph-build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Setup Claude Code
        run: curl -fsSL https://claude.ai/install.sh | bash

      - name: Run Ralph Loop
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          ./loop.sh build \
            --tasks "${{ github.event.inputs.tasks }}" \
            --max-iterations 30

      - name: Create Pull Request
        uses: peter-evans/create-pull-request@v5
        with:
          title: "Ralph Build: ${{ github.event.inputs.tasks }}"
          body: |
            Autonomous build completed by Ralph Wiggum

            Tasks completed:
            ${{ github.event.inputs.tasks }}

            See progress.txt for details.