Most developers write a CLAUDE.md, get slightly better output for a week, then forget about it.
The reason: their CLAUDE.md doesn't change Claude's behavior — it just reminds Claude of things it would have done anyway.
Here's how to write one that actually works.
What Claude does with your CLAUDE.md
Claude reads the entire file before starting any task in your project. It uses it to:
- Understand your architecture (so it puts code in the right place)
- Follow your conventions (so you don't have to correct it)
- Avoid your known anti-patterns (so you don't get burned by the same mistake twice)
The key word is specific. Claude responds to specifics, not generalities.
The structure that works
Here's a template that covers the essentials:
# Project: [Name]
## Stack
[List your actual stack — framework, database, auth, key libraries]
## Architecture
[Folder structure + what goes where. Be explicit.]
- `src/services/` — business logic only
- `src/routes/` — HTTP layer only, calls services
- `src/db/` — all database queries
## Critical Rules
[The 5-10 things Claude must never get wrong]
- Never expose [X] to the client
- Always validate [Y] before [Z]
- Auth happens in [specific place], nowhere else
## Code Conventions
[Language-specific patterns you actually use]
## Error Handling
[How errors should be handled, logged, returned]
## Testing
[What to test, how to test it, what not to mock]
## Environment Variables
[List every env var and what it does]
The rule of thumb: if Claude got it wrong once, write a rule
Every time Claude makes a mistake that surprises you, add a rule to your CLAUDE.md.
- Claude put business logic in a route handler? → Add an architecture rule
- Claude used the wrong auth pattern? → Add a critical rule
- Claude wrote a test that mocked the database? → Add a testing convention
Over time, your CLAUDE.md becomes a record of the project's institutional knowledge.
Stack-specific sections worth adding
For Next.js App Router
## Next.js Rules
- Server Components by default — "use client" only for event handlers and hooks
- Never useEffect for data fetching — use Server Components or React Query
- Auth: middleware.ts handles route protection — never in page components
- Stripe: sync subscription state via webhooks only — never trust client data
For FastAPI
## FastAPI Rules
- Routers: HTTP parsing + service calls only — no business logic
- Services: business logic only — no HTTP or DB concerns
- Repository: all DB queries — never in routers or services
- Always use Pydantic v2 validators — never raw dict access
For any AI agent project
## Agent Rules
- Max iterations on all agent loops: 10
- 30s timeout per tool execution
- Human-in-the-loop for: file deletion, email sending, payments
- Never pass LLM output directly to SQL or shell
- Log every LLM call: input, output, tokens, latency
How long should it be?
Long enough to cover your real conventions — short enough that every rule earns its place.
A 50-line CLAUDE.md with 10 specific, enforced rules beats a 500-line one where Claude picks and chooses what to follow.
Start lean. Add rules when Claude makes mistakes. After 2-3 projects, you'll have something worth copying to your next project.
Skip the blank page
If you'd rather not start from scratch, I packaged 25 production-ready CLAUDE.md files — one per stack.
Each covers the architecture, conventions, anti-patterns, env vars, and testing patterns for its framework.
→ CLAUDE.md Starter Pack ($47) — 5 stars, used daily by developers.
Free excerpts for Next.js SaaS, FastAPI, and AI agents: GitHub.
Top comments (0)