CLAUDE.md: the file that makes or breaks your AI workflow

Most developers who try Claude Code give up after a week. Not because the tool is bad. Because they're running it on a codebase that gives it nothing to work with.

The fix isn't a better prompt. It's a file called CLAUDE.md.

What CLAUDE.md actually does

Each Claude Code session starts with a fresh context window. CLAUDE.md is how you carry knowledge across sessions. It's the first thing Claude reads when a session begins.

Everything in that file becomes its working context: what the project is, how it's structured, what conventions to follow, what not to do. Without it, the agent guesses. Some guesses are right. Most are generic.

You don't have to write it manually from scratch. Run /init inside Claude Code and it analyzes your codebase to generate a starting file: build commands, project structure, conventions it discovers on its own. Refine from there with the things it wouldn't find on its own.

The 200-line rule

Anthropic's official guidance: keep each CLAUDE.md file under 200 lines. This isn't arbitrary. The file loads into the context window at the start of every session. A bloated CLAUDE.md burns tokens on instructions Claude won't follow consistently because they're buried too deep.

If your instructions are growing past that, split them. Put package-specific instructions in a CLAUDE.md inside that package's directory. Claude loads subdirectory files on demand when it reads files in that folder.

Tight and specific beats thorough every time.

What goes in it

What works, after iterating across a few projects:

Project overview in two sentences. Not a README. What the project does, what the tech stack is. The agent needs context, not documentation.

Repo structure. Which folders matter, what lives where. If you have a monorepo with apps/, packages/, libs/, map it. The agent navigates files constantly. It should know where things live before it starts moving them around.

Naming and style conventions. If your components use variant props, say so. If you use kebab-case for file names, say so. The agent can follow a rule if you tell it the rule.

What not to do. This is the most underused section. "Don't add new dependencies without asking." "Don't touch the auth module, it's in active refactor." "Mock data lives in __fixtures__, not inline." These constraints prevent expensive mistakes.

Commands the agent should know. How to run tests. How to build. How to check types. The agent will attempt to validate its own work if you give it the right tools.

Here's what mine looks like for a React Native project:

# CLAUDE.md

React Native app (Expo, TypeScript). Music practice app with real-time audio features.

## Structure
- `apps/mobile/` — main RN app
- `packages/ui/` — shared components
- `packages/core/` — business logic, no native code

## Conventions
- Components: PascalCase files, named exports
- Props: use `variant` not `type` for style variants
- Hooks live in `hooks/`, not colocated with components unless specific to one screen

## What to avoid
- No new dependencies without checking first
- Don't modify `packages/core/audio/` — in active refactor
- Don't add console.logs to production code paths

## Useful commands
- `pnpm test` — runs unit tests
- `pnpm typecheck` — tsc --noEmit
- `pnpm lint` — eslint

No philosophy. No mission statement. Just what the agent needs to operate without making expensive mistakes.

The foundation, not the ceiling

CLAUDE.md changes the failure mode. Without it, you're in correction mode constantly. The agent makes plausible-but-wrong choices, you catch them, explain them, restart. With it, the mistakes that happen are interesting ones: logic errors, edge cases. Not "wrong file name" or "that's not how we do props."

But it's the floor, not the system.

Once CLAUDE.md is solid, there's a whole layer of tools Claude Code supports on top: custom slash commands for workflow orchestration, subagents with isolated contexts for specialized tasks, skills (markdown files that load on demand), hooks that run on specific events outside the agentic loop, and MCPs for live external integrations.

CLAUDE.md is the prerequisite. Everything else builds from there.

Start simple

A one-page CLAUDE.md that covers structure, conventions, and two or three explicit constraints will outperform no CLAUDE.md by a wide margin. You don't need the perfect version on day one.

Write what you know today. Update it when something breaks.

The file that changes how your agent works isn't complex. It just has to exist.