Anatomy of the .claude/ Folder: Every File Explained

Why You Should Know What's In There

When you start using Claude Code, a .claude/ folder quietly appears in your project. Most builders treat it like a black box — they know it exists, they've seen it in their file tree, but they've never opened it.

That is like having a control panel in your workshop and never looking at the buttons. The .claude/ folder is where you tell Claude how to work with your project — not just what to build, but how to behave, what commands to run, which rules to follow, and what it is allowed to do.

Once you understand this folder, you stop repeating yourself to Claude every session. You stop getting generic answers. You start getting an AI that already knows your stack, your conventions, and your workflow.

There Are Two .claude/ Folders

Before diving in: there are actually two .claude/ directories, not one.

Project-level: your-project/.claude/ — lives in your project root, holds team configuration, gets committed to git. Everyone on the team gets the same rules, commands, and permission policies.

Global: ~/.claude/ — lives in your home directory, holds your personal preferences and machine-local state. Session history, auto-memory, and personal commands that apply across all projects live here.

When you start a Claude Code session, it reads both. Project-level settings take priority over global ones when they conflict.

1. CLAUDE.md — The Most Important File

This is the first file Claude Code reads when starting a session. It loads straight into the system prompt and Claude keeps it in mind for the entire conversation. Whatever you write in CLAUDE.md, Claude follows.

You can have three kinds of CLAUDE.md:

• Project root: CLAUDE.md — the main one, applies to the whole project
• Global: ~/.claude/CLAUDE.md — applies to every project you open
• Subdirectory: src/api/CLAUDE.md — applies only when Claude is working in that folder

Claude reads all of them and combines them. Subdirectory CLAUDE.md files let you give different instructions for different parts of your codebase — useful for monorepos.

What to put in CLAUDE.md

Think of it as the briefing document you would give a new developer joining your project. The sweet spot is 50–200 lines. Longer than that and Claude's instruction adherence actually drops as the file eats too much context.

Include:

• Build, test, and lint commands
• Your tech stack (be specific — include versions that matter)
• Key architectural decisions ("we use a monorepo with Turborepo")
• Non-obvious gotchas ("TypeScript strict mode is on, unused variables are errors")
• Import conventions, naming patterns, error handling styles
• Folder structure for main modules

For a full guide on writing effective CLAUDE.md files, see our CLAUDE.md deep dive.

2. CLAUDE.local.md — Your Personal Overrides

Sometimes you have preferences that are specific to you, not the whole team. Maybe you prefer a different test runner, or you want Claude to always explain its reasoning, or you like responses in a particular format.

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

# My personal Claude preferences for this project
# (not committed to git)

- Always explain what you changed and why before showing code
- When writing tests, use the describe/it pattern not test()
- I prefer arrow functions over function declarations

This is the right place for anything that is "my preference" rather than "the team standard." Your teammates use their own CLAUDE.local.md with their own preferences. Everyone gets the same base config plus their personal layer on top.

3. .claude/rules/ — Scoped Rule Files

A single CLAUDE.md works great when starting out. But as projects grow, it becomes a 300-line document that nobody maintains and everyone ignores.

The rules/ folder solves this. Every markdown file inside .claude/rules/ gets loaded alongside your CLAUDE.md automatically. Instead of one giant file, you split instructions by concern:

.claude/rules/
├── api-conventions.md     # REST API patterns for this project
├── testing.md             # Test standards and patterns
├── database.md            # DB query conventions, migration rules
└── security.md            # Security policies Claude must follow

Each file stays focused and easy to update. The team member who owns API conventions edits api-conventions.md. The testing lead edits testing.md. Nobody steps on each other.

Path-scoped rules (the power feature)

Rule files can include a YAML frontmatter block that scopes them to specific file paths. When you do this, Claude only loads that rule when it is working with matching files:

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

# API Handler Conventions

All handlers must return typed responses using the ApiResponse generic.
Never access the database directly from handlers — always go through the service layer.
Error responses must use the standardized error format in lib/errors.ts.

Claude will not load this file when editing a React component. It only activates when working inside src/api/ or src/handlers/. Rule files without a paths field load unconditionally every session.

This is the right pattern once your CLAUDE.md starts feeling crowded or you need different rules for different parts of the codebase.

4. .claude/commands/ — Custom Slash Commands

Claude Code has built-in slash 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. The filename is the command name.

.claude/commands/
├── review.md          → /project:review
├── fix-issue.md       → /project:fix-issue
├── security-scan.md   → /project:security-scan
└── deploy-check.md    → /project:deploy-check

Making commands dynamic

The real power of custom commands comes from dynamic content. Use backtick shell syntax to run commands and embed their output into the prompt:

# Code Review

Review the following changes for bugs, security issues, and code quality.
Focus on correctness and whether edge cases are handled.

Changes to review:
```
$(git diff HEAD~1)
```

When you run /project:review, Claude automatically gets the real git diff injected into its prompt before it starts responding.

Use $ARGUMENTS to accept text after the command name:

# Fix GitHub Issue

Analyze and fix the following issue.

Issue: $ARGUMENTS

First explain what's causing the problem, then implement a fix.
Check the existing tests and add new ones if needed.

