13 ms·

Writing a good Claude.md

748 points by objcts 10mo ago

eric-burel 10mo ago
"You can investigate this yourself by putting a logging proxy between the claude code CLI and the Anthropic API using ANTHROPIC_BASE_URL" I'd be eager to read a tutorial about that I never know which tool to favour for doing that when you're not a system or network expert.
- fishmicrowaver 10mo ago
  Have you considered just asking claude? I'd wager you'd get up and running in <10 minutes.
  - dhorthy 10mo ago
    agree - i've had claude one-shot this for me at least 10 times at this point cause i'm too lazy to lug whatever code around. literally made a new one this morning
  - eric-burel 10mo ago
    AI is good for discovery but not validation, I wanted experienced human feedback here
- 0xblacklight 10mo ago
  Hi, post author here We used cloudflare’s AI gateway which is pretty simple. Set one up, get the proxy URL and set it through the env var, very plug-and-play
  - eric-burel 10mo ago
    Smart, thanks for the tip
- Havoc 10mo ago
  Just install mitmproxy. Takes like 5 mins to figure out. 2 with Claude. On phone else I’d post commands
jasonjmcghee 10mo ago
Interesting selection of models for the "instruction count vs. accuracy" plot. Curious when that was done and why they chose those models. How well does ChatGPT 5/5.1 (and codex/mini/nano variants), Gemini 3, Claude Haiku/Sonnet/Opus 4.5, recent grok models, Kimi 2 Thinking etc (this generation of models) do?
- alansaber 10mo ago
  Guessing they included some smaller models just to show how they dump accuracy at smaller context sizes
  - jasonjmcghee 10mo ago
    Sure - I was more commenting that they are all > 6 months old, which sounds silly, but things have been changing fast, and instruction following is definitely an area that has been developing a lot recently. I would be surprised if accuracy drops off that hard still.
    - 0xblacklight 10mo ago
      I imagine it’s highly-correlated to parameter count, but the research is a few months old and frontier model architecture is pretty opaque so hard to draw too too many conclusions about newer models that aren’t in the study besides what I wrote in the post
vladsh 10mo ago
What is a good Claude.md?
- testdelacc1 10mo ago
  Claude.md - A markdown file you add to your code repository to explain how things work to Claude. A good Claude.md - I don’t know, presumably the article explains.
andersco 10mo ago
I have found enabling the codebase itself to be the “Claude.md” to be most effective. In other words, set up effective automated checks for linting, type checking, unit tests etc and tell Claude to always run these before completing a task. If the agent keeps doing something you don’t like, then a linting update or an additional test often is more effective than trying to tinker with the Claude.md file. Also, ensure docs on the codebase are up to date and tell Claude to read relevant parts when working on a task and of course update the docs for each new task. YMMV but this has worked for me.
- szundi 10mo ago
  [dead]
- Aeolun 10mo ago
  > Also, ensure docs on the codebase are up to date and tell Claude to read relevant parts when working on a task Yeah, if you do this every time it works fine. If you add what you tell it every time to CLAUDE.md, it also works fine, but you don’t have to tell it any more ;)
- Havoc 10mo ago
  > Claude.md It’s case sensitive btw. CLAUDE.md - Might explain your mixed results with it
prettyblocks 10mo ago
The advice here seems to assume a single .md file with instructions for the whole project, but the AGENTS.md methodology as supported by agents like github copilot is to break out more specific AGENTS.md files in the subdirectories in your code base. I wonder how and if the tips shared change assuming a flow with a bunch of focused AGENTS.md files throughout the code.
- 0xblacklight 10mo ago
  Hi, post author here :) I didn’t dive into that because in a lot of cases it’s not necessary and I wanted to keep the post short, but for large monorepos it’s a good idea
btbuildem 10mo ago
It seems overall a good set of guidelines. I appreciate some of the observations being backed up by data. 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.
_pdp_ 10mo ago
There is far much easier way to do this and one that is perfectly aligned with how these tools work. 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.
- dhorthy 10mo ago
  For the record I do think the AI community tries to unnecessarily reinvent the wheel on crap all the time. sure, readme.md is a great place to put content. But there's things I'd put in a readme that I'd never put in a claude.md if we want to squeeze the most out of these models. Further, claude/agents.md have special quality-of-life mechanics with the coding agent harnesses like e.g. `injecting this file into the context window whenever an agent touches this directory, no matter whether the model wants to read it or not` > What people often forget about LLMs is that they are largely trained on public information which means that nothing new needs to be invented. I don't think this is relevant at all - when you're working with coding agents, the more you can finesse and manage every token that goes into your model and how its presented, the better results you can get. And the public data that goes into the models is near useless if you're working in a complex codebase, compared to the results you can get if you invest time into how context is collected and presented to your agent.
  - theshrike79 10mo ago
    > For the record I do think the AI community tries to unnecessarily reinvent the wheel on crap all the time. On Reddit's LLM subreddits people are rediscovering the very basics of software project management as some massive insights daily or very least weekly. Who would've guessed that proper planning, accessible and up to documentation and splitting tasks into manageable testable chunks produces good code? Amazing! Then they write a massive blog post or even some MCP mostrosity for it and post it everywhere as a new discovery =)
candiddevmike 10mo ago
None of this should be necessary if these tools did what they say on the tin, and most of this advice will probably age like milk. Write readmes for humans, not LLMs. That's where the ball is going.
- 0xblacklight 10mo ago
  Hi, post author here :) Yes README.md should still be written for humans and isn’t going away anytime soon. CLAUDE.md is a convention used by claude code, and AGENTS.md is used by other coding agents. Both are intended to be supplemental to the README and are deterministically injected into the agent’s context. It’s a configuration point for the harness, it’s not intended to replace the README. Some of the advice in here will undoubtedly age poorly as harnesses change and models improve, but some of the generic principles will stay the same - e.g. that you shouldn’t use an LLM to do a linter &formatter’s job, or that LLMs are stateless and need to be onboarded into the codebase, and having some deterministically-injected instructions to achieve that is useful instead of relying on the agent to non-deterministically derive all that info by reading config and package files The post isn’t really intended to be super forward-looking as much as “here’s how to use this coding agent harness configuration point as best as we know how to right now”
  - teiferer 10mo ago
    > you shouldn’t use an LLM to do a linter &formatter’s job, Why is that good advice? If that thing is eventually supposed to do the most tricky coding tasks, and already a year ago could have won a medal at the informatics olympics, then why wouldn't it eventually be able to tell if I'm using 2 or 4 spaces and format my code accordingly? Either it's going to change the world, then this is a trivial task, or it's all vaporware, then what are we even discussing.. > or that LLMs are stateless and need to be onboarded into the codebase What? Why would that be a reasonable assumption/prediction for even near term agent capabilities? Providing it with some kind of local memory to dump its learned-so-far state of the world shouldn't be too hard. Isn't it supposed to already be treated like a junior dev? All junior devs I'm working with remember what I told them 2 weeks ago. Surely a coding agent can eventually support that too. This whole CLAUDE.md thing seems a temporary kludge until such basic features are sorted out, and I'm seriously surprised how much time folks are spending to make that early broken state less painful to work with. All that precious knowledge y'all are building will be worthless a year or two from now.
