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”
@@ -0,0 +1,91 @@
|
||||
# Database Optimization
|
||||
|
||||
## 1. Indexing
|
||||
|
||||
Create indexes on columns used in WHERE, ORDER BY, or JOIN clauses:
|
||||
|
||||
```sql
|
||||
-- Without index: ~500ms at 100k rows
|
||||
SELECT * FROM tasks WHERE user_id = 'abc123' ORDER BY created_at DESC;
|
||||
|
||||
-- After creating index: <10ms
|
||||
CREATE INDEX idx_tasks_user_id_created ON tasks(user_id, created_at DESC);
|
||||
```
|
||||
|
||||
**Rule of thumb:** If a column appears in WHERE or ORDER BY and the table will have >1000 rows, add an index.
|
||||
|
||||
Always include indexes in your migration SQL alongside CREATE TABLE.
|
||||
|
||||
## 2. Avoid N+1 Queries
|
||||
|
||||
The most common performance problem with ORMs and query builders:
|
||||
|
||||
```typescript
|
||||
// Bad: N+1 (1 query for users + N queries for tasks)
|
||||
const { data: users } = await supabase.from('users').select('*')
|
||||
for (const user of users) {
|
||||
const { data: tasks } = await supabase
|
||||
.from('tasks')
|
||||
.select('*')
|
||||
.eq('user_id', user.id)
|
||||
}
|
||||
|
||||
// Good: Single query with join (1 query total)
|
||||
const { data } = await supabase
|
||||
.from('users')
|
||||
.select('*, tasks(*)')
|
||||
```
|
||||
|
||||
## 3. Always Limit Results
|
||||
|
||||
Never return unbounded results from the database:
|
||||
|
||||
```typescript
|
||||
// Bad: Returns ALL rows
|
||||
const { data } = await supabase.from('tasks').select('*')
|
||||
|
||||
// Good: Returns max 50 rows
|
||||
const { data } = await supabase.from('tasks').select('*').limit(50)
|
||||
|
||||
// Better: Paginated
|
||||
const { data } = await supabase
|
||||
.from('tasks')
|
||||
.select('*')
|
||||
.range(0, 49) // First 50 rows
|
||||
```
|
||||
|
||||
## 4. Caching Strategy
|
||||
|
||||
For data that changes rarely (dashboard stats, config, categories):
|
||||
|
||||
```typescript
|
||||
import { unstable_cache } from 'next/cache'
|
||||
|
||||
export const getCategories = unstable_cache(
|
||||
async () => {
|
||||
const { data } = await supabase.from('categories').select('*')
|
||||
return data
|
||||
},
|
||||
['categories'], // Cache key
|
||||
{ revalidate: 3600 } // Refresh every hour
|
||||
)
|
||||
```
|
||||
|
||||
**When to cache:**
|
||||
- Data that changes less than once per hour
|
||||
- Expensive aggregation queries
|
||||
- Data shared across all users (not user-specific)
|
||||
|
||||
**When NOT to cache:**
|
||||
- User-specific data that changes frequently
|
||||
- Real-time data (use Supabase Realtime instead)
|
||||
|
||||
## 5. Select Only What You Need
|
||||
|
||||
```typescript
|
||||
// Bad: Fetches all columns
|
||||
const { data } = await supabase.from('users').select('*')
|
||||
|
||||
// Good: Fetches only needed columns
|
||||
const { data } = await supabase.from('users').select('id, name, avatar_url')
|
||||
```
|
||||
@@ -0,0 +1,43 @@
|
||||
# Error Tracking Setup (Sentry)
|
||||
|
||||
Track production errors automatically so you know about issues before your users report them.
|
||||
|
||||
## Setup (5 minutes)
|
||||
|
||||
### 1. Create Sentry Account
|
||||
- Go to [sentry.io](https://sentry.io) (free tier available for small apps)
|
||||
- Create a new project and select "Next.js"
|
||||
|
||||
### 2. Install Next.js Integration
|
||||
```bash
|
||||
npx @sentry/wizard@latest -i nextjs
|
||||
```
|
||||
This automatically:
|
||||
- Installs `@sentry/nextjs`
|
||||
- Creates `sentry.client.config.ts` and `sentry.server.config.ts`
|
||||
- Updates `next.config.ts` with Sentry webpack plugin
|
||||
|
||||
### 3. Add Environment Variables
|
||||
Add to `.env.local` (local) and Vercel Dashboard (production):
|
||||
```bash
|
||||
SENTRY_DSN=https://xxx@xxx.ingest.sentry.io/xxx
|
||||
NEXT_PUBLIC_SENTRY_DSN=https://xxx@xxx.ingest.sentry.io/xxx
|
||||
SENTRY_AUTH_TOKEN=sntrys_xxx # For source maps upload
|
||||
```
|
||||
|
||||
### 4. Verify Setup
|
||||
Trigger a test error and check Sentry Dashboard:
|
||||
```typescript
|
||||
// Temporary test - remove after verification
|
||||
throw new Error("Sentry test error")
|
||||
```
|
||||
|
||||
## What You Get
|
||||
- Automatic error capture (client + server)
|
||||
- Stack traces with source maps
|
||||
- Error grouping and deduplication
|
||||
- Email alerts for new errors
|
||||
- Performance monitoring (optional)
|
||||
|
||||
## Alternative
|
||||
**Vercel Error Tracking** - Built-in, simpler, but fewer features. Available in Vercel Dashboard under "Monitoring".
|
||||
@@ -0,0 +1,67 @@
|
||||
# Performance Monitoring
|
||||
|
||||
## Lighthouse Check (after every deployment)
|
||||
|
||||
1. Open Chrome DevTools (F12)
|
||||
2. Go to Lighthouse tab
|
||||
3. Select: Performance, Accessibility, Best Practices, SEO
|
||||
4. Generate Report for both Mobile and Desktop
|
||||
5. **Target: Score > 90** in all categories
|
||||
|
||||
## Common Performance Issues
|
||||
|
||||
### Unoptimized Images
|
||||
```tsx
|
||||
// Bad - unoptimized, no lazy loading
|
||||
<img src="/large-image.jpg" />
|
||||
|
||||
// Good - Next.js Image component
|
||||
import Image from 'next/image'
|
||||
<Image src="/large-image.jpg" width={800} height={600} alt="Description" />
|
||||
```
|
||||
Next.js Image automatically: resizes, lazy-loads, serves WebP format.
|
||||
|
||||
### Large JavaScript Bundle
|
||||
Use dynamic imports for heavy components that aren't needed on initial load:
|
||||
```tsx
|
||||
import dynamic from 'next/dynamic'
|
||||
|
||||
const HeavyChart = dynamic(() => import('./HeavyChart'), {
|
||||
loading: () => <p>Loading chart...</p>,
|
||||
})
|
||||
```
|
||||
|
||||
### Missing Loading States
|
||||
Always show feedback during data fetching:
|
||||
```tsx
|
||||
// Use shadcn Skeleton component
|
||||
import { Skeleton } from "@/components/ui/skeleton"
|
||||
|
||||
if (isLoading) return <Skeleton className="h-12 w-full" />
|
||||
```
|
||||
|
||||
### No Caching Strategy
|
||||
Cache slow database queries with `unstable_cache`:
|
||||
```typescript
|
||||
import { unstable_cache } from 'next/cache'
|
||||
|
||||
export const getStats = unstable_cache(
|
||||
async () => {
|
||||
const { data } = await supabase.from('stats').select('*')
|
||||
return data
|
||||
},
|
||||
['dashboard-stats'],
|
||||
{ revalidate: 3600 } // Refresh every hour
|
||||
)
|
||||
```
|
||||
|
||||
## Quick Wins Checklist
|
||||
- [ ] All images use `next/image` component
|
||||
- [ ] Heavy components use dynamic imports
|
||||
- [ ] Loading states show skeleton/spinner
|
||||
- [ ] Fonts loaded with `next/font`
|
||||
- [ ] No unnecessary client-side JavaScript (`"use client"` only when needed)
|
||||
|
||||
## Automated Monitoring
|
||||
- **Vercel Analytics** - Automatic on Pro plan, shows Core Web Vitals
|
||||
- **Vercel Speed Insights** - Real user performance data
|
||||
@@ -0,0 +1,101 @@
|
||||
# Rate Limiting
|
||||
|
||||
Prevent abuse, DDoS attacks, and excessive API usage.
|
||||
|
||||
## When to Add Rate Limiting
|
||||
- **MVP:** Optional (focus on features first)
|
||||
- **Production with users:** Recommended on auth endpoints and public APIs
|
||||
- **Public-facing APIs:** Required
|
||||
|
||||
## Setup with Upstash Redis
|
||||
|
||||
### 1. Install Dependencies
|
||||
```bash
|
||||
npm install @upstash/ratelimit @upstash/redis
|
||||
```
|
||||
|
||||
### 2. Create Upstash Account
|
||||
- Go to [upstash.com](https://upstash.com) (free tier: 10k requests/day)
|
||||
- Create a Redis database
|
||||
- Copy REST URL and token
|
||||
|
||||
### 3. Add Environment Variables
|
||||
```bash
|
||||
# .env.local
|
||||
UPSTASH_REDIS_REST_URL=https://xxx.upstash.io
|
||||
UPSTASH_REDIS_REST_TOKEN=xxx
|
||||
```
|
||||
|
||||
### 4. Create Rate Limiter
|
||||
```typescript
|
||||
// src/lib/rate-limit.ts
|
||||
import { Ratelimit } from '@upstash/ratelimit'
|
||||
import { Redis } from '@upstash/redis'
|
||||
|
||||
export const ratelimit = new Ratelimit({
|
||||
redis: Redis.fromEnv(),
|
||||
limiter: Ratelimit.slidingWindow(10, '10 s'), // 10 requests per 10 seconds
|
||||
})
|
||||
```
|
||||
|
||||
### 5. Use in API Routes
|
||||
```typescript
|
||||
// src/app/api/example/route.ts
|
||||
import { ratelimit } from '@/lib/rate-limit'
|
||||
import { NextRequest, NextResponse } from 'next/server'
|
||||
|
||||
export async function POST(request: NextRequest) {
|
||||
const ip = request.headers.get('x-forwarded-for') ?? 'anonymous'
|
||||
const { success, limit, remaining } = await ratelimit.limit(ip)
|
||||
|
||||
if (!success) {
|
||||
return NextResponse.json(
|
||||
{ error: 'Too many requests' },
|
||||
{
|
||||
status: 429,
|
||||
headers: {
|
||||
'X-RateLimit-Limit': limit.toString(),
|
||||
'X-RateLimit-Remaining': remaining.toString(),
|
||||
},
|
||||
}
|
||||
)
|
||||
}
|
||||
|
||||
// Process request normally...
|
||||
}
|
||||
```
|
||||
|
||||
### 6. Use in Middleware (Global)
|
||||
```typescript
|
||||
// middleware.ts
|
||||
import { ratelimit } from '@/lib/rate-limit'
|
||||
import { NextRequest, NextResponse } from 'next/server'
|
||||
|
||||
export async function middleware(request: NextRequest) {
|
||||
// Only rate limit API routes
|
||||
if (request.nextUrl.pathname.startsWith('/api/')) {
|
||||
const ip = request.headers.get('x-forwarded-for') ?? 'anonymous'
|
||||
const { success } = await ratelimit.limit(ip)
|
||||
|
||||
if (!success) {
|
||||
return NextResponse.json({ error: 'Too Many Requests' }, { status: 429 })
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
export const config = {
|
||||
matcher: '/api/:path*',
|
||||
}
|
||||
```
|
||||
|
||||
## Recommended Limits
|
||||
|
||||
| Endpoint Type | Limit | Window |
|
||||
|--------------|-------|--------|
|
||||
| Login/Register | 5 requests | 1 minute |
|
||||
| Password Reset | 3 requests | 5 minutes |
|
||||
| General API | 30 requests | 10 seconds |
|
||||
| File Upload | 5 requests | 1 minute |
|
||||
|
||||
## Alternative
|
||||
**Vercel Edge Config** - Simpler but less flexible. Built into Vercel, no external service needed.
|
||||
@@ -0,0 +1,64 @@
|
||||
# Security Headers Configuration
|
||||
|
||||
Protect against XSS, Clickjacking, MIME sniffing, and other common web attacks.
|
||||
|
||||
## Setup
|
||||
|
||||
Add security headers to `next.config.ts`:
|
||||
|
||||
```typescript
|
||||
import type { NextConfig } from 'next'
|
||||
|
||||
const nextConfig: NextConfig = {
|
||||
async headers() {
|
||||
return [
|
||||
{
|
||||
source: '/:path*',
|
||||
headers: [
|
||||
{
|
||||
key: 'X-Frame-Options',
|
||||
value: 'DENY',
|
||||
},
|
||||
{
|
||||
key: 'X-Content-Type-Options',
|
||||
value: 'nosniff',
|
||||
},
|
||||
{
|
||||
key: 'Referrer-Policy',
|
||||
value: 'origin-when-cross-origin',
|
||||
},
|
||||
{
|
||||
key: 'Strict-Transport-Security',
|
||||
value: 'max-age=31536000; includeSubDomains',
|
||||
},
|
||||
],
|
||||
},
|
||||
]
|
||||
},
|
||||
}
|
||||
|
||||
export default nextConfig
|
||||
```
|
||||
|
||||
## What Each Header Does
|
||||
|
||||
| Header | Protection |
|
||||
|--------|-----------|
|
||||
| X-Frame-Options: DENY | Prevents your site from being embedded in iframes (clickjacking) |
|
||||
| X-Content-Type-Options: nosniff | Prevents browsers from guessing content types (MIME sniffing) |
|
||||
| Referrer-Policy | Controls how much URL info is sent to other sites |
|
||||
| Strict-Transport-Security | Forces HTTPS connections |
|
||||
|
||||
## Verify After Deployment
|
||||
1. Open Chrome DevTools
|
||||
2. Go to Network tab
|
||||
3. Click on any request to your site
|
||||
4. Check Response Headers section
|
||||
5. Verify all 4 headers are present
|
||||
|
||||
## Advanced (Optional)
|
||||
**Content-Security-Policy (CSP)** - The most powerful header, but can break your app if misconfigured. Only add after thorough testing:
|
||||
```
|
||||
Content-Security-Policy: default-src 'self'; script-src 'self' 'unsafe-inline'
|
||||
```
|
||||
Start with report-only mode first: `Content-Security-Policy-Report-Only`
|
||||
Reference in New Issue
Block a user