About This Catalog

Volume 3 catalogs the tools an agent calls; Volume 2 catalogs skills as reusable capability; Volume 9 catalogs how agents coordinate. This volume catalogs the configuration surface of one specific agent --- Claude Code, Anthropic’s command-line coding agent --- because that surface has become an engineering discipline in its own right. A team adopting Claude Code does not just run it; they shape it: standing instructions in CLAUDE.md, custom slash commands, project subagents, permission rules, lifecycle hooks, and headless invocations wired into CI. Those are the patterns collected here.

The volume is Claude-Code-specific by design. The neighboring tools --- Cursor, Windsurf, Aider, Codex --- have their own configuration surfaces with different file names and mechanisms; Volume 14 surveys them as products. What generalizes is the shape of the discipline: a coding agent becomes a team tool through configuration-as-code checked into the repository, and the patterns here have analogues in every serious agent harness.

Volume 17’s closing appendix set a deliberately high bar for any eighteenth volume and asked that it justify its place explicitly rather than arrive by momentum. The justification is this: unlike the three “weaker candidate” consolidations that preceded it, this volume is not a re-framing of material already covered elsewhere but a tool-specific operational reference for a heavily-used tool the series documents nowhere else. It is narrower than the discipline-level catalogs around it, and says so; that narrower, concrete scope is exactly what earns it a place.

Scope

In scope: the files and mechanisms Claude Code reads to configure its behavior --- CLAUDE.md memory, settings.json for permissions and hooks, .claude/commands, .claude/agents --- and the workflows those enable, from interactive planning to headless CI runs and SDK-driven automation.

Out of scope: the underlying tool primitives (Volume 3), skills as portable artifacts (Volume 2), the multi-agent coordination patterns subagents participate in (Volume 9), and the comparative product landscape (Volume 14). Where a pattern here touches those, it cross-references rather than restates.

How to read this catalog

Part 1 orients: what Claude Code is, how its configuration layers compose, and how the interactive tool relates to the SDK and the raw API. Part 2 is the pattern catalog, in four sections --- project context and instructions, commands and subagents, permissions and safety, and headless and programmatic use. Each pattern follows the series template: Intent, Motivating Problem, How It Works, When to Use It, Sources, and example artifacts where a configuration is clearer shown than described.

Part 1 — The Narratives

Chapter 1. What Claude Code Is

Claude Code is an agentic command-line tool: it runs in the terminal, reads and edits files in a working directory, runs shell commands, searches the web, and iterates toward a goal through a plan-act-observe loop rather than answering a single prompt. It is not an autocomplete and not a chat window that returns text --- it takes actions against a real filesystem and a real shell, which is what makes its configuration consequential. The same properties that make it useful, that it can run any command and edit any file, are the ones its permission model, hooks, and instructions exist to govern.

Three facts shape everything in this volume. First, Claude Code holds no memory across sessions by default; continuity comes from what is written down --- CLAUDE.md, and the files the agent is asked to leave behind. Second, everything it reads to configure itself is a file, in the project or in the user’s home directory, which means configuration is version-controllable and shareable like any other code. Third, the agent chooses its own actions within a bounded permission surface, so the interesting engineering is in shaping that surface well: enough freedom to be useful, enough constraint to be safe.

Chapter 2. The Configuration Layers

Claude Code’s behavior is the sum of several layers that load together, each with a scope and a precedence. Instructions come from CLAUDE.md files: an enterprise-managed policy, the user’s personal ~/.claude/CLAUDE.md that applies across all projects, the project’s ./CLAUDE.md checked into the repository, and CLAUDE.md files in subdirectories that apply when the agent works in that subtree. They are additive --- all of them load --- with the more specific and more privileged layers taking precedence when they conflict.

Settings come from settings.json files on a parallel hierarchy: enterprise-managed settings, the user’s ~/.claude/settings.json, the project’s .claude/settings.json (shared, checked in), and .claude/settings.local.json (personal, git-ignored). Settings carry the permission rules and the hook registrations. Extensions live in their own directories: .claude/commands for slash commands and .claude/agents for subagents, each a folder of markdown files that become part of the tool the moment they are present, with no registration step. The mental model that makes the rest of the volume coherent: instructions guide, settings govern, and extensions add capability --- three layers, each a directory of files, each shareable through version control.

