Skip to main content

Settings Hierarchy

What Are Settings?​

Claude Code has a settings system that lets you customize how it behaves. These settings control things like:

  • Permission modes (whether Claude asks before edits)
  • Output preferences (how Claude formats responses)
  • Project-specific defaults (which tools Claude prioritizes)
  • Team standards (shared rules for collaborative work)

Instead of having one global settings file, Claude Code uses a three-level hierarchy. This design lets you have personal preferences, project standards, and temporary overrides all at the same time.

💬 AI Colearning Prompt​

"Explain why applications use hierarchical configuration systems instead of a single global settings file. What problems does hierarchy solve?"

The Three Settings Levels​

Claude Code settings exist at three levels, from general to specific:

Level 1: User Settings (Most General)​

Location: ~/.claude/settings.json

Scope: Applies to all your Claude Code projects on your machine

Applies to: Every project you work on, across your entire system

When to use this level:

  • Your personal preferences (always use dark mode, prefer verbose output)
  • Your coding style (consistent formatting choices)
  • Your workflow defaults (always prefer plan mode for safety)

Example content:

{
  "model": "claude-sonnet-4-5-20250929",
  "outputStyle": "Concise",
  "includeCoAuthoredBy": true
}

Level 2: Project Settings (Middle)​

Location: .claude/settings.json (inside your project directory)

Scope: Applies to just this project

Applies to: Only when you're working in this specific project

When to use this level:

  • Team standards (your team agrees on permission settings)
  • Project-specific customizations (this project uses a different framework)
  • Temporary standards (during alpha testing, use stricter permissions)

Example content:

{
  "permissions": {
    "defaultMode": "acceptEdits",
    "allow": ["Bash(npm run test:*)"],
    "deny": ["Read(./.env)"]
  },
  "env": {
    "PROJECT_ENV": "development"
  }
}

Level 3: Local Settings (Most Specific)​

Location: .claude/settings.local.json (inside your project directory)

Scope: Applies to this project only, on your machine only

Applies to: Just your local work in this project (not shared with team)

When to use this level:

  • Temporary overrides (you need different settings just for today)
  • Personal experiments (testing a new workflow locally)
  • Machine-specific settings (your laptop needs different settings than your desktop)

Example content:

{
  "outputStyle": "Verbose",
  "sandbox": {
    "enabled": true
  }
}

🎓 Expert Insight​

In AI-native development, settings hierarchy mirrors real-world team dynamics. Your personal style (user level) is your default. The team's standards (project level) override your defaults when working together. Your local experiments (local level) override both without affecting the team. This is how distributed teams collaborate without constant conflicts.

Precedence: Which Settings Win?​

When the same setting exists at multiple levels, Claude Code follows this precedence order (most specific wins):

Local > Project > User

This means:

  • Local settings override both project and user settings
  • Project settings override user settings
  • User settings are the fallback when nothing more specific exists

Visual Hierarchy​

┌─────────────────────────────────┐
│   LOCAL SETTINGS                │
│   .claude/settings.local.json    │  ← Most Specific (Highest Priority)
│   (just your machine, temporary) │
└─────────────────┬───────────────┘
                  ↑ Overrides
┌─────────────────────────────────┐
│   PROJECT SETTINGS              │
│   .claude/settings.json          │  ← Team/Project Level
│   (shared with team)             │
└─────────────────┬───────────────┘
                  ↑ Overrides
┌─────────────────────────────────┐
│   USER SETTINGS                 │
│   ~/.claude/settings.json        │  ← Most General (Fallback)
│   (all projects on this machine) │
└─────────────────────────────────┘

Example: Settings Precedence in Action​

Let's say you have:

User level (~/.claude/settings.json):

{
  "outputStyle": "Concise"
}

Project level (.claude/settings.json in your project):

{
  "outputStyle": "Explanatory"
}

Local level (.claude/settings.local.json in your project):

{
  // Empty or not set
}

Result: Claude Code uses outputStyle: "Explanatory" (from project level, since it overrides user level)

What If Local Level Is Set?​

Now you add a temporary local override:

Local level (.claude/settings.local.json):

{
  "outputStyle": "Verbose"
}

New Result: Claude Code uses outputStyle: "Verbose" (from local level, which overrides both project and user)

Why this matters: You can temporarily change your workflow for this one session without affecting your project's standards or your personal preferences. Tomorrow, when you delete the local settings file, you're back to "Explanatory" (project level).

