How to Write a CLAUDE.md File — Step-by-Step Guide With Examples

How to Write a CLAUDE.md File — Step-by-Step Guide With Examples

You know you need a CLAUDE.md file for your project, but staring at a blank file wondering what to write is intimidating. This tutorial walks you through writing one from scratch, with a complete real-world example you can adapt.

Before You Start

Open your project in whatever editor you use. Create a file called CLAUDE.md in the root directory — the same folder as your package.json, pyproject.toml, Cargo.toml, or equivalent.

Keep this principle in mind: write what a smart new hire would need to know on their first day. Not everything — just the things that are not obvious from reading the code.

Step 1: Project Overview (2-3 Sentences)

Start with what the project is and what technologies it uses. Be factual and concise.

# Project Overview

TaskFlow is a project management SaaS for small teams. Built with
Next.js 15 (App Router), TypeScript, Prisma with PostgreSQL, and
Tailwind CSS. Deployed on Vercel with the database on Neon.

Why this matters: Claude Code uses this to understand the overall technology stack before it reads any files. It will not suggest Express.js solutions when it knows you use Next.js, or recommend MongoDB patterns when you use PostgreSQL.

Step 2: Project Structure

List the key directories and what lives in them. You do not need to map every folder — just the ones that are not obvious.

# Project Structure

- `/app` — Next.js app router (pages, layouts, server actions)
- `/app/api` — API routes (only used for webhooks, everything else uses server actions)
- `/components` — Shared UI components
- `/components/ui` — Base components from shadcn/ui (do not edit directly)
- `/features` — Feature modules, each with its own components, hooks, and utils
- `/lib/db` — Prisma client, repository functions, and seed data
- `/lib/services` — Business logic layer (called by server actions)
- `/lib/schemas` — Zod validation schemas
- `/emails` — React Email templates

Why this matters: when you ask Claude Code to add a feature, it needs to know where to put new files. Without this map, it might create files in the wrong locations.

Step 3: Key Commands

List every command a developer needs to know. Be exact — include flags and options.

# Commands

- `npm run dev` — Start dev server (port 3000)
- `npm run build` — Production build
- `npm run test` — Run vitest (unit + integration)
- `npm run test:e2e` — Run Playwright e2e tests
- `npm run test -- --run path/to/file` — Run a specific test file
- `npx prisma migrate dev` — Create and apply migrations
- `npx prisma generate` — Regenerate Prisma client after schema changes
- `npx prisma studio` — Open database browser
- `npm run lint` — ESLint
- `npm run type-check` — TypeScript type checking

Why this matters: Claude Code runs these commands to test changes, check for errors, and verify its work. If it does not know your test command, it cannot run tests after making changes.

Step 4: Coding Conventions

This is the most impactful section. List the patterns your team follows — especially the ones that differ from the defaults or from what tutorials teach.

# Coding Conventions

## TypeScript
- Strict mode is on — no `any` types. Use `unknown` and narrow.
- Prefer interfaces over type aliases for object shapes.
- Use `satisfies` for type checking object literals.

## Components
- Use named exports, not default exports.
- Props interfaces are defined in the same file, named `[Component]Props`.
- Client components have the `"use client"` directive. Server components do not need a directive.
- Keep components under 150 lines. Extract sub-components when they grow.

## Data Fetching
- Server components fetch data directly using repository functions.
- Client-side mutations use server actions in `/app/actions/`.
- Do NOT use API routes for new endpoints. Use server actions instead.
- Revalidation uses `revalidatePath()` or `revalidateTag()`.

## Database
- All database queries go through repository functions in `/lib/db/repos/`.
- Never import `prisma` directly in components or actions — use the repo functions.
- One migration per logical change. Name migrations descriptively.

## Error Handling
- Server actions return `{ success: true, data } | { success: false, error }` — use the Result type from `/lib/types/result.ts`.
- Do not throw errors in server actions. Catch and return error results.
- User-facing error messages go in `/lib/constants/errors.ts`.

