The Claude Code Configuration & Workflows Catalog

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

Intent

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

Motivating Problem

Each session starts with a fresh context window; continuity comes from CLAUDE.md files the team writes and auto memory notes Claude writes, both loaded at session start. Without written-down 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 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 (or .claude/CLAUDE.md), checked into the repository, carries shared team conventions; a CLAUDE.local.md beside it holds personal project preferences and is git-ignored; and .claude/rules/ holds topic files, optionally scoped to paths (see Path-scoped rules and auto memory, below). Files in the working directory and the directories above it load at launch; CLAUDE.md files in subdirectories load on demand, when Claude reads or edits a file in that subtree. A repository set up for other agents with an AGENTS.md and no CLAUDE.md has its AGENTS.md read in place of CLAUDE.md.

No enforced precedence: all discovered files are concatenated into context rather than overriding each other, ordered from the filesystem root down, so more specific files appear later. Nothing enforces which wins; if two instructions contradict, Claude may follow either one. Keep the layers consistent, and use managed settings or hooks for anything that must hold. Personal preferences still belong in the user or local 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 import other files with @path syntax (paths resolve relative to the importing file, up to four hops deep), so large or shared instruction sets need not be duplicated; imports from outside the project ask for a one-time approval. Imports organize a file but do not reduce its context cost. The file is editable directly, through the /memory command, by asking Claude to add an instruction to CLAUDE.md, 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

• code.claude.com/docs/en/memory

• code.claude.com/docs/en/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.

Source: Anthropic Claude Code best-practices guidance

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. The memory docs target under 200 lines per CLAUDE.md; move rules that matter for only part of the codebase into path-scoped .claude/rules/ files.

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

• code.claude.com/docs/en/memory

• code.claude.com/docs/en/best-practices

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

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

• code.claude.com/docs/en/memory

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

Intent

Split standing context so each piece loads only when it applies: topic rule files in .claude/rules/, optionally scoped to file paths so they load only when Claude works on matching files, and auto memory, a per-repository set of notes Claude writes and reads back across sessions.

Motivating Problem

A single CLAUDE.md grows. Frontend rules, API conventions, migration procedures, and the test setup all end up in one file that every session pays for, though most sessions touch one area. Meanwhile the corrections a developer gives during a session (“use pnpm, not npm”, “the API tests need a local Redis”) are lost when the session ends unless someone stops to edit CLAUDE.md. The team needs a way to load area-specific rules only where they matter and a place for learned facts that nobody has to curate by hand.

How It Works

Rules directory: markdown files in .claude/rules/ (discovered recursively, one topic per file) load like CLAUDE.md. A rule with no paths frontmatter loads at launch with the same priority as .claude/CLAUDE.md. Personal rules in ~/.claude/rules/ apply to every project on the machine, and shared rule sets can be symlinked in.

Path scoping: a paths list in a rule’s YAML frontmatter (for example src/api/**/*.ts) makes it conditional. The rule loads when Claude reads, writes, or edits a matching file, so API conventions cost nothing in a session that never touches the API. This is the documented place for instructions that would push a CLAUDE.md past its target of about 200 lines.

Auto memory: on by default in local sessions, Claude saves notes for itself as it works, in four kinds (user, feedback, project, reference), and skips anything it can derive from the code or that CLAUDE.md already says. Notes live in ~/.claude/projects//memory/, one directory per git repository shared across its worktrees, as a MEMORY.md index plus topic files. The first 200 lines or 25KB of MEMORY.md load at the start of every session; topic files are read on demand. Auto memory is machine-local and not shared with teammates.

Control: /memory lists the loaded files, toggles auto memory, and opens the memory folder; autoMemoryEnabled in settings or CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 turns it off. Asking Claude to remember something saves it to auto memory; asking it to add something to CLAUDE.md writes there instead. Both CLAUDE.md and auto memory are context, not enforced configuration: for anything that must hold, use permissions or a PreToolUse hook (Section C).

When to Use It

Path-scoped rules: monorepos and any project whose CLAUDE.md is growing past a screen or two with rules that apply to one area. Auto memory: individual developers who want corrections to stick without editing shared files; review it periodically, since it is plain markdown that can go stale.

Alternatives: subdirectory CLAUDE.md files when the split follows directories rather than file patterns; a single short CLAUDE.md for small projects; turning auto memory off where sessions must start identical, such as CI (headless mode’s —bare skips it).