Chapter 3. Claude Code, the SDK, and the API

The same engine is reachable three ways. The interactive CLI is a human driving the agent turn by turn. Headless mode (claude -p) is the same CLI invoked non-interactively --- one prompt, structured output, an exit code --- so a script or a CI job can drive it. The Claude Agent SDK is the agent loop as a library, embedded in an application that constructs sessions programmatically, with the same tools, permissions, and CLAUDE.md context available under code control. Beneath all three is the Claude API, a single model call with no agent loop, no filesystem, and no tools unless the caller builds them.

The distinction matters when choosing where to build. Reach for the CLI when a human is in the loop; for headless mode when the task is well-defined enough to run unattended in a pipeline; for the SDK when the agent is a component inside a larger application; and for the raw API when what is needed is a model completion, not an agent. The configuration patterns in this volume apply to the first three --- they share the same CLAUDE.md, permissions, and hooks --- and stop at the API, which has none of them.

Part 2 — The Substrates

Sections at a glance

Section A --- Project context and instructions
Section B --- Commands and subagents
Section C --- Permissions, hooks, and safety
Section D --- Headless and programmatic use

Section A — Project context and instructions

CLAUDE.md and the standing context that makes the agent project-aware

Claude Code starts each session with no memory of the last. What it knows about a project on the first turn is whatever the project’s CLAUDE.md files tell it. This section covers the memory hierarchy those files form, how to write instructions the agent actually follows, and how to bootstrap a starting CLAUDE.md from an existing repository.

CLAUDE.md and the memory hierarchy

Source: docs.claude.com/en/docs/claude-code/memory

Classification Standing instructions loaded from a hierarchy of CLAUDE.md files.

Intent

Give Claude Code durable, project-aware context by placing instructions in CLAUDE.md files across a defined hierarchy --- enterprise, user, project, and subdirectory --- that load together at session start, so the agent behaves consistently without being re-briefed each turn.

Motivating Problem

Claude Code holds no memory between sessions; on the first turn of every session it knows only the general model plus whatever standing context it is given. Without that context it rediscovers the project’s conventions each time --- guessing the test command, the style rules, the architectural boundaries --- and guesses inconsistently. Re-explaining the project in the prompt every session is wasteful and unreliable. The need is a place to write down what is true about the project once, and have the agent read it automatically.

How It Works

The hierarchy: instructions load from several CLAUDE.md locations at once. An enterprise-managed file sets organization policy; the user’s ~/.claude/CLAUDE.md carries personal preferences across every project; the project’s ./CLAUDE.md, checked into the repository, carries shared team conventions; and CLAUDE.md files in subdirectories apply when the agent works within that subtree. All of them load; they are additive, not exclusive.

Precedence on conflict: when two layers disagree, the more specific and more privileged wins --- enterprise policy over user preference, project convention over personal default, a subdirectory’s local rule over the repository root. Complementary instructions from different layers simply both apply. This is why personal preferences belong in the user file and shared standards in the project file: mixing them puts one person’s habits into everyone’s context.

Loading and cost: every loaded CLAUDE.md consumes context-window tokens for the whole session (Volume 15). This makes concision a feature, not a nicety --- standing instructions are paid for on every turn, so they should be directive and short rather than exhaustive.

Imports and editing: a CLAUDE.md can pull in other files by reference, so large or shared instruction sets need not be duplicated. The file is editable directly, through the /memory command, or by prefixing a note with # in a session to append a memory to the appropriate file.

Not a conversation log: CLAUDE.md is standing configuration, not a scratchpad for session state. Evolving task state belongs in a separate working file (the scratchpad discipline of Volume 15), not in the instruction hierarchy.

When to Use It

Every project a team runs Claude Code against. The project ./CLAUDE.md is the highest-value single artifact --- it turns a generic agent into one that knows this codebase. Use the user file for cross-project personal preferences, subdirectory files for parts of a monorepo with local conventions, and enterprise settings for organization-wide policy.

