Domain 2 – Facts

Claude Code reads every memory file that applies to your folder and appends them, broadest first. The docs call this a load order, not a priority order: nothing deletes the earlier text, so both rules stay in context. That's why a project rule can't reliably beat a developer's personal ~/.claude/CLAUDE.md. If a rule must hold every time, put it in settings permissions or a hook — the client enforces those, whatever the model decides.

CLAUDE.md text is guidance for the model, with no guarantee it is followed. Permissions and hooks are run by the Claude Code client itself: a deny rule stops the call, and a PreToolUse or PostToolUse hook runs as a shell command no matter what the model wrote. Putting the sentence in CLAUDE.local.md just makes it the last file added; the conflict is still in context. And because that file is gitignored, a team rule there never reaches teammates.

At session start, Claude Code reads the memory files above the working directory. A CLAUDE.md inside services/billing/ stays unread until Claude touches files under that path; then it is pulled in and adds to the parent files — it does not replace them. That keeps billing rules out of unrelated sessions with no extra setup. If the rules belong to a file type spread across many folders, use a paths: rule instead.

Rules files let you split one big CLAUDE.md into topic files. Add a paths: list of glob patterns (file-name patterns) and the file becomes conditional: it enters context only when Claude edits a matching file, wherever it lives. That saves tokens and stops, say, Terraform rules showing up in React work. A section heading in the root file, a copy of the file in every folder, or a slash command you must type yourself — none of these switch on automatically by file pattern.

Pick the tool by the shape of the rule. Rules for a file type that shows up in many folders (test files, .tf files) need a .claude/rules/ file with paths: globs, because it matches by pattern. Rules for one folder tree need a nested CLAUDE.md, because it loads by location. A heading in the root file loads with everything else, and an @import line pulls its file in at session start — neither one is conditional.

The user-level file sits in your home directory and applies to every project you open, but it is never part of the repo. When a teammate pulls or CI checks out the code, only committed files travel: the project CLAUDE.md, .claude/rules/, settings and skills. A standard written only in ~/.claude/CLAUDE.md looks like "no standard" to everyone else. Keep personal preferences in the user file; put team standards in the project file and review them like code.

/memory gives a sure answer: it prints the user, project and folder-level memory files in this session, so a stray user file or a missing project file shows up right away. Asking the model to repeat the rule proves nothing — it can answer from training data or partial context. Deleting ~/.claude/CLAUDE.md is a destructive guess. /compact only summarizes the conversation; it does not reload or report config.

A message that starts with # adds that line to a memory file without opening an editor. /memory opens the loaded files for editing. /init scans the repo and writes a first CLAUDE.md with its build and test commands. An @path line inside a memory file pulls in another file when it loads. It keeps the root file short, but the imported text still uses context every session — tidier, not cheaper.

Memory files stack by folder: a CLAUDE.md in clients/acme/ is added on top of the root file, so the stricter rules apply only when the job runs from there, and every other run keeps the defaults. CLAUDE.md has no if-logic, so an "if the brief contains CLIENT_ID" block is just text. --append-config doesn't exist; the real --append-system-prompt-file flag adds to the system prompt, which is a different mechanism. Putting the rules in the user message works once, but it is not config.

The usual cause is that the instruction never said what an integration test must include. Concrete criteria — a real database connection, API contract checks, migration rollback, an example fixture — give the model a clear target and fix it at the source. A paths: rule or PostToolUse hook that rejects every mock also kills good unit tests. A review subagent that rewrites tests afterwards is less reliable and more complex than just saying what you need.

For single-value settings, these layers have a strict order, and the exam tests the whole chain. Managed policy comes from your organization, and nothing below can override it. A command-line value beats every file. Your personal, gitignored local project file beats the shared project file. Your home settings are weakest. This order is for settings only — CLAUDE.md text is added together, not ranked.

So it depends on the key. A single value such as model follows the precedence chain. Permission lists (allow, ask, deny) are combined from every layer, which is why a deny anywhere still applies. Memory files are pasted into context with no ranking at all. An answer that describes one hierarchy for everything is wrong about at least one of the three.

