Anatomy of the .claude/ folder

Lots of money being made by luring people into this trap.

The reality is that if you actually know what you want, and can communicate it well (where the productivity app can be helpful), then you can do a lot with AI.

My experience is that most people don't actually know what they want. Or they don't understand what goes into what they want. Asking for a plan is a shortcut to gaining that understanding.

Emacs init file bikeshedding comes to mind…

> Plain Claude, ask it to write a plan, review plan, then tell it to execute still works the best in my experience.

Working on an unspecified codebase of unknown size using unconfigured tooling with unstated goals found that less configuration worked better than more.

if you work on platforms, frameworks, tools that are public knowledge, then yeah. If there’s nothing unique to your project or how to write code in it, build it, deploy it, operate it, yeah.

But for some projects there will be things Claude doesn’t know about, or things that you repeatedly want done a specific way and don’t want to type it in every prompt.

example https://news.ycombinator.com/item?id=47501214

I'd also go even further and say that you likely should never install ANY skill that you didn't create yourself (i mean, guided claude to create it for you works too), or "forked" an existing one and pulled only what you need.

Everyone's workflow is different and nobody knows which workflow is the right one. If you turn your harness into a junk drawer of random skills that get auto updated, you introduce yet another layer of nondeterminism into it, and also blow up your context window.

The only skill you should probably install instead of maintaining it yourself is playwright-cli, but that's pretty much it.

This matters for big engineering teams who want to put _some_ kind of guardrails around Claude that they can scale out.

For example, I have a rule [^0] that instructs Claude to never start work until some pre-conditions are met. This works well, as it always seems to check these conditions before doing anything, every turn.

I can see security teams wanting to use this approach to feel more comfortable about devs doing things with agentic tools without worrying _as much_ about them wreaking havoc (or what they consider "havoc").

As well, as someone who's just _really_ getting started with agentic dev, spending time dumping how I work into rules helped Claude not do things I disapprove of, like not signing off commits with my GPG key.

That said, these rules will never be set in stone, at least not at first.

[^0]: https://github.com/carlosonunez/bash-dotfiles/blob/main/ai/c...

This article isn't saying you must set up a big .claude folder before you start. It repeats several times that it's important to start small and keep it short.

It's also not targeted at first-timers getting their first taste of AI coding. It's a guide for how to use these tools to deal with frustrations you will inevitably encounter with AI coding.

Though really, many of the complaints about AI coding on HN are written by beginners who would also benefit from a simple .claude configuration that includes their preferences and some guidelines. A frequent complaint from people who do drive-by tests of AI coding tools before giving up is that the tools aren't reading their mind or the tools keep doing things the user doesn't want. Putting a couple lines into AGENTS.md or the .claude folder can fix many of those problems quickly.

Yes, but as soon as you start checking in and sharing access to a project with other developers these things become shared.

Working out how to work on code on your own with agentic support is one thing. Working out how to work on it as a team where each developer is employing agentic tools is a whole different ballgame.

Seriously, just use plan mode first and you get like 90% of the way there, with CC launching subagents that will generally do the right thing anyway.

IMHO most of this “customize your config to be more productive” stuff will go away within a year, obsoleted by improved models and harnesses.

Just like how all the lessons for how to use LLMs in code from 1-2 years ago are already long forgotten.

this is true, but i think people are best off starting with SOME project that gives users an idea of how to organize and think about stuff. for me, this is gastown, and i now have what has gotta be the most custom gastown install out there. could not agree more that your ai experience must be that which you build for yourself, not a productized version that portends to magically agentize your life. i think this is the real genius of gastown— not how it works, but that it does work and yegge built it from his own mind. so i’ve taken the same lesson and run very, very far with it, while also going in a totally different direction in many ways. but it is a work of genius, and i respect the hell out of him for putting it out there.

Who is building an artificial wall? Maybe I skimmed the post too fast, but it doesn't seem like this information is being presented as "you have to know/do this before you start agentic engineering", just "this is some stuff to know."

