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

141–150 of 304 posts

Re: Writing a good Claude.md

#141

Post by adastra22 »

jmathai wrote: post #121
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…

I have a /bootstrap command that I run which instructs Claude Code to read all system and project CLAUDE.md files, skills and commands. Helps me quickly whip it back in line.

Isn’t that what every new session does?

Re: Writing a good Claude.md

#142

Post by adastra22 »

> Claude code injects the following system reminder…

OMG this finally makes sense.

Is there any way to turn off this behavior?

Or better yet is there a way to filter the context that is being sent?

Re: Writing a good Claude.md

#143

Post by stingraycharles »

sroussey wrote: post #140
stingraycharles wrote: post #103

Earlier quoted context omitted.

That’s hilarious and a great way to test this. What I’m surprised about is that OP didn’t mention having multiple CLAUDE.md files in each directory, specifically describing the current context / files in there. Eg if you have some database layer and want to document some critical things about that, put it in “src/persistence/CLAUDE.md” instead of the main one. Claude pulls in those files automatically whenever it tri…

Ummm… sounds like that directory should have a readme. And Claude should read readme files.

READMEs are written for people, CLAUDE.mds are written for coding assistants. I don’t write “CRITICAL (PRIORITY 0):” in READMEs.

The benefit of CLAUDE.md files is that they’re pulled in automatically, eg if Claude wants to read “tests/foo_test.py” it will automatically pull in “tests/CLAUDE.md” (if it exists).

Re: Writing a good Claude.md

#144

Post by chickensong »

foobarbecue wrote: post #119

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

It's not exactly the doc you'd need for a human. There could be overlap, but each side may also have unique requirements that aren't necessarily suitable for the other. E.g. a doc for a human may have considerably more information than you'd want to give to the agent, or, you may want to define agent behavior for workflows that don't apply to a human.

Also, while it may be hip to call any LLM output slop, that really isn't the case. Look at what a poor history we have of developer documentation. LLMs may not be great at everything, but they're actually quite capable when it comes to technical documentation. Even a 1-shot attempt by LLM is often way better than many devs who either can't write very well, or just can't be bothered to.

Re: Writing a good Claude.md

#145

Post by bird0861 »

fragmede wrote: post #33
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)

Whether it's setting up AI infrastructure or configuring Emacs/vim/VSCode, the important distinction to make is if the cost has to be paid continually, or if it's a one time/intermittent cost. If I had to configure my shell/git aliases every time I booted my computer, I wouldn't use them, but seeing as how they're saved in config files, they're pretty heavily customized by this point. Don't use AI if you don't want t…

I fully agree with this POV but for one detail; there is a problem with sunsetting frontier models. As we begin to adopt these tools and build workflows with them, they become pieces of our toolkit. We depend on them. We take them for granted even. And then the model either changes (new checkpoints, maybe alignment gets fiddled with) and all of the sudden prompts no longer yield the same results we expected from them after working on them for quite some time. I think the term for this is "prompt instability". I felt this with Gemini 3 (and some people had less pronounced but similar experience with Sonnet releases after 3.7) which for certain tasks that 2.5Pro excelled at..it's just unusable now. I was already a local model advocate before this but now I'm a local model zealot. I've stopped using Gemini 3 over this. Last night I used Qwen3 VL on my 4090 and although it was not perfect (sycophancy, overuse of certain cliches...nothing I can't get rid of later with some custom promptsets and a few hours in Heretic) it did a decent enough job of helping me work through my blindspots in the UI/UX for a project that I got what I needed.

If we have to perform tuning on our prompts ("skills", agents.md/claude.md, all of the stuff a coding assistant packs context with) every model release then I see new model releases becoming a liability more than a boon.

Re: Writing a good Claude.md

#146

Post by adastra22 »

stingraycharles wrote: post #143
sroussey wrote: post #140

Earlier quoted context omitted.

Ummm… sounds like that directory should have a readme. And Claude should read readme files.

