Properties5
| Type | Article |
| Author | Kyle Mistele |
| Date | Nov 25, 2025 |
| URL | https://www.humanlayer.dev/blog/writing-a-good-claude-md |
| Note created | Nov 25, 2025 |
At a high level, this means it should cover: • WHAT: tell Claude about the tech, your stack, the project structure. Give Claude a map of the codebase. This is especially important in monorepos! Tell Claude what the apps are, what the shared packages are, and what everything is for so that it knows where to look for things • WHY: tell Claude the purpose of the project and what everything is doing in the repository. What are the purpose and function of the different parts of the project? • HOW: tell Claude how it should work on the project. For example, do you use
buninstead ofnode? You want to include all the information it needs to actually do meaningful work on the project. How can Claude verify Claude’s changes? How can it run tests, typechecks, and compilation steps?
Claude will ignore the contents of your
CLAUDE.mdif it decides that it is not relevant to its current task. The more information you have in the file that’s not universally applicable to the tasks you have it working on, the more likely it is that Claude will ignore your instructions in the file.
LLMs bias towards instructions that are on the peripheries of the prompt: at the very beginning (the Claude Code system message and
CLAUDE.md), and at the very end (the most-recent user messages)
As instruction count increases, instruction-following quality decreases uniformly. This means that as you give the LLM more instructions, it doesn’t simply ignore the newer (“further down in the file”) instructions - it begins to ignore all of them uniformly
Since
CLAUDE.mdgoes into every single session, you should ensure that its contents are as universally applicable as possible.
Length-wise, the less is more principle applies as well. While Anthropic does not have an official recommendation on how long your
CLAUDE.mdfile should be, general consensus is that < 300 lines is best, and shorter is even better.
Instead of including all your different instructions about building your project, running tests, code conventions, or other important context in your
CLAUDE.mdfile, we recommend keeping task-specific instructions in separate markdown files with self-descriptive names somewhere in your project.
Prefer pointers to copies. Don’t include code snippets in these files if possible - they will become out-of-date quickly. Instead, include
file:linereferences to point Claude to the authoritative context.
LLMs are in-context learners! If your code follows a certain set of style guidelines or patterns, you should find that armed with a few searches of your codebase (or a good research document!) your agent should tend to follow existing code patterns and conventions without being told to.