Running /project:fix-issue 234 feeds "234" as the arguments. You can then combine this with a shell command that fetches the actual issue body from the GitHub API.

Project commands vs. user commands

Commands in .claude/commands/ are committed to git and shared with your team. They show up as /project:command-name.

For commands you want everywhere regardless of project, put them in ~/.claude/commands/. Those show up as /user:command-name and are available in every Claude Code session you open.

Good personal commands: a standup summary helper, a commit message generator, a quick security scan template.

5. settings.json — Permission Policies

The settings.json file (and its local counterpart settings.local.json) controls what Claude Code is allowed to do without asking permission.

By default, Claude asks before running shell commands, creating files, and making network requests. Settings let you pre-approve specific operations for your workflow:

{
  "permissions": {
    "allow": [
      "Bash(npm run test)",
      "Bash(npm run lint)",
      "Bash(git diff*)",
      "Bash(git log*)",
      "Read(**)",
      "Write(src/**)"
    ],
    "deny": [
      "Bash(rm -rf*)",
      "Bash(curl*)",
      "Write(.env*)"
    ]
  }
}

The allow list contains operations Claude can run without asking. The deny list contains operations that are always blocked, even if you try to approve them interactively.

Use settings.json (committed to git) for team-wide permission policies. Use settings.local.json (gitignored) for personal overrides — for example, if you want to pre-approve more commands locally than your team policy allows.

6. Memory Files — Claude's Persistent Memory

Claude Code has an auto-memory feature that lets it remember information across sessions. When Claude stores a memory, it gets written into your ~/.claude/ global folder as a memory file.

You can also explicitly trigger memory from a session: tell Claude "remember that this project uses PostgreSQL 16 and pgvector" and it will save that fact for future sessions.

This is separate from CLAUDE.md. Think of the difference as:

• CLAUDE.md = things you manually document about your project
• Memory files = things Claude learned and saved during sessions

The Full Folder Structure

Here is the complete picture of both .claude/ directories:

# Project-level (committed to git)
your-project/
├── CLAUDE.md               ← primary project instructions
├── CLAUDE.local.md         ← your personal overrides (gitignored)
└── .claude/
    ├── settings.json       ← team permission policies
    ├── settings.local.json ← your personal permission overrides (gitignored)
    ├── commands/           ← custom /project:* slash commands
    │   ├── review.md
    │   └── fix-issue.md
    └── rules/              ← scoped instruction files
        ├── api-conventions.md
        └── testing.md

# Global (your home directory, not committed)
~/.claude/
    ├── CLAUDE.md           ← preferences for all projects
    ├── commands/           ← custom /user:* slash commands
    └── memory/             ← Claude's saved memories across sessions

What AI Gets Wrong About the .claude/ Folder

When you ask AI tools about the .claude/ folder, they often give you incomplete answers. Common mistakes:

• "CLAUDE.md is the only file that matters" — Not true. The rules/ and commands/ folders can transform how productive you are, especially on team projects.
• "The .claude folder is read-only" — Wrong. You create and edit everything in it. Claude Code reads it; you manage it.
• "You should put all instructions in one big CLAUDE.md" — This actually hurts instruction adherence. Split into rules/ files once CLAUDE.md hits 200 lines.
• "Settings.json controls Claude's AI behavior" — It controls permissions (what Claude is allowed to do), not how Claude reasons or responds.

Debugging: When Claude Ignores Your Configuration

If Claude seems to be ignoring your CLAUDE.md or custom commands, check these common causes:

1. File not in the right place — CLAUDE.md must be in the directory where you launch Claude Code, not a parent or child directory (unless you want subdirectory-scoped rules).
2. CLAUDE.md is too long — Files over 300–400 lines dilute Claude's attention. Trim to essentials and move the rest to rules/.
3. Commands folder name is wrong — It must be .claude/commands/ (lowercase, inside the .claude hidden folder). Not commands/ at the project root.
4. Settings.json has a JSON syntax error — Even a single trailing comma will silently break the entire permissions file. Validate JSON before committing.
5. Rules frontmatter path doesn't match — If a scoped rule isn't loading, check that the paths glob actually matches the file you're editing. Test with a simpler pattern first.

Quick-Start: Set Up Your .claude/ Folder

If you are starting from scratch, here is the sequence that works:

1. Run /init in Claude Code — it scans your project and generates a starter CLAUDE.md. Edit it from there.
2. Add CLAUDE.local.md to your project root with your personal preferences. Add it to .gitignore.
3. Create .claude/commands/review.md with a git diff review command — this is the highest-ROI custom command for most projects.
4. Add .claude/settings.json with conservative permission allowances for your test and lint commands.
5. Split CLAUDE.md into rules/ files once it gets crowded (usually around the 150-line mark).

FAQ

What to Read Next

• What Is a CLAUDE.md File? (Deep Dive) — How to write effective project instructions
• Claude Code Beginners Guide — Start here if you're new to Claude Code
• Claude Code Cheat Sheet — All commands, flags, and keyboard shortcuts in one place
• What Are Claude Code Channels? — Claude Code's multi-channel architecture explained
• What Are System Prompts? — Understanding the instructions layer that shapes AI behavior