Alternatives --- passing context in the prompt for one-off tasks that do not recur; packaged Skills (Volume 2) when the instructions are large, reusable across projects, and better shipped as an artifact than as standing memory.

Sources

docs.claude.com/en/docs/claude-code/memory
docs.claude.com/en/docs/claude-code/settings

Example artifacts

Code.

# CLAUDE.md  (project root, checked into git)

## Commands
- Test: `npm test` (Vitest). Run before every commit.
- Build: `npm run build`. Type-check: `npm run typecheck`.

## Conventions
- TypeScript strict mode; no `any`. Prefer named exports.
- React function components only.

## Guardrails
- Never edit files under `src/generated/` (code-generated).
- Do not commit, push, or open PRs unless explicitly asked.

Writing effective CLAUDE.md instructions

Source: Anthropic Claude Code best-practices guidance

Classification Authoring standing instructions the agent reliably follows.

Intent

Write CLAUDE.md content that changes agent behavior reliably: specific, actionable, concise directives that earn their place in the context window, rather than a verbose document the agent skims and half-follows.

Motivating Problem

A CLAUDE.md is only worth its token cost if the agent follows it. Two failure modes are common. A file that is too vague (“write good code,” “follow best practices”) gives the model nothing concrete to act on. A file that is too long --- a wall of prose duplicating the linter, the style guide, and the onboarding doc --- dilutes attention and buries the few rules that matter. Standing instructions are paid for on every turn and read under attention pressure; they have to be written for that.

How It Works

Directive, not narrative: one instruction per line, imperative voice. “Run npm test before committing” beats a paragraph on the testing philosophy. Bullet lists of concrete rules outperform prose.

Encode what the agent cannot infer: project-specific commands, conventions, architectural boundaries, the deployment process --- the things that would surprise a competent newcomer. Skip what the model already knows (general language idioms, standard-library usage) and what tooling already enforces; if the linter rejects it, the CLAUDE.md need not repeat it.

Say what to do, not only what to avoid: positive, concrete directions (“prefer X”) are followed more reliably than long lists of prohibitions. Reserve prohibitions for genuine guardrails and state them plainly.

Structure for scanning: group rules under headers (Commands, Conventions, Testing, Guardrails) so the agent, and the humans maintaining the file, can find the relevant section. Keep the whole file short enough to read on one screen where possible.

Maintain it like code: the file drifts as the project changes. Prune stale rules, and treat a rule the agent keeps violating as a signal to sharpen the wording rather than to pile a second rule on top.

When to Use It

Whenever authoring or revising a CLAUDE.md. The discipline matters most for shared project files, which every team member’s agent reads, and where a bloated or vague file wastes everyone’s context budget.

Alternatives --- a slash command (Section B) when the instruction is really a repeatable task the user invokes rather than a standing rule; a subagent (Section B) when a body of instructions applies only to a specific delegated job.

Sources

docs.claude.com/en/docs/claude-code/memory
anthropic.com/engineering (Claude Code best practices)

Bootstrapping with /init

Source: docs.claude.com/en/docs/claude-code

Classification Generating a starting CLAUDE.md by analyzing the repository.

Intent

Generate a first-draft CLAUDE.md automatically by having Claude Code analyze an existing repository with the /init command, then refine the draft rather than writing standing instructions from a blank page.

Motivating Problem

A useful CLAUDE.md requires knowing the project’s structure, commands, and conventions and writing them down --- work that is easy to defer, so many projects run Claude Code with no standing context at all. The blank page is the obstacle. A generated starting point that is eighty-percent right and needs editing is far easier to finish than one written from scratch.

How It Works

What /init does: run in a project, it inspects the repository --- the file tree, the README, and config files such as package.json or pyproject.toml --- infers the languages, frameworks, entry points, and likely commands, and writes a starter CLAUDE.md with sections populated from what it found.

Draft, not final: the output is a first draft to review, not a finished file. It captures what is inferable and misses what is not --- the non-obvious guardrails, the conventions that live in the team’s heads, the rules that exist because of a past incident. Treat it as scaffolding.

Refine it: remove the noise (rules the linter already enforces, generic advice) and add the context the agent could not infer --- the deploy process, the directories not to touch, the commit and PR policy. The pattern is generate-then-curate.

