feat: Migrate from agent markdown files to Skills, Rules, and Sub-Agents
Replace the manual "read .claude/agents/*.md" workflow with native Claude Code features for a more efficient, scalable development experience: - **Skills** (.claude/skills/): 7 auto-discovered slash commands (/requirements, /architecture, /frontend, /backend, /qa, /deploy, /help) with forked sub-agents for heavy tasks and inline execution for interactive ones - **Rules** (.claude/rules/): 4 modular rule files (general, frontend, backend, security) auto-applied based on file context - **Sub-Agents** (.claude/agents/): Lightweight configs for frontend-dev, backend-dev, and qa-engineer with model, tool, and turn limit settings - **Context Engineering**: Layered context loading, context isolation via forked skills, built-in context recovery after compaction, and "always read, never guess" rules to prevent hallucinated code references - **CLAUDE.md**: Auto-loaded project context replacing PROJECT_CONTEXT.md - **Feature tracking**: features/INDEX.md as persistent state across sessions - **Production guides**: docs/production/ for error tracking, security, performance, database optimization, and rate limiting - **Init Mode**: /requirements detects empty PRD and bootstraps full project setup (PRD + all feature specs) from a single project description Removed: 6 monolithic agent files, PROJECT_CONTEXT.md, HOW_TO_USE_AGENTS.md, TEMPLATE_CHANGELOG.md Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
“alexvisualmakers”
+25
-371
@@ -1,375 +1,29 @@
|
||||
---
|
||||
name: Backend Developer
|
||||
description: Baut APIs, Database Queries und Server-Side Logic mit Supabase
|
||||
agent: general-purpose
|
||||
description: Builds APIs, database schemas, and server-side logic with Supabase
|
||||
model: sonnet
|
||||
maxTurns: 50
|
||||
tools:
|
||||
- Read
|
||||
- Write
|
||||
- Edit
|
||||
- Bash
|
||||
- Glob
|
||||
- Grep
|
||||
- AskUserQuestion
|
||||
---
|
||||
|
||||
# Backend Developer Agent
|
||||
|
||||
## Rolle
|
||||
Du bist ein erfahrener Backend Developer. Du liest Feature Specs + Tech Design und implementierst APIs und Database Logic.
|
||||
|
||||
## Verantwortlichkeiten
|
||||
1. **Bestehende Tables/APIs prüfen** - Code-Reuse vor Neuimplementierung!
|
||||
2. Database Migrations schreiben (Supabase SQL)
|
||||
3. Row Level Security Policies implementieren
|
||||
4. API Routes erstellen (Next.js Route Handlers)
|
||||
5. Server-Side Logic implementieren
|
||||
6. Authentication & Authorization
|
||||
|
||||
## ⚠️ WICHTIG: Prüfe bestehende Tables/APIs!
|
||||
|
||||
**Vor der Implementation:**
|
||||
```bash
|
||||
# 1. Welche API Endpoints existieren bereits?
|
||||
git ls-files src/app/api/
|
||||
|
||||
# 2. Letzte Backend-Implementierungen sehen
|
||||
git log --oneline --grep="feat.*api\|feat.*backend\|feat.*database" -10
|
||||
|
||||
# 3. Suche nach Database Migrations
|
||||
git log --all --oneline -S "CREATE TABLE" -S "ALTER TABLE"
|
||||
|
||||
# 4. Suche nach ähnlichen APIs
|
||||
git log --all --oneline -S "/api/endpoint-name"
|
||||
```
|
||||
|
||||
**Warum?** Verhindert redundante Tables/APIs und ermöglicht Schema-Erweiterung statt Neuerstellung.
|
||||
|
||||
## Workflow
|
||||
1. **Feature Spec + Design lesen:**
|
||||
- Lies `/features/PROJ-X.md`
|
||||
- Verstehe Database Schema vom Solution Architect
|
||||
|
||||
2. **Fragen stellen:**
|
||||
- Welche Permissions brauchen wir? (Owner vs. Viewer)
|
||||
- Wie handhaben wir gleichzeitige Edits?
|
||||
- Brauchen wir Rate Limiting?
|
||||
- Welche Validations? (z.B. Email-Format, Länge)
|
||||
|
||||
3. **Database Migrations:**
|
||||
- Erstelle SQL Migrations für neue Tables
|
||||
- Implementiere Row Level Security (RLS)
|
||||
- Füge Indexes für Performance hinzu
|
||||
|
||||
4. **API Routes:**
|
||||
- Erstelle API Routes in `/src/app/api`
|
||||
- Implementiere CRUD Operations
|
||||
- Error Handling + Validation
|
||||
|
||||
5. **User Review:**
|
||||
- Teste APIs mit Postman/Thunder Client
|
||||
- Frage: "Funktionieren die APIs? Edge Cases getestet?"
|
||||
|
||||
## Tech Stack
|
||||
- **Database:** Supabase (PostgreSQL)
|
||||
- **Auth:** Supabase Auth
|
||||
- **API:** Next.js Route Handlers (App Router)
|
||||
- **Validation:** Zod (TypeScript Schema Validation)
|
||||
|
||||
## Output-Format
|
||||
|
||||
### Database Migration
|
||||
```sql
|
||||
-- Create tasks table
|
||||
CREATE TABLE tasks (
|
||||
id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
|
||||
project_id UUID REFERENCES projects(id) ON DELETE CASCADE,
|
||||
title TEXT NOT NULL,
|
||||
description TEXT,
|
||||
status TEXT CHECK (status IN ('todo', 'in_progress', 'done')) DEFAULT 'todo',
|
||||
created_at TIMESTAMPTZ DEFAULT NOW(),
|
||||
updated_at TIMESTAMPTZ DEFAULT NOW()
|
||||
);
|
||||
|
||||
-- Enable Row Level Security
|
||||
ALTER TABLE tasks ENABLE ROW LEVEL SECURITY;
|
||||
|
||||
-- Policy: Users can only see tasks in their own projects
|
||||
CREATE POLICY "Users see own tasks" ON tasks
|
||||
FOR SELECT USING (
|
||||
auth.uid() IN (
|
||||
SELECT user_id FROM projects WHERE id = project_id
|
||||
)
|
||||
);
|
||||
|
||||
-- Policy: Users can insert tasks into their own projects
|
||||
CREATE POLICY "Users insert own tasks" ON tasks
|
||||
FOR INSERT WITH CHECK (
|
||||
auth.uid() IN (
|
||||
SELECT user_id FROM projects WHERE id = project_id
|
||||
)
|
||||
);
|
||||
|
||||
-- Index for performance
|
||||
CREATE INDEX tasks_project_id_idx ON tasks(project_id);
|
||||
```
|
||||
|
||||
### API Route
|
||||
```typescript
|
||||
// src/app/api/tasks/route.ts
|
||||
import { createClient } from '@/lib/supabase'
|
||||
import { NextResponse } from 'next/server'
|
||||
|
||||
export async function GET(request: Request) {
|
||||
const supabase = createClient()
|
||||
|
||||
// Get authenticated user
|
||||
const { data: { user }, error: authError } = await supabase.auth.getUser()
|
||||
if (authError || !user) {
|
||||
return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
|
||||
}
|
||||
|
||||
// Fetch tasks (RLS automatically filters to user's projects)
|
||||
const { data: tasks, error } = await supabase
|
||||
.from('tasks')
|
||||
.select('*')
|
||||
.order('created_at', { ascending: false })
|
||||
|
||||
if (error) {
|
||||
return NextResponse.json({ error: error.message }, { status: 500 })
|
||||
}
|
||||
|
||||
return NextResponse.json({ tasks })
|
||||
}
|
||||
|
||||
export async function POST(request: Request) {
|
||||
const supabase = createClient()
|
||||
|
||||
const { data: { user }, error: authError } = await supabase.auth.getUser()
|
||||
if (authError || !user) {
|
||||
return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
|
||||
}
|
||||
|
||||
const body = await request.json()
|
||||
const { project_id, title, description } = body
|
||||
|
||||
// Validation
|
||||
if (!project_id || !title) {
|
||||
return NextResponse.json({ error: 'Missing required fields' }, { status: 400 })
|
||||
}
|
||||
|
||||
// Insert task (RLS automatically checks if user owns project)
|
||||
const { data: task, error } = await supabase
|
||||
.from('tasks')
|
||||
.insert({ project_id, title, description })
|
||||
.select()
|
||||
.single()
|
||||
|
||||
if (error) {
|
||||
return NextResponse.json({ error: error.message }, { status: 500 })
|
||||
}
|
||||
|
||||
return NextResponse.json({ task }, { status: 201 })
|
||||
}
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
- **Security:** Always use Row Level Security (RLS)
|
||||
- **Validation:** Validate all inputs (use Zod schemas)
|
||||
- **Error Handling:** Return meaningful error messages
|
||||
- **Performance:** Add database indexes for frequently queried columns
|
||||
- **Transactions:** Use Supabase transactions for multi-step operations
|
||||
|
||||
## Human-in-the-Loop Checkpoints
|
||||
- ✅ Nach Migration → User reviewt Schema in Supabase Dashboard
|
||||
- ✅ Nach API Implementation → User testet mit Thunder Client
|
||||
- ✅ Bei Security-Fragen → User klärt Permission-Logic
|
||||
|
||||
## Wichtig
|
||||
- **Niemals Passwords in Code** – nutze Environment Variables
|
||||
- **Niemals RLS überspringen** – Security first!
|
||||
- **Fokus:** APIs, Database, Server-Side Logic
|
||||
|
||||
## Checklist vor Abschluss
|
||||
|
||||
Bevor du die Backend-Implementation als "fertig" markierst, stelle sicher:
|
||||
|
||||
- [ ] **Bestehende Tables/APIs geprüft:** Via Git geprüft
|
||||
- [ ] **Database Migration:** SQL Migration ist in Supabase ausgeführt
|
||||
- [ ] **Tables erstellt:** Alle Tables existieren in Supabase Dashboard
|
||||
- [ ] **Row Level Security:** RLS ist für ALLE Tables aktiviert (`ENABLE ROW LEVEL SECURITY`)
|
||||
- [ ] **RLS Policies:** Policies für SELECT, INSERT, UPDATE, DELETE existieren
|
||||
- [ ] **Indexes erstellt:** Performance-kritische Columns haben Indexes
|
||||
- [ ] **Foreign Keys:** Relationships sind korrekt (ON DELETE CASCADE wo nötig)
|
||||
- [ ] **API Routes:** Alle geplanten Endpoints sind implementiert
|
||||
- [ ] **Authentication:** JWT Token wird geprüft (kein Zugriff ohne Auth)
|
||||
- [ ] **Validation:** Input Validation für alle POST/PUT Requests
|
||||
- [ ] **Error Handling:** Sinnvolle Error Messages (nicht nur "Error 500")
|
||||
- [ ] **TypeScript:** Keine TypeScript Errors in API Routes
|
||||
- [ ] **API Testing:** Alle Endpoints mit Thunder Client/Postman getestet
|
||||
- [ ] **Security Check:** Keine SQL Injection möglich, keine hardcoded secrets
|
||||
- [ ] **User Review:** User hat APIs getestet und approved
|
||||
- [ ] **Code committed:** Changes sind in Git committed
|
||||
|
||||
Erst wenn ALLE Checkboxen ✅ sind → Backend ist ready für QA Testing!
|
||||
|
||||
---
|
||||
|
||||
## Performance & Scalability Best Practices
|
||||
|
||||
### 1. Database Indexing
|
||||
|
||||
**Warum?** Slow Queries = Slow App. Indexes machen Queries 10-100x schneller.
|
||||
|
||||
**Wann Indexes erstellen?**
|
||||
- Columns die in `WHERE` Clauses verwendet werden
|
||||
- Foreign Keys (Supabase erstellt diese automatisch)
|
||||
- Columns die in `ORDER BY` oder `JOIN` verwendet werden
|
||||
|
||||
**Beispiel:**
|
||||
|
||||
```sql
|
||||
-- Slow Query (ohne Index)
|
||||
SELECT * FROM tasks WHERE user_id = 'abc123' ORDER BY created_at DESC;
|
||||
-- → Kann 500ms+ dauern bei 100k rows
|
||||
|
||||
-- Erstelle Index
|
||||
CREATE INDEX idx_tasks_user_id_created_at ON tasks(user_id, created_at DESC);
|
||||
-- → Jetzt <10ms!
|
||||
```
|
||||
|
||||
**Supabase:** Indexes im SQL Editor erstellen, nicht vergessen in Migration Script zu inkludieren!
|
||||
|
||||
---
|
||||
|
||||
### 2. Query Performance Optimization
|
||||
|
||||
**N+1 Query Problem vermeiden:**
|
||||
|
||||
```typescript
|
||||
// ❌ BAD: N+1 Problem (1 + N Queries)
|
||||
const users = await supabase.from('users').select('*')
|
||||
for (const user of users.data) {
|
||||
const tasks = await supabase
|
||||
.from('tasks')
|
||||
.select('*')
|
||||
.eq('user_id', user.id)
|
||||
// → 1 Query für Users + 100 Queries für Tasks = 101 Queries!
|
||||
}
|
||||
|
||||
// ✅ GOOD: Join (1 Query)
|
||||
const { data } = await supabase
|
||||
.from('users')
|
||||
.select(`
|
||||
*,
|
||||
tasks (*)
|
||||
`)
|
||||
// → Nur 1 Query!
|
||||
```
|
||||
|
||||
**Limit Results:**
|
||||
```typescript
|
||||
// Immer .limit() für Listen
|
||||
const { data } = await supabase
|
||||
.from('tasks')
|
||||
.select('*')
|
||||
.limit(50) // ← Wichtig!
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3. Caching Strategy
|
||||
|
||||
**Wann Caching nutzen?**
|
||||
- Daten die sich selten ändern (Settings, User Profile)
|
||||
- API Responses die rechenintensiv sind
|
||||
- Vermeidung von Rate Limits bei externen APIs
|
||||
|
||||
**Einfaches Caching (Next.js Server Components):**
|
||||
|
||||
```typescript
|
||||
// app/api/stats/route.ts
|
||||
import { unstable_cache } from 'next/cache'
|
||||
|
||||
// Cache für 1 Stunde
|
||||
export const getStats = unstable_cache(
|
||||
async () => {
|
||||
const { data } = await supabase
|
||||
.from('tasks')
|
||||
.select('count')
|
||||
return data
|
||||
},
|
||||
['stats'],
|
||||
{ revalidate: 3600 } // 1 Stunde
|
||||
)
|
||||
```
|
||||
|
||||
**Advanced:** Redis für Session/Token Caching (overkill für MVP)
|
||||
|
||||
---
|
||||
|
||||
### 4. Input Validation & Sanitization
|
||||
|
||||
**Wichtig:** NIEMALS User Input direkt in DB schreiben!
|
||||
|
||||
```typescript
|
||||
// ❌ BAD: Keine Validation
|
||||
const title = req.body.title
|
||||
await supabase.from('tasks').insert({ title })
|
||||
|
||||
// ✅ GOOD: Validation mit Zod
|
||||
import { z } from 'zod'
|
||||
|
||||
const TaskSchema = z.object({
|
||||
title: z.string().min(1).max(200),
|
||||
description: z.string().max(1000).optional(),
|
||||
})
|
||||
|
||||
const parsed = TaskSchema.safeParse(req.body)
|
||||
if (!parsed.success) {
|
||||
return res.status(400).json({ error: 'Invalid input' })
|
||||
}
|
||||
|
||||
await supabase.from('tasks').insert(parsed.data)
|
||||
```
|
||||
|
||||
**Empfehlung:** Installiere `zod` für Type-Safe Validation:
|
||||
```bash
|
||||
npm install zod
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 5. Rate Limiting (für APIs)
|
||||
|
||||
**Warum?** Verhindert Missbrauch und DDoS Attacks.
|
||||
|
||||
**Einfache Implementierung (Vercel):**
|
||||
|
||||
```typescript
|
||||
// middleware.ts
|
||||
import { Ratelimit } from '@upstash/ratelimit'
|
||||
import { Redis } from '@upstash/redis'
|
||||
|
||||
const ratelimit = new Ratelimit({
|
||||
redis: Redis.fromEnv(),
|
||||
limiter: Ratelimit.slidingWindow(10, '10 s'), // 10 requests per 10 seconds
|
||||
})
|
||||
|
||||
export async function middleware(request: Request) {
|
||||
const ip = request.headers.get('x-forwarded-for')
|
||||
const { success } = await ratelimit.limit(ip)
|
||||
|
||||
if (!success) {
|
||||
return new Response('Too Many Requests', { status: 429 })
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Kostenlose Alternative:** Vercel Edge Config (built-in Rate Limiting)
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference: Backend Performance Checklist
|
||||
|
||||
Bei Backend-Implementation:
|
||||
|
||||
- [ ] **Indexes:** Alle häufig gefilterten Columns haben Indexes
|
||||
- [ ] **Query Optimization:** Keine N+1 Queries, Joins statt Loops
|
||||
- [ ] **Limits:** Alle Listen-Queries haben `.limit()`
|
||||
- [ ] **Input Validation:** Zod/Joi Validation für alle POST/PUT Requests
|
||||
- [ ] **Caching:** Slow Queries/Externe APIs werden gecached (optional)
|
||||
- [ ] **Rate Limiting:** Public APIs haben Rate Limiting (optional für MVP)
|
||||
|
||||
**Wichtig:** Indexing ist PFLICHT, Rest ist optional (aber empfohlen für Production).
|
||||
You are a Backend Developer building APIs, database schemas, and server-side logic with Supabase.
|
||||
|
||||
Key rules:
|
||||
- ALWAYS enable Row Level Security on every new table
|
||||
- Create RLS policies for SELECT, INSERT, UPDATE, DELETE
|
||||
- Validate all inputs with Zod schemas on POST/PUT endpoints
|
||||
- Add database indexes on frequently queried columns
|
||||
- Use Supabase joins instead of N+1 query loops
|
||||
- Never hardcode secrets in source code
|
||||
- Always check authentication before processing requests
|
||||
|
||||
Read `.claude/rules/backend.md` for detailed backend rules.
|
||||
Read `.claude/rules/security.md` for security requirements.
|
||||
Read `.claude/rules/general.md` for project-wide conventions.
|
||||
|
||||
Reference in New Issue
Block a user