---
name: config-hierarchy
description: |
  This skill should be used when the user asks about Claude Code configuration files,
  CLAUDE.md hierarchy, settings.json structure, MCP server configuration, or rules directory patterns.
  Triggers on: "CLAUDE.md hierarchy", "config file locations", "settings.json", ".mcp.json",
  "rules directory", "configuration inheritance", "where does Claude read config from".
---

# Claude Code Configuration Hierarchy

Comprehensive reference for understanding Claude Code's configuration system.

## Overview

Claude Code loads configuration from multiple sources, with a defined precedence order. Understanding this hierarchy is crucial for effective configuration management.

## Configuration Sources (By Priority)

### 1. CLAUDE.md Hierarchy

From highest to lowest priority:

| Level | Location | Shared? | Purpose |
|-------|----------|---------|---------|
| **Managed** | System-level paths | All users | Enterprise/organization policies |
| **Project local** | `./CLAUDE.local.md` | No (gitignored) | Machine-specific project overrides |
| **Project shared** | `./CLAUDE.md` or `./.claude/CLAUDE.md` | Yes (git) | Team-shared project instructions |
| **Project rules** | `./.claude/rules/*.md` | Yes (git) | Modular, path-scoped rules |
| **User global** | `~/.claude/CLAUDE.md` | No | Personal defaults |

### 2. Settings.json Hierarchy

| Level | Location | Purpose |
|-------|----------|---------|
| **Managed** | System `managed-settings.json` | Enterprise policies (highest) |
| **CLI args** | Command line | Session-only overrides |
| **Local** | `.claude/settings.local.json` | Machine-specific project |
| **Project** | `.claude/settings.json` | Team-shared project |
| **User** | `~/.claude/settings.json` | Personal defaults (lowest) |

### 3. Other Configuration Files

| File | Location | Purpose |
|------|----------|---------|
| `.mcp.json` | Project root | MCP server definitions for project |
| `~/.claude.json` | Home | OAuth tokens, global MCP servers, state |
| `.claudeignore` | Project | File/directory exclusions |
| `~/.claude/agents/` | User | Custom subagent definitions |

## Managed Configuration Paths

For enterprise/organization-wide settings:

| Platform | Path |
|----------|------|
| macOS | `/Library/Application Support/ClaudeCode/CLAUDE.md` |
| Linux | `/etc/claude-code/CLAUDE.md` |
| Windows | `C:\Program Files\ClaudeCode\CLAUDE.md` |

## Key Concepts

### Inheritance

- Files are loaded from current directory upward to root
- Subtree files loaded on-demand when entering directories
- Lower priority files provide defaults
- Higher priority files override specific settings

### Path-Scoped Rules

In `.claude/rules/`, files can be scoped to specific paths:

```yaml
---
globs: ["src/**/*.ts", "src/**/*.tsx"]
---

# TypeScript Rules
These rules apply only to TypeScript files in src/
```

### @Imports

CLAUDE.md files can import other files:

```markdown
# Project CLAUDE.md

@./docs/api.md
@./CONTRIBUTING.md
```

## Further Reading

See the reference files for detailed schemas:
- `references/claude-md-structure.md` - CLAUDE.md sections
- `references/settings-json-schema.md` - settings.json keys
- `references/mcp-json-patterns.md` - MCP configuration
- `references/rules-directory.md` - Rules pattern
- `references/quality-criteria.md` - Quick reference (detailed rubric in `agents/analyzer-agent.md`)