When to Use It

At the start of adopting Claude Code on a repository that has no CLAUDE.md. Also worth re-running as a diff aid when a project has changed substantially and the standing instructions have drifted.

Alternatives --- writing the CLAUDE.md by hand when the project is small or idiosyncratic enough that curating a generated draft saves little; copying a template from a sibling project with similar conventions.

Sources

docs.claude.com/en/docs/claude-code

Section B — Commands and subagents

Turning repeatable work and delegated jobs into checked-in extensions

Beyond standing instructions, Claude Code is extended by two file-based mechanisms: slash commands, which package a repeatable instruction the user invokes by name, and subagents, which delegate a job to a separate agent with its own context and tools. Both are folders of markdown checked into the project, shareable like any other code.

Custom slash commands

Source: docs.claude.com/en/docs/claude-code/slash-commands

Classification Repeatable prompts packaged as invokable /commands.

Intent

Package a repeatable instruction as a markdown file that becomes a slash command, so a common task --- a review, a scaffold, a fix routine --- is invoked by name with arguments instead of re-typed each time.

Motivating Problem

Teams repeat the same complex prompts: “review this PR against our checklist,” “scaffold a new component following our conventions,” “write a conventional-commit message for the staged diff.” Re-typing them is tedious and drifts --- everyone phrases the request slightly differently, so the results vary. A repeatable task deserves a stable, named, shareable definition.

How It Works

A command is a markdown file: place review-pr.md in .claude/commands and it becomes /review-pr; the file’s body is the prompt injected when the command runs. The filename is the command name. There is no registration step --- presence is activation.

Project versus personal scope: commands in the project’s .claude/commands are shared through version control and available to everyone on the repository; commands in ~/.claude/commands are personal and available across all of a user’s projects.

Arguments: a command takes input through the $ARGUMENTS placeholder (or positional $1, $2), so /review-pr 4821 passes the number into the prompt. This lets one command file serve every invocation.

Frontmatter controls: an optional YAML header sets the command’s description, an argument hint, the tools it is allowed to use, and the model it runs on, so a command can be scoped and documented in place.

What goes inside: a good command file reads like a focused instruction --- role, task, expected output, constraints --- and does one thing well. Broad, do-everything commands route poorly; narrow verb-noun commands (/review-pr, /run-tests, /explain-file) are invoked and behave predictably.

When to Use It

Any prompt a person or a team types more than a few times, especially multi-step routines with a fixed shape. Shared project commands encode team workflows; personal commands encode individual habits. They pair with CLAUDE.md: standing rules live in memory, invokable routines live in commands.

Alternatives --- a subagent (below) when the task needs an isolated context or its own tool set rather than an injected prompt; a Skill (Volume 2) when the capability should travel across tools and repositories as a portable artifact.

Sources

docs.claude.com/en/docs/claude-code/slash-commands

Example artifacts

Code.

---
description: Review a pull request against our checklist
argument-hint: <pr-number>
allowed-tools: Bash(gh pr view:*), Bash(gh pr diff:*)
---

Review pull request #$ARGUMENTS. Fetch its diff, then
check it against our review checklist:
- Tests cover the new behavior and pass.
- No secrets, credentials, or debug logging left in.
- Public APIs documented; naming matches conventions.

Report findings as Blocking / Should-fix / Nits.

Project subagents

Source: docs.claude.com/en/docs/claude-code/subagents

Classification Delegated agents with isolated context and scoped tools, defined as files.

Intent

Define specialized subagents as files in the project so Claude Code can delegate a bounded job --- a code review, a codebase search, a test-writing pass --- to a separate agent with its own context window, its own instructions, and a restricted tool set.

Motivating Problem

A single agent doing everything in one context has two problems: verbose subtasks (searching a large codebase, spelunking docs) flood the main context with noise, and a broadly-capable agent is a broad blast radius when something goes wrong. Some work is better handed to a focused worker that investigates in its own context and returns only a result, and that should not have more power than its job requires.

How It Works

