Every Claude Code setting has an address

Claude Code reads its configuration from a handful of files, and each file answers two questions at once: what kind of thing is this, and who should get it. Get both right and the file path follows. Get either wrong and you end up with a formatting rule nobody else receives, a secret committed to the repository, or a “never do this” that Claude is free to ignore.

Question one: what kind of thing is it?

Read the requirement and listen for its verb. “Prefer” and “follow our conventions” are advice. “When I ask for” is a procedure. “Every time”, “always” and “must never” are guarantees, and a guarantee cannot live in a file that Claude merely reads.

AdviceCLAUDE.md

Project conventions, build commands, architecture notes. Claude loads it at the start of a session and generally follows it, but it is context, not enforcement. The model decides.

Advice for some files.claude/rules/

Markdown files with a paths: list of glob patterns in their frontmatter. A rule for db/migrations/** loads when Claude reads a matching file, so it costs no context the rest of the time. A rule with no paths loads unconditionally, like CLAUDE.md.

A procedureSkills

A repeatable task you, or Claude, can call by name. .claude/skills/deploy/SKILL.md creates /deploy. The older .claude/commands/deploy.md creates the same /deploy. Command files still work, with the same frontmatter as Skills except name and paths, but new work should be a skill. If both exist under one name, the skill runs.

A guaranteeHooks

Shell commands that run at fixed points in the session, defined in a settings file. A PostToolUse hook on file edits runs the formatter whether or not Claude remembered to. A PreToolUse hook that exits with code 2 blocks the tool call outright.

Hooks are deterministic. That is the whole difference from CLAUDE.md.

A boundaryPermissions

allow, ask and deny rules in a settings file, such as Read(./.env) under deny. They govern what Claude may do at all, not what it should prefer to do.

A capabilityMCP servers

Tools and data from outside Claude Code: an issue tracker, a database, an internal API. Configured per scope, with its own file layout, which is where most of the traps are.

The pairing to hold on to is CLAUDE.md against hooks and permissions. “Never commit to main” written in CLAUDE.md is a request. The same sentence as a deny rule or a PreToolUse hook is a fact about the system. When a requirement says it must hold “regardless of” what the model does, only the second one answers it.

Question two: who should get it?

There are three audiences, and every mechanism above has a file for most of them.

• Project — everyone who clones the repository. These files are committed.
• Local — you, in this project only. Not committed.
• User — you, in every project on this machine. Lives under your home directory.

Above all three sits managed configuration, set by an organisation and deployed to system paths. You rarely write it, but it outranks everything you do write.

The scope map

What it is	ProjectCommitted · the whole team	LocalNot committed · you, this project	UserHome directory · you, every project
Instructions	./CLAUDE.md./.claude/CLAUDE.md	./CLAUDE.local.md	~/.claude/CLAUDE.md
Path-scoped rules	.claude/rules/*.md	—	~/.claude/rules/*.md
Skills and commands	.claude/skills/<name>/SKILL.md.claude/commands/<name>.md	—	~/.claude/skills/<name>/SKILL.md~/.claude/commands/<name>.md
Settings, hooks, permissions	.claude/settings.json	.claude/settings.local.jsonGit-ignored by default.	~/.claude/settings.json
MCP servers	.mcp.jsonAt the repository root. --scope project	~/.claude.jsonUnder this project’s entry, in your home directory, not the repo. --scope local, the default.	~/.claude.jsonTop-level mcpServers. --scope user

The shaded cell is the one to memorise. For every other mechanism, “local” means a file in the project folder. For MCP servers it means an entry in ~/.claude.json, and it is what claude mcp add gives you if you name no scope at all.

Read the map as a lookup. “A formatter hook for the team” is row four, column one: .claude/settings.json. “An MCP server I am trying out” is row five, and either local or user depending on whether the experiment is tied to this project. Anything described as shared team tooling belongs in the project column.

When the same thing is set twice

Scopes overlap, so each mechanism needs a tie-break. They do not all use the same one, and the differences are worth knowing precisely.

Keeping secrets out of shared config

A project-scoped MCP server lives in .mcp.json, which is committed, which means a token pasted into it is a token pasted into the repository. The file supports environment variable expansion instead: ${VAR}, or ${VAR:-default} with a fallback, in command, args, env, url and headers.

// .mcp.json: committed, shared, no secrets in it
{
  "mcpServers": {
    "tracker": {
      "type": "http",
      "url": "${TRACKER_URL:-https://tracker.example.com}/mcp",
      "headers": { "Authorization": "Bearer ${TRACKER_TOKEN}" }
    }
  }
}

Everyone on the team gets the same server; each of them supplies their own token. That is the shape of the right answer whenever a requirement combines “shared” with “credentials”.

Three ways to hand Claude context

There are three ways to give Claude context, and the choice turns on reusability, specificity, and whether the next session will need it too.

• Type it into the message when the fact matters for this request and nowhere else. It is gone when the conversation is.
• Use @path/to/file in the prompt when a specific file is what Claude needs for this task. The file’s full content goes into the conversation straight away, without waiting for Claude to decide to read it. An @ directory gives a file listing, not contents, and @server:resource pulls in an MCP resource. None of it carries into the next session.
• Put it in CLAUDE.md when every session will need it. CLAUDE.md can itself import other files with the same @path syntax, so a long conventions document can stay in docs/ and still load at launch.

The trap is the look-alike syntax. @docs/api.md typed in a prompt is a one-off inclusion. The same line inside CLAUDE.md is a standing import that every future session pays for in context.

One side effect is easy to miss: an @ file reference also adds the CLAUDE.md files from that file’s directory and its parent directories. Point at @packages/billing/invoice.ts and the billing package’s own CLAUDE.md comes along with it.

What context: fork is for

By default a skill runs inside your conversation: it sees what you have discussed and whatever it reads stays in your context afterwards. Adding context: fork to a skill’s frontmatter runs it in an isolated subagent instead. The skill’s content becomes that subagent’s prompt, it does not inherit the conversation history, and an agent: key can choose which subagent type runs it, such as Explore or Plan.

Reach for it when a skill does a lot of self-contained reading, or when it should not be swayed by the session: a code review that ought to judge the diff rather than the argument you just made for it. Leave it off when the skill genuinely needs what the conversation already knows.

Try the lookup

Decide the mechanism and the file before opening each one.

The whole method

1. Is it advice, a procedure, a guarantee, a boundary or a capability? That picks the mechanism.
2. Is it for the team, for you here, or for you everywhere? That picks the file.
3. If it says “always” or “never”, check you did not file it as advice.

Checked against the Claude Code documentation on memory, settings, skills, hooks, MCP and file references, September 2026.

More on this

• Your MCP server is a prompt — Tool descriptions, resource lists and error messages all end up in front of the model. When Claude picks the wrong tool, the fix is usually in text the server wrote.
• Your practice percentage is measuring the wrong thing — Any tool that re-asks the questions you got wrong poisons its own accuracy statistic. Here is how far off it gets, measured.
• A 720 is not 72% — Scaled scores and weighted blueprints both break the arithmetic people do in their heads.