rootusrootus 10mo ago
Ha, I just tell Claude to write it. My results have been generally fine, but I only use Claude on a simple codebase that is well documented already. Maybe I will hand-edit it to see if I can see any improvements.
serial_dev 10mo ago
I’m sure I’m just working like a caveman, but I simply highlight the relevant code, add it to the chat, and talk to these tools as if they were my colleagues and I’m getting pretty good results. 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.
- vanviegen 10mo ago
  > I simply highlight the relevant code, add it to the chat, and talk to these tools Different use case. I assume the discussion is about having the agent implement whole features or research and fix bugs without much guidance.
  - 0xblacklight 10mo ago
    Yep it is opinionated for how to get coding agents to solve hard problems in complex brownfield codebases which is what we are focused on at humanlayer :)
- rmnclmnt 10mo ago
  Matches my experience also. Bothered only once to setup a proper CLAUDE.md file, and now never do it. Simply refering to the context properly for surgical recommendations and edit works relatively well. It feels a lot like bikeshedding to me, maybe I’m wrong
- wredcoll 10mo ago
  How about a list of existing database tables/columns so you don't need to repeat it each time?
  - anonzzzies 10mo ago
gonzalohm 10mo ago
Probably a lot of people here disagree with this feeling. But my take is that if setting up all the AI infrastructure and onboarding to my code is going to take this amount of effort, then I might as well code the damn thing myself which is what I'm getting paid to (and enjoy doing anyway)
- vanviegen 10mo ago
  Perhaps. But keep in mind that the setup work is typically mostly delegated to LLMs as well.
- fragmede 10mo ago
  Whether it's setting up AI infrastructure or configuring Emacs/vim/VSCode, the important distinction to make is if the cost has to be paid continually, or if it's a one time/intermittent cost. If I had to configure my shell/git aliases every time I booted my computer, I wouldn't use them, but seeing as how they're saved in config files, they're pretty heavily customized by this point. Don't use AI if you don't want to, but "it takes too much effort to set up" is an excuse printf debuggers use to avoid setting up a debugger. Which is a whole other debate though.
  - bird0861 10mo ago
    I fully agree with this POV but for one detail; there is a problem with sunsetting frontier models. As we begin to adopt these tools and build workflows with them, they become pieces of our toolkit. We depend on them. We take them for granted even. And then the model either changes (new checkpoints, maybe alignment gets fiddled with) and all of the sudden prompts no longer yield the same results we expected from them after working on them for quite some time. I think the term for this is "prompt instability". I felt this with Gemini 3 (and some people had less pronounced but similar experience with Sonnet releases after 3.7) which for certain tasks that 2.5Pro excelled at..it's just unusable now. I was already a local model advocate before this but now I'm a local model zealot. I've stopped using Gemini 3 over this. Last night I used Qwen3 VL on my 4090 and although it was not perfect (sycophancy, overuse of certain cliches...nothing I can't get rid of later with some custom promptsets and a few hours in Heretic) it did a decent enough job of helping me work through my blindspots in the UI/UX for a project that I got what I needed. If we have to perform tuning on our prompts ("skills", agents.md/claude.md, all of the stuff a coding assistant packs context with) every model release then I see new model releases becoming a liability more than a boon.
ctoth 10mo ago
I've gotten quite a bit of utility out of my current setup[0]: 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/d8e629209ff1d9748185b9830fa4e79f https://gist.github.com/ctoth/d8e629209ff1d9748185b9830fa4e7...
johnfn 10mo ago
I was expecting the traditional AI-written slop about AI, but this is actually really good. In particular, the "As instruction count increases, instruction-following quality decreases uniformly" section and associated graph is truly fantastic! To my mind, the ability to follow long lists of rules is one of the most obvious ways that virtually all AI models fail today. That's why I think that graph is so useful -- I've never seen someone go and systematically measure it before! 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.)
- 0xblacklight 10mo ago
  I looked when I wrote the post but the paper hasn’t been revisited with newer models :/
boredtofears 10mo ago
It would be nice to see an actual example of what a good claude.md that implements all of these recommendations looks like.
huqedato 10mo ago
Looking for a similar GEMINI.md
- 0xblacklight 10mo ago
  It might support AGENTS.md, you could check the site and see if it’s there
vunderba 10mo ago
From the article: > 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 Full CLAUDE.md file for reference: https://gist.github.com/scpedicini/179626cfb022452bb39eff10becb95fa https://gist.github.com/scpedicini/179626cfb022452bb39eff10b...
- sothatsit 10mo ago
  I have also done this, but my results are very hit or miss. Claude rarely actually reads the other documentation files I point it to.
  - dhorthy 10mo ago
    I think the key here is “if X then Y syntax” - this seems to be quite effective at piercing through the “probably ignore this” system message by highlighting WHEN a given instruction is “highly relevant”
    - throwaway314155 10mo ago
      What?
      - xpe 10mo ago
        It helps when questions intended to resolve ambiguity are not themselves hopelessly ambiguous. See also: "Help me help you" - https://en.wikipedia.org/wiki/Jerry_Maguire https://en.wikipedia.org/wiki/Jerry_Maguire
tietjens 10mo ago
I think this could work really well for infrastructure/ops style work where the LLM will not be able to grasp the full context of say the network from just a few files that you have open. But as others are saying this is just basic documentation that should be done anyway.
acedTrex 10mo ago
"Here's how to use the slop machine better" is such a ridiculous pretense for a blog or article. You simply write a sentence and it approximates it. That is hardly worth any literature being written as it is so self obvious.
- 0xblacklight 10mo ago
  This is an excellent point - LLMs are autoregressive next-token predictors, and output token quality is a function of input token quality Consider that if the only code you get out of the autoregressive token prediction machine is slop, that this indicates more about the quality of your code than the quality of the autoregressive token prediction machine
  - acedTrex 10mo ago
    > that this indicates more about the quality of your code Considering that the "input" to these models is essentially all public code in existence, the direct context input is a drop in the bucket.
johnsmith1840 10mo ago
I don't get the point. Point it at your relevent files ask it to review discuss the update refine it's understanding and then tell it to go. 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.
- ra 10mo ago
  This is exactly right. Attention is all you need. It's all about attention. Attention is finite. The more you data load into context the more you dilute attention.
  - throwuxiytayq 10mo ago
    people who criticize LLMs for merely regurgitating statistically related token sequences have very clearly never read a single HN comment
- nightski 10mo ago
  IMO within the documentation .md files the information density should be very high. Higher than trying to shove the entire codebase into context that is for sure.
  - johnsmith1840 10mo ago
    You deffinetly don't just push the entire code base. Previous models required you to be meticulous about your input. A function here a class there. Even now if I am working on REALLY hard problems I will still manually copy and paste code sections out for discussion and algorithm designs. Depends on complexity. This is why I still believe open ai O1-Pro was the best model I've ever seen. The amount of compute you could throw at a problem was absurd.
