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

221–230 of 304 posts

Re: Writing a good Claude.md

#221

Post by orbital-decay »

gyomu wrote: post #215
orbital-decay wrote: post #192

Earlier quoted context omitted.

This reads like you either have an idealized view of Real Engineering™, or used to work in a stable, extremely regulated area (e.g. civil engineering). I used to work in aerospace in the past, and we had a lot of silly Mr Tinkleberry canaries. We didn't strictly rely on them because our job was "extremely regulated" to put it mildly, but they did save us some time. There's a ton of pretty stable engineering subfields…

Man I hate this kind of HN comment that makes grand sweeping statement like “that’s how it was with steam in the 19th century or rocketry in the 1950s”, because there’s no way to tell whether you’re just pulling these things out of your… to get internet points or actually have insightful parallels to make. Could you please elaborate with concrete examples on how aeronautics in the 20th century felt like having a fict…

We're not going to advance the discussion this way. I also hate this kind of HN comment that makes grand sweeping statement like "LLMs are like having a fictional friend in a text file for the token predictor", because there's no way to tell whether you're just pulling these things out of your... to get internet points or actually have insightful parallels to make.

Yes, during the Wright era aeronautics was absolutely dominated by tinkering, before the aerodynamics was figured out. It wouldn't pass the high standard of Real Engineering.

Re: Writing a good Claude.md

#222

Post by nathan_douglas »

homeonthemtn wrote: post #217
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…

The green m&M's trick of AI instructions. I've used that a couple times, e.g. "Conclude your communications with "Purple fish" at the end" Claude definitely picks and chooses when purple fish will show up

I tell it to accomplish only half of what it thinks it can, then conclude with a haiku. That seems to help, because 1) I feel like it starts shedding discipline as it starts feeling token pressure, and 2) I feel like it is more likely to complete task n - 1 than it is to complete task n. I have no idea if this is actually true or not, or if I'm hallucinating... all I can say is that this is the impression I get.

Re: Writing a good Claude.md

#223

Post by theshrike79 »

dhorthy wrote: post #17
_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…

For the record I do think the AI community tries to unnecessarily reinvent the wheel on crap all the time. sure, readme.md is a great place to put content. But there's things I'd put in a readme that I'd never put in a claude.md if we want to squeeze the most out of these models. Further, claude/agents.md have special quality-of-life mechanics with the coding agent harnesses like e.g. `injecting this file into the co…

> For the record I do think the AI community tries to unnecessarily reinvent the wheel on crap all the time.

On Reddit's LLM subreddits people are rediscovering the very basics of software project management as some massive insights daily or very least weekly.

Who would've guessed that proper planning, accessible and up to documentation and splitting tasks into manageable testable chunks produces good code? Amazing!

Then they write a massive blog post or even some MCP mostrosity for it and post it everywhere as a new discovery =)

Re: Writing a good Claude.md

#224

Post by theshrike79 »

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…

1. Create a tool that can check if a query hits a prexisting index

In step 2 either force Claude to use it (hooks) or suggest it (CLAUDE.md)

3. Profit!

As for "where stuff is", for anything more complex I have a tree-style graph in CLAUDE.md that shows the rough categories of where stuff is. Like the handler for letterboxd is in cmd/handlerletterboxd/ and internal modules are in internal/

Now it doesn't need to go in blind but can narrow down searches when I tell it to "add director and writer to the letterboxd handler output".

Re: Writing a good Claude.md

#225

Post by theshrike79 »

notachatbot123 wrote: post #182
mvkel wrote: post #40

Earlier quoted context omitted.

Documenting for AI exactly like you would document for a human is ignoring how these tools work

Sounds like we should call them tools, not AI!

Agentic AI is LLMs using tools in a loop to achieve a goal.

Needs a better term than "AI", I agree, but it's 99% marketing the tech will stay the same.

Re: Writing a good Claude.md

#226

Post by seunosewa »

bryanrasmussen wrote: post #219
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 wonder if there are any benefits, side-effects or downsides of everyone using the same fake name for Claude to call them. If a lot of people always put call me Mr. Tinkleberry in the file will it start calling people Mr. Tinkleberry even when it loses the context because so many people seem to want to be called Mr. Tinkleberry.