Claude Code checks deny rules first: if any layer denies a tool pattern, the call is blocked, however many allows match. It is not symmetric — dropping a tool from the allow list only removes pre-approval, so you get a prompt, not a block. To really take a tool away, use deny, disallowedTools or --tools. For a pipeline that needs human approval, hard-block the tool and tell the model to write a request for the human queue: a PostToolUse hook fires after the damage, and a PreToolUse hook can't pause and wait for a person.

Bash(npm run test:*) pre-approves only shell commands that start with npm run test; * is the wildcard, and other Bash commands are not covered. Read(.env*) in the deny list stops the model from reading any file whose name starts with .env, so secrets never enter context. MCP tools use the same system with the name mcp__<server>__<tool>, so you can allow one tool on the docs server and deny another one from the same server.

The two project files differ only in who sees them. .claude/settings.json is committed, so anything there is a team decision that every clone inherits. .claude/settings.local.json is your personal override for this checkout; it beats the shared file and must stay out of git. Writing "use Haiku" as text in CLAUDE.md does not set the model. Managed policy is for company-wide controls, not one person's preference.

IT puts managed settings in a system path normal users can't edit — /Library/Application Support/ClaudeCode/managed-settings.json on macOS, /etc/claude-code/ on Linux. Any key it sets — a deny on reading .env files, disableBypassPermissionsMode, a forced login method — sits at the top, and because permission lists add up, no lower file can cancel them. It is a clamp, not a full config: keys it doesn't mention are left to the layers below.

The flag removes the permission prompt completely. That's handy in a throwaway container, but it deletes the exact check a security question wants you to keep. The expected design is narrow allow rules like Bash(npm run test:*), credentials that can't publish, and a real network sandbox — controls that still work when the model makes a mistake or reads malicious input. To ban the flag org-wide, set disableBypassPermissionsMode: "disable" in managed settings; no lower layer can loosen it.

Claude Code keeps ~/.claude.json for itself: folder trust, global preferences and MCP server definitions. It is not a fifth settings.json layer, and there is no project-level claude.json. MCP scope means who a server is for, not where the file lives: user-scope and local-scope (per project path) servers both live in this home file, while project-scope servers your team shares live in .mcp.json at the repo root.

Tools you didn't list still exist; they may just prompt. --tools picks which built-in tools exist, and disallowedTools/deny block a pattern. But careful: in the exam's pipeline scenarios, allowedTools on a subagent or SDK query is treated as the hard set of tools the agent can reach. That holds because the run is unattended: nobody can approve a tool that is not pre-approved, so its call is denied. There, an allowlist beats a disabledTools blocklist, because any tool added to the server later is unreachable by default. A CLAUDE.md sentence is only soft advice, and a PreToolUse hook only reacts after the model already chose the tool.

Anything under the repo's .claude/ folder is in git, so the skill shows up in every clone and updates arrive with git pull. ~/.claude/skills/ is per user; sharing it through a wiki makes machines drift apart. CLAUDE.md is for always-loaded standards, not an on-demand multi-step procedure, and an MCP server gives tools and data, not prompt workflows. Subagents use the same layout in .claude/agents/.

There are three actors: you, the model, and the harness (Claude Code, the program around the model). The model reads the skill's description, decides it fits, and asks for it; the harness loads the skill and runs any tool calls the permission rules allow. Typing /name is a second way in. A hook is different: the harness fires it on a lifecycle event, with nobody choosing. Picking a skill is not permission — tool rules still decide what runs.

Each flag turns off one of the two routes. disable-model-invocation: true stops Claude from choosing the skill by itself — right for a deploy skill you never want fired by a casual "go live" sentence. user-invocable: false hides the slash command and leaves the choice to the model. Neither flag touches permissions: the skill still needs tool rules and credentials that allow what it does.

By default a skill loads inline, so a long analysis skill fills your main conversation and Claude can lose the original task. context: fork sends the body to a subagent with its own context window; the named agent: runs it there and only a summary returns. That is context isolation, nothing more: same working files (no git worktree), not running at the same time as the main session, and no copy of the whole conversation. Splitting the skill or using a smaller model still dumps everything into the main context.