malshe 10mo ago
I have been using Claude.md to stuff way too many instructions so this article was an eye opener. Btw, any tips for Claude.md when one uses subagents?
0xcb0 10mo ago
Here is my take, on writing a good claude.md. I had very good results with my 3 file approach. And it has also been inspired by the great blog posts that Human Layer is publishing from time to time https://github.com/marcuspuchalla/claude-project-management https://github.com/marcuspuchalla/claude-project-management
mmaunder 10mo ago
That paper the article references is old at this point. No GPT 5.1, no Gemini 3, which both were game changers. I'd love to see their instruction following graphs.
- 0xblacklight 10mo ago
  Same!
grishka 10mo ago
Oh yeah I added a CLAUDE.md to my project the other day: https://github.com/grishka/Smithereen/blob/master/CLAUDE.md https://github.com/grishka/Smithereen/blob/master/CLAUDE.md Is it a good one?
- lijok 10mo ago
  I copy/pasted it into my codebase to see if it’s any good and now Claude is refusing to do any work? I asked Copilot to investigate why Claude is not working but it too is not working. Do you know what happened?
- wizzledonker 10mo ago
  Definitely a good one - probably one of the best CLAUDE.md files you can put in any repository if you care about your project at all.
max-privatevoid 10mo ago
The only good Claude.md is a deleted Claude.md.
- rvz 10mo ago
  This is the only correct answer.
deleted 10mo ago
[deleted]
VimEscapeArtist 10mo ago
What's the actual completion rate for Advent of Code? I'd bet the majority of participants drop off before day 25, even among those aiming to complete it. Is this intentional? Is AoC designed as an elite challenge, or is the journey more important than finishing?
- philipwhiuk 10mo ago
  Wrong article. I rarely get past 18 or so. The stats for last year are here: https://adventofcode.com/2024/stats https://adventofcode.com/2024/stats
DR_MING 10mo ago
I already forgot CLAUDE.md, I generate and update it by AI, I prefer to keep design, tasks, docs folder instead. It is always better to ask it to read a some spec docs and read the real code first before doing anything.
nico 10mo ago
> Claude often ignores CLAUDE.md > 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
- stingraycharles 10mo ago
  That’s hilarious and a great way to test this. What I’m surprised about is that OP didn’t mention having multiple CLAUDE.md files in each directory, specifically describing the current context / files in there. Eg if you have some database layer and want to document some critical things about that, put it in “src/persistence/CLAUDE.md” instead of the main one. Claude pulls in those files automatically whenever it tries to read a file in that directory. I find that to be a very effective technique to leverage CLAUDE.md files and be able to put a lot of content in them, but still keep them focused and avoid context bloat.
  - sroussey 10mo ago
    Ummm… sounds like that directory should have a readme. And Claude should read readme files.
    - stingraycharles 10mo ago
      READMEs are written for people, CLAUDE.mds are written for coding assistants. I don’t write “CRITICAL (PRIORITY 0):” in READMEs. The benefit of CLAUDE.md files is that they’re pulled in automatically, eg if Claude wants to read “tests/foo_test.py” it will automatically pull in “tests/CLAUDE.md” (if it exists).
      - adastra22 10mo ago
deleted 10mo ago
[deleted]
deleted 10mo ago
[deleted]
deleted 10mo ago
[deleted]
astrostl 10mo ago
I have Claude itself write CLAUDE.md. Once it is informed of its context (e.g., "README.md is for users, CLAUDE.md is for you") you can say things like, "update readme and claudemd" and it will do it. I find this especially useful for prompts like, "update claudemd to make absolutely certain that you check the API docs every single time before making assumptions about its behavior" — I don't need to know what magick spell will make that happen, just that it does happen.
- dexwiz 10mo ago
  Do you have any proof that AI written instructions are better than human ones? I don't see why an AI would have an innate understanding on how best to prompt itself.
  - michaelbuckbee 10mo ago
    Generally speaking it has a lot of information from things like OP's blog post on how best to structure the file and prompt itself and you can also (from within Claude Code) ask it to look at posts or Anthropic prompting best practices and adopt those to your own file.
  - astrostl 10mo ago
    Having been through cycles of manual writing with '#' and having it do it itself, it seems to have been a push on efficacy while spending less effort and getting less frustrated. Hard to quantify except to say that I've had great results with it. I appreciate the spirit of OP's, "CLAUDE.md is the highest leverage point of the harness, so avoid auto-generating it" but you can always ask Claude to tighten it up itself too.
- chickensong 10mo ago
  This will start to break down after a while unless you have a small project, for reasons being described in the article.
brcmthrowaway 10mo ago
Is CLAUDE.md required when claude has a --continue option?
- Zerot 10mo ago
  I would recommend using it, yeah. You have limited context and it will be compacted/summarized occasionally. The compaction/summary will lose some information and it is easy for it to forget certain instructions you gave it. Afaik claude.md will be loaded into the context on every compaction which allows you to use it for instructions that should always be included in the context.
bryanhogan 10mo ago
I've been very satisfied with creating a short AGENTS.md file with the project basics, and then also including references to where to find more information / context, like a /context folder that has markdown files such as app-description.md.
m13rar 10mo ago
I was waiting for someone to build this so that I can chuck it into CLAUDE and tell it how to write good MD.
foobarbecue 10mo ago
Funny how this is exactly the documentation you'd need to make it easy for a human to work with the codebase. Perhaps this'll be the greatest thing about LLMs -- they force people to write developer guides for their code. Of course, people are going to ask an LLM to write the CLAUDE.md and then it'll just be more slop...
- chickensong 10mo ago
  It's not exactly the doc you'd need for a human. There could be overlap, but each side may also have unique requirements that aren't necessarily suitable for the other. E.g. a doc for a human may have considerably more information than you'd want to give to the agent, or, you may want to define agent behavior for workflows that don't apply to a human. Also, while it may be hip to call any LLM output slop, that really isn't the case. Look at what a poor history we have of developer documentation. LLMs may not be great at everything, but they're actually quite capable when it comes to technical documentation. Even a 1-shot attempt by LLM is often way better than many devs who either can't write very well, or just can't be bothered to.
AndyNemmity 10mo ago
it's always funny, i think the opposite. I use a massive CLAUDE.md file, but it's targetted towards very specific details of what to do, and what not to do. 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.
deleted 10mo ago
[deleted]
Ozzie_osman 10mo ago
Has anyone had success getting Claude to write it's own Claude.md file? It should be able to deduce rules by looking at the code, documentation, and PR comments.
- handoflixue 10mo ago
  The main failure state I find is that Claude wants to write an incredibly verbose Claude.md, but if I instruct it "one sentence per topic, be concise" it usually does a good job. That said, a lot of what it can deduce by looking at the code is exactly what you shouldn't include, since it will usually deduce that stuff just by interacting with the code base. Claude doesn't seem good at that. An example of both overly-verbose and unnecessary: ### 1. Identify the Working Directory When a user asks you to work on something: 1. *Check which project* they're referring to 2. *Change to that directory* explicitly if needed 3. *Stay in that directory* for file operations ```bash # Example: Working on ProjectAlpha cd /home/user/code/ProjectAlpha ``` (The one sentence version is "Each project has a subfolder; use pwd to make sure you're in the right directory", and the ideal version is probably just letting it occasionally spend 60 seconds confused, until it remembers pwd exists)
