The Highest Point of Leverage in Claude Code

Okay, so the biggest point of leverage that you  have when using Claude Code is your CLAUDE. md   file. And many people, including the creator of  Claude Code, says that you should be investing   in it and ruthlessly editing it over time. In  this video, I want to go through exactly what   that means and some of the things you can be  doing to your CLAUDE. md files to achieve better   results with Claude Code. Now, I really like  this graphic by humanlayer. It will be linked   down below where it shows you the hierarchy of  leverage. And to appreciate why your CLAUDE. md   file is so important, you want to consider this.   One bad line of code is code,   a bad line of a plan, when you're planning what  code should be written by your coding agent equals   hundreds of bad lines of code, because you just  have the wrong solution. One bad line of research   can lead to many bad lines of a plan that leads  to even more bad lines of code. And then finally,   one bad line of specification can lead to many  bad lines of research that leads to many bad   lines of planning code and so forth. So you  can see it's kind of cascading down here,   and the thing that sits at the very top  here is one bad line of your CLAUDE. md file,   because it's affecting every other thing here. So  with one bad line of your CLAUDE. md file, you can   get many bad lines of research that leads to even  more bad lines of a plan that can lead to hundreds   of bad lines of code. So the thing that you can  control that has the highest amount of leverage   after the model that you're actually using is your  CLAUDE. md file. So to 80/20, saving yourself from   a big buggy code base in the future, you want to  focus on making your CLAUDE. md file as good as   they can be. And I know that many people watching  the video have basically not touched their   CLAUDE. md file since their project was created  or touched it like a couple months ago, and they   haven't updated it since. But I found that this  graphic by humanlayer gave me, like, a really   deep appreciation for why I should be focusing  more of my efforts up here. And I know that most   of you watching this video will almost certainly  have a bad CLAUDE. md file. And the reason I know   this is because in the Claude Code system prompt,  when it reads your CLAUDE. md file, you can see the   Claude Code team wrote over here: "Important.   This context may or may not be relevant to your   tasks. You should not respond to this context  unless it's highly relevant to your tasks. " Now, there are a couple of reasons why the  Anthropic team may have written something   like this. And I think the reality is that many  people just have bad CLAUDE. md files that were   distracting Claude Code from making good judgment  calls. And they found this to be like a good hack   workaround to counter the fact that most people  just have bad files. And that's because when   you look at a lot of the advice online and on  Twitter, for example, people are downloading   random prompts and putting into CLAUDE. md  files; they're like treating it as a history   of all the changes that happen to a project. That  CLAUDE. md file is getting to like 1000 plus lines,   and they're basically never removing anything  or updating it when their project changes. Now,

there's a pretty good paper from about seven  months ago called "How Many Instructions Can   LLMs Follow at Once? " And they tested a bunch of  LLMs to see how accurate they were. And as you   increase the number of instructions and  you can see that Claude Opus 4. 1, after   about 150 instructions over here, its accuracy  begins to fall. Over previous weaker models,   the accuracy began to fall earlier, and other  ones sustained the accuracy for a longer period   of time before falling. Now, I'm sure that recent  models have gotten better on this benchmark,   and maybe they drop after 250 or 300 instead. So  you essentially have an instruction limit of how   many instructions can be given to a model before  it will do a worst job at the task at hand. Now,   the Claude Code system prompt contains about 50  instructions. So that means the remaining—let's   say this is 250 instead, for argument's sake,  because the models have gotten better since—you   then have about 200 instructions left in  your CLAUDE. md file and your plan and your   prompt and anything else the coding agent may  be reading. And because your CLAUDE. md file is   loaded upon every single request, that is the  biggest point in leverage that you can have. Now, when researching this video, I got Claude  Code to download and analyze over 1000 CLAUDE. md   files from public repos on GitHub to kind of  analyze and figure out what the average file   looks like. And this is a distribution for the  line count of all of these files. You can see   some of these CLAUDE. md files are over 500 lines,  so about 10% of them, which means that they have   way too many instructions that are being loaded  in all at once. So much so it probably explains   why the Claude Code team added this in the Claude  Code system prompt. And before I was educated on   this topic, when I was investigating one of my  own CLAUDE. md files, I noticed it reached over   650 lines and I was like, okay, this probably  explains why the model was performing pretty   bad on this particular part of the code base. Now,  before continuing in my Claude Code masterclass,   I do have a free video where I go through many of  my CLAUDE. md files and show you what it's like to   clean them up. And that will be linked down below  alongside a PDF summary of this video too. Now,   essentially, because we do  have an instruction budget,   which is some number depending on the model  that you're currently using, you want to stop   purging your CLAUDE. md file and only including  the most relevant things inside of it. Now,

