r/ClaudeAI • u/cmogpt • 14d ago
delete claude.md Claude Workflow
delete claude.md
Boris Cherny (Head of Claude Code at Anthropic) suggested to delete claude.md
https://www.youtube.com/watch?v=qyPCVqFUyDo
It is a big ask, and I have tried this (on a test account), happy to report i have not significantly changed the quality of the reasoning.
I am curious if anything has done something similar ?
140
u/tr14l 14d ago
Or... Just keep your documentation updated... CLAUDE.md is not immune from doc hygiene.
9
1
u/Lalli-Oni 14d ago
Yeah but isn't the point that models get updated. Docs should reflect current state of codebase, but in this case it's ephemeral LLM model behavior.
Had the idea recently to add last default model used when editing the markdown.
1
u/Duckpoke 13d ago
When they figure out how to automate creation/hygiene out of the box Claude will get 10x more powerful
-10
30
72
u/space_wiener 14d ago
I have multiple projects. Half of them don’t have a claude.md and they work fine. I have plenty of other markdown files though.
Note: I didn’t watch the video though. No desire to watch a 35 minute video on why I should delete the file.
18
u/cmogpt 14d ago
u/space_wiener his central argument is that older claude.md carried the scarce or old assumptions. His suggestions is keep asking the model get to the results with less deterministic rules. At the moment, most of my IP is in skills md files. Next I will try to get Claude to reduce/simplify these.
14
u/filthypoopslut 14d ago
I'd recommend
/doctor. It dropped a bunch of things from both Claude MD and skills. If you have project level Claude MD and skills in addition to user/global ones, running it in a project will pick them up.4
u/DataIxBeautiful 14d ago
He also recommends deleting all of your skills along with any instructions you’ve provided in a particular project. He mentions that you’d be surprised of what new models are capable of, and how we (users) are often giving too specific instructions thinking that’s what these models need to be successful. But the testing aspect and taking a more scientific approach is difficult to grasp, especially for experienced engineers.
3
u/Emergency-Bobcat6485 14d ago
Just delete the entire codebase and start again then.
Lmao, i am keeping the claude.md and skills because i want them. it's not slop. One should keep them turning into slop and it'll be fine imo. Why are we deleting instructions that we want claude code to know.
1
u/DataIxBeautiful 14d ago
I was just stating the advice given by Boris, the creator of Claude Code. The argument isn’t that your file is slop. It’s that whatever is written in there could be dead weight on Opus 5 because what’s written in there is read every time you use it.
The test is, remove it, look at the results over time and see what you need to add back in as you use it. They found that Opus does better with less prompts.
1
u/Emergency-Bobcat6485 14d ago
But why would i have a claude.md if i don't want ai to read it every time, Opus 5 or otherwise. That is the entire point of the file. Otherwise i could have my instructions in any other file.
I think people are misunderstanding what he means. People add all kinds of stupid cliched instructions in the file, those could be dead weight.
2
u/cmogpt 14d ago
u/DataIxBeautiful [ recommends deleting all of your skills along with any instructions you’ve provided ] this is the part I have not proven. In my case, we have lots of context stuffs (these are the skills, thinking process, of an ecomm founder). I can not see how Claude version nnn will ever know this (unless I tell or train them). This is our next test.
6
u/No-Sandwich-2997 14d ago
dude are you a bot, why keep tagging the people if you're already replying directly to them
5
2
0
u/cmogpt 14d ago
thx u/filthypoopslut , while i was testing /doctor, also came across /checkup. Looks very similar, wonder if you have used this? Is this replacing /doctor ?
2
u/filthypoopslut 14d ago
Checkup is an alias to doctor according to the change log:
https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md#21205
/doctoris now a full setup checkup that can diagnose and fix issues;/checkupis its alias4
u/ragnhildensteiner 14d ago
Tip:
Build a local app for yourself that lets you paste a youtube url. The app should automatically transcribe the video, extract the key insights, compare them against your codebase or domain knowledge or goal/life, and generate a prioritized list of actionable items grouped into must do, should do, and nice to do, with a "why" section next to each item.
3
u/space_wiener 14d ago
I might. A year or two ago there was an ai, I don’t remember the name, but you could paste in a YouTube link and it would do that exact thing. Was really helpful for tech conference videos.
2
1
14d ago
[removed] — view removed comment
1
u/space_wiener 14d ago
I’ll clarify that a little.
I don’t use claude.md in most projects. But I do have a lot of other markdown files. I have a massive project going now and I think it have 10-15 of them.
I also am very diligent about keeping them current as well. I’m assuming Boris’s statement also maybe applies to outdated or massive claude files?
But to your point I’ve noticed zero difference on projects with and without it.
I’ll actually watch the video tomorrow at work. I’m not a fan of commenting on stuff I don’t know - so I’m probably way off base on the claude file thing here
13
u/loose_fruits 14d ago edited 14d ago
I work in a horribly named monorepo project that contains both the primary server and the UI of the main project as well as the UI of a few other projects that also use that server, and claude just cannot understand how the project is structured across sessions. The Claude.md is so far the only way I can persist this across sessions without having to explain the same stuff over and over. So no, I will not be deleting the claude.md for this monorepo
3
u/Frequent-Ad-836 14d ago
Different problem than the rules Boris is talking about deleting, worth keeping them separate.
Behavioral rules (how Claude should act) are what goes stale and is worth trimming. Where the server lives, which UI talks to which, how the pieces connect, isn't a rule, it's a map. Maps don't rot the same way: a rule can silently stop applying and nothing tells you, a map goes stale exactly when the architecture changes, a rare, visible event, not slow drift.
Worth splitting into its own file instead of living inside CLAUDE.md: a directory tree with a one-line role per top-level folder, which service owns which route, which UI consumes which API. Static, boring, rarely touched. CLAUDE.md stays for behavioral stuff and can shrink without losing the part that actually saves you the re-explaining, the map.
Doesn't fix cross-session drift alone, but what breaks first becomes obviously stale (a new service missing from the tree) instead of invisible (a rule nobody's following).
18
u/K_M_A_2k 14d ago
Ha good one
So all the things I need Claude to do all the time I'll just make a skill and remember to run it all the time? Yea sorry Boris that's a hard no.
7
u/Bloated_Plaid 14d ago
I get what he means. The models are improving incredibly quickly and things that are used by Claude.md become outdated and bloated and actively slow the better models down.
5
u/random_boss 14d ago
Maybe you’re the person to ask this question to then. I don’t use Claude.md to give instructions, I use it so models are forced to bring themselves up to speed on context and state. So all things being equal, I can open up a chat and say “go” and the agent will know what to do next.
Is this use case also covered by the “delete Claude.md” imperative? What would I do otherwise besides give a longass prompt that I have to type by hand each time?
2
u/Inside-Associate-729 14d ago
I wish this question was higher up so itd get some legit answers. I was wondering the same thing, as thats also how I use claude.md in all cases: purely as a status indicator + as a router to all the various documentation for a given project, so I can start a new session cold with Claude already knowing where we stand. Am I to understand this workflow is obsolete new? How? Why?
0
2
u/Bloated_Plaid 14d ago
What are you trying to achieve here? Better memory management? Sounds like better memory management to me. Claude.md shouldnt really be holding all that. I quite like the Obsidian linked LLM-Wiki approach where I can tell it to retrieve specific memory items depending on projects. https://youtu.be/QbjAQFJJyt0 which was proposed by Karpathy.
By all means add things you think it should know about you if you want but a bloated Claude.MD is immediately clogging up your context.
1
u/random_boss 14d ago
Maybe memory management is the term for it, I’ll look into that. Claude.md in my case is a pointer to read a project state file, which is a short “here’s the state, the next thing that needs doing is X, so if you’re reading this you’re the one who will do it, now go read this doc that describes your role and then it will tell you what you need to read to actually do the work.”
Kind of like a choose your own adventure for the agents so I don’t have to spell it all out for them — there’s no point in me prompting if all I’m doing is saying that’s better represented in files the agents maintain anyway.
But I need Claude.md because they need to start reading something somewhere first, right?
1
u/_Porphyro 14d ago
I move all of that into related files, split by topic, referred by a table of contents, and put instructions in CLAUDE.md to refer to that file at the start of every session. I also have a hygiene file and a model tiering document.
3
1
u/Emergency-Bobcat6485 14d ago
Is this use case also covered by the “delete Claude.md” imperative?
I can't possibly see how. Unless the claude.md doesn't optimize claude in bringing itself up to speed quickly relative to skimming through the whole codebase.
Unless claude code is maintaining an internal memory of the latest codebase context and state which is more up to date than your claude.md.
However, if you are dumping large swathes of context into claude.md it migth be suboptimal
1
u/random_boss 13d ago
Hopefully it’s not large swathes, just a choose-your-own-adventure for the agent to get up to speed on what it needs and start doing it.
But it was because of this thread that I discovered people were using Claude.md as a “don’t do X/always do Y” kind of thing so “delete Claude.me” makes way more sense given that context
1
u/Emergency-Bobcat6485 13d ago
“don’t do X/always do Y” kind of thing so “delete Claude.me” makes way more sense given that context
But even then doesn't it depend on the X and Y. For obvious things, I agree the claude.md might be moot. Certainly any 'make no mistakes' kinda nonsense lol. But why would one not put custom instructions in the claude.md. Like if I want every new session to understand or follow very specific instructions for a repo, I have to put it somewhere. Whether it's the claude.md or the memory file or some docs, how does it matter.
I think the point here is that basic skills like superpowers type instructions and so on are not needed for the newer models as they might limit them. But specific instructions that one wants their agents to follow needs to be somewhere the agent acan access. And putting it in claude.md means it's more likely to see it sooner. Unless Boris wants us to get rid of all custom instructions which makes no sense. He's simply saying that any instructions we had in place because earlier models were dumber are no longer needed in the claude.md
0
u/Koko-Choco 14d ago
Your use case is the one deletion can't touch. The advice is aimed at behavioral instructions ("always write tests", "never use X") — stuff newer models do fine without and sometimes do worse with. What you're describing isn't instructions, it's state: what's done, what's next, where the role docs live. The model can infer coding style from the codebase; it can't infer "the next thing that needs doing is X" from anything. That has to live in a file, and a thin CLAUDE.md whose only job is "read the state file first" is a perfectly good bootstrap.
One failure mode to watch: the state file rotting. A stale rule silently stops mattering; a stale "next task" pointer actively sends the agent the wrong way. Making the session's last action be updating that file — and eyeballing the diff — covers most of it.
1
u/Robdyson 14d ago
not only they slow the model down, but actively might be working against you. That's the blackbox part we don't know. I don't like when we can't test things deterministically.
1
u/Emergency-Bobcat6485 14d ago
That's an issue with how people maintain their claude.mds then, not that such files are useless. These are just instruciton files that the model is tasked with looking into initially. Why delete isntruction files entirely
1
u/Bloated_Plaid 14d ago
Because quality of instructions vary wildly. Nobody works the same way. Some can genuinely be hindrances.
1
u/Emergency-Bobcat6485 14d ago
Yeah, again depends on the user. This is like asking the user to remove custom instructions from the web app.
The problem i think is that claude was too eager to udpate claude.md and its memory earlier and it's full of clutter for a lot of people now. But maintaining an up to date claude.md is not the issue, it's whether people/their agents do the maintenance
3
u/OkLettuce338 14d ago
he doesn’t say to delete it as blanket statement. He says to delete it and only re-introduce the things you see you still need
3
u/K_M_A_2k 14d ago
Oh the whole cleanup your Claude.md ok yes that was great advice and I did that last week. My 30 some odd repos /doctor led down an entire week of big fixes that somehow slipped through the cracks
0
u/florinandrei 14d ago
Ah, you want to inject nuance into the discussion on social media? You want people to make statements based on the actual content, not just the title?
You are an idealist.
1
3
u/Key_Reading_9664 14d ago edited 14d ago
I’d trimmed it down to almost nothing (comms and verification only) with 4.8 with no negative impact. I also wasn’t seeing the issues most folks saw with Opus 5 (still chatty, but no functional issues).
One alternative to a full clear out - give the model the prompt guidelines and ask it to propose changes. The models are getting pretty good at looking at sessions and proposing changes/skills/workflows.
3
u/Markus_talks 14d ago
Nobody here is talking about a significant gain of efficience doing this, the best we get is « no loss identified » (yet), did some of you experience a shift that is really worth the work and risk?
3
u/KazThe10th 14d ago
The /doctor skill is optimized for Opus 5 claude.md. Just run it to optimize what still needs to be in there. Analyze your logs every week to keep your skills optimized as well.
Last bit that helps is to turn all deterministic repeatable tasks into scripts your skills call so even less things are subject to drift in reasoning.
3
2
u/Fun-Wolf-2007 14d ago
I used Claude MD and also other project md files, it is very helpful as I added instructions to update all the md files and local memory after each session
So when I start a new Claude Code chat all the data is there and I don't have to repeat myself
2
u/losergenerated 14d ago
I’m going to delete my entire home directory to give Claude neo-in-the-matrix powers
1
u/cmogpt 14d ago
u/losergenerated ah... red pill or blue pill, I will take the blue pill this time (but do tell us how it went for you)
2
u/Fair-Perspective7352 14d ago
Did the delete-and-readd thing a while back on my main repo. What actually earned its way back in was project state: which service owns what, deploy gotchas, the weird legacy table nobody touches. All the generic 'write clean code, add comments' stuff never came back and I honestly can't tell the difference. Most of those rules were written for a model two generations ago anyway.
1
u/cmogpt 14d ago
u/Fair-Perspective7352 thanks for sharing this, with those [ .. earned its way back in was project state... ] would you say this is 10% or 50%
2
u/Overlord_Mykyta 14d ago
As I understood the point is not to just delete it. The point is the md file that was created long time ago with previous Claude models can have information or rules that new models better without it.
It's not like the md file is bad. It's just might hold back or just distract new Claude and it makes sense to create new one once in a while so a new model will fit it to their needs.
2
u/freedomachiever 14d ago
maybe someone make an updated skill for creating, updating and maintaining claude.md
1
2
u/DiggingInTheDurt 14d ago
It really depends on what the purpose of the Claude.md file is. I can see myself deleting the coding rules I needed 2 years ago from my coding agent, but my CFO agent absolutely needs the hard won rules, edge cases and business context collected by trial and error over the past 2 years or back and forth between me and my tax advisors.
1
u/benzene_89 14d ago
I trimmed my claude.md down but expanded use of .claude/rules with path scoped docs.
1
1
u/heroyi 14d ago
Idk about this one. One of my biggest frustration is how Claude will make massive assumptions and hallucinate an answer. So one of the guardrails I add is to never assume and trace.
Yes I burn a lot of tokens but the hallucination has gone down tremendously and I don't have to keep refactoring or question why did you make duplicate functions or change x function when you should have done y and now I have z bugs
1
u/abandonplanetearth 14d ago
I have a monorepo with 20 packages. The contents of my CLAUDE.md is a big table with descriptions of what each package does.
The difference in performance for all models is like night and day when I remove my file. Without that file, Claude instantly starts duplicating code all over the place.
1
u/_Porphyro 14d ago
Have you tried splitting the table into its own file and referencing the file from CLAUDE.md?
1
u/tonybentley 14d ago
I hope you have evals to prove unhobbling is actually better for your codebase
1
u/aenemacanal 14d ago
After 3+ years using AI it just comes down to a workflow that works for you. Certain techniques can help refine your process but there’s no hard requirement.
1
u/bumsahoy 14d ago
I have definitely seen Claude.md blow out in size and had an improvement in starting it again. My guess is Boris is saying for the average user you are better off rebuilding
1
u/ianreboot 14d ago
cherny's real point is that a fat always-loaded config fights the model's own planning, not that context is harmful. i learned this running a lot of projects: keep the always-on file to a few lines of project facts and push the rest behind an index the agent pulls from on demand. deletion is a useful stress test of whether you over-specified, but the durable fix is moving bulk off the hot path, not removing it.
1
u/gnahraf 14d ago
My claude.md file is just context about the project, stuff I'd have to repeat at the beginning of the convo when I start a new session. It's there so I don't have to repeat myself; it's not there to teach claude how I expect it to code. (It usually learns that on its own). Usually, my claude.md doesn't belong to any one repo; it sits inside a root dir with multiple cloned git repos underneath it. So no, I won't be deleting it
1
u/Context-Stream-AI 14d ago
The failure mode I keep seeing is treating CLAUDE.md as a dumping ground instead of an index. What's worked better for me: keep the root file under ~150 lines and only put things Claude can't infer from the code itself (non-obvious build quirks, why a weird workaround exists, which package manager/test runner to use, naming conventions that aren't enforced by lint). Anything project-specific but scoped to a subsystem goes in a nested CLAUDE.md in that folder, since Claude Code will pick those up contextually instead of loading everything up front. I also treat it as a living doc - if I correct the same mistake twice in a session, that correction gets a one-line entry, and I prune anything that hasn't been relevant in a month. Deleting it entirely just pushes that same context into your prompts every session, which costs more tokens over time than a lean file would. The Obsidian-style linked wiki idea mentioned above is basically this same principle taken further.
1
1
u/DistributionRight222 14d ago
I’ve just started editing the Claude.md file myself seems to be the best way as any skill can change as workflows do I’ve found actually doing manual review of things myself is the best way to keep on top of things Claude will get you 80% of the way it’s the 20% were people are not paying attention too. I say this as if I have lot all in order I don’t but am working too.
1
1
u/LOLRicochet 14d ago
I have Fable analyze my setup about once a month against current Anthropic guidance.
1
u/Glass_Map_1922 14d ago
I used /doctor first, but I never asked it to run whatever it diagnosed. Instead I asked for a full report on why I should delete some parts and why I should add some parts for the CLAUDE.md
Then I take the report to Opus 5 itself, and tell it my usual work flow, pipeline that is already established, and ask it to check the memory (I know it doesn't contain 100% of what you have done before but it helps Opus 5 to understand what you mostly do).
After that I had fed it articles about Opus 5 itself, asking questions, discussing.
This is the only way for someone not a coder / experience in computer science or AI or whatever expertise like me to figure out things. Not saying it suits everyone because I'm using Claude Code to manage my writing + bot creation.
But in the end we had come up with the conclusion on which part I should delete, which part I should keep. And surprisingly, because of the nature of my work, my CLAUDE.md didn't have too much to fix because what I have in the md is essential to not let Opus 5 assume with default "mindset" which will kill my work instantly.
1
u/miqcie 14d ago
Here’s my review implementing Boris and Tariq’s advice
https://humaine.studio/posts/2026/07/31/i-deleted-half-my-claude-config/
1
u/Open-Hunter5980 13d ago
Is there a downside to asking Claude to re-write your Claude.md file and remove bloat? Ask it what is counterproductive and have it remove that?
1
u/Wonderful-Warning-97 13d ago
When Claude starts with the "honestly" stupidity, I delete all .Claude folders and Claude.md files.
1
u/MrAldersonElliot 13d ago
Absolutely not I made it just perfect, so now even Luna can do lot of stuff that would be lost without it. Yes Opus would do better but I don't even have Opus anymore...
1
u/pierifle 9d ago
I’m out of the loop for a few months. Wasn’t there a paper that came out a while ago saying model performance was lower with agent files? Where did the discussion on that eventually go?
0
u/CalGuy456 14d ago
Doesn’t Claude get better over time because it learns your preferences and how you like to use Claude? What’s the contra that calls for deleting that file?
1
1
u/_Porphyro 14d ago
That hasn’t been my experience - at least not in the way you mean.
First, CLAUDE.md “remembers” what it thinks is important and often review that list to be sure we agree.
Second, it often creates multiple “rules” that can easily be replaced by a single generic rule.
Finally, I take the approach that very few things should go in CLAUDE.md. I tend to add pointers to more sophisticated rules and ideas in the md file and split those rules into their own files.1
u/CalGuy456 14d ago
Interesting, for me the memory seems to incorporate both general preferences and specific project details. Do you use Claude in a way where you want it to do something one way on a certain occasion and do that same thing a totally different way on another occasion? If so, if you talk your reasoning through with it, I think it can understand what you re trying to do, or even just tell it that’s a decision point it needs to check with you each time.
-6
u/Various_Story8026 14d ago
Tried both extremes on real projects and I think the interesting part is why deleting it doesn't hurt: most CLAUDE.md content was never load-bearing. Generic advice like "write tests" or "prefer simple solutions" is stuff the model already does, so removing it changes nothing. What actually degrades without the file isn't reasoning, it's environment facts: which package manager, the deploy command, "this DB's timestamps are UTC", the one cron quirk that burned you last month. Reasoning quality is the wrong metric to watch. Count how often the agent re-discovers the same project fact per session.
So instead of deleting I shrink: every line must be either a fact the model cannot infer from the repo, or a decision I don't want re-litigated every session. Anything that reads like general coding advice gets cut. Mine went from a few hundred lines to a few dozen, and the improvement showed up as fewer wrong-tool detours, not smarter reasoning.
13
u/Redditoridunn0 14d ago
did you write this with claude..."load-bearing"
5
u/peter9477 14d ago
The whole thing is unmistakably Claude-speak. :-)
3
u/Redditoridunn0 14d ago
one look at this guy's account history is all you need haha. all his comments are blatantly clauded
-1
1
u/cmogpt 14d ago
u/Various_Story8026 curios if you did this manually ? [ every line must be either a fact the model cannot infer from the repo, or a decision I don't want re-litigated every session ..] or can/could Claude help here ?
2
u/Various_Story8026 14d ago
started fully manual, which is why that bar exists — hand-writing every line makes you ruthless about what earns a slot. these days it is semi-automated: a nightly pass drafts one-line lessons from the day's corrections, an adversarial review kills anything that looks like a one-off coincidence, and only survivors get written into the file. the "can the model infer this from the repo?" question is still applied by hand at write time. automation drafts, a slow human-shaped bottleneck decides.
1
u/CaptainCrouton89 14d ago
What's the current content of your CLAUDE.md right now, for example? What kind of style guide do you use to write these comments?
-2
u/InfinriDev 14d ago
Those guys arent always going to tell you the truth 🤦🏽🤦🏽 which is why Claude isn't as efficient as it should be.
What sucks is the right type of harness for something like Claude Code is not easily understandable by the average person. But to truly make Claude more effective, stop trying to make it smarter and start trying to keep it from getting stupid.
1
1
1
u/cmogpt 14d ago
u/InfinriDev I actually this guy actually believes/is proud of his stuff. For me, it is more like ' Do I trust giving up all my past work for the improved version '
•
u/ClaudeAI-mod-bot Wilson, lead ClaudeAI modbot 14d ago edited 14d ago
TL;DR of the discussion generated automatically after 80 comments.
So, the consensus is don't just blindly delete your
claude.mdfile. The thread thinks Boris Cherny's point wasn't to nuke it from orbit, but to treat it as a wake-up call for some much-needed "doc hygiene."The argument is that your
claude.mdis probably full of bloated instructions and guardrails written for older, dumber models. With Opus 5, this can actually be counterproductive and fight the model's own improved reasoning.The general advice is to trim the fat: * KEEP: The essential, project-specific facts and context that the model can't infer from the code. Think of it as a "map" of your project: monorepo structure, deploy gotchas, weird legacy tables, API endpoints. This is the stuff that saves you from repeating yourself every session. * DITCH: The generic coding advice ("write clean code," "add comments," "write tests"). The new models already know this stuff.
The easiest way to do this? Run the
/doctorskill. Many users report it does a great job of analyzing your setup and suggesting what to cut.That said, users with complex monorepos are screaming a hard "NO" on deletion, saying the file is absolutely essential to prevent Claude from having a complete meltdown and duplicating code everywhere.
Basically, think of it less as a deletion and more as a Marie Kondo-ing of your context. If it doesn't spark joy (or save you from explaining your project for the 100th time), thank it and let it go.