DEV Community

Christopher Hoeben
Christopher Hoeben

Posted on • Originally published at stickwithfiddle-sys.github.io

How to Set Up a CLAUDE.md File for Claude Code: A Step-by-Step Guide

#claudecode #claudemd #aidevelopment #vibecoding

How to Set Up a CLAUDE.md File for Claude Code: A Step-by-Step Guide

Learn to create a CLAUDE.md file that gives Claude Code persistent project context. We cover the init command, the five-question framework, structuring sections, keeping it under 200 lines, and testing your file for maximum effectiveness.

TL;DR: Run claude init to generate a draft CLAUDE.md in your project root. Then refine it using the five-question framework (Who, What, Where, Why, How) to define your role, project, structure, decisions, and commands. Keep the file under 200 lines and split large contexts into a CLAUDE.md directory. This file acts as a system prompt, read at the start of every session, ensuring consistent AI behavior.

What is CLAUDE.md and Why It Matters

CLAUDE.md is a Markdown file placed in your project's root directory that acts as a persistent system prompt for Claude Code, giving it project-specific context at the start of every session. Without it, Claude begins each interaction from scratch, relying on generic assumptions that often miss your actual conventions, architecture, and preferences.

When Claude Code opens a project, it reads this file first. The file's Markdown structure lets you define everything from the tech stack and folder layout to coding style rules, testing commands, and key architectural decisions. This upfront context prevents Claude from making reasonable but incorrect guesses about your codebase, saving you from repeatedly correcting the same mistakes across sessions.

You don't have to write the file manually. Running the following command in your project root will scan your codebase and generate an initial draft:

claude init
Enter fullscreen mode Exit fullscreen mode

This auto-generated file includes detected project structure, dependencies, and conventions. However, treat it as a first draft only — it often misses important details like your preferred testing framework, naming patterns, or the why behind architectural choices. A well-maintained CLAUDE.md ensures Claude consistently follows your project's specific rules, reducing friction and making the AI a more reliable collaborator from the very first prompt.

Step 1: Generate a Draft with claude init

Run claude init from your project root to generate a first draft of your CLAUDE.md automatically. Claude scans your entire codebase and populates the file with project architecture, conventions, and other essential details.

cd /path/to/your/project
claude init
Enter fullscreen mode Exit fullscreen mode

After the scan, you'll find a CLAUDE.md file in the root directory containing sections like build commands, code style notes, and a high-level structure overview. This gives you a solid foundation without starting from a blank page.

However, the generated file is only a first draft. It often misses critical context — such as specific linting rules, testing workflows, or nuanced architectural decisions — that you'll need to add manually. Treat the output as a scaffold, not the final product. In the next steps, you'll refine it with project-specific conventions and constraints that make Claude truly effective.

Step 2: Answer the Five-Question Framework

To build a CLAUDE.md that gives Claude the context it needs without guesswork, answer five specific questions about your role, project, structure, decisions, and commands. The claude init command can generate a first draft, but you must refine it to include these details. Keep the final file concise—ideally under 200 lines—by segmenting into logical sections.

Who are you? Define your role and team. This sets the perspective Claude should adopt.

## Who
- I am a full-stack developer on a two-person team.
- We prioritize accessibility and mobile-first design.
Enter fullscreen mode Exit fullscreen mode

What are you building? Describe the project and its goals.

## What
- A Next.js 14 e-commerce site for handmade goods.
- Goal: fast, SEO-optimized product pages with Stripe checkout.
Enter fullscreen mode Exit fullscreen mode

Where does everything live? Outline the project structure and key directories.

## Where
- `app/`: Next.js App Router pages and API routes.
- `components/`: Shared UI components.
- `lib/`: Business logic, database helpers, and API clients.
- `supabase/`: Database migrations and edge functions.
Enter fullscreen mode Exit fullscreen mode

Why did you make those choices? Explain architectural decisions and constraints.

## Why
- Chose Supabase for real-time features and row-level security.
- Server Components by default; `'use client'` only when necessary.
- No CSS framework—use Tailwind utility classes exclusively.
Enter fullscreen mode Exit fullscreen mode

How do you work? Provide exact commands for building, testing, linting, and running the project.

## How
- Build: `npm run build`
- Dev server: `npm run dev`
- Lint: `npm run lint`
- Test: `npm run test` (Vitest)
- Type check: `npx tsc --noEmit`
Enter fullscreen mode Exit fullscreen mode

Answering these five questions gives Claude the precise context it needs to make correct decisions without guessing.

Step 3: Structure the File for Clarity

Organize your CLAUDE.md into logical sections with clear Markdown headings. A proven structure includes Project Overview, Project Structure, Purpose & Key Decisions, and Working on the Project. If the file exceeds ~200 lines, split it into a CLAUDE.md/ directory containing individual files per section, then reference them from the main file to keep context modular and maintainable.

Start with a high-level description of what the project does and its primary tech stack. Follow with a concise directory tree so Claude understands the code layout. The Purpose & Key Decisions section explains why the architecture exists—for example, why you chose a particular state management library or database schema. The Working on the Project section provides the exact commands Claude needs to build, test, and lint the codebase.

