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
Writing a good Claude.md
61–70 of 304 posts
Re: Writing a good Claude.md
#62That 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.
Re: Writing a good Claude.md
#63I 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 lo…
> I never give the second to my LLM. How do you practically achieve this? Honest question. Thanks
Custom scripts.
1. Turn off 2. Code 3. Turn on 4. Commit
I also delete all llm comments they 100% poison your codebase.
Re: Writing a good Claude.md
#64Oh yeah I added a CLAUDE.md to my project the other day: https://github.com/grishka/Smithereen/blob/master/CLAUDE.md
Is it a good one?
Re: Writing a good Claude.md
#65The only good Claude.md is a deleted Claude.md.
Re: Writing a good Claude.md
#66[deleted]
Re: Writing a good Claude.md
#67I 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 lo…
> I have found that more context comments and info damage quality on hard problems. There can be diminishing returns, but every time I’ve used Claude Code for a real project I’ve found myself repeating certain things over and over again and interrupting tool usage until I put it in the Claude notes file. You shouldn’t try to put everything in there all the time, but putting key info in there has been very high ROI fo…
Agreed, I don't love the CLAUDE.md that gets autogenerated. It's too wordy for me to understand and for the model to follow consistently.
I like to write my CLAUDE.md directly, with just a couple paragraphs describing the codebase at a high level, and then I add details as I see the model making mistakes.
Re: Writing a good Claude.md
#68What'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?
Re: Writing a good Claude.md
#69Earlier quoted context omitted.
This is missing the point. If I want to instruct Claude to never write a database query that doesn't hit a preexisting index, where exactly am I supposed to document that? You can either choose: 1. A centralized location, like a README (congrats, you've just invented CLAUDE.md) 2. You add a docs folder (congrats, you've just done exactly what the author suggests under Progressive Disclosure) Moreover, you can't just…
You put a warning where it is most likely to be seen by a human coder. Besides, no amount of prompting will prevent this situation. If it is a concern then you put a linter or unit tests to prevent it altogether, or make a wrapper around the tricky function with some warning in its doc strings. I don't see how this is any different from how you typically approach making your code more resilient to accidental mistakes…
> no amount of prompting will prevent this situation.
Again, missing the point. If you don't prompt for it and you document it in a place where the tool won't look first, the tool simply won't do it. "No amount of promoting" couldn't be more wrong, it works for me and all my coworkers.
> If it is a concern then you put a linter or unit tests to prevent it altogether
Sure, and then it'll always do things it's own way, run the tests, and have to correct itself. Needlessly burning tokens. But if you want to pay for it to waste its time and yours, go for it.
> I don't see how this is any different from how you typically approach making your code more resilient to accidental mistakes.
It's not about avoiding mistakes! It's about having it follow the norms of your codebase.
- My codebase at work is slowly transitioning from Mocha to Jest. I can't write a linter to ban new mocha tests, and it would be a pain to keep a list of legacy mocha test suites. The solution is to simply have a bullet point in the CLAUDE.md file that says "don't write new Mocha test suites, only write new test suites in Jest". A more robust solution isn't necessary and doesn't avoid mistakes, it avoids the extra step of telling the LLM to rewrite the tests.
- We have a bunch of terraform modules for convenience when defining new S3 buckets. No amount of documenting the modules will have Claude magically know they exist. You tell it that there are convenience modules and to consider using them.
- Our ORM has findOne that returns one record or null. We have a convenience function getOne that returns a record or throws a NotFoundError to return a 404 error. There's no way to exhaustively detect with a linter that you used findOne and checked the result for null and threw a NotFoundError. And the hassle of maybe catching some instances isn't necessary, because avoiding it is just one line in CLAUDE.md.
It's really not that hard.
Re: Writing a good Claude.md
#70I’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 differe…
How about a list of existing database tables/columns so you don't need to repeat it each time?
Do you not use a model file for your orm?