- chickensong 10mo ago
  If you have any substantial codebase, it will write a massive file unless you explicitly tell it not to. It also will try and make updates, including garbage like historical or transitional changes, project status, etc... I think most people who use Claude regularly have probably come to the same conclusions as the article. A few bits of high-level info, some behavior stuff, and pointers to actual docs. Load docs as-needed, either by prompt or by skill. Work through lists and constantly update status so you can clear context and pick up where you left off. Any other approach eats too much context. If you have a complex feature that would require ingesting too many large docs, you can ask Claude to determine exactly what it needs to build the appropriate context for that feature and save that to a context doc that you load at the beginning of each session.
wowamit 10mo ago
> Regardless of which model you're using, you may notice that Claude frequently ignores your CLAUDE.md file's contents. 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.
adastra22 10mo ago
> Claude code injects the following system reminder… 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?
edf13 10mo ago
Ah, never knew about this injection… <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
nurettin 10mo ago
I've been a customer since sonnet 3.5. It is coming to the point where opus 4.5 usually does better than whatever your instructions say on claude.md just by reading your code and having a general sense of what your preferences are. 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.
magictux 10mo ago
I think this is an overall good approach and I've got allright results with a similar approach - I still think that this CLAUDE.md experience is too magical and that Anthropic should really focus on it. 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 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.
toenail 10mo ago
A good Claude.md only needs one line: Read your instructions from Agents.md
ilmj8426 10mo ago
I've recently started using a similar approach for my own projects. providing a high-level architecture overview in a single markdown file really helps the LLM understand the 'why' behind the code, not just the 'how'. Does anyone have a specific structure or template for Claude.md that works best for frontend-heavy projects (like React/Vite)? I find that's where the context window often gets cluttered.
asim 10mo ago
That's a good write up. Very useful to know. I'm sort of on the outside of all this. I've only sort of dabbled and now use copilot quite a lot with claude. What's being said here, reminds me a lot of CPU registers. If you think about the limited space in CPU registers and the processing of information is astounding, how much we're actually able to do. So we actually need higher layers of systems and operating systems to help manage all of this. So it feels like a lot of what's being said. Here will end up inevitably being an automated system or compiler or effectively an operating system. Even something basic like a paging system would make a lot of difference.
aiibe 10mo ago
Writing and updating CLAUDE.md or AGENTS.md feels like pointless to me. Humans are the real audience for documentation. The code changes too fast, and LLMs are stateless anyway. What’s been working is just letting the LLM explore the relevant part of the code to acquire the context, defining the problem or feature, and asking for a couple of ways to tackle it. All in a one short prompt. That usually gets me solid options to pick and build it out. And always do, one session for one problem. This is my lazy approach to getting useful help from an LLM.
- arnorhs 10mo ago
  I agree with you, however your approach results in much longer LLM development runs, increased token usage and a whole lot of repetitive iterations.
  - aiibe 10mo ago
    I’m definitely interested in reducing token usage techniques. But with one session one problem I’ve never hit a context limit yet, especially when the problem is small and clearly defined using divide-and-conquer. Also, agentic models are improving at tool use and should require fewer tokens. I’ll take as many iterations as needed to ensure the code is correct.
- dncornholio 10mo ago
  Because it's stateless it's not pointless? Good codebases don't change fast. Stuff gets added but for the most stuff, they shouldn't change.
  - aiibe 10mo ago
    A well-documented codebase lets both developers and agentic models locate relevant code easily. If you treat the model like a teammate, extra docs for LLMs are unnecessary. IMHO. In frontend work, code moves quickly.
- samuelknight 10mo ago
  I use .md to tell the model about my development workflow. Along the lines of "here's how you lint", "do this to re-generate the API", "this is how you run unit tests", "The sister repositories are cloned here and this is what they are for". One may argue that these should go in a README.md, but these markdowns are meant to be more streamlined for context, and it's not appropriate to put a one-liner in the imperative tone to fix model behavior in a top-level file like the README.md
philipp-gayret 10mo ago
I find writing a good CLAUDE.md is done by running /init, and having the LLM write it. If you need more controls on how it should work, I would highly recommend you implement it in an unavoidable way via hooks and not in a handwritten note to your LLM.
jankdc 10mo ago
I'm not sure if Claude Code has integrated it in its system prompts or not since it's moving at breakneck speed, but one instruction I like putting on all of my projects is to "Prompt for technical decisions from user when choices are unsure". This would almost always trigger the prompting feature that Claude Code has for me when it's got some uncertainty about the instructions I gave it, giving me options or alternatives on how to approach the problem when planning or executing. This way, it's got more of a chance in generating something that I wanted, rather than running off on it's own.
saberience 10mo ago
I find the Claude.md file mostly useless. It seems to be 50/50 or LESS that Claude.md even reads/uses this file. 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.
uncletaco 10mo ago
Honestly I’d rather google get their gemini tool in better shape. I know for a fact it doesn’t ignore instructions like Claude code does but it is horrible at editing files.
rcarmo 10mo ago
PSA: Claude can also use .github/copilot-instructions.md 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).
fpauser 10mo ago
Even better: learn to code yourself.
alan-jordan13 10mo ago
[dead]
jason-richar15 10mo ago
[dead]
_august 10mo ago
I copied this post and gave it to claude code, and had it self-modify CLAUDE.md. It.. worked really well.
scelerat 10mo ago
> we recommend keeping task-specific instructions in separate markdown files with self-descriptive names somewhere in your project. 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.
- abustamam 10mo ago
  There's a funny joke I heard that they made Claude Code only to force developers to write better documentation. But in all seriousness, it's working. I write cursor rules religiously and I point other devs to them. Its great.
- minor3 10mo ago
  Yeah I do love how many "best practices" we are only implementing because of LLMs, even though they were massively beneficial for humans prior as well.
vaer-k 10mo ago
> we recommend keeping task-specific instructions in separate markdown files with self-descriptive names somewhere in your project. 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-practices https://www.anthropic.com/engineering/claude-code-best-pract...
andai 10mo ago
>Frontier thinking LLMs can follow ~ 150-200 instructions with reasonable consistency. 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.
rootnod3 10mo ago
Here's an idea for LLM makers: allow for a very rigid and structured Claude.md file. One that gives detailed instructions, as void of ambiguity as possible. Then go and refine said language, allow maybe for more than one file to give it some file structure. Iterate on that for a few years and if you ever need a name for it, you might wanna give it a name describing something that describes a program, or maybe if you are inclined enough....a programming language. 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?
sixothree 10mo ago
I pointed CC to this URL and told it to fix my files in planning mode. It gave me some options and did all of the work.
kirso 10mo ago
I always read these articles and always fail to find a good example of CLAUDE.md Why not just to show one?