Definition as a file: a subagent is a markdown file in .claude/agents with YAML frontmatter --- a name, a description of when it should be used, the tools it may call, and optionally the model --- followed by its system prompt. The /agents command scaffolds and manages these interactively; the file is what persists.

Context isolation: a subagent runs with its own context window, separate from the main session. The parent passes it a task and the context it needs; the subagent works without polluting the parent’s context and returns a synthesized result. Verbose investigation stays in the subagent and never enters the main thread.

Scoped authority: a subagent is granted only the tools its job needs --- a review agent that reads and searches but cannot write, a test runner scoped to the test directory. This is least privilege (Volume 12) applied to delegation: narrower scope, smaller blast radius.

The hand-off: because the subagent starts with an empty context, the task, the relevant context, and the expected output shape must be stated explicitly. Vague delegation returns vague results; a precise brief --- what to find, what to skip, what to return --- returns a usable one.

Relation to Volume 9: subagents are Claude Code’s concrete implementation of the delegation and orchestration patterns catalogued in Volume 9. This pattern is about defining and scoping them as project files; the coordination patterns they participate in live there.

When to Use It

Delegatable, bounded jobs that benefit from an isolated context or a restricted tool set --- codebase surveys, focused reviews, parallel investigations, anything verbose enough to pollute the main thread. Less useful for tightly interactive work where the back-and-forth with the main agent is the point.

Alternatives --- a slash command (above) when an injected prompt in the main context suffices; keeping the work inline when it is short and the isolation buys nothing.

Sources

docs.claude.com/en/docs/claude-code/subagents
Volume 9 (multi-agent coordination) for the patterns subagents implement

Example artifacts

Code.

---
name: code-reviewer
description: Reviews a diff for bugs, security, and style.
tools: Read, Grep, Bash(git diff:*)
---

You are a rigorous code reviewer. Given a diff, find
correctness bugs, security issues, and convention
violations. Do not edit files. Return findings ranked
most-severe first, each with a file:line and a fix.

Section C — Permissions, hooks, and safety

Governing what the agent may do, and what must happen when it does

Claude Code acts against a real shell and filesystem, so shaping what it is allowed to do --- and interposing deterministic checks around its actions --- is where safety is engineered. This section covers the permission model that bounds the agent, the hooks that fire on its lifecycle, and the plan mode that puts a human gate before execution.

The permission model

Source: docs.claude.com/en/docs/claude-code/settings

Classification Allow / ask / deny rules that bound the agent's actions.

Intent

Bound what Claude Code may do without asking through permission rules --- allow, ask, and deny lists matched against tool calls --- so routine actions run friction-free, sensitive ones prompt for confirmation, and forbidden ones are blocked outright.

Motivating Problem

An agent that can run any shell command and edit any file is powerful and dangerous in the same breath. Prompting the human before every action is safe but unusable; allowing everything is usable but unsafe. Neither extreme works. What is needed is a policy that distinguishes the safe common case (read a file, run the tests) from the consequential one (delete files, push to a remote, touch a secret) and treats them differently --- and that a team can standardize and check in.

How It Works

Rules matched to tool calls: permissions are expressed as rules over tools and their arguments --- allow Bash(npm test:), ask Bash(git push:), deny Read(./.env). The agent runs allowed calls without interruption, pauses on ask calls for confirmation, and refuses denied ones.

Three lists, three behaviors: allow grants silent execution, deny forbids outright, and ask prompts the human. Denies take precedence, so a broad allow can be carved out by a specific deny.

Controlling file access: read and write access is governed the same way --- a deny rule on a path keeps the agent out of it regardless of what a command tries. This, alongside standard ignore files, is how sensitive files are kept outside the agent’s reach.

Permission modes: a session runs in a mode --- the default ask-when-sensitive, a plan mode that permits no edits at all (below), an accept-edits mode for trusted flows, and a bypass mode for sandboxed automation. The mode sets the baseline the rules refine.

Where the rules live: permissions are settings, so they follow the settings hierarchy --- enterprise-managed rules that cannot be overridden, the user’s defaults, the project’s shared .claude/settings.json, and personal .claude/settings.local.json. An organization can thus mandate denies that everyone inherits.

When to Use It

