Anatomy of the .claude/ folder

bagrow

Here's a question that I hope is not too off-topic. Do people find the nano-banana cartoon infographics to be helpful, or distracting? Personally, I'm starting to tire seeing all the little cartoon people and the faux-hand-drawn images. Wouldn't Tufte call this chartjunk?

TheRoque

So that's what "software engineering" has become nowadays ? Some cargo cult basically. Seriously all of this gives red flag. No statements here are provable. It's just like langhchain that was praised and then everyone realized it's absolute dog water. Just like MCP too. The job in 2026 is really sad.

manudaro

The .claude folder structure reminds me of how Terraform organizes state files. Smart move putting conversation history in Json rether than some propiertary format, makes it trivial to grep through old conversations or build custom analysis tools.

galoisscobi

> Most people either write too much or too little. Here’s what works. > Two folders, not one Why post AI slop here?

jwilliams

> Simply put: whatever you write in CLAUDE.md, Claude will follow. No. CLAUDE.md is just prompt text. Compaction rewrites prompt text. If it matters, enforce it in other ways.

exitb

I’m seeing this more and more, where people build this artificial wall you supposedly need to climb to try agentic coding. That’s not the right way to start at all. You should start with a fresh .claude, empty AGENTS.md, zero skills and MCP and learn to operate the thing first.

Synthetic7346

I wish all model providers would converge on a standard set of files, so I could switch easily from Claude to Codex to Cursor to Opencode depending on the situation

phyzix5761

Is there a completely free coding assistant agent that doesn't require you to give a credit card to use it? I recently tried IntelliJ for Kotlin development and it wanted me to give a credit card for a 30 day trial. I just want something that scans my repo and I tell it the changes I want and it does it. If possible, it would also run the existing tests to make sure its changes don't break anything.

63stack

The article starts off really weak: >Claude Code users typically treat the .claude folder like a black box. They know it exists. They’ve seen it appear in their project root. But they’ve never opened it, let alone understood what every file inside it does. I know we are living in a post-engineering world now, but you can't tell me that people don't look at PRs anymore, or their own diffs, at least until/if they decide to .gitignore .claude.

groby_b

100% AI slop. All the way to "The Key Insight".

rdevilla

The fuck? What's next, configuring maven and pom.xml? At least XML is unambiguous, well specified, and doesn't randomly refuse to compile 2% of the time..

forgotusername6

If these different agents could agree on a standard location that would be great. The specs are almost the same for .github and Claude but Claude won't even look at the .github location.

submeta

Tangential: The image with the heading "Anatomy of the .claude/ folder" is nicely made, anyone knows what tool is used for it?

saadn92

The claim that "whatever you write in CLAUDE.md, Claude will follow" is doing a lot of heavy lifting. In practice CLAUDE.md is a suggestion, not a contract. Complex tasks and compaction will dilute the use of CLAUDE.md, especially once the context window runs out.

PetrBrzyBrzek

Why is this AI slop article first on HN?

BuildItBusk

I think this does a great job of explaining the .claude directories in a beginner friendly way. And I don’t necessarily read it as “you have to do all this, before you start”. It has a few issues with outdated advice (e.g. commands has been merged with skills), but overall I might use share it with co-workers who needs an introduction to the concept.

frizlab

Completely tangential, but can we please stop putting one million files at the root of the project which have nothing to do with the project? Can we land on a convention like, idk, a `.meta` folder (not the meta company, the actual word), or whatever, in which all of these Claude.md, .swift-version, Code-of-Conduct.md, Codeowners, Contributing.md, .rubocop.yml, .editorconfig, etc. files would go??

akalidz

interesting

dataviz1000

Claude Fast has very good alternate documentation for this. [0] I don't understand the hate for defining .claude/ . It is quite easy to have the main agent write the files. Then rather doing one shot coding, instead iterate quickly updating .claude/ I'm at the point where .claude/ makes copies of itself, performs the task, evaluates, and updates itself. I'm not coding code, I'm coding .claude/ which does everything else. This is also a mechanism for testing .claude, agents, and instructions which would be useful for sharing and reuse in an organization. [0] https://claudefa.st/blog/guide/mechanics/claude-md-mastery