Sources

• code.claude.com/docs/en/memory

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

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.

Commands are now skills: custom commands have been merged into skills (Volume 2). A file at .claude/skills/review-pr/SKILL.md creates the same /review-pr and is the recommended format for new work; it can carry supporting files in its directory, and Claude can invoke it on its own when relevant. The .claude/commands file is the older format and keeps working. Set disable-model-invocation: true in the frontmatter to keep a command user-only.

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

Arguments: a command takes input through the $ARGUMENTS placeholder, 0-based positional $0, $1 (also written $ARGUMENTS[N]), or named arguments declared in frontmatter, 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; a plugin (below) to ship a set of commands to many repositories at once.

Sources

• code.claude.com/docs/en/skills

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.

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

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 (project) or ~/.claude/agents (user) with YAML frontmatter followed by its system prompt. Only a name and a description of when it should be used are required; optional fields include the tools it may call, the model, skills to preload, MCP servers, hooks, and persistent memory. To create one, ask Claude to write it or write the file directly; the /agents command now only prints that reminder (the interactive wizard was removed after v2.1.197). 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. The fields that matter most are tools and disallowedTools (an allowlist and a denylist; a disallowedTools entry such as Bash(git push *) removes the whole tool, so block single commands with a permissions deny rule instead), permissionMode, isolation: worktree (the subagent works in a temporary git worktree), and maxTurns. 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.

Nesting and the SDK: by default a subagent can spawn subagents of its own, up to three levels below the main conversation. The same subagent definitions are available to applications through the Claude Agent SDK (Section D), which exposes the primitive for teams to define their own subagent types.

Relation to Volume 9: subagents are Claude Code’s concrete implementation of the delegation and orchestration patterns catalogued in Volume 9 (Agents-as-tools is the closest entry); The Claude Agent SDK entry in this volume covers the same feature from the framework side. This entry is the series’ home for defining and scoping them; 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

• code.claude.com/docs/en/sub-agents

• 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.

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

Intent

Bundle a team’s Claude Code configuration (skills and commands, subagents, hooks, and MCP servers) into a plugin that installs as one unit from a marketplace, so the same setup reaches every repository and every developer without copying files by hand.

Motivating Problem

The extensions in this section and the hooks in Section C each work on their own, as files in one repository or one home directory. A team with twenty repositories that wants the same review command, the same reviewer subagent, and the same format-on-write hook ends up copying .claude directories around, and the copies drift. Fixes have to be applied everywhere, and there is no version to point at. The need is a package format with a source, a version, and an install step.

How It Works

What a plugin is: a directory of components, usually with a manifest at .claude-plugin/plugin.json that gives it a name and optionally a version and description. Components include skills (which also run as commands), agents (subagent definitions), hooks, and MCP servers.

Marketplaces: a marketplace is a repository or directory with a .claude-plugin/marketplace.json that lists plugins and where to fetch each one; it is a catalog, not a hosted store. Teams add a marketplace once and install from it by name, for example commit-commands@claude-plugins-official. Claude Code adds Anthropic’s official marketplace on first interactive start; any other marketplace, including one a team publishes, is third-party. During development a plugin loads straight from its folder with —plugin-dir.

Install scopes: user scope enables a plugin in every project on the machine; project scope enables it for everyone in the repository through the committed .claude/settings.json (each collaborator still installs it locally); local scope enables it for one person in one repository.

Cost and trust: an enabled plugin is part of every session. The names and descriptions of its model-invocable skills and agents sit in context on every turn, its MCP servers run alongside each session, and its hooks fire at their events. Whatever it runs, it runs with the user’s privileges, so review a third-party plugin before installing it. Plugin subagents ignore the hooks, mcpServers, and permissionMode frontmatter fields. Through managed settings an organization can allowlist or block marketplaces and force-install plugins.

When to Use It

When the same set of commands, subagents, hooks, or MCP servers should apply across several repositories or a whole organization, or when a team wants versioned releases of its setup. For a single repository, plain files in .claude are simpler.

Alternatives: checked-in .claude directories for one repository; Volume 2’s skill marketplaces when only skills need to travel, including to other agents; managed settings when the goal is policy rather than capability.

Sources

• code.claude.com/docs/en/plugins

• code.claude.com/docs/en/sub-agents (plugin subagent restrictions)

