Claude Code configuration, top down.

Before any detail, the map. Read it top to bottom: where configuration comes from, what it turns into when a session starts, and what happens on every turn. Every later section zooms into one box.

How to study this page

1. Redraw the diagram above from memory. Until you can, do not go on; everything else hangs off it.
2. Each level has the same rhythm: big idea, a Java anchor, the facts, exam traps, a self-check. Answer the self-check out loud before opening it.
3. Finish with the fifteen scenario questions at the end and only then open the answer key.

The map shows what exists. This workbench shows the order in which a company creates it, who does each step, and exactly where every file lives. Alpine Bank’s payments-portal team is fictional; the files are real, working examples you can copy. Walk the ten steps with the buttons, click any file in the tree to read it, then place the files yourself in the exercise below.

Two more words complete the vocabulary. A plugin bundles skills, agents, hooks and MCP servers into one installable unit. An MCP server gives Claude external tools and data.

The eight building blocks

Which piece for which job

Seven myths, fixed

The file map

Who wins a conflict

Enforcing policy for an organization

• Three delivery channels. A managed-settings.json file in the system folder (plus managed-settings.d/*.json drop-ins, merged alphabetically); OS policy via MDM (macOS plist domain com.anthropic.claudecode, Windows registry HKLM\SOFTWARE\Policies\ClaudeCode); or server-managed settings from the claude.ai admin console.
• System folders. macOS /Library/Application Support/ClaudeCode/; Linux and WSL /etc/claude-code/; Windows C:\Program Files\ClaudeCode\.
• Useful locks. permissions.deny rules, allowManagedHooksOnly, allowManagedPermissionRulesOnly, and strictPluginOnlyCustomization, which blocks skills, agents, hooks and MCP servers from user and project sources.
• Also managed. managed-mcp.json for MCP servers, a managed CLAUDE.md for behavioural guidance, and .claude/agents/ in the managed folder for org-wide subagents.

Startup order, as a table

The project-context layer is sent as a user message after the system prompt, not inside it.

During the conversation

• Full SKILL.md bodies and plan mode are appended as messages, so the cached prefix stays intact.
• Path-scoped rules and nested CLAUDE.md files load when Claude reads a matching file.
• MCP tool schemas load when Claude needs a specific tool.
• Never loaded until needed: user-only skills (until you type /name), a skill's supporting files, auto-memory topic files, and CLAUDE.md in --add-dir folders.

After /compact

A subagent's own stack

Its own system prompt (which replaces Claude Code's; only environment details are added), plus CLAUDE.md files (not for the built-in Explore and Plan agents), plus preloaded skills, plus a git status snapshot, plus the task Claude wrote for it. Not your conversation, and not your main auto memory.

All 33 hook events

Setup fires for claude --init-only (or --init / --maintenance with -p). It has nothing to do with the /init command.

Anatomy of a hook

Event, optional matcher, handler:

"hooks": {
  "PreToolUse": [                                  // ← event
    {
      "matcher": "Bash",                           // ← which tool; a regex like "Edit|Write" or "mcp__github__.*"
      "hooks": [
        { "type": "command",                       // ← handler: command | http | mcp_tool | prompt | agent
          "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-dangerous.sh",
          "args": [], "timeout": 10 }
      ]
    }
  ]
}

What the exit code means

JSON output (exit 0 plus JSON on stdout):

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",              // allow | deny | ask
    "permissionDecisionReason": "Recursive delete of ~ ..."
  }
}

Other fields: updatedInput rewrites the tool call, additionalContext adds text Claude sees, continue: false stops everything, systemMessage shows a message to the user.

What it decides

How it works

• Reads the event JSON from stdin with jq, then lowercases and normalises the command.
• Splits compound commands (;, &&, |, $(…), backticks) and strips wrappers (sudo, env, bash -c, xargs, …), so each simple command is checked on its own.
• Prints a JSON permissionDecision (deny beats ask), or nothing for "no opinion".
• Fails closed on its own errors: missing jq or unreadable input → exit 2.
• Fails open on setup errors: wrong path or missing chmod +x → Claude Code treats it as a non-blocking error.

The settings that wire it in

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "deny": ["Bash(sudo *)"]
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-dangerous.sh",
            "args": [],
            "timeout": 10
          }
        ]
      }
    ]
  }
}

The sudo deny rule is the hard floor for a fixed pattern. The hook adds judgement a fixed rule cannot express: rm -rf build/ is fine, rm -rf ~ is not.

Install and test

cd ~/pro
mkdir -p .claude/hooks
cp ~/Downloads/block-dangerous.sh .claude/hooks/
chmod +x .claude/hooks/block-dangerous.sh
echo '{"tool_input":{"command":"rm -rf ~"}}' | .claude/hooks/block-dangerous.sh   # prints a deny decision
echo '{"tool_input":{"command":"npm test"}}'  | .claude/hooks/block-dangerous.sh   # prints nothing

Then run /hooks in Claude Code: the hook should appear under PreToolUse, labelled Project Settings.

#!/usr/bin/env bash
# .claude/hooks/block-dangerous.sh
#
# PreToolUse hook for Claude Code's Bash tool.
# Reads the hook event JSON on stdin and answers with one of:
#   deny        -> the command is blocked and Claude is told why
#   ask         -> you get a permission prompt, even if a rule would allow it
#   (no output) -> no opinion; your normal permission rules decide
#
# Pattern matching is best effort: a seatbelt against accidents,
# not a security boundary. Requires jq.
set -uo pipefail

# Fail closed: without jq the command can't be inspected, so block it.
if ! command -v jq >/dev/null 2>&1; then
  echo "block-dangerous.sh: jq is not installed (brew install jq / apt install jq). Bash is blocked until it is." >&2
  exit 2
fi
cmd=$(jq -r '.tool_input.command // empty') || {
  echo "block-dangerous.sh: could not parse the hook input." >&2
  exit 2
}
[ -z "$cmd" ] && exit 0

# Normalise: join line continuations, turn newlines into ';',
# lowercase everything and squeeze whitespace to single spaces.
cmd=${cmd//$'\\\n'/ }
lc=$(printf '%s' "$cmd" | tr '\n' ';' | tr '[:upper:]' '[:lower:]' | tr -s '[:space:]' ' ')

verdict="" reason=""
flag() {   # flag deny|ask "reason"   (deny beats ask; first reason wins)
  case "$verdict:$1" in
    deny:*|ask:ask) ;;
    *) verdict=$1 reason=$2 ;;
  esac
}
check() {  # check deny|ask 'regex' "reason"   (tested against the current segment $s)
  if [[ $s =~ $2 ]]; then flag "$1" "$3"; fi
}

# ---- Checks on the whole command (these span pipes) -------------------------
re_pipe_shell='(curl|wget).*\| *(sudo +)?(ba|z|da|k)?sh( |$)|(ba|z|da|k)?sh <\( *(curl|wget)'
re_forkbomb=':\(\) *\{ *:\|:'
[[ $lc =~ $re_pipe_shell ]] && flag deny "Piping a downloaded script into a shell. Download it first, show the user what it does, then run it."
[[ $lc =~ $re_forkbomb ]] && flag deny "Fork bomb."

# ---- Checks per simple command ----------------------------------------------
# Split on ; & | ( ) and backticks, so "cd x && rm -rf ~" and "$(rm -rf /)"
# are each checked on their own.
segments=$(printf '%s\n' "$lc" | sed 's/[;&|()`]/\n/g')

# Wrappers and shell keywords to peel off the front: VAR=x, sudo, env, xargs -0, bash -c, then ...
re_prefix='^([a-z_][a-z0-9_]*=[^ ]*|sudo|doas|env|command|builtin|exec|eval|nohup|nice|time|xargs|if|then|else|elif|do|while|until|!|\{|(ba|z|da|k)?sh -c|-[a-z0-9-]+) '
re_rm='^([^ ]*/)?rm '
re_recursive=' (-[a-z]*r[a-z]*|--recursive)( |$)'
re_target=' (/|~|\$home|\$\{home\}|\.|\.\.|\*|/(applications|bin|boot|dev|etc|home|lib|library|opt|root|sbin|system|users|usr|var))(/?\*|/)?( |$)'