## Testing
- Test files live next to the source: `Button.tsx` and `Button.test.tsx` in the same folder.
- Use Testing Library for component tests. Test behavior, not implementation.
- Use `vi.mock()` for mocking. Mock at the module boundary (repos, services).
- E2E tests go in `/e2e/` and test complete user flows.

Why this matters: this section prevents 90% of the corrections you would otherwise make. Every rule here is something Claude Code will follow automatically.

Step 5: Important Context and Gotchas

Add anything unusual, any known issues, or any decisions that might not be obvious.

# Important Context

- The `user.email` field is nullable in the database due to a legacy migration.
  Always null-check it in backend code even though the UI requires it.
- The `/lib/legacy/` directory is deprecated. Do not import from it or add to it.
  New code should use the equivalent in `/lib/services/`.
- We use Resend for transactional email. The API key is in env as `RESEND_API_KEY`.
- Stripe webhooks hit `/api/webhooks/stripe`. The webhook secret is `STRIPE_WEBHOOK_SECRET`.
- The `admin` role is checked via `user.role === 'ADMIN'` — there is no separate admin table.

Step 6: Do Not List

Explicitly state what Claude should avoid. This is surprisingly effective at preventing common mistakes.

# Do Not

- Do not use `any` type — use `unknown` and narrow.
- Do not create new API routes — use server actions.
- Do not import Prisma client directly — use repository functions.
- Do not add new dependencies without checking if an existing one covers the need.
- Do not modify files in `/components/ui/` — these are managed by shadcn.
- Do not use `console.log` for error handling — use the logger from `/lib/logger`.
- Do not hardcode URLs — use the constants in `/lib/config`.

The Complete Example

Here is everything from above assembled into a complete CLAUDE.md file:

# Project Overview

TaskFlow is a project management SaaS for small teams. Built with
Next.js 15 (App Router), TypeScript, Prisma with PostgreSQL, and
Tailwind CSS. Deployed on Vercel with the database on Neon.

# Project Structure

- `/app` — Next.js app router (pages, layouts, server actions)
- `/app/api` — API routes (only for webhooks)
- `/components` — Shared UI components
- `/components/ui` — shadcn/ui base components (do not edit)
- `/features` — Feature modules
- `/lib/db` — Prisma client and repository functions
- `/lib/services` — Business logic
- `/lib/schemas` — Zod schemas
- `/emails` — React Email templates

# Commands

- `npm run dev` — Dev server on port 3000
- `npm run test` — Vitest
- `npm run test:e2e` — Playwright
- `npx prisma migrate dev` — Database migrations
- `npm run lint` — ESLint
- `npm run type-check` — TypeScript checking

# Conventions

- TypeScript strict mode, no `any`
- Named exports, not default exports
- Server actions for mutations, not API routes
- Database queries through repo functions only
- Result types for server action returns
- Tests adjacent to source files

# Do Not

- Do not use `any` type
- Do not create API routes (use server actions)
- Do not import Prisma directly
- Do not modify `/components/ui/`
- Do not import from `/lib/legacy/`

This is about 50 lines of markdown. It takes 15-20 minutes to write for a project you know well, and it saves hours of correcting Claude over the following weeks.

Tips for Maintaining Your CLAUDE.md

Add rules when you correct Claude. Every time you tell Claude Code "no, we do it this way," add that convention to your CLAUDE.md. This is the most natural way to build a comprehensive file over time.

Review quarterly. Projects evolve. Conventions change. Set a reminder to review your CLAUDE.md and remove outdated rules.

Keep it under 200 lines. A CLAUDE.md that is too long dilutes the important information. If you need more detail on specific areas, consider using Claude Skills for domain-specific instructions.

Commit it to version control. Your CLAUDE.md should be in git, reviewed in PRs, and maintained by the team. It is project documentation, not personal configuration.

Generate One Automatically

If you want a head start, we built a free tool that generates a CLAUDE.md tailored to your project. Answer a few questions about your stack and conventions, and it produces a ready-to-use file. Try the CLAUDE.md generator.

Next Steps

Once your CLAUDE.md is in place, you will immediately notice better results from Claude Code. For more ways to optimize your AI-assisted development workflow, check our complete guide, browse our prompt library for tested patterns, and keep our cheat sheet handy for quick reference.