How to Configure Claude Code: The Complete Setup Guide (2026)

To configure Claude Code, you create three files: ~/.claude/CLAUDE.md for your identity and rules, ~/.claude/settings.json for permissions and guardrails, and skill files in ~/.claude/skills/ for reusable workflows. Claude Code reads these automatically at the start of every session. No plugins, no extensions, no restarts. Just files.

This guide covers the exact configuration I use across 160+ sessions and 9 production tools. Every example is real, tested, and running in production right now.

What Is Claude Code Configuration?

Claude Code is Anthropic's CLI tool that gives Claude direct access to your terminal, filesystem, and development tools. Out of the box, it works. But without configuration, every session starts from zero. Claude doesn't know who you are, what stack you use, or how you like to work.

Configuration fixes that. You write plain text files that Claude reads at session start. These files act as persistent memory, behavioral rules, and workflow automation. The system is intentionally simple: markdown files and JSON. No proprietary formats, no lock-in.

The official Anthropic documentation covers the basics. This guide covers what actually works in production.

CLAUDE.md - Your Identity File

The CLAUDE.md file is the single most important piece of Claude Code configuration. It loads at the start of every session and tells Claude who you are, how you work, and what rules to follow. Think of it as a persistent system prompt that lives on your filesystem.

Where It Goes

Claude Code loads CLAUDE.md files from three locations, in order:

1. ~/.claude/CLAUDE.md - Global. Loads every session, every project.
2. ~/.claude/projects/{project-path}/CLAUDE.md - Project-scoped but stored globally.
3. ./CLAUDE.md - Project root. Checked into version control with your team.

Later files override earlier ones. Use the global file for your identity and universal rules. Use project-level files for stack-specific instructions.

A Real, Working CLAUDE.md Template

Here is a production-ready starter template. This is not placeholder text. Every section earns its place.

# CLAUDE.md

## Who I Am
Jane Chen. Senior full-stack engineer at Acme Corp.
Primary stack: TypeScript, React, Node.js, PostgreSQL.
Prefer clear code over clever code. Tests before implementation.

## Rules - Always Follow These

### Code Style
- Use TypeScript strict mode. No `any` types.
- Prefer named exports over default exports.
- Error handling: never swallow errors silently. Log or throw.
- Use `const` by default. Only `let` when mutation is required.

### Git Workflow
- Always create a feature branch. Never commit directly to main.
- Commit messages: imperative mood, under 72 characters.
- Run tests before every commit. If tests fail, fix them first.

### Testing
- Write tests before implementation (TDD).
- Unit tests for business logic. Integration tests for API routes.
- Use vitest for unit tests, playwright for e2e.

### Communication
- Explain what you are about to do before doing it (one sentence).
- After writing code, explain what it does and why.
- If you are unsure about a decision, ask. Do not guess.

## Preferences
- Prefer open-source packages over proprietary ones.
- Keep solutions simple. A 10-line script beats a framework.
- Plain language in comments. No jargon without context.

## Project Context
- Monorepo: apps/web (Next.js), apps/api (Express), packages/shared
- Database: PostgreSQL 16 on Supabase
- CI: GitHub Actions. All PRs require passing tests.
- Deploy: Vercel (web), Railway (api)

What Makes It Effective

• Identity section is short. Name, role, stack. Claude does not need your life story.
• Rules are specific and actionable. "Use TypeScript strict mode" is enforceable. "Write good code" is not.
• Preferences state tradeoffs. "Simple over clever" tells Claude which direction to lean when choosing between approaches.
• Project context is structural. Directory layout, database, CI, deploy targets. These prevent wrong assumptions.

settings.json - Permissions and Guardrails

The ~/.claude/settings.json file controls what Claude Code can do without asking for permission. By default, Claude asks before running most shell commands. The settings file lets you pre-approve safe commands and block dangerous ones.

