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

271–280 of 304 posts

Re: Writing a good Claude.md

#271

Post by llbeansandrice »

stingraycharles wrote: post #162
llbeansandrice wrote: post #151

Earlier quoted context omitted.

If AI is supposed to deliver on this magical no-lift ease of use task flexibility that everyone likes to talk about I think it should be able to work with a README instead of clogging up ALL of my directories with yet another fucking config file. Also this isn’t portable to other potential AI tools. Do I need 3+ md files in every directory?

It’s not delivering on magical stuff. Getting real productivity improvements out of this requires engineering and planning and it needs to be approached as such. One of the big mistakes I think is that all these tools are over-promising on the “magic” part of it. It’s not. You need to really learn how to use all these tools effectively. This is not done in days or weeks even, it takes months in the same way becoming…

My issue is not with learning. This "tool" has an incredibly shallow learning curve. My issue is that I'm having to make way for these "tools" that everyone says vastly increases productivity but seems to just churn out tech-debt as quickly as it can write it.

It a large leap to "requires engineering and planning" when no one even in this thread can seem to agree on the behavior of any of these "tools". Some comments tell anecdotes of not getting the agents to listen until the context of the whole world is laid out in these md files. Others say the only way is to keep the context tight and focused, going so far as to have written _yet more tools_ to remove and re-add code comments so they don't "poison" the context.

I am slightly straw-manning, but the tone in this thread has already shifted from a few months ago where these "tools" were going to immediately give huge productivity gains but now you're telling me they need 1) their own special files everywhere (again, this isn't even agreed on) and 2) "engineering and planning...not done in days or weeks even

The entire economy is propped up on this tech right now and no one can even agree on whether it's effective or how to use it properly? Not to mention the untold damage it is doing to learning outcomes.

Re: Writing a good Claude.md

#272

Post by grayhatter »

adastra22 wrote: post #268
grayhatter wrote: post #264

Earlier quoted context omitted.

> It took 100 years to explain the steam engine. That didn’t stop us from making factories and railroads. You keep saying this, why do you believe it so strongly? Because I don't believe this is true. Why do you? And then, even assuming it's completely true exactly as stated; shouldn't we have higher standards than that when dealing with things that people interact with? Boiler explosions are bad right? And we should…

Because I’m trained as a physicist and (non-software) engineer and I know my field’s history? Here’s the first result that comes up on Google. Seems accurate from a quick skim: https://www.ageofinvention.xyz/p/age-of-invention-why-wasnt-... And yes we should seek to understand new inventions. Which we are doing right now, in the form of interpretability research. We should not be making Luddite calls to halt progress…

Can you cite a section from this very long page that might convince me no one at the time understood how turning water into steam worked to create pressure?

If this is your industry, shouldn't you have a more reputable citation, maybe something published more formally? Something expected to stand up to peer review, instead of just a page on the internet?

> We should not be making Luddite calls to halt progress simply because our analytic capabilities haven’t caught up to our progress in engineering.

You've misunderstood my argument. I'm not making a luddite call to halt progress, I'm objecting to my industry which should behave as one made up of professionals, willingly sacrifice intellectual control over the things they are responsible for, and advocate others should do the same. Especially not at the expense of users, which I see happening.

Anything that results in sacrificing the understanding over exactly how the thing you built works is bad should be avoided. The source, either AI or something different, doesn't matter as much as the result.

Re: Writing a good Claude.md

#273

Post by philipwhiuk »

VimEscapeArtist wrote: post #68

What's the actual completion rate for Advent of Code? I'd bet the majority of participants drop off before day 25, even among those aiming to complete it. Is this intentional? Is AoC designed as an elite challenge, or is the journey more important than finishing?

Wrong article.

I rarely get past 18 or so. The stats for last year are here: https://adventofcode.com/2024/stats

Re: Writing a good Claude.md

#274

Post by cindyllm »

adastra22 wrote: post #268
grayhatter wrote: post #264

