Domain 2 · Claude Code Configuration & Workflows (20%)

This domain explains three things about Claude Code. Where do its instructions and settings live? When does Claude Code load them? Which mechanisms run an action, and which ones block it?

How this page is organized: the six exam tasks

Domain 2 is simple at the top: how you configure Claude Code, and how you work with it. The official exam guide splits that into six tasks. This page follows them in order. Every section opens with a box that says what it teaches, the scenario, and which exam task it serves.

Numbering note: this KB calls it "Domain 2". The official exam guide calls the same content Domain 3: Claude Code Configuration & Workflows (20%), so its tasks are numbered 3.1–3.6.

The Claude Code file map: every file, where it lives, who wins

Here's the trick. Claude Code reads config from four levels: Organization (your IT team), User (you, every project), Project (the team, committed in git) and Local (you, this one project). At each level there are two very different kinds of file. Settings files (*.json) are rules that Claude Code itself enforces: permissions, hooks, env, model. Instruction files (CLAUDE.md, .claude/rules/*.md) are advice that the model reads; nothing enforces them. (Rule or guidance? The full explanation.) Settings fight each other by precedence, and the higher level wins. Instruction files never fight: Claude Code loads all of them, one after the other.

The map

‹managed› is the system folder for organization files. macOS: /Library/Application Support/ClaudeCode/. Linux and WSL: /etc/claude-code/. Windows: C:\Program Files\ClaudeCode\ (Claude Code does not read the old C:\ProgramData\ClaudeCode\ path). Managed settings can also arrive without a file: from the claude.ai admin console, an MDM profile (macOS domain com.anthropic.claudecode), or the Windows registry (HKLM\SOFTWARE\Policies\ClaudeCode). Click any path with ↗ to see a full example file. All the examples belong to one developer on one repo, acme-app, so they fit together.

What is managed-settings.d/? It is an optional folder next to managed-settings.json for splitting the org policy into several files. Why: in a big company, different teams own different parts of the policy. The telemetry team owns telemetry, security owns the deny rules. Instead of everyone editing one shared file, each team ships its own file, for example 10-telemetry.json and 20-security.json. Claude Code reads managed-settings.json first, then every *.json in the folder in alphabetical order (that's why the number prefixes), and merges them into one org policy. Inside that merge: single values → the later file wins; lists like permissions.deny → combined, duplicates removed; blocks like env → merged key by key. It ignores hidden files and files that don't end in .json. A file that isn't valid JSON stops Claude Code from starting. To you as a developer it all looks like one managed level. Official: split a policy across teams↗

Hooks can also be registered in a plugin's hooks/hooks.json, in a skill's frontmatter, and in a subagent's frontmatter. ~/.claude.json is a separate file that Claude Code writes for itself (sign-in, trust decisions, your MCP servers). It is not ~/.claude/settings.json.

Who wins?

Settings: the higher level wins. This is the official order, highest first:

1. Managed settings: managed-settings.json, MDM, or the claude.ai console. Nothing in your own files or in --settings overrides a managed key.
2. Command line: claude --settings '<json or file>', for this session only.
3. Project local: .claude/settings.local.json.
4. Shared project: .claude/settings.json.
5. User: ~/.claude/settings.json.

So yes, your personal ~/.claude/settings.json is the lowest. The team file beats it. Your local file beats the team file.

Single values: the higher level wins. Lists: they merge. model set in two files? Claude Code takes the value from the higher one. permissions.allow set in three files? Claude Code combines all three lists. env is merged per variable: when two files set the same variable, the higher one applies. hooks merge across files too, and nobody can remove a managed hook from another file.

Deny beats allow, at any level. Claude Code checks rules in this order: deny, then ask, then allow. The first match decides. A deny in your user file blocks an allow in the project file, and the other way round. An allow can never cut an exception out of a deny: deny: Bash(aws *) blocks allow: Bash(aws s3 ls).

A few exceptions (official list, short version):

• Some model keys don't merge: fallbackModel (taken whole from the highest file), modelPicker (only managed, --settings or user count), availableModels (a managed list applies as-is; your additions are ignored), modelSettings (resolved per model).
• A few security keys honor the stricter value even from a lower level, over managed. Examples: disableClaudeAiConnectors: true, permissions.blockReadsOutsideWorkingDirectories: true, isolatePeerMachines: true, a lower maxEffortLevel cap. The full table also covers enableArtifact, autoMode.classifyAllShell, remoteControlAtStartup, crossSessionInbound, useAutoModeDuringPlan, syncClaudeAiSkills and syncClaudeAiPlugins.
• Some keys are managed-only. In user or project files they do nothing. Examples: allowManagedPermissionRulesOnly, allowManagedHooksOnly, allowManagedMcpServersOnly, strictPluginOnlyCustomization, managedMcpServers, claudeMd.
• permissions.defaultMode values auto and bypassPermissions don't take effect from project or local files. Set them in user or managed settings.
• Environment variables are not a level. For example, ANTHROPIC_MODEL in your shell beats the model key from any file.

Instruction files: no winner, all of them load. Claude Code concatenates (joins) every CLAUDE.md it finds. They don't override each other. Load order is from broadest to most specific: managed, then user, then project, then local. Inside the directory tree, it goes from the filesystem root down to your working folder, and in each folder CLAUDE.local.md comes after CLAUDE.md. So the most specific file is read last. If two instructions contradict each other, the docs say Claude "may pick one arbitrarily". User rules (~/.claude/rules/) load before project rules, and neither overrides the other. You can skip unwanted files with claudeMdExcludes, but the managed CLAUDE.md cannot be excluded.

Careful: other file types have their own order.

• Subagents with the same name: managed > --agents flag > project > user > plugin.
• Skills with the same name: enterprise > personal > project. Yes, here your personal skill beats the project skill, the opposite of settings.
• MCP servers with the same name: local > project > user > plugin > claude.ai connectors. A server the org provides through managedMcpServers beats a local, project or user server with the same name. The whole entry from the winner is used; fields don't merge. And managed-mcp.json is different: it doesn't win a contest, it ends it. When that file exists, Claude Code loads only its servers (plus any from managedMcpServers), and users can't add others.

The four settings files, side by side

These four files belong to one developer on one repo, acme-app. They use the same keys, so you can follow each conflict.

{
  "availableModels": ["claude-sonnet-5", "claude-opus-5-5"],
  "cleanupPeriodDays": 30,
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./secrets/**)",
      "Bash(aws *)"
    ],
    "disableBypassPermissionsMode": "disable"
  },
  "env": {
    "DISABLE_TELEMETRY": "1"
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "/usr/local/bin/acme-audit-bash.sh" }
        ]
      }
    ]
  },
  "claudeMd": "Never commit secrets. Follow the ACME security standard."
}

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "claude-opus-5-5",
  "cleanupPeriodDays": 90,
  "permissions": {
    "allow": [
      "Bash(git status)",
      "Bash(git diff *)"
    ]
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "~/.claude/hooks/check-bash.sh" }
        ]
      }
    ]
  }
}

{
  "model": "claude-sonnet-5",
  "permissions": {
    "allow": [
      "Bash(mvn test *)",
      "Bash(mvn package *)"
    ],
    "deny": [
      "Bash(rm -rf *)"
    ]
  },
  "env": {
    "MAVEN_OPTS": "-Xmx2g"
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/format.sh" }
        ]
      }
    ]
  }
}

{
  "model": "claude-opus-5-5",
  "permissions": {
    "allow": [
      "Bash(docker compose up *)",
      "Bash(aws s3 ls)"
    ]
  },
  "env": {
    "MAVEN_OPTS": "-Xmx4g"
  }
}

Trace it: what Claude Code actually ends up with

Instruction, agent, skill and MCP files: examples

# ACME engineering standards

- Never put secrets, tokens or customer data in code, logs or commits.
- All new services use Java 21 and Spring Boot 3.
- Ask before changing anything under `infra/` or `.github/workflows/`.

# My preferences

- Explain in plain, short sentences.
- Prefer constructor injection over field injection.
- Run the tests before you say a task is done.

# acme-app

- Build: `mvn package`. Test: `mvn test`.
- Layout: `src/main/java/com/acme/api` = REST controllers, `.../service` = business logic.
- Every controller method validates its input with Bean Validation.
- Error responses always use `ErrorResponse { code, message }`.

---
paths:
  - "src/main/java/com/acme/api/**/*.java"
---

# API rules

- Every endpoint has an OpenAPI annotation.
- Never return a JPA entity; map it to a DTO.
- Use the standard `ErrorResponse` format.

---
name: code-reviewer
description: Reviews code for correctness, security, and maintainability
tools: Read, Grep, Glob
---

You are a senior code reviewer. Review for:

1. Correctness: logic errors, edge cases, null handling
2. Security: injection, auth bypass, data exposure
3. Maintainability: naming, complexity, duplication

---
description: Reviews code changes for security vulnerabilities, authentication gaps, and injection risks
disable-model-invocation: true
argument-hint: <branch-or-path>
---

## Diff to review

!`git diff $ARGUMENTS`

Audit the changes above for:

1. Injection vulnerabilities (SQL, XSS, command)
2. Authentication and authorization gaps
3. Hardcoded secrets or credentials

Use checklist.md in this skill directory for the full review checklist.

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "NOTION_TOKEN": "${NOTION_TOKEN}"
      }
    }
  }
}

Every other file in the map: full examples

These complete the map. Each one also opens from its ↗ link in the table.

// managed-settings.d/10-telemetry.json — owned by the platform team
{
  "cleanupPeriodDays": 30,
  "env": {
    "DISABLE_TELEMETRY": "1",
    "OTEL_SERVICE_NAME": "claude-code-acme"
  }
}

// managed-settings.d/20-security.json — owned by the security team
{
  "cleanupPeriodDays": 14,
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(~/.aws/**)"
    ]
  }
}

# My notes for acme-app (not shared)

- My local database runs on port 5463 (docker compose), not 5432.
- Test account for manual checks: `dev-sam@acme.test`.
- I'm working on the refund flow this week; start there.

---
paths:
  - "**/*.java"
---

# My Java style

- Use `record` for DTOs instead of a class with getters.
- Prefer `Optional` return values over returning `null`.
- Keep methods under ~30 lines; extract a private method otherwise.

---
name: security-auditor
description: Audits changes for secrets, injection and auth problems. Use before any commit that touches auth or payment code.
tools: Read, Grep, Glob
---

You are ACME's security auditor. You only read code; you never edit it.

Check the changed files for:
1. Hardcoded secrets, tokens or passwords
2. SQL, command or template injection
3. Missing authorization checks on endpoints

Report each finding as: file:line, severity (high/medium/low), one-line fix.

---
name: explainer
description: Explains unfamiliar code in plain, short English. Use when the user asks what some code does.
tools: Read, Grep, Glob
---

Explain the code the user points at.
- Start with one sentence: what it does and who calls it.
- Then walk through it step by step in short sentences.
- Name each technical term with its meaning the first time.

---
description: ACME's release checklist. Use when preparing or reviewing a production release.
---

Before a release, confirm each item and report ✅ or ❌:

1. All tests pass on the release branch (`mvn verify`).
2. The CHANGELOG has an entry for this version.
3. Database migrations are backward compatible.
4. No `TODO` or `FIXME` in the changed files.

---
description: Explains the current git diff in plain English, file by file.
argument-hint: [base-branch]
---

## The diff

!`git diff ${ARGUMENTS:-main}`

Explain the diff above:
- one short paragraph per file: what changed and why it matters
- end with the risks a reviewer should check

---
description: Summarize what I did since yesterday for standup
---

Look at my git commits since yesterday (`git log --since=yesterday --author="$(git config user.name)"`)
and write three bullets: done, doing, blocked.

---
description: Fix a GitHub issue by number
argument-hint: <issue-number>
---

Fix GitHub issue #$ARGUMENTS:
1. Read the issue with `gh issue view $ARGUMENTS`.
2. Find the code involved and fix it.
3. Add or update a test that fails without the fix.
4. Run `mvn test` and report the result.

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    }
  }
}

{
  "mcpServers": {
    "hubspot": {
      "type": "http",
      "url": "https://mcp.hubspot.com/anthropic"
    }
  },
  "projects": {
    "/Users/sam/Projects/acme-app": {
      "mcpServers": {
        "stripe": {
          "type": "http",
          "url": "https://mcp.stripe.com"
        }
      }
    }
  }
}

#!/usr/bin/env bash
# PreToolUse hook (matcher: Bash). Logs every command; blocks pushes to main.
input=$(cat)                                        # JSON from Claude Code on stdin
cmd=$(jq -r '.tool_input.command' <<<"$input")
echo "$(date -u +%FT%TZ) $USER $cmd" >> /var/log/acme/claude-bash.log
if [[ "$cmd" =~ git\ push.*(main|master) ]]; then
  echo "Blocked by ACME policy: push to a branch and open a PR instead." >&2
  exit 2
fi
exit 0

#!/usr/bin/env bash
# PreToolUse hook (matcher: Bash). Stops me from deleting things by accident.
cmd=$(jq -r '.tool_input.command')                  # stdin = the pending tool call
if [[ "$cmd" =~ (^|[[:space:]])rm[[:space:]]+-rf ]]; then
  echo "rm -rf is blocked by my user hook. Delete the specific file instead." >&2
  exit 2                                            # 2 = block; stderr goes to Claude
fi
exit 0

#!/usr/bin/env bash
# PostToolUse hook (matcher: Edit|Write). Formats every Java file right after Claude edits it.
file=$(jq -r '.tool_input.file_path')               # stdin = the tool call that just ran
if [[ "$file" == *.java ]]; then
  google-java-format --replace "$file"
fi
exit 0

Straight answers

Is the org-level file settings.json or CLAUDE.md? Both can exist, side by side in the same system folder. managed-settings.json holds enforced settings. CLAUDE.md holds instructions. Note the name: at org level it is managed-settings.json, not settings.json. IT can also skip the separate CLAUDE.md and put the text in the claudeMd key inside managed-settings.json.

Do settings only configure hooks? No. Settings files hold permissions (allow / ask / deny), hooks, env, model, statusLine, outputStyle and many more keys. Things that are not in settings: instructions (CLAUDE.md, .claude/rules/), subagents (agents/), skills (skills/), and project MCP servers (.mcp.json). Your personal MCP servers live in ~/.claude.json.

Where are agents defined? As markdown files: .claude/agents/<name>.md for the project, ~/.claude/agents/<name>.md for you. You can also pass them as JSON with claude --agents '…' for one session, or get them from a plugin's agents/ folder.

