.claude Folder Anatomy: Control Center for AI Coding

Most Claude Code users 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 does.

That's leaving 80% of Claude's power on the table.

The .claude folder is your control center. It holds your instructions, your custom commands, your permission rules, and Claude's memory across sessions. Once you understand what lives where, you can configure Claude to behave exactly how your workflow needs it to.

Two .claude Directories, Not One

Before we dive in, here's something that trips everyone up: there are actually two .claude directories.

Project-level config is shared. Everyone on your team gets the same rules, same commands, same conventions.

Global ~/.claude/ holds your personal preferences and machine state — session history, auto-memory, your own custom commands.

Claude reads both and merges them. Project rules take precedence.

CLAUDE.md: The Most Important File

When you start a Claude Code session, the first thing it reads is CLAUDE.md. This file loads straight into the system prompt and stays in context for the entire conversation.

Whatever you write in CLAUDE.md, Claude will follow.

Tell Claude to always write tests before implementation? It will.

Say "never use console.log for errors, always use our custom logger"? It will respect that every time.

Most people either write too much or too little. Here's what actually works:

Write:

• Build, test, and lint commands (npm run test, make build)
• Key architectural decisions ("monorepo with Turborepo")
• Non-obvious gotchas ("TypeScript strict mode, unused vars are errors")
• Import conventions, naming patterns, error handling style
• File and folder structure for main modules

Don't write:

• Anything that belongs in a linter config
• Full documentation you can already link to
• Long theoretical explanations

Keep CLAUDE.md under 200 lines. Files longer than that eat too much context, and Claude's instruction adherence actually drops.

# Project Setup

## Tech Stack
- Next.js 14 (App Router)
- TypeScript strict mode
- Tailwind CSS
- Prisma ORM

## Commands
- `npm run dev` — Start dev server
- `npm run build` — Production build
- `npm test` — Run tests (Vitest)
- `npm run lint` — ESLint + Prettier

## Code Conventions
- Use named exports, not default
- Error handling: throw custom AppError, never raw Error
- Database queries: always use Prisma, never raw SQL
- API routes: /app/api/[resource]/route.ts

## Project Structure
- /app — Next.js pages and API routes
- /components — React components (client + server)
- /lib — Utilities and shared logic
- /prisma — Database schema and migrations

That's ~20 lines. It gives Claude everything it needs without constant clarification.

CLAUDE.local.md: Your Personal Overrides

Sometimes you have preferences specific to you. Maybe you prefer a different test runner, or you want Claude to open files differently.

Create CLAUDE.local.md in your project root. Claude reads it alongside the main CLAUDE.md, and it's automatically gitignored so your personal tweaks never land in the repo.

rules/: Split Instructions by Concern

CLAUDE.md works great for a single project. But once your team grows, you end up with a 300-line file that nobody maintains.

The rules/ folder solves that.

Every markdown file inside .claude/rules/ gets loaded alongside CLAUDE.md automatically. Instead of one giant file, you split instructions by domain:

Each file stays focused. The team member who owns API conventions edits api-conventions.md. The person who owns testing edits testing.md. Nobody stomps on each other.

Path-Scoped Rules

The real power: rules that only load for specific files.

Add YAML frontmatter to a rule file and it only activates when Claude is working with matching paths:

---
paths:
  - "src/api/**"
  - "src/handlers/**"
---

# API Handler Rules

All API handlers must:
- Validate input with Zod schemas
- Return standardized error responses
- Log requests to our observability stack

Claude won't load this when editing a React component. It only loads when working inside src/api/ or src/handlers/.

Rules without a paths field load unconditionally.

This is the right pattern once your CLAUDE.md starts feeling crowded.

commands/: Custom Slash Commands

Out of the box, Claude Code has built-in commands like /help and /compact. The commands/ folder lets you add your own.

Every markdown file you drop into .claude/commands/ becomes a slash command.

A file named review.md creates /project:review. A file named fix-issue.md creates /project:fix-issue.

Here's a simple example:

# .claude/commands/review.md

Review the changes in the current branch:

```
!git diff main...HEAD
```

