Writing a good CLAUDE.md | HumanLayer Blog

Note: This post is also applicable to AGENTS.mdequivalent to open-source CLAUDE.md For agents and harnesses like OpenCode, Jade, Cursor and Codex.

, Principle: LLMs are (mostly) stateless

LLMs are stateless functions. By the time they are used for inference, their weights are stable, so they do not learn over time. The only thing the model knows about your codebase is the tokens you put in it.

Similarly, coding agent harnesses like Cloud Code typically require you to explicitly manage the agents’ memory. CLAUDE.md (Or AGENTS.md) is the only file that goes by default every conversation You have it with the agent.

This has three important implications:

, CLAUDE.md Onboards the cloud to your codebase

Since the cloud doesn’t know anything about your codebase at the beginning of each session, you should use CLAUDE.md To incorporate the cloud into your codebase. At a high level, this means it should include:

But how you do it is important! Don’t try to stuff every command that Claude might possibly need to run into your CLAUDE.md File – You will get sub-optimal results.

, The cloud often ignores CLAUDE.md

No matter which model you’re using, you may find that the cloud often ignores you CLAUDE.md Contents of the file.

You can check this yourself by setting up a logging proxy using the Cloudflare CLI and Anthropic API ANTHROPIC_BASE_URLCloud Code injects the following system reminders with you CLAUDE.md File user message to agent:

      IMPORTANT: this context may or may not be relevant to your tasks. 
      You should not respond to this context unless it is highly relevant to your task.

As a result, the cloud will ignore your content CLAUDE.md If he decides it is not relevant to his current work. The file doesn’t contain as much information as you have. universally applicable The more tasks it is working on, the more likely it is that the cloud will ignore your instructions in the file.
Why did Anthropic add this? It’s hard to say for sure, but we can guess a little. most of CLAUDE.md The files we get consist of a set of instructions in the file are not doing Widely applicable. Many users saw the file as a way to add a “hotfix” to behavior they didn’t like with lots of instructions that weren’t necessarily widely applicable.
We can only assume that the Cloud Code team found that harnesses actually produced better results than telling the cloud to ignore bad instructions.
, a good build CLAUDE.md file
The following section provides several recommendations about writing a good article. CLAUDE.md File references following engineering best practices.
Your mileage may vary. Not all of these rules are necessarily optimal for every setup. Like anything else, feel free to break the rules once in a while…


You understand when and why it’s okay to break them
you have a good reason for doing so


, less is more (instructions)
It can be tempting to try and fill in every single command the cloud could possibly need to run, while also including your code standards and style guidelines. CLAUDE.md, We recommend against it.
Although this topic has not been examined in an incredibly rigorous manner, some research has been done that indicates the following:


LLMs with marginal thinking can follow ~150-200 instructions with reasonable consistency. Small models can pay attention to fewer instructions than larger models, and non-thinking models can pay attention to fewer instructions than thinking models.
Small models wear out very fastSpecifically, as the number of instructions increases, smaller models exhibit a potential decline in instruction-following performance, while larger marginal thinking models exhibit a linear decline (see below), For this reason, we recommend not using small models for multi-step tasks or complex implementation plans,
LLMs have a bias toward instructions that are on the periphery of the prompt: At the very beginning (cloud code system message and CLAUDE.md), and at the end (the most recent user message)
As the number of instructions increases, the quality of instruction-following decreases correspondingly.This means that as you give more instructions to LLM, it doesn’t just ignore the new (“further in the file”) instructions – it starts over, ignore them all equally



