Mastering the .claude Folder: The Complete Claude Code Configuration Guide for 2026

Mastering the .claude Folder: The Complete Claude Code Configuration Guide for 2026

Most Claude Code users know the .claude folder exists. They have seen it appear in their project root. They have never opened it.

That is a significant missed opportunity. The .claude folder is the control center for how Claude behaves in your project. It holds your instructions, your custom commands, your permission rules, and Claude's memory across sessions. Once you understand what lives where and why, you can configure Claude Code to behave exactly the way your team needs.

This guide is based on a widely shared breakdown by developer Akshay Pachaar, who published one of the most complete walkthroughs of the .claude folder structure to date. We have expanded it with additional technical details and current documentation to make it the most practical reference available.

---

Two Folders, Not One

Before going further, the most commonly missed fact about Claude Code's configuration: there are two .claude directories, not one.

The project-level folder lives inside your repository at .claude/. You commit it to git. Everyone on the team gets the same rules, the same custom commands, the same permission policies.

The global folder lives at ~/.claude/ on your machine. It holds your personal preferences and machine-local state like session history and auto-generated memory. It is never committed anywhere.

Both load on every session. The same tool, different scope.

---

CLAUDE.md: Claude's Instruction Manual

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

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

If you tell Claude to always write tests before implementation, it will. If you say "never use console.log for error handling, always use the custom logger module," it will respect that every single time, without you having to repeat it.

A CLAUDE.md at your project root is the most common setup. You can also have one in ~/.claude/CLAUDE.md for global preferences that apply across all projects, and even one inside subdirectories for folder-specific rules. Claude reads all of them and combines them.

What actually belongs in CLAUDE.md

Write your build, test, and lint commands. Write key architectural decisions. Write non-obvious gotchas like "TypeScript strict mode is on, unused variables are errors." Write import conventions, naming patterns, and error handling styles.

Do not write anything that belongs in a linter config. Do not write full documentation you can already link to. Do not write long paragraphs explaining theory.

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

Here is a minimal but effective example:

## Project: Acme API

## Commands
npm run dev          # Start dev server
npm run test         # Run tests (Jest)
npm run lint         # ESLint + Prettier check
npm run build        # Production build

## Architecture
- Express REST API, Node 20
- PostgreSQL via Prisma ORM
- All handlers live in src/handlers/
- Shared types in src/types/

## Conventions
- Use zod for request validation in every handler
- Return shape is always { data, error }
- Never expose stack traces to the client
- Use the logger module, not console.log

## Watch out for
- Tests use a real local DB, not mocks. Run npm run db:test:reset first
- Strict TypeScript: no unused imports, ever

That is roughly 20 lines. It gives Claude everything it needs to work productively in the codebase without constant clarification.

CLAUDE.md loading order

When multiple CLAUDE.md files exist, they are all loaded and merged into the system prompt at session start. The priority order, from lowest to highest, is:

1. Managed Policy (org-wide, IT-deployed, cannot be overridden)
2. ~/.claude/CLAUDE.md (your global preferences)
3. ./CLAUDE.md (project root, committed to git)
4. CLAUDE.local.md (your personal project overrides, gitignored)

Higher priority wins in a conflict. Your local overrides beat the team config. The org-wide managed policy beats everything.

CLAUDE.local.md for personal overrides

Sometimes you have a preference specific to you, not the whole team. 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 repository.

---

The rules/ Folder: Modular Instructions That Scale

CLAUDE.md works well for a single project. Once your team grows, you end up with a 300-line file 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/
├── code-style.md
├── testing.md
├── api-conventions.md
└── security.md

The real power comes from path-scoped rules. Add a YAML frontmatter block to a rule file and it only activates when Claude is working with matching files:

---
paths:
  - "src/api/**/*.ts"
  - "src/handlers/**/*.ts"
---
## API Design Rules
- All handlers return { data, error } shape
- Use zod for request body validation
- Never expose internal error details to clients

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

---

The commands/ Folder: Custom Slash Commands

Out of the box, 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.

---
description: Review the current branch diff for issues before merging
---
## Changes to Review

!`git diff --name-only main...HEAD`

## Detailed Diff

!`git diff main...HEAD`

Review the above changes for code quality issues, security vulnerabilities,
missing test coverage, and performance concerns. Give specific, actionable
feedback per file.

The ! backtick syntax runs shell commands and embeds the output before Claude sees the prompt. That is what makes these commands genuinely useful rather than just saved text.

You can also pass arguments using $ARGUMENTS:

---
description: Investigate and fix a GitHub issue
argument-hint: [issue-number]
---
Look at issue #$ARGUMENTS in this repo.

!`gh issue view $ARGUMENTS`

Understand the bug, trace it to the root cause, fix it, and write a test
that would have caught it.

Running /project:fix-issue 234 feeds issue 234's real content directly into the prompt.

Project commands in .claude/commands/ are committed and shared with your team. Personal commands go in ~/.claude/commands/ and show up as /user:command-name across all your projects.

---

The skills/ Folder: Workflows Claude Invokes on Its Own

Skills look similar to commands on the surface, but the trigger is fundamentally different.

Commands wait for you. You type /project:review and it runs. Skills watch the conversation and act automatically when the task matches the skill's description. Claude reads the description, recognizes a match, and invokes the skill without you doing anything.

Each skill lives in its own subdirectory with a SKILL.md file:

