How to Set Up CLAUDE.md: The Five-Question Framework That Makes Claude

What Changed — CLAUDE.md is Now Essential for Every Claude Code Project

CLAUDE.md is a Markdown file placed in your project's root directory that acts as a persistent system prompt for Claude Code. Without it, Claude starts each session from scratch, relying on generic assumptions that miss your actual conventions, architecture, and preferences.

When Claude Code opens a project, it reads this file first. This upfront context prevents Claude from making reasonable but incorrect guesses about your codebase, saving you from repeatedly correcting the same mistakes across sessions.

The Technique — The Five-Question Framework

To build a CLAUDE.md that gives Claude the context it needs without guesswork, answer five specific questions. Start by generating a draft:

cd /path/to/your/project
claude init

This scans your codebase and produces a first draft with build commands, code style notes, and structure overview. But treat it as a scaffold—it often misses critical details like your preferred testing framework or architectural decisions.

Refine it with these five 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.

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.

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.

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.

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`

Why It Works — Context Window Economics

Claude Code's context window is finite. A bloated CLAUDE.md wastes tokens on irrelevant details. Keeping it under 200 lines forces you to prioritize the most impactful context. If you have extensive guidelines, split them into a CLAUDE.md/ directory:

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

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.

This approach keeps the initial context lean while giving Claude access to all necessary information on demand.

Try It Now — Apply to Your Project Today

1. Run claude init in your project root.
2. Edit the generated CLAUDE.md using the five-question framework.
3. Keep the file under 200 lines. If it grows, split into CLAUDE.md/ directory.
4. Test by asking Claude a project-specific question—observe if it follows your conventions without correction.

Source: dev.to