Why Your CLAUDE.md Is Wrong (And How to Fix It in 20 Minutes)

I spent three months with a CLAUDE.md that looked great in my editor but was completely useless in production.

It had everything: company values, code style preferences, architectural diagrams in ASCII. Claude would acknowledge it, then do whatever it wanted anyway. My components came back with class names instead of Tailwind. My Supabase queries used deprecated patterns. My API responses had inconsistent structures.

The problem wasn't that Claude wasn't reading the file. The problem was I'd written it like documentation instead of constraints.

What Makes a CLAUDE.md Actually Work

After rebuilding mine three times, I landed on a structure that Claude follows consistently:

1. Start with the stack as immutable facts, not preferences

Bad:

We prefer to use Tailwind for styling.

Good:

Stack (non-negotiable):
- Next.js 14 App Router
- Tailwind 3.x (no custom CSS files)
- Supabase (auth + db)
- TypeScript strict mode

The difference: Claude interprets "prefer" as "suggest if convenient." When you frame the stack as constraints, it treats them like TypeScript types — violations break the build.

2. Define patterns with before/after examples

This was the biggest shift. Instead of explaining why we do things, I show exactly what to do.

Bad:

Use server components when possible for better performance.

Good:

Server vs Client Components:

// ❌ Don't make data-fetching client-side
'use client'
export default function Page() {
  const { data } = useSWR('/api/posts')
}

// ✅ Do this
export default async function Page() {
  const { data } = await supabase.from('posts').select()
}

Claude is excellent at pattern matching. Give it the pattern.

3. Make error handling explicit and boring

I used to write "handle errors appropriately." Claude would return creative try-catch blocks that logged to services I don't use.

Now:

Error handling (always):
- API routes: return { error: string } with appropriate status
- Server components: show error.tsx boundary
- Client components: use error state, show inline message
- Never: console.error in production, generic "something went wrong"

4. Build a "Never Do This" section

This section saved me the most time. Every time Claude does something wrong twice, it goes here:

Never:
- Create new CSS files (Tailwind only)
- Use useEffect for data fetching (server components or SWR)
- Make Supabase calls from client components without RLS
- Add dependencies without checking bundle size
- Use any date library except date-fns

I have 23 items in this list. Each one represents a pattern I had to fix multiple times before documenting it.

The BRICK Test

A good CLAUDE.md passes the BRICK test: can Claude generate a deployable component from a two-sentence prompt?

Before I fixed mine:

Prompt: "Create a post card component"
Result: 20 minutes of back-and-forth fixing imports, styling, TypeScript errors

After:

Prompt: "Create a post card component"
Result: Working component, correct patterns, deploys immediately

That's the difference between GRAVEL (fixing the same issues every day) and POUR (consistent forward momentum).

How I Structure Mine Now

# BuildNotBurn Development Guide

## Stack (non-negotiable)
[List exact versions and rules]

## File Structure
[Actual directory tree of the project]

## Patterns (with examples)
[Before/after code blocks for every common task]

## Database
[Supabase schema, RLS rules, query patterns]

## API Routes
[Request/response format, auth pattern, error handling]

## Never Do This
[The list of things Claude keeps trying to do wrong]

## Current Work
[Update this daily with what you're building]

The "Current Work" section is key. I update it every morning. It tells Claude what context matters right now, so it doesn't generate components for features I shipped last week.

The 20-Minute Fix

1. Open your CLAUDE.md
2. Delete everything that sounds like documentation
3. Add your stack as a bulleted list
4. Find the last 5 things Claude did wrong — add them to "Never"
5. Pick your most common task (for me: new API route). Write the exact pattern with a code example.
6. Save it

That's it. You don't need comprehensive coverage. You need the 20% that fixes 80% of your back-and-forth.

Mine is 200 lines. I add to it when Claude makes me fix something twice. It's not a design document. It's a constraint system.

And now when I prompt "create a settings page," I get a settings page that works. No GRAVEL. Just BRICK.