Every non-trivial Claude Code deployment, and mandatory for any automated or shared one. Interactive users allow their safe routines to cut confirmation friction; teams and enterprises use the shared and managed layers to enforce guardrails --- no pushes, no secret access, no destructive commands --- that hold regardless of the individual session.

Alternatives --- hooks (below) when the guardrail needs custom logic rather than a static match; OS- or container-level sandboxing (Volume 12) when the agent should be isolated from the host entirely rather than governed by in-tool rules.

Sources

docs.claude.com/en/docs/claude-code/settings
docs.claude.com/en/docs/claude-code/iam

Example artifacts

Code.

{
  "permissions": {
    "allow": ["Bash(npm test:*)", "Bash(npm run lint:*)", "Read(./src/**)"],
    "ask": ["Bash(git push:*)"],
    "deny": ["Read(./.env)", "Read(./secrets/**)", "Bash(rm -rf:*)"]
  }
}

Lifecycle hooks

Source: docs.claude.com/en/docs/claude-code/hooks

Classification Shell commands fired deterministically on agent lifecycle events.

Intent

Run your own shell commands at defined points in Claude Code’s lifecycle --- before and after tool calls, on session and turn boundaries, on prompt submission --- so policies and side effects execute deterministically rather than depending on the model choosing to perform them.

Motivating Problem

Some behaviors must happen every time, not most of the time: format code after every edit, block a dangerous command before it runs, log every action for audit, run the tests when a file changes. Asking the model to remember in its instructions is probabilistic --- it will occasionally forget under context pressure. A deterministic mechanism is needed, one the model cannot skip and cannot disable.

How It Works

Events: hooks bind to lifecycle events --- PreToolUse (before a tool runs, and able to block it), PostToolUse (after a tool runs), UserPromptSubmit (when the user sends a prompt), Stop and SubagentStop (when a turn or subagent finishes), plus Notification, PreCompact, and SessionStart. Each fires deterministically at its point in the loop.

Registered in settings, run as shell: hooks are declared in settings.json, matched to tools by a matcher, and executed as ordinary shell commands. They live outside the model --- Claude cannot turn them off --- which is exactly what makes them a trustworthy control.

Exit codes decide flow: a hook’s exit code is its verdict. Zero lets the action proceed; a non-zero exit (exit code 2 specifically) blocks the tool call and feeds the reason back to the agent. A PreToolUse hook that exits non-zero on a matched dangerous command is a hard block the model cannot argue past.

Common patterns: format-on-write (a PostToolUse hook running Prettier or Black after an edit), block-destructive-commands (a PreToolUse hook refusing rm -rf or a push to a protected branch), audit logging (a hook appending every tool call to a log), auto-test (a PostToolUse hook running the affected tests), and completion notifications (a Stop hook posting to Slack).

Discipline: hooks run real commands with real consequences, so they want the same care as any automation --- fast, because they sit in the agent’s loop; tested in isolation; and fail-safe. A slow or wrongly-exiting hook degrades every session.

When to Use It

Whenever a behavior must be guaranteed rather than encouraged --- deterministic formatting, hard safety blocks, audit trails, test gating, notifications. Especially valuable in shared and automated deployments, where “the model usually remembers” is not good enough and the guarantee has to be structural.

Alternatives --- permission rules (above) when a static allow/deny match suffices and no custom logic is needed; CLAUDE.md instructions when a soft, model-followed convention is acceptable and a hard guarantee is not required.

Sources

docs.claude.com/en/docs/claude-code/hooks

Example artifacts

Code.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "npm run format" }]
      }
    ]
  }
}

Plan mode and approval workflows

Source: docs.claude.com/en/docs/claude-code

Classification A read-only planning phase gated by human approval before execution.

Intent

Separate deciding from doing by running Claude Code in a read-only plan mode: the agent investigates and proposes a plan, a human reviews and approves it, and only then does execution begin --- so consequential work is inspected before any file is touched.

Motivating Problem

For a mechanical one-file change, letting the agent act immediately is fine. For a cross-file refactor, a schema change, or an ambiguous request, immediate action means discovering a misunderstanding after the edits are made and half-tangled. The cost of a wrong direction rises with the scope of the change, and the cheapest place to catch it is before execution, while it is still just a plan.