It's not as bucolic as this when trying to get an org on board. We're currently very open to using Claude, but the unknowns are still the unknowns, so the guardrails the `.claude` folder provides gives us comfort when gaining familiarity with the tool.

.claude has become the new dotfiles. And what do people do when they want to start using dotfiles ? they copy other’s dotfiles and same is happening here :)

> empty AGENTS.md, zero skills

which is basically every setup because claude sucks at calling skills and forget everything in claude.md with a few seconds.

I totally agree with you that this not the right way to start. But, in my experience, the more you use the tool the more of a "feel" you get for it, and knowing how all these different pieces work and line up can be quite useful (though certainly not mandatory). It's been immensely frustrating to me how difficult it is to find all this info with all the low-quality junk that is out there on the internet.

I agree with most of this, with one important exception: you should have some form of sandboxing in place before running any local AI agent. The easiest way to do that is with .claude/settings.json[0].

This is important no matter how experienced you are, but arguable the most important when you don't know what you're doing.

0: or if you don't want to learn about that, you can use Claude Code Web

Peter Steinberger himself says he's just chatting with AI instead of coming up with crazy coding workflows.

Seems maybe you're just not the target audience for this article.

with Anthropic already starting to sell "Claude Certified Architect" exams and a "Partner Network Program", I think a lot of this stuff is around building a side industry on top of it unfortunately

Operate == me send https post and pray for the best

The intro paragraph sounds exactly like Claude’s phrasing. So much so that I couldn’t read the rest of the article because I assumed I could just ask Claude about the topic.

> Dont skills supercede commands?

Don't skills sit in context while custom slash commands are only manually invoked?

The difference isn't clear to me, especially since, upon googling it right now, I see that skills can also be invoked with a /slash.

Issue is that both harness and specific model matters a lot in what type of instruction works best, if you were to use Anthrophic's models together with the best way to do prompting with Codex and GPT models, you'd get a lot worse results compared to if you use GPT models with Codex, prompted in the way GPTs react best to them.

I don't think people realize exactly how important the specific prompts are, with the same prompt you'd get wildly different results for different models, and when you're iterating on a prompt (say for some processing), you'd do different changes depending on what model is being used.

You can just use a single agents.md and have claude.md use it. Then symlink or sync skills/etc between .folders. It’s not perfect but works.

Agree, for now im using dotagents by sentry to handle a lot of this.

And why would they ever let switch?

This is correct. All of these .md files are just blobs of text that the LLM matches against. They might increase the likelihood of something happening or not happening.

They look to me like people actually want to build deterministic workflows, but blobs of text are the wrong approach for that. The right tool is code that controls the agent through specific states and validates the tool calls step by step.

Yeah, the moment I saw this I knew this article was not going to be very useful.

Getting claude to follow your guidance files consistently is a bit maddening.

Claude itself will grep through old conversations so it’s handy that Claude understands too

You’re assuming most people using Claude code are senior engineers.

I don't. I have Claude do all my PR reviews, running in a daily loop in the morning. The truth is an LLM is better at code review than the average programmer.

I'm a senior engineer who has been shipping code since before GitHub and PR reviews was a thing. Thankfully LLMs have freed me from being asked to read other people's shit code for hours every day.

There are lots! Too many to cover in a single HN comment, and this space is evolving rapidly so I encourage you to look around.

While the coding assistants are pretty much universally free, you still need to connect them to a model. The model tokens generally cost something once you've gone past a certain quota.

I'm not sure if this is still true, but if you have a Google account, Gemini Code Assist had a quite generous "free tier" that I used for a while and found it do be pretty decent.

https://news.ycombinator.com/item?id=47533611

It is fun to use.

Gemini Code Assist has a free tier.

You log in with your Goggle account.

Qwen code has a free tier

Opencoder is bring your own model.

You get what you pay for so good luck.

I think I'm finding a pretty good niche for myself honestly. IMO, Software engineering is more so splitting into different professions based on the work is produces.

