Configuration Deep Dive

Configuration Overview

Claude Code can be customized at multiple levels:

Project settings override global settings. Session flags override both.

Global Settings

Your global settings apply to all Claude Code sessions.

Location

Example Global Settings

json
Copy
{
  "theme": "dark",
  "defaultModel": "claude-sonnet-4-20250514",
  "autoApprove": {
    "read": true,
    "write": false,
    "execute": false
  },
  "editor": "code",
  "maxTokens": 4096,
  "temperature": 0
}

Key Settings Explained

Project Settings

Project settings live in your repository and apply to everyone working on that project.

Location

your-project/
├── .claude/
│   └── settings.json
├── src/
└── package.json

Example Project Settings

json
Copy
{
  "projectContext": "This is a Next.js 15 e-commerce application using TypeScript.",
  "conventions": {
    "components": "Use functional components with TypeScript interfaces",
    "styling": "Use Tailwind CSS, no inline styles",
    "imports": "Use absolute imports from @/ prefix"
  },
  "ignore": [
    "node_modules",
    ".next",
    "*.log",
    ".env*"
  ],
  "testCommand": "npm run test",
  "buildCommand": "npm run build",
  "lintCommand": "npm run lint"
}

Key Project Settings

The AGENTS.md File

AGENTS.md is a special file that gives Claude Code detailed instructions about your project.

Why AGENTS.md?

While settings.json handles technical configuration, AGENTS.md handles context and behavior:

• How your project is structured
• Coding conventions and patterns
• What to do (and not do)
• Domain-specific knowledge

Location

Place it in your project root:

your-project/
├── AGENTS.md
├── .claude/
│   └── settings.json
├── src/
└── package.json

Example AGENTS.md

markdown
Copy
# Project: E-Commerce Platform

## Overview
This is a Next.js 15 e-commerce application with:
- App Router for routing
- TypeScript for type safety
- Tailwind CSS for styling
- Prisma for database access
- Stripe for payments

## Architecture

### Directory Structure
- `/src/app` - Next.js App Router pages and API routes
- `/src/components` - Reusable UI components
- `/src/lib` - Utility functions and shared logic
- `/src/types` - TypeScript type definitions
- `/prisma` - Database schema and migrations

### Key Patterns
1. **Server Components by default** - Only use 'use client' when necessary
2. **API Routes** - Use route handlers in `/src/app/api`
3. **Database** - Always use Prisma client from `/src/lib/db`

## Coding Conventions

### TypeScript
- Always define interfaces for props
- Use `type` for unions, `interface` for objects
- Avoid `any` - use `unknown` if type is truly unknown

### Components
- One component per file
- Name file same as component (PascalCase)
- Export component as default

### Styling
- Use Tailwind CSS exclusively
- No CSS modules or inline styles
- Extract repeated patterns to components, not utilities

## DO NOT
- Modify files in `/prisma/migrations` - these are auto-generated
- Store secrets in code - use environment variables
- Use `console.log` in production code - use the logger utility
- Create new API routes without authentication middleware

## Common Tasks

### Adding a new page
1. Create folder in `/src/app/[page-name]`
2. Add `page.tsx` with the page component
3. Add `loading.tsx` for loading state
4. Update navigation if needed

### Adding a new API endpoint
1. Create folder in `/src/app/api/[endpoint]`
2. Add `route.ts` with handler
3. Wrap with `withAuth` middleware
4. Add to API documentation

### Database changes
1. Modify `/prisma/schema.prisma`
2. Run `npx prisma migrate dev --name descriptive-name`
3. Update types if needed

Tips for Effective AGENTS.md

1. Be specific: Instead of "use good practices", say exactly what you want
2. Include examples: Show code snippets of correct patterns
3. Explain why: Claude makes better decisions with context
4. Keep it updated: Outdated instructions cause confusion
5. List anti-patterns: Explicitly say what NOT to do

.cursorrules and Other IDE Files

If you use Cursor, you can also create a .cursorrules file with additional instructions specific to Cursor's AI features.

your-project/
├── .cursorrules    # Cursor-specific
├── AGENTS.md       # Claude Code specific
├── .claude/
│   └── settings.json
└── ...

Example .cursorrules

You are an expert in Next.js 15, TypeScript, and Tailwind CSS.

Key principles:
- Write concise, technical responses
- Use functional programming patterns
- Prefer composition over inheritance
- Use descriptive variable names

Next.js patterns:
- Use App Router conventions
- Implement proper loading and error states
- Use server components by default

Command-Line Flags

Override settings for a single session:

bash
Copy
# Use a different model
claude --model claude-opus-4-5-20251101

# Auto-approve all actions (DANGEROUS - see lesson 3)
claude --dangerously-skip-permissions

# Increase response length
claude --max-tokens 8192

# Specify a working directory
claude --cwd /path/to/project

# Non-interactive mode with a specific prompt
claude -p "Fix the linting errors in src/components"

Common Flag Combinations

Quick exploration session:

bash
Copy
claude --model claude-haiku-3-5-20241022

Detailed code review:

bash
Copy
claude --model claude-opus-4-5-20251101 --max-tokens 8192

Automated CI task:

bash
Copy
claude --dangerously-skip-permissions -p "Run tests and fix any failures"

Environment Variables

Some settings can be controlled via environment variables:

Configuration Best Practices

1. Commit Project Settings

Add .claude/settings.json and AGENTS.md to version control so your team shares the same configuration.

2. Keep Secrets Out

Never put API keys or secrets in settings files. Use:

• Environment variables
• .env files (with .gitignore)
• Secret management tools

3. Start Restrictive

Begin with conservative auto-approve settings and relax them as you build trust:

json
Copy
{
  "autoApprove": {
    "read": true,
    "write": false,
    "execute": false
  }
}

4. Document Your Setup

Add a section to your README explaining:

• What Claude Code configuration exists
• How to set up API keys
• Any project-specific instructions

Common Issues

---

Next: Learn about Claude Code's hooks system for automation.