Are there org-level agents and skills? Yes. The admin puts them inside the managed settings folder: .claude/agents/ and .claude/skills/<name>/SKILL.md there (macOS: /Library/Application Support/ClaudeCode/.claude/agents/). A managed agent beats a project or user agent with the same name. An enterprise skill beats personal and project skills with the same name. The other way to share across a team is a plugin. An org-level rules/ folder is not documented.

Where do MCP servers go? Team: .mcp.json at the project root, committed. Just you: ~/.claude.json (user scope = all projects, local scope = this project only), written by claude mcp add --scope user|local. Org, two different tools: managed-mcp.json in the managed folder is a lock (only its servers load; nobody can add others), while the managedMcpServers key in managed settings adds remote servers and users keep their own.

Does CLAUDE.md enforce anything? No. The docs call it "context, not enforced configuration". Claude usually follows it, but nothing forces it. If something must never happen, use a permissions.deny rule or a PreToolUse hook. Claude Code applies those whatever the model decides.

Rule or guidance? What is enforced, and what Claude only reads

Short answer: settings are enforced; CLAUDE.md is guidance. Claude tries to follow CLAUDE.md, and usually does. But nothing stops it when it doesn't. A settings rule does not depend on Claude at all: Claude Code (the program) checks it in code, every time.

The official docs say it word for word:

"Settings rules are enforced by the client regardless of what Claude decides to do. CLAUDE.md instructions shape Claude's behavior but are not a hard enforcement layer." — Memory docs↗

"CLAUDE.md content is delivered as a user message after the system prompt, not as part of the system prompt itself. Claude reads it and tries to follow it, but there's no guarantee of strict compliance, especially for vague or conflicting instructions." — Memory docs, troubleshooting↗

Who reads what: the model or the program?

Two different readers. This is the whole trick.

Think of a new coworker. CLAUDE.md is the team wiki they read on day one. They follow it almost always. Settings are the badge reader on the server-room door: it doesn't matter what they decided, the door doesn't open.

Same rule, written both ways

The rule: "never push to main".

# acme-app

- Never push to `main`. Push to a feature branch and open a PR.

{
  "permissions": {
    "deny": [
      "Bash(git push origin main*)",
      "Bash(git push --force*)"
    ]
  }
}

Best practice is both: the CLAUDE.md line tells Claude why and what to do instead (so it doesn't waste a turn hitting the wall). The deny rule makes sure it can't happen. For checks that need logic (look inside the command, check a file path, run a formatter), use a hook script instead of a deny rule. Example hook scripts.

It's the same split outside Claude Code

The exam asks this in every runtime. Only the names change.

So in the API world, the system prompt is the CLAUDE.md: guidance. And your code is the settings.json: enforcement. Writing "IMPORTANT: NEVER refund more than $500" in capital letters in the system prompt is still guidance. A code check if amount > 500: require_approval() is enforcement.

One trap: "Respond only in JSON" in the system prompt is guidance, so the model may add text around the JSON. output_config.format with a JSON schema is enforcement. The API constrains the output so it matches the schema (the documented exceptions: a refusal, or a reply cut off by max_tokens). Structured output, in Domain 3.

How to pick the answer on the exam

Read the stem for these words:

Two traps to spot. A distractor is a wrong answer choice that is written to look right.

• Trap 1: a louder prompt, when the question asks for a guarantee. The question says "must never" or "guarantee". One answer choice says "add CRITICAL to CLAUDE.md" or "repeat the rule in the system prompt". Don't pick it. Capital letters and repetition make the instruction louder, but it is still text that the model reads, and the model can still ignore it. So it is not a guarantee. Pick the choice that adds a check in code: a deny rule or a hook in Claude Code, or a code check in your API app.
• Trap 2: a hook, when the question only asks Claude to know something. The question says the team wants Claude to know a convention, for example "use pnpm". One answer choice adds a hook or a code check. Don't pick it. A hook can block an action or run a command, but it can't teach Claude anything. Pick the choice that adds a line to the project CLAUDE.md.

CLAUDE.md, settings.json, and .claude.json: which file does what?

These are separate kinds of files. They are not three competing versions of one configuration. The names say CLAUDE, not “cloud.” .claude is a directory; .claude.json is a file. Open the file guide glossary.

Instruction files: guidance loaded into context

# services/billing

- Money amounts are integer cents. Never use floats.
- Ledger writes go through `postEntry()`; never write SQL INSERTs directly.
- Run `mvn -pl services/billing test` after any change in this folder.

Claude Code adds every matching Markdown file to the context; the files add up. Files in parent folders load when the session starts. Files in nested folders can load later, when Claude reads files in that folder. This is not like JSON, where one key replaces another. A more specific instruction can guide the model, but Markdown is guidance only. It is not a hard permission limit. Official memory documentation↗.

Settings files: runtime configuration and precedence

Settings files configure permissions, hooks, the preferred model, and other supported behavior. Claude Code enforces them. The order, strongest first, is: managed → command line → project local → shared project → user. For a single-value key, the stronger source wins. Lists, such as permission rules, are combined. After combining, an allow rule still does not cancel a matching deny. Some keys have their own exceptions; check them in the reference.

~/.claude.json is a different file. Claude Code itself writes it, to store state such as folder-trust decisions, MCP configurations, and global preferences. It is not another level of settings.json. A project file named claude.json is also not the project version of it. Use Claude Code’s own commands to change it, instead of editing it by hand. Official settings documentation↗.

MCP configuration: scope is not the same as file location

The surprising part: Local-scope MCP configuration for a project lives in a file in your home folder. But local runtime settings for a project live in .claude/settings.local.json. So “local” says who the entry applies to (you, in this project). It is not one fixed filename. If two scopes define an MCP server with the same name, local wins over project, and project wins over user. Managed restrictions still apply on top. To view or manage connections, use claude mcp list, claude mcp get <name>, and the --scope option of the MCP commands. Official MCP scope documentation↗.

Three hierarchies to keep separate

Inside Claude Code, use /memory to find instruction files and /context to see what is loaded in the context. Use /config and /status to see settings and where they came from, and /mcp to see server status. A plain Messages API call from your own app does not load any of these Claude Code files. In an Agent SDK application, your code sets options that control what it loads.

Continue with tool availability and permission examples and whether an agent loads CLAUDE.md.

Recall: Markdown guides the model. Settings configure the runtime. Hooks run checks. MCP configuration connects servers. .claude.json is state that Claude Code stores for itself; it is not “project settings with a different name.” Documentation checked September 22, 2026; the examples use the standard locations.

CLAUDE.md — the memory hierarchy

🧭 Your role here: Claude Code comes with the harness (the software that runs the agent) already built. So your job as architect moves up one level: you write the standing setup that every session starts from. With CLAUDE.md, you set context and rules once, and every future session gets them (guidance). With skills, you package expertise. With hooks, you make rules run the same way every time (enforcement). With settings, you draw the permission boundary (enforcement). In Domain 2, "configuring a tool" and "designing a system" turn out to be the same work.

flowchart TD
  U[User CLAUDE.md] --> C[Combined model instructions]
  P[Project CLAUDE.md, checked in] --> C
  N[Nested CLAUDE.md, loaded when relevant] --> C
  E[Managed settings] --> R[Runtime configuration and enforcement]
  C --> M[Model proposes action]
  M --> R

Managed settings are runtime configuration. They are not part of the Markdown memory ladder. An organization's instruction files still only guide the model. Managed configuration can enforce the controls that Claude Code supports. Do not put these two mechanisms into one precedence diagram.

• Claude Code loads these files automatically when the session starts. For memory, all loaded files are combined into one set of instructions. The narrower file (project, then nested) is meant to guide behavior for its part of the folder tree. This is only a weighting of context. It is not the strict, fixed > chain that decides settings and permissions (that strict chain is explained under Permissions below). When instructions conflict, do not assume that the more specific one will reliably win. Remove the conflict. For rules that must be enforced, add a check that runs code.
• What belongs there: build and test commands, architecture conventions, style rules, and repo habits. These are long-lasting instructions, not prompts for one task.
• Keep it short, and write commands ("Run the tests"), because every token loads into every session. Do not paste long documents into it. Instead, use @path imports: an @ followed by a file path (e.g. @docs/architecture.md) adds that file to the loaded instructions. The imported file still uses context space.
• In Claude Code, # at the start of a message adds a memory quickly. /memory edits memory files. /init creates a first CLAUDE.md for a repo.

🎯 Scenario 2 (team code generation — one of the six scenarios) often asks about precedence. For permissions (enforced): enterprise policy > project settings > user settings. For memory (guidance): the project CLAUDE.md covers the repo, while ~/.claude/CLAUDE.md goes with the person. Shared standards → project file in git. Personal preferences → user file.

🧭 Each layer here is a real file you can click, below — the layers as real files.

Team instructions versus enforced naming rules

Why the checked-in rule did not guarantee compliance

A team naming rule in the repository feels like it should beat a developer's personal preference. That is a fair expectation, because the team owns the repo. But sharing a rule and enforcing a rule are different things. Git shares the file. Claude Code loads the matching instructions. The model must still follow them when it writes code. When a personal instruction conflicts with the team's, the generated code can follow the wrong one.

The filename is CLAUDE.md, not cloud.md. Once the model has already produced a wrong name, the question changes. It is no longer "which Markdown file shares the convention best?" It is "how do we make sure a wrong name cannot be accepted, even when the model follows the wrong preference?" Keep the convention in the team's CLAUDE.md (guidance). Add enforcement that runs code. Only moving the text to another file is not enough.

Three mechanisms, three different jobs

flowchart TD
    U[Personal CLAUDE.md instructions] --> C[Model context contains instructions]
    P[Team CLAUDE.md instructions] --> C
    C --> G[Model proposes Java changes]
    S[Effective settings configure hooks and permissions] --> H[Runtime checks the operation]
    G --> H
    H --> V[Run naming validator on relevant code]
    V --> PASS[Compliant change can proceed]
    V --> FAIL[Violation: reject or request repair]
    PASS --> CI[Required CI check before merge]

Worked example: refactoring, tests and test files

One team has five rules. Each rule goes to the mechanism whose promise matches how strict the rule is. All of these are Claude Code files in the repo.

1 · CLAUDE.md: context the model reads and weighs

# Checkout service

## How we work
- Refactor in small, reviewable steps. Keep public API names stable.
- Propose a plan and wait for approval before changing more than 10 files.
- Run the test suite with `npm test` (vitest; tests live in tests/).
- Fix the code, not the test: existing tests are the specification.
  (A hook enforces this, so an edit to an existing test is rejected.)

2 · .claude/settings.json: what may run at all, plus hook registration

{
  "permissions": {
    "allow": ["Bash(npm test)", "Bash(npm run lint)"],
    "deny": ["Bash(git push origin main*)", "Bash(git push --force*)"]
  },
  "hooks": {
    "PreToolUse": [
      { "matcher": "Edit|Write", "hooks": [{ "type": "command", "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/protect_tests.py\"" }] }
    ],
    "PostToolUse": [
      { "matcher": "Edit|Write", "hooks": [{ "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" }] }
    ]
  }
}

3 · .claude/hooks/protect_tests.py: the rule that needs logic

import json
import os
import sys

call = json.load(sys.stdin)                      # the pending tool call, sent by Claude Code
path = call.get("tool_input", {}).get("file_path", "")
is_test = "/tests/" in "/" + path.lstrip("./")
if is_test and os.path.exists(path):
    print("Existing tests are the specification: fix the code, not the test. "
          "New test files are allowed.", file=sys.stderr)
    sys.exit(2)                                  # exit code 2 = block; stderr goes back to Claude
sys.exit(0)                                      # anything else proceeds

What happens when Claude tries each action

Look for the strength word in the exam question. "Prefer", "convention", "explain how", "our commands are" → CLAUDE.md (guidance). "Must never", "guarantee", "compliance", "every time" → settings (which tool or command may run) or a hook (a condition that needs logic, or an action after every edit) (enforcement). If a rule is only in CLAUDE.md and "it happened anyway", move the rule into enforcement and keep the explanation in CLAUDE.md.

Read the filenames before applying a hierarchy

CLAUDE.local.md and settings.local.json are different files. If you move Markdown into CLAUDE.local.md, it does not gain the fixed, enforced behavior of settings.local.json. Loaded instruction files only add context. There is no guaranteed “last file wins” rule that safely settles conflicting instructions. Official memory documentation↗

Overlay versus union: which operation is happening?

For normal settings conflicts, the general order is managed → CLI → project-local → shared project → user. “Project-local” means .claude/settings.local.json. It does not mean the user file ~/.claude/settings.json, which applies to all projects. Some keys have exceptions; check each key.

Overlay (one value replaces another): When two scopes set the same single-value key, the value from the stronger scope applies. Other keys from the weaker scope stay. For example, a project spinnerTipsEnabled: false beats a user true, unless a stronger scope also sets it.

Union (lists are added together): Normal permission lists collect entries from every scope; one list does not replace another. Collecting the rules is one step. Deciding whether one action is allowed is a second step. An allow entry never gets around a matching deny.

Instructions add up: Claude Code combines the loaded Markdown text into the model's context. This is not value replacement, and it is not a permission check that code runs. Do not call all three behaviors just “the hierarchy.” Settings precedence and list merging↗

Simulate the Java naming example

Suppose the team requires Java class names like InvoiceService, but a personal instruction prefers invoice_service. These names are illustrative.

1. The model sees the team convention, but it still writes class invoice_service.
2. A configured Java linter checks the new code against the team's class-name pattern and reports a violation.
3. Someone must fix the change before a required acceptance check can pass. Claude can write the fix, or a person can.
4. The same check runs in CI, so edits made outside Claude Code are also checked before merge.

The design works because bad output is rejected. It does not work by making the model unable to produce bad output. For generated code, “guaranteed on every run” should mean this: the violations that the check covers cannot pass the enforced gate. It does not mean every draft along the way is correct.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash \"$CLAUDE_PROJECT_DIR/scripts/check-java-names.sh\""
          }
        ]
      }
    ]
  }
}

#!/usr/bin/env bash
# scripts/check-java-names.sh — PostToolUse hook; event JSON arrives on stdin
set -euo pipefail

file=$(jq -r '.tool_input.file_path // empty')
[[ "$file" == *.java ]] || exit 0                  # not a Java file: nothing to check