Look for:
- Breaking changes
- Missing tests
- Performance issues
- Security vulnerabilities

Now run /project:review and Claude automatically injects the real git diff into the prompt before processing it.

The ! backtick syntax runs shell commands and embeds the output. That's what makes custom commands genuinely useful instead of just saved text.

Commands with Arguments

Use $ARGUMENTS to pass text after the command name:

# .claude/commands/fix-issue.md

Analyze GitHub issue and propose a fix:

```
!gh issue view $ARGUMENTS --json title,body,comments
```

Based on the issue above, suggest:
1. Root cause
2. Implementation approach
3. Test cases needed

Running /project:fix-issue 234 fetches issue #234 and feeds it to Claude.

Personal Commands

Project commands in .claude/commands/ are committed and shared. For commands you want everywhere regardless of project, put them in ~/.claude/commands/.

Those show up as /user:command-name instead of /project:command-name.

Useful personal commands:

• Daily standup helper
• Commit message generator following your style
• Quick security scan
• Explain this codebase (for jumping into new projects)

skills/: Automatically Triggered Workflows

Commands are explicit — you type /project:review to trigger them.

Skills are automatic — Claude decides when to use them based on your request.

Example: You have a skill for "deploy to staging." When you say "push this to staging," Claude sees the skill, realizes it matches, and executes it without you typing a slash command.

Skills are more complex than commands because they include:

• Trigger conditions (when to activate)
• Multi-step workflows
• Error handling

Most solo builders don't need skills. Commands are simpler and cover 90% of use cases. But if you're building repeated multi-step processes, skills are worth learning.

Practical Workflow for Solo Builders

Here's my current setup after two months of heavy Claude Code usage:

Project-Level (.claude/ in repo)

• CLAUDE.md: Tech stack, key commands, 15-20 lines
• commands/review.md: Git diff analysis
• commands/deploy-staging.md: Deploy script with safety checks
• rules/api.md: API conventions (path-scoped to src/api/)

Global (~/.claude/)

• CLAUDE.md: My personal coding preferences
• commands/standup.md: Generate standup based on recent commits
• commands/commit.md: Generate commit message from staged changes

Typical Session

1. Open Claude Code in project
2. Claude auto-loads project CLAUDE.md + my global preferences
3. I ask "refactor the auth system to use middleware"
4. Claude knows our auth conventions from rules/api.md
5. It refactors, I review with /project:review
6. I deploy with /project:deploy-staging

Total time: 10 minutes. Without the custom setup, this would take 30+ minutes of back-and-forth clarifications.

Common Mistakes to Avoid

1. Writing a Novel in CLAUDE.md

I see projects with 500-line CLAUDE.md files. Claude can't keep that in context. It starts ignoring instructions halfway through.

Keep it under 200 lines. Move specialized rules to rules/ with path scoping.

2. Not Using CLAUDE.local.md

Don't pollute the team's CLAUDE.md with your personal preferences. Use CLAUDE.local.md for debugging modes, verbose logging, or alternative workflows.

3. Creating Commands for Everything

Commands are great for repeated tasks. They're overkill for one-off actions.

Ask yourself: "Will I use this 5+ times?" If no, just type the prompt directly.

4. Forgetting to Test Commands

Commands that run shell scripts can break your environment if they fail. Always test in a safe branch before committing.

Advanced: Memory and Session State

Claude Code stores session state in ~/.claude/.state/. This includes:

• Conversation history
• Auto-memory (facts Claude learns about your project)
• File context from previous sessions

You generally don't touch this manually. But if Claude starts "remembering" wrong information, you can clear state:

rm -rf ~/.claude/.state/

This resets Claude to a fresh session.

What to Do Next

1. Open your project's .claude/ folder (or create it)
2. Create a minimal CLAUDE.md — 20 lines covering your tech stack and build commands
3. Add one custom command for your most repeated task
4. Use Claude Code for a week
5. Iterate: add rules and commands as you notice repeated clarifications

The .claude folder is how you stop treating Claude like a chatbot and start treating it like a team member who knows your project.

Once you have this configured, you'll wonder how you ever coded without it.

Further reading: Full .claude folder guide | Official Claude Code docs