This sort of "prompt and pray" flow really works for people, as in they can make products and money, however, I do think the people that succeed today also would've reached for no-code tools 5 years ago and seen similar success. It's just faster and more comprehensive now. I think the general theme of the products remains the same though; not un-important or worthless, but it tends to be software that has effects that say INSIDE the realm of software. I feel like there's always been a market for that, as it IS important, it's just not WORTH the time and money to the right people to "engineer" those tools. A lot of SaaS products filled that niche for many years.

While it's not a way I want to work, I am also becoming comfortable with respecting that as a different profession for producing a certain brand of software that does have value, and that I wasn't making before. The intersection of that is opportunity I'm missing out on; no fault to anyone taking it!

The software engineer that writes the air traffic avoidance system for a plane better take their job seriously, understand every change they make, and be able to maintain software indefinitely. People might not care a ton about how their sales tracking software is engineered, but they really care about the engineering of the airplane software.

When was it not a cargo cult?

I was glad when linux went with the .config standard for most dotfiles.

There already is, it's ~/.agents and you use symlinks for .claude, and the dir structure is pretty similar and anything you want to reuse across models is pretty standardized, just not formalized.

I haven't come around any AI generated imagery in documents / slides that adds any value. It's more the opposite, they stand out like a sore thumb and often even reduce usability since text cannot be copied. Oh and don't get me started on leadership adding random AI generated images to their emails just to show that they use AI.

When I see AI images, I skip them, and most likely, the entire article. They're a better warning sign than the ones hidden in the text.

Tufte is evergreen. Zinsser is another.

> Clutter is the disease of American writing. We are a society strangling in unnecessary words, circular constructions, pompous frills and meaningless jargon.

> Look for the clutter in your writing and prune it ruthlessly. Be grateful for everything you can throw away. Reexamine each sentence you put on paper. Is every word doing new work? Can any thought be expressed with more economy?

On Writing Well (Zinsser)

This is equivalent to "do people find PowerPoint to be helpful or distracting." Sometimes yes, mostly no.

In this case, I'd say helpful because I didn't have to read the article at all to understand what was being communicated.

I never trust them to actually be correct. Aka they're probably worse than useless.

Most of the time I find them distracting, and sometimes a huge negative on the article. In this particular article though, they're well done and relevant, and I think they add quite a bit. It's a highly personal opinion kind of thing though for sure.

LinkedIn loves these, even if they're broken.

But they had already lost me at all the links, and the fact there's not a red wire through the entire article.

The first thing my eyes skimmed was:

> CLAUDE.md: Claude’s instruction manual

> This is the most important file in the entire system. When you start a Claude Code session, the first thing it reads is CLAUDE.md. It loads it straight into the system prompt and keeps it in mind for the entire conversation.

No it's not. Claude does not read this until it is relevant. And if it does, it's not SOT. So no, it's argumentatively not the most important file.

I think it's fine. As someone who blogged a lot, the instant visual differentiation among articles offered by the art within is actually valuable.

I am a victim of AI-documentation-slop at work, and the result is that I've become far more "Tuftian" in my preferences than ever before. In the past, I was a fan of beautiful design and sometimes liked nice colors and ornaments. Now, though, I've a fan of sparse design and relevant data (not information -- lots of information is useless slop). I want content that's useful and actionable, and the majority of the documents many of my peers create using Claude, Gemini or ChatGPT are fluffy broadsheets of irrelevant filler, rarely containing insights and calls-to-action.

So yes, it's chartjunk.

It's not necessarily an AI-generated infographics issue, it's that these aren't good infographics. The graphic part is adding minimal value.

My eye has started skipping past them, even though they're often quite useful if you engage with them.

I think the problem is that they're uninformative slop often enough that I've subconsciously determined they aren't worth risking attention time on.

No. It adds nothing so nothing is preferred

CLAUDE.md survives compaction.

Exactly!

[dead]

Yea I went through my global claude skills and /context yesterday because claude was performing terribly. I deleted a bunch of stuff including memory and anecdotally got better results later on in the day.

Yeah skills get loaded into context which in effect pollutes context.

"Thinking" is about to get even harder to do for most grifters with newsletters to sell.