748 points by objcts 10mo ago

"You can investigate this yourself by putting a logging proxy between the claude code CLI and the Anthropic API using ANTHROPIC_BASE_URL" I'd be eager to read a tutorial about that I never know which tool to favour for doing that when you're not a system or network expert.

fishmicrowaver 10mo ago
Have you considered just asking claude? I'd wager you'd get up and running in <10 minutes.
- dhorthy 10mo ago
  agree - i've had claude one-shot this for me at least 10 times at this point cause i'm too lazy to lug whatever code around. literally made a new one this morning
- eric-burel 10mo ago
  AI is good for discovery but not validation, I wanted experienced human feedback here
0xblacklight 10mo ago
Hi, post author here We used cloudflare’s AI gateway which is pretty simple. Set one up, get the proxy URL and set it through the env var, very plug-and-play
- eric-burel 10mo ago
  Smart, thanks for the tip
Havoc 10mo ago
Just install mitmproxy. Takes like 5 mins to figure out. 2 with Claude. On phone else I’d post commands

jasonjmcghee 10mo ago

Interesting selection of models for the "instruction count vs. accuracy" plot. Curious when that was done and why they chose those models. How well does ChatGPT 5/5.1 (and codex/mini/nano variants), Gemini 3, Claude Haiku/Sonnet/Opus 4.5, recent grok models, Kimi 2 Thinking etc (this generation of models) do?

alansaber 10mo ago
Guessing they included some smaller models just to show how they dump accuracy at smaller context sizes
- jasonjmcghee 10mo ago
  Sure - I was more commenting that they are all > 6 months old, which sounds silly, but things have been changing fast, and instruction following is definitely an area that has been developing a lot recently. I would be surprised if accuracy drops off that hard still.
  - 0xblacklight 10mo ago
    I imagine it’s highly-correlated to parameter count, but the research is a few months old and frontier model architecture is pretty opaque so hard to draw too too many conclusions about newer models that aren’t in the study besides what I wrote in the post

vladsh 10mo ago

What is a good Claude.md?

testdelacc1 10mo ago
Claude.md - A markdown file you add to your code repository to explain how things work to Claude. A good Claude.md - I don’t know, presumably the article explains.

andersco 10mo ago

I have found enabling the codebase itself to be the “Claude.md” to be most effective. In other words, set up effective automated checks for linting, type checking, unit tests etc and tell Claude to always run these before completing a task. If the agent keeps doing something you don’t like, then a linting update or an additional test often is more effective than trying to tinker with the Claude.md file. Also, ensure docs on the codebase are up to date and tell Claude to read relevant parts when working on a task and of course update the docs for each new task. YMMV but this has worked for me.

szundi 10mo ago
[dead]
Aeolun 10mo ago
> Also, ensure docs on the codebase are up to date and tell Claude to read relevant parts when working on a task Yeah, if you do this every time it works fine. If you add what you tell it every time to CLAUDE.md, it also works fine, but you don’t have to tell it any more ;)
Havoc 10mo ago
> Claude.md It’s case sensitive btw. CLAUDE.md - Might explain your mixed results with it

prettyblocks 10mo ago

The advice here seems to assume a single .md file with instructions for the whole project, but the AGENTS.md methodology as supported by agents like github copilot is to break out more specific AGENTS.md files in the subdirectories in your code base. I wonder how and if the tips shared change assuming a flow with a bunch of focused AGENTS.md files throughout the code.

0xblacklight 10mo ago
Hi, post author here :) I didn’t dive into that because in a lot of cases it’s not necessary and I wanted to keep the post short, but for large monorepos it’s a good idea

btbuildem 10mo ago

It seems overall a good set of guidelines. I appreciate some of the observations being backed up by data. 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.

_pdp_ 10mo ago

There is far much easier way to do this and one that is perfectly aligned with how these tools work. 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.

dhorthy 10mo ago
For the record I do think the AI community tries to unnecessarily reinvent the wheel on crap all the time. sure, readme.md is a great place to put content. But there's things I'd put in a readme that I'd never put in a claude.md if we want to squeeze the most out of these models. Further, claude/agents.md have special quality-of-life mechanics with the coding agent harnesses like e.g. `injecting this file into the context window whenever an agent touches this directory, no matter whether the model wants to read it or not` > What people often forget about LLMs is that they are largely trained on public information which means that nothing new needs to be invented. I don't think this is relevant at all - when you're working with coding agents, the more you can finesse and manage every token that goes into your model and how its presented, the better results you can get. And the public data that goes into the models is near useless if you're working in a complex codebase, compared to the results you can get if you invest time into how context is collected and presented to your agent.
- theshrike79 10mo ago
  > For the record I do think the AI community tries to unnecessarily reinvent the wheel on crap all the time. On Reddit's LLM subreddits people are rediscovering the very basics of software project management as some massive insights daily or very least weekly. Who would've guessed that proper planning, accessible and up to documentation and splitting tasks into manageable testable chunks produces good code? Amazing! Then they write a massive blog post or even some MCP mostrosity for it and post it everywhere as a new discovery =)

candiddevmike 10mo ago

None of this should be necessary if these tools did what they say on the tin, and most of this advice will probably age like milk. Write readmes for humans, not LLMs. That's where the ball is going.

0xblacklight 10mo ago
Hi, post author here :) Yes README.md should still be written for humans and isn’t going away anytime soon. CLAUDE.md is a convention used by claude code, and AGENTS.md is used by other coding agents. Both are intended to be supplemental to the README and are deterministically injected into the agent’s context. It’s a configuration point for the harness, it’s not intended to replace the README. Some of the advice in here will undoubtedly age poorly as harnesses change and models improve, but some of the generic principles will stay the same - e.g. that you shouldn’t use an LLM to do a linter &formatter’s job, or that LLMs are stateless and need to be onboarded into the codebase, and having some deterministically-injected instructions to achieve that is useful instead of relying on the agent to non-deterministically derive all that info by reading config and package files The post isn’t really intended to be super forward-looking as much as “here’s how to use this coding agent harness configuration point as best as we know how to right now”
- teiferer 10mo ago
  > you shouldn’t use an LLM to do a linter &formatter’s job, Why is that good advice? If that thing is eventually supposed to do the most tricky coding tasks, and already a year ago could have won a medal at the informatics olympics, then why wouldn't it eventually be able to tell if I'm using 2 or 4 spaces and format my code accordingly? Either it's going to change the world, then this is a trivial task, or it's all vaporware, then what are we even discussing.. > or that LLMs are stateless and need to be onboarded into the codebase What? Why would that be a reasonable assumption/prediction for even near term agent capabilities? Providing it with some kind of local memory to dump its learned-so-far state of the world shouldn't be too hard. Isn't it supposed to already be treated like a junior dev? All junior devs I'm working with remember what I told them 2 weeks ago. Surely a coding agent can eventually support that too. This whole CLAUDE.md thing seems a temporary kludge until such basic features are sorted out, and I'm seriously surprised how much time folks are spending to make that early broken state less painful to work with. All that precious knowledge y'all are building will be worthless a year or two from now.