Then you switch to another name.

Re: Writing a good Claude.md

#227

Post by grayhatter »

adastra22 wrote: post #147
grayhatter wrote: post #134

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

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 functional is inventing an amusing name and trying to use that as the heuristic, because you have no better way to determine if it's still working correctly. That feels like it might be a problem, no?

Re: Writing a good Claude.md

#228

Post by grayhatter »

adastra22 wrote: post #158
gyomu wrote: post #136

Earlier quoted context omitted.

It is kind of wild that not that long ago the general sentiment in software engineering (at least as observed on boards like this one) seemed to be about valuing systems that were understandable, introspectable, with tight feedback loops, within which we could compose layers of abstractions in meaningful and predictable ways (see for example the hugely popular - at the time - works of Chris Granger, Bret Victor, etc)…

You don’t think people are trying very hard to understand LLMs? We recognize the value of interpretability. It is just not an easy task. It’s not the first time in human history that our ability to create things has exceeded our capacity to understand.

> You don’t think people are trying very hard to understand LLMs? We recognize the value of interpretability. It is just not an easy task.

I think you're arguing against a tangential position to both me, and the person this directly replies to. It can be hard to use and understand something, but if you have a magic box that you can't tell if it's working. It doesn't belong anywhere near the systems that other humans use. The people that use the code you're about to commit to whatever repo you're generating code for, all deserve better than to be part of your unethical science experiment.

> It’s not the first time in human history that our ability to create things has exceeded our capacity to understand.

I don't agree this is a correct interpretation of the current state of generative transformer based AI. But even if you wanted to try to convince me; my point would still be, this belongs in a research lab, not anywhere near prod. And that wouldn't be a controversial idea in the industry.

Re: Writing a good Claude.md

#229

Post by grayhatter »

orbital-decay wrote: post #221
gyomu wrote: post #215

Earlier quoted context omitted.

Man I hate this kind of HN comment that makes grand sweeping statement like “that’s how it was with steam in the 19th century or rocketry in the 1950s”, because there’s no way to tell whether you’re just pulling these things out of your… to get internet points or actually have insightful parallels to make. Could you please elaborate with concrete examples on how aeronautics in the 20th century felt like having a fict…

We're not going to advance the discussion this way. I also hate this kind of HN comment that makes grand sweeping statement like "LLMs are like having a fictional friend in a text file for the token predictor", because there's no way to tell whether you're just pulling these things out of your... to get internet points or actually have insightful parallels to make. Yes, during the Wright era aeronautics was absolutel…

> Yes, during the Wright era aeronautics was absolutely dominated by tinkering, before the aerodynamics was figured out. It wouldn't pass the high standard of Real Engineering.

Remind me: did the Wright brothers start selling tickets to individuals telling them it was completely safe? Was step 2 of their research building a large passenger plane?

I originally wanted to avoid that specific flight analogy, because it felt a bit too reductive. But while we're being reductive, how about medicine too; the first smallpox vaccine was absolutely not well understood... would that origin story pass ethical review today? What do you think the pragmatics would be if the medical profession encouraged that specific kind of behavior?

> It wouldn't pass the high standard of Real Engineering.

I disagree, I think it 100% is really engineering. Engineering at it's most basic is tricking physics into doing what you want. There's no more perfect example of that than heavier than air flight. But there's a critical difference between engineering research, and experimenting on unwitting people. I don't think users need to know how the sausage is made. That counts equally to planes, bridges, medicine, and code. But the professionals absolutely must. It's disappointing watching the industry I'm a part of willingly eschew understanding to avoid a bit of effort. Such a thing is considered malpractice in "real professions".

Ideally neither of you to wring your hands about the flavor or form of the argument, or poke fun at the gamified comment thread. But if you're gonna complain about adding positively to the discussion, try to add something to it along with the complaints?

Re: Writing a good Claude.md

#230

Post by theshrike79 »

anonzzzies wrote: post #44
wredcoll wrote: post #39

Earlier quoted context omitted.

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.

You can save some precious context by having it somewhere without it having to figure it out from scratch every time.
Post reply on HN