A Full Working settings.json

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(npx *)",
      "Bash(node *)",
      "Bash(git status)",
      "Bash(git diff*)",
      "Bash(git log*)",
      "Bash(git branch*)",
      "Bash(git checkout*)",
      "Bash(git add *)",
      "Bash(git commit*)",
      "Bash(git push*)",
      "Bash(git pull*)",
      "Bash(git stash*)",
      "Bash(ls *)",
      "Bash(cat *)",
      "Bash(mkdir *)",
      "Bash(cp *)",
      "Bash(mv *)",
      "Bash(rm *)",
      "Bash(grep *)",
      "Bash(find *)",
      "Bash(wc *)",
      "Bash(head *)",
      "Bash(tail *)",
      "Bash(sort *)",
      "Bash(which *)",
      "Bash(echo *)",
      "Bash(pwd)",
      "Bash(docker compose *)",
      "Bash(gh *)",
      "Read",
      "Write",
      "Edit",
      "Glob",
      "Grep"
    ],
    "deny": [
      "Bash(curl * | bash)",
      "Bash(wget * | bash)",
      "Bash(rm -rf /)",
      "Bash(sudo *)",
      "Bash(chmod 777 *)",
      "Bash(git push --force origin main)"
    ]
  }
}

Understanding the Permission Model

• allow - Commands matching these patterns run without asking. Wildcards (*) match any arguments.
• deny - Commands matching these patterns are blocked entirely. Deny always wins over allow.
• Anything not listed - Claude asks for permission before running. This is the safe default.

Common Permission Patterns

Python developer:

"Bash(python *)",
"Bash(python3 *)",
"Bash(pip install *)",
"Bash(pytest *)",
"Bash(uv *)",
"Bash(ruff *)"

Rust developer:

"Bash(cargo *)",
"Bash(rustup *)",
"Bash(rustc *)"

Full-stack (Node + Docker + cloud CLI):

"Bash(npm *)",
"Bash(pnpm *)",
"Bash(docker *)",
"Bash(railway *)",
"Bash(vercel *)",
"Bash(gh *)"

Start with a tight allow list and expand it as you find yourself approving the same commands repeatedly. You can also approve commands on the fly during a session - Claude remembers within that session.

Skills - Reusable Workflows

Skills are the most powerful and least understood part of Claude Code configuration. A skill is a markdown file that defines a complete workflow for a specific task. Unlike CLAUDE.md (which loads every session), skills load on demand when you invoke them.

How Skills Differ from Prompts

A prompt is a one-shot instruction. A skill is a repeatable process with steps, decision points, and guardrails. You write a prompt once and forget it. You invoke a skill every time you do that type of work, and it enforces the same quality bar every time.

Where Skills Go

Skills live in ~/.claude/skills/. Each skill is a single markdown file. The filename becomes the skill name.

~/.claude/skills/
  test-driven-development.md
  systematic-debugging.md
  code-review.md
  writing-plans.md

Example: Test-Driven Development Skill

# Test-Driven Development

## When to Use
Before implementing any feature or bug fix.

## Process

### Step 1: Understand the requirement
- Read the spec, issue, or user description.
- State what you are about to build in one sentence.
- Identify the inputs, outputs, and edge cases.

### Step 2: Write the test first
- Create a failing test that describes the expected behavior.
- Run the test. Confirm it fails for the right reason.
- Do NOT write implementation code yet.

### Step 3: Write the minimum implementation
- Write only enough code to make the test pass.
- No extra features. No premature optimization.
- Run the test. Confirm it passes.

### Step 4: Refactor
- Clean up the implementation without changing behavior.
- Run tests again. Still green? Good.
- Look for duplication, unclear names, unnecessary complexity.

### Step 5: Repeat
- Move to the next test case.
- Follow the same red-green-refactor cycle.

## Rules
- NEVER write implementation before the test exists.
- NEVER skip the failing test verification.
- If a test is hard to write, the interface is wrong. Redesign it.

Example: Systematic Debugging Skill

# Systematic Debugging

## When to Use
When encountering any bug, test failure, or unexpected behavior.