• Volume 2 (skills and skill marketplaces)

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

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 older Bash(npm test:) form is an accepted equivalent of the trailing space-star. 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. Rules are evaluated deny, then ask, then allow, and specificity does not change that order: an allow can never carve an exception out of a deny, and an ask prompts even when a more specific allow also matches.

Controlling file access: read and write access is governed the same way. Read deny rules, for example Read(./.env) and Read(./secrets/**), are how sensitive files are kept out of the agent’s reach; a .claudeignore file is not honored, so its entries belong in Read deny rules.

Permission modes: a session runs in one of six modes. Manual (config value default) asks before most edits, shell commands, and network access; acceptEdits runs file edits and common filesystem commands without asking; plan permits reads and research but no source edits (below); auto has a background classifier review each action instead of prompting (see Auto mode, below); dontAsk auto-denies anything that would prompt, which suits locked-down CI; and bypassPermissions skips checks, for isolated containers and VMs only. The mode sets the baseline the rules refine; deny rules apply in every mode.

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

• code.claude.com/docs/en/permissions

• code.claude.com/docs/en/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 *)"]
  }
}

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

Intent

Let Claude Code work through long tasks without routine permission prompts by routing each tool call through a separate classifier model that blocks anything irreversible, destructive, beyond the request, or aimed outside the trusted environment, while deny and ask rules still apply first.

Motivating Problem

Allow lists are static. A long task touches commands nobody thought to pre-approve, so the session either stops to ask (and an unattended run stalls) or the team widens the allow list until it means little. Bypass mode removes the prompts and every check with them. What is needed is a gate that judges each action in context, the way a reviewer would, without a human answering every prompt.

How It Works

The classifier: in auto mode a second model reviews actions before they run, blocking anything that escalates beyond the user’s request, targets unrecognized infrastructure, or appears driven by hostile content Claude read. It is a second gate after the permission rules: deny rules block and explicit ask rules prompt before the classifier is consulted. Since v2.1.283 auto mode is the built-in starting mode for interactive terminal and VS Code sessions; claude -p and SDK runs start in Manual mode unless told otherwise.

Trusted infrastructure: by default the classifier trusts only the working directory and the current repository’s configured remotes. The autoMode settings block adds trusted repositories, buckets, and domains (environment) and replaces the built-in rule lists: hard_deny (unconditional), soft_deny (destructive actions that explicit user intent can clear), and allow (exceptions to soft_deny). Rules are prose, read as natural language; including the string “$defaults” in a list keeps the built-in entries. The classifier also reads CLAUDE.md, so a project instruction such as “never force push” steers it too.

Where it is configured: autoMode is read from user settings, managed settings, and the —settings flag or SDK, never from the repository’s .claude/settings.json, so a checked-in file cannot grant itself trust. Entries combine across scopes, and a developer’s allow entry can override an organization’s soft_deny, so autoMode is not a hard policy boundary; for that, use permissions.deny in managed settings. Administrators can turn auto mode off with permissions.disableAutoMode.

Fallback and review: blocked actions appear under Recently denied in /permissions, where they can be retried. After three blocks in a row or twenty in a session, auto mode pauses and prompting resumes. claude auto-mode defaults prints the built-in rules, and /auto-mode-setup drafts environment entries from the project and recent sessions and writes them to ~/.claude/settings.json, where the example below belongs.

When to Use It

Long interactive tasks where the general direction is trusted and prompt fatigue is the problem, and unattended runs that need judgment rather than a fixed allow list. The docs warn it reduces prompts but does not guarantee safety, so keep ask rules on pushes and other consequential actions, and keep sensitive work in Manual mode.

Alternatives: static permission rules (above) when the set of actions is known in advance; dontAsk mode for locked-down CI where anything not pre-approved should fail; bypassPermissions only inside an isolated container or VM (Volume 12).

Sources

• code.claude.com/docs/en/permission-modes

• code.claude.com/docs/en/auto-mode-config

Example artifacts

Code.

{
  "permissions": {
    "ask": ["Bash(git push *)", "Bash(gh pr create *)"]
  },
  "autoMode": {
    "environment": [
      "$defaults",
      "Source control: github.com/example-org and all repos under it"
    ]
  }
}

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

Intent

Run your own 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 SessionStart, SessionEnd, PermissionRequest, PreCompact, and Notification. There are more than thirty events in all; the full list is in the hooks reference. Each fires deterministically at its point in the loop.

Registered in settings, run outside the model: hooks are declared in settings.json, matched to tools by a matcher, and executed as shell commands, HTTP calls, MCP tool calls, or model-evaluated prompts (agent hooks are experimental). They live outside the model --- Claude cannot turn them off --- which is exactly what makes them a trustworthy control.

Exit codes decide flow: a command hook’s exit code is its verdict. Exit 0 proceeds; exit 2 blocks the action (on events that support blocking) and returns stderr to Claude; any other non-zero exit, including 1, is a non-blocking error and the action still runs, unless the hook sets onFailure to “block”. A PreToolUse guard must therefore exit 2 to be 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; Volume 2’s git-guardrails-claude-code skill is a packaged example), 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

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

• Volume 2, Section F (mattpocock/skills, whose git-guardrails-claude-code is a hook packaged as a skill)

Example artifacts

Code.

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

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

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, search, and run read-only shell commands (or, where auto mode is available, commands its classifier approves), but not edit source files until the plan is approved. 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 pattern and of Volume 1’s Human-in-the-Loop Checkpoint, the base pattern for every approval gate in the series; Volume 7 covers human-in-the-loop design in depth and Volume 13 the pre-action-approval UX.

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; spec-driven development (Section E) when the plan should outlive the session as a reviewed document.

Sources

• code.claude.com/docs/en/permission-modes

• Volume 1 (Plan-and-Execute; Human-in-the-Loop Checkpoint); Volume 7 (human-in-the-loop)

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

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: —output-format json (or stream-json for newline-delimited events) 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. When the next step needs a fixed shape, add —json-schema; the schema-conforming result arrives in a structured_output field, which the script should check is present before using.

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. Pass —allowedTools for what the job needs and —permission-mode dontAsk so anything else is denied rather than waiting for an answer.

Reproducible runs: in CI, add —bare. It skips auto-discovery of hooks, skills, commands, subagents, plugins, MCP servers, auto memory, and CLAUDE.md, so the run does not depend on what happens to be on the runner; the docs recommend it for scripted calls and say it will become the -p default. Without —bare, claude -p runs the hooks in the repository’s .claude/settings.json and connects the servers in its .mcp.json with no trust dialog, which matters when the job checks out untrusted code.

CI wiring: in a pipeline (GitHub Actions has its own integration and docs page), the agent is installed, the API key is supplied as a secret through the environment, and the job invokes claude —bare -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

• code.claude.com/docs/en/headless

• code.claude.com/docs/en/github-actions

• 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 --bare -p "Triage the failing tests in this PR and summarize the likely cause." \
  --allowedTools "Read,Grep,Bash(npm test *)" \
  --permission-mode dontAsk \
  --output-format json > result.json

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

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

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 (the claude-agent-sdk-typescript and claude-agent-sdk-python packages, renamed from the Claude Code SDK) and runs the Claude Code binary underneath.

Same substrate as the CLI: an SDK session gets the same built-in tools, permissions, hooks, subagents, MCP servers, and sessions that can be resumed or forked, and loads skills, commands, and CLAUDE.md memory from the project’s .claude/ and from ~/.claude/, as Claude Code does. Plugins load by local path. 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.

Where it sits among Anthropic’s options: the choice is four-way. The Agent SDK embeds Claude Code’s loop and tools in a process you operate. The Client SDK calls the API directly; you write the tool loop yourself or let its beta tool runner drive it over tools you define. Managed Agents has Anthropic host the agent harness, with sessions in an Anthropic-managed cloud sandbox or a self-hosted one. The CLI covers interactive and one-off work. Rebuilding Claude Code’s file and shell tools by hand on the raw API is the mistake the Agent SDK prevents; a tool runner over your own tools, or a hosted harness, are the alternatives when you do not want Claude Code’s tools or do not want to run the process.

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 Client SDK’s tool runner when the application owns its tools and wants Anthropic’s SDK to run the loop; Managed Agents when Anthropic should host the harness; 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

• code.claude.com/docs/en/agent-sdk/overview

• platform.claude.com/docs/en/agents-and-tools/tool-use/tool-runner; platform.claude.com/docs/en/managed-agents/overview

• Volume 9 (Agents-as-tools, the pattern SDK subagents implement) and Volume 14 (Section C, Agent frameworks, which points here); this entry is the series’ home for the SDK

Source: martinfowler.com/articles/exploring-gen-ai/sdd-3-tools.html

Intent

Write a structured, behavior-oriented specification in natural language before any code, then have the coding agent derive a plan and a task list from it and implement task by task, with a human reviewing each artifact, so the spec becomes the shared source of truth for the human and the agent.

Motivating Problem

A detailed prompt for a feature lives in one session and is gone when the session ends. Plan mode (Section C) puts a gate before execution, but the approved plan is not kept, and the next change to the same feature starts from nothing. As features grow, the agent’s interpretation of the request becomes the only record of what was wanted. Teams want the intent written down in a reviewable form that outlasts a session.

How It Works

Levels: Birgitta Böckeler’s survey (October 2025) distinguishes spec-first (a spec is written and used for the task at hand), spec-anchored (the spec is kept after the task and used to evolve the feature), and spec-as-source (only the spec is edited; the code is generated from it). Every approach she found is spec-first; not all aim for the other two.

Specs versus memory bank: a spec covers the functionality a task creates or changes, while general context (rules files, CLAUDE.md, product descriptions) applies to every session. Tools keep the two apart.

Kiro: three steps (Requirements, Design, Tasks), one markdown document each, inside a VS Code based IDE. Requirements are user stories with GIVEN/WHEN/THEN acceptance criteria; tasks trace back to requirement numbers. Kiro calls its memory bank “steering”.

GitHub Spec Kit: a CLI that sets up the workspace for many coding assistants, after which the steps run as slash commands: constitution (immutable high-level principles), then specify, plan, and tasks. Each step produces several files with checklists, and each spec gets its own branch.

Tessl: a CLI that also runs as an MCP server, and the only one of the three that explicitly aims at spec-anchored development and explores spec-as-source, with specs written per code file and generated code marked as such.

Review at every phase: the artifacts are only as good as the human review of them. Böckeler reports that the heavier tools produce many repetitive markdown files, that a small bug fix became four user stories with sixteen acceptance criteria, and that the agent sometimes ignored notes in the spec (regenerating existing classes as duplicates) or followed instructions too eagerly.

When to Use It

Features of medium size where a written requirement and design would be produced anyway, and teams that want the spec kept for later changes. Match the tool’s ceremony to the problem: for a small fix, a short spec in the prompt or plan mode is enough.

Alternatives: plan mode (Section C) for an approval gate without kept artifacts; Volume 2’s context-driven-development and Rosetta entries for related methodologies packaged as skills and tools; a hand-written spec file referenced from CLAUDE.md when no dedicated tool is wanted.

Sources

• martinfowler.com/articles/exploring-gen-ai/sdd-3-tools.html (Birgitta Böckeler, 15 October 2025)

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.local.md --- personal project instructions, git-ignored.

• .//CLAUDE.md --- instructions scoped to a subtree of the project, loaded on demand.

• .claude/rules/.md and ~/.claude/rules/.md --- topic rule files, optionally scoped to paths.

• ./AGENTS.md --- read in place of CLAUDE.md when the repository has no CLAUDE.md.

• ~/.claude/projects//memory/ --- auto memory written by Claude (MEMORY.md index plus topic files).

• ~/.claude/settings.json --- personal settings: permission defaults, hooks, and autoMode.

• .claude/settings.json --- shared project settings, checked in.

• .claude/settings.local.json --- personal project settings, git-ignored.

• .claude/skills//SKILL.md --- slash commands as skills (recommended format).

• .claude/commands/*.md --- custom slash commands, older format (filename becomes the command).

• .claude/agents/.md and ~/.claude/agents/.md --- project and user subagents (name, description, and prompt per file).

• .claude-plugin/plugin.json --- a plugin’s manifest; .claude-plugin/marketplace.json lists plugins in a marketplace.

• Enterprise-managed settings --- organization policy, taking precedence over all of the above; user and project settings cannot override them, apart from a few documented keys.

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 (custom commands are now a form of skill), and skill marketplaces, while plugins that package Claude Code configuration are covered here; 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, while this volume is the home for Claude Code subagents and the Claude Agent SDK; Volume 12 supplies the least-privilege and sandboxing disciplines the permission model and hooks apply in-tool; Volume 1’s Human-in-the-Loop Checkpoint is the base pattern plan mode realizes, and Volumes 7 and 13 supply the human-in-the-loop design and UX; 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 ---