Verified against the official docs on 30 August 2026

Everything Claude Code loads,
and what wins when they disagree.

Claude Code's configuration is not one system. It is seven independent subsystems that happen to share a .claude/ directory, with different file formats, different discovery rules, and sometimes opposite precedence rules. This is the map.

Start with the mental modelJump to the cheat sheet
~/work/platform — claude
$ claude
# session start, in order
settings   managed → cli → local → project → user   override
agents     managed → cli → project → user → plugin  shadow
skills     enterprise → personal → project      shadow, reversed
memory     /etc → ~ → /work → ./ → ./local        additive, nobody wins
rules      unscoped now, paths: globs on demand    additive
hooks      every matching hook, every source      all of them run

# when something looks wrong
> /context
The distinction that resolves most questions

Prose, config, and code

Every mechanism falls into one of three families, and the family decides what happens when two pieces of configuration disagree.

Proseis a request

CLAUDE.md · rules · skills · output styles

Text concatenated into the prompt. Conflicts resolved by the model, non-deterministically.

Configis a rule

settings.json · agent frontmatter · permissions

Structured values. Conflicts resolved by a defined precedence order.

Codeis enforcement

hooks

Shell commands that run and can block. Not a conflict at all: it fires or it does not.

If something absolutely must happen every time, it belongs in a hook, not in CLAUDE.md.

Cost profile

Not every layer costs the same

CLAUDE.md is the most expensive place to put anything, because it is paid for on every single turn whether relevant or not. This table is the reason "put everything in CLAUDE.md" stops working at scale.

See the full breakdown →
  • CLAUDE.mdFull text, every turn
  • Rule without paths:Full text, every turn
  • Rule with paths:Zero until a matching file is touched
  • SkillOne description line
  • Skill, model-invocation offZero
  • SubagentOne description line; work runs elsewhere
  • HookZero, it runs outside the model
Contents

Sixteen sections

Read it in order the first time. After that, the two pages you will come back to areconflicting rules andrecipes.

Foundations

01

The mental model

Seven subsystems sharing one directory. Prose is a request, config is a rule, hooks are enforcement.

02

What loads at session start

The exact boot sequence, what loads lazily, and the three commands that show you the truth.

03

Memory files

The CLAUDE.md family: four scopes, discovery order, imports, size discipline, and exclusion.

04

Rules

Path-scoped instructions that cost nothing until Claude touches a matching file.

05

Settings and env

The one subsystem with real precedence, and the env block that wires up your toolchain.

Extending

06

Skills

Progressive disclosure, dynamic context injection, and why a 400-line reference can be free.

07

Agents, subagents and forks

Separate context windows. One definition, three placements, and when each one earns its keep.

08

Plugins

The box that holds skills, agents, hooks and MCP servers, with collision-proof namespacing.

09

Output styles

Changing how Claude communicates, and the one frontmatter field that silently breaks it.

10

Hooks

The enforcement layer. Shell commands that fire outside the model and can block a tool call.

Resolving

11

Conflicting rules

How every subsystem resolves disagreements, including the two that resolve in opposite directions.

12

Choosing the right mechanism

A decision tree and a matrix for placing any instruction in the right layer the first time.

In practice

13

Worked example: a polyglot repository

A complete configuration for a monorepo with Java, Go, Python and TypeScript.

14

Recipes

Twelve worked setups: incident triage, migration guards, review agents, monorepo scoping and more.

15

Gotchas and anti-patterns

The failure modes that cost the most time, grouped by the subsystem that causes them.

16

Cheat sheet

File map, commands, flags, and the five things worth committing to memory.

If you read nothing else

The five things worth memorising

  1. 01

    Memory files are additive, not hierarchical. Contradictions are resolved by the model, unpredictably. Remove them rather than ranking them.

    Read why →
  2. 02

    Skills: personal beats project. Agents: project beats personal. Opposite directions, no mnemonic.

    Read why →
  3. 03

    CLAUDE.md is the most expensive place to put anything. Path-scoped rules and skills are nearly free until used.

    Read why →
  4. 04

    Prose is a request; config is a rule; hooks are enforcement. Match the mechanism to how badly you need it to hold.

    Read why →
  5. 05

    /context before theorising. Most "Claude ignored my instruction" reports are "the instruction was never loaded".

    Read why →