If you use Claude Code, you've probably noticed it references a CLAUDE.md file. You might have one already — or you might be wondering if you need one. Either way, understanding how CLAUDE.md works can meaningfully improve how Claude Code assists you.

This post explains what it is, how to structure it, what to put in it, and how it compares to similar config files in other AI coding tools.

What Is CLAUDE.md?

CLAUDE.md is a markdown file that Claude Code reads automatically at the start of every conversation in a project directory. Think of it as a persistent system prompt for your project — context that Claude Code carries into every session without you needing to re-explain it.

When you run Claude Code in a directory that contains a CLAUDE.md, it reads the file and uses that context to inform all its responses. It understands your tech stack, your conventions, your preferred patterns, what commands to run, what directories to avoid, and whatever else you've told it.

Without a CLAUDE.md, you start every Claude Code session cold. With a good one, you start with a collaborator that already knows your project.

Why CLAUDE.md Matters

Here's what a CLAUDE.md file enables:

Consistent conventions. If your team uses specific patterns — a particular way to name API routes, a component file structure, a testing approach — you document it once in CLAUDE.md and Claude Code follows it in every session.

Stack context. Claude Code knows what frameworks and versions you're using, what dependencies are available, and what architectural constraints exist. It doesn't suggest using a library you're not using, or a pattern that doesn't fit your stack.

Project structure awareness. You can tell Claude Code which directories contain what, what's auto-generated (and therefore shouldn't be manually edited), and where important files live.

Command reference. What command runs tests? What command builds for production? What starts the dev server? Documenting these in CLAUDE.md means Claude Code can suggest the right commands rather than guessing.

Critical rules. Constraints that Claude Code absolutely must not violate — no console.log in production code, always use the internal auth middleware, never modify files in certain directories. These go in a "Critical Rules" section and Claude Code treats them as hard constraints.

Structure of a Good CLAUDE.md

There's no required format, but a structure that works well:

# Project Name — Claude Code Guide

## Project Overview

What the project is, what it does, who it's for. 2-3 sentences.

## Tech Stack

| Layer | Tool |
|-------|------|
| Framework | Next.js 15 (App Router) |
| Styling | Tailwind CSS v4 |
| Database | PostgreSQL + Drizzle ORM |
| Auth | Clerk |
| Deployment | Vercel |

## Project Structure

\`\`\`
src/
├── app/          — Next.js App Router pages
├── components/   — Reusable UI components
├── lib/          — Utilities and helpers
├── server/       — Server actions and API
└── db/           — Database schema and migrations
\`\`\`

## Development Commands

\`\`\`bash
npm run dev      # Start dev server
npm run build    # Production build
npm run test     # Run tests
npm run db:push  # Push schema changes
\`\`\`

## Conventions

- Use Server Components by default; only 'use client' when needed
- API routes return { data, error } shape
- Component names: PascalCase; files: kebab-case
- All API calls go through lib/api.ts

## Critical Rules

1. Never modify files in src/generated/ — they are auto-generated
2. All mutations must go through server actions (never client-side fetch to database)
3. All new API routes must use the withAuth() middleware
4. Never commit .env files

This is a real-world structure. The specifics will vary enormously by project, but the pattern holds.

What to Include

Always include:

Tech stack with specific versions
Project structure overview
Key commands (dev, build, test, deploy)
Naming and file organization conventions
Any hard constraints or rules

Include if relevant:

Authentication and authorization patterns
Database schema overview or link to it
Environment variable names and what they do
CI/CD pipeline context
Team-specific workflows

What to omit:

Information Claude Code can infer from reading the code
Redundant documentation that's already in README.md (link to it instead)
Detailed API documentation for third-party services (link to the docs)

Keeping CLAUDE.md Updated

A CLAUDE.md that's outdated is worse than no CLAUDE.md — Claude Code will confidently follow conventions that no longer apply. Keep it updated as your project evolves:

When you add a major dependency, add it to the Tech Stack table
When you introduce a new pattern, add it to Conventions
When the command to run tests changes, update the commands section
When you add a new directory with a distinct purpose, update the structure map

Some teams treat updating CLAUDE.md like updating package.json — it's part of the work, not an afterthought.

Reading CLAUDE.md Properly

Here's something that matters more than you'd expect: CLAUDE.md files should be read in a proper markdown viewer, not a text editor or the terminal.

A well-structured CLAUDE.md uses headings, tables, and code blocks. When you open it in a text editor, you see the raw symbols. When you open it in a markdown editor, you see formatted sections, aligned tables, and properly highlighted code blocks.

This matters because you'll be writing and reviewing your CLAUDE.md regularly — adding new rules, updating the tech stack, refining conventions. Working in a proper markdown editor makes the structure clearer and editing faster.

OpenMark opens any .md file and renders it immediately. You can see the formatted output, toggle to edit mode to make changes, and toggle back to verify. For a file you're editing repeatedly, this is meaningfully better than working in raw text.

CLAUDE.md vs Other AI Config Files

Several AI coding tools use similar config file patterns:

.cursorrules — Cursor's equivalent. Same idea: a text file in the project root that the AI reads for context. Cursor reads it from .cursorrules; Claude Code reads CLAUDE.md. The content is similar — stack, conventions, rules.

.github/copilot-instructions.md — GitHub Copilot's equivalent for repository-level instructions. Stored in .github/, read by Copilot in editors with the extension. Similar structure to CLAUDE.md.

.windsurfrules — Windsurf's equivalent.

The pattern is converging: AI coding tools benefit enormously from project context, and markdown files in the repository are the obvious mechanism for providing it.

If you use multiple tools, you can maintain one canonical context file and symlink or copy it to the appropriate location for each tool. The content is largely the same regardless of which AI reads it.

Real Examples (Genericized)

Here's what a front-end project's critical rules section might look like:

## Critical Rules

1. This is a Server Components-first app — 'use client' only for interactivity
2. All form submissions use Server Actions (no client-side fetch to database)
3. Styles use Tailwind utility classes — no custom CSS except in globals.css
4. Images must use next/image, never raw <img> tags
5. All external API calls go through lib/api/ — never call APIs directly from components

And a backend service:

## Critical Rules

1. All endpoints must validate input with Zod before processing
2. Database queries must go through the repository layer (src/repositories/)
3. Never log sensitive data (passwords, tokens, PII)
4. All new endpoints require integration tests in tests/api/
5. Use camelCase for JSON field names in API responses

The specific rules are less important than the habit of capturing them. Claude Code will respect them.

Try OpenMark

Read and edit your CLAUDE.md as it's meant to be read — formatted, structured, scannable.

Download OpenMark on the Mac App Store → $9.99 one-time. Native macOS. No subscription. openmarkapp.com

CLAUDE.md Explained: How to Configure Claude Code with Markdown