D2 · Claude Code Configuration and Workflows

This domain is worth roughly 12 of 60 items and maps to the Code-Generation and CI/CD scenarios. It tests whether you can configure Claude Code correctly for an individual and, crucially, for a team: where context lives, how settings and permissions resolve, when to enforce with hooks versus guide with prompts, and how to run Claude Code headlessly in CI. The recurring theme is precedence and the right mechanism for the right job.

Learning objectives

By the end of this page you should be able to:

1. Order the CLAUDE.md hierarchy and decide what belongs in each level.
2. Resolve settings.json scopes and permissions (allow / deny / ask) precedence.
3. Configure hooks for every event, use exit code 2 to block, and read/write JSON on stdin/stdout.
4. Choose among Skill, CLAUDE.md, slash command, subagent and MCP for a given need.
5. Write custom slash commands with $ARGUMENTS and define subagents with tool allowlists and per-agent models.
6. Decide plan mode vs direct execution and run Claude Code headlessly in CI with the right flags and exit-code handling.
7. Design team-scale conventions: checked-in project settings, managed policies, MCP config scopes, and cost control.

2.1 The CLAUDE.md hierarchy

CLAUDE.md files inject persistent project context into every session. They compose from broad to narrow, with more specific files layering on top.

Managed policy (enterprise, admin-controlled)   ← highest authority, cannot be overridden
        ▼
User        ~/.claude/CLAUDE.md                  ← your personal defaults across all projects
        ▼
Project     ./CLAUDE.md   (checked into git)     ← shared team context for this repo
        ▼
Subdirectory ./packages/x/CLAUDE.md              ← context specific to a part of the repo

CLAUDE.local.md is a git-ignored personal file for project-specific notes you do not want to share. Use @path/to/file to import other files (e.g., @docs/architecture.md) so context stays modular and DRY.

2.2 settings.json scopes and precedence

settings.json configures permissions, hooks, environment and the model. Scopes resolve from most to least authoritative:

Managed policy settings         (admin, cannot be overridden)
        ▼ overrides
.claude/settings.local.json     (personal, git-ignored)
        ▼ overrides
.claude/settings.json           (project, checked in)
        ▼ overrides
~/.claude/settings.json         (user, global default)

{
  "model": "claude-opus-5",
  "permissions": {
    "allow": ["Read", "Edit", "Bash(npm test:*)", "Bash(git status)"],
    "deny": ["Bash(rm -rf:*)", "Read(./.env)", "Read(./secrets/**)"],
    "ask": ["Bash(git push:*)", "WebFetch"]
  },
  "env": { "NODE_ENV": "test" }
}

2.3 Permissions: allow / deny / ask

deny wins over allow. Patterns match tool name and arguments (e.g., Bash(git commit:*)). Prefer a narrow allowlist plus explicit denies for dangerous operations; use ask for actions that are usually fine but occasionally consequential.

2.4 Hooks

Hooks are deterministic shell (or HTTP) handlers that fire on lifecycle events. They receive event JSON on stdin and can emit JSON on stdout; exit code 2 blocks the action (and returns stderr to Claude), while exit code 0 allows it.

Events: PreToolUse, PostToolUse, UserPromptSubmit, Stop, SessionStart, Notification, SubagentStop, PreCompact.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": "./.claude/hooks/guard.sh" }]
      }
    ]
  }
}

#!/usr/bin/env bash
# .claude/hooks/guard.sh — reads tool call JSON on stdin, blocks destructive commands.
input=$(cat)
cmd=$(echo "$input" | jq -r '.tool_input.command // ""')
if echo "$cmd" | grep -qE 'rm -rf|:(){ :|:& };:'; then
  echo "Blocked destructive command: $cmd" >&2
  exit 2      # exit code 2 blocks the tool call
fi
exit 0

#!/usr/bin/env bash
# Block a git commit if the test suite fails. Deterministic — not a prompt instruction.
input=$(cat)
cmd=$(echo "$input" | jq -r '.tool_input.command // ""')
if echo "$cmd" | grep -q 'git commit'; then
  if ! npm test --silent; then
    echo "Tests failing — commit blocked." >&2
    exit 2
  fi
fi
exit 0

#!/usr/bin/env bash
# After Claude edits a file, auto-lint it and surface issues back to Claude.
input=$(cat)
file=$(echo "$input" | jq -r '.tool_input.file_path // ""')
if [[ "$file" == *.ts || "$file" == *.tsx ]]; then
  npx eslint --fix "$file" 2>&1 || echo "Lint issues remain in $file" >&2
fi
exit 0

2.5 Skills, CLAUDE.md, slash commands, subagents, MCP – which one?

These five mechanisms overlap, and choosing correctly is heavily tested.

Skills and progressive disclosure

A Skill lives in .claude/skills/<name>/SKILL.md with frontmatter (name, description) and optional bundled scripts. Claude reads the description to decide when the skill is relevant and loads the full body only then – progressive disclosure keeps context lean.

