# Performance

> Skill — Performance Engineering

- Skill: `sairam0424/performance` (Agent Skill)
- Install (CLI): `npx skillmds@latest add sairam0424/performance`
- Raw SKILL.md: https://api.skillmd.com/api/skills/sairam0424/performance/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: sairam0424 (https://skillmd.com/u/sairam0424)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/sairam0424/performance

---


# Skill — Performance Engineering

## When this skill activates
Any task involving response time, resource usage, bundle size, database query
performance, or user-perceived load time metrics.

## Mandatory actions when this skill is active

### Before writing any code
1. Identify what is being measured. Never optimise without a baseline.
2. Read the relevant metric from REQUIREMENTS.md (NFRs):
   - API response time target (e.g., p95 < 200ms)
   - Page load time target (e.g., LCP < 2.5s)
   - Bundle size budget (e.g., < 200KB gzipped initial JS)
3. If no NFR is defined: ask the user to define one before optimising.
   "Optimisation without a target is premature optimisation."

### Backend performance standards

**Database queries:**
- Every query must use indexes for its WHERE, JOIN, and ORDER BY columns
- Detect N+1 queries: if fetching a list then querying per item, use JOIN or batch fetch
- Pagination: always paginate list endpoints (default page size: 20, max: 100)
- Avoid `SELECT *` — select only the columns needed
- Use `EXPLAIN ANALYZE` (PostgreSQL) or `EXPLAIN` (MySQL) to verify query plans
- Cache repeated identical queries: Redis with appropriate TTL

**API response time:**
- Default targets (override with NFRs): p50 < 100ms, p95 < 500ms, p99 < 2000ms for most endpoints
- Slow endpoints (> 500ms): must be async (return immediately, use webhooks or polling)
- Database connection pooling: always use a connection pool (never open/close per request)
- Pool sizing: start with `min=2`, `max=CPU * 2 + 2` per instance, then tune to DB limits and workload
- Serverless: prefer a DB proxy (PgBouncer, RDS Proxy) or driver-level pooling that supports bursty concurrency
- Avoid synchronous I/O in request handlers
- Cache hot DB reads at the query or service layer when data is read-heavy and tolerant of staleness

**Caching strategy:**
Defaults below — tune per data freshness requirements and invalidate on writes.
| Data type | Recommended cache | TTL |
|---|---|---|
| User session data | Redis | 24 hours |
| Computed aggregates | Redis | 1–5 minutes |
| Static reference data | Redis | 1 hour |
| User-specific data | Redis with user key | 15 minutes |
| API responses | HTTP Cache-Control | depends on freshness needs |

### Frontend performance standards

**Bundle size budgets:**
| Asset | Budget (gzipped) |
|---|---|
| Initial JavaScript | < 200KB |
| Initial CSS | < 50KB |
| Per-route chunk | < 100KB |
| Images (hero) | < 200KB WebP |
| Fonts | < 50KB per weight |

**Core Web Vitals targets (Google's thresholds):**
| Metric | Good | Needs improvement | Poor |
|---|---|---|---|
| LCP (Largest Contentful Paint) | < 2.5s | 2.5–4s | > 4s |
| INP (Interaction to Next Paint) | < 200ms | 200–500ms | > 500ms |
| CLS (Cumulative Layout Shift) | < 0.1 | 0.1–0.25 | > 0.25 |

**Implementation patterns:**
- Route-based code splitting: every route is its own chunk
- Lazy load non-critical components: `React.lazy()` + `Suspense`
- Image optimisation: use `next/image` or equivalent. Always specify `width`/`height`.
- Font loading: `font-display: swap`. Preload critical fonts.
- Avoid layout thrashing: batch DOM reads before DOM writes
- Debounce user input handlers (search: 300ms, resize: 100ms)
- Memoize expensive computations: `useMemo` / `useCallback` where measured

**SSR/SSG guidance:**
- Prefer SSG for marketing and content pages with low data volatility
- Prefer SSR for personalized data, but watch TTFB and cache at the edge where possible
- For hybrid apps, stream server components or HTML where supported to reduce TTFB and improve LCP

### Performance measurement commands

```bash
# Backend: measure API response time
curl -w "@curl-format.txt" -o /dev/null -s https://api.example.com/endpoint

# Frontend: Lighthouse CI
npx lighthouse https://example.com --output json --output-path ./lighthouse.json

# Bundle analysis
npx bundle-analyzer stats.json

# Node.js profiling
node --prof app.js
node --prof-process isolate-*.log > profile.txt

# Database: explain query
EXPLAIN ANALYZE SELECT * FROM users WHERE email = 'test@example.com';
```

## Performance review checklist
Before marking any task done that involves a query or endpoint:
- [ ] Query uses appropriate indexes (verified with EXPLAIN)
- [ ] No N+1 queries in list endpoints
- [ ] Response time verified locally (curl with timing)
- [ ] No `SELECT *` in production queries
- [ ] Caching applied where data is read-heavy and tolerance allows staleness

## Output
Write performance notes to SUMMARY.md:
- Baseline metric (before)
- Achieved metric (after)
- What optimisation was applied
- Whether the NFR target was met ✅ or still needs work ⚠️