cd "$CLAUDE_PROJECT_DIR"
# Checkstyle exits non-zero when it finds violations.
if ! report=$(java -jar tools/checkstyle.jar -c config/checkstyle/naming.xml "$file" 2>&1); then
  {
    echo "Java naming rules failed for $file. Fix these names:"
    echo "$report" | grep -E '\[(ERROR|WARN)\]' | head -20
  } >&2
  exit 2                                            # exit 2: stderr is shown to Claude
fi
exit 0                                              # clean: Claude continues normally

PreToolUse or PostToolUse? May the bad change happen at all?

The example above uses PostToolUse. It lets Claude write the file, then finds bad names and asks Claude to fix them. That fits when a bad change may exist for a moment and get fixed. When the rule is "this must never be created", you need the hook that runs before the write.

Memory hook: Pre = the gate (stops it). Post = the cleanup crew (reacts to it). Both are enforced code. They differ only in when they run, and only Pre can stop the action.

#!/usr/bin/env bash
# PreToolUse hook (matcher: Write). Blocks migration files with a bad name BEFORE they are written.
file=$(jq -r '.tool_input.file_path // empty')
[[ "$file" == */db/migration/* ]] || exit 0                  # not a migration: allow
name=$(basename "$file")
if [[ ! "$name" =~ ^V[0-9]+__[a-z0-9_]+\.sql$ ]]; then
  echo "Blocked: '$name' does not match V<number>__<lower_snake_case>.sql (e.g. V3__add_table.sql). Use that format." >&2
  exit 2                                                      # 2 = block; stderr goes to Claude
fi
exit 0

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          { "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/check-migration-name.sh" }
        ]
      }
    ]
  }
}

Decision rule — where a rule must live to be enforced:

• Copying the convention into every user's CLAUDE.md spreads more text that people must maintain. It still depends on the model following instructions. It is a weak way to share a team standard.
• Moving it into CLAUDE.local.md moves a shared convention into a personal file. “Local” does not give any enforcement power. Adding instructions later does not turn them into a checker.
• Leaving it in the repository-root CLAUDE.md because it “wins” is the right place to document the rule, but for the wrong reason. Nothing about that location guarantees that it beats personal text. Keep the team instruction, and add a check that runs code.
• Settings that register a hook which runs a real validator is the enforcement path. Settings must configure a supported control, and the hook must run a real checker. No general settings key means “all Java names obey this sentence.” For strong acceptance, add the same checker to the required CI checks.

Mental model: Git makes a file available to teammates. Loading makes the file visible to the model. A validator decides whether the real code follows a rule that someone implemented. A required gate decides whether that result can be accepted.

Continue with hook registration and script location, settings precedence, and hooks.

Does this agent load CLAUDE.md?

“Agent” describes behavior. The runtime decides how instructions are loaded. A coordinator is a role an agent plays; it is not the name of an API. A research coordinator can run inside Claude Code, use the Claude Agent SDK, or be your own Python loop around the Messages API. All of them call the model in the end, but the software around the model is different.

The filename is CLAUDE.md, not cloud.md. It can hold research steps, client preferences, or instructions for one project. It is not only for general coding rules.

flowchart TD
    R["Coordinator: a role"] --> A["Custom Messages API application"]
    R --> B["Claude Code or Agent SDK runtime"]
    A --> C["Application assembles system and messages explicitly"]
    B --> D["Runtime loads applicable instructions and assembles context"]
    C --> M["Model receives request content"]
    D --> M

The exact clue in the coordinator question

The clue is a given fact in the question, such as “the research coordinator's CLAUDE.md defines the default research methodology.” A sentence like that tells you the system already loads that file. Guidance from files is already working. So the runtime acts like Claude Code's hierarchy of instruction files, not like a plain API call that ignores files. Read the sentence as a fact about the loader, even when the question never names the runtime.

Do not use the shortcut “CLAUDE.md is mentioned, so it must apply.” Another scenario can describe a custom service that never loads the file; there, the honest answer is no. Find the loader the question states, or the behavior that already exists. When the question establishes guidance from files, nested CLAUDE.md files scoped to folders are the matching mechanism. When it does not, first ask which runtime the system uses and how it loads instructions. Only then choose a file.

research/
  CLAUDE.md
  clients/
    acme/
      CLAUDE.md

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="Research the commissioned Acme report using this workspace's guidance.",
        options=ClaudeAgentOptions(
            cwd="/absolute/path/research/clients/acme",
            setting_sources=["project"],
            system_prompt="You coordinate evidence-based research. Identify unsupported claims.",
            max_turns=5,
        ),
    ):
        print(message)

# Illustrative SDK call; requires an installed/configured SDK and real workspace.
# asyncio.run(main())

import json

# In a service, choose these from trusted configuration using authorized client identity.
default_rules = "Coordinate evidence-based research. Cite the sources used."
client_rules = "For this Acme report, use APA 7 and peer-reviewed sources only."
request = {
    "model": "YOUR_SUPPORTED_MODEL_ID",
    "max_tokens": 1500,
    "system": default_rules + "\n" + client_rules,
    "messages": [{
        "role": "user",
        "content": [{"type": "text", "text": "Prepare an outline for the commissioned remote-work report."}]
    }]
}
print(json.dumps(request, indent=2))

import os

import anthropic

from app.config import rules_for_client  # your trusted config or database lookup

MODEL = os.environ.get("CLAUDE_MODEL", "claude-sonnet-5")
client = anthropic.Anthropic()  # reads ANTHROPIC_API_KEY; never a key in code


def outline_report(client_id: str, task: str) -> str:
    """client_id comes from the authenticated session, never from the prompt text."""
    rules = rules_for_client(client_id)
    response = client.messages.create(
        model=MODEL,
        max_tokens=1500,
        system=rules.default + "\n" + rules.client_specific,
        messages=[{"role": "user", "content": task}],
    )
    if response.stop_reason == "refusal":
        raise RuntimeError("The model declined this request; route it to a person.")
    if response.stop_reason == "max_tokens":
        raise RuntimeError("The outline was cut off; raise max_tokens or ask for less.")
    return "".join(block.text for block in response.content if block.type == "text")

Why the other choices felt plausible

There are three other options besides a nested client folder. Each has a real idea in it, and each has a limit.

A client brief in the user message. Sending the client's rules in the user message works. It fits a custom API service or a one-time request well; the custom-API route above does exactly this. Its limit is reuse: you must send the brief again every time. And a Markdown file is not more “enforced” than a message. Both are instructions that the model reads and interprets.

A command-line flag that loads a file. Loading extra instructions at start-up sounds reasonable. But --append-config is not a documented Claude Code feature, and a flag that looks real is not proof that it exists. Claude Code does document --append-system-prompt-file, which adds a file to the system prompt. That is a different mechanism from the hierarchy of project instruction files. CLI reference↗.

An if-sentence in the root file. “If the client is Acme, use APA 7” can guide the model. But it is not configuration logic that runs, and it puts client details into the shared root file. Scoping by folder gives a cleaner split. It is still not the only possible design.

Remember the difference: “coordinator” tells you the agent's job. “Claude Code / Agent SDK / custom API harness” tells you who loads the instructions. Guidance versus enforcement.

Scope: these files are loaded by the agent runtime

This domain is about Claude Code configuration. A custom refund agent that you build on the Messages API does not get this file-loading behavior automatically. A deployed application built on Claude Code or the Agent SDK may use it; that depends on how the runtime is configured. Compare runtimes, explicit file loading, and enforced rules. In every runtime, written instructions (guidance) are different from permission checks that code enforces.

Permissions & settings precedence

• In Claude Code, permission rules decide whether a tool call runs. They are listed in .claude/settings.json under permissions.allow / permissions.deny. Read the Tool(pattern:*) syntax as "this tool, but only for calls that match this pattern". Bash(npm run test:*) means the Bash tool, limited to commands that start with npm run test. * is the wildcard.
• To deny a pattern, put it in the deny list. Claude Code reads this file at start-up and enforces it in every session. For example, this blocks Claude from reading sensitive files:

{
  "permissions": {
    "allow": ["Bash(npm run test:*)"],
    "deny": ["Read(~/.zshrc)", "Read(.env*)"]
  }
}

Real file: cookbook:skills/.claude/settings.json — a real project settings file (it uses the old hook format; see the note below).

• Precedence (strongest first): enterprise managed policy > CLI flags > local project settings > shared project settings > user settings.
• 🧭 Why this order confuses people who know CSS: the lower four layers ARE a specificity cascade (the layer closest to this moment wins — user < project < local < CLI). But the top layer is a hard limit, not a default. Managed policy always beats specificity. Specificity wins — until policy sets a limit. And the limit applies per KEY, never to a whole layer. If managed policy sets a single-value key, policy owns that key completely (lower layers cannot choose a different value). Permissions can only get stricter. Keys that policy does not set cascade normally. So in one Claude Code run, your CLI flag can win model while permissions stays limited by policy. For a layer-by-layer explanation, see the settings-precedence card. Watch the merge in the diff-style cascade.
• --dangerously-skip-permissions exists for containers and CI. The exam answer is to use narrow allowlists instead wherever possible.
• Protecting sensitive files: put secrets (.env, keys) on the deny list, so Claude Code blocks every read of them.

The layers as real files — annotated, clickable

💡 Everything above describes the layers. This section lets you open them. The </> chips go to the claude-cookbooks repo (a real example of the hierarchy — it really has nested memory and a .claude/ toolbox).

Memory (CLAUDE.md) — which instructions are loaded

Enterprise memory — for the whole organization, installed by IT through MDM (device management), read-only for users (a static example — most personal machines have none, and you can check: ls "/Library/Application Support/ClaudeCode/")

# Acme Corp — engineering-wide Claude instructions   <!-- IT deploys this file; devs can't edit it -->
- Never paste customer PII into prompts; reference records by internal ID only.
- All generated code follows the Acme secure-coding checklist (wiki/SEC-101).
- Outbound network calls in examples must use the corporate proxy hostnames.

Real file: no public example — an organization's policy never lives in a public repo.

~/.claude/CLAUDE.md — user memory · personal · every project you open (guidance)

# My global instructions            <!-- travels with YOU, not the repo -->
- Prefer uv for Python; never install a duplicate runtime.
- All web UIs default to the zen-light theme.

Real file: no public example — user memory is always personal.

<repo>/CLAUDE.md — project memory · committed · every teammate's session (guidance)

# acme-billing-agent                <!-- travels with the REPO -->
- Run tests with `npm run test:unit` (never plain `npm test` — it hits staging).
- Money amounts are integer cents everywhere. No floats. Ever.

Real file: cookbook:CLAUDE.md — the project memory at the cookbook's root.

<repo>/billing/CLAUDE.md — nested memory · loaded when working under billing/

# billing/ conventions              <!-- instructions for this subtree; not enforced settings -->
- Ledger writes go through `postEntry()` — direct INSERTs break replayability.

Real file: cookbook:skills/CLAUDE.md — nested memory for one folder tree · cookbook:managed_agents/slack/CLAUDE.md — memory for one sub-project; there are five of them in one repo.

Settings — the same key at three layers, and who wins

// /Library/Application Support/ClaudeCode/managed-settings.json — MANAGED POLICY (static example)
// Deployed by IT via MDM. WINS OVER EVERYTHING below — users cannot loosen it, only tighten.
{
  "permissions": {
    "deny": ["Read(.env*)", "Read(**/*.pem)",        // secrets unreadable org-wide
             "Bash(curl:*)", "Bash(wget:*)"],        // no ad-hoc exfil channels
    "ask":  ["Bash(git push:*)"]
  },
  "forceLoginMethod": "console",                     // org API billing — no personal claude.ai logins
  "forceLoginOrgUUID": "3f1a…-org-uuid",             // and only THIS org
  "disableBypassPermissionsMode": "disable",         // --dangerously-skip-permissions is dead here
  "env": { "HTTPS_PROXY": "http://proxy.acme.internal:8443" }
}

Real file: no public example — a managed policy is always private to the organization.

# CLI flags — one rung below managed policy, above every settings file (per invocation)
claude -p "run the release checks" \
  --model claude-opus-5 \
  --allowedTools "Bash(npm run test:*)"   # adds preapproval for this run; does not override a deny

// ~/.claude/settings.json — USER: yours, every project
{
  "model": "claude-sonnet-5",                    // ← your personal default…
  "permissions": { "allow": ["Bash(git status)"] },
  "hooks": {                                      // deterministic control — fires regardless of prompts
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{ "type": "command", "command": "./guard.sh" }]
    }]
  }
}

{
  "model": "claude-sonnet-5",
  "permissions": { "allow": ["Bash(git status)"] },
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{ "type": "command", "command": "bash \"$HOME/.claude/hooks/guard.sh\"" }]
    }]
  }
}

#!/usr/bin/env bash
# ~/.claude/hooks/guard.sh — PreToolUse hook for the Bash tool; event JSON on stdin
set -euo pipefail

cmd=$(jq -r '.tool_input.command // empty')

# Shapes a deny pattern misses: they can sit anywhere inside a compound command.
risky='rm -rf (/|~)|git push (--force|-f)|curl [^|]*\| *(ba)?sh'
if grep -Eq "$risky" <<<"$cmd"; then
  echo "guard.sh blocked: this command matches a risky pattern. Ask the user to run it by hand." >&2
  exit 2                                    # the Bash call does not run
fi
exit 0                                      # everything else follows the normal permission rules

Real file: no public example — user settings are always personal.

// <repo>/.claude/settings.json — PROJECT: committed, shared with every teammate
{
  "model": "claude-opus-5",                      // …overridden here for this repo…
  "permissions": { "allow": ["Bash(npm run test:*)"] }
}

Real file: cookbook:skills/.claude/settings.json — a real project settings file (an example with outdated keys; see below).

// <repo>/.claude/settings.local.json — LOCAL: personal, gitignored, wins over both
{
  "model": "claude-haiku-4-5"                    // …and THIS one wins (managed policy & CLI flags aside)
}

Real file: cookbook:claude_agent_sdk/chief_of_staff_agent/.claude/settings.local.json — a .local file that was committed. Notice the bad pattern: this layer is designed to stay out of git, but here it is in git, and everyone who clones the repo gets it.

The chain, strongest first: managed policy → CLI flags → settings.local.json → project settings.json → user settings.json. This is the table above, now shown with real files.