one of the most important ideas to understand  when editing and removing stuff from your   CLAUDE. md files is that as we're getting better  and better models, many of the best practices are   being ingrained into the model itself. So you  don't need to have it in your CLAUDE. md files. Now there's a good related blog post by Vercel  that will show you what I mean. They were   making an AI agent called D0 for understanding  data, so they could ask questions kind of like   this, and it would just give them an answer  on Slack. And when designing this agent,   they basically gave it a bunch of tools to make  sure that every edge case was covered. And they   did all this heavy prompt engineering to  kind of constrain the model's reasoning,   and they found the success rate to only be 80%.   It was taking longer to complete tasks and it   was using more tokens. And then they were like,  okay, what if we just remove all the tools and   just give it two tools instead and rely more  heavily on the underlying power of the model?    Let's not do the model's thinking for it; it's  capable enough on its own. And after doing this,   they reached 100% on their benchmarks and they  got it done in fewer steps, faster and with less   tokens. And this is a general trend that we're  seeing as well going forward. A lot of the things   that people are adding to their prompts, so  they call them CLAUDE. md files, their agents,   they're trying to handle all these weird edge  cases for the agent and trying to do the thinking   of the model for the model itself. But as we get  model upgrades, you actually want to be removing   stuff from your CLAUDE. md files and removing  some of the tools that you have available,   because chances are those best practices are  now ingrained into the model itself. So you   don't have to fill your CLAUDE. md files with  obvious things like saying use encryption when   it comes to handling passwords or something, or  doing what I did over here and telling it how to   handle git submodules because it already knows  how to do that, or giving it example code for   how to do things like I have in my file here.   As models are getting better, you don't need   many of these things because many of these best  practices are slowly being baked into the model   itself. And ideally what you should be doing  is that with every model release, you should be   looking at what you can remove instead of thinking  about what you can add instead. Because chances   are if you do have some best practices in your  CLAUDE. md file, the newer model has even better   practices than you have written. And now you're  just constraining the newer and more capable   model from applying the even better practices  that it has within itself to your code base. It's also why many of these random things that  people are finding on Twitter and sticking inside   their CLAUDE. md file, hoping it will suddenly  fix everything, ends up performing worse because   either you're essentially wasting space by putting  things into your CLAUDE. md file that it already   knows not to do, like premature generalization.   Newer models will be better at this than older   models, so there's no reason to specify this  or stuff like not seeking clarifications when   needed. And this is also why some people notice  a new model performs better on a brand new code   base that does not have a CLAUDE. md file, because  it's not being held back by any constraints that   you wrote in your CLAUDE. md file to handle bad  behaviors in older models. Now because of that,   I can probably remove several hundred lines from  this CLAUDE. md file because I know that recent   models have gotten even better and they don't  need all this like excess padding teaching it   how to do something in probably a less efficient  way than it already knows how to do. The better

approach here is to start really small. Don't  rely on any CLAUDE. md files that you find online   or using the init command to auto generate one,  because that ends up being way too verbose. You   should start small with the bare minimum and only  add things as you find the model making mistakes,   by only adding things when need be and committing  it to GitHub, you can go back to points in your   code base where you added a new line that  led to worse performance for the model. So at the very beginning of a brand new project,  your CLAUDE. md file may be as small as this,   so it just gives a description of  what you're making. So Claude Code,   when it comes up with a plan, it knows exactly  how everything ties back to the bigger picture.    Then you have some short commands that may not be  inferred from the code base itself, like using NPM   instead of PNPM or bun, for example. And then  over time, as you're coding with Claude Code,   you may notice that it makes a mistake. And  then you add a brand new thing to your file,   such as this: "When a library's types are unclear  or cause errors, never use the anycasts. Instead,   use an explorer subagent to search through the  package's types file. " And you may consider   removing this a couple months later, when we  have better models and a better Claude Code,   because it may have a better way of handling  this specific situation. So by doing this,   you essentially ensure that firstly, when  you're adding new things to your CLAUDE. md file,   you can know what line may have caused it  to perform worse. And secondly, you prevent   yourself from hitting your instruction budget  too soon, whatever that may be, by not having   a really long CLAUDE. md file. One thing you want  to bear in mind when having your CLAUDE. md file

is that positioning matters. So ideally it should  be in the structure of project description, key   commands near the top, because LLMs weigh things  that are closer to the beginning and the end of   their instructions more than things that are kind  of in the middle. And then also any caveats. But   these caveats should instead be ingrained  into hooks that I will be covering later.

