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.
Writing a good Claude.md
181–190 of 304 posts
Re: Writing a good Claude.md
#182Earlier quoted context omitted.
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…
Documenting for AI exactly like you would document for a human is ignoring how these tools work
Sounds like we should call them tools, not AI!
Re: Writing a good Claude.md
#183Writing 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 opt…
I agree with you, however your approach results in much longer LLM development runs, increased token usage and a whole lot of repetitive iterations.
Re: Writing a good Claude.md
#184There 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…
Writing documentation for LLMs is strangely pleasing because you have very linear returns for every bit of effort you spend on improving its quality and the feedback loop is very tight. When writing for humans, especially internal documentation, I’ve found that these returns are quickly diminishing or even negative as it’s difficult to know if people even read it or if they didn’t understand it or if it was incomplete.
Re: Writing a good Claude.md
#185> 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 Tinkle…
It baffles me how people can be happy working like this. "I wrap the hammer in paper so if the paper breaks I know the hammer has turned into a saw."
probably by not thinking in ridiculous analogies that don't help
Re: Writing a good Claude.md
#186> 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 Tinkle…
That's smart, but I worry that that works only partially; you'll be filling up the context window with conversation turns where the LLM consistently addresses it's user as "Mr. Tinkleberry", thus reinforcing that specifc behavior encoded by CLAUDE.md. I'm not convinced that this way of addressing the user implies that it keeps attention the rest of the file.
Re: Writing a good Claude.md
#187I 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.
Re: Writing a good Claude.md
#188Writing 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 opt…
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.
Re: Writing a good Claude.md
#189Re: Writing a good Claude.md
#190> 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 Tinkle…
It baffles me how people can be happy working like this. "I wrap the hammer in paper so if the paper breaks I know the hammer has turned into a saw."
If you have any experience in 3D modeling, I feel it's quite closer to 3D Unwrapping than software development.
You got a bitmap atlas ("context") where you have to cram as much information as possible without losing detail, and then you need to massage both your texture and the structure of your model so that your engine doesn't go mental when trying to map your informations from a 2D to a 3D space.
Likewise, both operations are rarely blemish-free and your ability resides in being able to contain the intrinsic stochastic nature of the tool.