ktg-plugin-marketplace/plugins/config-audit/skills/config-hierarchy/SKILL.md

name	description
config-hierarchy	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:

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

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

@Imports

CLAUDE.md files can import other files:

# 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)