---
name: pdf-invoice-extractor
description: Extract structured fields from PDF invoices. Use when the user asks to pull totals, dates, or line items from an invoice PDF.
---

# PDF Invoice Extractor
1. Read the PDF text layer.
2. Extract fields into the JSON schema in ./schema.json.
3. Validate and report any missing required fields.

2.6 Custom slash commands

A file .claude/commands/review.md becomes /review. $ARGUMENTS is substituted with whatever follows the command.

---
description: Review a pull request for security and style issues.
---
Review the changes in PR #$ARGUMENTS. Check for injection risks, missing input
validation, and deviations from ./CLAUDE.md conventions. Output a table of
findings with severity.

Invoke as /review 482. Commands can be project (.claude/commands/) or user (~/.claude/commands/) scoped.

2.7 Subagents

A subagent is defined in .claude/agents/<name>.md with its own system prompt, tool allowlist and model. It runs in an isolated context window, protecting the main conversation from noise.

---
name: security-reviewer
description: Reviews diffs for security vulnerabilities. Use proactively before merges.
tools: Read, Grep, Bash(git diff:*)
model: claude-opus-5
---
You are a security reviewer. Examine the diff for injection, authz gaps, secret
leakage and unsafe deserialisation. Report findings with severity and file:line.
Do not modify code.

Key design points: give each subagent a narrow tool allowlist (least privilege), pick a model per agent (a cheap Haiku classifier, an Opus reviewer), and remember its context is isolated – the parent must pass context explicitly (same rule as Domain 1).

2.8 Plan mode vs direct execution

Plan mode (Shift+Tab) makes Claude explore read-only and produce a plan before touching anything. Direct execution lets it edit and run immediately.

2.9 Headless and CI usage

Run Claude Code non-interactively with claude -p (print mode). This is the CI/CD scenario.

# Headless review in CI, machine-readable output, tight tool allowlist, no prompts.
claude -p "Review the diff in this PR for security issues and output JSON findings." \
  --output-format json \
  --allowedTools "Read,Grep,Bash(git diff:*)" \
  --permission-mode acceptEdits

echo "exit code: $?"   # 0 success; non-zero for failures — gate the pipeline on it

Gate the pipeline on the exit code; parse the JSON for structured findings. Keep the tool allowlist minimal in CI so an injected instruction cannot run arbitrary commands.

2.10 Multi-pass code review for large PRs

Large PRs overflow a single review pass. Split the work:

1. Partition the diff by file or module so each pass fits comfortably in context.

2. Review each partition in its own pass (or subagent) with a focused prompt, emitting structured findings.

3. Aggregate findings, deduplicate, and rank by severity in a final synthesis pass.

This mirrors orchestrator-workers: independent partitions reviewed in isolated contexts, then aggregated. It also keeps each context small enough that quality does not degrade.

2.11 Team-scale conventions

MCP configuration scopes

Agent teams, dynamic workflows, routines

Claude Code supports agent teams (multiple coordinated subagents), dynamic workflows (runtime-composed steps) and routines (saved multi-step procedures). Position them as higher-level orchestration built on the primitives above; on the exam, prefer the simplest one that solves the stated problem.

Cost control

Use /cost to inspect spend, choose a cheaper model per subagent where quality allows (Haiku for classification, Sonnet for balanced work, Opus for hard coding), and keep CLAUDE.md concise to reduce per-turn tokens. Prompt caching applies to the stable CLAUDE.md/tools prefix.

2.12 A complete, worked team configuration

The exam rewards knowing exactly which file holds which setting. Here is a coherent, checked-in project layout for the Code-Generation scenario, followed by the reasoning for each placement.

repo/
├── CLAUDE.md                      # shared: build/test cmds, architecture, conventions (+ @imports)
├── CLAUDE.local.md                # git-ignored: personal scratch notes, local paths
├── .mcp.json                      # shared: project-scope MCP servers
└── .claude/
    ├── settings.json              # shared: permissions, hooks, model, env
    ├── settings.local.json        # git-ignored: personal overrides
    ├── agents/
    │   └── security-reviewer.md   # subagent: isolated context, tool allowlist, model
    ├── commands/
    │   └── review.md              # /review $ARGUMENTS
    ├── skills/
    │   └── release-notes/SKILL.md # progressive-disclosure capability
    └── hooks/
        └── guard.sh               # PreToolUse guard (exit 2 blocks)

Worked CLAUDE.md (concise, imports for bulk):

# Payments Service
Build: `pnpm build`  ·  Test: `pnpm test`  ·  Lint: `pnpm lint`
Never touch `migrations/` without a reviewed plan.
Architecture and coding conventions: @docs/architecture.md
Never put secrets here; use the secret manager. See @docs/security.md

Worked .claude/settings.json:

{
  "model": "claude-sonnet-5",
  "permissions": {
    "allow": ["Read", "Edit", "Bash(pnpm test:*)", "Bash(pnpm lint:*)", "Bash(git status)"],
    "deny": ["Bash(rm -rf:*)", "Read(./.env)", "Read(./secrets/**)"],
    "ask": ["Bash(git push:*)", "WebFetch"]
  },
  "hooks": {
    "PreToolUse": [
      { "matcher": "Bash", "hooks": [{ "type": "command", "command": "./.claude/hooks/guard.sh" }] }
    ],
    "PostToolUse": [
      { "matcher": "Edit", "hooks": [{ "type": "command", "command": "./.claude/hooks/lint.sh" }] }
    ]
  },
  "env": { "NODE_ENV": "test" }
}

2.13 Hook events in depth and exit-code semantics

Every hook receives event JSON on stdin; exit code 2 blocks (stderr is returned to Claude), exit 0 allows, and other non-zero codes surface an error without necessarily blocking. Matching the event to the goal is tested directly.

#!/usr/bin/env bash
# PreCompact hook: persist the running decision log before the window is compacted.
input=$(cat)
echo "$input" | jq -r '.transcript_summary // ""' >> ./.claude/decision-log.md
exit 0

2.14 Headless output formats and exit-code gating in CI

claude -p supports two machine-readable output formats. Choosing correctly matters for CI design.

set -euo pipefail
result=$(claude -p "Review the diff for security issues; output JSON {findings:[{severity,file,line,note}]}." \
  --output-format json \
  --allowedTools "Read,Grep,Bash(git diff:*)")
# Fail the build if any high-severity finding exists.
echo "$result" | jq -e '.findings | map(select(.severity=="high")) | length == 0' >/dev/null \
  || { echo "High-severity findings — failing build."; exit 1; }

Gate the pipeline on both the process exit code and the parsed structured findings; never grep prose.

Common misconceptions

Scenario walkthrough — standardising a team on Claude Code safely

Situation. A 40-engineer org adopts Claude Code. Security mandates that production secret files are never readable and that rm -rf is never run — for everyone, with no local override. The platform team wants shared build/test commands and architecture conventions available to all, a way to block commits when tests fail, a repeatable PR-review command, and a diff-review helper that can never edit or push. One engineer wants personal notes that stay off the shared repo. CI must review PRs headlessly and fail builds on high-severity issues without being hijacked by malicious diff content.

Expert reasoning trace.

1. Non-overridable security rules → managed policy. “For everyone, no override” is the definition of managed policy; put deny rules for Read(./secrets/**) and Bash(rm -rf:*) there (and back the destructive-command block with a managed PreToolUse hook exiting 2). Reject settings.local.json (per-user, overridable) and CLAUDE.md prose (#3).

2. Shared conventions → checked-in project CLAUDE.md, kept concise with @import for bulk. Reject the user file (per-person) and CLAUDE.local.md (git-ignored).

3. Tests-before-commit → PreToolUse hook on the commit that runs tests and exits 2. Reject a CLAUDE.md instruction (probabilistic) and a slash command (opt-in).

4. Repeatable review → slash command .claude/commands/review.md with $ARGUMENTS. Reject a subagent (that is for isolated delegated contexts, not an on-demand named prompt).

5. Diff-reviewer that cannot edit/push → subagent with a least-privilege allowlist (Read, Grep, Bash(git diff:*)). Reject “tell it in the prompt” (#3-style, bypassable).

6. Personal notes → git-ignored CLAUDE.local.md.

7. Headless CI → claude -p --output-format json with a minimal --allowedTools, gate on exit code + parsed findings, never bypassPermissions, so an injected instruction in the diff cannot run arbitrary shell.

Exam-correct decision: managed policy + checked-in CLAUDE.md/settings + PreToolUse hooks + slash command + least-privilege subagent + local file for personal notes + headless JSON with a tight allowlist. Every rejected option is a mechanism used for the wrong job — the exact shape of D2 distractors.

Exam traps in this domain

Practice questions

Key takeaways

• CLAUDE.md composes managed policy → user → project → subdirectory; keep it concise, never store secrets, and use @import for modularity.
• settings.json resolves managed policy → local → project → user; deny beats allow; use ask for occasionally-consequential actions.
• Hooks are deterministic: exit code 2 blocks, JSON on stdin/stdout, events cover the whole lifecycle. Use hooks (not prompts) for critical rules, and PreToolUse (not PostToolUse) to block.
• Choose the mechanism deliberately: CLAUDE.md (always-on context), Skill (progressive on-demand capability), slash command (invoked prompt), subagent (isolated context/tools/model), MCP (external integration).
• Subagents get least-privilege tool allowlists and a model per agent; plan mode for large/unfamiliar/risky work.
• Headless CI: claude -p with --output-format json (short) or stream-json (long), a minimal --allowedTools, and pipeline gating on the exit code and parsed findings — never grep prose.
• Team scale: checked-in project settings and .mcp.json, managed policy for mandatory rules, /cost and per-subagent models for cost control, multi-pass review for large PRs.
• Map every “where should X live” question to two axes — shared vs personal, advisory vs mandatory — to pick the correct file/mechanism.
• Never store secrets in any checked-in file (CLAUDE.md or settings.json); use a secret manager plus deny rules on secret paths.