---
name: security-review
description: Comprehensive security audit. Use when reviewing code for
  vulnerabilities, before deployments, or when the user mentions security.
allowed-tools: Read, Grep, Glob
---
Analyze the codebase for security vulnerabilities including SQL injection,
XSS risks, exposed credentials, and authentication gaps. Report findings
with severity ratings and specific remediation steps.

When you say "review this PR for security issues," Claude reads the description, recognizes it matches, and invokes the skill automatically. You can also call it explicitly with /security-review.

Skills can also bundle supporting files alongside them. A @DETAILED_GUIDE.md reference in the instructions pulls in a document that lives right next to SKILL.md. Commands are single files. Skills are packages.

---

The agents/ Folder: Specialized Subagent Personas

When a task is complex enough to benefit from a dedicated specialist, you can define a subagent persona in .claude/agents/. Each agent is a markdown file with its own system prompt, tool access, and model preference.

---
name: code-reviewer
description: Expert code reviewer. Use PROACTIVELY when reviewing PRs,
  checking for bugs, or validating implementations before merging.
model: sonnet
tools: Read, Grep, Glob
---
You are a senior code reviewer focused on correctness and maintainability.
Flag bugs, not just style issues. Suggest specific fixes. Check for edge
cases and error handling gaps.

When Claude needs a code review done, it spawns this agent in its own isolated context window. The agent does its work, compresses the findings, and reports back. Your main session does not get cluttered with thousands of tokens of intermediate exploration.

The tools field restricts what the agent can do. A security auditor only needs Read, Grep, and Glob. It has no business writing files. That restriction is intentional.

The model field lets you use a cheaper, faster model for focused tasks. Haiku handles most read-only exploration well. Save Sonnet and Opus for the work that actually needs them.

---

settings.json: Permissions and Project Config

The settings.json file inside .claude/ controls what Claude is and is not allowed to do at the system level.

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git status)",
      "Bash(git diff *)",
      "Read",
      "Write",
      "Edit"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(curl *)",
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  }
}

The allow list contains commands that run without Claude asking for confirmation. The deny list contains commands that are blocked entirely, regardless of what Claude thinks it needs to do. If something is in neither list, Claude asks before proceeding.

Always include the $schema line. It enables autocomplete and inline validation in VS Code and Cursor.

settings.json follows a five-scope priority chain, from highest to lowest: Enterprise managed policy, session flags, project shared (.claude/settings.json), project local (.claude/settings.local.json), and user global (~/.claude/settings.json). Array fields like permissions.allow are concatenated across scopes rather than replaced, so lower-priority scopes can add entries without overriding higher-priority ones.

Create .claude/settings.local.json for permission changes you do not want committed. It is auto-gitignored.

---

The Full Folder Structure

your-project/
├── CLAUDE.md                  # Team instructions (committed)
├── CLAUDE.local.md            # Your personal overrides (gitignored)
│
└── .claude/
    ├── settings.json          # Permissions and config (committed)
    ├── settings.local.json    # Personal permission overrides (gitignored)
    ├── commands/              # Custom slash commands
    │   ├── review.md          # /project:review
    │   └── fix-issue.md       # /project:fix-issue
    ├── rules/                 # Modular, path-scoped instructions
    │   ├── code-style.md
    │   └── api-conventions.md
    ├── skills/                # Auto-invoked workflows
    │   └── security-review/
    │       └── SKILL.md
    └── agents/                # Specialized subagent personas
        └── code-reviewer.md

~/.claude/
├── CLAUDE.md                  # Your global instructions (all projects)
├── settings.json              # Your global settings
├── commands/                  # Personal commands (all projects)
├── skills/                    # Personal skills (all projects)
├── agents/                    # Personal agents (all projects)
└── projects/                  # Session history and auto-memory

---

A Practical Setup to Get Started

If you are starting from scratch, this progression works well for most projects.

Run /init inside Claude Code first. It generates a starter CLAUDE.md by reading your project. Edit it down to the essentials and keep it under 200 lines.

Add .claude/settings.json with allow and deny rules appropriate for your stack. At minimum, allow your run commands and deny .env reads.

Create one or two commands for the workflows you run most often. Code review and issue fixing are good starting points.

As your project grows and CLAUDE.md gets crowded, start splitting instructions into .claude/rules/ files and scope them by path where it makes sense.

Add a ~/.claude/CLAUDE.md with your personal preferences. This is where you put things like "always write types before implementations" or "prefer functional patterns over class-based."

That covers 95% of projects. Skills and agents come in when you have recurring complex workflows worth packaging.

---

Key Facts at a Glance

• CLAUDE.md loads into every session automatically, no configuration needed
• Max recommended length: 200 lines before instruction adherence drops
• Priority order: Managed policy beats global beats project beats local
• commands/ files trigger when you type a slash command
• skills/ files trigger automatically when the task matches the description
• agents/ run in isolated context windows, keeping the main session clean
• settings.json: controls OS-level permissions, not just conversational behavior
• settings.local.json: personal overrides, always gitignored
• ~/.claude/: personal config, never committed, applies across all projects

---

Sources and Further Reading

• Akshay Pachaar's original thread on the .claude folder anatomy (the foundation for this guide)
• Anthropic Claude Code official settings documentation
• Claude Code configuration files reference
• Complete settings.json guide

---

Published: March 23, 2026. Claude Code is updated frequently. Check the official documentation for the latest changes to the configuration system.