How It Works

Read-only investigation: in plan mode the agent may read and search but not edit, run mutating commands, or otherwise change state. It uses that freedom to understand the task and produce a concrete plan --- the steps it will take, the files it will touch, the risks it sees.

The approval gate: the plan is presented for review before anything executes. The human approves, edits, or rejects it --- the single highest-leverage control point in the workflow, because everything downstream follows from an approved plan.

Iterate before executing: a plan that is wrong is cheap to fix --- redirect and re-plan rather than undo executed work. Review is where a misread requirement or a missed constraint is caught, at a fraction of the cost of catching it in the diff.

Re-planning: if execution reveals the plan was incomplete, the agent returns to planning rather than improvising silently --- the failure mode plan mode most guards against is an agent that abandons an approved plan and drifts without saying so.

When to Use It

Cross-file refactors, schema and interface changes, unfamiliar codebases, and any request ambiguous enough that the agent’s interpretation should be checked before it acts. Overkill for single-file mechanical edits and trivial fixes, where the plan step is pure friction. It is Claude Code’s realization of the Plan-and-Execute and Human-in-the-Loop-Checkpoint patterns (Volume 1) and the pre-action-approval UX (Volume 13).

Alternatives --- an accept-edits flow for trusted, well-scoped changes where speed matters more than a gate; permission rules and hooks (above) for guardrails that do not need a full plan review.

Sources

docs.claude.com/en/docs/claude-code
Volume 1 (Plan-and-Execute; Human-in-the-Loop Checkpoint)

Section D — Headless and programmatic use

Driving the same agent from scripts, pipelines, and applications

The interactive CLI is one of three ways to drive Claude Code. This section covers the other two: headless invocation for scripts and CI, and the Agent SDK for embedding the loop in an application --- both carrying the same CLAUDE.md, permissions, and hooks as the interactive tool.

Headless mode and CI integration

Source: docs.claude.com/en/docs/claude-code (headless / print mode)

Classification Non-interactive invocation for scripts and CI pipelines.

Intent

Run Claude Code non-interactively --- one prompt in, structured output and an exit code out --- with the print flag, so a script or a CI job can drive the agent unattended as a pipeline step.

Motivating Problem

The interactive CLI assumes a human at the terminal to answer prompts and read output. A CI job has neither: an agent invocation that stops to ask a question hangs the pipeline forever, and free-form terminal output is not something a subsequent step can parse. Automation needs a mode that runs to completion without prompting and emits a result a machine can consume.

How It Works

Print mode: claude -p “prompt” runs non-interactively, prints the result to stdout, and exits with a status code. There is no interactive session and no waiting for input --- the invocation completes or fails on its own.

Structured output: an output-format option (json) returns the result as structured data rather than prose, so a pipeline step can parse the outcome, check fields, and branch on them instead of scraping text.

Non-interactivity is the point: because nothing prompts, the task must be self-contained --- a clear, standalone instruction, with permissions pre-configured so the run does not need to ask. Anything the interactive tool would ask about must be pre-allowed or pre-denied, or the run fails cleanly rather than hanging.

CI wiring: in a pipeline (GitHub Actions and the like), the agent is installed, the API key is supplied as a secret through the environment, and the job invokes claude -p with a scoped prompt. The surrounding job captures stdout, checks the exit code, validates the output shape, and sets a timeout.

Least privilege for automation: an unattended run should carry the narrowest permissions that let it do its job --- automation is exactly where an over-broad grant is most dangerous, because no human is watching.

When to Use It

Any unattended agent task: CI checks, scheduled jobs, batch operations, an agent step inside a larger script. The task must be well-defined enough to run without clarification --- automated triage, a scripted fix routine, a generated report --- rather than open-ended exploration that needs a human in the loop.

Alternatives --- the interactive CLI when a person should be present; the Agent SDK (below) when the agent is embedded in an application rather than invoked as a shell command; Volume 4’s event-and-trigger patterns for the orchestration around when the job fires.

Sources

docs.claude.com/en/docs/claude-code
Volume 4 (events and triggers) for CI and schedule invocation

Example artifacts

Code.

