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

111–120 of 304 posts

Re: Writing a good Claude.md

#111

Post by johnsmith1840 »

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?

Custom scripts and basic merge logic but manual still happens around modifications. Forces me to update stale comments around changes anyhow.

I first "discovered" it because I repeatedly found LLM comments poisoned my code base over time and linited it's upper end of ability.

Easy to try just drop comments around a problem and see the difference. I was previously doing that and then manually updating the original.

Re: Writing a good Claude.md

#112

Post by johnsmith1840 »

senshan wrote: post #94
johnsmith1840 wrote: post #63

Earlier quoted context omitted.

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

Telling an AI to ignore comments != no comments that's pretty fundamental to get my point.

Re: Writing a good Claude.md

#113

Post by vunderba »

dimitri-vs wrote: post #109
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…

Correct me if I'm wrong but I think the new "skillss are exactly this, but better.

Yeah I think "Skills" are just a more codified folder based approach to this TOC system. The main reason I haven't migrated yet is that the TOC approach lends itself better to the more generic AGENTS.md style - allowing me to swap over to alternative LLMs (such as Gemini) relatively easily.

Re: Writing a good Claude.md

#114

Post by [deleted] »

Aurornis wrote: post #60
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…

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

[deleted]

Re: Writing a good Claude.md

#115

Post by senshan »

johnsmith1840 wrote: post #112
senshan wrote: post #94

Earlier quoted context omitted.

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

Telling an AI to ignore comments != no comments that's pretty fundamental to get my point.

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

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

So can you describe your "turn off" / "turn on" process in practical terms?

Asking simply because saying "Custom scripts" is similar to saying "magic".

Re: Writing a good Claude.md

#116

Post by ares623 »

TheRoque wrote: post #91
nichochar wrote: post #76

Earlier quoted context omitted.

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

Curious why there hasn't been a rebuttal study to that one yet (or if there is I haven't seen it come up). There must be near infinite funding available to debunk that study right?

Re: Writing a good Claude.md

#118

Post by callc »

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

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…

This CLAUDE.md dance feels like herding cats. Except we’re herding a really good autocorrect encyclopedic parrot. Sans intelligence

Relating / personifying LLM to an engineer doesn’t work out

Maybe the best though model currently is just “good way to automate trivial text modifications” and “encyclopedic ramblings”

Re: Writing a good Claude.md

#119

Post by foobarbecue »

Funny how this is exactly the documentation you'd need to make it easy for a human to work with the codebase. Perhaps this'll be the greatest thing about LLMs -- they force people to write developer guides for their code. Of course, people are going to ask an LLM to write the CLAUDE.md and then it'll just be more slop...

Re: Writing a good Claude.md

#120

Post by grayhatter »

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 the lengths AI enjoyers will go though just to avoid any amount of independent thought...

Post reply on HN