Workflow · last verified 2026-07-13

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

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

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.

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.

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 (Haiku, read-only) for searches and Plan for design work, and define your own 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.

Know one design decision that 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.

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 subagents run in acceptEdits inheriting your allowlist — so your permission posture from step 4 is load-bearing here. Cost is real: v2.1.203+ warns on "large workflows" (>25 agents or >1.5M tokens), a size cap lives in /config, 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.

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.

The repo becomes operable by agents; that config is the artifact. 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.
• Workflow sticker shock. Dynamic workflows "consume meaningfully more usage" — a 100-agent audit is a 100-agent bill. Check the large-workflow warning, set the size 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-07-13 — initial version, verified against Claude Code v2.1.203+ docs.