Workflow · last verified 2026-10-05

The Claude Code workflow: how AI-native engineers actually run it

Most of this workflow lives at layer 2 of the AI quality stack: context engineering — what the agent loads, prunes, and delegates, shaping every decision before any later gate gets a look at the output. Step 4's plan permission mode is a working instance of layer 1, spec-first development: a read-only plan you approve before a single edit lands, not a review of code already written.

Part of the AI quality stack — the layered gate chain for knowing your LLM is delivering quality.

The job this workflow does

Claude Code is an agent that reads your repo, edits files, and runs commands. Used naively — one long chat session, instructions repeated by hand, output eyeballed — it produces the failure modes the official docs now name outright: the kitchen-sink session, correcting-over-and-over, the trust-then-verify gap. The workflow's job is to replace ad-hoc chat with an operable system: the rules live in files the agent loads, verification is a check the agent can run itself, and the expensive resource — the context window — is spent deliberately. Anthropic's own best-practices doc is blunt about the core constraint: the context window is the resource. Everything below is organized around protecting it.

We run this workflow building aiArch itself — a production platform whose repo is operated daily by Claude Code sessions and subagents. The prescriptions here are the ones that survived that use. For where Claude Code sits among the other agentic coding tools, see the tool landscape guide; this page assumes you've picked it.

The workflow

1. Install and bootstrap the repo

Claude Code runs as a CLI, in the desktop app (macOS/Windows, Linux beta), at claude.ai/code, and inside VS Code and JetBrains; it's bundled in all paid plans from Pro up. Start in the terminal — the CLI is where the whole configuration surface lives. In a fresh repo, run /init to generate a starter CLAUDE.md, then commit it: it's project documentation for agents, and it belongs in version control like any other interface contract.

claude          # start a session in the repo root
/init           # generate CLAUDE.md from the codebase
git add CLAUDE.md && git commit -m "docs: agent operating instructions"

Adopt the prune discipline on day one. The docs carry a first-party warning: "Bloated CLAUDE.md files cause Claude to ignore your actual instructions." The test for every line: would removing it cause the agent to make a mistake? If not, cut it.

2. Encode the rules — advisory in CLAUDE.md, deterministic in hooks

Memory is layered: ~/.claude/CLAUDE.md for your personal conventions across projects, ./CLAUDE.md committed for the team, ./CLAUDE.local.md gitignored for your machine-local quirks; parent and child directory files load as you work in them, and @path imports let you split without duplicating. If the repo already carries an AGENTS.md for other coding tools, Claude Code (v2.1.277+) reads it as the project instructions, but only while no CLAUDE.md or CLAUDE.local.md sits in the working directory or above it; add one and the AGENTS.md silently stops loading, unless your CLAUDE.md imports it with @AGENTS.md. But CLAUDE.md is advisory — the model can drift from it. For rules that must always hold, use hooks: the docs describe them as "deterministic, unlike advisory CLAUDE.md". Hooks live in settings.json (user, project, or local scope), fire on events like PreToolUse, PostToolUse, Stop, and SessionStart, and can block an action with exit code 2 or {"decision":"block"}, inject context, or rewrite tool input.

// .claude/settings.json — block any edit that fails typecheck
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "npm run typecheck" }]
      }
    ]
  }
}

The split is the point: prose for judgment ("prefer editing over creating files"), hooks for law ("typecheck must pass"). Wire external context in the same pass — claude mcp add registers MCP servers, and project scope commits a .mcp.json so the whole team gets the same tools.

A hook in settings.json being committed and correctly formatted is not the same claim as it firing — a wrong gate condition can sit in a clean file for weeks with no error. If you manage Claude API agents and skills as versioned config with ant apply, declared is not enforced covers what its plan/apply lockfile can and can't tell you.

3. Package repeated procedures as skills

The third time you type the same multi-step instruction, it's a skill. A skill is a directory — .claude/skills/<name>/SKILL.md — whose name becomes a slash command and whose body loads on demand, so it costs no context until invoked. The frontmatter carries name, description (which drives when the model invokes it unprompted), and optionally allowed-tools, model, and argument-hint; $ARGUMENTS substitutes what you pass. Custom commands (.claude/commands/*.md) have merged into the same mechanism, and the format is an open standard (agentskills.io).

# .claude/skills/release/SKILL.md
---
name: release
description: Ship to production - gates, deploy, post-deploy verification
argument-hint: [component]
---
1. Run the pre-release gates: typecheck, full test suite.
2. Deploy $ARGUMENTS with npx wrangler deploy.
3. Verify live: hit /api/health, confirm the new version responds.