🪤 An example that is out of date — read it carefully: cookbook:skills/.claude/settings.json is a real settings file, but its format is old or non-standard. contextFiles and projectInfo are not Claude Code settings keys, and its hooks do not have the matcher/hooks nesting shown in the settings file examples. Good exam practice: find what a validator would reject. The rest of the .claude/ toolbox there is standard: cookbook:.claude/commands/review-pr.md — a slash command · cookbook:.claude/agents/code-reviewer.md — a subagent definition · cookbook:.claude/skills/cookbook-audit/SKILL.md — a skill.

At a glance

💡 The last column lets you open each layer, not only read about it: every chip is a real file. Public chips link to the claude-cookbooks repo at a fixed commit.

Skills vs slash commands vs subagents — the discriminator

How the current product separates them: A user can start a skill by typing /name, or the model can select it, depending on how the skill is configured. Custom commands and skills now use the same invocation system. Older .claude/commands/ files still work. So “skill” and “slash command” can be the same thing. A subagent is different: it is a separate context where work runs. Official extension guide↗.

These three mechanisms, and the exact lines between them, are correct as of mid-2026 — check current docs. Claude Code's configuration options keep changing.

🧭 What the official words mean: The docs and the exam say skills are “model-invoked”. That means the model chooses the skill. It reads each skill’s description and decides that one fits, exactly as it picks a tool from tools[]. It never means that the model runs it. The model cannot act by itself here either. It selects, and Claude Code (the harness in your terminal) performs the call. This is the same split of work as the tool-use handshake. Hooks are the other end: nobody chooses them at run time. The harness runs them on events, the same way every time.

🪤 Trap: "The team keeps pasting the same 20-line release-checklist prompt" → slash command. "The team wants Claude to know the deployment procedure whenever deploys come up" → skill. "Code review uses up the main session's context" → subagent.

Who invokes a skill and who runs it?

When you type /go-live, which file wins?

You normally type /go-live, not /skill go-live or /command go-live. The name after / is the command name. Claude Code looks up that name among the loaded definitions. The model does not guess which file wins.

.claude/skills/go-live/SKILL.md   → /go-live (skill)
.claude/commands/go-live.md       → /go-live (legacy command)

If both define go-live: the SKILL wins.
If only the legacy command exists: that command runs.

/go-live production
 └ name   └ argument text passed to the selected procedure

The slash is only the way you call something. It is not a separate kind of stored file. When enterprise, personal and project skills have the same name, the order is enterprise > personal > project. Plugin skills use /plugin-name:skill-name. These rules only decide which name wins; the rules about who may invoke still apply. If you want both procedures available, give them different names.

See Claude Code’s name-conflict rules↗.

Who invokes it? Follow the request through three owners

You give the goal. Either you name a skill directly with /name, or the model picks an available skill that fits your words. Claude Code (the application around the model) loads the skill. The model then follows its instructions and asks for tools. Claude Code runs the tool calls that are permitted and returns the results. A skill is a set of instructions. It is not a Python thread and not a deployment service.

YOU: “Review my changes.”
  ↓
CLAUDE: selects the review-changes skill
  ↓
CLAUDE CODE: loads its SKILL.md instructions
  ↓
CLAUDE: requests a tool to read the diff
  ↓
CLAUDE CODE: checks permissions and runs that tool
  ↓
CLAUDE: reads the result and explains the review

This sequence explains the flow. It is not a raw Messages API payload. The Skill tool and slash-command handling are part of Claude Code. A custom app built on messages.create must build or add its own way to load skills.

Four situations: direct invocation, automatic selection, suggestion, execution

Full file: both user and model may invoke this skill

Illustrative .claude/skills/review-changes/SKILL.md. Neither invocation-control field is set, so the default behavior applies. This file only illustrates the example; it is not an installed skill.

---
name: review-changes
description: Review uncommitted code changes when the user asks for a review or asks what changed.
---
Read the current diff using an available permitted tool.
Explain what changed and identify specific defects with file locations.
Do not modify files.

You can type /review-changes. You can also ask “Are there problems in my changes?”, and the model may pick it. The description helps the model pick it. The body explains the work after it loads.

Full file: a deployment skill invoked only by the user

Illustrative .claude/skills/go-live/SKILL.md for a team that wants only an explicit slash command to start it. This is a different configuration. It is not a change to this repository’s real deployment skill.

---
name: go-live
description: Deploy the reviewed application to production.
disable-model-invocation: true
---
Use the project’s documented deployment procedure.
Check the selected environment and required approvals before deployment.
Verify the deployment result and report failures accurately.

Type /go-live to start this version. The model cannot start this skill by itself from a normal “go live” sentence. It can suggest that you type /go-live. This setting controls who can start the skill. Permission to really deploy is still decided by the runtime and the deployment system.

Invocation switches: read the flag literally

Your “go live” example: what caused it to start?

Suppose the description says “Use when asked to ship, deploy, or go live”, and model invocation is on. Your sentence gives the intent, and the model chooses the procedure. So both of you take part: the user asked for the result, and the model picked the matching skill. With /go-live, you choose the procedure directly. With disable-model-invocation: true, you must use the slash command.

context: fork changes where the instructions run: inside a separate subagent context. It does not decide whether the user or the model picks the skill. Putting scripts next to SKILL.md does not run them. A script runs only through a defined mechanism, such as a tool call or a command expansion that you configured explicitly.

Are slash commands and skills different things?

A custom /name can be the way into a skill. Current Claude Code merges custom command templates and skills; older .claude/commands/name.md files still work. Do not conclude “only the user can start it” just from the words slash command. Check the invocation settings of the custom skill behind it. Built-in commands such as /help are a separate group. Do not assume every slash command is a skill that the model can pick.

Remember: USER gives the goal → USER or MODEL picks the skill → CLAUDE CODE loads it → MODEL asks for actions → CLAUDE CODE runs the permitted tools.

Read the current Claude Code rules for starting skills↗. The same worked examples are in the skill glossary dialog and the slash command glossary dialog.

Skill frontmatter — the three options the exam names

SKILL.md files start with YAML frontmatter. This is the config block that the harness (Claude Code) reads. The body below it is what the model reads (open the term for all the parts). These fields affect where the skill runs, which tools are pre-approved, and the hint shown for the command:

Project skills live in .claude/skills/ (shared through git). Personal versions go in ~/.claude/skills/ with a different name, so they do not hide the team's version.

Skill or agent? — packaging a procedure like “go live”

The table above separates the mechanisms. Here is the question you really face: my team has a stage-it / ship-it / go-live procedure — should it be a skill or an agent? The answer is to combine them, not to choose one:

---
name: go-live
description: Use when asked to ship, deploy to production, or "go live".
context: fork                 # the WHOLE procedure runs in a disposable context…
agent: general-purpose        # …executed by this agent (or a separately configured deploy agent)
allowed-tools: Bash, Read
---
1. Run `scripts/ship.sh "<message>"` and wait for it to finish.
2. Verify the live URL returns 200.
3. Report back ONLY: commit shas, deploy URL, and any failure verbatim.

In this example, model invocation is on (the flag that turns it off is missing). So saying “ok, go live” can lead to this: the model matches the description → Claude Code starts the forked agent → the checklist and all build output stay inside that context and end there → your session gets three lines. This repo now has exactly this skill — its frontmatter in git currently leaves out disable-model-invocation. So the model may pick it from a matching request, and /go-live picks it explicitly. Session configuration and permissions still apply to that choice. The bad pattern is to put the procedure inside a deploy agent's system prompt instead. It works through delegation, but the knowledge is locked inside the executor. The main loop cannot see it, other agents cannot share it, and it starts to differ from the team's skill the first time either one is edited.

🧭 This is the same split between knowledge and executor that you already know. CLAUDE.md and skills hold what to do. Agents hold who does it, where, and with which tools. Combine them; never copy one into the other.

Go live: where permissions are stored

Open the complete permission walkthrough in a glossary dialog.

Go live: three permission checks, not one permission inside the skill

Imagine /go-live asks Claude Code to start a GitHub workflow. The workflow deploys an existing container image to a staging Cloud Run service. The skill only describes the procedure (guidance). Three separate systems enforce permissions. Claude Code checks local tool access. GitHub checks the caller. GCP checks the workflow's identity. Passing one check does not give the next permission. This is a design for teaching; it does not describe this repository’s real ship script.

You: /go-live
  → Claude reads the skill and requests Bash
  → Claude Code checks its tool permission settings
  → gh sends a workflow dispatch using its authenticated identity
  → GitHub checks repository/workflow access
  → GitHub applies staging environment protection rules
  → Runner obtains short-lived GCP credentials through OIDC federation
  → gcloud sends the deployment request
  → GCP IAM checks the deployment identity’s resource permissions
  → Workflow reports success or failure; Claude reads that result

Where each setting lives—and who enforces it

1 · Full illustrative skill file: request the workflow, then inspect its outcome

Example .claude/skills/go-live/SKILL.md. Only the user can start this example. It leaves out allowed-tools, so the skill adds no pre-approval of its own. The normal session permission rules still apply.

---
name: go-live
description: Start and verify the staging deployment workflow.
disable-model-invocation: true
---
1. Confirm the target repository and reviewed release ref with the user’s request.
2. Request the command:
   gh workflow run deploy-staging.yml --repo EXAMPLE_ORG/EXAMPLE_REPO --ref main
3. Locate the workflow run for this dispatch; inspect its status and logs.
4. Report success only after the deployment and health verification succeed.
5. If a permission check fails, report which system refused it. Do not change IAM to bypass the failure.

These are instructions for the model (guidance). Claude Code runs the commands the model requests. Stronger words in the prompt cannot fix a missing credential or a failed IAM check. Reading this example does not deploy anything.

2 · Full illustrative Claude Code settings: permission to request a shell action

Example .claude/settings.json. This configuration is for teaching; it does not change your real settings. The rules are examples for single commands, not a complete sandbox policy.

{
  "permissions": {
    "allow": [
      "Bash(git status)"
    ],
    "ask": [
      "Bash(gh workflow run *)",
      "Bash(gcloud run deploy *)"
    ]
  }
}

In a Claude Code session that uses these rules, matching deployment commands need approval first. The rules hold command patterns, not credentials. A skill’s allowed-tools can pre-approve the listed tools, but deny and ask rules still come first. Allowing Bash does not log gh in, does not give a GitHub role, and does not create a GCP IAM binding. When a script wraps commands, check the wrapper too, and also use sandbox and cloud controls. A text pattern is not a complete security boundary.

3 · Full illustrative GitHub workflow: use an already-built image

Example .github/workflows/deploy-staging.yml. It needs GitHub and GCP setup first, plus the environment variables described below. Pasting it alone will not deploy anything. The action tags show major versions so they are easy to read; production workflows should pin reviewed commit SHAs.

name: Deploy staging
on:
  workflow_dispatch:

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: staging
    permissions:
      contents: read
      id-token: write
    steps:
      - uses: actions/checkout@v4
      - name: Obtain a short-lived GCP identity
        uses: google-github-actions/auth@v3
        with:
          workload_identity_provider: ${{ vars.GCP_WIF_PROVIDER }}
          service_account: ${{ vars.GCP_DEPLOYER_SA }}
      - uses: google-github-actions/setup-gcloud@v2
      - name: Deploy the approved image to staging
        env:
          PROJECT_ID: ${{ vars.GCP_PROJECT_ID }}
          IMAGE: ${{ vars.STAGING_IMAGE_DIGEST }}
          RUNTIME_SA: ${{ vars.GCP_RUNTIME_SA }}
        run: |
          gcloud run deploy orders-staging \
            --project="$PROJECT_ID" \
            --region=us-central1 \
            --image="$IMAGE" \
            --service-account="$RUNTIME_SA" \
            --quiet

Store these non-secret IDs as variables of the GitHub staging environment: the provider resource name, the deployer service-account email, the project ID, the fixed image digest, and the runtime service-account email. OIDC federation gives the runner short-lived credentials, so no long-lived GCP key is stored here. id-token: write lets the job ask for a GitHub identity token. It gives no Cloud Run permission. This example stops at deployment. Add health checks for your application before you treat the release as verified.

4 · What must an administrator configure in GCP first?

For the design above, where the workflow acts as a service account, the administrator must set up a trusted GitHub OIDC provider. Only the intended workflow identity may act as the deployer service account. Give that deployer the permissions the deployment needs, such as Cloud Run Developer, and Service Account User on the specific runtime service account. Access to the image, and any registry permissions across projects, must also be set up. The smallest set of roles depends on the job: building an image, creating resources, or only updating an existing service.

These grants live in GCP IAM. The skill does not create them. Neither does the service_account YAML field, or id-token: write. An administrator or platform team creates the trust and the grants. The normal deploy workflow only uses the existing grants. It should not give itself wider roles.

5 · Which system rejected the operation?

What if the skill runs gcloud directly on your laptop?

Then GitHub Actions is not part of that path. Claude Code still checks whether it may run gcloud. The CLI uses the account that is logged in on your machine, or a service account it acts as. GCP checks that identity’s IAM roles. The gcloud CLI login and the Application Default Credentials that SDKs use are two separate configurations. Your laptop login does not move to a GitHub runner automatically.

Recall: SKILL = procedure (guidance). CLAUDE CODE SETTINGS = permission to use local tools (enforced by Claude Code). CREDENTIAL = who is calling. GITHUB/GCP POLICY = what that identity may do (enforced by GitHub and GCP).

References: Claude Code permission rules↗, GitHub OIDC to GCP↗, GCP deployment pipeline federation↗.

CosmicKeys: a real go-live permission trace

Open the full CosmicKeys case inside the glossary.

CosmicKeys: the real go-live flow, traced from repository files

Sources read: the CosmicKeys skill, deploy-prod.yaml, the Terraform bootstrap, and the backend route registration. This shows what the files in git intend. It is not a checked live deployment, and not an audit of live IAM. No workflow was started. The frontend and the backend deploy in different ways.

stage-it → push staging → frontend preview on Vercel
ship-it → merge staging into main → push main
  → GitHub Actions deploy-prod.yaml (matching path changes)
  → build image → deploy green at 0% traffic in US / EU / Asia
go-live → wait for the correct successful green deployment
  → LOCAL gcloud update-traffic → green gets 100% in each region
  → frontend promotion through Vercel CLI when needed
  → verify backend and frontend health

go-live also has a step that merges staging into main and pushes it, which overlaps with ship-it. These are reusable procedures (skills), not three new kinds of agent. Its frontmatter leaves out disable-model-invocation, so by default the model can pick it from normal language. /go-live is the explicit way.

