If you find yourself explaining the same five things to an AI every single morning, there's a file for that. There's also a lot of confident nonsense written about it.
The frustrating thing about AI assistants is re-explaining your context every morning: who you write for, what your team calls things, which formats you use, what you never want it to do. A CLAUDE.md file solves that by putting it in a markdown file the assistant reads at the start of every session. Anthropic’s own guidance is that these files should stay under about 200 lines, because a long one gets ignored. This piece covers what actually goes in one, why MEMORY.md is not the thing most articles say it is, a filled-in example for a marketing team rather than a codebase, and the equivalent in ChatGPT, Gemini and Copilot.
You open a new chat. You explain that you’re writing for mid-market HR directors, that the company style drops the Oxford comma, that “the Q report” means the quarterly retention summary and not the quarterly revenue one, and that you never want bullet points in client-facing copy.
Tomorrow you do it again. And on Thursday, when you’re in a hurry, you skip half of it and get something generic back, and conclude the tool has got worse.
A CLAUDE.md file is the fix, and it’s less sophisticated than it sounds. It’s a markdown file, in a folder, that Claude reads at the start of every session in that folder. You write it in plain text. That’s the entire mechanism.
Two things about it are widely misreported, and the first one changes how you should use it. Anthropic’s documentation is explicit: “CLAUDE.md content is delivered as a user message after the system prompt, not as part of the system prompt itself. Claude reads it and tries to follow it, but there’s no guarantee of strict compliance, especially for vague or conflicting instructions.” [1]
The docs put it more bluntly a line earlier: Claude “treats them as context, not enforced configuration.” That’s worth sitting with, because a lot of writing on this treats the file as a control panel, and it works more like a very well-placed note. Vague instructions produce vague adherence, and contradictory ones produce a coin flip. Anthropic says that plainly too: “if two rules contradict each other, Claude may pick one arbitrarily.”
Instructions are context, not a contract. Write them to be understood, not to be enforced.
The second thing is where these files live, because there’s more than one and they stack rather than override:
| Scope | Where it sits | Who sees it |
|---|---|---|
| Organisation policy | A managed system location, set by IT | Everyone in the organisation |
| You, everywhere | ~/.claude/CLAUDE.md | Just you, across all your projects |
| This project | ./CLAUDE.md or ./.claude/CLAUDE.md | The team, shared through version control |
| You, on this project | ./CLAUDE.local.md | Just you, not shared |
The four scopes per Anthropic’s documentation, broadest first. All discovered files are concatenated into context rather than overriding each other. [1]
Concatenated, not overridden, is the part that surprises people. Your personal file doesn’t replace the team one. Both arrive. So if your personal note says “always use British spelling” and the project file says “US spelling, house style,” you’ve created exactly the contradiction the docs warn about. If you’re already working in a folder, /init generates a starting file by looking at what’s there, and suggests improvements rather than overwriting if one exists.
Search for MEMORY.md and you’ll find a genre of article telling you to create one, structure it in sections, and maintain it as your AI’s long-term brain. Some of those pieces are well written. As a description of what MEMORY.md is, they’re wrong, and it’s worth being precise because the mistake leads people to build something that does nothing.
MEMORY.md is a real, official file. It’s just not yours to write, and that single fact undoes most of the advice written about it.
Claude Code has a feature called auto memory, which is on by default, where Claude writes notes to itself about what it’s learned working with you. Those notes go in a folder, and MEMORY.md is the index of that folder. Anthropic’s documentation describes it as acting “as an index of the memory directory,” which Claude “reads and writes files in throughout your session.” [1] The first 200 lines, or 25KB, load at the start of every conversation.
So the distinction that matters:
| CLAUDE.md | MEMORY.md | |
|---|---|---|
| Who writes it | You | Claude |
| What’s in it | Instructions and rules you’ve decided on | An index of things Claude noticed and saved |
| Should you edit it | Yes, constantly | Not really. It maintains itself |
| Portable to other tools | Partly. GitHub Copilot will read a root CLAUDE.md | No. It’s specific to Claude Code, and machine-local |
Per Anthropic’s memory documentation. Hand-authoring a MEMORY.md is a community practice, not a vendor convention. [1]
So if you write your own MEMORY.md and drop it in a folder expecting it to be read, nothing happens, because nothing is looking for it there. The instructions file you want is CLAUDE.md, and the effort is better spent making that one shorter.
Separately, and confusingly, the Claude you use in a browser has memory too, and it involves no files at all. It saves topics as you chat, you manage it in settings, and you can tell it to remember something directly. We’ve written about how memory works across ChatGPT and Claude if that’s the part you’re actually after. Three different things share one word, which is most of why this topic is confusing.
The failure mode here is not writing too little. It’s writing too much, and Anthropic names it directly: “If your CLAUDE.md is too long, Claude ignores half of it because important rules get lost in the noise.” [2]
Their stated target is under 200 lines, on the grounds that longer files consume more context and reduce adherence. There’s a related idea worth knowing if you’ve ever watched an assistant get vaguer over a long session, which we’ve covered in what context rot actually is. A bloated instructions file is a self-inflicted version of the same problem, and the test Anthropic gives for avoiding it is one line: “For each line, ask: ‘Would removing this cause Claude to make mistakes?’ If not, cut it.”
Their include and exclude table is written for developers. Here’s the same logic for people whose work is documents rather than code:
| Worth including | Leave it out |
|---|---|
| Internal shorthand it can’t guess: “the Q report means quarterly retention, not revenue” | Anything it can read from the files you’ve given it |
| House style that differs from the obvious default: no Oxford comma, British spelling, no bullet points in client copy | General good writing advice. It knows |
| Who the audience is, specifically. “Mid-market HR directors, 200 to 2,000 staff, not consultants” | Long background documents. Attach those instead |
| Things that have gone wrong twice: “never invent a statistic, and never state a figure without its source” | Information that changes weekly. It’ll go stale and mislead |
| What to never do: “don’t draft anything that names a specific employee” | Self-evident instructions like “be accurate” |
The structure of Anthropic’s official include and exclude guidance, translated from software work to document work. [2]
Anthropic’s third criterion, after size and structure, is specificity, and their examples are for code: “Use 2-space indentation” instead of “Format code properly.” The translation is exact. “Keep paragraphs to three sentences” instead of “write concisely.” “Every claim needs a source in brackets” instead of “be accurate.” The pattern underneath is that a verifiable instruction works and an aspirational one doesn’t, so if you couldn’t check whether it was followed by looking at the output, the model can’t really act on it either.
Short enough to be read beats complete.
One more from the docs, which is counterintuitive and saves people a lot of wasted effort: emphasis only works if it’s rare. “If you emphasize many lines, none of them stands out.” A file where six things are marked IMPORTANT has no important things in it.
Everything above is documented for software work, which is where the convention came from. The idea transfers cleanly, because the underlying problem isn’t technical. It’s that you keep re-explaining your context.
This is a complete instructions file for a marketing team. It’s short on purpose. Copy it and replace the specifics:
| Section | Content |
|---|---|
| ## Who we write for | HR and people ops leaders at UK companies with 200 to 2,000 employees. Not consultants, not enterprise. They are time-poor and sceptical of vendor language. |
| ## What our words mean | “The Q report” is the quarterly retention summary. “Pipeline” means marketing-qualified leads only. “The deck” is the standard partner deck, not the sales one. |
| ## Style | British spelling. No Oxford comma. Paragraphs of three sentences or fewer. No bullet points in anything client-facing. Never write “circle back” or “touch base”. |
| ## Always | Put a source in square brackets after any statistic. Give me two subject line options, never one. Flag anything you are unsure about at the top rather than burying it. |
| ## Never | Never invent a customer quote or a case study outcome. Never name a specific employee in a draft. Never state a figure I have not given you. |
| ## Where things live | Brand guidelines and the last four campaign reports are in this folder. Read them before drafting rather than asking me to summarise them. |
A worked example, roughly 25 lines as an actual file. Every line would cause a real mistake if removed, which is the test from the previous section.
Notice there’s no section on being helpful, no explanation of what marketing is, and no background on the company. All of that feels useful to write and none of it changes an output.
The “Never” section tends to be the one people underinvest in and the one that earns its place fastest. It’s also the only part of the file that meaningfully reduces risk rather than improving quality.
Where the file lives matters less than people fear. Put it in the folder you keep the work in, and anything running in that folder will pick it up. If you’re working through Claude Cowork with a folder on your computer, that’s the folder you selected.
Write down what you keep re-explaining. Nothing else.
The file convention belongs to developer tools. If you use ChatGPT or Gemini in a browser, there’s no file, and looking for one is a common source of confusion. The equivalent exists, it just lives in a settings box.
| Tool | What it’s called | Worth knowing |
|---|---|---|
| Claude Code | CLAUDE.md, a file in the folder | Target under 200 lines. Files at every level are concatenated, not overridden [1] |
| ChatGPT | Custom instructions, plus per-project instructions | 1,500 characters on Free and Go plans, 5,000 on Plus, Pro, Business, Enterprise and Education. Project instructions override the global ones [3] |
| Gemini | Instructions for Gemini, under Personal Intelligence | Personal Google accounts only. Not available in work, school or supervised accounts, and not applied inside Gems [4] |
| GitHub Copilot | .github/copilot-instructions.md | Also reads AGENTS.md, and a single CLAUDE.md or GEMINI.md in the repository root [5] |
From each vendor’s own documentation, checked 29 August 2026. The character limits and account restrictions are the details most often missed.
Three practical differences worth knowing, because they change what you should write:
And a decision rule for the two most common ones, since this is really the question underneath. Reach for a project or folder-level instruction file when the context belongs to a body of work: a client, a campaign, a report you rebuild monthly. Reach for global instructions when it’s about you and doesn’t change: how you like to be written to, your role, the formats you always want. Putting the first kind in the second place is what produces an instruction set that’s mostly irrelevant to whatever you’re doing today, and that’s the version people abandon.
Worth one line on AGENTS.md, since it keeps coming up. It’s an open format, stewarded by the Agentic AI Foundation under the Linux Foundation, and supported by a long list of tools. [5] Claude Code doesn’t read it. Anthropic’s documented answer is to create a CLAUDE.md that imports your AGENTS.md, so both tools read one set of instructions.
The realistic lifecycle is that you write a good file in an afternoon, it works, you add to it whenever something goes wrong, and eight months later it’s four hundred lines and performing worse than the first version. Nothing broke. It just accumulated.
Anthropic gives four triggers for adding a line, and they’re stricter than what most people do: [2]
Each one has the same shape: evidence that the absence of the instruction caused a real problem. Adding a line because it seems like a good idea is how you get to four hundred.
The diagnostic that goes with it is the most useful thing in Anthropic’s guidance and it’s genuinely counterintuitive: “If Claude keeps doing something you don’t want despite having a rule against it, the file is probably too long and the rule is getting lost.” The instinct when a rule is being ignored is to restate it more forcefully, and the move that actually works is usually to delete four other things.
A monthly maintenance pass built from Anthropic’s stated criteria of size, structure and specificity. [1] [2]
When a rule stops working, cut four others before rewriting it.
There’s a useful relationship between this and a shared prompt library, if your team has one. The instructions file holds what’s always true. The library holds specific requests you make repeatedly. Mixing them produces a file full of half-prompts that only apply on Thursdays, which is why keeping the library separate is worth the small overhead.
To start: open a plain text file, call it CLAUDE.md, and write down the three things you explained to an AI this week that you’d already explained last week. Three lines. That file will be more useful tomorrow than anything else you could spend the next hour on, and you can grow it from evidence rather than from imagination.
A plain markdown file that Claude reads at the start of every session in the folder where it sits. You write it yourself in ordinary text, and it holds the context you’d otherwise re-explain: who the work is for, what your internal terms mean, house style, and things you never want done. Anthropic’s documentation is specific about what it isn’t, and this gets misreported constantly: the content is delivered as a user message after the system prompt rather than as part of it, so Claude reads it and tries to follow it without any guarantee of strict compliance. That has a practical consequence. Vague instructions produce vague adherence, and two rules that contradict each other mean Claude may pick one arbitrarily rather than resolving the conflict.
No, and this is the most common misunderstanding about it. MEMORY.md is a real file in Anthropic’s documentation, but Claude writes it, not you. Claude Code has an auto memory feature, on by default, where it saves notes about what it has learned working with you into a memory folder, and MEMORY.md is the index of that folder. The first 200 lines or 25KB load at the start of each conversation. It’s machine-local and doesn’t sync across computers. Plenty of articles recommend hand-authoring a MEMORY.md as a long-term brain for your AI, and that’s a community practice rather than a vendor convention. If you write one and drop it in a folder, nothing is looking for it there. The file you want for your own instructions is CLAUDE.md.
Anthropic targets under 200 lines and states that longer files consume more context and reduce adherence. The per-line test they give is the practical version: ask whether removing the line would cause Claude to make a mistake, and if not, cut it. The counterintuitive part is what to do when an instruction is being ignored. The instinct is to restate it more forcefully or add emphasis, and Anthropic’s own diagnosis is usually the opposite, that the file has grown too long and the rule is getting lost in the noise. Emphasis has the same property: if you mark many lines as important, none of them stands out. Most files that stop working stopped because they grew, not because they were unclear.
The underlying idea works everywhere; the file does not. Files are a developer-tool convention. In ChatGPT the equivalent is custom instructions, capped at 1,500 characters on Free and Go plans and 5,000 on Plus, Pro, Business, Enterprise and Education, plus per-project instructions that override the global ones rather than adding to them. In Gemini it’s Instructions for Gemini under Personal Intelligence, which is documented as unavailable on work, school and supervised Google accounts and not applied inside Gems. GitHub Copilot does use files and will read a CLAUDE.md in the repository root as well as its own. The decision rule that matters: put things about you in global settings, and things about a body of work in the project or folder level.
The things you keep re-explaining, and nothing else. In practice that’s five short sections: who the audience is with real specificity, what your internal shorthand means, style rules that differ from the obvious default, things to always do, and things to never do. The never section is usually the most valuable and the most neglected, because it’s the only part that reduces risk rather than improving quality; lines like never invent a customer quote or never state a figure I haven’t given you earn their place quickly. Leave out anything the model can read from the files you’ve given it, anything that changes weekly and will go stale, and any general advice about doing good work. A useful file is often twenty-five lines.
Every technical claim here comes from vendor documentation rather than from commentary, all read on 29 August 2026: Anthropic’s memory and best-practices pages, OpenAI’s help centre articles on custom instructions and projects, Google’s Gemini support pages, GitHub’s Copilot customisation docs, and the agents.md project site. Two notes on sourcing. Anthropic’s documentation has moved: the older docs.claude.com path for the memory page now redirects, and the widely quoted April 2025 Claude Code Best Practices engineering blog post no longer exists as a blog post, so anything citing that version is citing a superseded document. Canonical URLs are used below. Second, and more substantively, the claim that MEMORY.md is a file users should author appears across a large number of well-written articles and is not supported by any vendor documentation we could find; the only official MEMORY.md is the index Claude Code generates for its own memory directory. Correcting that is most of why this piece exists. Three things could not be verified from official documentation and so are not stated here: Google’s legacy Saved info naming, which was only reachable as a search snippet; the details of Anthropic’s API memory tool, same reason; and the frequently repeated claim that GitHub caps custom instructions at two pages, which appears in GitHub’s docs only inside a copy-paste prompt template and not as a documented platform limit.
Weekly tips. Real examples. Practical help for busy professionals.
We care about your data, check out our privacy policy.