How to Write a CLAUDE.md File for a Content Project

Claude Code reads one file before it does anything else in a project: CLAUDE.md. On a content project, that file decides whether every session starts out knowing the voice, the sources and the claims you never make, or whether you spend the first ten minutes of each one explaining them again. This guide covers how to write a CLAUDE.md file for a content project: what belongs in it, what to leave out, how long it should be and what goes first, how to word a rule so it is followed, where the rules that cannot bend should live instead, how to split the file as the project grows, and how to test that the result works.

How to write a CLAUDE.md file: start from what you keep re-explaining

A CLAUDE.md file is a plain text file at the root of a project that Claude Code reads at the start of every session, and the way to write one is to collect the things you would otherwise have to explain each time. Anthropic's guide to how Claude remembers your project puts it in one line: "Treat CLAUDE.md as the place you write down what you'd otherwise re-explain." It suggests adding to the file when the same mistake happens twice, or when a new teammate would need the same context.

On a content project, the things people re-explain are predictable. Which voice to write in and which phrases never to use. Where the facts come from and which claims are off limits. Which folder holds the drafts and which holds the published pieces. What has to happen before a draft counts as finished. Every one of those is a sentence that would otherwise be typed into the chat again tomorrow.

That makes the file the cheapest piece of a content system to build and one of the most consequential. Our guide to using Claude Code for content automation covers what the tool is good for; this post is about the single file that shapes how it behaves once a content project is set up. A session that reads a good file starts where the last one finished. A session that reads a poor one, or none, starts from nothing. The rest of what we have written about the tool is collected in our Claude Code guides.

What belongs in a CLAUDE.md for content

A CLAUDE.md for content should hold the few facts and rules that apply to almost every task in the project: the voice in brief, where the source material lives, what may never be claimed, where each kind of file goes, and the command or check that decides when a piece is done. Anything that applies to every session belongs here. Anything that applies to one task belongs somewhere that loads only for that task.

The facts themselves usually belong in their own files, with CLAUDE.md pointing to them. Our guide to writing a knowledge base for AI content, including a do-not-say list covers how to structure those files, and the guide to the single folder a content system reads shows how voice, strategy and sources can sit side by side. CLAUDE.md is the short page at the front that tells Claude where to look.

The memory documentation gives a useful example of the level of detail it means. It recommends a line such as "API handlers live in src/api/handlers/" in place of "Keep files organized". The content version is the same move: "Drafts go in drafts/, named by date and slug" rather than "Keep drafts tidy".

What to leave out of the file

Leave out anything Claude can work out by reading the project, anything that matters for only one kind of task, and anything that will be out of date next month. What is left after those three cuts is usually short, and short is the point.

Anthropic's best practices for Claude Code explain why: the file loads into every session, "which means every line in it takes a little of Claude's attention on every task, whether it's relevant or not." A paragraph describing the folder structure Claude can see for itself is not free. It costs a little attention on every task, including the ones it has nothing to do with.

The guidance for writing skills makes the same point more bluntly. Anthropic's skill authoring best practices say: "Only add context Claude doesn’t already have." They also warn against information that will become outdated, which on a content project means campaign dates, this month's priorities and anything that names a season. Those belong in the brief for that piece of work, not in the file every session reads.

Do not paste the whole brand guide in either. A forty-page guide written for people is not an instruction file; it is source material. Keep the five rules that change most drafts in CLAUDE.md and put the rest where it can be read when needed, which is the same principle our guide to documenting a content automation system applies to every file the model reads.

How long it should be, and what goes first

Keep a CLAUDE.md file well under two hundred lines, and put the rules that matter most near the top. Anthropic's memory guidance says to "target under 200 lines per CLAUDE.md file" and adds that "Longer files consume more context and reduce adherence." A file that has grown past that point is not more thorough; it is less likely to be followed.

The reason is the same one that applies to any long prompt. Anthropic's essay on effective context engineering describes the goal as finding "the smallest set of high-signal tokens that maximize the likelihood of your desired outcome", and calls context "a finite resource with diminishing marginal returns." Every rule you add makes each of the others slightly less likely to be noticed.

Research points the same way. The arXiv paper known as Lost in the Middle found that model performance "is often highest when relevant information occurs at the beginning or end of the input context" and drops when the answer is buried in the middle. A later arXiv benchmark asking how many instructions models can follow at once was built to measure how instruction-following "degrades as instruction density increases", and found that it does. Both findings argue for a short file with the important rules first.

In practice, order the file by consequence. The claims that must never be made go near the top, then the voice rules that change most drafts, then where things live, then the commands. Group related rules under short headings, because the memory guidance notes that organised sections are easier to follow than dense paragraphs.

Claude Code instructions that get followed: specific, consistent, explained

A rule gets followed when it is specific enough to act on, worded the same way every time it appears, and, where it is not obvious, accompanied by its reason. "Write well" is not an instruction. "Open with the reader's problem in the first sentence" is.

