The CLAUDE.md Guide: Give AI Perfect Context for Your Codebase

There’s one file that separates vibe coders who get mediocre output from vibe coders who get code that feels like it was written by someone who’s been on the team for months.

That file is CLAUDE.md.

What Is CLAUDE.md?

CLAUDE.md is a markdown file at the root of your project that Claude Code reads automatically every time it starts. Think of it as onboarding documentation — except your new hire is an AI agent with perfect memory and the ability to write code at machine speed.

When Claude Code opens your project, the first thing it does is read CLAUDE.md. Everything in that file becomes context for every prompt you give it. Your stack, your conventions, your patterns, your quirks — all front-loaded so you don’t have to repeat yourself.

Without CLAUDE.md, Claude Code is smart but generic. With a good CLAUDE.md, it writes code that looks like your code.

Why It Matters

Every vibe coder has had this experience: you prompt the AI to add a feature, and it works… but it doesn’t match your existing code style. It uses a different state management pattern. It imports from the wrong path. It names things differently than everything else in the project.

CLAUDE.md eliminates this. When Claude Code knows that you use Zustand for state, that your components live in src/components/ui/, that you prefer const over let, and that you always add loading states — it generates code that fits seamlessly.

The difference is dramatic. With CLAUDE.md, “add a user settings page” produces code that uses your auth pattern, your component library, your styling approach, and your file naming convention. Without it, you get generic React code that needs heavy editing.

How to Write a Great CLAUDE.md

The Essential Sections

1. Project Overview (2-3 sentences)

What does this project do? What’s the tech stack? Keep it brief.

## Project
Task management SaaS. Next.js 14 App Router + Supabase + Stripe.
Deployed on Vercel. TypeScript everywhere.

2. Architecture & File Structure

Where things live. This is the most important section because it prevents Claude from creating files in the wrong place or importing from non-existent paths.

## Structure
- app/ — Next.js App Router pages and layouts
- components/ui/ — Reusable UI components (Button, Input, Modal, etc.)
- components/features/ — Feature-specific components (Dashboard, Settings, etc.)
- lib/ — Utilities, API clients, helpers
- lib/supabase.ts — Supabase client (server + browser)
- lib/stripe.ts — Stripe client and helpers
- hooks/ — Custom React hooks
- types/ — TypeScript type definitions

3. Code Conventions

How you write code. Be specific about patterns you care about.

## Conventions
- Use `const` exclusively (no `let` unless mutation required)
- Components: PascalCase, one component per file
- Hooks: `use` prefix, always return typed object
- Server actions: `app/actions/` directory
- Error handling: always use try/catch with typed errors
- Imports: absolute paths via `@/` alias
- Styling: Tailwind utility classes only, no CSS modules
- State: Zustand for global, useState for local

4. Patterns & Examples

Show Claude what “right” looks like in your project. This is the secret weapon.

## Patterns

### API Route Pattern
Every API route follows this structure:
- Validate input with Zod
- Check auth with getServerSession()
- Try/catch with consistent error response
- Return typed JSON response

### Component Pattern
- Props interface defined above component
- Default export
- Loading state handled with Skeleton component
- Error state handled with ErrorBoundary

5. What NOT to Do

Negative constraints are surprisingly powerful. Tell Claude what to avoid.

## Don'ts
- Never use `any` type
- Never use CSS-in-JS or styled-components
- Never import from relative paths (use @/ alias)
- Never create new utility files — add to existing lib/ files
- Never use class components
- Never commit .env files

Advanced Sections

Testing approach:

## Testing
- Jest + React Testing Library
- Test files: `__tests__/[component].test.tsx`
- Minimum: render test + key interaction test
- Mock Supabase client in tests, never hit real DB

Deployment context:

## Deployment
- Push to main auto-deploys via Vercel
- Preview deployments for all PRs
- Env vars in Vercel dashboard (never hardcoded)
- Run `npm run build` before pushing to catch errors

Current priorities (great for ongoing projects):

## Current Focus
- Building: User settings page with profile editing
- Next: Stripe billing portal integration
- Tech debt: Refactor auth middleware (too many edge cases)

Real-World Example

Here’s a complete CLAUDE.md for a SaaS project:

# CLAUDE.md

## Project
JobTracker — Job application tracking SaaS for developers.
Next.js 14 App Router + Supabase + Stripe. TypeScript. Deployed on Vercel.

## Structure
- app/(auth)/ — Auth pages (login, signup, forgot-password)
- app/(dashboard)/ — Protected dashboard pages
- app/api/ — API routes
- app/actions/ — Server actions
- components/ui/ — Shadcn-style reusable components
- components/features/ — Feature components
- lib/supabase/ — Server and browser Supabase clients
- lib/stripe.ts — Stripe helpers
- hooks/ — Custom hooks (useJobs, useUser, useSubscription)
- types/database.ts — Generated Supabase types

## Conventions
- Absolute imports with @/ alias
- Server components by default, "use client" only when needed
- Zod for all validation
- Tailwind for styling, no CSS modules
- Supabase RLS for data access control
- Conventional commits (feat:, fix:, chore:)

## Patterns
- Auth: use getUser() server action, redirect if null
- Data: React Server Components fetch with Supabase, mutations via server actions
- Forms: React Hook Form + Zod resolver
- Loading: Suspense boundaries with Skeleton components

## Don'ts
- No `any` types
- No client-side Supabase writes (always server actions)
- No inline styles
- No new dependencies without justification

## Current Focus
- Building: Analytics dashboard with charts
- Fixing: Email notification timing (sends too early)

Tips That Make a Difference

Keep it under 100 lines. CLAUDE.md is context that gets loaded on every prompt. Too long and you’re wasting context window on boilerplate. Be concise.

Update it as you go. Your project evolves. Your CLAUDE.md should too. When you establish a new pattern or change a convention, update the file. Five seconds of editing saves hours of correcting AI output.

Use the “Current Focus” section. This is underrated. When Claude Code knows what you’re actively working on, its suggestions are more relevant. It won’t randomly refactor things you’re not touching.

Test it. After writing your CLAUDE.md, open a fresh Claude Code session and prompt something like “add a new page for user settings.” If the output matches your conventions without corrections, your CLAUDE.md is working.

One per project, not per workspace. CLAUDE.md should be checked into your repo. It’s documentation for both AI and humans. Future developers (or future you) benefit from it too.

CLAUDE.md vs .cursorrules

If you’re coming from Cursor, CLAUDE.md serves the same purpose as .cursorrules — project-level context for your AI tool. The difference is that CLAUDE.md is specifically designed for Claude Code’s agentic workflow, where the AI doesn’t just suggest code but actively builds, tests, and iterates.

CLAUDE.md tends to be more actionable because Claude Code can actually execute commands, run tests, and modify files. So your instructions can include things like “run npm test after changes” and Claude Code will actually do it.

Start Now

Create a CLAUDE.md in your project right now. Even a 10-line version makes a massive difference. Start with the project overview, file structure, and three conventions you care most about. Iterate from there.

The best vibe coders aren’t the ones who write the best prompts. They’re the ones who set up the best context. CLAUDE.md is how you do that.