Now, something that I don't see people doing  enough is to split up their CLAUDE. md file   into many smaller ones that they have  distributed throughout their project   in folders and subfolders. So to show you how  this works, you have your root CLAUDE. md file,   which is always loaded in the conversation at the  beginning. And then when the model wants to read   a file on your computer, Claude Code will then  use a read tool and pass it back into the model.    So you can see kind of looks like this: the  model says, oh, this file looks interesting,   I want to use the read tool. Then our local  version, like Claude Code, reads that file,   passes it back into the model on Anthropic  servers, and it has like: this is line number one,   this is line two, three, four, and so on. And  at the very end of the file we have a system   reminder. And then we have the nested CLAUDE. md  file. So not the root one, we have the nested   one. So this means if Claude Code were to read  File 1, the CLAUDE. md file in the same hierarchy,   the same level, would be appended onto the  tool result. So if in another situation we   had file three over here and Claude Code wanted  to read that, then this CLAUDE. md file would be   appended onto it, then this one, and if it  were to read file 2, then the blue CLAUDE. md   file and the red one would be ignored because  they exist in different parts of the codebase. Now the reason this is powerful is because  since your root CLAUDE. md file is loaded in at   the beginning of the conversation, it can end up  forgetting certain things much later down in the   conversation. But by lazy loading any CLAUDE. md  files, by appending it just after the file,   we have any relevant context injected into  the right point in the conversation at the   right time. So this means your root CLAUDE. md  file can be really lightweight and you can have   more context-heavy CLAUDE. md files in other parts  of your code base. So as a quick example, in my   root CLAUDE. md file I have this migration flow  when it comes to creating Supabase migrations,   and honestly this should not be in the root  CLAUDE. md file because in many cases I simply   won't be making a Supabase migration. So this  is taking up tokens and space and instruction   budget when it doesn't need to be. So what I  can do is I can delete this from the root file,   then go to my supabase folder right over here,  right click, create a brand new CLAUDE. md file   and then paste it in over here instead. So  this basically means whenever Claude Code   reads a Supabase file because it's about to make  another migration, then this will automatically   be injected into conversation at the right  point. Now, there may be some times where

you don't want to rely only on the CLAUDE. md  file to do something for you. So for example,   this thing earlier where it says never run DB  push yourself, always allow the user to push   migrations to remote after reviewing them, 1  in 30 or 1 in 50 times. Claude Code may ignore   this particular hook and try to do DB push, partly  because a session could end up going really badly,   and I confuse the model a lot during the session,  and partly because of this system reminder. So what I can do instead is rely on a hook,  because that will work every single time. So   tagging the @claude-code-guide subagent, I can  then say, "Can you search online to find every   dangerous Supabase command like supabase DB  push and then block all those commands with a   pre-tool-use hook? " and that will look through the  Claude Code docs to understand how hooks work and   then also search online as well. Since this video  is not about hooks, if you're confused by hooks,   then you may want to check out the video in my  Claude Code masterclass. So you can see that after   searching online, it now made me a hook script and  it's adding the hook to the pre-tool-use hook. And   if I look for the hook here, I can see that's  blocking Supabase DB push, so I no longer need   this in my CLAUDE. md file. I can delete this from  over here. And then it's blocking other commands   like Supabase DB Reset, migrations repair, and a  bunch of other things, because I want to do those   commands instead. Instead of having a constraint  in my CLAUDE. md file, such as "never touch this   particular folder," I can tell Claude Code to  make a hook to prevent that happening to begin   with. And then finally, especially if you're  working in a team, you want to regularly audit

your CLAUDE. md file, so there may be a new model  release and you don't need as many things to teach   it the correct behavior. You may notice that you  are adding random things to your CLAUDE. md files   throughout the week, and now you have conflicting  instructions or instructions that should belong in   another CLAUDE. md file in the codebase. And if  you don't do that, you may notice that you get   a Claude Code file that is several hundred lines  long because you kept telling Claude Code, hey,   just add that to the CLAUDE. md file. And now  every time you use Claude Code, your context   window fills up way too quickly, and you've also  hit your instruction budget limit much sooner.

Now, if you want a nice summary cheat sheet  based on this video, it will be linked down   below alongside a real demonstration where  I go through my own CLAUDE. md files for this   particular project and then clean them up so you  get a sense of what to do in your own code base.    That will be available for free in a section on  my Master Claude Code class. And if you want to   apply these ideas to really large code bases  of hundreds of thousands or millions of lines,   then I cover how to do that in my Advanced  Context Engineering class right over here.    A bunch of teams have applied this to  code bases consisting of hundreds of   thousands of lines and have seen better  performance with Claude Code. So this   is perhaps the most advanced class on context  engineering that you will find on the internet.