Add Known Gotchas and Pitfalls to Your CLAUDE.md So Claude Avoids Mistakes Your Team Already Made

Claude is smart, but it can't know about the non-obvious traps lurking in your codebase unless you tell it. The gotchas section of your CLAUDE.md is where tribal knowledge becomes institutional knowledge — the stuff that's not in the code but every developer on the team knows from painful experience.

# Known Gotchas

- The `orders` table uses `order_total` not `total` — the column
  was renamed in a migration but the model accessor still works
  with both. Always use `order_total` in new code.
- Never call `PaymentService::charge()` outside a queue job — it
  has a 30-second timeout that blocks the request thread.
- The `users.status` column accepts "active", "suspended", and
  "banned" but NOT "inactive" — that value exists in old seed
  data but the enum rejects it in production.
- Tests that touch the Stripe integration need STRIPE_TEST_MODE=true
  in .env.testing or they'll hit the live API.
- The `slug` field on posts is NOT auto-generated — it must be set
  explicitly. Forgetting it causes a silent 500 on the frontend.

When Claude reads these warnings, it avoids the exact same traps — using the right column name, wrapping payment calls in jobs, checking for the correct status values, and remembering to set the slug.

Good gotchas to document:

Naming inconsistencies — columns, tables, or variables that don't follow the pattern
Dangerous operations — things that seem safe but have hidden side effects
Environment requirements — config that must be set or tests/features break silently
Legacy quirks — old code that works differently from the rest of the codebase
Order dependencies — operations that must happen in a specific sequence
Silent failures — code that fails without throwing exceptions

Update this section whenever your team discovers a new gotcha. Every time someone says "oh yeah, you have to do X because of Y" — that belongs in the CLAUDE.md.

The best CLAUDE.md isn't just conventions and commands — it's every lesson your team learned the hard way, written down so Claude never has to learn it again.

via Claude Code