rootusrootus 10mo ago

Ha, I just tell Claude to write it. My results have been generally fine, but I only use Claude on a simple codebase that is well documented already. Maybe I will hand-edit it to see if I can see any improvements.

serial_dev 10mo ago

I’m sure I’m just working like a caveman, but I simply highlight the relevant code, add it to the chat, and talk to these tools as if they were my colleagues and I’m getting pretty good results. 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.

vanviegen 10mo ago
> I simply highlight the relevant code, add it to the chat, and talk to these tools Different use case. I assume the discussion is about having the agent implement whole features or research and fix bugs without much guidance.
- 0xblacklight 10mo ago
  Yep it is opinionated for how to get coding agents to solve hard problems in complex brownfield codebases which is what we are focused on at humanlayer :)
rmnclmnt 10mo ago
Matches my experience also. Bothered only once to setup a proper CLAUDE.md file, and now never do it. Simply refering to the context properly for surgical recommendations and edit works relatively well. It feels a lot like bikeshedding to me, maybe I’m wrong
wredcoll 10mo ago
How about a list of existing database tables/columns so you don't need to repeat it each time?
- anonzzzies 10mo ago

gonzalohm 10mo ago

Probably a lot of people here disagree with this feeling. But my take is that if setting up all the AI infrastructure and onboarding to my code is going to take this amount of effort, then I might as well code the damn thing myself which is what I'm getting paid to (and enjoy doing anyway)

vanviegen 10mo ago
Perhaps. But keep in mind that the setup work is typically mostly delegated to LLMs as well.
fragmede 10mo ago
Whether it's setting up AI infrastructure or configuring Emacs/vim/VSCode, the important distinction to make is if the cost has to be paid continually, or if it's a one time/intermittent cost. If I had to configure my shell/git aliases every time I booted my computer, I wouldn't use them, but seeing as how they're saved in config files, they're pretty heavily customized by this point. Don't use AI if you don't want to, but "it takes too much effort to set up" is an excuse printf debuggers use to avoid setting up a debugger. Which is a whole other debate though.
- bird0861 10mo ago
  I fully agree with this POV but for one detail; there is a problem with sunsetting frontier models. As we begin to adopt these tools and build workflows with them, they become pieces of our toolkit. We depend on them. We take them for granted even. And then the model either changes (new checkpoints, maybe alignment gets fiddled with) and all of the sudden prompts no longer yield the same results we expected from them after working on them for quite some time. I think the term for this is "prompt instability". I felt this with Gemini 3 (and some people had less pronounced but similar experience with Sonnet releases after 3.7) which for certain tasks that 2.5Pro excelled at..it's just unusable now. I was already a local model advocate before this but now I'm a local model zealot. I've stopped using Gemini 3 over this. Last night I used Qwen3 VL on my 4090 and although it was not perfect (sycophancy, overuse of certain cliches...nothing I can't get rid of later with some custom promptsets and a few hours in Heretic) it did a decent enough job of helping me work through my blindspots in the UI/UX for a project that I got what I needed. If we have to perform tuning on our prompts ("skills", agents.md/claude.md, all of the stuff a coding assistant packs context with) every model release then I see new model releases becoming a liability more than a boon.

ctoth 10mo ago

I've gotten quite a bit of utility out of my current setup[0]: 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/d8e629209ff1d9748185b9830fa4e79f https://gist.github.com/ctoth/d8e629209ff1d9748185b9830fa4e7...

johnfn 10mo ago

I was expecting the traditional AI-written slop about AI, but this is actually really good. In particular, the "As instruction count increases, instruction-following quality decreases uniformly" section and associated graph is truly fantastic! To my mind, the ability to follow long lists of rules is one of the most obvious ways that virtually all AI models fail today. That's why I think that graph is so useful -- I've never seen someone go and systematically measure it before! 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.)

0xblacklight 10mo ago
I looked when I wrote the post but the paper hasn’t been revisited with newer models :/

boredtofears 10mo ago

It would be nice to see an actual example of what a good claude.md that implements all of these recommendations looks like.

huqedato 10mo ago

Looking for a similar GEMINI.md

0xblacklight 10mo ago
It might support AGENTS.md, you could check the site and see if it’s there

vunderba 10mo ago

From the article: > 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 Full CLAUDE.md file for reference: https://gist.github.com/scpedicini/179626cfb022452bb39eff10becb95fa https://gist.github.com/scpedicini/179626cfb022452bb39eff10b...

sothatsit 10mo ago
I have also done this, but my results are very hit or miss. Claude rarely actually reads the other documentation files I point it to.
- dhorthy 10mo ago
  I think the key here is “if X then Y syntax” - this seems to be quite effective at piercing through the “probably ignore this” system message by highlighting WHEN a given instruction is “highly relevant”
  - throwaway314155 10mo ago
    What?
    - xpe 10mo ago
      It helps when questions intended to resolve ambiguity are not themselves hopelessly ambiguous. See also: "Help me help you" - https://en.wikipedia.org/wiki/Jerry_Maguire https://en.wikipedia.org/wiki/Jerry_Maguire

tietjens 10mo ago

I think this could work really well for infrastructure/ops style work where the LLM will not be able to grasp the full context of say the network from just a few files that you have open. But as others are saying this is just basic documentation that should be done anyway.

acedTrex 10mo ago

"Here's how to use the slop machine better" is such a ridiculous pretense for a blog or article. You simply write a sentence and it approximates it. That is hardly worth any literature being written as it is so self obvious.

0xblacklight 10mo ago
This is an excellent point - LLMs are autoregressive next-token predictors, and output token quality is a function of input token quality Consider that if the only code you get out of the autoregressive token prediction machine is slop, that this indicates more about the quality of your code than the quality of the autoregressive token prediction machine
- acedTrex 10mo ago
  > that this indicates more about the quality of your code Considering that the "input" to these models is essentially all public code in existence, the direct context input is a drop in the bucket.

johnsmith1840 10mo ago

I don't get the point. Point it at your relevent files ask it to review discuss the update refine it's understanding and then tell it to go. 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.

ra 10mo ago
This is exactly right. Attention is all you need. It's all about attention. Attention is finite. The more you data load into context the more you dilute attention.
- throwuxiytayq 10mo ago
  people who criticize LLMs for merely regurgitating statistically related token sequences have very clearly never read a single HN comment
nightski 10mo ago
IMO within the documentation .md files the information density should be very high. Higher than trying to shove the entire codebase into context that is for sure.
- johnsmith1840 10mo ago
  You deffinetly don't just push the entire code base. Previous models required you to be meticulous about your input. A function here a class there. Even now if I am working on REALLY hard problems I will still manually copy and paste code sections out for discussion and algorithm designs. Depends on complexity. This is why I still believe open ai O1-Pro was the best model I've ever seen. The amount of compute you could throw at a problem was absurd.