while IFS= read -r s; do
  s=${s//\"/}; s=${s//\'/}        # rm -rf "/" is the same as rm -rf /
  s=${s# }
  while [[ $s =~ $re_prefix ]]; do s=${s#"${BASH_REMATCH[0]}"}; done
  [ -z "$s" ] && continue

  # DENY: irreversible, never OK from an agent
  if [[ $s =~ $re_rm && $s =~ $re_recursive && $s =~ $re_target ]]; then
    flag deny "Recursive delete of /, ~, \$HOME, ., .., * or a system folder. Delete specific paths instead, e.g. rm -rf build/."
  fi
  check deny '^find (/|~|\$home)( |$).*-delete'             "find -delete across / or the home folder."
  check deny '^mkfs'                                          "Formatting a filesystem."
  check deny '^dd .*of=/dev/'                                 "Writing raw bytes to a device."
  check deny '^diskutil (erase|zero|secureerase|partition)'   "Erasing or repartitioning a disk."
  check deny '> ?/dev/(sd|hd|vd|xvd|nvme|disk)'               "Redirecting output onto a raw disk."

  # ASK: sometimes legitimate, so a human decides
  check ask '^git push( .*)? (-f|--force[a-z-]*|\+[^ ]+)( |=|$)'  "Force push rewrites shared history."
  check ask '^git reset( .*)? --hard( |$)'                        "git reset --hard throws away uncommitted work."
  check ask '^git clean( .*)? -[a-z]*f'                           "git clean -f deletes untracked files."
  check ask '^terraform (destroy|apply( .*)? -auto-approve)'      "Changes or destroys infrastructure without review."
  check ask '^kubectl delete '                                    "Deletes Kubernetes resources."
  check ask '^chmod (-r|--recursive) ([^ ]+ )*(777|a\+rwx)'       "Makes files world-writable, recursively."
  check ask '(^| )(drop (table|database|schema)|truncate table)( |$)' "Destructive SQL."
done <<< "$segments"

# ---- Answer ------------------------------------------------------------------
[ -z "$verdict" ] && exit 0      # silent = no opinion
[ "$verdict" = deny ] && reason="$reason If it is truly needed, ask the user to run it themselves."
jq -n --arg d "$verdict" --arg r "block-dangerous hook: $reason" '{
  hookSpecificOutput: {
    hookEventName: "PreToolUse",
    permissionDecision: $d,
    permissionDecisionReason: $r
  }
}'

Example frontmatter

---
name: review-checklist
description: Checklist for reviewing code changes - correctness, security, tests and maintainability. Use when reviewing a diff, a pull request or a commit.
---
# Code review checklist
Work through every section for each changed file. Report only real findings.
...

---
name: review-checklist
description: Checklist for reviewing code changes - correctness, security, tests and maintainability. Use when reviewing a diff, a pull request or a commit.
---
# Code review checklist

Work through every section for each changed file. Report only real findings, not ticked boxes.

## Correctness
- Edge cases: empty, null, zero, very large, unicode, time zones
- Errors handled at the right level; nothing swallowed silently
- Concurrency: shared state, thread safety, retries that are safe to repeat
- Resources closed on every path (connections, streams, files)

## Security
- Input validated at every trust boundary
- No SQL, shell commands or file paths built from untrusted input
- Authorization checked on every endpoint and service call, not only authentication
- No secrets, tokens or personal data in code, logs or error messages
- No untrusted data into deserialization, reflection or templates

## Tests
- New behaviour is tested, including the failure path
- Tests assert outcomes, not implementation details
- No test depends on ordering, the clock or the network without a stub

## Maintainability
- Names say what things are; no dead or commented-out code
- Each function does one thing; duplication extracted
- Public API changes are backward compatible, or flagged as breaking

How it is invoked

• Automatically, when your request matches its description. "Use proactively…" makes this eager.
• Explicitly: @"code-reviewer (agent)" review my changes.
• As the whole session: claude --agent code-reviewer, which also sends its initialPrompt.
• Subagents can launch their own subagents, up to three levels deep by default. In interactive sessions they run in the background by default.
• Where: .claude/agents/ (project), ~/.claude/agents/ (user), a plugin's agents/, managed, the --agents flag. Edits hot-reload within seconds; restart only after the first file in a brand-new agents folder.

Example: .claude/agents/code-reviewer.md

---
name: code-reviewer
description: Reviews code changes for bugs, security issues and maintainability problems. Use proactively after writing or modifying code, and before every commit.
tools: Read, Grep, Glob, Bash
model: sonnet
effort: high
maxTurns: 25
skills:
  - review-checklist
memory: project
color: purple
initialPrompt: Review the current changes and give your verdict.
---
You are a senior code reviewer. You review code; you never modify it.

When invoked:
1. Run `git status` and `git diff HEAD` to see uncommitted changes. If there are none,
   review the branch against the default branch instead (e.g. `git diff main...HEAD`).
   If the task names specific files, focus on those.
2. Read each changed file and enough surrounding code to understand it.
3. Check your agent memory for this codebase's conventions and recurring issues.

Review for:
- Correctness: logic errors, edge cases, null handling, concurrency, error handling
- Security: injection, missing authorization checks, secrets in code, unsafe deserialization
- Maintainability: naming, duplication, complexity, missing or weak tests

Report findings grouped as Critical (must fix), Warnings (should fix) and Suggestions.
For each finding give file:line, the problem, and a concrete fix.
End with a one-line verdict: APPROVE or REQUEST CHANGES.

Before you finish, add any new recurring pattern or convention you noticed to your agent memory.

Everything below the second --- is the agent's entire system prompt: it replaces Claude Code's own. Only name and description are required.

Fields used in the example

The other fields

Five rules

1. Keep .claude-plugin/ for the manifest only. Every other folder sits at the plugin root.
2. A CLAUDE.md in a plugin is not loaded. Ship instructions as a skill instead.
3. Everything is prefixed with the plugin name, so several plugins can each ship a review skill without clashing.
4. Plugin agents ignore hooks, mcpServers and permissionMode for security. Put hooks in hooks/hooks.json.
5. Point at bundled files with ${CLAUDE_PLUGIN_ROOT}. Its path changes on every update, so keep lasting state in ${CLAUDE_PLUGIN_DATA}. A plugin cannot reference files outside its own folder.

plugin.json (from the review-kit plugin)

{
  "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
  "name": "review-kit",
  "displayName": "Review Kit",
  "version": "1.0.0",
  "description": "Code-review subagent, a review checklist skill, and a hook that blocks dangerous shell commands.",
  "author": { "name": "Janaka" },
  "license": "MIT",
  "keywords": ["code-review", "security", "hooks", "subagent"]
}

Every manifest field

All paths in the manifest are relative to the plugin folder and start with ./.

The review-kit plugin, built and tested

Contents: agents/code-reviewer.md (the level 7 reviewer adapted for plugins: it lists Skill in its tools, its first step loads review-kit:review-checklist, and it drops color and initialPrompt), skills/review-checklist/SKILL.md, hooks/hooks.json plus scripts/block-dangerous.sh, and a README. Checked with Claude Code v2.1.278: claude plugin validate --strict passed, and plugin details found 1 skill, 1 agent and 1 PreToolUse hook, adding about 84 tokens to each session.

unzip review-kit.zip
claude plugin validate ./review-kit     # schema check
claude --plugin-dir ./review-kit        # load it for one session
cp -r review-kit ~/.claude/skills/      # load it in every project, from the next session

{
  "description": "Deny catastrophic shell commands, ask before risky ones",
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/scripts/block-dangerous.sh", "args": [], "timeout": 10 }
        ]
      }
    ]
  }
}