Our repo runs release, incident-response, and weekly-metrics procedures this way. The payoff is consistency: the procedure executes the same on the tenth run as the first, regardless of who — or which session — invokes it. For the context-budget trade-off of "costs no context until invoked" — and what it costs once it is invoked and stays loaded — see skills vs subagents vs hooks.

4. Set the permission posture

Pick the posture deliberately instead of clicking through prompts. Shift+Tab cycles modes in-session; protected paths (.git, .claude, .mcp.json, shell rc files) are never auto-approved in any mode.

Since 14 Aug 2026, new interactive sessions on Pro, Max and Team plans have started in auto rather than default. The Claude Code changelog then widened that in three steps: v2.1.283 (25 Sep 2026) made it the start mode for interactive sessions on third-party providers or with telemetry off; v2.1.284 (28 Sep) extended that to the terminal and the VS Code extension on every plan and provider; v2.1.285 (29 Sep) brought claude -p and Python Agent SDK sessions in too, but only on third-party providers or with telemetry off. Auto mode itself is available on all plans, and an organization can switch it off with disableAutoMode in managed settings. Two carve-outs matter: a claude -p run or Agent SDK session that fetches feature flags (in practice a first-party session with telemetry on) usually still starts in default, and a project settings file cannot make auto the default (your user or managed settings, or --permission-mode, can). Anthropic's own controlled study of 1,053 paid testers found the auto-mode classifier caught 89% of a set of dangerous commands against 13.6% for humans approving prompt-by-prompt, a gap that widened with session length — though Anthropic's own caveat is that the classifier "relies on classification systems and therefore does not eliminate risk". An org that pins defaultMode in managed settings is unaffected by the shift. Anthropic's announcement has the study detail. What we run: our user-level settings pin permissions.defaultMode to auto, and this repo's committed .claude/settings.json sets no mode at all. We switch to acceptEdits when we want to read the diff ourselves, and the hooks from step 2 carry the rules that must hold in every mode. The 13.6% figure is the case for choosing a mode on purpose, not for trusting whatever ships as default.

For isolation, use worktrees: claude --worktree feature-x gives the session its own checkout under .claude/worktrees/ on branch worktree-feature-x, so parallel sessions can't stomp each other. One gotcha we hit in practice: worktrees branch from origin/HEAD by default, so unpushed local commits are absent — set worktree.baseRef: "head" to branch from local HEAD, and list gitignored files the session needs (like .env) in .worktreeinclude. claude --worktree "#1234" checks out a PR directly; the desktop app gives every session a worktree automatically.

5. Work the loop: explore → plan → implement → commit

The core loop, per the canonical best-practices doc: have the agent explore the relevant code first, plan the change, then implement and commit. Skip the plan step only when the diff fits in one sentence. Two disciplines carry most of the value:

Give Claude a check it can run. A test, a build, a screenshot — anything that turns "looks done" into "verified done" without you in the loop. When output quality needs escalating pressure, the docs prescribe a ladder: iterate in the same prompt → set a /goal → gate completion with a Stop hook → adversarial subagent review.

Protect the window. /clear between unrelated tasks, every time. After two failed corrections, stop correcting — /clear and write a better prompt; a polluted context re-derives the same mistake. Use /compact <instructions> to steer what survives compaction, and /rewind (Esc Esc) to walk back a wrong turn instead of arguing with it.

6. Delegate investigation to subagents

