Configuration Files

Claude Code uses several configuration files to customize behavior, manage projects, and integrate with tools.

CLAUDE.md

The most important configuration file - acts as persistent memory and project-specific instructions.

Location

CLAUDE.md files are loaded from:

1. Current working directory
2. All parent directories (up to root)
3. Home directory (~/CLAUDE.md)

Files are merged with closer files taking precedence.

Basic Structure

# Project Name

## Overview
Brief description of the project and its purpose.

## Tech Stack
- Frontend: React, TypeScript, Tailwind
- Backend: Node.js, Express, PostgreSQL
- Testing: Jest, React Testing Library

## Development
- `npm run dev` - Start development server
- `npm test` - Run tests
- `npm run build` - Build for production

## Conventions
- Use TypeScript for all new files
- Follow ESLint rules
- Write tests for new features

## Architecture
Description of key architectural decisions and patterns.

## Important Notes
- Never modify files in vendor/
- Always run tests before committing
- Use feature branches for new work

Advanced Sections

## Commands
Frequently used commands and their purposes:
- `make migrate` - Run database migrations
- `make seed` - Seed development data
- `./scripts/deploy.sh staging` - Deploy to staging

## Environment Variables
Required environment variables:
- `DATABASE_URL` - PostgreSQL connection string
- `REDIS_URL` - Redis connection string
- `JWT_SECRET` - JWT signing secret

## Testing Strategy
- Unit tests for utilities and helpers
- Integration tests for API endpoints
- E2E tests for critical user flows

## Deployment
Deployment process and considerations:
1. Run tests: `npm test`
2. Build: `npm run build`
3. Deploy: `./deploy.sh production`

## Troubleshooting
Common issues and solutions:
- Port already in use: `lsof -i :3000` and kill process
- Database connection failed: Check DATABASE_URL

Dynamic Sections

## Current Sprint
Working on: User authentication
- [x] Login endpoint
- [x] Registration endpoint
- [ ] Password reset
- [ ] OAuth integration

## Recent Decisions
- 2024-01-15: Chose JWT over sessions for stateless auth
- 2024-01-10: Migrated from CRA to Vite for faster builds

## Known Issues
- Performance: Dashboard slow with 1000+ items
- UX: Mobile navigation needs improvement

.claude/settings.json

Project-specific Claude settings.

Structure

{
  "defaultModel": "sonnet",
  "allowedTools": [
    "Read",
    "Edit",
    "Write",
    "Bash(git:*)",
    "Bash(npm:*)"
  ],
  "mcp": {
    "think-tool": {
      "transport": "local",
      "command": "think-tool",
      "args": ["start"]
    }
  },
  "autoContext": {
    "include": ["src/**/*.ts", "*.md"],
    "exclude": ["node_modules", "dist", "*.test.ts"]
  },
  "customPrompts": {
    "codeReview": "Review code for security, performance, and best practices",
    "testGeneration": "Generate comprehensive tests with edge cases"
  }
}

Configuration Options

Key	Type	Description
defaultModel	string	Default model (opus/sonnet/haiku)
allowedTools	array	Pre-allowed tools
mcp	object	MCP server configurations
autoContext	object	Automatic file inclusion rules
customPrompts	object	Reusable prompt templates
theme	string	UI theme (light/dark)
autoSave	boolean	Auto-save conversations
contextLimit	number	Max context tokens

~/.claude/settings.json

Global Claude settings (user-level).

Example

{
  "apiKey": "${ANTHROPIC_API_KEY}",
  "defaultModel": "sonnet",
  "theme": "dark",
  "editor": "code",
  "shortcuts": {
    "review": "Review this code for best practices",
    "explain": "Explain how this works in simple terms",
    "optimize": "Optimize this for performance"
  },
  "globalAllowedTools": [
    "Read",
    "LS"
  ],
  "logging": {
    "level": "info",
    "file": "~/.claude/claude.log"
  }
}

Environment Variable Substitution

Use ${VAR_NAME} syntax:

{
  "apiKey": "${ANTHROPIC_API_KEY}",
  "proxy": "${HTTP_PROXY}",
  "customHeader": "Bearer ${AUTH_TOKEN}"
}

.claudeignore

Exclude files from Claude's context (similar to .gitignore).

Example