Our analysis of cloud code harnesses indicates that Cloud Code’s system prompt contains ~50 individual instructionsDepending on the model you’re using, that’s about a third of the instructions your agent can already reliably follow – and that’s before rules, plugins, skills, or user messages,
This means that your CLAUDE.md The file should contain as few instructions as possible – ideally only those that apply universally to your task.
, CLAUDE.md File Length and Applicability
all else being equal, An LLM will perform better on a task when his or her context window is filled with focused, relevant context. It includes examples, related files, tool calls, and tool results, compared to when its context window contains a lot of irrelevant context.
since CLAUDE.md goes into every sessionYou should ensure that its content is as universally applicable as possible.
For example, avoid including instructions about (for example) how to structure a new database schema – it won’t make a difference and will distract from the model while you’re working on something else unrelated!
According to length, less is more The principle also applies. While Anthropic has no official recommendations on how long to get your period CLAUDE.md The file should be, the general consensus is that <300 lines is best, and shorter lines are even better.
On HumanLayer, our root CLAUDE.md the file is less than sixty lines,
, progressive disclosure
jotting down CLAUDE.md Creating a file that covers everything you need the cloud to know can be challenging, especially in larger projects.
To address this, we can take advantage of the principle of progressive disclosure To ensure that the cloud only sees task- or project-specific instructions when it needs them.
Instead of including all your different instructions about building your project, running tests, code conventions, or other important context. CLAUDE.md In the file, we recommend keeping task-specific instructions separate markdown files With self-descriptive names somewhere in your project.
For example:
agent_docs/
  |- building_the_project.md
  |- running_tests.md 
  |- code_conventions.md
  |- service_architecture.md
  |- database_schema.md
  |- service_communication_patterns.md
Then, in your CLAUDE.md In the file, you can include a list of these files with a brief description of each, and instruct the cloud to decide which (if any) are relevant and read them before starting work. Or, ask the cloud to present the files it wants to read to you for approval before reading.
Prefer pointers over copiesIf possible don’t include code snippets in these files – they will quickly become out of date, Instead, include file:line References pointing to the official reference to the cloud.
Conceptually, this is similar to the way Cloud Skills works, although the skills are more focused on the use of the tool rather than instructions.
, Cloud is (not) an expensive linter.
One of the most common things we see people keeping in their CLAUDE.md The file is a code style guideline. Never send LLM to do linter workLLM are comparatively expensive and unbelievably Slower than traditional linters and formatter. we think you should Always use deterministic tools whenever possible,
Code style guidelines will essentially add a bunch of instructions and mostly irrelevant code snippets to your context window, which will degrade the performance and instruction-following of your LLM and kill your context window.
LLMs are context-based learnersIf your code follows a certain set of style guidelines or patterns, you should find that your agent, armed with a few searches of your codebase (or a good research document,), follows existing code patterns and conventions without being told.
If you think about this very seriously, you can even consider installing Cloud Code Stop Hook that runs your formatter and linter and presents it to the cloud to fix errors. Don’t let the cloud discover formatting problems on its own.
bonus points: Use a linter that can automatically fix problems (we like Biome), and carefully adjust your rules about what can safely be automatically fixed for maximum (safe) coverage.
You can also create a slash command that includes your code guidelines and places it in version control or in your git statusor similar. This way, you can handle implementation and formatting separately. As a result you will see better results with both,
, do not use /init or generate your own CLAUDE.md
Other harnesses with Cloud Code and OpenCode come with ways to auto-generate your CLAUDE.md file (or AGENTS.md,
Because CLAUDE.md goes into every session With cloud code, it’s one of the highest leverage point of the harness – For better or worse, it depends on how you use it.
A bad line of code is a bad line of code. A poor line of execution plan has the potential to create a Very Bad lines of code. One bad line of research that misunderstands how the system works is likely to result in a lot of bad lines in the plan, and so and many more Resulting in bad lines of code.
But CLAUDE.md file affects Every step of your workflow And every single artwork it produces. As a result, we believe you should spend some time thinking very carefully about each line involved:

, in conclusion


CLAUDE.md    The cloud is meant to be incorporated into your codebase. This should define your project Why, WhatAnd How,
less is more (instructions)Although you should not omit essential instructions, you should include as few instructions as possible in the file,
keep your content CLAUDE.md concise and universally applicable,
Use progressive disclosure – Don’t tell Claude all the information you could possibly want to tell him. tell me instead how to find Important information so he can find it and use it, but only when he needs to to keep your reference window or instruction number from bloating.
Cloud is not a linter. Use linters and code formatter, and use other features like hooks and slash commands as needed.
CLAUDE.md    The highest leverage point of the harness isSo avoid generating it automatically. You should prepare its ingredients carefully for best results.