## Process

### Step 1: Reproduce
- Get the exact error message or unexpected behavior.
- Find the minimal reproduction case.
- Do NOT guess at the cause yet.

### Step 2: Gather evidence
- Read the relevant source code. Do not assume you know what it does.
- Check recent changes with git log and git diff.
- Look at test output, logs, and stack traces.

### Step 3: Form a hypothesis
- Based on evidence, state one specific theory.
- Predict what you would see if the theory is correct.
- Identify one test or check that proves or disproves it.

### Step 4: Test the hypothesis
- Run the specific check. Did it confirm or deny?
- If denied: go back to Step 2 with new information.
- If confirmed: proceed to fix.

### Step 5: Fix and verify
- Make the smallest change that fixes the root cause.
- Run the original reproduction case. Does it pass?
- Run the full test suite. Any regressions?

## Rules
- NEVER apply a fix without reproducing the bug first.
- NEVER guess. Evidence before hypotheses, hypotheses before fixes.
- If you are on your third hypothesis, step back and re-read the code.

How to Invoke Skills

In Claude Code, use the Skill tool to invoke a skill by name:

Use the skill: test-driven-development

Or reference it in your CLAUDE.md with a rule like:

## Skill Enforcement
- Before implementing any feature: invoke `test-driven-development`
- Before proposing any bug fix: invoke `systematic-debugging`
- Before claiming work is done: invoke `verification-before-completion`

This turns skills from optional guidance into mandatory checkpoints.

Hooks - Automatic Triggers

Hooks run shell commands automatically at key moments during a Claude Code session. They are configured in settings.json and fire without any manual invocation.

Available Hook Points

• SessionStart - Runs when a new session begins. Good for loading context.
• PostToolUse - Runs after Claude uses a tool. Good for monitoring and warnings.
• PreCompact - Runs before context compaction. Good for preserving state.

Example: Context Warning Hook

This hook checks context usage after every tool call and warns when you are running low:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "*",
        "command": "echo 'Context check: review usage if this session has been long'"
      }
    ]
  }
}

Example: Session Start Hook

Load critical context files automatically when a session begins:

{
  "hooks": {
    "SessionStart": [
      {
        "command": "cat ~/.claude/context/current-sprint.md 2>/dev/null || true"
      }
    ]
  }
}

Hooks keep your sessions consistent without requiring you to remember setup steps every time.

Putting It All Together

The Complete File Tree

Before and After

Before configuration: Every session starts cold. Claude asks what stack you use. You repeat your preferences. It runs commands you have to approve one by one. It forgets your git workflow. You re-explain your testing approach.

After configuration: Claude knows your name, stack, and workflow from the first message. Safe commands run without prompts. Skills enforce consistent quality. Hooks load context automatically. You go from setup to productive work in seconds.

The difference is not subtle. It is the difference between having a new contractor every day and having a teammate who knows the codebase.

Frequently Asked Questions

Do I need to restart Claude Code after changing config?

No. Claude Code reads CLAUDE.md fresh at the start of each session. Changes to settings.json and skills take effect on your next session. No restart, no reload command. Just save the file and start a new session.

Can I have project-specific configuration?

Yes. Place a CLAUDE.md file in your project root for project-specific instructions. Claude Code loads files in order: ~/.claude/CLAUDE.md (global), then ~/.claude/projects/{path}/CLAUDE.md (project-scoped global), then ./CLAUDE.md (project root). Project instructions build on top of global ones.

What is the difference between skills and CLAUDE.md?

CLAUDE.md defines identity - who you are, how you work, your preferences. It loads every session automatically. Skills define workflows - step-by-step procedures for specific tasks like TDD, debugging, or code review. They load on demand when invoked. Identity is passive context. Skills are active processes.

How do I know if my config is working?

Ask Claude "What do you know about me from CLAUDE.md?" at the start of a session. It will summarize what it loaded. You can also check active settings by asking Claude to describe its current permissions, or ask it to list available skills.