MD Vessel

What Is a CLAUDE.md File? (And How Claude Code Uses It)

A CLAUDE.md file is a Markdown document that Claude Code reads at the start of every session to understand your project — how to build it, how to test it, and the conventions it should follow. It lives in your repository and acts as the agent's project memory.

If you've used a coding agent, you know the failure mode: every session starts from zero. The agent has your repo and your prompt, but no idea that this project builds with pnpm, tests with vitest, or that /generated is build output nobody touches. So it spends the first ten minutes rediscovering the obvious — and occasionally getting it wrong. CLAUDE.md is the fix that costs nothing to adopt.

What Claude Code actually does with it

When you start a session in a project that contains a CLAUDE.md, Claude Code loads the file as context. Everything in it steers the session:

  • The commands — it knows npm run dev, pytest, or bun run build without guessing, and runs the right one for the task
  • The architecture — it understands where things live, so a "where does checkout live?" question gets answered from the file, not from a scan of your whole repo
  • The conventions — naming, formatting, what not to touch. Agents follow written instructions far more reliably than they infer them
  • The boundaries — files to leave alone, generated directories, where secrets live

The file is the cheapest way to make a coding agent behave like a developer who's been in the repo for months instead of a visitor who just arrived.

What should go in a CLAUDE.md?

The best files are short, specific, and command-first. A good skeleton:

# Project: [name]

## Commands
- Build: `npm run build`
- Test: `npm test`
- Dev server: `npm run dev`

## Architecture
- Next.js app in /app, Convex backend in /convex
- Shared components in /components

## Conventions
- TypeScript strict, no `any`
- Tailwind for all styling
- Commit messages: conventional commits

## Don't
- Don't edit files in /generated — they're build output
- Don't add new runtime dependencies without asking

Every line should be actionable. "The codebase is a mess" is not actionable; "don't touch /legacy" is.

Best practices that keep the file useful

  1. Commands first. If the file only gets ten lines, spend them on how to build, test, and run the project.
  2. Keep it short. A CLAUDE.md that needs scrolling is a wall that gets ignored. Aim for 50–100 lines; link out to detailed docs instead of embedding them.
  3. Write rules, not descriptions. "Use pnpm" beats "we prefer pnpm as our package manager".
  4. Version it with the repo. The file is documentation — review it in PRs like code, update it when conventions change.
  5. Never put secrets in it. The file ships in the repo and is loaded into every session.
  6. One source of truth. If a rule exists in both CLAUDE.md and the README, they will drift. Keep canonical rules in one place and link from the other.
  7. Let the agent update it. When conventions change, the agent that discovered the change is often the best one to record it — in the same style as the rest of the file.

Common mistakes

  • The 800-line novel. Detail is good; a wall of prose is ignored. Prefer bullets and commands.
  • Stale commands. A CLAUDE.md whose test command broke last month is worse than none — the agent runs it confidently and reports the failure as your bug.
  • Contradictory rules. "Never edit /config" plus "update the API key in /config/config.js" returns garbage no matter how the agent resolves it.
  • Secrets in the file. It's the first file an agent reads — and the first one a repo leak exposes.

Example: one of the better ones

# analytics-service

## Commands
- Install: `pnpm install`
- Test: `pnpm vitest run`
- Typecheck: `pnpm tsc --noEmit`
- Lint: `pnpm eslint`

## Stack
- Deno + Hono, Postgres via Drizzle, deployed on Fly.io

## Conventions
- Handler files live in /src/handlers, named <resource>.handler.ts
- Errors return { error: { code, message } }
- All DB access via repository modules in /src/repositories

## Don't
- Don't commit migration files — they're generated by `pnpm db:gen`
- Don't touch /infra unless the task is explicitly about deployment

CLAUDE.md vs AGENTS.md

Claude Code reads CLAUDE.md natively. Other tools have their own conventions — and many are converging on AGENTS.md, a cross-agent file that any tool can support. Some teams ship both: AGENTS.md as the shared, tool-agnostic file and CLAUDE.md as a short pointer to it. If you only run Claude Code, one file is enough; if your team is split across Cursor, Codex, and Claude Code, the cross-agent file saves you from maintaining two sources of truth.

Keep it in sync — without a shared place it rots

There's a quiet problem with CLAUDE.md files shared across a team: everyone's copy diverges, and the version in your head is never the one in the repo. A simple pattern is to keep the file somewhere it can be read, edited, and handed to the agent over HTTP:

  • Store the canonical CLAUDE.md in an MD Vessel workspace
  • Your agent reads it via the API at the start of a session — same file, every session, no copy-paste
  • When the team's conventions change, the file updates in one place and every session picks it up

For a full walkthrough of what happens at session start and how to write a file your agent actually follows, read How Claude Code Uses CLAUDE.md.

Frequently Asked Questions

Is a CLAUDE.md file required? No — Claude Code works without one. But the file is how you stop repeating the same context ("we use pnpm, tests are in /tests", "don't touch /legacy") in every session.

What if CLAUDE.md conflicts with what I write in my prompt? Session instructions generally take precedence — treat the file as the baseline and the prompt as the override.

Does Cursor or other tools read CLAUDE.md? Claude Code reads it natively. Other tools have their own conventions — many now support the cross-agent AGENTS.md file instead, and some read both.

How big should it be? Short. If you need more than ~100 lines, put the detail in a linked doc and keep the file a pointer plus the essentials.

Should CLAUDE.md be committed to git? Yes. It's project documentation and belongs in the repo — that's how the whole team (and their agents) stay on the same page.

Can a CLAUDE.md file be global instead of per-project? Claude Code supports user-level configuration, but the project file is the one that carries repo-specific commands and conventions. Most teams keep both: personal preferences globally, project rules in the repo.

Related

Related articles