CLAUDE.md is a small instruction file that lives in your project and changes how Claude Code behaves from the first line of every session.
CLAUDE.md is a Markdown file you place at the root of a project (or in your home directory for global use). When Claude Code starts, it reads the file and uses its instructions as the starting context for every conversation in that project.
The name CLAUDE.md is a convention — Anthropic's Claude Code specifically looks for this filename and injects its contents into the system prompt before your first message. It's not a configuration file, a code file, or a database. It's plain text instructions in Markdown format that Claude reads and follows.
Think of it like a project-specific briefing. Instead of explaining your stack, your conventions, and your constraints in every new conversation, you write them once in CLAUDE.md and they apply everywhere — every session, every file, every task.
When Claude Code starts a session, it performs this sequence:
~/.claude/CLAUDE.md (always, regardless of project)CLAUDE.md it finds at each directory levelThis means CLAUDE.md is not a one-time setup file. It's a persistent layer that shapes every interaction. Changes to it take effect the next time you start a session — there's no manual reload step.
The practical result: a well-written CLAUDE.md makes Claude Code feel like it already knows your project. It doesn't need to be told what your stack is, which conventions matter, or what to avoid. That context is baked in from the start.
Language models are generalists by default. Without explicit instruction, Claude treats every project the same way — using generic conventions, making generic assumptions, and applying generic patterns.
A CLAUDE.md file overrides that default. It tells Claude:
Without a CLAUDE.md, Claude Code works fine for straightforward tasks. With one, it works correctly for the specific things that matter in your project — the edge cases, the convention violations, the decisions that don't appear in any README.
A good CLAUDE.md is specific and concise. Here's what belongs in it:
Two or three sentences. What you build, what your stack is, and what you're trying to accomplish. Skip the history lesson — just the current-state facts Claude needs to understand the work.
The most impactful section most people skip. A numbered list of the actual tasks you hand to Claude — debugging, writing migrations, reviewing diffs, drafting copy, whatever you actually do. This tells Claude how to interpret ambiguous requests in your context.
How you want responses formatted. "Be concise" is not a style. "Bullets over paragraphs, code blocks for anything over two lines, no preamble" is a style. Be specific — vague instructions get vague compliance.
Imperative rules: things Claude must always do or must never do. These should be concrete and testable. "Show me the SQL before running any migration" is a hard rule. "Be careful with the database" is not.
Internal terms, acronyms, and naming conventions that don't appear in the code. Without this, Claude will invent plausible wrong definitions on first ambiguity.
Three locations matter:
~/.claude/CLAUDE.md — global. Your personal communication style, hard rules, and defaults apply across every project. Loaded every session regardless of directory.
<project-root>/CLAUDE.md — project-specific. Stack, conventions, hard rules for this codebase. Loaded when Claude starts inside the project.
<subdirectory>/CLAUDE.md — scoped. Useful in monorepos where apps/web and apps/api have different conventions. Loads only when working inside that subdirectory.
Deeper files override shallower ones on conflicts. Your global preferences apply everywhere as a baseline; project files can override them where needed.
CLAUDE.md is not a README. It doesn't document the project — it instructs Claude on how to work in it.
It's not a task list. It shouldn't contain TODOs, project status, or ongoing work descriptions. Those belong in your project management tool, not a system prompt file.
It's not a style guide for humans. Every sentence in CLAUDE.md is competing for a slot in Claude's instruction budget. If a paragraph exists to inform a human reader, not to change Claude's behavior, cut it.
It's not a one-time file. You update CLAUDE.md as your project evolves — new conventions, new constraints, new recurring tasks. It's a living instruction file, not a setup step.
CLAUDE.md is Anthropic's convention for Claude Code specifically. AGENTS.md is a more recent, product-agnostic convention used by tools like Cursor, Windsurf, and others that support custom agent instructions.
The format is nearly identical. The key difference is which tool reads which file:
CLAUDE.mdAGENTS.md or bothFor Claude Code users, CLAUDE.md is the right file.
Writing the file is step one. Verifying it loads is step two.
Use /context in Claude Code. Type /context and review what's shown in the system prompt. Your CLAUDE.md content should appear near the top. If it doesn't, the file isn't in the right location or the filename is wrong (it's case-sensitive: CLAUDE.md, not claude.md).
Test rules functionally. Give Claude a task designed to trigger each hard rule. If the rule fires correctly, it's working. If Claude ignores it, the rule is either buried too deeply in the file or not specific enough to apply.
Check a new session. Don't test in a session where you've already been talking. Start fresh. Rules can be loaded but not applied in long conversations with accumulated context.
The autobiography. Three paragraphs of career history that tell Claude nothing actionable about the current project. One sentence on your role, one on the project, one on the stack — that's it.
The encyclopedia. 1,200 lines covering every possible scenario. Claude loads the first 200 rules reliably and treats the rest as optional. Cut to what actually matters.
The abstract wish list. "Be insightful and thorough." Claude interprets this as permission to do whatever looks good. Replace every adjective with a concrete constraint.
Burying the hard rules. Rules at the bottom of a long file get the least consistent application due to position bias. Put your most important rules at the top.
Where exactly does CLAUDE.md go in my project?
At the repository root — same level as your README.md. Claude Code walks upward from the current directory when it starts, so it finds the root file automatically. The filename is case-sensitive: CLAUDE.md, not claude.md.
What does CLAUDE.md stand for?
It's not an acronym. The name is simply CLAUDE.md — Claude's instruction file. The .md extension indicates it's written in Markdown format, which makes it human-readable and lets Claude parse headings, lists, and code blocks naturally.
Is CLAUDE.md the same as a system prompt?
In function, yes — it gets prepended to the system prompt. In scope, not exactly. A system prompt is typically global and fixed. CLAUDE.md is per-project and editable by you at any time without touching any tool configuration.
Can I have both CLAUDE.md and AGENTS.md?
Yes. Claude Code reads CLAUDE.md. Other tools read AGENTS.md. Having both lets you optimize each file for the specific tool. If you use Claude Code as your primary tool, CLAUDE.md is where your effort goes.
Does CLAUDE.md slow down Claude Code?
No. The file is read once at session start, and its contents are injected into the initial context window. There's no runtime overhead during a session. A 200-line CLAUDE.md adds roughly 1–2 seconds to session startup and no ongoing latency.
What's the difference between CLAUDE.md and .claude/settings.json?
CLAUDE.md contains behavioral instructions — rules, conventions, preferences. settings.json (in .claude/) contains tool-level configuration — which MCP servers to mount, default model settings, UI preferences. They serve different purposes and complement each other.
Can Claude learn from CLAUDE.md automatically over time?
No — CLAUDE.md is not dynamic. It doesn't learn from your sessions or update based on your behavior. It's a static instruction file you maintain manually. If you want Claude to change behavior, you edit the file directly.
CoworKit's generator asks 5–6 questions about how you work with Claude and produces a scored, structured CLAUDE.md tailored to your role and stack. Free, no signup required.
The Optimize tab analyzes an existing file and rewrites it with concrete constraints instead of vague guidance — closing the gap between what you wrote and what Claude actually follows.
Practical guides and prompt patterns — no fluff, unsubscribe any time.