The CLAUDE.md mistake 90% of Claude Code users make (and how to fix it)

If you're using Claude Code and your CLAUDE.md looks like this:

Use TypeScript. Write clean code. Follow best practices.

Claude is ignoring it. Here's why — and what to write instead.

The problem with generic rules

Claude doesn't respond to vague instructions. "Write clean code" means nothing to an LLM. It has no way to evaluate whether code is "clean" in your specific context.

What Claude actually follows: specific, verifiable rules that leave no room for interpretation.

What a good CLAUDE.md actually looks like

Generic (ignored):

Handle errors properly

Specific (followed):

Error handling:
- Always fmt.Errorf("context: %w", err) — never return raw errors
- Log once at the top of the call stack, never re-log when wrapping
- Domain errors in internal/domain/ as sentinel errors

The second one is checkable. Claude can verify compliance. The first is subjective noise.

The 3 categories that matter most

1. Architecture rules (where things go)

## Architecture
- api/endpoints/: HTTP parsing + calling services only
- services/: All business logic — no HTTP concerns
- repository/: All DB queries — none in handlers or services

2. Critical anti-patterns (what never to do)

## Never do this
- Never expose Supabase service key to client components
- Never sync Stripe state from client — webhooks only
- Never put auth checks inside page components — use middleware.ts

3. Stack-specific gotchas

## Stripe webhooks
- Always verify webhook signature with stripe.webhooks.constructEvent()
- Make handlers idempotent — check if event already processed
- Store webhook events in DB before processing