AIGuide
Deep dive

Advanced loop engineering

Context windows, isolation, parallel orchestration, and the design patterns that separate a reliable agent from a flaky one. This is the material to reach for once the basics click.

Fuel & friction

Context windows: the agent's working memory

The context window is everything the model can "see" on a given turn: the conversation so far, files it has read, tool outputs, CLAUDE.md, saved memory, MCP tool definitions, and loaded skills. It's finite. Fill it with noise and the loop gets slower, more expensive, and less accurate.

conversation files read tool results memory / MD free spaceto think One finite context window → keep the free space large

Auto-compaction

As the window fills, Claude Code trims the oldest tool outputs first, then summarises older conversation while preserving your requests and code — so the loop can keep running.

Keep it lean

Push heavy side-work into subagents, load skills on demand rather than upfront, and use /context to inspect what's consuming space.

The core trick

Context isolation

This is the reason subagents exist. Each subagent gets a fresh, separate context window. It sees its own system prompt and the task it was handed — not the main conversation's history. When it finishes, only its summary crosses back.

  • 🔒One-way mirror. The main agent can read a subagent's result; the subagent cannot read the main agent's earlier work. That asymmetry is what preserves isolation.
  • 🧾Transcripts stay separate. A subagent's full working history is stored on its own, so nothing bloats the parent — and it can be resumed later with its context intact.
  • 💸Cheap parallelism. Because five subagents mean five separate windows, running them at once doesn't bloat any single one.
🧠

Mental model

Isolation converts an expensive "read everything into one huge context" problem into many small, disposable contexts whose only lasting output is a tidy summary.

Doing more at once

Parallelism & fan-out

Two layers of concurrency stack in Claude Code. First, within a single turn the agent can emit multiple tool calls at once — reading three files in parallel instead of one after another. Second, it can spawn multiple subagents that run concurrently, each in its own context.

Orchestrator fan-out ▸ Subagent A · module 1own context Subagent B · module 2own context Subagent C · module 3own context Synthesis ◂ fan-in

Fan-out / fan-in: split independent work across parallel subagents, then merge their summaries.

📐

Depth & format matter

Subagents can nest — spawning their own subagents up to a bounded depth below the main conversation. And to preserve in-turn parallelism, all results from a batch of parallel tool calls come back together in one step rather than trickling in one message at a time.

Two roles

Orchestrator vs subagent

Loop engineering at scale is really about splitting one role into two: a manager that owns the plan, and workers that own the details.

AspectOrchestrator (main agent)Subagent (worker)
ContextFull conversation historyFresh & isolated — task + system prompt only
JobDrives the workflow, high-level decisionsExecutes one focused task
Sees the other's work?Yes — reads each subagent's summaryNo — blind to the parent's history
Can spawn subagents?YesYes — nested, up to a depth limit
OutputThe final result to youA concise summary back to the parent
TranscriptThe main sessionStored separately; resumable
Configuration

Subagent frontmatter reference

A subagent definition is YAML frontmatter plus a Markdown system prompt. Only name and description are required; everything else tunes behaviour.

FieldTypePurpose
namestringUnique lowercase-hyphenated id. Required.
descriptionstringWhen Claude should delegate to it. "Use proactively" encourages auto-delegation. Required.
toolslistAllowlist of tools. Omit to inherit all. Restrict for safety (e.g. read-only reviewer).
disallowedToolslistDenylist — applied before the allowlist.
modelenumsonnet · opus · haiku · inherit, etc. Match the model to the job's difficulty.
permissionModeenumdefault · acceptEdits · plan · bypassPermissions …
maxTurnsintCaps the subagent's loop length — a safety backstop.
skillslistSkills to preload into the subagent's context.
memoryenumPersistent cross-session memory: user · project · local.
isolationenumworktree = run in an isolated git worktree so parallel edits don't clash.
effortenumReasoning level override: low → max.
--- name: test-runner description: Runs the suite and reports failures. Use proactively after code changes. tools: [Bash, Read, Grep] model: haiku # cheap + fast for a mechanical job maxTurns: 12 --- Run the project's tests. If any fail, return the failing test names, the assertion messages, and the file:line — nothing else. Do not attempt fixes.

A narrow, single-purpose subagent: restricted tools, a small model, a hard turn cap, and a tightly-scoped prompt.

The playbook

Five loop-engineering patterns

These are the reusable shapes for building reliable loops. Mix and match them.

✅

1 · Verification loop

Do the work, then send it to a read-only checker (e.g. a reviewer or test-runner subagent). Feed the critique back and fix, looping until it comes back clean. Keeps the checker's noisy output out of the builder's context.

🌐

2 · Fan-out / fan-in

Split independent work across several subagents running in parallel, then merge their summaries into one synthesis step. Best when the pieces don't depend on each other.

➡️

3 · Pipeline

Chain specialised subagents so each one's output feeds the next: Explore → Plan → Implement → Review → Test. Each stage is focused and isolated.

🔁

4 · Loop-until-done

A subagent retries the same task, checking its own output each pass, until a clear condition is met. Because a resumed subagent keeps its context, it learns from prior attempts.

⚔️

5 · Adversarial verification

Spin up independent skeptics whose only job is to refute a finding — default to "rejected" unless the evidence is convincing. Kill any claim a majority refute. Diverse lenses (correctness, security, "does it actually reproduce?") catch failure modes a single reviewer misses. This is how you stop plausible-but-wrong results from surviving the loop.

🛠️ Builder writes the change 👓 Checker read-only review submit work critique → fix & repeat loop until the checker is satisfied ✓
Getting it right

Pitfalls & best practices

⚠️ Common pitfalls

  • ✗No stopping condition. A loop with no clear "done" wanders or runs forever. Always define success and a turn cap.
  • ✗Skipping verification. Acting without looping back to check is how silent, plausible-looking bugs ship.
  • ✗Context bloat. Doing heavy reads in the main loop instead of delegating them.
  • ✗Over-delegation. Spawning subagents for trivial one-liners adds latency for no benefit.

✓ Best practices

  • ✓One job per subagent. Narrow scope, restricted tools, a focused prompt.
  • ✓Right model for the job. A small fast model for mechanical tasks; a stronger one for hard reasoning.
  • ✓Verify, then trust. Build a checking step into the loop rather than hoping the first attempt is correct.
  • ✓Isolate the noise. Send searches, logs, and big reads to subagents so the manager stays clear-headed.
🎯

The whole idea, distilled

A capable model is the engine. Loop engineering is the transmission — the goal, the feedback, the verification, the isolation, and the stop signal that turn raw capability into dependable, repeatable work.

⌂ Back to all lessons