# Dependencies
node_modules/
vendor/
bower_components/

# Build outputs
dist/
build/
*.min.js
*.map

# Large files
*.mp4
*.zip
*.tar.gz

# Sensitive files
.env
.env.*
secrets/
*.key
*.pem

# IDE
.idea/
.vscode/
*.swp

# Logs
*.log
logs/

# OS
.DS_Store
Thumbs.db

Patterns

• * - Match any characters except /
• ** - Match any characters including /
• ? - Match single character
• [abc] - Match any character in brackets
• !pattern - Negate pattern

MCP Configuration

Project-Level (.claude/mcp.json)

{
  "servers": {
    "github": {
      "transport": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer ${GITHUB_TOKEN}"
      }
    },
    "database": {
      "transport": "local",
      "command": "mcp-postgres",
      "args": ["--connection", "${DATABASE_URL}"],
      "env": {
        "NODE_ENV": "development"
      }
    }
  },
  "autoStart": ["github"],
  "permissions": {
    "github": ["read", "write"],
    "database": ["read"]
  }
}

Global MCP (~/.claude/mcp.json)

{
  "registry": "https://registry.mcp.anthropic.com",
  "servers": {
    "filesystem": {
      "transport": "local",
      "command": "mcp-filesystem",
      "autoStart": true
    }
  },
  "defaults": {
    "timeout": 30000,
    "retries": 3
  }
}

Hooks Configuration

.claude/hooks.json

{
  "preCommand": {
    "Bash": "echo 'Executing: $COMMAND' >> audit.log"
  },
  "postCommand": {
    "Edit": "./scripts/lint-changed-files.sh"
  },
  "preSession": "./scripts/setup-environment.sh",
  "postSession": "./scripts/cleanup.sh",
  "onError": {
    "script": "./scripts/error-handler.sh",
    "notificationUrl": "https://hooks.slack.com/..."
  }
}

IDE-Specific Configurations

VS Code (.vscode/claude.json)

{
  "claude.autoStart": true,
  "claude.defaultModel": "sonnet",
  "claude.inlineCompletions": true,
  "claude.showDiff": true,
  "claude.shortcuts": {
    "explainSelection": "Ctrl+Shift+E",
    "reviewFile": "Ctrl+Shift+R"
  }
}

JetBrains (.idea/claude.xml)

<component name="ClaudeSettings">
  <option name="defaultModel" value="opus" />
  <option name="autoContext" value="true" />
  <option name="showInlineHints" value="true" />
</component>

Best Practices

1. CLAUDE.md Organization

Keep CLAUDE.md focused and scannable:

## 🚀 Quick Start
Essential commands for new developers

## 📋 Current Tasks
What we're working on right now

## 🏗️ Architecture
High-level design decisions

## 📚 Resources
Links to documentation and designs

2. Sensitive Data

Never commit sensitive data:

// Bad
{
  "apiKey": "sk-ant-12345"
}

// Good
{
  "apiKey": "${ANTHROPIC_API_KEY}"
}

3. Modular Configuration

Split large CLAUDE.md files:

project/
├── CLAUDE.md          # Main project info
├── docs/
│   └── CLAUDE.md      # Documentation-specific
├── frontend/
│   └── CLAUDE.md      # Frontend-specific
└── backend/
    └── CLAUDE.md      # Backend-specific

4. Version Control

Track configurations:

# .gitignore
.claude/settings.json  # May contain secrets
.claude/cache/
.claude/logs/

# Track these
CLAUDE.md
.claudeignore
.claude/hooks.json

Configuration Precedence

1. Command-line arguments (highest)
2. Environment variables
3. Project settings (.claude/settings.json)
4. User settings (~/.claude/settings.json)
5. System defaults (lowest)

Troubleshooting

Configuration Not Loading

# Check which config files are loaded
claude config sources

# Validate configuration
claude config validate

# Show merged configuration
claude config show --merged

Common Issues

CLAUDE.md not found:

• Check file name (case-sensitive)
• Ensure it's in project root
• Try /memory load

Settings not applied:

• Check JSON syntax
• Verify file permissions
• Look for override settings

MCP servers failing:

• Check server installation
• Verify transport settings
• Review server logs

Next Steps

• Review CLI Reference
• Explore Workflows
• Learn about MCP Servers