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

251–260 of 304 posts

Re: Writing a good Claude.md

#251

Post by adastra22 »

grayhatter wrote: post #227
adastra22 wrote: post #147

Earlier quoted context omitted.

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!

I am blaming the developers who use AI because they're willing to sacrifice intellectual control in trade for something that I find has minimal value. I agree it's likely to be a complex or intractable problem. But I don't enjoy watching my industry revert down the professionalism scale. Professionals don't choose tools that they can't explain how it works. If your solution to understanding if your tool is still func…

I’m sorry you don’t like it. But this has very strong old-man-yells-at-cloud vibes. This train is moving, whether you want it to or not.

Professionals use tools that work, whether they know why it works is of little consequence. It took 100 years to explain the steam engine. That didn’t stop us from making factories and railroads.

Re: Writing a good Claude.md

#252

Post by lubujackson »

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…

For whatever reason, I can't get into Claude's approach. I like how Cursor handles this, with a directory of files (even subdirectories allowed) where you can define when it should use specific documents.

We are all "context engineering" now but Claude expects one big file to handle everything? Seems luke a deadend approach.

Re: Writing a good Claude.md

#253

Post by xpe »

throwaway314155 wrote: post #126
dhorthy wrote: post #100

Earlier quoted context omitted.

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”

What?

It helps when questions intended to resolve ambiguity are not themselves hopelessly ambiguous.

See also: "Help me help you" - https://en.wikipedia.org/wiki/Jerry_Maguire

Re: Writing a good Claude.md

#254

Post by wry_discontent »

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.

That makes sense given that it's trained on real world developers.

Re: Writing a good Claude.md

#255

Post by piokoch »

lubujackson wrote: post #252
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…

For whatever reason, I can't get into Claude's approach. I like how Cursor handles this, with a directory of files (even subdirectories allowed) where you can define when it should use specific documents. We are all "context engineering" now but Claude expects one big file to handle everything? Seems luke a deadend approach.

This is good for the company, chances are you will eat more tokens. I liked Aider approach, it wasn't trying to be too clever, it used files added to chat and asks if it figure out that something more is needed (like, say, settings in case of Django application).

Sadly Aider is no longer maintained...

Re: Writing a good Claude.md

#256

Post by unshavedyak »

lubujackson wrote: post #252
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…

For whatever reason, I can't get into Claude's approach. I like how Cursor handles this, with a directory of files (even subdirectories allowed) where you can define when it should use specific documents. We are all "context engineering" now but Claude expects one big file to handle everything? Seems luke a deadend approach.

I think their skills have the ability to dynamically pull in more data, but so far i've not tested it to much since it seems more tailored towards specific actions. Ie converting a PDF might translate nicely to the Agent pulling in the skill doc, but i'm not sure if it will translate well to it pulling in some rust_testing_patterns.md file when it writes rust tests.

Eg i toyed with the idea of thinning out various CLAUDE.md files in favor of my targeted skill.md files. In doing so my hope was to have less irrelevant data in context.

However the more i thought through this, the more i realized the Agent is doing "everything" i wanted to document each time. Eg i wasn't sure that creating skills/writing_documentation.md and skills/writing_tests.md would actually result in less context usage, since both of those would be in memory most of the time. My CLAUDE.md is already pretty hyper focused.

So yea, anyway my point was that skills might have potential to offload irrelevant context which seems useful. Though in my case i'm not sure it would help.

Re: Writing a good Claude.md

#257

Post by xpe »

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.

I'm skeptical this a valid generalization over what was directly observed. [1] We would learn more if they wrote a more detailed account of their observations. [2]

I'd like to draw a parallel to another area of study possibly unfamiliar to many of us. Anthropology faced similar issues until Geertz's 1970s reform emphasized "thick description" [3] meaning detailed contextual observations instead of thin generalization.

[1]: I would not draw this generalization. I've found that adding guidelines (on the order of 10k tokens) to my CLAUDE.md has been beneficial across all my conversations. At the same time, I have not constructed anything close to study of variations of my approach. And the underlying models are a moving target. I will admit that some of my guidelines were added to address issues I saw over a year ago and may be nothing more than vestigial appendages nowadays. This is why I'm reluctant to generalize.

[2]: What kind of "hard problems"? What is meant by "more" exactly? (Going from 250 to 500 tokens? 1000 to 2000? 2500 to 5000? &c) How much overlap exists between the CLAUDE.md content items? How much ambiguity? How much contradiction?

[3]: https://en.wikipedia.org/wiki/Thick_description

Re: Writing a good Claude.md

#258

Post by jswny »

lubujackson wrote: post #252
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…

For whatever reason, I can't get into Claude's approach. I like how Cursor handles this, with a directory of files (even subdirectories allowed) where you can define when it should use specific documents. We are all "context engineering" now but Claude expects one big file to handle everything? Seems luke a deadend approach.

They have an entire feature for this: https://www.claude.com/blog/skills

CLAUDE.md should only be for persistent reminders that are useful in 100% of your sessions

Otherwise, you should use skills, especially if CLAUDE.md gets too long.

Also just as a note, Claude already supports lazy loaded separate CLAUDE.md files that you place in subdirectories. It will read those if it dips into those dirs

Re: Writing a good Claude.md

#259

Post by acedTrex »

0xblacklight wrote: post #110
acedTrex wrote: post #48

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

This is an excellent point - LLMs are autoregressive next-token predictors, and output token quality is a function of input token quality Consider that if the only code you get out of the autoregressive token prediction machine is slop, that this indicates more about the quality of your code than the quality of the autoregressive token prediction machine

> that this indicates more about the quality of your code

Considering that the "input" to these models is essentially all public code in existence, the direct context input is a drop in the bucket.

Re: Writing a good Claude.md

#260

Post by xpe »

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…

> Humans are the real audience for documentation.

Seeing "real" is a warning flag here that either-or thinking is in play.

Putting aside hopes and norms, we live in a world now where multiple kinds of agents (human and non-human) are contributing to codebases. They do not contribute equally; they work according to different mechanisms, with different strengths and weaknesses, with different economic and cultural costs.

Recall a lesson from Ralph Waldo Emerson: "a foolish consistency is the hobgoblin of little minds" [1]. Don't cling to the past; pay attention to the now, and do what works. Another way of seeing it: don't force a false equivalence between things that warrant different treatment.

If you find yourself thinking thoughts that do more harm than good (e.g. muddle rather than clarify), attempt to reframe them to better make sense of reality (which has texture and complexity).

Here's my reframing: "Documentation serves different purposes to different agents across different contexts. So plan and execute accordingly."

[1]: https://en.wikipedia.org/wiki/Wikipedia:Emerson_and_Wilde_on...

Post reply on HN