docs: add user guide and example projects (#139)
New users were confused about which files they write vs. which Ralph manages, and how PROMPT.md, specs/, and fix_plan.md relate to each other. Added: - docs/user-guide/ with quick start tutorial, file reference, and requirements writing guide - examples/simple-cli-tool/ showing minimal Ralph configuration - examples/rest-api/ demonstrating when to use specs/ - README section explaining Ralph files and their relationships Also documents specs/stdlib/ purpose for reusable patterns.
This commit is contained in:
Test User
parent
dbb27d89e9
commit
dff2d358f6
13 changed files with 1386 additions and 2 deletions
190
docs/user-guide/01-quick-start.md
Normal file
190
docs/user-guide/01-quick-start.md
Normal file
|
|
@ -0,0 +1,190 @@
|
|||
# Quick Start: Your First Ralph Project
|
||||
|
||||
This tutorial walks you through enabling Ralph on an existing project and running your first autonomous development loop. By the end, you'll have Ralph building a simple CLI todo app.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Ralph installed globally (`./install.sh` from the ralph-claude-code repo)
|
||||
- Claude Code CLI installed (`npm install -g @anthropic-ai/claude-code`)
|
||||
- A project directory (we'll create one)
|
||||
|
||||
## Step 1: Create Your Project
|
||||
|
||||
Let's create a simple Node.js project:
|
||||
|
||||
```bash
|
||||
mkdir todo-cli
|
||||
cd todo-cli
|
||||
npm init -y
|
||||
git init
|
||||
```
|
||||
|
||||
## Step 2: Enable Ralph
|
||||
|
||||
Run the interactive wizard:
|
||||
|
||||
```bash
|
||||
ralph-enable
|
||||
```
|
||||
|
||||
The wizard will:
|
||||
1. Detect your project type (Node.js/TypeScript)
|
||||
2. Ask about task sources (you can skip for now)
|
||||
3. Create the `.ralph/` directory with starter files
|
||||
|
||||
You'll see output like:
|
||||
|
||||
```
|
||||
Ralph Enable Wizard
|
||||
==================
|
||||
|
||||
Phase 1: Environment Detection
|
||||
------------------------------
|
||||
Detected project type: javascript
|
||||
Detected package manager: npm
|
||||
Git repository: yes
|
||||
|
||||
Phase 2: Task Source Selection
|
||||
------------------------------
|
||||
No task sources selected. You can add tasks manually.
|
||||
|
||||
Phase 3: Configuration
|
||||
------------------------------
|
||||
Creating .ralph/ directory structure...
|
||||
|
||||
Phase 4: File Generation
|
||||
------------------------------
|
||||
Created: .ralph/PROMPT.md
|
||||
Created: .ralph/fix_plan.md
|
||||
Created: .ralph/AGENT.md
|
||||
Created: .ralphrc
|
||||
|
||||
Ralph is now enabled for this project.
|
||||
```
|
||||
|
||||
## Step 3: Customize Your Requirements
|
||||
|
||||
After `ralph-enable`, you have starter files that need customization. Open `.ralph/PROMPT.md` and replace the placeholder content:
|
||||
|
||||
```markdown
|
||||
# Ralph Development Instructions
|
||||
|
||||
## Context
|
||||
You are Ralph, an autonomous AI development agent building a CLI todo application in Node.js.
|
||||
|
||||
## Current Objectives
|
||||
1. Create a command-line todo app with add, list, complete, and delete commands
|
||||
2. Store todos in a JSON file (~/.todos.json)
|
||||
3. Use commander.js for argument parsing
|
||||
4. Include helpful --help output
|
||||
5. Write unit tests with Jest
|
||||
|
||||
## Key Principles
|
||||
- Keep the code simple and readable
|
||||
- Use async/await for file operations
|
||||
- Provide clear error messages
|
||||
- Follow Node.js best practices
|
||||
```
|
||||
|
||||
## Step 4: Define Your Tasks
|
||||
|
||||
Edit `.ralph/fix_plan.md` to list specific tasks:
|
||||
|
||||
```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 module
|
||||
```
|
||||
|
||||
## Step 5: Start Ralph
|
||||
|
||||
Now let Ralph build your project:
|
||||
|
||||
```bash
|
||||
ralph --monitor
|
||||
```
|
||||
|
||||
This opens a tmux session with:
|
||||
- **Left pane**: Ralph loop output (what Claude is doing)
|
||||
- **Right pane**: Live monitoring dashboard
|
||||
|
||||
### What You'll See
|
||||
|
||||
Ralph will:
|
||||
1. Read your PROMPT.md and fix_plan.md
|
||||
2. Start implementing tasks in priority order
|
||||
3. Create files, run tests, update fix_plan.md
|
||||
4. Continue until all tasks are complete
|
||||
|
||||
### Monitoring Tips
|
||||
|
||||
- **Ctrl+B, then D** - Detach from tmux (Ralph keeps running)
|
||||
- **tmux attach -t todo-cli** - Reattach to watch progress
|
||||
- **ralph --status** - Check current loop status
|
||||
|
||||
## Step 6: Review the Results
|
||||
|
||||
When Ralph finishes (or you want to check progress), look at:
|
||||
|
||||
```bash
|
||||
# See what files were created
|
||||
ls -la src/
|
||||
|
||||
# Check the updated fix_plan.md
|
||||
cat .ralph/fix_plan.md
|
||||
|
||||
# Run the tests Ralph wrote
|
||||
npm test
|
||||
|
||||
# Try your new CLI
|
||||
node src/index.js add "Buy groceries"
|
||||
node src/index.js list
|
||||
```
|
||||
|
||||
## What Just Happened?
|
||||
|
||||
Ralph followed this cycle:
|
||||
1. **Read** - Loaded PROMPT.md for context and fix_plan.md for tasks
|
||||
2. **Implement** - Wrote code for the highest priority unchecked task
|
||||
3. **Test** - Ran any tests and fixed failures
|
||||
4. **Update** - Marked completed tasks in fix_plan.md
|
||||
5. **Repeat** - Continued until EXIT_SIGNAL was set
|
||||
|
||||
## Next Steps
|
||||
|
||||
- Read [Understanding Ralph Files](02-understanding-ralph-files.md) to learn what each file does
|
||||
- Check [Writing Effective Requirements](03-writing-requirements.md) for best practices
|
||||
- Explore the [examples/](../../examples/) directory for more complex projects
|
||||
|
||||
## Common Questions
|
||||
|
||||
### Ralph stopped early - why?
|
||||
|
||||
Check `.ralph/logs/` for the latest log. Common reasons:
|
||||
- Rate limit reached (waits for reset)
|
||||
- Circuit breaker opened (detected stuck loop)
|
||||
- All tasks marked complete
|
||||
|
||||
### Ralph keeps running tests without implementing anything
|
||||
|
||||
Your fix_plan.md might be too vague. Make tasks specific and actionable:
|
||||
- Bad: "Improve the code"
|
||||
- Good: "Add error handling for missing ~/.todos.json file"
|
||||
|
||||
### How do I add more features later?
|
||||
|
||||
Just add new tasks to `.ralph/fix_plan.md` and run `ralph --monitor` again. Ralph will pick up where it left off.
|
||||
245
docs/user-guide/02-understanding-ralph-files.md
Normal file
245
docs/user-guide/02-understanding-ralph-files.md
Normal file
|
|
@ -0,0 +1,245 @@
|
|||
# Understanding Ralph Files
|
||||
|
||||
After running `ralph-enable`, `ralph-import`, or `ralph-setup`, you'll have a `.ralph/` directory with several files. This guide explains what each file does and whether you need to edit it.
|
||||
|
||||
## File Reference Table
|
||||
|
||||
| File | Auto-Generated? | Who Writes It | Who Reads It | You Should... |
|
||||
|------|-----------------|---------------|--------------|---------------|
|
||||
| `.ralph/PROMPT.md` | Yes (with smart defaults) | **You** customize it | Ralph reads every loop | Review and customize project goals |
|
||||
| `.ralph/fix_plan.md` | Yes (can import tasks) | **You** + Ralph updates | Ralph reads and updates | Add/modify specific tasks |
|
||||
| `.ralph/AGENT.md` | Yes (detects build commands) | Ralph maintains | Ralph reads for build/test | Rarely edit (auto-maintained) |
|
||||
| `.ralph/specs/` | Empty directory created | **You** add files when needed | Ralph reads for context | Add when PROMPT.md isn't detailed enough |
|
||||
| `.ralph/specs/stdlib/` | Empty directory created | **You** add reusable patterns | Ralph reads for conventions | Add shared patterns and conventions |
|
||||
| `.ralphrc` | Yes (project-aware) | Usually leave as-is | Ralph reads at startup | Rarely edit (sensible defaults) |
|
||||
| `.ralph/logs/` | Created automatically | Ralph writes logs | You review for debugging | Don't edit (read-only) |
|
||||
| `.ralph/status.json` | Created at runtime | Ralph updates | Monitoring tools | Don't edit (read-only) |
|
||||
|
||||
## The Core Files
|
||||
|
||||
### PROMPT.md - Your Project Vision
|
||||
|
||||
**Purpose**: High-level instructions that Ralph reads at the start of every loop.
|
||||
|
||||
**What to include**:
|
||||
- Project description and goals
|
||||
- Key principles or constraints
|
||||
- Technology stack and frameworks
|
||||
- Quality standards
|
||||
|
||||
**What NOT to include**:
|
||||
- Step-by-step implementation tasks (use fix_plan.md)
|
||||
- Detailed API specifications (use specs/)
|
||||
- Build commands (use AGENT.md)
|
||||
|
||||
**Example**:
|
||||
```markdown
|
||||
## 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
|
||||
```
|
||||
|
||||
### fix_plan.md - Your Task List
|
||||
|
||||
**Purpose**: Prioritized checklist of tasks Ralph works through.
|
||||
|
||||
**Key characteristics**:
|
||||
- Ralph checks off `[x]` items as it completes them
|
||||
- Ralph may add new tasks it discovers
|
||||
- You can add, reorder, or remove tasks anytime
|
||||
- More specific tasks = better results
|
||||
|
||||
**Good task structure**:
|
||||
```markdown
|
||||
## 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
|
||||
```
|
||||
|
||||
**Bad task structure**:
|
||||
```markdown
|
||||
- [ ] Make the API work
|
||||
- [ ] Add features
|
||||
- [ ] Fix bugs
|
||||
```
|
||||
|
||||
### specs/ - Detailed Specifications
|
||||
|
||||
**Purpose**: When PROMPT.md isn't enough detail for a feature.
|
||||
|
||||
**When to use specs/**:
|
||||
- Complex features needing detailed requirements
|
||||
- API contracts that must be followed exactly
|
||||
- Data models with specific validation rules
|
||||
- External system integrations
|
||||
|
||||
**When NOT to use specs/**:
|
||||
- Simple CRUD operations
|
||||
- Features already well-explained in PROMPT.md
|
||||
- General coding standards (put in PROMPT.md)
|
||||
|
||||
**Example structure**:
|
||||
```
|
||||
.ralph/specs/
|
||||
├── api-contracts.md # OpenAPI-style endpoint definitions
|
||||
├── data-models.md # Entity relationships and validations
|
||||
└── third-party-auth.md # OAuth integration requirements
|
||||
```
|
||||
|
||||
### specs/stdlib/ - Standard Library Patterns
|
||||
|
||||
**Purpose**: Reusable patterns and conventions for your project.
|
||||
|
||||
**What belongs here**:
|
||||
- Error handling patterns
|
||||
- Logging conventions
|
||||
- Common utility functions specifications
|
||||
- Testing patterns
|
||||
- Code style decisions
|
||||
|
||||
**Example**:
|
||||
```markdown
|
||||
# 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)
|
||||
```
|
||||
|
||||
### AGENT.md - Build Instructions
|
||||
|
||||
**Purpose**: How to build, test, and run the project.
|
||||
|
||||
**Who maintains it**: Primarily Ralph, as it discovers build commands.
|
||||
|
||||
**When you might edit**:
|
||||
- Setting initial build commands for a complex project
|
||||
- Adding environment setup steps
|
||||
- Documenting deployment commands
|
||||
|
||||
### .ralphrc - Project Configuration
|
||||
|
||||
**Purpose**: Project-specific Ralph settings.
|
||||
|
||||
**Default contents** (usually fine as-is):
|
||||
```bash
|
||||
PROJECT_NAME="my-project"
|
||||
PROJECT_TYPE="typescript"
|
||||
MAX_CALLS_PER_HOUR=100
|
||||
ALLOWED_TOOLS="Write,Read,Edit,Bash(git *),Bash(npm *),Bash(pytest)"
|
||||
```
|
||||
|
||||
**When to edit**:
|
||||
- Restricting tool permissions for security
|
||||
- Adjusting rate limits
|
||||
- Changing session timeout
|
||||
|
||||
## File Relationships
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ 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) │ │
|
||||
│ └─────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Common Scenarios
|
||||
|
||||
### Scenario 1: Simple feature addition
|
||||
|
||||
Just edit fix_plan.md:
|
||||
```markdown
|
||||
- [ ] Add a /health endpoint that returns {"status": "ok"}
|
||||
```
|
||||
|
||||
### Scenario 2: Complex feature with specific requirements
|
||||
|
||||
Add a spec file first, then tasks:
|
||||
|
||||
1. Create `.ralph/specs/search-feature.md`:
|
||||
```markdown
|
||||
# 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
|
||||
```
|
||||
|
||||
2. Then add to fix_plan.md:
|
||||
```markdown
|
||||
- [ ] Implement search per specs/search-feature.md
|
||||
```
|
||||
|
||||
### Scenario 3: Establishing team conventions
|
||||
|
||||
Add to specs/stdlib/:
|
||||
```markdown
|
||||
# Logging Conventions
|
||||
|
||||
All service methods must log:
|
||||
- Entry with parameters (DEBUG level)
|
||||
- Exit with result summary (DEBUG level)
|
||||
- Errors with full context (ERROR level)
|
||||
```
|
||||
|
||||
## Tips for Success
|
||||
|
||||
1. **Start simple** - Begin with just PROMPT.md and fix_plan.md. Add specs/ only when needed.
|
||||
|
||||
2. **Be specific** - Vague requirements produce vague results. "Add user auth" is worse than "Add JWT authentication with /login and /logout endpoints".
|
||||
|
||||
3. **Let fix_plan.md evolve** - Ralph will add tasks it discovers. Review periodically and reprioritize.
|
||||
|
||||
4. **Don't over-specify** - If Claude can figure it out from context, you don't need to specify it.
|
||||
|
||||
5. **Review logs** - When something goes wrong, `.ralph/logs/` tells you what Ralph was thinking.
|
||||
323
docs/user-guide/03-writing-requirements.md
Normal file
323
docs/user-guide/03-writing-requirements.md
Normal file
|
|
@ -0,0 +1,323 @@
|
|||
# Writing Effective Requirements
|
||||
|
||||
Ralph works best when it understands what you want. This guide shows you how to write clear requirements in PROMPT.md, when to use specs/, and how fix_plan.md evolves during development.
|
||||
|
||||
## PROMPT.md: Good vs Bad Examples
|
||||
|
||||
### Bad Example
|
||||
|
||||
```markdown
|
||||
# Project
|
||||
|
||||
Make a good API for managing stuff. Use best practices.
|
||||
Should be fast and work well.
|
||||
```
|
||||
|
||||
**Problems**:
|
||||
- What "stuff"? Too vague.
|
||||
- What are "best practices"? Claude will guess.
|
||||
- "Fast" and "work well" aren't measurable.
|
||||
|
||||
### Good Example
|
||||
|
||||
```markdown
|
||||
# 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
|
||||
```
|
||||
|
||||
**Why this works**:
|
||||
- Clear domain (pet adoption shelter)
|
||||
- Specific technology choices
|
||||
- Measurable constraints (pagination limits)
|
||||
- Concrete data model
|
||||
- Defined quality bar
|
||||
|
||||
## fix_plan.md: Task Writing
|
||||
|
||||
### The Goldilocks Principle
|
||||
|
||||
Tasks should be **not too big, not too small**.
|
||||
|
||||
**Too big** (Ralph doesn't know where to start):
|
||||
```markdown
|
||||
- [ ] Build the entire authentication system
|
||||
```
|
||||
|
||||
**Too small** (wastes loop iterations):
|
||||
```markdown
|
||||
- [ ] Create the auth folder
|
||||
- [ ] Create the auth/__init__.py file
|
||||
- [ ] Create the auth/routes.py file
|
||||
```
|
||||
|
||||
**Just right** (one loop of meaningful work):
|
||||
```markdown
|
||||
- [ ] Create auth routes with POST /login and POST /logout endpoints
|
||||
- [ ] Add JWT token generation and validation middleware
|
||||
- [ ] Create refresh token endpoint POST /auth/refresh
|
||||
```
|
||||
|
||||
### Task Structure Template
|
||||
|
||||
```markdown
|
||||
# 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 -->
|
||||
```
|
||||
|
||||
### How fix_plan.md Evolves
|
||||
|
||||
**Initial state** (you write this):
|
||||
```markdown
|
||||
## Priority 1: Database
|
||||
- [ ] Set up database models for Animal, Adopter, Adoption
|
||||
|
||||
## Priority 2: API
|
||||
- [ ] Create CRUD endpoints for animals
|
||||
```
|
||||
|
||||
**After Loop 1** (Ralph updates):
|
||||
```markdown
|
||||
## 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
|
||||
```
|
||||
|
||||
**After Loop 3**:
|
||||
```markdown
|
||||
## 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 adds tasks it discovers and checks them off as it works. You can:
|
||||
- Reorder tasks by moving them to different priority sections
|
||||
- Delete tasks that are no longer relevant
|
||||
- Add new tasks anytime
|
||||
|
||||
## When to Use specs/
|
||||
|
||||
### Use specs/ for complex features
|
||||
|
||||
**PROMPT.md says**:
|
||||
```markdown
|
||||
Add a matching algorithm that suggests animals to adopters.
|
||||
```
|
||||
|
||||
**This is too vague.** Create `.ralph/specs/matching-algorithm.md`:
|
||||
```markdown
|
||||
# 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
|
||||
```json
|
||||
[
|
||||
{"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)
|
||||
```
|
||||
|
||||
**Then in fix_plan.md**:
|
||||
```markdown
|
||||
- [ ] Implement matching algorithm per specs/matching-algorithm.md
|
||||
```
|
||||
|
||||
### Use specs/stdlib/ for conventions
|
||||
|
||||
When you want consistency across the project, document it:
|
||||
|
||||
`.ralph/specs/stdlib/error-responses.md`:
|
||||
```markdown
|
||||
# Error Response Standard
|
||||
|
||||
All API errors return this structure:
|
||||
|
||||
```json
|
||||
{
|
||||
"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 doesn't exist |
|
||||
| ALREADY_ADOPTED | 409 | Animal not available |
|
||||
| UNAUTHORIZED | 401 | Missing/invalid token |
|
||||
```
|
||||
|
||||
### Don't use specs/ for everything
|
||||
|
||||
**Overkill** - You don't need specs/ for:
|
||||
```markdown
|
||||
# User Password Requirements
|
||||
|
||||
Passwords must be at least 8 characters.
|
||||
```
|
||||
|
||||
**Just put it in PROMPT.md**:
|
||||
```markdown
|
||||
## Authentication
|
||||
- Passwords: minimum 8 characters, at least one number
|
||||
- JWT tokens expire after 1 hour
|
||||
```
|
||||
|
||||
## Common Mistakes
|
||||
|
||||
### Mistake 1: Assuming Claude knows your preferences
|
||||
|
||||
**Bad**:
|
||||
```markdown
|
||||
Use standard authentication.
|
||||
```
|
||||
|
||||
**Good**:
|
||||
```markdown
|
||||
Use JWT authentication with 1-hour token expiry.
|
||||
Refresh tokens last 7 days and rotate on use.
|
||||
```
|
||||
|
||||
### Mistake 2: Mixing implementation with requirements
|
||||
|
||||
**Bad** (in PROMPT.md):
|
||||
```markdown
|
||||
Create a file called auth.py and add these imports:
|
||||
import jwt
|
||||
from datetime import datetime
|
||||
```
|
||||
|
||||
**Good** (in PROMPT.md):
|
||||
```markdown
|
||||
Use JWT for authentication. Tokens should expire after 1 hour.
|
||||
```
|
||||
|
||||
Let Ralph figure out the implementation details.
|
||||
|
||||
### Mistake 3: Over-specifying tests
|
||||
|
||||
**Bad**:
|
||||
```markdown
|
||||
- [ ] Write test_create_animal_success
|
||||
- [ ] Write test_create_animal_invalid_species
|
||||
- [ ] Write test_create_animal_missing_name
|
||||
- [ ] Write test_create_animal_negative_age
|
||||
```
|
||||
|
||||
**Good**:
|
||||
```markdown
|
||||
- [ ] Write tests for animal creation (success and validation errors)
|
||||
```
|
||||
|
||||
Ralph knows how to write tests. Tell it what to test, not how.
|
||||
|
||||
### Mistake 4: Forgetting the "why"
|
||||
|
||||
**Bad**:
|
||||
```markdown
|
||||
Add a 100ms delay to all API responses.
|
||||
```
|
||||
|
||||
**Good**:
|
||||
```markdown
|
||||
Add a 100ms delay to all API responses (required for rate limiting compliance with external payment API).
|
||||
```
|
||||
|
||||
When Ralph understands *why*, it makes better decisions.
|
||||
|
||||
## Checklist: Before Running Ralph
|
||||
|
||||
Before `ralph --monitor`, verify:
|
||||
|
||||
- [ ] **PROMPT.md has clear context** - Does Ralph know what it's building?
|
||||
- [ ] **Technology stack is specified** - Did you pick the frameworks?
|
||||
- [ ] **Key constraints are documented** - Auth approach? API conventions?
|
||||
- [ ] **fix_plan.md has specific tasks** - Can Ralph start on task 1 immediately?
|
||||
- [ ] **Complex features have specs/** - Is anything too vague for PROMPT.md?
|
||||
|
||||
If you can answer "yes" to these, Ralph will do good work.
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Need to... | Put it in... |
|
||||
|------------|--------------|
|
||||
| Set project vision and principles | PROMPT.md |
|
||||
| Define technology stack | PROMPT.md |
|
||||
| List specific implementation tasks | fix_plan.md |
|
||||
| Document complex feature requirements | specs/feature-name.md |
|
||||
| Establish coding conventions | specs/stdlib/convention-name.md |
|
||||
| Configure Ralph behavior | .ralphrc |
|
||||
37
docs/user-guide/README.md
Normal file
37
docs/user-guide/README.md
Normal file
|
|
@ -0,0 +1,37 @@
|
|||
# Ralph User Guide
|
||||
|
||||
This guide helps you get started with Ralph and understand how to configure it effectively for your projects.
|
||||
|
||||
## Guides
|
||||
|
||||
### [Quick Start: Your First Ralph Project](01-quick-start.md)
|
||||
A hands-on tutorial that walks you through enabling Ralph on an existing project and running your first autonomous development loop. You'll build a simple CLI todo app from scratch.
|
||||
|
||||
### [Understanding Ralph Files](02-understanding-ralph-files.md)
|
||||
Learn which files Ralph creates, which ones you should customize, and how they work together. Includes a complete reference table and explanations of file relationships.
|
||||
|
||||
### [Writing Effective Requirements](03-writing-requirements.md)
|
||||
Best practices for writing PROMPT.md, when to use specs/, and how fix_plan.md evolves during development. Includes good and bad examples.
|
||||
|
||||
## Example Projects
|
||||
|
||||
Check out the [examples/](../../examples/) directory for complete, realistic project configurations:
|
||||
|
||||
- **[simple-cli-tool](../../examples/simple-cli-tool/)** - Minimal example showing core Ralph files
|
||||
- **[rest-api](../../examples/rest-api/)** - Medium complexity with specs/ directory usage
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| I want to... | Do this |
|
||||
|-------------|---------|
|
||||
| Enable Ralph on an existing project | `ralph-enable` |
|
||||
| Import a PRD/requirements doc | `ralph-import requirements.md project-name` |
|
||||
| Create a new project from scratch | `ralph-setup my-project` |
|
||||
| Start Ralph with monitoring | `ralph --monitor` |
|
||||
| Check what Ralph is doing | `ralph --status` |
|
||||
|
||||
## Need Help?
|
||||
|
||||
- **[Main README](../../README.md)** - Full documentation and configuration options
|
||||
- **[CONTRIBUTING.md](../../CONTRIBUTING.md)** - How to contribute to Ralph
|
||||
- **[GitHub Issues](https://github.com/frankbria/ralph-claude-code/issues)** - Report bugs or request features
|
||||
Loading…
Add table
Add a link
Reference in a new issue