dff2d358f6
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.
100 lines
2.7 KiB
Markdown
100 lines
2.7 KiB
Markdown
# Example: REST API with Specifications
|
|
|
|
This example shows a medium-complexity Ralph configuration for a bookstore REST API. It demonstrates when and how to use the specs/ directory.
|
|
|
|
## What This Example Demonstrates
|
|
|
|
- **Focused PROMPT.md** - High-level goals and principles
|
|
- **Detailed specs/api.md** - Endpoint specifications that are too detailed for PROMPT.md
|
|
- **Structured fix_plan.md** - Tasks organized by feature area
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
rest-api/
|
|
├── .ralph/
|
|
│ ├── PROMPT.md # Project vision and principles
|
|
│ ├── fix_plan.md # Implementation tasks
|
|
│ └── specs/
|
|
│ └── api.md # Detailed API specifications
|
|
├── .ralphrc # Configuration (auto-generated)
|
|
└── README.md # This file
|
|
```
|
|
|
|
## Why This Example Uses specs/
|
|
|
|
The PROMPT.md keeps things high-level:
|
|
- What the API is for (bookstore inventory)
|
|
- Technology stack (FastAPI, PostgreSQL)
|
|
- Key principles (REST conventions, authentication)
|
|
|
|
But the API needs detailed specifications that would clutter PROMPT.md:
|
|
- Exact request/response formats
|
|
- Validation rules
|
|
- Error codes
|
|
- Pagination behavior
|
|
|
|
That's what `specs/api.md` is for.
|
|
|
|
## How to Use This Example
|
|
|
|
1. Copy this directory to a new location:
|
|
```bash
|
|
cp -r examples/rest-api ~/my-bookstore-api
|
|
cd ~/my-bookstore-api
|
|
```
|
|
|
|
2. Initialize git and Python environment:
|
|
```bash
|
|
git init
|
|
python -m venv venv
|
|
source venv/bin/activate
|
|
pip install fastapi uvicorn sqlalchemy pytest
|
|
```
|
|
|
|
3. Run Ralph:
|
|
```bash
|
|
ralph --monitor
|
|
```
|
|
|
|
## Key Points
|
|
|
|
### PROMPT.md Sets Direction
|
|
|
|
PROMPT.md answers "what are we building and how?" without getting into implementation details.
|
|
|
|
### specs/api.md Provides Details
|
|
|
|
When you need to specify:
|
|
- Exact endpoint paths and methods
|
|
- Request/response schemas
|
|
- Business rules and constraints
|
|
- Error handling behavior
|
|
|
|
These details help Ralph implement correctly on the first try.
|
|
|
|
### fix_plan.md References specs/
|
|
|
|
Notice how tasks reference the specification:
|
|
```markdown
|
|
- [ ] Implement book endpoints per specs/api.md
|
|
```
|
|
|
|
This tells Ralph where to find the detailed requirements.
|
|
|
|
## When to Add More Specs
|
|
|
|
Consider adding additional spec files for:
|
|
- **specs/database.md** - Schema details, relationships, indexes
|
|
- **specs/auth.md** - Token formats, permission rules, session handling
|
|
- **specs/stdlib/errors.md** - Standard error response format
|
|
- **specs/stdlib/pagination.md** - Pagination conventions
|
|
|
|
## Comparison with Simple Example
|
|
|
|
| Aspect | Simple CLI | REST API |
|
|
|--------|-----------|----------|
|
|
| Complexity | Low | Medium |
|
|
| Uses specs/ | No | Yes |
|
|
| PROMPT.md length | ~40 lines | ~30 lines |
|
|
| Why | Self-contained | API contracts need detail |
|