Writing a good Claude.md • Hacker News Board

Re: Writing a good Claude.md

#41

Post by vunderba » Sun, Nov 30, 2025, 9:29 PM UTC

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/179626cfb022452bb39eff10b...

Re: Writing a good Claude.md

#42

Post by anonzzzies » Sun, Nov 30, 2025, 9:37 PM UTC

mvkel wrote: post #40

_pdp_ wrote: post #34

Earlier 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

But they are right, claude routinely ignores stuff from CLAUDE.md, even with warning bells etc. You need a linter preventing things. Like drizzle sql` templates: it just loves them.

Re: Writing a good Claude.md

#43

Post by jwpapi » Sun, Nov 30, 2025, 9:38 PM UTC

serial_dev wrote: post #20

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

=== myExperience

Re: Writing a good Claude.md

#44

Post by anonzzzies » Sun, Nov 30, 2025, 9:39 PM UTC

wredcoll wrote: post #39

serial_dev wrote: post #20

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

How about a list of existing database tables/columns so you don't need to repeat it each time?

Claude code figures that out at startup every time. Never had issues with it.

Re: Writing a good Claude.md

#45

Post by tietjens » Sun, Nov 30, 2025, 9:54 PM UTC

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.

Re: Writing a good Claude.md

#46

Post by CuriouslyC » Sun, Nov 30, 2025, 9:57 PM UTC

mvkel wrote: post #40

_pdp_ wrote: post #34

Earlier 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

You can make affordances for agent abilities without deviating from what humans find to be good documentation. Use hyperlinks, organize information, document in layers, use examples, be concise. It's not either/or unless you're being lazy.

Re: Writing a good Claude.md

#47

Post by kissgyorgy » Sun, Nov 30, 2025, 9:58 PM UTC

gonzalohm wrote: post #21

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)

I strongly disagree with the author not using /init. It takes a minute to run and Claude provides surprisingly good results.

Re: Writing a good Claude.md

#48

Post by acedTrex » Sun, Nov 30, 2025, 9:58 PM UTC

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

Re: Writing a good Claude.md

#49

Post by johnsmith1840 » Sun, Nov 30, 2025, 10:04 PM UTC

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.

Re: Writing a good Claude.md

#50

Post by malshe » Sun, Nov 30, 2025, 10:17 PM UTC

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?