The important distinction: there are TWO GCP callers

Actual workflow trigger and authentication wiring

A short excerpt from .github/workflows/deploy-prod.yaml. The build job and the deploy job both declare the GitHub permissions and login step shown here. Only secret NAMES are shown; the values were not read.

on:
  push:
    branches: [main]
    paths:
      - 'backend/**'
      - '.github/workflows/deploy-prod.yaml'
  workflow_dispatch:
    inputs:
      skip_build:
        type: boolean
        default: false

# Inside each relevant job:
permissions:
  contents: read
  id-token: write
steps:
  - uses: google-github-actions/auth@v2
    with:
      workload_identity_provider: ${{ secrets.GCP_WORKLOAD_IDENTITY_PROVIDER }}
      service_account: ${{ secrets.GCP_SERVICE_ACCOUNT }}

A matching push starts the normal path; workflow_dispatch also allows manual runs. The job gets an OIDC identity and exchanges it through GCP federation. The secret entries hold a provider ID and a service-account ID, not a stored GCP private key. This file does not select a GitHub environment with environment: staging/production. So this workflow does not create the environment approval queue from the earlier illustrative example.

Where CosmicKeys declares the GCP permissions

A short declaration from terraform/bootstrap/main.tf. Terraform describes the policy you want; GCP enforces it after it is applied. This review did not check the current live bindings.

# Federation permits this repository identity to impersonate the deployer.
resource "google_service_account_iam_member" "github_actions_wif" {
  service_account_id = google_service_account.github_actions.name
  role = "roles/iam.workloadIdentityUser"
  member = "principalSet://iam.googleapis.com/${google_iam_workload_identity_pool.github_pool.name}/attribute.repository/${var.github_org}/${var.github_repo}"
}

# Existing repository declaration: broad project-level authority.
resource "google_project_iam_member" "github_actions_owner" {
  project = var.project_id
  role = "roles/owner"
  member = "serviceAccount:${google_service_account.github_actions.email}"
}

The workload identity provider checks the repository owner. The impersonation binding narrows access to the named repository. The Owner grant is very broad. It is not a template for giving only the smallest needed rights. For a narrower design, separate infrastructure administration from normal deployment, and grant only the actions that are needed. A trust rule answers “who may become this identity?”. The project role answers “what may that identity do?”

The local traffic promotion command and its separate permission check

The real command format in go-live. It is shown for learning; it was not run. Matching commands target europe-west1 and asia-southeast1.

gcloud run services update-traffic cosmickeys-production-us-api \
  --region=us-central1 --project=cosmickeys --to-tags=green=100

Claude Code decides whether the local Bash tool may run. Then GCP checks whether the active gcloud identity may update the service. The project flag chooses the target project; it does not give access. The green tag chooses a deployed revision; moving traffic does not build a new image. The skill itself holds neither the gcloud login nor an IAM role.

What to verify before using this as a production template

Read the evidence: which file answers which question?

Credential values, live IAM grants, branch protections, and the active local gcloud identity were not read. The source configuration explains the design. It does not prove that the current account has access.

.claude/rules/ — path-scoped conventions with glob frontmatter