# CI step: run a scoped, non-interactive agent task and capture JSON output.
# ANTHROPIC_API_KEY is provided as a CI secret in the environment.

claude -p "Triage the failing tests in this PR and summarize the likely cause." \
  --output-format json > result.json

# Fail the job if the agent run did not succeed.
test $? -eq 0 || { echo "agent run failed"; exit 1; }

The Claude Agent SDK

Source: docs.claude.com/en/docs/claude-code/sdk

Classification The agent loop as a library for embedding in applications.

Intent

Embed Claude Code’s agent loop inside an application through the Agent SDK, constructing sessions programmatically --- with the same tools, permissions, and CLAUDE.md context as the CLI --- so the agent becomes a component of a larger system rather than a tool a human drives.

Motivating Problem

The interactive CLI and headless mode both put the agent at the edge of the system --- a human or a pipeline invoking a command. Some products need the agent inside: a code-review bot, a documentation generator, a support agent that runs the coding loop as part of a service. Shelling out to the CLI from application code is brittle; what is needed is the loop as a library, driven by code with full control over inputs and outputs.

How It Works

Sessions in code: the SDK constructs agent sessions programmatically --- setting the model, the system prompt, the tool permissions, and the working directory --- and drives them with prompts from application code rather than a terminal. It is available for TypeScript and Python.

Same substrate as the CLI: an SDK session reads the same CLAUDE.md context, honors the same permission rules, and fires the same hooks as the interactive tool. The configuration patterns in this volume carry over; the difference is who drives the loop.

Streaming and events: the SDK surfaces the agent’s progress as a stream of events --- tool calls, outputs, errors --- so the embedding application can display, log, or react to each step rather than waiting for a final result.

SDK versus API: the API is a single model completion with no loop, no tools, and no filesystem; the SDK is the full agent loop with all three. The choice is whether the application needs an agent (tools, iteration, files) or a completion (one call). Reaching for the API and rebuilding the loop by hand is the common mistake the SDK exists to prevent.

When to Use It

When the agent is a component inside an application rather than a tool at its edge --- review bots, generators, embedded coding assistants, any service that runs the loop as part of its own logic. Less appropriate when a human should drive (use the CLI) or when the task is a self-contained pipeline step (use headless mode).

Alternatives --- headless mode for shell-invoked automation; the raw Claude API (Volume 2, claude-api) when a model completion, not an agent, is what the application needs; the frameworks of Volume 9 when orchestrating many agents rather than embedding one.

Sources

docs.claude.com/en/docs/claude-code/sdk
Volume 9 (Claude Agent SDK subagents); Volume 14 (agent SDKs among products)

Appendix A --- The configuration files at a glance

The files and directories Claude Code reads, and what each is for:

~/.claude/CLAUDE.md --- personal standing instructions, applied across all projects.
./CLAUDE.md --- shared project instructions, checked into version control.
.//CLAUDE.md --- instructions scoped to a subtree of the project.
~/.claude/settings.json --- personal settings: permission defaults and hooks.
.claude/settings.json --- shared project settings, checked in.
.claude/settings.local.json --- personal project settings, git-ignored.
.claude/commands/*.md --- custom slash commands (filename becomes the command).
.claude/agents/*.md --- project subagents (name, tools, and prompt per file).
Enterprise-managed settings --- organization policy, taking precedence over all of the above and not overridable by the user.

Appendix B --- Relation to the rest of the series

This volume is the operational companion to several others. Volume 2 catalogs skills, the portable capability artifacts that Claude Code also reads; Volume 3 catalogs the tool primitives the permission model governs and the design craft behind them; Volume 9 catalogs the multi-agent coordination patterns that subagents implement; Volume 12 supplies the least-privilege and sandboxing disciplines the permission model and hooks apply in-tool; Volume 13 supplies the human-in-the-loop UX that plan mode realizes; Volume 14 places Claude Code among the comparable coding-agent products; and Volume 15 supplies the context-window economics that make CLAUDE.md concision matter. Read this volume for how to configure and drive the tool; read those for the disciplines the configuration expresses.

--- End of The Claude Code Configuration & Workflows Catalog v0.1 ---