Initial commit
This commit is contained in:
Zhongwei Li
468
references/example-enhanced-phase.md
Normal file
468
references/example-enhanced-phase.md
Normal file
@@ -0,0 +1,468 @@
|
||||
# Example: Enhanced Phase with File-Level Detail
|
||||
|
||||
This document shows before/after examples of phases with and without file-level detail enhancements.
|
||||
|
||||
---
|
||||
|
||||
## Example Project: Task Management API
|
||||
|
||||
A simple task management system with user authentication, CRUD operations, and tagging.
|
||||
|
||||
---
|
||||
|
||||
## BEFORE: Basic Phase (Without File-Level Detail)
|
||||
|
||||
```markdown
|
||||
## Phase 3: Tasks API
|
||||
|
||||
**Type**: API
|
||||
**Estimated**: 4 hours (~4 minutes human time)
|
||||
**Files**: `src/routes/tasks.ts`, `src/lib/schemas.ts`, `src/middleware/auth.ts`
|
||||
|
||||
### Tasks
|
||||
- [ ] Create task validation schemas
|
||||
- [ ] Implement GET /api/tasks endpoint
|
||||
- [ ] Implement POST /api/tasks endpoint
|
||||
- [ ] Implement PATCH /api/tasks/:id endpoint
|
||||
- [ ] Implement DELETE /api/tasks/:id endpoint
|
||||
- [ ] Add error handling
|
||||
- [ ] Test all endpoints
|
||||
|
||||
### Verification Criteria
|
||||
- [ ] All endpoints return correct status codes
|
||||
- [ ] Validation works properly
|
||||
- [ ] Authentication is enforced
|
||||
- [ ] CRUD operations work
|
||||
|
||||
### Exit Criteria
|
||||
Task API is complete and functional.
|
||||
```
|
||||
|
||||
**Problems with basic phase**:
|
||||
- ❌ Claude doesn't know file relationships (what imports what)
|
||||
- ❌ No indication of which file to start with
|
||||
- ❌ Missing security considerations (ownership checks)
|
||||
- ❌ No performance considerations (pagination)
|
||||
- ❌ Vague verification criteria
|
||||
- ❌ Token waste: Claude will grep/glob to understand structure
|
||||
|
||||
---
|
||||
|
||||
## AFTER: Enhanced Phase (With File-Level Detail)
|
||||
|
||||
```markdown
|
||||
## Phase 3: Tasks API
|
||||
|
||||
**Type**: API
|
||||
**Estimated**: 4 hours (~4 minutes human time)
|
||||
**Files**: `src/routes/tasks.ts` (new), `src/lib/schemas.ts` (modify), `src/middleware/auth.ts` (existing)
|
||||
|
||||
### File Map
|
||||
|
||||
- `src/routes/tasks.ts` (estimated ~150 lines)
|
||||
- **Purpose**: CRUD endpoints for task management
|
||||
- **Key exports**: GET, POST, PATCH, DELETE handlers
|
||||
- **Dependencies**:
|
||||
- `../lib/schemas` (taskSchema, createTaskSchema, updateTaskSchema)
|
||||
- `../middleware/auth` (authenticateUser middleware)
|
||||
- `env.DB` (D1 binding)
|
||||
- **Used by**: Main Hono app (src/index.ts)
|
||||
- **Route**: `/api/tasks` and `/api/tasks/:id`
|
||||
|
||||
- `src/lib/schemas.ts` (add ~40 lines to existing)
|
||||
- **Purpose**: Zod validation schemas for request/response validation
|
||||
- **Key exports**:
|
||||
- `taskSchema` - Complete task object
|
||||
- `createTaskSchema` - New task input validation
|
||||
- `updateTaskSchema` - Partial task updates
|
||||
- **Dependencies**: `zod` package
|
||||
- **Used by**: routes/tasks.ts (validation), frontend forms (type inference)
|
||||
- **Modifications**: Add three new schema definitions to existing file
|
||||
|
||||
- `src/middleware/auth.ts` (existing, no changes needed)
|
||||
- **Purpose**: JWT verification and user extraction
|
||||
- **Key exports**: `authenticateUser` middleware
|
||||
- **Note**: Already implemented in Phase 2, just import and use
|
||||
|
||||
### Data Flow
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant C as Client (Browser)
|
||||
participant W as Worker (Hono)
|
||||
participant A as Auth Middleware
|
||||
participant V as Validator (Zod)
|
||||
participant D as D1 Database
|
||||
|
||||
C->>W: POST /api/tasks<br/>{title, description}
|
||||
Note over W: Route: routes/tasks.ts
|
||||
W->>A: authenticateUser()
|
||||
Note over A: Check JWT token
|
||||
A-->>W: {user_id, email}
|
||||
W->>V: validateSchema(createTaskSchema)
|
||||
Note over V: Validate request body
|
||||
V-->>W: {validated data}
|
||||
W->>D: INSERT INTO tasks<br/>(user_id, title, description)
|
||||
D-->>W: {id, title, description, created_at}
|
||||
W->>C: 201 Created<br/>{task object}
|
||||
```
|
||||
|
||||
### Critical Dependencies
|
||||
|
||||
**Internal** (codebase files):
|
||||
- `src/middleware/auth.ts` - JWT authentication (must run before routes)
|
||||
- `src/lib/schemas.ts` - Validation schemas (import and extend)
|
||||
- `src/index.ts` - Main Hono app (register routes here)
|
||||
|
||||
**External** (npm packages):
|
||||
- `zod` (^3.23.8) - Schema validation
|
||||
- `hono` (^4.6.14) - Web framework
|
||||
- `@clerk/backend` (^1.18.5) - JWT verification
|
||||
|
||||
**Configuration** (environment):
|
||||
- `CLERK_SECRET_KEY` - Set in wrangler.jsonc secrets
|
||||
- No additional env vars needed
|
||||
|
||||
**Cloudflare Bindings**:
|
||||
- `DB` (D1 database) - Must be configured in wrangler.jsonc:
|
||||
```jsonc
|
||||
{
|
||||
"d1_databases": [
|
||||
{
|
||||
"binding": "DB",
|
||||
"database_name": "task-manager-db",
|
||||
"database_id": "your-database-id"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Gotchas & Known Issues
|
||||
|
||||
**🔒 Security: Ownership Verification Required**:
|
||||
- PATCH and DELETE **must** verify `task.user_id === user.id` before mutations
|
||||
- Failing to check allows users to modify/delete others' tasks (critical security vulnerability)
|
||||
- Pattern:
|
||||
```typescript
|
||||
// Fetch task first
|
||||
const task = await env.DB.prepare('SELECT * FROM tasks WHERE id = ?').bind(id).first();
|
||||
if (!task || task.user_id !== user.id) {
|
||||
return c.json({ error: 'Not found or unauthorized' }, 404);
|
||||
}
|
||||
// Now safe to update/delete
|
||||
```
|
||||
|
||||
**⚡ Performance: Pagination Required for GET**:
|
||||
- Without pagination, endpoint returns ALL tasks (performance issue for users with 1000+ tasks)
|
||||
- Max: 50 tasks per page (reasonable default)
|
||||
- Use query params: `?page=1&limit=50`
|
||||
- Pattern:
|
||||
```typescript
|
||||
const page = parseInt(c.req.query('page') || '1');
|
||||
const limit = Math.min(parseInt(c.req.query('limit') || '50'), 100); // Cap at 100
|
||||
const offset = (page - 1) * limit;
|
||||
|
||||
const tasks = await env.DB.prepare(
|
||||
'SELECT * FROM tasks WHERE user_id = ? AND deleted_at IS NULL ORDER BY created_at DESC LIMIT ? OFFSET ?'
|
||||
).bind(user.id, limit, offset).all();
|
||||
```
|
||||
|
||||
**🗑️ Data Integrity: Soft Delete Pattern**:
|
||||
- Don't use `DELETE FROM tasks` (hard delete loses data permanently)
|
||||
- Use `UPDATE tasks SET deleted_at = ? WHERE id = ?` (soft delete)
|
||||
- Reasons:
|
||||
- Audit trail (know when/why data was deleted)
|
||||
- Undo capability (restore deleted tasks)
|
||||
- Data recovery (prevent accidental data loss)
|
||||
- Filter in queries: `WHERE deleted_at IS NULL`
|
||||
|
||||
**🕐 Timezone Handling**:
|
||||
- Store all timestamps as UTC unix timestamps (INTEGER)
|
||||
- Convert to user's timezone in frontend only
|
||||
- Patterns:
|
||||
- Storage: `Math.floor(Date.now() / 1000)` (unix timestamp in seconds)
|
||||
- Display: `new Date(timestamp * 1000).toLocaleString()`
|
||||
- SQLite date functions won't work with unix timestamps - use JavaScript
|
||||
|
||||
**🔍 Case-Sensitive Search**:
|
||||
- SQLite's LIKE is case-insensitive by default
|
||||
- For case-sensitive search, use: `WHERE title LIKE ? COLLATE NOCASE`
|
||||
- For full-text search, consider adding FTS5 table (separate phase)
|
||||
|
||||
### Tasks
|
||||
|
||||
- [ ] Add task schemas to `src/lib/schemas.ts`
|
||||
- [ ] `taskSchema` (base schema)
|
||||
- [ ] `createTaskSchema` (omit id, user_id, timestamps)
|
||||
- [ ] `updateTaskSchema` (partial with only title, description, completed)
|
||||
|
||||
- [ ] Create `src/routes/tasks.ts` file
|
||||
- [ ] Set up Hono router with auth middleware
|
||||
- [ ] Implement GET /api/tasks (with pagination)
|
||||
- [ ] Implement POST /api/tasks (with validation)
|
||||
- [ ] Implement PATCH /api/tasks/:id (with ownership check)
|
||||
- [ ] Implement DELETE /api/tasks/:id (soft delete with ownership check)
|
||||
|
||||
- [ ] Register task routes in `src/index.ts`
|
||||
- [ ] Import task routes
|
||||
- [ ] Mount at `/api/tasks`
|
||||
|
||||
- [ ] Error handling
|
||||
- [ ] 400 for validation errors (Zod messages)
|
||||
- [ ] 401 for missing/invalid JWT
|
||||
- [ ] 404 for non-existent task IDs
|
||||
- [ ] 403 for ownership violations
|
||||
|
||||
- [ ] Testing (all endpoints with curl or Postman)
|
||||
- [ ] Test with valid JWT
|
||||
- [ ] Test with invalid/missing JWT
|
||||
- [ ] Test with invalid data
|
||||
- [ ] Test pagination parameters
|
||||
- [ ] Test ownership checks
|
||||
|
||||
### Verification Criteria
|
||||
|
||||
**Authentication**:
|
||||
- [ ] Requests without JWT return 401 Unauthorized
|
||||
- [ ] Requests with invalid JWT return 401 Unauthorized
|
||||
- [ ] Requests with valid JWT proceed to handler
|
||||
|
||||
**GET /api/tasks** (List):
|
||||
- [ ] Returns 200 with array of user's tasks (only their tasks)
|
||||
- [ ] Returns empty array `[]` for users with no tasks
|
||||
- [ ] Pagination works: `?page=2` returns correct offset
|
||||
- [ ] Limit works: `?limit=10` returns max 10 tasks
|
||||
- [ ] Deleted tasks are excluded (WHERE deleted_at IS NULL)
|
||||
- [ ] Tasks are sorted by created_at DESC (newest first)
|
||||
|
||||
**POST /api/tasks** (Create):
|
||||
- [ ] Valid data returns 201 Created with task object
|
||||
- [ ] Task has auto-generated `id` (integer)
|
||||
- [ ] Task has `user_id` matching authenticated user
|
||||
- [ ] Task has `created_at` timestamp
|
||||
- [ ] Invalid data returns 400 with Zod error messages
|
||||
- [ ] Missing required fields (title) returns 400
|
||||
|
||||
**PATCH /api/tasks/:id** (Update):
|
||||
- [ ] Valid update returns 200 with updated task
|
||||
- [ ] Can update `title`, `description`, `completed` fields
|
||||
- [ ] Cannot update `id`, `user_id`, `created_at` (immutable)
|
||||
- [ ] Invalid task ID returns 404
|
||||
- [ ] Another user's task returns 404 (not 403 to avoid leaking existence)
|
||||
- [ ] Deleted task returns 404
|
||||
|
||||
**DELETE /api/tasks/:id** (Soft Delete):
|
||||
- [ ] Valid delete returns 204 No Content
|
||||
- [ ] Task still exists in database (SELECT * FROM tasks WHERE id = ?)
|
||||
- [ ] Task has `deleted_at` timestamp set
|
||||
- [ ] Task no longer appears in GET /api/tasks
|
||||
- [ ] Deleting same task twice returns 404 (already deleted)
|
||||
- [ ] Another user's task returns 404
|
||||
|
||||
**Performance**:
|
||||
- [ ] GET /api/tasks with 100+ tasks completes in <200ms
|
||||
- [ ] Pagination limits result set (never returns unbounded data)
|
||||
|
||||
### Exit Criteria
|
||||
|
||||
All CRUD operations work correctly with:
|
||||
- ✅ Proper HTTP status codes (200, 201, 204, 400, 401, 404)
|
||||
- ✅ Request validation via Zod schemas
|
||||
- ✅ Authentication enforcement (JWT required)
|
||||
- ✅ Ownership checks (users can only access their tasks)
|
||||
- ✅ Pagination (prevents performance issues)
|
||||
- ✅ Soft delete (preserves data and audit trail)
|
||||
- ✅ Error messages are helpful and consistent
|
||||
```
|
||||
|
||||
**Benefits of enhanced phase**:
|
||||
- ✅ Claude knows exactly where to start (routes/tasks.ts)
|
||||
- ✅ Clear dependency graph (what imports what)
|
||||
- ✅ Visual data flow (Mermaid diagram shows request/response)
|
||||
- ✅ Security considerations upfront (ownership checks)
|
||||
- ✅ Performance patterns documented (pagination)
|
||||
- ✅ Specific verification criteria (testable, measurable)
|
||||
- ✅ Token savings: ~60-70% reduction (fewer grep/glob operations)
|
||||
|
||||
---
|
||||
|
||||
## More Mermaid Diagram Examples
|
||||
|
||||
### Example 1: UI Component Interaction (Flowchart)
|
||||
|
||||
```mermaid
|
||||
flowchart TB
|
||||
Start([User clicks 'Add Task' button]) --> OpenDialog[TaskDialog opens]
|
||||
OpenDialog --> FillForm[User fills form]
|
||||
FillForm --> ValidateClient{Client-side<br/>validation}
|
||||
ValidateClient -->|Invalid| ShowError[Show validation errors]
|
||||
ShowError --> FillForm
|
||||
ValidateClient -->|Valid| SubmitAPI[POST /api/tasks]
|
||||
SubmitAPI --> ValidateServer{Server-side<br/>validation}
|
||||
ValidateServer -->|400 Error| ShowServerError[Show server errors]
|
||||
ShowServerError --> FillForm
|
||||
ValidateServer -->|201 Success| RefetchTasks[TanStack Query refetch]
|
||||
RefetchTasks --> UpdateUI[UI updates with new task]
|
||||
UpdateUI --> CloseDialog[Dialog closes]
|
||||
CloseDialog --> End([Done])
|
||||
```
|
||||
|
||||
### Example 2: Authentication Flow (Sequence Diagram)
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant U as User (Browser)
|
||||
participant F as Frontend (React)
|
||||
participant C as Clerk
|
||||
participant W as Worker
|
||||
participant D as D1 Database
|
||||
|
||||
U->>F: Enter email/password
|
||||
F->>C: signIn(email, password)
|
||||
C-->>F: JWT token + user data
|
||||
F->>F: Store token in localStorage
|
||||
|
||||
Note over F: User navigates to tasks page
|
||||
|
||||
F->>W: GET /api/tasks<br/>Authorization: Bearer {token}
|
||||
W->>W: Extract token from header
|
||||
W->>C: Verify JWT signature
|
||||
C-->>W: Valid: {user_id, email}
|
||||
W->>D: SELECT * FROM tasks<br/>WHERE user_id = ?
|
||||
D-->>W: Array of tasks
|
||||
W-->>F: 200 OK + tasks array
|
||||
F->>U: Render task list
|
||||
```
|
||||
|
||||
### Example 3: Error Handling Paths (Flowchart)
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
Request[Incoming Request] --> Auth{Auth<br/>Middleware}
|
||||
Auth -->|No token| E401[401 Unauthorized]
|
||||
Auth -->|Invalid token| E401
|
||||
Auth -->|Valid token| Validate{Zod<br/>Validation}
|
||||
Validate -->|Invalid data| E400[400 Bad Request]
|
||||
Validate -->|Valid data| CheckOwnership{Ownership<br/>Check}
|
||||
CheckOwnership -->|Not owner| E404[404 Not Found]
|
||||
CheckOwnership -->|Owner| Database[(Database<br/>Operation)]
|
||||
Database -->|Success| S200[200 OK]
|
||||
Database -->|Error| E500[500 Internal Error]
|
||||
```
|
||||
|
||||
### Example 4: Multi-Service Architecture (Graph)
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
Browser[Browser Client]
|
||||
Worker[Cloudflare Worker]
|
||||
D1[(D1 Database)]
|
||||
R2[(R2 Storage)]
|
||||
KV[(KV Cache)]
|
||||
Clerk[Clerk Auth]
|
||||
AI[Workers AI]
|
||||
|
||||
Browser -->|HTTPS| Worker
|
||||
Worker -->|SQL| D1
|
||||
Worker -->|Files| R2
|
||||
Worker -->|Config| KV
|
||||
Worker -->|Verify JWT| Clerk
|
||||
Worker -->|Inference| AI
|
||||
|
||||
style Browser fill:#e1f5ff
|
||||
style Worker fill:#ffd6a5
|
||||
style D1 fill:#caffbf
|
||||
style R2 fill:#caffbf
|
||||
style KV fill:#caffbf
|
||||
style Clerk fill:#ffc6ff
|
||||
style AI fill:#ffadad
|
||||
```
|
||||
|
||||
### Example 5: Database Relationships (ER Diagram)
|
||||
|
||||
```mermaid
|
||||
erDiagram
|
||||
USERS ||--o{ TASKS : creates
|
||||
TASKS ||--o{ TASK_TAGS : has
|
||||
TAGS ||--o{ TASK_TAGS : applied_to
|
||||
|
||||
USERS {
|
||||
int id PK
|
||||
text email UK
|
||||
int created_at
|
||||
}
|
||||
|
||||
TASKS {
|
||||
int id PK
|
||||
int user_id FK
|
||||
text title
|
||||
text description
|
||||
bool completed
|
||||
int deleted_at
|
||||
int created_at
|
||||
}
|
||||
|
||||
TAGS {
|
||||
int id PK
|
||||
text name UK
|
||||
text color
|
||||
}
|
||||
|
||||
TASK_TAGS {
|
||||
int task_id FK
|
||||
int tag_id FK
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## When to Use Each Diagram Type
|
||||
|
||||
| Diagram Type | Best For | Example Use Cases |
|
||||
|--------------|----------|-------------------|
|
||||
| **Sequence** | Request/response flows, API calls | Authentication, webhooks, multi-step processes |
|
||||
| **Flowchart** | Decision logic, user flows | Form validation, error handling, component state |
|
||||
| **Graph/Architecture** | System components, service boundaries | Multi-service apps, microservices, infrastructure |
|
||||
| **ER Diagram** | Database relationships | Schema design, data modeling |
|
||||
|
||||
---
|
||||
|
||||
## Token Efficiency Comparison
|
||||
|
||||
### Scenario: "Implement task CRUD endpoints"
|
||||
|
||||
**Without file-level detail**:
|
||||
```
|
||||
1. Claude greps for existing routes: ~2k tokens
|
||||
2. Claude globs for schema patterns: ~1k tokens
|
||||
3. Claude reads 3-4 files to understand structure: ~6k tokens
|
||||
4. Claude writes code in wrong location: ~2k tokens
|
||||
5. User corrects: "Use routes/tasks.ts": ~500 tokens
|
||||
6. Claude re-reads and rewrites: ~4k tokens
|
||||
Total: ~15.5k tokens, 2 corrections needed
|
||||
```
|
||||
|
||||
**With file-level detail**:
|
||||
```
|
||||
1. Claude reads IMPLEMENTATION_PHASES.md file map: ~1k tokens
|
||||
2. Claude writes code in correct location first try: ~2k tokens
|
||||
3. Claude references gotchas to implement security checks: ~500 tokens
|
||||
Total: ~3.5k tokens, 0 corrections needed
|
||||
```
|
||||
|
||||
**Savings**: 12k tokens (~77% reduction) + 2 fewer correction cycles
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
Enhanced phases with file-level detail provide:
|
||||
|
||||
1. **Navigation efficiency** - Claude knows exactly where to look
|
||||
2. **Security by default** - Gotchas prevent common vulnerabilities
|
||||
3. **Performance patterns** - Best practices documented upfront
|
||||
4. **Visual clarity** - Mermaid diagrams show complex flows
|
||||
5. **Token savings** - 60-70% reduction vs grep/glob exploration
|
||||
6. **First-try accuracy** - Correct file placement, fewer rewrites
|
||||
|
||||
The small upfront investment in detailed planning (~5 extra minutes) saves significant implementation time and prevents errors.
|
||||
Reference in New Issue
Block a user