When do rules load? .claude/rules/*.md belongs to the MEMORY family (guidance). Plain topic files load when the session starts, exactly like CLAUDE.md content. Splitting them into files only keeps things tidy; it does not delay loading. Adding paths: frontmatter is what makes a file conditional: it appears only when the files being worked on match the glob. So: split only for tidiness → always loaded. Split with paths: → loaded when relevant.

🧭 “Keep these standing rules” — where do they go? When you tell a session “from now on, always X”, that is a rule (memory), not a skill. The assistant writes it into ~/.claude/CLAUDE.md (global, every project) or into the repo's CLAUDE.md / .claude/rules/ (whole project). Then the HARNESS loads it in every session. Nothing chooses it; it is always in context. A skill works the opposite way: it is a procedure used on demand, and the model CHOOSES it by its description when it fits. A limit you must never forget → rule. A procedure you run sometimes → skill.

One huge CLAUDE.md loads everything into every session. Two mechanisms make that smaller:

• Topic files: split the rules into .claude/rules/testing.md, api-conventions.md, deployment.md. This keeps things organized without one giant file.
• Path-scoped rules: give a rules file YAML frontmatter with glob patterns, such as paths: ["terraform/**/*"] or paths: ["**/*.test.tsx"]. Then it loads only when Claude edits a matching file. Conventions that do not apply stay out of the context, so tokens go to the rules that apply right now.

The difference the exam tests (a pattern from the sample questions): Conventions for a file type found all over the tree (test files everywhere, React components in many folders) → glob-pattern rules. A folder-level CLAUDE.md is tied to one folder and cannot follow a pattern. Conventions for one folder and its subfolders → a nested CLAUDE.md works. Relying on Claude to "work out which section applies" from one big file → always the wrong answer when it is offered.

Real files: the cookbook has no .claude/rules/. The nested cookbook:skills/CLAUDE.md is its only conditional layer.

Watch the merge happen — layered config, git-diff style

Two families of files combine in two different ways. This picture helps you remember precedence. Left: each layer's file (weakest first). Each card's open → chip is a real file: the cookbook example. Right: the effective config as it builds up. Each line shows the layer that won; values that lost are crossed out.

flowchart TB
  subgraph SETTINGS [settings — per-key OVERRIDE, strongest wins]
    U1[user settings] --> M1{merge by key}
    P1[project settings] --> M1
    L1[settings.local.json] --> M1
    MP1[managed policy] -->|always wins| M1
    M1 --> E1[ONE effective value per key]
  end
  subgraph MEMORY [memory — UNION, all load together]
    E2[enterprise CLAUDE.md] --> M2{concatenate}
    U2[user CLAUDE.md] --> M2
    P2[project CLAUDE.md + rules/] --> M2
    N2[nested CLAUDE.md] -->|specificity wins at conflicts| M2
    M2 --> EF2[ALL lines in context]
  end

Settings (enforced by Claude Code) — each key is overridden separately. Watch model change owner three times, permissions.deny arrive and stay fixed, and the allow list grow:

{"mode":"override","layers":[
 {"name":"user","file":"~/.claude/settings.json","entries":[
   {"k":"model","v":"claude-sonnet-5"},{"k":"permissions.allow[git]","v":"Bash(git status)"},{"k":"hooks.PreToolUse","v":"guard.sh"}],
  "note":"yours, every project — the weakest layer"},
 {"name":"project","file":"<repo>/.claude/settings.json","pub":"cookbook:skills/.claude/settings.json","entries":[
   {"k":"model","v":"claude-opus-5"},{"k":"permissions.allow[test]","v":"Bash(npm run test:*)"}],
  "note":"committed — every teammate inherits"},
 {"name":"local","file":"<repo>/.claude/settings.local.json","pub":"cookbook:claude_agent_sdk/chief_of_staff_agent/.claude/settings.local.json","entries":[
   {"k":"model","v":"claude-haiku-4-5"}],
  "note":"personal, gitignored — beats both below it"},
 {"name":"managed","file":"/Library/…/managed-settings.json","entries":[
   {"k":"permissions.deny[env]","v":"Read(.env*)"},{"k":"disableBypassPermissionsMode","v":"disable"}],
  "note":"IT's layer — nothing below can loosen it"}]}

Memory (guidance) — combined context. The matching instruction files are read together. No fixed “last file wins” algorithm settles conflicting text, so keep the instructions consistent. The picture shows which instructions are present. It does not guarantee enforcement:

{"mode":"union","layers":[
 {"name":"enterprise","file":"/Library/…/ClaudeCode/CLAUDE.md","entries":[
   {"k":"org","v":"never paste customer PII"}],
  "note":"MDM-deployed, read-only"},
 {"name":"user","file":"~/.claude/CLAUDE.md","entries":[
   {"k":"style","v":"prefer uv for Python"},{"k":"ui","v":"zen-light theme by default"}],
  "note":"travels with YOU"},
 {"name":"project","file":"<repo>/CLAUDE.md","pub":"cookbook:CLAUDE.md","entries":[
   {"k":"tests","v":"npm run test:unit (never plain npm test)"},{"k":"style","v":"THIS repo uses poetry","conflicts":false}],
  "note":"travels with the repo — note style now has TWO lines loaded"},
 {"name":"nested","file":"<repo>/billing/CLAUDE.md","pub":"cookbook:skills/CLAUDE.md","entries":[
   {"k":"billing","v":"ledger writes via postEntry() only"}],
  "note":"joins when working under billing/ — adds local guidance; reconcile conflicting prose"}]}

⚠️ That enterprise line — “never paste customer PII” — is only advice, like all memory. The rule and an accidental paste reach the model in the same context. So the rule cannot prevent the data from being exposed; it can only guide behavior afterwards. Real prevention is code that runs the same way every time, BEFORE the call: the PII boundary.

🧭 The exam difference inside these two pictures: a single-value setting ends up with one value; lists and permissions have their own merge rules (ask “who wins?”). Memory keeps ALL the lines (ask “what is loaded — and which line is more specific?”). Skills and commands have their own rules for names and invocation. Do not guess those rules from how instruction files load.

Beyond the standard mechanisms — the project-map pattern (a house invention)

Everything above sets CONDITIONS on what loads: nested CLAUDE.md (by folder) and paths: rules (by file pattern). This pattern turns the question around. Instead of loading more knowledge under conditions, it always loads a tiny index. The index is a file of about 60 lines: one mermaid diagram of the project's main structure plus a | Need | Location | lookup table. The project launcher (a shell script, not Claude Code itself) adds it to the system prompt when the session starts.

The context numbers show why this is a real pattern, not just a convenience. Without the map, every “where is the deploy script?” costs a search-and-read round trip: 2–6 tool turns. Each turn returns output that enters the context and stays there. Ten questions ≈ thousands of tokens of search output used only once. The map is about 1.5K tokens. It loads once, answers all ten, and keeps exploration read-only. It also survives compaction better than search results: an index compresses well; long find output does not.

🧭 In one line: rules load what the session should KNOW; the map loads what the session can FIND. One gives knowledge up front; the other gives an index up front, so every later lookup is exact. It works together with the standard ladder; it does not replace it. It also needs a refresh skill that rebuilds the map whenever the structure changes (an out-of-date index is worse than none).

Plan mode vs direct execution — and the Explore subagent

Two ways to work in Claude Code, and one rule to choose:

• Plan mode — for tasks that affect the architecture: large changes, many files, several valid approaches, or decisions about service boundaries. Claude explores the codebase and designs an approach before it makes changes. This avoids expensive rework when you discover dependencies in the middle of editing. Typical cases: splitting a monolith into microservices, a library migration that touches 45+ files, or choosing between ways to integrate.
• Direct execution — for small, clear, well-understood changes: a bug fix in one file with a clear stack trace, or adding one validation check. Plan mode here is only extra ceremony.
• How to turn it on: Shift+Tab (cycles default → acceptEdits → plan), /plan before one prompt, claude --permission-mode plan, or "defaultMode": "plan" in .claude/settings.json. Claude reads files and runs shell commands to explore (a command outside the read-only set asks first), but it does not edit your source until you approve the plan. The blocks also hold in -p runs and SDK sessions.
• The combination is valid and appears on the exam: plan mode to investigate and design, then direct execution to build the approved plan.
• The Explore subagent helps you save context. It keeps long discovery output (mapping a large codebase, tracing flows) in its own context and returns only a summary. So a task with several phases does not fill the main window with exploration output.

🎯 "Restructure the monolith — where do you start?" → plan mode: explore before changing (not "start editing and let the boundaries appear"). "One bug fix with a stack trace?" → direct execution. "Discovery output is filling the context window?" → Explore subagent.

Explore, then refactor: two subagents in sequence

The task: find every use of the old v1 payments API, then change each one to v2. Two Claude Code subagents can do this: one explores, one edits. The difficult part is not the editing. It is the handoff: the second subagent knows only what it is given.

What each subagent starts with

Facts from the Claude Code subagent documentation↗:

What comes back: only the subagent's final message. Its file reads, searches and intermediate steps stay in its own context. That is the whole point (the main context stays small), and it is also the risk (details stay behind).

The two definition files

The frontmatter (the YAML between --- lines) configures the agent. The body is its system prompt. There is no output-schema field in the frontmatter. The "structured output" you saw in the course is the Output section in the body: an instruction that defines exactly what to return.

---
name: v1-usage-explorer
description: Finds every use of the v1 payments API. Use before a v1-to-v2 migration. Does not change source code.
tools: Read, Grep, Glob, Write
model: haiku
---
You find every use of the v1 payments API (PaymentsV1Client, /api/v1/payments, PAYMENTS_V1_* settings).
Never change source files. The only file you write is the inventory below.

## Output (the handoff contract)
1. Write the complete inventory to .claude/handoff/v1-usages.json:
   {"commit": "<git rev-parse HEAD>", "total": <n>,
    "usages": [{"file": "src/billing/Charge.java", "line": 42,
                "symbol": "PaymentsV1Client.charge", "kind": "call|import|config|test",
                "note": "retries on timeout"}]}
2. Your final message: the file path, the total, the count per kind,
   and every place you could not classify. Do not retell the list in prose.

---
name: v2-refactorer
description: Migrates v1 payments API uses to v2 from an inventory file. Use after v1-usage-explorer.
tools: Read, Edit, Grep, Glob, Bash
model: sonnet
---
Your task message gives you an inventory file. Read the WHOLE file first.
For each usage, apply the mapping in docs/payments-v2-migration.md. Read the code around a usage before you edit it.
The inventory is a starting point, not proof: before you finish, search again for every v1 symbol
and handle any use the inventory missed. Then run the tests of the modules you changed.

## Output
- Changed files (count and list)
- Inventory items you did NOT change, each with the reason
- Extra uses you found that were not in the inventory
- The test command you ran and its result

Note on enforcement: tools: Write lets the explorer write anywhere. If "writes only the inventory" must be guaranteed, add a permission rule or a PreToolUse hook for that agent. The sentence in the body is guidance only.

Who runs what, and in which order

You ask in the main conversation: "Use v1-usage-explorer to build the inventory, then use v2-refactorer with that inventory file." The docs describe exactly this: subagents used in sequence; each returns its result to the main Claude, which then passes the relevant context to the next one.

Sequential, because of the dependency. The refactorer cannot start before the inventory exists. Parallel where the work is independent: several explorers can scan different modules at the same time. After the inventory exists, several refactorers can each take one module's slice, as long as no two of them edit the same file (isolation: worktree in the frontmatter gives each one its own git worktree). Do not run explore and refactor at the same time on the same code.

Where findings get lost: three hops

Memory anchor: a report is a summary unless you define a contract; a file is the full handoff; a new search is the proof.

Fork, fresh subagent, or no subagent?

Exam rule: if a scenario says the second agent made mistakes "because it did not have the first agent's full findings", the answer is to fix the handoff: define what the first agent returns, store the full result where the second can read it, pass it unchanged, and verify at the end. "Use a bigger model", "tell it to be careful" or "run them in parallel" do not fix missing information. (General coordinator rules: Domain 1, coordinator handoffs.)

What "structured output" means in this domain

The full map of all runtimes: Structured output: which runtime is the question about?

Iterative refinement: getting Claude from "close" to "right"

This is about how you talk to Claude Code during a task. No files are involved. Each technique fixes a different problem, so the exam gives you the problem and asks for the technique.

Normalize phone numbers to E.164. Examples:

  "(415) 555-0123"      → "+14155550123"
  "415.555.0123 ext 9"  → "+14155550123"   (drop the extension)
  "+44 20 7946 0958"    → "+442079460958"  (keep a foreign country code)

Turn 1:  "Write tests for parse_amount(): '12.50' → 1250 cents, '' → error,
          '1,234.5' → 123450, None → error. Don't write the function yet."
Turn 2:  "Now implement parse_amount() so these tests pass."
Turn 3:  (you run the tests) "2 failing:
          test_none_input: TypeError instead of ValueError
          test_thousands_separator: got 1234 (expected 123450)
          Fix only these."

"I need a caching layer for the product API. Before you write any code,
ask me the questions you need answered: what invalidates the cache,
what happens when the cache is down, how stale data may be, and anything
else I might not have thought of."

One message or several? Problems interact when fixing one changes the other. For example, a changed date format breaks the sorting, and the sort decides which rows you deduplicate. Send those together with the full picture, or each fix will undo the last one. Problems that don't touch each other (a typo in a log line, a missing null check in another module) are faster and safer one by one.

Exam cue: the stem names the symptom. "Interpreted inconsistently" → examples. "Edge cases keep failing" → tests and the failure output. "Unfamiliar domain, unknown risks" → interview. "Fixes keep breaking each other" → one combined message.

From solo development to CI and team enforcement

CI means continuous integration: an automated runner checks each proposed code change. A solo developer can use it too. You do not need to remember to run tests in your terminal. A workflow in the repository runs them each time someone opens or updates a pull request. CI is a program; it is not necessarily an agent. CI glossary.

The whole enforcement picture

This diagram keeps two things apart. The first is which settings win inside Claude Code (on your machine). The second is separate checks on the repository server (for example GitHub). The arrows show influence or the next step. They do not show the exact internal order of every permission check.

flowchart TD
    M["1. Admin-managed Claude Code policy"] --> R["Claude Code runtime permissions and hooks"]
    C["2. CLI, local, project, user settings"] --> R
    I["CLAUDE.md and user prompt: model guidance"] --> A["Model proposes a tool call"]
    A --> R
    R -->|Denied| X["Action blocked"]
    R -->|Permitted| W["Working-tree change"]
    H["Other editor or manual terminal"] --> W
    W --> P["Pull request on repository server"]
    P --> T["CI runner: formatting, lint, tests"]
    T --> G["Required checks and reviews"]
    G -->|Fail or missing| B["Merge blocked"]
    G -->|Pass with authorized actor| F["Protected branch updated"]
    K["Runner credentials: repository read only"] --> T

Two separate questions: First, may this agent run a command? Claude Code answers that. Second, may this change enter the protected branch? The repository server answers that. Passing the first check does not pass the second. A person who edits in another editor skips Claude Code hooks completely. But their proposed changes still meet the repository checks.

Where the configuration actually goes

Settings hierarchy: what can a local override change?

The rule is not “the last file wins” for every key. Claude Code combines the permission lists from all layers, and a matching deny beats an allow. So an allow in your local file does not cancel a deny that another layer loaded. But a developer who can edit the project files can also change a normal project policy. So put required Claude Code controls in managed policy (set by an admin). Put rules for the whole repository in server controls (on GitHub). Permission evaluation↗ · Managed deployment↗.

name: Repository checks
on: [pull_request]

permissions:
  contents: read

jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          persist-credentials: false
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
          cache: npm
      - run: npm ci
      - run: npm run format:check
      - run: npm run lint
      - run: npm test

{
  "permissions": {
    "allow": ["Bash(npm test)"],
    "deny": ["Bash(git push *)"]
  }
}

What hooks guarantee, and what they do not

Hooks run real code, but a hook enforces only what its code checks. A lower-level disableAllHooks setting cannot turn off managed hooks. Administrators can also limit where hooks may come from with allowManagedHooksOnly. And the hook scripts themselves must be protected so that nobody can edit them without permission. Hook configuration and managed hooks↗.

For a team: Aim for this guarantee: changes that break the rules cannot enter the protected branch. Do not claim that no developer can ever create a rule-breaking file on their own machine. Administrators, people with bypass rights, and outside credentials are still part of what you must trust.

Recall: Instructions (CLAUDE.md) explain. Hooks check the events they cover. Managed policy limits the agent. CI tests the change. Repository rules block the merge. Credentials limit what can be done on remote systems. Review tool availability versus permission.

Claude Code in CI/CD (scenario 5 — CI/CD automation — territory)

• Headless mode (Claude Code with no interactive UI): claude -p "review this diff" --output-format stream-json works in any pipeline. Exit codes and JSON output let scripts use it.
• GitHub Actions integration: @claude mentions on PRs and issues. The action runs Claude Code on the repo, with a token of limited scope and your CLAUDE.md conventions.
• What the exam asks an architect to think about: tokens with the smallest needed rights, pinning the action and model version, a budget limit per run, and whether Claude's PR feedback is an advisory gate or a blocking gate. A blocking gate needs criteria that give the same result every time (tests, lint), not a feeling. Also: an audit log of what the agent did.
• Headless + hooks + allowlists = the reason you can trust CI. The agent can run only allowed commands, every action is logged, and formatting and tests run the same way after every edit.

GitHub Actions: set it up as an admin, then what happens on each event

The Claude Code GitHub Action (anthropics/claude-code-action) runs Claude Code inside a normal GitHub Actions job. Nothing runs by magic: a workflow file decides which GitHub events start Claude. You need admin access to the repository for setup.

Quick setup (one command)

1. Install the GitHub CLI and run gh auth login.
2. Open claude in the repo and run /install-github-app. It works with github.com repos only.
3. Claude Code installs the Claude GitHub App and saves a repo secret: ANTHROPIC_API_KEY (API key) or CLAUDE_CODE_OAUTH_TOKEN (Claude subscription token).
4. It pushes a branch with the workflow files you picked and opens a pull request. Merge it, and @claude works.

Manual setup (you do each step)

1. Install the Claude GitHub App (github.com/apps/claude) on the repo. The action needs three of its permissions: Contents, Issues and Pull requests, all read and write. Installing the app grants its full permission set; GitHub doesn't let you accept a subset.
2. Add a repo secret: ANTHROPIC_API_KEY (from the Claude Console) or CLAUDE_CODE_OAUTH_TOKEN (run claude setup-token locally). In the workflow, pass it to anthropic_api_key or claude_code_oauth_token.
3. Copy examples/claude.yml from the action's repo into .github/workflows/claude.yml.
4. Test it: write @claude in an issue or PR comment.

Rolling out to a whole organization

• Install the Claude GitHub App once at the org level, for all repos or a chosen list.
• Store the secret as an org-level Actions secret. Use a Console API key here, not an OAuth token, because an OAuth token is tied to one person's subscription.
• Add the workflow file to each repo, or write it once as a reusable workflow that each repo calls.
• No long-lived secret at all: use workload identity federation (GitHub OIDC token → Claude Console service account), with anthropic_federation_rule_id and anthropic_organization_id, plus id-token: write.

name: Claude Code
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
jobs:
  claude:
    if: contains(github.event.comment.body, '@claude')
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      issues: write
      id-token: write
      actions: read
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

name: Code Review
on:
  pull_request:
    types: [opened, synchronize, ready_for_review, reopened]
jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: read
      issues: read
      id-token: write
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          plugin_marketplaces: "https://github.com/anthropics/claude-code.git"
          plugins: "code-review@claude-code-plugins"
          prompt: "/code-review:code-review --comment ${{ github.repository }}/pull/${{ github.event.pull_request.number }}"
          claude_args: '--allowedTools "mcp__github_inline_comment__create_inline_comment"'

What happens when…

On who may trigger: on issue and PR events the user needs write access, unless you list them in allowed_non_write_users (and pass your own github_token). Bots are always rejected unless listed in allowed_bots, so bots can't loop Claude. This bot check also applies to scheduled runs. A schedule skips only the write-access check.

Note. Claude Code in the action reads CLAUDE.md from the checked-out repo, so put your standards there and keep it short (it is read on every run). Settings go in through the settings input (JSON or a file path) or CLI flags in claude_args; secrets live only in GitHub Secrets, never in the repo.

The @claude tag — how a TEAM works with Claude on GitHub

A solo developer works with Claude in the terminal. A team works with it as a teammate you @-mention on GitHub. The parts are the Claude Code GitHub App plus a workflow file committed to the repo. An admin sets it up once; then everyone with write access can use it. Who does what (the actor test, for an organization):

sequenceDiagram
  participant T as Teammate
  participant GH as GitHub (entry point)
  participant A as Action runner — headless Claude Code
  participant API as Claude API
  T->>GH: "@claude fix the null check in checkout.ts" (PR comment)
  GH->>A: webhook fires workflow (author has write access ✓)
  A->>A: checkout repo — CLAUDE.md + .claude/settings.json load (NO user layer in CI)
  A->>API: the loop: read thread + code → tool_use → edits
  A->>GH: pushes commit to the PR branch + updates its checklist comment
  T->>GH: reviews the diff, approves, merges — the human gate

🧭 The YAML holds no behavior. The workflow file controls exactly three things: WHEN it runs (events + the @claude trigger), WHAT it may touch (permissions:), and WHICH secret it uses. Every convention, rule, and skill that the run follows comes from the layers committed in the repo, loaded at checkout. So “will @claude follow X?” always means “is X committed to the repo?”, never “is X in the YAML?”. (And in exam language, “her personal conventions” means ~/.claude/CLAUDE.md — the one layer that no runner ever has.)

The workflow file, with notes (format correct as of mid-2026 — check current docs for exact versions and inputs):

# .github/workflows/claude.yml — committed once; every @claude mention flows through here
name: Claude
on:
  issue_comment:            { types: [created] }   # "@claude" in issue/PR comments
  pull_request_review_comment: { types: [created] }   # …and on PR review lines
  issues:                   { types: [opened, assigned] }
permissions:
  contents: write           # push branches/commits
  pull-requests: write      # open/update PRs
  issues: write             # reply on issues
  id-token: write
jobs:
  claude:
    if: contains(github.event.comment.body, '@claude')   # the tag IS the trigger phrase
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}   # org/repo SECRET — never in the file

“Where do I type claude -p?” — you don't. The three review lanes, demystified

claude -p "review this diff" confuses everyone who works in an interactive session. In YOUR daily work, commits happen inside the session (Claude proposes, you approve), and you never go to a terminal to review. Here is the answer: headless commands are written in YAML, not typed by a person. They live in a committed workflow file, and a RUNNER runs them when events happen. There are three review lanes, and each one is started by someone different:

And here is the team picture that explains why files are committed: teammates commit exactly like you do. Each works in their own session or editor, pushes branches, and opens PRs. The lanes do not replace human review; they add layers under it. A mature setup uses all three. Authors review in the session before pushing (lane 1). The workflow reviews every PR automatically (lane 3). People @-mention Claude on specific lines when they want a conversation (lane 2). And branch protection still requires a HUMAN approval to merge.

🧭 Your ai-partner-review habit (Gemini/Codex/Grok on the same diff) is lane 1 with one extra idea that the exam rewards: a judge from a different model family. It is the same principle as Domain 1's “never grade your own homework”, used for code review. A team would build the same idea as a second workflow in lane 3.

Three points for an architect; each one can come up in an exam or interview:

• The layers, in CI: the runner clones the repo. So the project CLAUDE.md (guidance), .claude/settings.json (enforcement), rules, and skills control the run, and there is no user layer. This is why teams commit their memory and settings: on GitHub, only the repo's layers speak.
• Security uses the same three actors as always: The permission check on the person who comments (write access is required by default) is the gate against random prompt injection through public comments. The API key lives in secrets. And the model still merges nothing; branch protection is the gate that always behaves the same way.
• Tell the two CI forms apart: @claude = interactive, started by a person, shaped like a conversation (a teammate in the thread). The headless claude -p job above = automated, started by an event, shaped like a pipeline. “The team wants to ask Claude to fix review feedback from the PR page” → the tag. “Every merge must regenerate release notes” → headless. Different triggers, same harness.

What actually happens after @claude, step by step, and who reads the JSON

Each step names who acts. The action here is anthropics/claude-code-action (a program that Anthropic publishes; it runs Claude Code through the Agent SDK).

1. A person writes a comment on a PR: @claude fix the null check in checkout.ts. GitHub (the website) saves it and creates an issue_comment event.
2. GitHub Actions (GitHub's job system) finds each workflow file whose on: matches that event. The if: line checks that the comment contains @claude. If it does not, no job starts and nothing is charged.
3. GitHub starts a runner: an empty virtual machine (runs-on: ubuntu-latest). It puts the secret (ANTHROPIC_API_KEY) into the job's environment.
4. The actions/checkout step copies the repository onto the runner (a git clone at the PR's commit). Now CLAUDE.md, .claude/settings.json and the skills are files on that disk.
5. The action checks that the person who commented has write access and is not a bot. Then it posts a "working…" comment (the tracking comment). It collects the context (the comment, the PR title and description, the diff, the earlier comments) and builds a prompt from it.
6. Claude Code, headless, runs the normal agent loop in the checkout folder. It sends a request to the Claude API. Claude answers with tool_use blocks: read a file, edit it, run the tests with Bash. Claude Code on the runner runs each tool on the runner's copy and sends the tool_result back. This repeats until Claude gives a final answer (or --max-turns stops it).
7. The action sends the results to GitHub through GitHub's API, with the Claude GitHub App's token. It commits the changes and pushes them to a branch: the PR's branch, or a new branch for an issue. It updates the tracking comment with a summary. A review workflow can also post inline comments through a tool that the action provides (mcp__github_inline_comment__create_inline_comment).
8. GitHub deletes the runner.
9. People review the new commits like a teammate's work. Branch protection (rules that an admin set) decides whether the merge button works. The action never merges.

🧭 Anthropic also offers Code Review, a managed product: it reviews every PR automatically with no workflow file. It is a different product from this action, and it uses the same Claude GitHub App.

Where is the JSON, and who makes the decision?

With the action, you never handle JSON. The action reads Claude Code's output events itself and turns them into commits and comments. You can see the events in the workflow run log.

With your own claude -p step, your script receives JSON. --output-format json prints one JSON object when the run ends. The answer text is in result (illustrative, fields shortened):

{
  "type": "result",
  "subtype": "success",
  "is_error": false,
  "result": "Found 2 issues: an unchecked null in checkout.ts line 41, and a missing test.",
  "session_id": "3f1c…",
  "num_turns": 6,
  "total_cost_usd": 0.31
}

Add --json-schema and the answer also arrives as an object that matches your schema, in the field structured_output. Now your script, not Claude, turns that object into a decision:

The schema, saved in the repo as .github/review-schema.json (illustrative):

{
  "type": "object",
  "properties": {
    "findings": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "file": {"type": "string"},
          "severity": {"type": "string", "enum": ["critical", "minor"]}
        },
        "required": ["file", "severity"]
      }
    }
  },
  "required": ["findings"]
}

# CI step (illustrative). Claude reports; this script decides.
out=$(gh pr diff "$PR" | claude -p "Review this diff for security bugs." \
  --output-format json \
  --json-schema "$(cat .github/review-schema.json)")

critical=$(echo "$out" | jq '[.structured_output.findings[] | select(.severity == "critical")] | length')
if [ "$critical" -gt 0 ]; then
  echo "Blocking: $critical critical findings"
  exit 1          # non-zero exit code = this CI job fails
fi

So "Claude approved it" is never the real mechanism. The decision is made by code you wrote and rules an admin set. Claude only produces the input to them. That is also why the exam separates an advisory Claude review (comments) from a blocking gate: a blocking gate should rest on checks that give the same result every time (tests, lint), or on a clear, written threshold in your script.

Claude Code GitHub Actions↗ · Run Claude Code programmatically (-p, --output-format, --json-schema)↗.

Start fast and the same on every runner: --bare and the system prompt flags

Normally, Claude Code discovers its configuration by itself. At start-up the harness (the Claude Code program on the runner) looks for CLAUDE.md files and their @imports, hooks, skills, MCP servers and plugins. That is useful on your laptop. In CI it has two costs: start-up takes longer, and the result depends on what files happen to sit on that machine.

--bare turns that discovery off. The Claude Code docs say it reduces start-up time "by skipping auto-discovery of hooks, skills, custom commands, subagents, installed plugins, MCP servers, auto memory, and CLAUDE.md". The docs give the reason: it "is useful for CI and scripts where you need the same result on every machine".

The docs call --bare "the recommended mode for scripted and SDK calls" and say it "will become the default for -p in a future release". (Before v2.1.286 these limits held only partly.)

Append or replace the system prompt? The system prompt is the standing instructions that Claude Code sends to the model with every request. Two flag families change it. Each one also has a -file form that reads the text from a file.

Worked case. The ACME review job is slow to start. The repo's CLAUDE.md has many @imports, but the review needs only one file of review standards. Which command?

# Illustrative CI step. Secret ANTHROPIC_API_KEY is in the job environment.
gh pr diff "$PR" | claude -p --bare \
  --append-system-prompt-file .github/review-standards.md \
  --output-format json \
  --json-schema "$(cat .github/review-schema.json)" \
  "Review this diff against the appended standards."

Two more limits for unattended runs (both print mode only): --max-turns <n> stops the agent loop after n turns and exits with an error. --max-budget-usd <amount> stops the run when the estimated API spend reaches that amount (an estimate on the client, so it can differ from the bill). For permissions, --permission-mode dontAsk is the mode the docs name for CI pipelines, and plan mode keeps its blocks in -p runs too.

Start faster with bare mode↗ · CLI reference: system prompt flags↗.

Hooks — deterministic control (the harness inside Claude Code)

Hook registration versus script location

Open the hook glossary for the same complete examples.

Where is a hook defined? Start with .claude/settings.json

For a hook the whole project shares, put the registration under hooks in .claude/settings.json. Put the program it runs in a separate file, for example .claude/hooks/after_edit.py. CLAUDE.md is instruction text (guidance). Writing “run this after every edit” there does not register anything to run on an event. A script file alone does not register itself either.

1 · Complete settings file: register the event

Example .claude/settings.json. If the file already has settings, add this hooks entry to them; do not overwrite the file. This example watches Write/Edit tool calls that succeeded.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/after_edit.py\""
          }
        ]
      }
    ]
  }
}

hooks is a top-level settings key. PostToolUse chooses the event. matcher chooses the tool names. The inner hooks list holds the handlers. type: command tells Claude Code to start a command. CLAUDE_PROJECT_DIR gives the project folder. This is Claude Code configuration. It is not JSON that you send to messages.create.

2 · Complete script: read the hook event

Example .claude/hooks/after_edit.py. This safe teaching handler reads the JSON it receives on standard input and prints a diagnostic message. It does not format or change the file. Python 3 must be installed where Claude Code runs.

import json
import sys

event = json.load(sys.stdin)
tool = event.get("tool_name")
if tool in {"Write", "Edit"}:
    print("after_edit hook ran after " + tool, file=sys.stderr)
sys.exit(0)

Claude Code sends the event data when the hook runs. The model does not call this Python file itself. Exit 0 means the handler finished successfully. The diagnostic message is not guaranteed to reach the user or the model. Use /hooks to see the registration, and debug output to see whether it ran.

3 · What happens when Claude edits a file?

Claude requests the Edit tool
  → Claude Code applies tool checks and runs Edit
  → Edit succeeds
  → Claude Code emits PostToolUse
  → matcher Write|Edit matches Edit
  → Claude Code launches after_edit.py and supplies event JSON on stdin
  → script reads the event and exits
  → Claude Code continues the agent loop

Claude Code starts this automatically; you do not type the script name after each edit. This matcher does not cover changes made through Bash or by another application. A PostToolUse handler runs after the edit, so it cannot stop that edit. For a check that must block a proposed action, use the PreToolUse event and follow its input/output rules.

See the official hook location guide↗.

Command hooks are Claude Code settings that run programs at events in the session (other hook types also exist). A hook can do one of three things: observe, block (exit code 2, on supported events like PreToolUse), or do extra work (for example, format a file right after a write). The key difference from instructions: code makes these happen (enforcement); they are not polite requests in text (guidance). Timing matters most here. A PreToolUse hook runs before the action and can stop it completely. A PostToolUse hook runs after the action already happened. It can format or test the file that was just written, but it cannot undo the write. Pre or Post? The side-by-side table, with a blocking example.

Exit code 2 from a PreToolUse hook blocks the action and sends stderr back to Claude. That is the enforcement loop.

The full registration and handler above show where hook code belongs. For hooks that block, follow the documented PreToolUse input/output rules. Do not assume that a $FILE variable exists automatically. The hook receives the event data as JSON on standard input.

Check the mechanism: Instructions explain the behavior you want (guidance). Hooks run checks at supported events (enforcement in Claude Code). Permissions and sandbox controls limit actions (enforcement). Check what your hooks really did, and use CI for checks that must cover every change.

Tool availability versus permission: where the lists live

Your API mental model is correct: In a Messages API request, your app sends the tool definitions in tools. The extra allow and deny options belong to the runtime around the model, not to the API request. So first decide which runtime the question is about: Messages API, Claude Code, or Agent SDK. Only then read its “allowed list.” Quick glossary.

The normal API client SDK and the Agent SDK are different libraries. The first one sends requests to the model. The second one runs a full agent runtime (the Claude Code engine). API tool definitions↗ · CLI flags↗ · Subagent configuration↗.

claude --tools "Read,Bash" --allowedTools "Bash(git status)"

{
  "permissions": {
    "allow": ["Bash(git status)", "mcp__docs__load_document"],
    "deny": ["mcp__docs__archive_document"]
  }
}

const options = {
  tools: ["Read"],
  mcpServers: { docs: documentServer },
  allowedTools: ["Read", "mcp__docs__load_document"],
  disallowedTools: ["mcp__docs__archive_document"]
};

for await (const message of query({
  prompt: "Read the supplied document and explain its findings.",
  options
})) {
  // Your application consumes the SDK messages here.
}

import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";
import { z } from "zod";
import { documents } from "./documents"; // your repository/service module

const loadDocument = tool(
  "load_document",
  "Load one document's text by its id. Read-only.",
  { documentId: z.string().describe("The document id, e.g. doc-17") },
  async ({ documentId }) => {
    const doc = await documents.findReadable(documentId); // your access check lives here
    if (!doc) {
      return { content: [{ type: "text", text: `No readable document ${documentId}` }], isError: true };
    }
    return { content: [{ type: "text", text: doc.text }] };
  },
  { annotations: { readOnlyHint: true } }
);

const documentServer = createSdkMcpServer({ name: "docs", version: "1.0.0", tools: [loadDocument] });

for await (const message of query({
  prompt: "Read document doc-17 and explain its findings.",
  options: {
    model: process.env.CLAUDE_MODEL ?? "claude-sonnet-5",
    tools: ["Read"],
    mcpServers: { docs: documentServer },
    allowedTools: ["Read", "mcp__docs__load_document"],
    disallowedTools: ["mcp__docs__archive_document"],
    maxTurns: 8,
  },
})) {
  if (message.type === "result") {
    if (message.subtype === "success") console.log(message.result);
    else console.error(`Run stopped: ${message.subtype}`); // e.g. error_max_turns
  }
}

{
  "type": "object",
  "properties": { "documentId": { "type": "string", "description": "The document id, e.g. doc-17" } },
  "required": ["documentId"]
}

Many pipelines in one repo: the project file is the floor, not the whole policy

One .claude/settings.json file cannot describe two pipelines that need different tools. It does not need to. Permissions stack in layers. A deny in any layer wins. allow entries from all layers are merged. The flags on one run sit above every file. So the shared file holds the rules that every pipeline in the repo must follow. Each pipeline then sets its own pre-approved list (and its own extra denies) in its own job definition.

// .claude/settings.json — the floor every pipeline in the repo shares
{ "permissions": { "deny": ["mcp__finance__update_database", "mcp__finance__send_alert", "mcp__finance__delete_record"] } }

# pipelines/extract.sh — narrows to its three tools; unattended, nothing outside the list can be approved
claude -p "Extract the filings in inbox/" --output-format json \
  --allowedTools "mcp__finance__read_file,mcp__finance__write_output,mcp__finance__lookup_vendor"

# pipelines/reconcile.sh — same repo, a different list; the shared denies still apply
claude -p "Reconcile yesterday's ledger" --output-format json \
  --allowedTools "mcp__finance__read_file,mcp__finance__lookup_vendor,mcp__ledger__post_entry"

Pipelines written as code (Agent SDK) do the same thing for each call. The query() options accept allowedTools and disallowedTools, so each pipeline function carries its own list. The model decides nothing about this at run time. The job definition is the policy.

Read an exam’s “allowed tools” precisely

Suppose an agent must never archive a document by itself. There are two different fixes. You can remove the archive capability: no archive tool is exposed, and the agent's backend identity does not have that right. Or you can remove only its pre-approval: the tool still exists, but the runtime now asks a person before it runs. A separate case: if the MCP tools are already configured and reachable and the model picks the wrong one, the allowlist is not the cause. Look at the tool descriptions and how the model selects tools.

Recall: Registration provides the tool. Descriptions guide which tool the model picks. Permissions decide whether a call runs. Backend authorization checks the requested action on the resource. Checked against official documentation on September 22, 2026. Check your installed runtime version for the exact options it supports.

Developer tools: arguments and shell flags

Read, Write, Edit, Bash, Grep, and Glob are names of tools inside the Claude Code runtime. They are not macOS commands. The model picks a tool and fills in structured arguments. Then Claude Code (the runtime) checks permission, runs the tool's code, and sends the result back to the model. A plain Messages API call from your own app does not come with these tools.

flowchart LR
    M["Model requests named tool with JSON input"] --> R["Claude Code runtime checks and dispatches"]
    R --> F["Built-in file/search operation"]
    R --> B["Bash tool launches shell program"]
    R --> C["MCP client calls connected server tool"]
    F --> O["Result returned to model"]
    B --> O
    C --> O

Which operation should I choose?

Tool arguments are not shell flags

Compare two ways to search:

{"name":"Grep","input":{"pattern":"processPayment","path":"/project/src","output_mode":"content"}}

{"name":"Bash","input":{"command":"rg -n -F 'processPayment' /project/src","timeout":10000}}

These are parts of tool calls, not complete API requests. In the first one, JSON properties set the options of the Grep tool. In the second one, Claude Code passes command to a shell. That shell starts ripgrep (rg). Ripgrep, not the tool, reads -n (show line numbers) and -F (match literal text). The glossary dialogs below show complete illustrative model responses, including the call ID and the stop reason. Claude Code provides these tool definitions itself. Do not assume the same names exist in a custom harness that you build on the API.

Do not move a flag from one program to another. Do not write made-up commands such as Read --file. The shell command grep (lowercase), ripgrep rg, and the Claude Code Grep tool do similar jobs, but each has its own interface. Also, a glob pattern is a general idea: a pattern for filenames. The name Glob with a capital G means the Claude Code tool.

Using Read

{
  "file_path": "/project/src/payment.js",
  "offset": 1,
  "limit": 40
}

Using Write

{
  "file_path": "/project/docs/payment-notes.md",
  "content": "# Payment notes\nReview pending.\n"
}

Using Edit

{
  "file_path": "/project/src/payment.js",
  "old_string": "userData",
  "new_string": "customerData",
  "replace_all": true
}

Using Bash

{
  "command": "rg -n -F 'processPayment' src/",
  "timeout": 10000
}

Using Grep

{
  "pattern": "processPayment",
  "path": "/project/src",
  "glob": "**/*.js",
  "output_mode": "content",
  "head_limit": 30
}