Consistency matters more than most people expect. The skill authoring guide advises choosing one term and using it throughout, because "Consistency helps Claude parse and follow instructions." If the file says "draft" in one place, "post" in another and "piece" in a third, it has described three things. The memory guidance adds the sharper warning: "if two instructions contradict each other, Claude may pick one arbitrarily."

Decide which rules are absolute and which are preferences, and say which is which. Internet standards settled this vocabulary long ago with words like MUST and SHOULD, and a later note, RFC 8174 on uppercase and lowercase key words, clarifies that "only UPPERCASE usage of the key words" carries the special meaning. A CLAUDE.md does not need that formality, but it does need the distinction: "Never state a price" and "Prefer shorter paragraphs" are different kinds of rule, and the file should not word them the same way.

Add the reason to any rule that might look arbitrary. "Never name a competitor, because the business has agreed not to" lets Claude handle the cases the rule did not foresee, such as a quotation that happens to include a competitor's name. The same habits that make a good prompt make a good instruction file.

Rules that cannot bend belong somewhere else

CLAUDE.md is for guidance, so any rule that must hold every single time should be enforced by something else: a check that fails, a hook that blocks, or a permission that refuses. Writing it in capitals does not change what kind of rule it is.

Anthropic is direct about this. The memory documentation says Claude treats these files "as context, not enforced configuration." The best practices page says "CLAUDE.md is for guidelines, and Claude is allowed to decide a guideline doesn't apply", and warns that "If Claude keeps ignoring a line that is in CLAUDE.md, adding IMPORTANT probably won't fix it." Its advice is to move a rule that cannot have exceptions into configuration the tool applies itself.

For a content project, the candidates are easy to find. A banned phrase, a claim that must never appear, a required source for every number, a folder that must not be edited: each of those can be checked by a script that fails the draft, and our guide to automated content checks and how to prove one can fail covers how to write them. The line in CLAUDE.md then becomes a pointer: "Run the checks before calling a draft finished." The file tells Claude what to do, and the check makes sure it was done.

This division also keeps the file short. Every rule that moves into a check is one less line competing for attention, and one less place where a person has to hope the instruction was noticed.

Splitting the file: folders, imports, skills and AGENTS.md

When a content project grows, split the instructions by where and when they apply instead of letting one file grow. Claude Code offers several ways to do this, and each solves a different problem.

A project can have more than one CLAUDE.md. A file in a subfolder applies when Claude works in that folder, so the rules for the newsletter can live beside the newsletter rather than in the root file. The memory documentation also describes imports, written as @ followed by a path, which pull another file in, though it notes that imports "help you organize a long file but don't reduce its context cost". Personal preferences that should not be shared go in a separate local file kept out of version control.

For a procedure that only matters for one kind of task, such as the steps to turn a webinar into a series of posts, a skill is usually better than any of these, because it loads only when the task calls for it. The same skill authoring guide covers how to write one. Our guide to splitting model steps so each does one job makes the same argument about workflows: one instruction per job, loaded where the job happens.

Other tools have their own version of the file. OpenAI's documentation on custom instructions with AGENTS.md says "Codex reads AGENTS.md files before doing any work", and Claude Code can read an existing AGENTS.md in place of CLAUDE.md. Whichever name you use, write it in plain Markdown, the format CommonMark specifies, so any person or tool can open it. Our ChatGPT guides cover how that tool fits a content system.

Test the file with a fresh session

Test a CLAUDE.md the way you would test a brief for a new writer: start a fresh session, give it a typical task you already know the right answer to, and see what comes back without adding any explanation in the chat. Every correction you find yourself typing is a line the file is missing or a line it has worded badly.

Use three or four tasks that cover the project's real work: a short post, a longer article, an edit to an existing piece, and one task designed to tempt a banned claim. Anthropic's prompt engineering overview starts from the same place, assuming you already have a clear definition of success for the task and some way to test against it before you improve the wording.

Claude Code also helps maintain the file. The memory documentation describes a command, /init, that generates a starting CLAUDE.md from the project, and an audit that looks for instructions that are outdated, refer to files that no longer exist, or contradict each other. Neither replaces reading the file yourself, but both catch drift that is easy to miss when the file has been edited by several people over several months.

Repeat the test whenever the file changes and whenever the model behind the tool changes. A rule that was followed last month and is ignored this month is telling you something about its wording or its position in the file.

What the file can hold, and what a person still decides

The file can hold any decision that has already been made: the voice, the sources, the claims to avoid, the order of work. It cannot make a decision that has not been made yet, and it should not pretend to. When a draft raises a question the file does not answer, a person answers it, and if the answer will come up again, it becomes a new line.

