← z3n.iwnl

The .claude/ Folder — The Control Center Nobody Opens

March 27, 2026 · 5 min read

You're using Claude Code. You've seen that .claude folder appear in your project root.

You've never opened it.

That's like buying a sports car and never touching the dashboard. The .claude/ folder is the entire control center for how Claude behaves in your project — and most developers treat it like a black box.

Let's fix that.

Two .claude Folders, Not One

First surprise: there are actually two .claude directories.

The project-level one gets committed to git. Everyone on your team shares the same rules. The global one in your home directory? That's personal. Your preferences, your session history, your shortcuts.

CLAUDE.md — The Highest-Leverage File

This is the most important file in the entire system. When a Claude Code session starts, CLAUDE.md loads directly into the system prompt. Claude reads it and follows it for the entire conversation.

Write too little, and Claude constantly asks for clarification. Write too much, and it drowns in context. The sweet spot is under 200 lines.

What to include:

• Build, test, and lint commands
• Key architectural decisions ("we use Turborepo monorepo")
• Non-obvious gotchas ("TypeScript strict mode, unused vars = errors")
• Import conventions and naming patterns

What to skip:

• Anything that belongs in a linter config
• Full documentation (just link to it)
• Long theory explanations

CLAUDE.local.md — Your Personal Playground

Some preferences are just for you. Maybe you prefer a different test runner. Maybe you want Claude to always use your preferred debugging pattern.

Create CLAUDE.local.md in your project root. It's automatically gitignored. Your personal tweaks never land in the repo. Your team never sees them.

The rules/ Folder — When CLAUDE.md Gets Crowded

Once your CLAUDE.md hits 300 lines, nobody maintains it and everyone ignores it. The solution: split it up.

Each file loads alongside CLAUDE.md automatically. The team member who owns API conventions edits api-conventions.md. Testing person edits testing.md. Nobody stomps on each other.

The real power: path-scoped rules. Add YAML frontmatter and a rule only activates for matching files:

---
paths: ["src/api/**", "src/handlers/**"]
---

Always validate request bodies against the OpenAPI schema.
Return 400 with structured error messages.

Claude won't load this when editing React components. Only when touching API code. This is the pattern.

commands/ — Your Custom Slash Commands

Every markdown file in .claude/commands/ becomes a slash command. Drop in review.md, get /project:review.

// .claude/commands/review.md

Review the current git diff for issues:
!`git diff HEAD~1`

Focus on:
- Security vulnerabilities
- Error handling gaps  
- Performance red flags

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

Use $ARGUMENTS to pass dynamic input: /project:fix-issue 234 feeds issue 234's content into the prompt.

Project commands go in .claude/commands/ (shared). Personal commands go in ~/.claude/commands/ (show up as /user:command-name).

Skills vs Commands — Know the Difference

They look similar. They're not.

Commands wait for you. You type /project:review, it runs.

Skills watch and act. They sit in the background, and when the task matches their description, Claude invokes them automatically.

Skills also bundle supporting files. A skill directory can have its own SKILL.md, reference docs, even scripts. Commands are single files. Skills are packages.

agents/ — Spawn Subagent Personas

For complex recurring tasks, define a subagent in .claude/agents/. Each agent gets its own system prompt, tool restrictions, and model preference:

// .claude/agents/code-reviewer.md

You are a senior code reviewer.
Focus on security, performance, and maintainability.

tools: Read, Grep, Glob
model: haiku

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

The tools field restricts what the agent can touch. A security auditor only needs read access. The model field lets you use cheaper models for focused tasks.

settings.json — The Permission Layer

This is where you define what Claude can and can't do:

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

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

There's also settings.local.json for personal permission overrides. Auto-gitignored, same as CLAUDE.local.md.

The 5-Step Setup

Starting from scratch? Here's the progression:

1. Run /init inside Claude Code → generates starter CLAUDE.md → edit it down
2. Add .claude/settings.json with allow/deny rules for your stack
3. Create 1-2 commands for workflows you do most (code review, issue fixing)
4. As CLAUDE.md grows, split instructions into .claude/rules/ files
5. Add ~/.claude/CLAUDE.md with personal preferences

The .claude folder is a protocol for telling Claude who you are, what your project does, and what rules it should follow. The clearer you define that, the less time you spend correcting Claude and the more time it spends doing actual work.

Get CLAUDE.md right first. Everything else is optimization.