When the file grows too large, create a CLAUDE.md/ directory. Move each section into its own file, then use a reference in the main CLAUDE.md:

CLAUDE.md/
├── 01-project-overview.md
├── 02-project-structure.md
├── 03-purpose-and-decisions.md
└── 04-working-on-project.md
Enter fullscreen mode Exit fullscreen mode

In the root CLAUDE.md, include a simple pointer:

# CLAUDE.md

This project uses a modular context. See the `CLAUDE.md/` directory for full details.
Enter fullscreen mode Exit fullscreen mode

This approach keeps the initial context lean while giving Claude access to all necessary information on demand. Each section file should still use clear Markdown headings and remain focused on its topic.

Step 4: Keep It Lean — Under 200 Lines

Keep your CLAUDE.md under 200 lines to prevent information overload. A lean file ensures Claude reads and applies the most critical context without getting lost in noise. If you have extensive guidelines, split them into separate files within a CLAUDE.md/ directory and reference them from the main file.

For example, instead of pasting a full style guide, point to a dedicated file:

# CLAUDE.md

## Project Overview
- Next.js 14 app with Tailwind CSS and Supabase
- All API routes live in `app/api/`

## Commands
- `npm run dev` – start development server
- `npm run test` – run vitest suite
- `npm run lint` – check ESLint + Prettier

## Guidelines
- See `CLAUDE.md/architecture.md` for project structure and data flow
- See `CLAUDE.md/conventions.md` for naming, component patterns, and error handling
- See `CLAUDE.md/testing.md` for test structure and mocking rules
Enter fullscreen mode Exit fullscreen mode

This approach keeps the main file focused on the essentials: project overview, key commands, and pointers to detailed docs. Avoid pasting large code snippets or entire documentation pages; Claude can read the referenced files when needed. A concise CLAUDE.md ensures the AI starts each session with clear, actionable context rather than sifting through a wall of text.

Step 5: Test and Iterate

Test your CLAUDE.md by starting a fresh Claude Code session and asking it to perform a common task, then refine the file based on where it deviates from your conventions. This loop turns the auto-generated first draft into a reliable, project-specific instruction set.

Begin by running claude init to generate a baseline file, but treat it as a starting point — it often misses critical details. Then open a new session and give Claude a representative prompt, such as:

Add a new API endpoint GET /api/users/:id that returns a user object from the database.
Enter fullscreen mode Exit fullscreen mode

Observe the output carefully. Does Claude use your preferred folder structure (e.g., placing the handler in app/api/users/[id]/route.ts)? Does it follow your linting and testing commands? If it runs npm run lint instead of your project’s pnpm lint, or writes raw SQL instead of using your ORM, the CLAUDE.md is missing context.

When you spot a mistake, update the file immediately. For example, if Claude skipped tests, add a short, explicit block:

## Commands
- Build: `pnpm build`
- Lint: `pnpm lint`
- Test: `pnpm test` (run after every code change)
Enter fullscreen mode Exit fullscreen mode

If it placed a component in the wrong directory, reinforce your conventions:

## Project Structure
- `components/ui/` – shared UI components
- `components/features/` – feature-specific components
- Never create new files in `pages/`; use the App Router.
Enter fullscreen mode Exit fullscreen mode

After each update, restart the session and repeat the same prompt to verify the fix. As your project evolves, review CLAUDE.md regularly — add new patterns, remove outdated ones, and keep the file under 200 lines to prevent information overload. If it grows too large, split logical sections into separate files and reference them from the main CLAUDE.md. This living document ensures Claude always works with your current conventions, not last month’s assumptions.

FAQ

What's the difference between CLAUDE.md and AGENTS.md?

Both serve the same purpose: providing project context to AI coding agents. CLAUDE.md is specific to Claude Code, while AGENTS.md is a more generic convention used by other tools. You can use either, but CLAUDE.md is the default file Claude Code looks for.

Can I use a directory instead of a single CLAUDE.md file?

Yes. If your context is too large for a single file, create a CLAUDE.md/ directory and store individual Markdown files for each section. Reference them from a main CLAUDE.md file using relative links or simply by placing them in the directory — Claude Code will read all files in that directory.

How often should I update my CLAUDE.md?

Update it whenever your project's architecture, conventions, or key commands change. Treat it as a living document. After major refactors or when you notice Claude making repeated mistakes, revisit and refine the file to keep it accurate.

What happens if I don't have a CLAUDE.md file?

Claude Code will still work, but it will start each session with no prior knowledge of your project. It will make guesses about your tech stack, coding style, and commands, which often leads to inconsistent or incorrect output. A well-crafted CLAUDE.md eliminates this guesswork.

References for further reading

Sources consulted while researching this guide, included so you can verify the details and go deeper. Listing them is not a claim that every line was independently fact-checked.

Your turn

What's the one section or piece of context you've added to your CLAUDE.md that made the biggest difference in Claude Code's output quality? Share your experience — I'd love to see what works for different tech stacks.

I packaged the setup above into a ready-to-use kit — **The Claude Code Project Setup Playbook* — for anyone who'd rather copy-paste than wire it from scratch: https://unfairhq.gumroad.com/l/dpllv.*

Top comments (0)