allowed-tools lists tools the skill can use without asking each time. It is a convenience, not a limit: unlisted tools are still available, and a deny or ask rule from any settings layer still beats it. So real read-only behavior comes from permission rules or a subagent's tool list, not from this field. argument-hint is even lighter — it shows a hint in command completion and doesn't check or require anything.

A slash command saves a fixed prompt so everyone runs exactly the same text, and $ARGUMENTS fills in the part that changes — a ticket ID, an environment name. It is committed, so the team shares one version with no retyping. A hook is wrong because it fires on lifecycle events, not when you ask; a subagent adds a separate context for what is just a template; pasting it into CLAUDE.md loads release details into every unrelated session. Modern skills can offer the same /name, so it's not only for old command files.

Each subagent is its own instance with its own config, so its tools are decided where it is defined — the tools list in its .claude/agents/ frontmatter, or allowedTools passed at creation. A web-search worker set up that way can't call write_report, even if a prompt tells it to. A CLAUDE.md list of allowed tools is just advice, and the coordinator's PreToolUse hook never sees calls inside another agent's session. Separate MCP namespaces would work but need server changes for something config already solves.

A subagent starts with a fresh context window: it can read dozens of files, trace callbacks and inheritance, and return only a short list of findings, so the exploration never lands in your main conversation. Compacting more often still lets the material pile up first and may summarize away other context; a bigger model only delays the problem. The built-in Explore subagent is tuned for thorough discovery, which fixes a shallow three-file summary. Plan mode explores too, but inside the main conversation, and it aims at a change plan, not full discovery.

Plan mode lets Claude explore the code, map dependencies and propose a design without editing anything, so a split across dozens of files is designed before the first change. Starting directly assumes you already know the right boundaries, and you pay in rework when cross-module dependencies show up halfway. If you already know it's complex, don't wait until it gets hard to switch to plan mode. For a clear, small change, direct execution is the right start.

git worktree checks out several branches of one repo into separate folders that share one git history. Each Claude Code instance edits its own files, and you merge with normal branch operations. Three separate clones would work but leave histories to reconcile by hand. One shared folder fails because switching branches changes the files under the other instances. fork_session and a context: fork skill make separate conversations, not separate filesystems, so they can't stop three big edits from colliding.

Hooks can go in .claude/settings.json (shared), .claude/settings.local.json (personal), ~/.claude/settings.json (user) or managed settings, and Claude Code reads them at startup. Writing "always run the formatter" in CLAUDE.md registers nothing — the model may or may not follow it. The JSON only points to a script; the logic lives in that script, which must exist and follow the hook's input/output contract.

The event name (PostToolUse) decides when it fires. Each matcher is a regex on the tool name, so Write|Edit covers both editing tools. The inner hooks list holds the handlers, and type: command tells Claude Code to run a shell command. $CLAUDE_PROJECT_DIR expands to the repo root, so scripts work from anywhere. The handler gets the tool name, inputs and file paths as JSON on stdin — don't expect a $FILE variable.

The hook ties the formatter to the event: after any Write or Edit succeeds, Claude Code runs it on the file, whether the model remembered or not. A CLAUDE.md rule needs the model to comply on every single edit; a skill runs only when formatting seems relevant; /format relies on a human. The hook still misses edits made through Bash or outside Claude Code, so keep a CI formatting check as the repo-wide backstop.

Timing is the whole difference. A PreToolUse hook sees the proposed call before it runs; exit code 2 vetoes it, and the model can't talk its way around that. A PostToolUse hook runs after the tool succeeded: it can format, test or log, but the file is already on disk. Both are run by the client, so unlike CLAUDE.md text, they hold even when the model would rather do something else.

At PreToolUse time the Write tool hasn't run, so there is nothing on disk for Checkstyle or Prettier to format; the hook only sees the proposed input. That makes it the place to inspect or reject — block a write to a protected path, lint a shell command — not to fix output. PostToolUse gets the finished write and can correct it in place. A hook on Read that checks files before they enter context is on the wrong event entirely.

