Writing a good Claude.md • Hacker News Board

Re: Writing a good Claude.md

#201

Post by giancarlostoro » Mon, Dec 01, 2025, 12:15 PM UTC

stingraycharles wrote: post #162

llbeansandrice wrote: post #151

Earlier quoted context omitted.

If AI is supposed to deliver on this magical no-lift ease of use task flexibility that everyone likes to talk about I think it should be able to work with a README instead of clogging up ALL of my directories with yet another fucking config file. Also this isn’t portable to other potential AI tools. Do I need 3+ md files in every directory?

It’s not delivering on magical stuff. Getting real productivity improvements out of this requires engineering and planning and it needs to be approached as such. One of the big mistakes I think is that all these tools are over-promising on the “magic” part of it. It’s not. You need to really learn how to use all these tools effectively. This is not done in days or weeks even, it takes months in the same way becoming…

Yeah I feel like on average I still spend a similar amount of time developing but drastically less time fixing obscure bugs, because once it codes the feature and I describe the bugs it fixed them, the rest of my times spent testing and reviewing code.

Re: Writing a good Claude.md

#202

Post by pacifika » Mon, Dec 01, 2025, 12:28 PM UTC

globular-toast wrote: post #172

nico wrote: post #82

> 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."

> It Is Difficult to Get a Man to Understand Something When His Salary Depends Upon His Not Understanding It

Re: Writing a good Claude.md

#203

Post by pacifika » Mon, Dec 01, 2025, 12:32 PM UTC

grayhatter wrote: post #134

crystal_revenge wrote: post #122

Earlier quoted context omitted.

I suspect you’re misjudging the friend here. This sounds more like the famous “no brown m&ms” clause in the Van Halen performance contract. As ridiculous as the request is, it being followed provides strong evidence that the rest (and more meaningful) of the requests are. Sounds like the friend understands quite well how LLMs actually work and has found a clever way to be signaled when it’s starting to go off the rai…

> I suspect you’re misjudging the friend here. This sounds more like the famous “no brown m&ms” clause in the Van Halen performance contract. As ridiculous as the request is, it being followed provides strong evidence that the rest (and more meaningful) of the requests are. I'd argue, it's more like you've bought so much into the idea this is reasonable, that you're also willing to go through extreme lengths to recon…

This could be a very niche standup comedy routine, I approve.

Re: Writing a good Claude.md

#204

Post by uncletaco » Mon, Dec 01, 2025, 12:38 PM UTC

avereveard wrote: post #200

_pdp_ wrote: post #13

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…

Well, no. You run pretty fast into context limit (or attention limit for long context models) And the model understand pretty well what code does without documentation. Theres also a question of processes. How to format code what style of catching to use and how to run the tests, which human keep on the bacl of their head after reading it once or twice but need a constant reminder for llm whose knowledge lifespan is…

I’m pretty sure Claude would not work well in my code base if I hadn’t meticulously added docstrings, type hints, and module level documentation. Even if you’re stubbing out code for later implementation, it helps to go ahead and document it so that a code assistant will get a hint of what to do next.

Re: Writing a good Claude.md

#205

Post by uncletaco » Mon, Dec 01, 2025, 12:41 PM UTC

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.

Re: Writing a good Claude.md

#206

Post by sesm » Mon, Dec 01, 2025, 12:46 PM UTC

nico wrote: post #82

> 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…

We are back to color-sorted M&Ms bowls.

Re: Writing a good Claude.md

#207

Post by Sammi » Mon, Dec 01, 2025, 1:01 PM UTC

sothatsit wrote: post #95

vunderba wrote: post #41

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 have also done this, but my results are very hit or miss. Claude rarely actually reads the other documentation files I point it to.

Yeah I don't trust any agent to follow document references consistently. I just manually add the relevant files to context every single time.

Though I know some people who have built an mcp that does exactly this: https://www.usable.dev/

It's basically a chat-bot frontend to your markdown files, with both rag and graph db indexes.

Re: Writing a good Claude.md

#208

Post by aiibe » Mon, Dec 01, 2025, 1:05 PM UTC

arnorhs wrote: post #183

aiibe wrote: post #181

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 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.

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.

Re: Writing a good Claude.md

#209

Post by samuelknight » Mon, Dec 01, 2025, 1:06 PM UTC

aiibe wrote: post #181

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 opt…

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

Re: Writing a good Claude.md

#210

Post by Alpha_Logic » Mon, Dec 01, 2025, 1:09 PM UTC

grayhatter wrote: post #120

nico wrote: post #82

> 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…

> 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 this is a totally normal thing that everyone does, that no one should view as a signal of a psychotic break from reality... is your friend in the room with us right now? I doubt I'll ever understand t…

The 'canary in the coal mine' approach (like the Mr. Tinkleberry trick) is silly but pragmatic. Until we have deterministic introspection for LLMs, engineers will always invent weird heuristics to detect drift. It's not elegant engineering, but it's effective survival tactics in a non-deterministic loop.