Claude Code Configuration

Problem: Fresh Claude Code sessions hand back generic answers because they know nothing about your project.

Quick Win: Drop a CLAUDE.md into your project root and the next session reads it before you type a word.

Result: Answers stop sounding like a stock tutorial and start matching your actual stack.

Three files do most of the work. CLAUDE.md gives Claude context. MCP servers give it tools. Slash commands give it workflows. Set up once, reuse everywhere.

Create the Config Files

Two commands start you off:

touch CLAUDE.md                    # Project root - required
mkdir -p .claude/commands          # Custom workflows - optional

That's the whole skeleton. Now fill it in.

CLAUDE.md (Required)

Drop this into the project root. Claude reads it on every session start:

# [Project Name] - Development Context

## What This Project Does

[2-sentence description of your app's purpose]

## Tech Stack & Version

- Frontend: React 18.2.0 with TypeScript 5.0
- Backend: Node.js with Express or Next.js App Router
- Database: PostgreSQL 15 with Prisma ORM
- Styling: Tailwind CSS 3.4

## File Structure

src/
├── app/ # Next.js pages (App Router)
├── components/ # Reusable UI components
├── lib/ # Utilities and configurations
└── types/ # TypeScript definitions

## Current Sprint Goals
- [ ] User authentication system
- [ ] Dashboard with user data
- [ ] API endpoints for CRUD operations

## Never Touch Without Permission
- package.json dependencies (ask first)
- Database migrations (explain changes)
- Production environment variables

Success Check: Claude mentions your stack and sprint goals in its next reply, without being asked.

MCP Servers (Power Features)

MCP (Model Context Protocol) servers bolt real tools onto Claude. Put them in your global settings at ~/.claude/settings.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem"],
      "env": {
        "ACCESS_DIRECTORIES": "/Users/yourname/projects"
      }
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

What that buys you:

• Direct file read and write
• GitHub repository searching
• Access to project documentation
• Pattern recognition across your code

Success Check: Claude can now open files and hit GitHub without you pasting anything.

Slash Commands (Reusable Workflows)

Any markdown file under .claude/commands/ becomes a slash command. Name the file, get the command for free.

Debug Workflow (.claude/commands/debug.md):

# Debug Workflow

When debugging:

1. Reproduce the error in isolation
2. Check browser console and network tab
3. Add console.logs to trace execution
4. Test with minimal data
5. Check recent changes in git log
6. Ask before suggesting major architecture changes

Test Generation (.claude/commands/test.md):

# Test Generation Guidelines

For new functions:

1. Write unit tests with Jest/Vitest
2. Test happy path and edge cases
3. Mock external dependencies
4. Use descriptive test names
5. Aim for 80% coverage on critical paths

Usage: Type /debug or /test in any session and Claude runs the workflow.

Success Check: Claude follows the same documented steps every time.

Common Configuration Fixes

When CLAUDE.md gets heavy, split it. Keep the root file short and point to the rest:

# Main CLAUDE.md (keep short)

See also:

- .claude/database-schema.md (detailed schema)
- .claude/api-patterns.md (endpoint conventions)

The settings.json Scope System

Past CLAUDE.md, Claude Code uses settings.json files for permissions, env vars, default models, and tool behavior. Four scopes stack, and the narrower one wins:

Precedence, top to bottom: Managed > Command line args > Local > Project > User. Managed settings always win, so company policy stays enforced.

Add $schema at the top of your settings.json and VS Code, Cursor, or any JSON-schema editor will autocomplete and validate as you type:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": ["Bash(npm run lint)", "Bash(npm run test *)"],
    "deny": ["Read(./.env)", "Read(./.env.*)", "Read(./secrets/**)"]
  },
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1"
  }
}

Claude Code also timestamps every settings edit and keeps the five most recent backups, so a bad save doesn't cost you anything.

Key Settings Categories

Each category has its own dedicated guide. Short version:

• Permissions. Gate which tools Claude uses, which files it reads, which commands it runs. Rules go under allow, deny, and ask.
• Sandbox. Box bash commands away from your filesystem and network, enforced at the OS level. Flip it on with /sandbox or sandbox.enabled.
• Attribution. Keep or kill the Co-Authored-By trailer on commits and PRs. Commits and PRs configure separately.
• Plugins. Pull in skills, agents, hooks, and MCP servers from marketplaces. Controlled by enabledPlugins and extraKnownMarketplaces.
• Model. Pin a default via the model key instead of passing --model every time.
• Status Line. Put live context usage, git branch, model name, or cost into a persistent bar.
• Keybindings. Rebind keys with /keybindings, which writes to ~/.claude/keybindings.json.

Essential Environment Variables

Env vars give you the finest control over Claude Code. Set them in your shell profile, pass them inline, or tuck them inside the env key in settings.json. The ones worth knowing:

Three ways to apply them. Inline for a one-off session:

ANTHROPIC_MODEL=claude-sonnet-4-20250514 claude

Persistent, by adding to ~/.bashrc or ~/.zshrc:

export CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=80
export MAX_THINKING_TOKENS=10000

Or bake them into settings.json so they apply every run:

{
  "env": {
    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "80",
    "MAX_THINKING_TOKENS": "10000"
  }
}

Around 70 env vars exist. The settings reference has the full list, and the terminal setup guide covers line breaks and notifications.

Global vs Project Configuration

Global Settings (~/.claude/settings.json):

• MCP server configurations
• Personal preferences and model defaults
• Universal coding standards

Project Settings (project root):

• CLAUDE.md. Project context and rules.
• .claude/commands/. Custom slash commands.
• .claude/settings.json. Team-shared permissions, hooks, and MCP servers.
• .claude/settings.local.json. Your personal overrides for this project (gitignored).

Priority again, briefly: Managed > Local > Project > User. Run /init and Claude writes a starter CLAUDE.md for you.

Working in a monorepo or sharing standards across repos? The --add-dir flag lets Claude load CLAUDE.md files from extra directories.

Next Steps

Claude Code is now configured. From here:

• Build your first project on top of the configured setup
• Pick up terminal control techniques
• Dig into context management strategies
• Add more MCP servers from the popular list
• Hit the troubleshooting guide if anything snags

Pro Tip: Keep CLAUDE.md fresh. Stack changes, priorities shift, sprint goals rotate. Update the file when they do. Claude is only as sharp as the context you feed it.