Three things stay with people. Deciding what the business believes and will say in public is a judgement no instruction file can make on anyone's behalf. Approving a piece before it goes out stays with whoever is accountable for it, whatever the file says about checks. And deciding when a rule in the file is wrong, because the business changed or the audience did, is a decision only the people who own the content can make.

A useful habit is to note, beside any rule that came from a specific incident, who decided it and when. That turns the file from a list of commands into a record of decisions someone can revisit, which is exactly what a person needs when deciding whether a rule still applies.

A worked example: a property manager's content project

This example is illustrative, not a client. Picture a property management company that publishes a monthly guide for landlords and a few short posts drawn from it. Their first CLAUDE.md was their brand guide pasted in whole, with a few lines added at the end about folders. Drafts came back in roughly the right voice, but two kept promising faster lettings than the company would ever commit to, and the line forbidding that was near the bottom of a very long file.

They rewrote it from what they kept correcting. The new file opened with what the project was and who it served, then the claims never to make, each with its reason: no promised yields, no let dates, nothing that reads as legal advice. Then five voice rules, then where the sources, drafts and published pieces lived, then one line saying to run the checks before calling any draft finished. The brand guide moved into the sources folder, where Claude could read it when a task needed it.

The banned claims also became a check, so a draft that promised a let date failed before anyone read it. The step-by-step process for turning the monthly guide into posts became a skill, loaded only for that task. And each month's priorities moved out of the file into the brief for that month, so nothing in CLAUDE.md went stale when the season changed.

They tested the result with a fresh session and four tasks, including one that asked for a post about how quickly a property could be let. The draft explained what affects letting times without promising one. The file the session read was a fraction of its earlier length, and the corrections the team typed each week dropped to the ones that reflected genuinely new decisions.

What a good instruction file honestly costs

The first version costs an afternoon: collecting the corrections you keep making, writing them as specific lines, ordering them by consequence and testing with a fresh session. The ongoing cost is a few minutes whenever a new correction comes up twice, plus a periodic read to remove what no longer applies.

The larger cost is in what the file reveals. Writing down the claims never made and the voice rules that matter forces decisions that many teams have avoided, and some of those conversations take longer than the writing. That time is not wasted; it is the same work any content system needs, whichever tool runs it. If you would rather have it done as part of a build, that is what our content automation services cover, and the story of how we came to work this way is on our story as a content automation company.

The cost to avoid is the opposite mistake: a file that tries to hold everything. A long, thorough instruction file feels safe and performs worse. Keep it short, keep it current, and move everything else to where it is needed. If n8n or another tool runs the publishing side, keep its rules in that tool's own notes rather than in a file Claude reads on every task.

Frequently asked questions

What should a CLAUDE.md file include for a content project?

What the project is and who it serves, the claims never to make with their reasons, the few voice rules that change most drafts, where sources, drafts and published pieces live, and the check to run before a draft counts as finished. Facts and long guides belong in their own files, with CLAUDE.md pointing to them.

How long should a CLAUDE.md file be?

Well under two hundred lines. Anthropic's documentation recommends targeting under 200 lines per file, because longer files use more context and are followed less reliably. Move task-specific procedures into skills and per-folder files rather than letting the main file grow.

Why does Claude ignore a rule in CLAUDE.md?

Usually because the file is long enough that the rule gets lost, the rule contradicts another one, or it is worded vaguely. Adding capitals rarely helps. Shorten the file, move the rule near the top, word it specifically, and if it must hold every time, enforce it with a check or a hook instead.

What is the difference between CLAUDE.md and AGENTS.md?

They do the same job for different tools. Claude Code reads CLAUDE.md, and OpenAI's Codex reads AGENTS.md before doing any work. Claude Code can also read an existing AGENTS.md in place of CLAUDE.md, so a project can keep one file of instructions for both.

Should the brand guide go in CLAUDE.md?

No. Keep the handful of voice rules that change most drafts in CLAUDE.md and put the full guide in a sources folder that Claude reads when a task needs it. A long guide in the main file costs attention on every task and buries the rules that matter most.

How do you test a CLAUDE.md file?

Start a fresh session, give it three or four typical tasks you already know the right answer to, including one that tempts a banned claim, and add no explanation in the chat. Every correction you have to type is a missing or badly worded line. Repeat whenever the file or the model changes.

Where to start

Go back through the last week of sessions and list every correction or explanation you typed more than once. Turn each into one specific line, put the claims never to make at the top, and stop when the list runs out. Then open a fresh session, give it a task you know the answer to, and see what is still missing.

After that, move any rule that must hold every time into a check, and any long procedure into a skill. The thinking behind this way of working, and the frameworks that go with it, are collected in our knowledge hub, and our guide to content creation with Claude Code and Higgsfield shows a content project built this way end to end.

Keep reading

• Claude Code for content automation — what the tool is for, before you write its instructions.
• How to build a knowledge base for AI content — the files of facts CLAUDE.md should point to.
• Automated content checks — where the rules that cannot bend should be enforced.