Compaction summarizes the conversation and throws away detail, so anything you want must be saved just before. PreCompact is the event for that: it fires before manual and automatic compaction and gets the transcript path, so it can copy it to a timestamped log. Compaction is not a tool the model calls, so no PreToolUse matcher catches it. Logging every result with PostToolUse makes huge files that still miss reasoning and user messages, and a hook on Write fires at unrelated times.

Match each event to a job. UserPromptSubmit runs when the user sends a message, before the model sees it. Stop and SubagentStop run when Claude or a subagent finishes — the place to check that tests passed or the checklist is done, or to send a notification. SessionStart runs once when a session opens. Together with PreToolUse, PostToolUse and PreCompact, these cover the whole session.

A hook fires only for the tools its matcher names. A sed command through Bash, a script that rewrites files, or a developer in their IDE never trigger a Write|Edit hook, so the check is silently skipped. The repo-wide guarantee is a required CI check on every pull request, however the change was made. Hooks are also synchronous: a PreToolUse hook can block or ask the user, but it can't pause for an outside approval, so human sign-off belongs in a queue the pipeline routes to.

-p (print mode) runs one prompt and exits — what CI scripts need — and --output-format json or stream-json wraps the result for a pipeline to parse. Neither changes what Claude Code can do: it still has Read, Grep and Glob, and the format doesn't touch the analysis. If a headless check claims 100% coverage that audits disprove, the prompt had no validation criteria, so the model pattern-matched instead of checking each endpoint. Give explicit criteria and an expected output format; a second instance reviewing the same vague output won't help.

Headless mode makes the run scriptable. --allowedTools "Bash(npm run test:*)" pre-approves exactly the commands the job needs, so it never stalls on a prompt. Hooks add fixed checks around tool calls. Read-only credentials mean even a hijacked prompt can't push or publish. An allow never cancels a deny from any settings layer. --tools is a different knob: it picks which built-in tools exist and doesn't affect MCP tools, which are set up and denied separately.

A GitHub Actions runner is a fresh machine with only what the workflow checks out or sets up. Everything committed — CLAUDE.md, .claude/rules/, .claude/settings.json, .claude/skills/ — is there and loads normally. A developer's home-folder memory file was never copied, so rules that lived only there vanish in CI. Headless mode doesn't turn off memory, and no managed policy strips user files; the file just isn't on the runner.

Anyone can comment on a public repo, so a workflow that ran on every @claude mention would let strangers steer an agent that holds the repo's credentials. So the official Action checks the commenter's permission level and runs only for users with write access. The API key lives in the repo's secrets, not in the contributor's fork, and a missing event subscription wouldn't explain why trusted and untrusted commenters behave differently.

The workflow file is plumbing, not policy. The on: block and the @claude trigger decide when the job runs, permissions: limits the GitHub token, and a secret reference supplies the key. Coding standards, permission rules, hooks and skills all come from the committed CLAUDE.md, .claude/rules/, .claude/settings.json and .claude/skills/. On GitHub those committed files are the only voice; there is no user layer to fill gaps.

Tests and linters give the same answer every run, so a failure is a repeatable fact the team agreed to enforce. An AI reviewer's opinion is useful, but it isn't proven reliable or objective enough to be a hard gate, so post it as comments. Making any AI output blocking lets unsupported claims stop merges; removing every gate lets known test failures through. And a workflow that runs checks is not a gate until branch protection lists it as required.

Permission rules match the command Claude Code is asked to run. So a deny on git push or curl does nothing when an allowed script like npm test opens a connection or pushes by itself. The guarantee must come from the environment: a token with permissions: contents: read and persist-credentials: false, so no write credential is on the runner, plus a network sandbox or egress (outgoing traffic) policy. Prompt instructions and trusting the model restrict nothing when the model makes a mistake or reads malicious input.

The Agent SDK is the Claude Code runtime as a library, not a thin wrapper on the Messages API. A query() call takes the same kinds of options Claude Code uses and, depending on cwd and setting_sources, reads the project's CLAUDE.md and settings; an empty setting_sources turns that off. A direct anthropic.messages.create call sends only what you put in the request — it has no idea a CLAUDE.md exists on disk. So when a question names the runtime, check which one before assuming instructions get discovered.