Using Glob

{
  "pattern": "**/*.test.js",
  "path": "/project"
}

Using MCP tools

An MCP server is not one extra general tool called “MCP.” The server publishes operations such as analyze_dependencies. Each has its own name, description, and input schema. The host (here, Claude Code) discovers them and shows the right definitions to the model. When the model picks one, the host sends the call through its MCP client. The server can be a local process or a remote service. The real operation names and arguments come from that server, not from some standard set of operating-system commands.

Imagine a registered server named codeintel. The host might show an operation called mcp__codeintel__analyze_dependencies with the input {"module_path":"src/payment.js"}. This name and schema are illustrative. Open discovery, call and result examples. The built-in Bash tool can also run a language tool directly. A command that helps with coding is not automatically an MCP tool.

Exam terminology versus your installed runtime

The official reference (checked 21 September 2026) says that, under the conditions it describes, Grep and Glob are not present by default on macOS, Linux and WSL. Claude Code may use shell commands instead. Windows, or an explicit configuration, can be different. Read the tool definitions in your installed version to see the supported arguments and output limits. Do not assume that an older exam question describes the exact current list of tools. Current Claude Code reference↗.

Claude Code runs built-in operations, and its permissions still apply. Bash commands depend on which programs are installed and on the platform; Windows may not have the same shell programs as macOS. MCP operations depend on the connected server and on what it authorizes. “Built-in” does not mean “no limits” or “the same on every machine.”

