The .claude Folder: A Complete Guide to Configuring Claude Code Like a Pro

The first .claude folder lives inside your project. You commit it to git. Everyone on the team gets the same rules, the same commands, the same permissions.

The second one lives in your home directory: ~/.claude/. That's your personal configuration — preferences, session history, auto-memory. It follows you across every project.

Think of it this way:

Get this distinction wrong and you'll either pollute your repo with personal preferences or lose team conventions that should be shared.

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 memory for the entire conversation.

Whatever you write in CLAUDE.md, Claude follows. Tell it to always write tests before implementation — it will. Tell it to never use console.log for error handling — it won't.

You can place CLAUDE.md in three locations:

• Project root (./CLAUDE.md) — most common, team-wide
• Global (~/.claude/CLAUDE.md) — your personal defaults across all projects
• Subdirectories — folder-specific rules for monorepos

Claude reads all of them and combines them.

💡 Keep it under 200 lines. Longer files eat too much context and Claude's instruction adherence actually drops.

Here's a minimal but effective example:

# Project: Acme API

npm run dev # Start dev server
npm run test # Run tests (Jest)
npm run build # Production build

• Express REST API, Node 20
• PostgreSQL via Prisma ORM
• All handlers live in src/handlers/

• Use zod for request validation
• Return shape is always { data, error }
• Use the logger module, not console.log

• Tests use a real local DB, not mocks
• Strict TypeScript: no unused imports

That's 20 lines. It gives Claude everything it needs to work productively without constant clarification.

⚠️ **Don't put linter rules in CLAUDE.md.** Those belong in `.eslintrc` or `prettier.config`. CLAUDE.md is for things your linter can't enforce — architectural decisions, naming patterns, non-obvious gotchas.

Want a personalized version? `CLAUDE.local.md` in your project root works exactly like CLAUDE.md but is automatically gitignored. Your personal tweaks never land in the repo.

Once your team grows, CLAUDE.md becomes a 300-line monster that nobody maintains. The rules/ folder fixes this.

Every markdown file inside .claude/rules/ gets loaded alongside CLAUDE.md automatically:

.claude/rules/
├── code-style.md
├── testing.md
├── api-conventions.md
└── security.md

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

The real power: path-scoped rules. Add YAML frontmatter and a rule only activates when Claude works with matching files:

---
paths:
  - "src/api/**/*.ts"
  - "src/handlers/**/*.ts"
---
# API Design Rules
- All handlers return { data, error }
- Use zod for request validation

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

Every markdown file in .claude/commands/ becomes a slash command. A file named review.md creates /project:review.

The killer feature: the ! backtick syntax runs shell commands and embeds the output before Claude sees the prompt:

---
description: Review current branch before merging
---

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

!git diff main...HEAD

Review these changes for bugs, security issues,
and missing test coverage.

Now `/project:review` automatically injects the real git diff into the prompt. That's what makes commands genuinely useful instead of just saved text.

You can pass arguments too. Use `$ARGUMENTS` in your command file:

```markdown
---
description: Investigate and fix a GitHub issue
argument-hint: [issue-number]
---
Look at issue #$ARGUMENTS. Fix the root cause
and write a test that would have caught it.

Running /project:fix-issue 234 feeds issue 234's content directly in.

Personal commands go in ~/.claude/commands/ and show up as /user:command-name across all projects.

Skills look similar to commands on the surface. The difference is fundamental: commands wait for you to type a slash. Skills watch the conversation and activate when the task matches.

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

.claude/skills/
├── security-review/
│   ├── SKILL.md
│   └── DETAILED_GUIDE.md
└── deploy/
    ├── SKILL.md
    └── templates/
        └── release-notes.md

The SKILL.md uses YAML frontmatter to describe when it should trigger:

---
name: security-review
description: Comprehensive security audit. Use when reviewing
  code for vulnerabilities or before deployments.
allowed-tools: Read, Grep, Glob
---
Analyze the codebase for security vulnerabilities...

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

The key advantage over commands: skills can bundle supporting files. The @DETAILED_GUIDE.md reference pulls in a detailed document that lives right next to SKILL.md. Commands are single files. Skills are packages.

For complex tasks that benefit from a dedicated specialist, define subagent personas in .claude/agents/:

---
name: code-reviewer
description: Expert code reviewer. Use PROACTIVELY
  when reviewing PRs or validating implementations.
model: sonnet
tools: Read, Grep, Glob
---
You are a senior code reviewer focused on correctness.
Flag bugs, not style issues. Suggest specific fixes.

When Claude needs a code review, it spawns this agent in its own isolated context window. The agent does its work, compresses the findings, and reports back. Your main session stays clean.

The tools field restricts what the agent can do — a security auditor that only needs Read, Grep, and Glob has no business writing files.

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

The settings.json inside .claude/ controls what Claude can and can't do:

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git status)",
      "Read",
      "Write",
      "Edit"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(curl *)",
      "Read(./.env)"
    ]
  }
}

Allow list — runs without confirmation. Cover your build scripts and git read commands.

Deny list — blocked entirely. Destructive shell commands, direct network calls, sensitive files.

Anything not in either list: Claude asks before proceeding. That middle ground is intentional.

Same pattern as before: settings.local.json for personal overrides, auto-gitignored.

Here's how everything fits together:

your-project/
├── CLAUDE.md                  # Team instructions
├── CLAUDE.local.md            # Personal overrides (gitignored)
└── .claude/
    ├── settings.json          # Permissions (committed)
    ├── settings.local.json    # Personal perms (gitignored)
    ├── commands/              # Custom slash commands
    ├── rules/                 # Modular instruction files
    ├── skills/                # Auto-invoked workflows
    └── agents/                # Subagent personas

~/.claude/
├── CLAUDE.md                  # Global instructions
├── commands/                  # Personal commands
├── skills/                    # Personal skills
├── agents/                    # Personal agents
└── projects/                  # Session history + memory

Don't try to set up everything at once. Here's the progression:

• Run /init inside Claude Code — it generates a starter CLAUDE.md
• Edit it down to essentials (build commands, architecture, conventions)
• Add settings.json with allow/deny rules for your stack
• Create 1-2 commands for your most common workflows
• Split CLAUDE.md into rules/ files when it gets crowded
• Add ~/.claude/CLAUDE.md with your personal coding preferences
• Package recurring complex workflows as skills

That covers 95% of what you'll ever need. Skills and agents come later, when you have workflows worth packaging.

Can CLAUDE.md break anything?

No. CLAUDE.md is just instructions — it doesn't execute code or change permissions. The worst case is Claude follows a bad instruction, which you can always override.

How is CLAUDE.md different from a system prompt?

It effectively IS a system prompt, but managed as a file in your project. The benefit: it's versioned in git, shared with your team, and split across multiple files.

Do I need both commands and skills?

Start with commands. They're simpler — one file, one slash command. Move to skills only when you need bundled supporting files or automatic triggering without a slash command.

What happens if project and global settings conflict?

Project settings take priority. Your global ~/.claude/CLAUDE.md sets defaults, but project-level CLAUDE.md and .claude/settings.json override them.

How do I reset Claude's memory for a project?

Delete the project folder inside ~/.claude/projects/. Next session starts fresh with no auto-memory from previous conversations.

Subscribe to our newsletter at aimakerslab.io/newsletter to get more guides like this straight to your inbox.