alt Hacker NewsAnatomy of the .claude/ folder
Comments
Feel little like this is generated and not based on experience. Claude.md should be short. Typescript strict mode isnt a gotcha, itll figure that out on its own easily, imo omit things like that. People put far too much stuff in claude, just a few lines and links to docs is all it needs. You can also @Agents.md and put everything there instead. Dont skills supercede commands? Subagents are good esp if you specify model, forked memory, linked skills, etc. Always ask what you can optimize after you see claude thrashing, then figure out how to encode that (or refactor your scripts or code choices).
Always separate plan from implementation and clear context between, its the build up of context that makes it bad ime.
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
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
Nice! Article didn't mention but ~/.claude/plans is where it stores plan md file when running in plan mode. I find it useful to open or backup plans from the directory.
The real wall I never see people talking about is, yes, you can tell Claude to update whatever file you want, but you have to be aware that if it's .claude/INSTRUCTIONS.md or CLAUDE.md that you need to tell Claude to re-read those files because it wrote the contents but its not treating it as if it were fresh instructions, it will run off whatever the last time it read that file was, so if it never existed, it will not know. I believe Claude puts those instructions in a very specific part of its context window.
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.
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.
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.
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.
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??
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.
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.
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?
huh neat, somehow completely missed out on the rules/ + path filters as a way to extend CLAUDE.md
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.
> 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.
Alchemy.
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..
In my experience fewer skills is significantly better.
When you have this performative folder of skills the AI wastes a bunch of tool calls, gets confused, doesn't get to the meat of the problem.
beware!
Tangential: The image with the heading "Anatomy of the .claude/ folder" is nicely made, anyone knows what tool is used for it?
interesting
Why is this AI slop article first on HN?
100% AI slop. All the way to "The Key Insight".
[dead]
[dead]
[dead]
[dead]
> Most people either write too much or too little. Here’s what works.
> Two folders, not one
Why post AI slop here?
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.