> 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

Claude.md files can get pretty long, and many times Claude Code just stops following a lot of the directions specified in the file

A friend of mine tells Claude to always address him as “Mr Tinkleberry”, he says he can tell Claude is not paying attention to the instructions on Claude.md, when Claude stops calling him “Mr Tinkleberry” consistently

> We recommend keeping task-specific instructions in separate markdown files with self-descriptive names somewhere in your project. Then, in your CLAUDE.md file, you can include a list of these files with a brief description of each, and instruct Claude to decide which (if any) are relevant and to read them before it starts working.

I've been doing this since the early days of agentic coding though I've always personally referred to it as the Table-of-Contents approach to keep the context window relatively streamlined. Here's a snippet of my CLAUDE.md file that demonstrates this approach:

  # Documentation References

  - When adding CSS, refer to: docs/ADDING_CSS.md
  - When adding assets, refer to: docs/ADDING_ASSETS.md
  - When working with user data, refer to: docs/STORAGE_MANAGER.md

https://gist.github.com/scpedicini/179626cfb022452bb39eff10b...

I have found that more context comments and info damage quality on hard problems.

I actually for a long time now have two views for my code.

1. The raw code with no empty space or comments. 2. Code with comments

I never give the second to my LLM. The more context you give the lower it's upper end of quality becomes. This is just a habit I've picked up using LLMs every day hours a day since gpt3.5 it allows me to reach farther into extreme complexity.

I suppose I don't know what most people are using LLMs for but the higher complexity your work entails the less noise you should inject into it. It's tempting to add massive amounts of xontext but I've routinely found that fails on the higher levels of coding complexity and uniqueness. It was more apparent in earlier models newer ones will handle tons of context you just won't be able to get those upper ends of quality.

Compute to informatio ratio is all that matters. Compute is capped.

It is called documenting your code!

Just write what this file is supposed to do in a clear concise way. It acts as a prompt, it provides much needed context specific to the file and it is used only when necessary.

Another tip is to add README.md files where possible and where it helps. What is this folder for? Nobody knows! Write a README.md file. It is not a rocket science.

What people often forget about LLMs is that they are largely trained on public information which means that nothing new needs to be invented.

You don't have to "prompt it just the right way".

What you have to do is to use the same old good best practices.

About 12 to 6 months ago this was not the case (with or without .md files), I was getting mainly subpar result, so I’m assuming that the models have improved a lot.

Basically, I found that they not make that much of a difference, the model is either good enough or not…

I know (or at least I suppose) that these markdown files could bring some marginal improvements, but at this point, I don’t really care.

I assume this is an unpopular take because I see so many people treat these files as if they were black magic or silver bullet that 100x their already 1000x productivity.

Why should we do this when anthropic specifically recommends creating multiple CLAUDE.md files in various directories where the information is specific and pertinent? It seems to me that anthropic has designed claude to look for claude.md for guidance, and randomly named markdown files may or may not stand out to it as it searches the directory.

You can place CLAUDE.md files in several locations:

> The root of your repo, or wherever you run claude from (the most common usage). Name it CLAUDE.md and check it into git so that you can share it across sessions and with your team (recommended), or name it CLAUDE.local.md and .gitignore it Any parent of the directory where you run claude. This is most useful for monorepos, where you might run claude from root/foo, and have CLAUDE.md files in both root/CLAUDE.md and root/foo/CLAUDE.md. Both of these will be pulled into context automatically Any child of the directory where you run claude. This is the inverse of the above, and in this case, Claude will pull in CLAUDE.md files on demand when you work with files in child directories Your home folder (~/.claude/CLAUDE.md), which applies it to all your claude sessions

https://www.anthropic.com/engineering/claude-code-best-pract...

Have we really reached the low point that we need tutorials on how to coerce a LLM into doing what we want instead of just....writing the god damn code?

Some explicit things I found helpful: Have the agent address you as something specific! This way you know if the agent is paying attention to your detailed instructions.

