I was nine months into using Claude Code before I understood what the .claude folder was actually for.
I had a CLAUDE.md. Claude read it every session. I thought that was the whole story.
Then I saw someone's full setup. Separate agents for code review. Hooks that automatically run tests before every commit. Rules that are only loaded when touching API files. Skills that replaced every slash command I'd ever typed.
I rebuilt my entire setup the same afternoon. The difference in output quality was immediate and it stayed.
This guide covers every file, what it does, when to use it, and exactly how to configure it.
First: how the .claude folder actually works.
Before touching any individual file, it helps to understand the five jobs the folder does:
Instructions - CLAUDE.md and rules/ tell Claude how to work. What to do, what to avoid, what standards to follow.
Workflows - skills/ holds reusable playbooks. Tasks Claude can execute on demand with one command.
Specialists - agents/ are subagents with their own context, tools, and permissions. They handle side tasks without polluting your main session.
Automation - hooks/ fire on lifecycle events. These run every time, guaranteed, regardless of what you've told Claude in the chat.
Permissions - settings.json and settings.local.json control what Claude is and isn't allowed to do in this project.
The decision rule: Stable rules go in CLAUDE.md. Long workflows go in skills. Deterministic automation goes in hooks. Noisy research or review tasks go in agents.
CLAUDE.md. Your project's operating manual.
CLAUDE.md is always loaded every session. It's a user message, not a system prompt. That distinction matters: it means Claude reads it the way it reads your instructions, not as background configuration.
The .claude folder controls instructions, workflows, specialists, permissions, and memory. CLAUDE.md handles the instructions layer.
Keep it under 200 lines. Bloated CLAUDE.md files get ignored. The goal is a short, specific operating manual that Claude actually reads and follows, not a dump of everything you've ever wanted from it.
A real CLAUDE.md structure:
What makes a CLAUDE.md actually work: Specificity.
"Write clean code" does nothing.
"Functions under 100 lines, complexity under 8, always typecheck before marking done" - Claude follows that.
Want to keep reading?
Become a paying subscriber to get access to this post and all other premium content.