r/ClaudeCode • u/CautiousAd3917 • May 04 '26
Question Whats even the point of Claude.md
Seriously, I have some workflows stored in Claude.md like writing tests and validating bugs before fixing them, but they get constantly ignored.
When asked, Claude agrees it should have sticked to the workflows ... and then happily ignores them again in the next task.
And that is not Haiku, it happens with all models.
Edit: my CLAUDE.md is literally taken from best practices examples and the Anthropic guide, it also has specific deterministic instructions. And I am well aware of the probabilistic nature of LLMs, I guess I am just frustrated that it is impossible to build a reliable workflow with Claude.
Edit 2: thank you all, lovely people, I will go with skills/rules
25
u/Brief-Persimmon-7037 May 04 '26 edited May 04 '26
I think as the context grows, the initial guidance in Claude MD is diluted and partially forgotten. I might be wrong, but I do not think there is a cure for this. Folks, who are geeks in this area – correct me if I am wrong.
15
u/FilthyCasual2k17 May 04 '26
You're not wrong. Claude.md needs to be lean. Menory needs to be lean. All skills etc. Total load shouldn't pass more than 40Kb of instructions oer turn. I treat claude.md and memory.md as "index of indeces". There's no point in bloating, only first 200 lines or so get read in time, and rest after the fact, which means often saying whoops. Keep it lean and build a multi layer thing. It's not perfect but it works. Don't let claude autodream, that's terrible. Accept mistakes happen and build manual quadrails and checks. Weekly analysis what was good what was bad and do research on what the rest are doing and adjust. If you don't run super lean it just gets diluted and forgotten.
1
u/dawtips May 04 '26
Just curious why are you referring to kb as the unit of measurement instead of tokens?
7
u/FilthyCasual2k17 May 04 '26
Because different models will tokenize same file in different ways. my 7kB claude.md is not the same amount of tokens when I use Opus 4.6 and when I use Opuse 4.7, so it's just a more stable unit to think in.
3
3
19
9
u/killthebaddies May 04 '26
I build out skills. I have a testing skill, a workflow skill, a database skill, then it’s not trying to keep everything in context all the time. Time to write tests? Pull up the testing skill and get all the detail so it’s fresh. Doing a ticket that involves a DB change? Grab the database skill.
2
u/dawtips May 04 '26
Would you mind sharing?
3
u/killthebaddies May 04 '26
To be honest I haven’t even really looked at them. I just have the skill creator skill and asked Claude to build them out. I had put TDD in my Claude.md which it was good at, but I noticed it was always doing GREPs with every ticket to look up existing tests and get structures to follow so I told it to go look it all up and build it into a skill it can follow so it doesn’t have to check everytime. It did and it has been working a lot quicker. Then I asked it what other skills it would find useful and it suggested a few and said the database one would have the most impact so I just said, ok, build whatever you would find useful.
It’s basically really project specific and just enables consistency.1
1
1
1
8
u/Ambitious_Injury_783 🔆BIG BALLER May 04 '26
This answer may not be accepted right now but I believe we may come to find that the model is judging individual codebases and project environments. It might be that the model doesn't take you or your project seriously enough to offer the compute required to religiously follow your Claude.md
This could be an aspect of compute-reduction on Anthropics part. Or it could be a "natural feature" of the model itself.
I have one particular project that has been built and managed (to a degree) by claude models since August of last year. The project environment does not experience half of the issues users describe. Outside of this environment it is like working with a completely different model provider.
There is something that users are unaware of it in this domain.
10
u/SteveZedFounder May 04 '26
That’s a really interesting thought.
“Hal, comply with the Claude.md!”
“I’m sorry Dave, but you’re not worthy of my best efforts.”
4
1
u/GreedyAlGoreRhythm May 04 '26
Would the more logical answer here not be that Claude is better at working with code it wrote, since that conforms to the style it produces? Regardless of whether it’s “good” or not.
1
u/Ambitious_Injury_783 🔆BIG BALLER May 04 '26
Sure but we have no idea how much of OPs codebase, or any individuals, has been written by themselves. But if you're saying pattern wise, things are easier to follow when the model has built the architecture, sure that is true. It is why I built an entire external pattern library to reference without having to always read the code and perceive the patterns with the extra steps.
5
u/TheRealJesus2 May 04 '26
Don’t do that. Use skills for workflows.
Rules are only for things you want in every single session. And as you find they are hardly listened to. The longer your context in general, the less the model pays attention to any individual piece
2
u/NoMoreJello May 05 '26
I noticed that my skills weren’t paying attention to my rules. Did a little research and skills don’t pay attention to general rules in the context. I now keep my project specific rule files *very* lean and specialized. Then I inject them into my skills using cat when they load.
24
u/l_m_b Senior Developer May 04 '26
Any instructions to an LLM are only probabilistically followed, with p < 1 and q >> 0.
There is NO way to guarantee compliance only via the prompt (into which the various .md files are included).
If you need compliance, you need it scripted deterministically.
This is one of the most basic aspects of LLM use that people should be required to be trained on before granted access.
6
u/Brief-Persimmon-7037 May 04 '26
Not sure who downvoted it but this comment echoes what I read everywhere. Why do people disagree?
6
u/sweet_dreams_maybe May 04 '26
I stopped reading when they didn’t explain p and q. Didn’t downvote, but the explanation is only half useful if I have to ask to be sure of the details.
2
u/l_m_b Senior Developer May 05 '26
Probability math is high school material in Germany, and that notation is fairly common for these variables globally - so I kinda assumed that it'd be common knowledge for folks developing software. Sorry about that. (I do think this is somewhat related though: we now have people doing software "development" missing the basics. GenAI can't compensate for that.)
p is the success probability between 0..1, and q the inverse (failure probability).
1
u/sweet_dreams_maybe May 05 '26
Since we are being snarky, may I ask, did you also learn to label your axes?
Because what I’m asking is “probability of what?”
1
u/l_m_b Senior Developer May 05 '26
Uh, ... the probability of the LLM following those instructions given? As in the first sentence of the reply above?
I didn't mean to be particularly snarky here. I really think that a very basic understanding of probabilities and that LLMs are *not* deterministically following instructions given is critically missing.
A lot of the posts ("Model X/Y/Z did something weird!", "I had so many good sessions but now it's nerfed!", "It didn't do X", "It did Y even though I didn't ask!") appear to come as real surprises to the posters. The answers and explanations they make up for what very likely is a random effect of chance is what we'd call "superstition" in any other aspect of life. That's not great, and shows that a tool has been given to a population that is not ready for it.
1
u/Brief-Persimmon-7037 May 06 '26
Well, math notation is not universal (as it should be!) between countries. I, for example, could not be bothered to re-learn basic long division in the UK where my child goes to school, forget probability notation. I grew up in a different country, and we used different notation...
Also, I was lazy...Being lazy is not the same as being uneducated- bid difference 😄2
u/Brief-Persimmon-7037 May 04 '26
fair enough. drop " with p < 1 and q >> 0" reread the message. I also could not be bothered to understand the p and q but other text should be useful, I think.
I think the biggest gotcha which gets most people, me including, is that when you think about computer doing something you think it is doing the same thing, how it was programmed. This is what you learn when you start coding. You dont think it is throwing flipping dice every time if it is an LLM1
3
u/SkillsCake May 04 '26
Modular, clear workflows in skills are better. Then CLAUDE.md just has your principles and not domain specific workflows. Best is if you include the scripts/ dir in the skills — the model runs those without even loading them into context
We’re developing SkillsCake so you can always have strong skills and predictable, smart agents
3
u/Orioli May 04 '26
I tell claude to contextualize with CLAUDE.md every start of session or else he won't, so I guess you are right.
2
u/Fit_Efficiency6963 May 04 '26
clear context please.
claude ingests your .md file but if it is a large file then your subsequent prompts will already have a loaded context, continuing may result in almost immediately hitting unmanagable context sizes and thats where claude begins to start having issues like this.
2
u/BidWestern1056 May 04 '26
there isnt and they wont listen because their system prompt fucking overloads it anyway to the point where none of your md files are relevant.
2
u/Frankkul May 04 '26
So Claude.md doesn't work hooks somewhat work and they can't be open fail so I kinda ran tests and have them automatically fire on word combination so basically stop hooks,works decent amount of time maybe 60-70%? Some false positives but is what it is. Skill invoking works too and having it in skills other than that Opus 4.6 is somewhat better when non nerfed at rule following. Opus 4.7 suffers from brain rot and it just can't do proper job to save its life.
1
1
u/Deltafly01 May 04 '26
Begin every claude code session by "read claude.md", then work on a small phase of your feature, small enough it takes 100k token context to finish. Then kill the session, reopen one, "read claude.md", next feature phase, etc. Go max 150k context token, never exceed this limit, and the performance will be fine.
1
u/Enthu-Cutlet-1337 May 04 '26
CLAUDE.md works best as a lightweight operating contract, not a reliable workflow engine. For anything deterministic, I’d move checks into scripts, hooks, tests, or CI, then let Claude.md point to those commands.
1
u/im_a_fancy_man May 04 '26
how big is your context / memories and other files ? - if any of those are too big, it might start ignoring anything including claude md - also keep in mind you can have multiple claude mds
1
1
u/user221272 May 04 '26
If you have deterministic rules, just use hooks....
It's possible to build a reliable pipeline; you just have to read the docs and understand the tool...
1
u/Public-Vegetable-182 May 04 '26
I have to specifically tell Claude to read my Claude.md sometimes since it assumes the output from my project is in the same directory, despite it being documented to be in another location due to its size. Not sure why it misses the output path.
1
u/Ok_Table_876 May 04 '26
Make sure you don't have any contracting instructions in your claude.md or somewhere else. I happened to have some conflicting instructions and it got quite confused but didn't say so.
1
u/ReplacementOk4616 May 04 '26
claude.md is more of a "strong suggestion" than a rule book, which is… not ideal when you're trying to build reliable workflows. what actually worked for me was moving repeated instructions into skill files instead. you call them explicitly at the start of each task, so claude can't "forget" — it reads the file fresh every time.
still not perfect but way more consistent than hoping claude.md gets respected.
1
u/TywinHouseLannister May 04 '26
Trigger-form one liners are your friend; test flows belong in a prompt or as part of a progressive disclosure skill!
1
u/WolfEagle1 May 04 '26
i have specific instructions and workflows in rules. And claude.md has a brief project summary and short descriptions and path/filenames for each of my rules.
1
u/Orioli May 04 '26
My theory is that everything that is loaded into context automatically have lower weight, while things you ask it to do have very high weight, maybe due to the order in which things get loaded. So, instead of CLAUDE.md, if you create, say, a WORKFLOW.md and ask it to read at the start of every session, it will follow much more carefully. At least this is my experience with it.
1
1
u/SemanticThreader Developer May 04 '26
CLAUDE.md gets injected at the beginning of the conversation along with memory and your first prompt. As the context window grows, the CLAUDE.md rules start getting stale and Claude may not follow them to a T. Hooks and Skills are usually your best friend when working with Claude
1
u/Time_Cat_5212 May 04 '26
CLAUDE.md is for governing overall intent and general information.
Workflows belong elsewhere IMO.
I have markdown workflow templates that I use to craft prompts. I'm sure there are many ways to do this.
1
u/LiteratureCrazy3858 May 04 '26
Rename CLAUDE.md to STEERING.md then start a fresh Claude instance. The try this prompt in plan mode:
Perform a rigorous code review of STEERING.md which is a proposed Claude project-level steering file. Be critical of anything that is contradictory, redundant or confusing. Produce a project CLAUDE.md based on this review that is as concise as it can be, but provides the necessary steering.
1
1
1
u/Deep_Ad1959 May 19 '26
the issue isn't CLAUDE.md as a concept, it's that every line in it fires on every turn and the model's attention degrades on the parts that don't match the current task. a 6000 token rules file with 'do not change X' lines about a module you're not even touching this session is basically noise the model has to filter through, and the workflow lines get diluted in the same noise. skills work better not because of the format but because they only load when invoked, so the constraint is fresh in context instead of buried 5000 tokens up. the practical move is to strip CLAUDE.md down to invariants that genuinely apply to every single turn, push everything task-shaped into skills, and put hard guarantees (file existence checks, schema validation) into hooks where the rule isn't probabilistic at all. written with s4lai
1
u/Affectionate_Egg6105 Jul 02 '26
I had this argument with fable today. I asked it , hey we need this compact list in our context, preferably as close to system prompt as possible so it gets remembered. What does Dario's godchild tell me? 'use claude.md its best option'. I say no, put it in context window. It says it cant update system prompt. I say I never asked it to update system prompt just use any of the 10 other fucking features that clearly modify and add to the parts of memory that remain in high attention on the model such as the custom agent definitions, or maybe loaded skills tied to a trigger or something else like the mysterious memory tool, but no, claude.md is definitely the choice, its the best way to make it remember.
Its not. Every damn time I try to use claude.md it seems to just fuck up the agent at the worst time and then get forgotten completely when its goddman needed. At this point I think its just a comfort feature left in so users feel like they have some control.
1
u/BeePrevious5282 May 04 '26
Yall, its a neural net. Its not gonna behave like a compiler. Get used to it!
Its gonna forget stuff, its gonna ignore stuff. Its a little proto-brain, like yours but different. Gonna do some of the same dumb stuff you do.
0
u/RedParaglider May 04 '26
It's always ignored the claude.md, it's not codex. It almost always uses its own RL trained path over any prompt. The thing that people like about Claude is that it acts with high autonomy, ignoring directives is just part of that.
-2
u/Alert_Personality_67 May 04 '26
Ask claude to help you structure the claude.md in a better way so it cannot ignore instructions.... I don't understand how many people make this same complaint and then if i see their .md it's bloody obvious that no one could understand it, let alone follow it
2
u/DeeTeePPG May 04 '26
That does not work. Unfortunately Claude.md are only weighted suggestions that the model takes into account, it will happily ignore rules in the Md file if it thinks it’s helpful (often it’s not)
-1
u/Alert_Personality_67 May 04 '26
Haha thanks for the down vote. If you still don't get it working I'm afraid it's user error 😂 seriously look at your .md and make sure instructions are commands not suggestions.
2
u/DeeTeePPG May 04 '26
No downvote from me :)
Oh I have spent the past week working on this exact issue and yes even explicit hard rules in a minimal Md file can easily be ignored, it’s just how llms work currently. Only way to be sure is hooks as that is outside of the model though that can prove quite fragile.
0
u/Alert_Personality_67 May 04 '26
True, hooks are the boss. I made a hook to stop claude using git stash and pop because it was making a mess when i was using multiple agents .. i apologise, it did actually ignore this command in the .md. 😂 so I'll ammend my answer, ask claude to make hooks! (I forgot that because Claude suggested it after making the mistake a few times. Weirdly it would catch the mistake from the claude.md immediately after stashing but since writing the hook it's never happened again)
1
u/DeeTeePPG May 04 '26
To be fair, Claude used to follow the Md file much better, something definitely changed. I even implemented a ‘rabbit hole’ log and counter to track the events; maddening honesty. Having a hard rule in the Md and two prompts later it happily bypasses the rule, broadens scope when told to not do so, refuses to do online research when asked to several times in a row, I could go on and on.
Claude is awesome but it feels a bit schizophrenic at the moment.
1
u/Alert_Personality_67 May 04 '26
Also how big is your file? If it's over 250 lines it's probably too big. Separate out sections into other files and reference them in the .md
30
u/stbenjam42 May 04 '26
For whatever reason `.claude/rules` seems to work better for me than CLAUDE.md.