malshe 10mo ago

I have been using Claude.md to stuff way too many instructions so this article was an eye opener. Btw, any tips for Claude.md when one uses subagents?

0xcb0 10mo ago

Here is my take, on writing a good claude.md. I had very good results with my 3 file approach. And it has also been inspired by the great blog posts that Human Layer is publishing from time to time https://github.com/marcuspuchalla/claude-project-management https://github.com/marcuspuchalla/claude-project-management

mmaunder 10mo ago

That paper the article references is old at this point. No GPT 5.1, no Gemini 3, which both were game changers. I'd love to see their instruction following graphs.

0xblacklight 10mo ago
Same!

grishka 10mo ago

Oh yeah I added a CLAUDE.md to my project the other day: https://github.com/grishka/Smithereen/blob/master/CLAUDE.md https://github.com/grishka/Smithereen/blob/master/CLAUDE.md Is it a good one?

lijok 10mo ago
I copy/pasted it into my codebase to see if it’s any good and now Claude is refusing to do any work? I asked Copilot to investigate why Claude is not working but it too is not working. Do you know what happened?
wizzledonker 10mo ago
Definitely a good one - probably one of the best CLAUDE.md files you can put in any repository if you care about your project at all.

max-privatevoid 10mo ago

The only good Claude.md is a deleted Claude.md.

rvz 10mo ago
This is the only correct answer.

deleted 10mo ago

[deleted]

VimEscapeArtist 10mo ago

What's the actual completion rate for Advent of Code? I'd bet the majority of participants drop off before day 25, even among those aiming to complete it. Is this intentional? Is AoC designed as an elite challenge, or is the journey more important than finishing?

philipwhiuk 10mo ago
Wrong article. I rarely get past 18 or so. The stats for last year are here: https://adventofcode.com/2024/stats https://adventofcode.com/2024/stats

DR_MING 10mo ago

I already forgot CLAUDE.md, I generate and update it by AI, I prefer to keep design, tasks, docs folder instead. It is always better to ask it to read a some spec docs and read the real code first before doing anything.

nico 10mo ago

> Claude often ignores CLAUDE.md > 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

stingraycharles 10mo ago
That’s hilarious and a great way to test this. What I’m surprised about is that OP didn’t mention having multiple CLAUDE.md files in each directory, specifically describing the current context / files in there. Eg if you have some database layer and want to document some critical things about that, put it in “src/persistence/CLAUDE.md” instead of the main one. Claude pulls in those files automatically whenever it tries to read a file in that directory. I find that to be a very effective technique to leverage CLAUDE.md files and be able to put a lot of content in them, but still keep them focused and avoid context bloat.
- sroussey 10mo ago
  Ummm… sounds like that directory should have a readme. And Claude should read readme files.
  - stingraycharles 10mo ago
    READMEs are written for people, CLAUDE.mds are written for coding assistants. I don’t write “CRITICAL (PRIORITY 0):” in READMEs. The benefit of CLAUDE.md files is that they’re pulled in automatically, eg if Claude wants to read “tests/foo_test.py” it will automatically pull in “tests/CLAUDE.md” (if it exists).
    - adastra22 10mo ago

deleted 10mo ago

[deleted]

deleted 10mo ago

[deleted]

deleted 10mo ago

[deleted]

astrostl 10mo ago

I have Claude itself write CLAUDE.md. Once it is informed of its context (e.g., "README.md is for users, CLAUDE.md is for you") you can say things like, "update readme and claudemd" and it will do it. I find this especially useful for prompts like, "update claudemd to make absolutely certain that you check the API docs every single time before making assumptions about its behavior" — I don't need to know what magick spell will make that happen, just that it does happen.

dexwiz 10mo ago
Do you have any proof that AI written instructions are better than human ones? I don't see why an AI would have an innate understanding on how best to prompt itself.
- michaelbuckbee 10mo ago
  Generally speaking it has a lot of information from things like OP's blog post on how best to structure the file and prompt itself and you can also (from within Claude Code) ask it to look at posts or Anthropic prompting best practices and adopt those to your own file.
- astrostl 10mo ago
  Having been through cycles of manual writing with '#' and having it do it itself, it seems to have been a push on efficacy while spending less effort and getting less frustrated. Hard to quantify except to say that I've had great results with it. I appreciate the spirit of OP's, "CLAUDE.md is the highest leverage point of the harness, so avoid auto-generating it" but you can always ask Claude to tighten it up itself too.
chickensong 10mo ago
This will start to break down after a while unless you have a small project, for reasons being described in the article.

brcmthrowaway 10mo ago

Is CLAUDE.md required when claude has a --continue option?

Zerot 10mo ago
I would recommend using it, yeah. You have limited context and it will be compacted/summarized occasionally. The compaction/summary will lose some information and it is easy for it to forget certain instructions you gave it. Afaik claude.md will be loaded into the context on every compaction which allows you to use it for instructions that should always be included in the context.

bryanhogan 10mo ago

I've been very satisfied with creating a short AGENTS.md file with the project basics, and then also including references to where to find more information / context, like a /context folder that has markdown files such as app-description.md.

m13rar 10mo ago

I was waiting for someone to build this so that I can chuck it into CLAUDE and tell it how to write good MD.

foobarbecue 10mo ago

Funny how this is exactly the documentation you'd need to make it easy for a human to work with the codebase. Perhaps this'll be the greatest thing about LLMs -- they force people to write developer guides for their code. Of course, people are going to ask an LLM to write the CLAUDE.md and then it'll just be more slop...

chickensong 10mo ago
It's not exactly the doc you'd need for a human. There could be overlap, but each side may also have unique requirements that aren't necessarily suitable for the other. E.g. a doc for a human may have considerably more information than you'd want to give to the agent, or, you may want to define agent behavior for workflows that don't apply to a human. Also, while it may be hip to call any LLM output slop, that really isn't the case. Look at what a poor history we have of developer documentation. LLMs may not be great at everything, but they're actually quite capable when it comes to technical documentation. Even a 1-shot attempt by LLM is often way better than many devs who either can't write very well, or just can't be bothered to.

AndyNemmity 10mo ago

it's always funny, i think the opposite. I use a massive CLAUDE.md file, but it's targetted towards very specific details of what to do, and what not to do. 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.

deleted 10mo ago

[deleted]

Ozzie_osman 10mo ago

Has anyone had success getting Claude to write it's own Claude.md file? It should be able to deduce rules by looking at the code, documentation, and PR comments.

