101 lines
3.3 KiB
Markdown
101 lines
3.3 KiB
Markdown
---
|
|
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`)
|