Earlier quoted context omitted.

> It took 100 years to explain the steam engine. That didn’t stop us from making factories and railroads. You keep saying this, why do you believe it so strongly? Because I don't believe this is true. Why do you? And then, even assuming it's completely true exactly as stated; shouldn't we have higher standards than that when dealing with things that people interact with? Boiler explosions are bad right? And we should…

Because I’m trained as a physicist and (non-software) engineer and I know my field’s history? Here’s the first result that comes up on Google. Seems accurate from a quick skim: https://www.ageofinvention.xyz/p/age-of-invention-why-wasnt-... And yes we should seek to understand new inventions. Which we are doing right now, in the form of interpretability research. We should not be making Luddite calls to halt progress…

[dead]

Re: Writing a good Claude.md

#275

Post by andai »

>Frontier thinking LLMs can follow ~ 150-200 instructions with reasonable consistency.

Doesn't that mean that Claude Code's system prompt exhausts that budget before you even get to CLAUDE.md and the user prompt?

Edit: They say Claude Code's system prompt has 50. I might have misjudged then. It seemed pretty verbose to me!

The part about smaller models attending to fewer instructions is interesting too, since most of what was added doesn't seem necessary for the big models. I thought they added them so Haiku could handle the job as well, despite a relative lack of common sense.

Re: Writing a good Claude.md

#276

Post by rootnod3 »

Here's an idea for LLM makers: allow for a very rigid and structured Claude.md file. One that gives detailed instructions, as void of ambiguity as possible. Then go and refine said language, allow maybe for more than one file to give it some file structure. Iterate on that for a few years and if you ever need a name for it, you might wanna give it a name describing something that describes a program, or maybe if you are inclined enough....a programming language.

Have we really reached the low point that we need tutorials on how to coerce a LLM into doing what we want instead of just....writing the god damn code?

Re: Writing a good Claude.md

#278

Post by dkubb »

theshrike79 wrote: post #223
dhorthy wrote: post #17

Earlier quoted context omitted.

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

I can totally understand where you are coming from with this comment. It does feel a bit frustrating that people are rediscovering things that were written in books 30/40/50 years ago.

However, I think this is awesome for the industry. People are rediscovering basic things, but if they didn't know about the existing literature this is a perfect opportunity to refer them to it. And if they were aware, but maybe not practicing it, this is a great time for the ideas to be reinforced.

A lot of people, myself included, never really understand which practices are important or not until we were forced to work on a system that was most definitely not written with any good practices in mind.

My current view of agentic coding is that it's forcing an entire generation of devs to learn software project management or drowning under the mountain of debt an LLM can produce. Previously it took much longer to feel the weight of bad decisions in a project but an LLM allows you to speed-run this process in a few weeks or months.

Re: Writing a good Claude.md

#279

Post by Zarathruster »

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've done this too. The nice side-benefit of this approach is that it also serves as good documentation for other humans (including your future self) when trying to wrap their heads around what was done and why. In general I find it helpful to write docs that help both humans and agents to understand the structure and purpose of my codebase.

Re: Writing a good Claude.md

#280

Post by llbeansandrice »

gtaylor wrote: post #236
tsimionescu wrote: post #231

Earlier quoted context omitted.

While I believe you're probably right that getting any productivity gains from these tools requires an investment, I think calling the process "engineering" is really stretching the meaning of the word. It's really closer to ritual magic than any solid engineering practices at this point. People have guesses and practices that may or may not actually work for them (since measuring productivity increases is difficult…

Most countries don’t have a notion of a formally licensed software engineer, anyway. Arguing what is and is not engineering is not useful.

I think it's relevant when people keep using terms like "prompt engineering" to try and beef up this charade of md files that don't even seem to work consistently.

This is a far far cry from even writing yaml for Github/Gitlab CICD pipelines. Folks keep trying to say "engineering" when every AI thread like this seems to push me more towards "snake oil" as an appropriate term.

Post reply on HN