handoflixue 10mo ago
The main failure state I find is that Claude wants to write an incredibly verbose Claude.md, but if I instruct it "one sentence per topic, be concise" it usually does a good job. That said, a lot of what it can deduce by looking at the code is exactly what you shouldn't include, since it will usually deduce that stuff just by interacting with the code base. Claude doesn't seem good at that. An example of both overly-verbose and unnecessary: ### 1. Identify the Working Directory When a user asks you to work on something: 1. *Check which project* they're referring to 2. *Change to that directory* explicitly if needed 3. *Stay in that directory* for file operations ```bash # Example: Working on ProjectAlpha cd /home/user/code/ProjectAlpha ``` (The one sentence version is "Each project has a subfolder; use pwd to make sure you're in the right directory", and the ideal version is probably just letting it occasionally spend 60 seconds confused, until it remembers pwd exists)
chickensong 10mo ago
If you have any substantial codebase, it will write a massive file unless you explicitly tell it not to. It also will try and make updates, including garbage like historical or transitional changes, project status, etc... I think most people who use Claude regularly have probably come to the same conclusions as the article. A few bits of high-level info, some behavior stuff, and pointers to actual docs. Load docs as-needed, either by prompt or by skill. Work through lists and constantly update status so you can clear context and pick up where you left off. Any other approach eats too much context. If you have a complex feature that would require ingesting too many large docs, you can ask Claude to determine exactly what it needs to build the appropriate context for that feature and save that to a context doc that you load at the beginning of each session.

wowamit 10mo ago

> Regardless of which model you're using, you may notice that Claude frequently ignores your CLAUDE.md file's contents. 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.

adastra22 10mo ago

> Claude code injects the following system reminder… 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?

edf13 10mo ago

Ah, never knew about this injection… <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

nurettin 10mo ago

I've been a customer since sonnet 3.5. It is coming to the point where opus 4.5 usually does better than whatever your instructions say on claude.md just by reading your code and having a general sense of what your preferences are. 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.

magictux 10mo ago

I think this is an overall good approach and I've got allright results with a similar approach - I still think that this CLAUDE.md experience is too magical and that Anthropic should really focus on it. 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 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.

toenail 10mo ago

A good Claude.md only needs one line: Read your instructions from Agents.md

ilmj8426 10mo ago

I've recently started using a similar approach for my own projects. providing a high-level architecture overview in a single markdown file really helps the LLM understand the 'why' behind the code, not just the 'how'. Does anyone have a specific structure or template for Claude.md that works best for frontend-heavy projects (like React/Vite)? I find that's where the context window often gets cluttered.

asim 10mo ago

That's a good write up. Very useful to know. I'm sort of on the outside of all this. I've only sort of dabbled and now use copilot quite a lot with claude. What's being said here, reminds me a lot of CPU registers. If you think about the limited space in CPU registers and the processing of information is astounding, how much we're actually able to do. So we actually need higher layers of systems and operating systems to help manage all of this. So it feels like a lot of what's being said. Here will end up inevitably being an automated system or compiler or effectively an operating system. Even something basic like a paging system would make a lot of difference.

aiibe 10mo ago

Writing and updating CLAUDE.md or AGENTS.md feels like pointless to me. Humans are the real audience for documentation. The code changes too fast, and LLMs are stateless anyway. What’s been working is just letting the LLM explore the relevant part of the code to acquire the context, defining the problem or feature, and asking for a couple of ways to tackle it. All in a one short prompt. That usually gets me solid options to pick and build it out. And always do, one session for one problem. This is my lazy approach to getting useful help from an LLM.

arnorhs 10mo ago
I agree with you, however your approach results in much longer LLM development runs, increased token usage and a whole lot of repetitive iterations.
- aiibe 10mo ago
  I’m definitely interested in reducing token usage techniques. But with one session one problem I’ve never hit a context limit yet, especially when the problem is small and clearly defined using divide-and-conquer. Also, agentic models are improving at tool use and should require fewer tokens. I’ll take as many iterations as needed to ensure the code is correct.
dncornholio 10mo ago
Because it's stateless it's not pointless? Good codebases don't change fast. Stuff gets added but for the most stuff, they shouldn't change.
- aiibe 10mo ago
  A well-documented codebase lets both developers and agentic models locate relevant code easily. If you treat the model like a teammate, extra docs for LLMs are unnecessary. IMHO. In frontend work, code moves quickly.
samuelknight 10mo ago
I use .md to tell the model about my development workflow. Along the lines of "here's how you lint", "do this to re-generate the API", "this is how you run unit tests", "The sister repositories are cloned here and this is what they are for". One may argue that these should go in a README.md, but these markdowns are meant to be more streamlined for context, and it's not appropriate to put a one-liner in the imperative tone to fix model behavior in a top-level file like the README.md

philipp-gayret 10mo ago

I find writing a good CLAUDE.md is done by running /init, and having the LLM write it. If you need more controls on how it should work, I would highly recommend you implement it in an unavoidable way via hooks and not in a handwritten note to your LLM.

jankdc 10mo ago

I'm not sure if Claude Code has integrated it in its system prompts or not since it's moving at breakneck speed, but one instruction I like putting on all of my projects is to "Prompt for technical decisions from user when choices are unsure". This would almost always trigger the prompting feature that Claude Code has for me when it's got some uncertainty about the instructions I gave it, giving me options or alternatives on how to approach the problem when planning or executing. This way, it's got more of a chance in generating something that I wanted, rather than running off on it's own.

saberience 10mo ago

I find the Claude.md file mostly useless. It seems to be 50/50 or LESS that Claude.md even reads/uses this file. 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.

uncletaco 10mo ago

Honestly I’d rather google get their gemini tool in better shape. I know for a fact it doesn’t ignore instructions like Claude code does but it is horrible at editing files.

rcarmo 10mo ago

PSA: Claude can also use .github/copilot-instructions.md 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).

fpauser 10mo ago

Even better: learn to code yourself.

alan-jordan13 10mo ago

[dead]

jason-richar15 10mo ago

[dead]

_august 10mo ago

I copied this post and gave it to claude code, and had it self-modify CLAUDE.md. It.. worked really well.

scelerat 10mo ago

> we recommend keeping task-specific instructions in separate markdown files with self-descriptive names somewhere in your project. 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.

abustamam 10mo ago
There's a funny joke I heard that they made Claude Code only to force developers to write better documentation. But in all seriousness, it's working. I write cursor rules religiously and I point other devs to them. Its great.
minor3 10mo ago
Yeah I do love how many "best practices" we are only implementing because of LLMs, even though they were massively beneficial for humans prior as well.

vaer-k 10mo ago

> we recommend keeping task-specific instructions in separate markdown files with self-descriptive names somewhere in your project. 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-practices https://www.anthropic.com/engineering/claude-code-best-pract...

andai 10mo ago

>Frontier thinking LLMs can follow ~ 150-200 instructions with reasonable consistency. 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.

rootnod3 10mo ago

Here's an idea for LLM makers: allow for a very rigid and structured Claude.md file. One that gives detailed instructions, as void of ambiguity as possible. Then go and refine said language, allow maybe for more than one file to give it some file structure. Iterate on that for a few years and if you ever need a name for it, you might wanna give it a name describing something that describes a program, or maybe if you are inclined enough....a programming language. 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?

sixothree 10mo ago

I pointed CC to this URL and told it to fix my files in planning mode. It gave me some options and did all of the work.

kirso 10mo ago

I always read these articles and always fail to find a good example of CLAUDE.md Why not just to show one?