Reading is the cheapest thing to delegate and the most expensive thing to hoard: a broad codebase question answered in the main session fills your window with file dumps you'll pay for on every subsequent turn. Use the built-in Explore agent (read-only) for searches and Plan for design work. Explore runs on your session's model, with one carve-out: when the session runs Fable on a subscription, a Console account or an LLM gateway, it drops to the model the opus alias resolves to. To get cheap exploration, define your own subagent named Explore with model: haiku; it overrides the built-in. Define the rest of your roster in .claude/agents/*.md — YAML frontmatter with name, a description that drives automatic delegation, tools, model (sonnet/opus/haiku/inherit), and optional isolation: worktree. Since v2.1.198 there's no /agents wizard — you edit the files directly, which is better anyway: they're code.

# .claude/agents/security-reviewer.md
---
name: security-reviewer
description: Reviews diffs for injection, authz gaps, and secret leaks
tools: Read, Grep, Glob
model: opus
---
Review the given diff as a hostile auditor. Report findings with
file:line evidence. Never propose fixes - only findings.

One design decision surprises people: the built-in Explore and Plan agents deliberately omit CLAUDE.md from their context. Repo-specific rules you need enforced during investigation must travel in the prompt you give the subagent. This is one of several harness defaults worth knowing before you delegate, including the model a subagent inherits; the agent harness defaults guide lists them with the override for each. For how isolation bounds a subagent's blast radius — and where it doesn't, on its own — see skills vs subagents vs hooks.

7. Scale out with dynamic workflows when work fans out

This is the feature named workflows. When a task fans out beyond a few subagents — audit every route, migrate every module, verify every claim — dynamic workflows have Claude write a JavaScript orchestration script that the runtime executes in the background, keeping intermediate results in script variables instead of your context window. Requires v2.1.154+, available on all paid plans (Pro enables it in /config). Invoke with the keyword ultracode (pre-v2.1.160 it was workflow), natural language ("use a workflow"), /effort ultracode (v2.1.203+), or the bundled /deep-research.

// .claude/workflows/audit-routes.js - saved workflows run as /audit-routes
export const meta = { name: 'audit-routes', description: 'Audit every API route for authz gaps' };

const routes = await agent('List every API route in src/routes with file:line', {
  schema: { routes: 'array' },
  label: 'enumerate',
});
const findings = await pipeline(routes.routes, (r) =>
  agent(`Audit ${r} for missing auth checks; report file:line evidence`)
);

The primitives are plain JS with top-level await: agent(prompt, {schema, label}) and pipeline(list, fn). Save a workflow from the /workflows picker with s; they live in .claude/workflows/ (project) or ~/.claude/workflows/. Know the limits before you lean on it: 16 concurrent agents, 1,000 per run, no mid-run input, and the agents use your permission rules, with their mode following the subagent rules (a subagent runs in your session's mode when that is acceptEdits, auto or bypassPermissions) — so your permission posture from step 4 is load-bearing here. Cost is real: v2.1.203+ flags "large workflows" (>25 agents or >1.5M tokens) with an advisory warning that does not stop the run, a size guideline in /config is advice to Claude rather than a hard cap, and you can disable the feature entirely with CLAUDE_CODE_DISABLE_WORKFLOWS=1. For a handful of tasks per turn, plain subagents are cheaper and simpler — reach for this at codebase-audit and large-migration scale.

8. Verify adversarially

The docs' reasoning for evidence-over-assertion is the right one: the agent doing the work isn't the one grading it. Structure verification so fresh context does the judging. The Writer/Reviewer split — one session (or subagent) writes, a second with clean context reviews the diff — catches what the writer's context has rationalized away. /code-review packages this; the security-reviewer agent from step 6 is the same pattern pointed at a threat model. The rule we enforce: a claim of "done" must arrive with evidence — a passing test run, a screenshot, a curl of the live endpoint — never an assertion.

9. Automate headless

Everything above scripts. claude -p "prompt" runs non-interactively, --output-format json (or stream-json) makes output machine-readable, and --allowedTools scopes exactly what CI may do:

# CI: triage a failing log
cat error.log | claude -p "Identify the root cause; output JSON" --output-format json

# Scoped autonomous fix
claude --permission-mode auto -p "Fix the lint errors" \
  --allowedTools "Edit,Bash(git commit *)"

The workflow ends where it started: the repo you bootstrapped in step 1 is now operable by an agent with no human present — because the rules, procedures, and checks all live in files.

As built: two failures that only appear at fan-out scale

Steps 6 and 7 are where operating this repo has cost the most to get wrong, and in both cases the defect was in the briefing rather than in any agent. Neither is visible in a single session — they need two or more agents reading the same instruction before they bite.

Generate a shared brief's concrete lists from disk, never from recall

On 2026-07-16 one instruction fanned out to six parallel subagents converting 35 public pages. The brief carried a menu of internal cross-link targets, and one entry was written from memory: /patterns/eval-gate. The real slug is /patterns/eval-harness-gate. Two agents wrote the broken link before a third reported back that the brief was wrong; a grep of the combined diff for the brief-supplied literal then found and fixed both, pre-commit.

The delta from single-session work is the multiplier, and it runs the wrong way. A wrong fact in your own prompt costs one correction. A wrong fact in a shared brief is transcribed faithfully by every agent that reads it, and the copies then corroborate each other — several independent-looking outputs agreeing is exactly what a review pass treats as evidence. The same mechanism bit us two days later with CLI invocations instead of slugs: two commands written into a plan from memory were transcribed by the writers and cleared five review passes into a merged PR. So the rule is mechanical, not a matter of care: every slug, path, URL, anchor id, and command that goes into a fan-out brief gets listed from ls or grep at authoring time, and when the fan-out returns you grep the combined diff for each literal the brief supplied and read the hits. Both steps take seconds and they are the cheapest checks in the loop.

Choose the interaction mode per handoff, not once for all of them

A useful lens here comes from Team Topologies (Skelton and Pais), which names three ways teams interact: X-as-a-Service, a clean request and response with no back-and-forth needed; collaborating, deliberate close coordination because the problem is genuinely joint; and facilitating, one side unblocking the other without doing its work. Subagent handoffs have exactly the same three shapes, and the mode is a choice you make per handoff — most people make it once, implicitly, by defaulting everything to fire-and-forget.

Reviewed against that lens, our own runs split cleanly. A claims-review gate over a 35-page diff was right as X-as-a-Service: one round, findings with file:line, applied without discussion. The subagent that corrected the brief's slug was facilitating, and welcome — a report back is not friction. But a desk report that ran as an isolated request-and-response surfaced an item as needing an owner decision when the decision was already logged in our decision record; the subagent could not see the record, so nothing reconciled its output against it, and the reconciliation had to happen by hand afterwards.

That gives a usable test before you dispatch: if the handoff's output has to be consistent with state the subagent cannot see, it is not a service call. Either put the state in the prompt, or add an explicit reconcile step where whoever holds that state checks the output against it. This is the same root cause as the Explore/Plan pitfall below — those agents deliberately omit CLAUDE.md — generalized past the built-ins to every subagent you write.

Artifacts this workflow produces

The output isn't just shipped code. It's a repo any agent — and any teammate's agent — can operate:

• CLAUDE.md (committed) — the operating manual, pruned to what prevents mistakes.
• .claude/skills/ — your procedures as slash commands.
• .claude/agents/ — your reviewers and investigators as files.
• .claude/settings.json — hooks: the deterministic rules.
• .mcp.json (committed) — the team's shared external tools.
• .claude/workflows/ — saved fan-out orchestrations.

It compounds: every session starts from the accumulated encoded judgment of every previous one.

Pitfalls

• Rules vanish after compaction. Users report CLAUDE.md instructions being ignored after /compact (issue #24460). Don't treat compaction as free: /clear at task boundaries so you rarely hit it, and put must-hold rules in hooks, which survive by construction.
• Context exhaustion degrades silently. Auto-compaction triggers around 95% full, and instruction-following decays well before that (analysis). A session that "got dumber" is usually a session that got full.
• The bloated CLAUDE.md. First-party acknowledged: an over-specified file causes the agent to ignore your actual instructions. More rules is less compliance. Prune ruthlessly (step 1's test).
• Explore/Plan don't read CLAUDE.md. By design — but it surprises users when a subagent violates a repo rule the main session follows. Repeat load-bearing rules in the delegation prompt.
• Trust-then-verify gap. The named failure pattern: accepting "done" without evidence. The fix is structural (steps 5 and 8), not vigilance.
• A shared brief written from memory. One wrong slug, path, or command in a fan-out brief becomes N wrong outputs that read like independent corroboration. List every literal from disk before dispatch; grep the combined diff for it afterwards.
• Every handoff defaulted to fire-and-forget. A subagent whose output must agree with state it cannot see needs that state in the prompt or an explicit reconcile step — otherwise you get a confident report that contradicts a decision you already made.
• Workflow sticker shock. Dynamic workflows "consume meaningfully more usage" — a 100-agent audit is a 100-agent bill. Check the large-workflow warning, set a size guideline (advice, not a cap), and don't use ultracode for what three subagents can do.

When not to use it

Skip the full apparatus when the diff fits in one sentence — a rename, a copy tweak, a one-line fix needs no plan step and no subagent. Skip dynamic workflows for anything under a handful of parallel tasks; plain sessions and subagents cover it at a fraction of the cost. And don't adopt the workflow in a repo you're not allowed to instrument: without a committed CLAUDE.md and hooks, you're back to ad-hoc chat, and the failure modes above come with it. If you're still choosing a tool at all, start with the agentic coding tools guide rather than this page.

Changelog

• 2026-10-05 — step 4 corrected against the Claude Code changelog: the every-plan, every-provider start in auto mode for the terminal and VS Code is v2.1.284 (28 Sep), not v2.1.283, and claude -p and Python Agent SDK sessions now start in auto on third-party providers or with telemetry off (v2.1.285, 29 Sep).
• 2026-10-03 — re-verified against the current docs. Step 2 now covers AGENTS.md; step 4 says auto is the built-in start mode in the terminal and VS Code on any plan (v2.1.283+) and states what we actually run; step 6 no longer calls Explore a Haiku agent; step 7 corrects the workflow subagent permission mode and the size-guideline wording.
• 2026-08-17 — step 4's permission-posture table now notes Anthropic's 14 Aug 2026 shift to auto as the default mode for new Pro/Max/Team sessions, with the classifier study and defaultMode/disableAutoMode pinning facts.
• 2026-08-10 — added the as-built section on fan-out failures: generating a shared brief's literals from disk rather than recall, and choosing an interaction mode per handoff; two matching pitfalls and two source lines.
• 2026-07-13 — initial version, verified against Claude Code v2.1.203+ docs.