Rationality, as in the stuff practiced on early Less Wrong, gives a great language for constraining the agent, and since it's read The Sequences and everything else you can include pointers and the more you do the more it will nudge it into that mode of thought.

The explicit "This is what I'm doing, this is what I expect" pattern has been hugely useful for both me monitoring it/coming back to see what it did, and it itself. It makes it more likely to recover when it goes down a bad path.

The system reminder this article mentions is definitely there but I have not noticed it messing much with adherence. I wish there were some sort of power user mode to turn it off though!

Also, this is probably too long! But I have been experimenting and iterating for a while, and this is what is working best currently. Not that I've been able to hold any other part constant -- Opus 4.5 really is remarkable.

[0]: https://gist.github.com/ctoth/d8e629209ff1d9748185b9830fa4e7...

You can easily test this by adding some mandatory instruction into the file. E.g. "Any new method you write must have less than 50 lines or code." Then use Claude for ten minutes and watch it blow through this limit again and again.

I use CC and Codex extensively and I constantly am resetting my context and manually pasting my custom instructions in again and again, because these models DO NOT remember or pay attention to Claude.md or Agents.md etc.

Should do this for human developers too. Can't count the number of times I've been thrown onto a project and had to spend a significant amount of time opening and skimming files just to answer simple questions that should be answered in high-level docs like this.

Doesn't that mean that Claude Code's system prompt exhausts that budget before you even get to CLAUDE.md and the user prompt?

Edit: They say Claude Code's system prompt has 50. I might have misjudged then. It seemed pretty verbose to me!

The part about smaller models attending to fewer instructions is interesting too, since most of what was added doesn't seem necessary for the big models. I thought they added them so Haiku could handle the job as well, despite a relative lack of common sense.

Write readmes for humans, not LLMs. That's where the ball is going.

Actually having official guidelines in their docs would be a good entrypoint, even though I guess we have this which is the closest available from anything official for now: https://www.claude.com/blog/using-claude-md-files

One interesting thing I also noticed and used recently is that Claude Code ships with a @agent-claude-code-guide. I've used it to review and update my dev workflow / CLAUDE.md file but I've got mixed feelings on the discussion with the subagent.

This way, it's got more of a chance in generating something that I wanted, rather than running off on it's own.

Why not just to show one?

<system-reminder> 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. </system-reminder>

Perhaps a small proxy between Claude code and the API to enforce following CLAUDE.md may improve things… I may try this

What I find most interesting is how a hierarchical / recursive context construct begins to emerge. The authors' note of "root" claude.md as well as the opening comments on LLMs being stateless ring to me like a bell. I think soon we will start seeing stateful LLMs, via clever manipulation of scope and context. Something akin to memory, as we humans perceive it.

If you're using VSCode, that is automatically added to context (and I think in Zed that happens as well, although I can't verify right now).

Is it a good one?

Is this intentional? Is AoC designed as an elite challenge, or is the journey more important than finishing?

But as others are saying this is just basic documentation that should be done anyway.

Read your instructions from Agents.md

OMG this finally makes sense.

Is there any way to turn off this behavior?

Or better yet is there a way to filter the context that is being sent?

This is a news for me. And at the same time it isn’t. Without the knowledge of how the models actually work, most of the prompting is guesstimate at best. You have no control over models via prompts.

I would love to see it extended to show Codex, which to my mind is by far the best at rule-following. (I'd also be curious to see how Gemini 3 performs.)

I used to instruct about coding style (prefer functions, avoid classes, use structs for complex params and returns, avoid member functions unless needed by shared state, avoid superfluous comments, avoid silly utf8 glyphs, AoS vs SoA, dry, etc)

I removed all my instructions and it basically never violates those points.

I have a full system of agents, hooks, skills, and commands, and it all works for me quite well.

I believe is massive context, but targetted context. It has to be valuable, and important.

My agents are large. My skills are large. Etc etc.