Walkthrough: find test filenames with Glob → search the relevant content with Grep → look at the file with Read → change a small part with Edit, or create a new file with Write → run the tests through Bash. Use an MCP dependency analyzer when you need the code analysis that its server really implements. Explore alias-aware reference searching.

Grep, Glob, and callers with different names

Grep searches the text inside files. Glob finds files by their paths. A symbol-aware reference search follows what a name means in the code. Claude Code's tools are spelled Grep and Glob. Shell commands such as grep and rg also search text, but a shell runs them and they have their own flags. Shorthand such as Grep "processPayment" --all-files is not a real tool call. The tool takes structured arguments, not command-line flags. Which tools exist, and their interfaces, depend on the runtime and its version. Claude Code tools reference↗.

Follow one function through four names

An alias is a second name for the same exported value. In these examples, a re-export does not create a new payment function. The as keyword only changes the name that other files use to import it.

// core/payment.js
export function processPayment(order) {
  return { accepted: true, orderId: order.id };
}

// api/gateway.js
export { processPayment as handlePayment } from "../core/payment.js";

// services/billing.js
export { processPayment as executePayment } from "../core/payment.js";

// clients/web.js
import { handlePayment } from "../api/gateway.js";
handlePayment({ id: "order-web" });

// clients/batch.js
import { executePayment } from "../services/billing.js";
executePayment({ id: "order-batch" });

// clients/mobile.js
import { handlePayment as pay } from "../api/gateway.js";
pay({ id: "order-mobile" });

flowchart LR
    F["core: processPayment"] --> G["gateway re-exports as handlePayment"]
    F --> B["billing re-exports as executePayment"]
    G --> W["web calls handlePayment"]
    G --> M["mobile imports as pay and calls pay"]
    B --> C["batch calls executePayment"]

The arrows show one exported function becoming available under different names. A plain text search does not follow these arrows. A dependency graph shows which modules import from which other modules. Symbol resolution goes further: it tracks which exported value each local name points to. A module graph alone may still not show each individual place where the function is called.

rg -n -F 'processPayment' .
rg -n 'processPayment|handlePayment|executePayment' .
rg --files -g '*.js' api

Why A is intended and C is reasonable

When a processPayment search misses callers, two diagnoses are both true, but at different levels. Call them A (the direct cause) and C (the deeper limit of the tool).

A — the direct cause: callers use a different spelling. After the function is re-exported as handlePayment and executePayment, the consumer files never contain the string processPayment. This one fact explains why the search is incomplete. It also points directly to the fix: search every known name, then read the imports to find more local aliases.

C — the deeper limit: Grep matches text, not import relationships. A text search does not know that three names point to one exported value. This is a real property of the tool, and it is why A can happen at all. Keep this rule. It tells you when to use a language server or the IDE's Find References instead of a wider regex.

The two overlap. The difference is how specific each one is. A is the exact diagnosis for this symptom. C is the general rule that predicts it. One detail separates them. A re-export chain that keeps the same spelling does not hide any text. If a consumer still writes processPayment(...), that line matches, even though Grep does not understand the chain. The changed spelling is what removes caller lines from the results.

Two diagnoses are wrong. The first treats “every place the string appears” as “every use of the function”; but a string can be a comment, an import, or a different symbol with the same name. The second switches to finding paths; but Glob only finds files to look at. It cannot see inside them, so it cannot solve an alias problem.

Decision habit: First ask what you need: a filename, a place where text appears, or a reference to one specific symbol. For an alias, write the chain original → exported alias → local import alias → call. Then check which of those names your search really includes.

Built-in editing tools: one match or all matches

Suppose userData appears twelve times in one file, and every one must become customerData. A careful method works: find each one, include enough nearby text to make it unique, and replace that one. But that is twelve edit calls. Claude Code's Edit tool has a replace-all mode: one call, one file, every exact match. The real decision is what scope the operation should have. Twelve separate edits are possible, but that is not the question.

Built-in tools: which job belongs where?

These are tools of the Claude Code runtime. A plain messages.create API call from your own app does not get them. Which tools exist depends on the runtime, platform, version, and configuration. For example, current releases may search through Bash instead of showing Grep/Glob by default. This section assumes that the named tools are available. Official tool reference↗

Grep the tool versus grep the command

Grep (the tool name) and grep (a command inside a shell) can both search text, but their interfaces are different. sed is a shell program that changes text. It is not a Claude Code tool named Sed. A Bash call can run sed if that program is installed where the shell runs. Bash itself is a built-in tool. So “built-in tool” does not mean “never uses shell commands.”

{
  "type": "tool_use",
  "id": "toolu_search_dedicated",
  "name": "Grep",
  "input": {
    "pattern": "userData",
    "path": "/workspace/app/profile.js",
    "output_mode": "content"
  }
}

{
  "type": "tool_use",
  "id": "toolu_search_shell",
  "name": "Bash",
  "input": {
    "command": "grep -n 'userData' /workspace/app/profile.js"
  }
}

What changes across operating systems?

Software that runs on many platforms can offer structured file tools and run commands in a supported shell. A shell command must fit the real environment. Installed programs, paths, quoting, and options can differ. For example, do not assume every platform accepts the same sed syntax for editing a file in place. On Windows you may have Git Bash, WSL, or a supported PowerShell setup. These are different environments, not different spellings of the same thing.

Do not guess which tools exist from the operating system alone. The current documentation says that in some configurations Grep/Glob are not present by default on macOS, Linux, and WSL, and search goes through Bash instead. The model can choose only from the tool list that the runtime exposes. Older exam material may assume a different default set of tools. Current Claude Code tool availability↗

Beyond file editing: recognize the tool families

This is a map for learning. It does not promise that every session has every tool. For the current full list and when each tool is available, use the official reference.

How to reason through another tool-choice question

First, name the operation: find, look, change, run, or delegate. Next, name its scope: one occurrence, every match in one file, or the whole repository. Then check which available tool, with which arguments, does exactly that. Last, check the result. For the same rename everywhere in one file, this gives Edit + all intended matches in one named file. Working across platforms is useful context. But the difference that matters is twelve targeted edits versus one replace-all operation.

Two Edit modes: one occurrence or every match

One occurrence: Without replace-all, the old text must match in exactly one place. If the short string appears many times, add enough nearby text to make it unique.

All occurrences: Set replace_all: true when every exact match in that file should get the same replacement. It is an argument inside the Edit call. It is not a global setting in settings.json, and it is not a top-level Messages API option.

Below are complete illustrative tool-use blocks. The model proposes the call. Claude Code checks permissions and runs it. The IDs and paths are examples. These blocks are not full Messages API responses.

{
  "type": "tool_use",
  "id": "toolu_rename_all",
  "name": "Edit",
  "input": {
    "file_path": "/workspace/app/profile.js",
    "old_string": "userData",
    "new_string": "customerData",
    "replace_all": true
  }
}

// Before
const userData = loadProfile();
renderProfile(userData);
saveProfile(userData);

// After
const customerData = loadProfile();
renderProfile(customerData);
saveProfile(customerData);

{
  "type": "tool_use",
  "id": "toolu_target_one",
  "name": "Edit",
  "input": {
    "file_path": "/workspace/app/profile.js",
    "old_string": "renderProfile(userData);",
    "new_string": "renderProfile(customerData);",
    "replace_all": false
  }
}

Follow the runtime flow

sequenceDiagram
    participant M as Claude model
    participant H as Claude Code runtime
    participant F as File
    M->>H: Read file
    H->>F: Load current contents
    F-->>M: Contents through tool result
    M->>H: Edit(old_string, new_string, replace_all=true)
    H->>H: Check permission and matching conditions
    H->>F: Apply replacements in the specified file
    H-->>M: Tool result reports outcome
    M->>H: Inspect diff and run relevant checks

Reading the file first is good practice here. Whether the runtime forces a read before an edit depends on the model and runtime version. Do not memorize it as a rule for all versions. The skill the exam tests here is replace-all.

Decision rule — four ways to do the rename, and what each costs:

• Grep, then twelve targeted Edit calls. This works, and Grep is not the mistake. The waste is twelve separate change calls when every match needs the same replacement. “Each occurrence has unique nearby text” explains how to make each call clear. It does not explain why twelve calls are needed.
• Bash running sed. This also works. Bash is a built-in tool, so “sed is wrong because Bash is not built-in” is a false reason. The cost is shell replacement syntax that must fit the platform, when a tool made for editing already exists.
• Edit with replace_all: true. This says the intended scope directly: one file, one old string, one new string, every intended match. There may still be Read calls and check calls. “One call” means one change call, not always one whole agent turn.
• Write with the whole file. This rewrites the file without need. Write fits when you want to give the complete file content. A small replacement needs less content and gives fewer chances for unrelated edits by mistake. Edit takes old and new strings; it does not take a unified-diff format.

Text replacement is not semantic refactoring

Before you use replace-all, check strings, comments, and longer names. For example, replacing userData also changes that part of userDatabase. The same text can mean different variables in different scopes. When it matters which symbol is which, a rename that understands the code (from a compiler or IDE) is better. Replace-all assumes that every match should change. If that is not true, look first and choose a narrower operation.

Remember: unique nearby text selects one match; replace-all selects every exact match in one file.

Continue with tool-use blocks and the complete tool request/result loop.

Request approval without executing the archive

Putting an archive request in a queue is not the same as archiving the document. The document can still be archived later, after an authorized person approves that exact action. The rule is not “never archive.” The rule is “the agent that proposes the archive must not perform it itself.” Two designs keep these steps apart. Choose between them by how complex each is to build, not by whether the word “tool” appears in the answer.

Two valid ways to request approval

Both designs put a request in a queue. Neither one archives anything right away. The request-only tool does change something: it creates the approval record. But it does not do the restricted action, which is archiving the document. The proposal JSON does not queue itself. Your harness (the application code around the model) must receive it, validate it, and write the record. A tool's name guarantees nothing. Check what its code does and which backend permissions it has.

Structured output is the smaller change, because it adds no tool. That is a preference for simplicity. It does not show that a request-only tool breaks the approval rule. A request tool does not need an MCP server or any MCP server change. It can be an ordinary function in your application whose code only writes the pending record.

sequenceDiagram
    participant M as Proposing agent
    participant H as Harness / request-only tool
    participant DB as Durable approval store
    participant U as Compliance officer
    participant E as Authorized executor
    M->>H: Propose archive of doc-17 version v3
    H->>DB: Save ar-17 as pending_approval
    H-->>M: Request recorded, document not archived
    Note over H,DB: Save run checkpoint if more agent work remains, then release process
    U->>DB: Approve ar-17 through authenticated application
    DB-->>E: Approved request ready for execution
    E->>DB: Verify approval, action, version and execution state
    E->>E: Archive once using request id as idempotency key
    E->>DB: Record completed outcome

{
  "request_id": "ar-17",
  "run_id": "run-84",
  "action": "archive_document",
  "document_id": "doc-17",
  "document_version": "v3",
  "reason": "Retention period reached; awaiting compliance review",
  "status": "pending_approval",
  "approved_by": null,
  "approved_at": null,
  "execution_idempotency_key": "ar-17",
  "execution_status": "not_started"
}

Where enforcement actually lives

allowedTools text written inside CLAUDE.md is not a permission setting; nothing enforces it. In Claude Code, allow rules pre-approve tool use. Removing an allow entry is not the same as denying the tool. Use the runtime's real controls for which tools exist and which are denied. Also limit the backend rights of the service that proposes. Instructions (guidance) describe the behavior you want. Enforcement (settings, hooks, backend rights) stops actions that are not allowed. Permission rules↗.

For example, a custom harness (your own app) exposes read_file, write_output, and request_archive. Its backend identity has no archive permission. A separate executor identity has archive permission, but it accepts only requests that a person approved and that passed validation. The structured-output design uses the same split: it receives proposal JSON instead of exposing a request tool. This is an example of architecture. It does not claim that editing a tool list alone keeps the parts separate.

Decision habit: Find the restricted action. Check whether approval happens before it. Find where the pending record is stored. Find the component that is really allowed to perform the action. Only then compare how complex each design is. Do not decide just because an answer contains the word “hook,” “tool,” or “queue.” Guidance versus enforcement, in the naming-rule example.

Claude Agent SDK (scenario 1 & 4 — embedded agents & developer tooling — territory)

The Claude Agent SDK (it grew out of the Claude Code SDK) gives you the same agent harness as a library that your code can call (TypeScript/Python). You get sessions, tools (Read/Write/Bash/Grep/Glob/WebFetch…), MCP connections, hooks, permissions, and subagents — all of it — to build your own agents outside the terminal. In this runtime, your code sets the options that Claude Code would read from settings files.

• Use the SDK when you put an agent inside a product (support bot, pipeline worker). Use Claude Code interactively for development work itself.
• The built-in tools (Read, Write, Edit, Bash, Grep, Glob) ARE the "developer productivity tooling" of scenario 4. Know what each one does. Grep/Glob only search and read; Bash is the powerful one that permissions guard.
• Sessions keep the conversation state. --continue/--resume (CLI) and session ids (SDK) continue earlier work.