READMEs are written for people, CLAUDE.mds are written for coding assistants. I don’t write “CRITICAL (PRIORITY 0):” in READMEs. The benefit of CLAUDE.md files is that they’re pulled in automatically, eg if Claude wants to read “tests/foo_test.py” it will automatically pull in “tests/CLAUDE.md” (if it exists).

Is this documented anywhere? This is the first I have ever heard of it.

Re: Writing a good Claude.md

#147

Post by adastra22 »

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…

It feels like you’re blaming the AI engineers here, that they built it this way out of ignorance or something. Look into interpretability research. It is a hard problem!

Re: Writing a good Claude.md

#148

Post by gravypod »

bird0861 wrote: post #129
TheRoque wrote: post #91

Earlier quoted context omitted.

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

That study is garbo and I suspect you didn't even read the abstract. Am I right?

I've heard this mentioned a few times. Here is a summarized version of the abstract:

    > ... We conduct a randomized controlled trial (RCT)
    > ... AI tools ... affect the productivity of experienced
    > open-source developers. 16 developers with moderate AI
    > experience complete 246 tasks in mature projects on which they
    > have an average of 5 years of prior experience. Each task is
    > randomly assigned to allow or disallow usage of early-2025 AI
    > tools. ... developers primarily use Cursor Pro ... and
    > Claude 3.5/3.7 Sonnet. Before starting tasks, developers forecast that allowing
    > AI will reduce completion time by 24%. After completing the
    > study, developers estimate that allowing AI reduced completion time by 20%.
    > Surprisingly, we find that allowing AI actually increases
    > completion time by 19%—AI tooling slowed developers down. This
    > slowdown also contradicts predictions from experts in economics
    > (39% shorter) and ML (38% shorter). To understand this result,
    > we collect and evaluate evidence for 21 properties of our setting
    > that a priori could contribute to the observed slowdown effect—for
    > example, the size and quality standards of projects, or prior
    > developer experience with AI tooling. Although the influence of
    > experimental artifacts cannot be entirely ruled out, the robustness
    > of the slowdown effect across our analyses suggests it is unlikely
    > to primarily be a function of our experimental design.
So what we can gather:

1. 16 people were randomly given tasks to do

2. They knew the codebase they worked on pretty well

3. They said AI would help them work 24% faster (before starting tasks)

4. They said AI made them ~20% faster (after completion of tasks)

5. ML Experts claim that they think programmers will be ~38% faster

6. Economists say ~39% faster.

7. We measured that people were actually 19% slower

This seems to be done on Cursor, with big models, on codebases people know. There are definitely problems with industry-wide statements like this but I feel like the biggest area AI tools help me is if I'm working on something I know nothing about. For example: I am really bad at web development so CSS / HTML is easier to edit through prompts. I don't have trouble believing that I would be slower trying to make an edit to code that I already know how to make.

Maybe they would see the speedups by allowing the engineer to select when to use the AI assistance and when not to.

Re: Writing a good Claude.md

#149

Post by edf13 »

Ah, never knew about this injection…

IMPORTANT: this context may or may not be relevant to your tasks. You should not respond to this context unless it is highly relevant to your task.

Perhaps a small proxy between Claude code and the API to enforce following CLAUDE.md may improve things… I may try this

Re: Writing a good Claude.md

#150

Post by grumbelbart »

adastra22 wrote: post #146
stingraycharles wrote: post #143

Earlier quoted context omitted.

READMEs are written for people, CLAUDE.mds are written for coding assistants. I don’t write “CRITICAL (PRIORITY 0):” in READMEs. The benefit of CLAUDE.md files is that they’re pulled in automatically, eg if Claude wants to read “tests/foo_test.py” it will automatically pull in “tests/CLAUDE.md” (if it exists).

Is this documented anywhere? This is the first I have ever heard of it.

Here: https://www.anthropic.com/engineering/claude-code-best-pract...

claude.md seems to be important enough to be their very first point in that document.

Post reply on HN