Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Writing a good Claude.md

humanlayer.dev

Post reply on HN
Print view View original

91–100 of 304 posts

Re: Writing a good Claude.md

#91

Post by TheRoque »

nichochar wrote: post #76
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)

The effort described in the article is maybe a couple hours of work. I understand the "enjoy doing anyway" part and it resonates, but not using AI is simply less productive.

> but not using AI is simply less productive

Some studies shows the opposite for experienced devs. And it also shows that developers are delusional about said productivity gains: https://metr.org/blog/2025-07-10-early-2025-ai-experienced-o...

If you have a counter-study (for experienced devs, not juniors), I'd be curious to see. My experience also has been that using AI as part of your main way to produce code, is not faster when you factor in everything.

Re: Writing a good Claude.md

#92

Post by michaelbuckbee »

dexwiz wrote: post #89
astrostl wrote: post #88

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…

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.

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.

Re: Writing a good Claude.md

#93

Post by astrostl »

dexwiz wrote: post #89
astrostl wrote: post #88

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…

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.

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.

Re: Writing a good Claude.md

#94

Post by senshan »

johnsmith1840 wrote: post #63
senshan wrote: post #55

Earlier quoted context omitted.

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

>> 1. The raw code with no empty space or comments. 2. Code with comments

> 1. Turn off 2. Code 3. Turn on 4. Commit

What does it mean "turn off" / "turn on"?

Do you have a script to strip comments?

Okay, after the comments were stripped, does this become the common base for 3-way merge?

After modification of the code stripped of the comments, do you apply 3-way merge to reconcile the changes and the comments?

This seems a lot of work. What is the benefit? I mean demonstrable benefit.

How does it compare to instructing through AGENTS.md to ignore all comments?

Re: Writing a good Claude.md

#95

Post by sothatsit »

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.

Re: Writing a good Claude.md

#96

Post by wormpilled »

Mtinie wrote: post #57
johnsmith1840 wrote: post #49

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

> 1. The raw code with no empty space or comments. 2. Code with comments I like the sound of this but what technique do you use to maintain consistency across both views? Do you have a post-modification script which will strip comments and extraneous empty space after code has been modified?

Curious if that is the case, how you would put comments back too? Seems like a mess.

Re: Writing a good Claude.md

#98

Post by brianwawok »

MarkMarine wrote: post #71
Aurornis wrote: post #60

Earlier quoted context omitted.

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

Setting hooks has been super helpful for me, you can reject certain uses of tools (don’t touch my tests for this session) with just simple scripting code.

Git lint hook has been key. No matter how many times I told it, it lints randomly. Sometimes not at all. Sometime before rubbing tests (but not after fixing test failures).

Re: Writing a good Claude.md

#99

Post by girvo »

bastawhiz wrote: post #69
_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…

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

> There's no way to exhaustively detect with a linter that you used findOne and checked the result for null and threw a NotFoundError

Yes there is? Though this is usually better served with a type checker, it’s still totally feasible with a linter too if that’s your bag

> because avoiding it is just one line in CLAUDE.md.

Except no, it isn’t, because these tools still ignore that line sometimes so I still have to check for it myself.

Re: Writing a good Claude.md

#100

Post by dhorthy »

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.

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”
Post reply on HN