Gotchas & tips
Hard-won lessons. The “if only I’d known this earlier” notes. Organized by tool or area. Every gotcha here is something that has cost me (or someone I trust) real time, or something documented as a common trap.
Planned collections
| File | Status | Covers |
|---|---|---|
| Next.js gotchas | 🟥 STUB | App Router quirks, hydration mismatches, the 'use client' rules |
| Supabase gotchas | 🟥 STUB | RLS bypass via service_role, session vs JWT confusion, region pinning |
| Vercel gotchas | 🟥 STUB | Build cache surprises, env var scoping, function regions |
| Git gotchas | 🟥 STUB | Line endings on Windows, force-push hazards, .gitignore misses |
| Auth gotchas | 🟥 STUB | Session cookies + SameSite, JWT expiry, magic-link replay |
| Tailwind gotchas | 🟥 STUB | Purge surprises, dark mode order, space-x-* vs gap-* |
| Windows dev gotchas | 🟥 STUB | CRLF vs LF, PowerShell vs Bash, file path escaping |
| Claude Code gotchas | 🟥 STUB | Permissions confusion, hooks misfiring, MEMORY.md scaling |
| LLM API gotchas | 🟥 STUB | Context limits, tool-use vs JSON-mode, streaming edge cases |
| Deployment gotchas — general | 🟥 STUB | ”Works on my machine” — env, time zones, file paths |
Conventions for gotcha entries
### {Short description of the trap}
**Symptom:** {What you see when it bites}
**Why it happens:** {Root cause in 1-3 sentences}
**Fix:** {The actual remedy}
**Prevention:** {How to avoid it next time}Keep gotchas tight — readers come here under stress. A page of gotchas should feel like a quick scan, not a deep read.