🤝 Practice Exercise​

Ask your AI: "I have outputStyle set to 'Concise' at user level and 'Explanatory' at project level. I'm working in this project. Which style is active? If I create a .claude/settings.local.json file with outputStyle: 'Verbose', what happens?"

Expected Outcome: AI explains that project level is active (Explanatory), and creating a local override would switch to Verbose—helping you understand how to temporarily override settings without changing team standards.

Why Settings Hierarchy Matters​

For Team Collaboration​

Your team might decide: "All projects should deny access to .env files for security." They set permissions.deny: ["Read(./.env)"] at the project level (.claude/settings.json). Everyone on the team gets this standard automatically.

But you, personally, have different permission settings at your user level. Project settings win, so when working on this project, everyone (including you) uses the team's security standards. When you work on personal projects, your user-level preferences kick in again.

For Personal Customization​

You want special settings just for this project—maybe more verbose output or a specific framework preference. You set .claude/settings.json (project level) without touching user settings. Your other projects still use your personal defaults (user level).

For Temporary Experiments​

You want to test a new workflow today without affecting the team. You create .claude/settings.local.json (local level). Your changes stay on your machine, invisible to the team. Delete the file tomorrow, and everything reverts to project/user standards.

The .claude/ Directory: Don't Delete It​

You might see a .claude/ directory in your project and wonder: "Is this important? Can I delete it?"

Short answer: Don't delete it.

What it contains:

  • settings.json — Project-level settings
  • settings.local.json — Your local, temporary overrides
  • Other configuration files Claude Code needs

The .claude/ directory is how Claude Code stores project customization. Deleting it would reset all your project settings to defaults.

What you should do: Treat .claude/settings.json like your .gitignore or package.json—it's part of your project configuration. Include it in version control (share with team). But .claude/settings.local.json should probably be in your .gitignore (keep it personal).

💬 AI Colearning Prompt​

"Explain the difference between .claude/settings.json and .claude/settings.local.json. Which one should be in .gitignore? Why?"

Not Configuring Yet—This Is Part 5 Content​

This lesson teaches you that settings exist and how the hierarchy works. You don't need to configure them yet. Basic Claude Code usage works perfectly fine with defaults.

Detailed settings configuration (what specific settings do, how to change them, team policies) is Part 5 content (Spec-Driven Development, team workflows). For now, just know:

✅ Settings exist at three levels ✅ Precedence is: local > project > user ✅ This hierarchy enables team collaboration + personal customization

That's enough to understand when you encounter .claude/settings.json references in documentation.

Try With AI​

Now let's explore settings hierarchy with Claude Code.

Setup: Open Claude Code in your terminal and work through these prompts to understand how settings levels work together.

Prompt 1: Explain Settings Hierarchy​

In Claude Code, settings exist at three levels: user (~/.claude/settings.json),
project (.claude/settings.json), and local (.claude/settings.local.json).

Explain what each level is for and why having three levels is better than one global settings file.

Expected Outcome: AI explains that hierarchy enables team standards without overriding personal preferences, and allows temporary overrides without affecting shared configuration.

Prompt 2: Show Your Settings Files​

Show me what settings files exist on my machine:
- Do I have ~/.claude/settings.json? (user level)
- Do I have .claude/settings.json in my current project? (project level)
- Do I have .claude/settings.local.json? (local level)
Which ones exist? Where are they located?

Expected Outcome: AI guides you to check which settings files exist and explains where to find them (home directory vs project root).

Prompt 3: Precedence Scenario​

Let's say:
- User level has: outputStyle = "Concise"
- Project level has: outputStyle = "Explanatory"
- Local level is: not set

Which outputStyle is active? Why?
Then: what happens if I add outputStyle = "Verbose" to local level?

Expected Outcome: AI correctly explains that project level wins initially (Explanatory), then local level overrides when you add it (Verbose)—demonstrating understanding of precedence order.

Prompt 4 (Stretch): Plan for Part 5​

When I learn team workflows in Part 5, what settings would I modify?
- User level (my personal preferences)?
- Project level (team standards)?
- Local level (temporary experiments)?

Explain when each level is the right choice for different scenarios.

Expected Outcome: AI explains use cases—user level for personal defaults, project level for team standards, local level for temporary changes. You'll understand why hierarchy matters for team collaboration.