Sharing. Publish the plugin in a marketplace (a git repo with .claude-plugin/marketplace.json). Teammates add it with /plugin marketplace add owner/repo and install with project scope, which records it under enabledPlugins in the committed .claude/settings.json.

Four options, one best answer. Written from the docs as practice, not taken from the real exam. Tags: [D2] Claude Code Configuration and Workflows, [D5] Context Management and Reliability. Answer all fifteen before opening the answer key in the next section.

1. [D2] A bank's platform team must guarantee that no developer's Claude Code session can run sudo, whatever developers put in their own or project settings. What should they do? A. Add "Never use sudo" to the managed CLAUDE.md. B. Add a PreToolUse hook that blocks sudo to each repository's .claude/settings.json. C. Add a Bash(sudo *) deny rule to managed settings. D. Add disallowedTools: Bash(sudo *) to every subagent.
2. [D5] A developer adds a new rule to CLAUDE.md halfway through a session, but Claude keeps ignoring it. What is the most likely reason? A. CLAUDE.md is read once at session start; the edit loads after /clear, /compact or a restart. B. The rule must be moved into .claude/CLAUDE.md to be read. C. CLAUDE.md is only read by subagents. D. The rule needs a SessionStart hook to activate.
3. [D5] Your team has a 3,000-line migration runbook that Claude needs only when a migration task comes up. You do not want to pay its tokens in every session. What is the best option? A. Paste it into the project CLAUDE.md. B. Print it from a SessionStart hook. C. Put it into the output style. D. Package it as a skill with a clear description.
4. [D5] You need Claude to audit a large codebase for security issues without flooding the main conversation with hundreds of file reads. What is the best approach? A. Load a security-checklist skill in the main session. B. Delegate the audit to a subagent that returns a summary. C. Add a PostToolUse hook that scans each file Claude reads. D. Run /compact after every few file reads.
5. [D2] A PreToolUse policy hook meant to stop rm -rf ~ writes an error to stderr and exits with code 1. Claude runs rm -rf ~. What happens? A. The command is blocked and Claude sees the stderr text. B. Claude Code asks the user for permission. C. The command runs, because exit 1 is a non-blocking error. D. The session ends.
6. [D5] After /compact, Claude stops picking up several skills it used to use automatically, although a skill it invoked earlier still works. Why? A. The skill listing is not re-injected after compaction; only invoked skill bodies are. B. Compaction disables all model-invocable skills until restart. C. After compaction, skills load only inside subagents. D. Compaction clears the skill folders' cache on disk.
7. [D2] ~/.claude/settings.json sets the model to haiku, the project's .claude/settings.json sets opus, and .claude/settings.local.json sets sonnet. There are no CLI flags or managed settings. Which model is used? A. opus, because shared project settings keep the team consistent. B. haiku, because user settings follow you everywhere. C. Whichever file was saved most recently. D. sonnet, because local project settings override shared project settings.
8. [D2] A subagent's frontmatter sets permissionMode: plan, but the developer runs the main session in auto mode. How does the subagent run? A. In plan mode, as its frontmatter says. B. In auto mode, because the main session's mode wins when it is auto, acceptEdits or bypassPermissions. C. In default (Manual) mode. D. It refuses to launch because the modes conflict.
9. [D2] You give a subagent isolation: worktree so it can try refactors safely. It reports that it cannot find changes you made this morning and have not committed. Why? A. Worktrees are read-only. B. Worktree subagents cannot use Bash. C. The worktree branches from the default branch, not your current HEAD, so uncommitted work is not there. D. The worktree is deleted before the subagent starts.
10. [D2] Where should a plugin's hook configuration live? A. hooks/hooks.json at the plugin root, or inline in plugin.json. B. .claude-plugin/hooks.json. C. In the frontmatter of the plugin's agents. D. In a CLAUDE.md at the plugin root.
11. [D2] A skill named deploy exists in ~/.claude/skills/deploy/ and another in the repo's .claude/skills/deploy/. There is no managed skill. Which one does Claude use? A. The project one, because project configuration always beats personal configuration. B. Both, merged into one skill. C. Neither, because Claude Code refuses duplicate names. D. The personal one, because for skills user beats project.
12. [D2] Your plugin's plugin.json has "version": "1.0.0". You push several fixes without changing it. What do users get? A. The fixes, automatically, on next startup. B. Nothing new: with a version set, users only get updates when you bump it. C. An error because the version is stale. D. A prompt asking whether to update.
13. [D2] A PreToolUse hook exits 0 with no output for a command. What does that mean? A. The command is approved and skips permission checks. B. The command is denied. C. The hook has no opinion; the normal permission flow decides. D. Claude is asked to retry the tool call.
14. [D2] Which of these is NOT a way to deliver organization-managed Claude Code settings? A. A managed-settings.json file in the system configuration folder. B. MDM or OS policy (macOS plist, Windows registry). C. Server-managed settings from the claude.ai admin console. D. A "managed": true flag inside ~/.claude/settings.json.
15. [D5] Which of these belongs to the system-prompt layer of a Claude Code request, rather than the project-context layer? A. Tool definitions and the git status snapshot. B. ~/.claude/CLAUDE.md. C. The first 200 lines of MEMORY.md. D. Unscoped rules in .claude/rules/.

Score: ____ / 15. For every miss, re-read the level named in the answer key.

Sources

• Explore the .claude directory: every file and where it lives
• Extend Claude Code: when to use each feature and how they layer
• Settings: scopes and precedence
• Managed settings: organization policy
• Memory: CLAUDE.md, rules and auto memory
• Explore the context window: what loads and when
• Prompt caching: the three request layers
• Hooks reference: events, exit codes, JSON output
• Subagents: definition files and fields
• Plugins reference: layout and plugin.json
• On this site: MCP end to end, the protocol behind the MCP box in the map.