Learning objectives

By the end of this chapter, you will be able to:

1. Place coding agents within the production agent taxonomy — the broad domain of agents (hybrid RAG, agentic apps) divides into **shallow** agents (the ReAct reason→act→observe loop) and **deep** agents, and deep agents split into deep-research agents and **coding agents** (Claude Code, Cursor, Devin, Gemini CLI) — and explain why the *application layer* (the 'agent harness') is where most current innovation happens.
2. Explain the limitation of shallow agents — each ReAct iteration injects the tool result back into the prompt, so over many iterations the context grows until it suffers **context rot** (bloat, contradiction, pollution), degrading quality and raising cost/latency — and define what makes an agent **'deep'**: the ability to perform complex, long-running (long-horizon) tasks with quality and reliability, which reduces to **smart context management**.
3. Name the four building blocks a deep agent typically shares — a **detailed system prompt**, a **planning tool**, **subagents**, and a **filesystem** — and recognize that **'deep agent' is a community/LangChain-articulated term, not an official Anthropic/Claude Code label** (Anthropic more commonly discusses 'long-running / long-horizon' agentic work, context engineering, and agents/workflows rather than defining 'deep agent' as an official term); map each block onto both Claude Code and the LangChain DeepAgents harness.
4. Explain the **planning** block — an *explicit, dynamic to-do list* (tasks marked pending / in-progress / completed) that the agent rewrites as it works, whose real job is **context management** (keeping the current plan in the window to re-orient the agent), not computation — and know the current Claude Code surface (the `Task*` tools — `TaskCreate`/`TaskList`/`TaskGet`/`TaskUpdate` — with the book's `TodoWrite`/`TodoRead` now the *legacy* form, disabled by default), and that this dynamic to-do list is distinct from read-only **plan mode** (Chapter 6).
5. Explain **subagents / hierarchical delegation** — an orchestrator (main agent) delegates a scoped task to a specialized subagent with its own system prompt, tools, and **isolated context window**; the subagent works independently and returns **only its final result** (not its intermediate steps), which both keeps the main context lean and enables parallelism — and connect it to the `Agent` tool (formerly `Task`), Chapter 7, and the orchestrator-workers pattern.
6. Explain the **filesystem** block — writing intermediate state to disk instead of the context window, plus *selective retrieval* (`glob`/`grep`) to pull in only what a step needs — as the mechanism behind 'precise context selection'; ground it in the context-engineering 'attention budget' / three-box model (all-available ⊃ selected vs. required context), Claude Code's file tools (`Read`/`Write`/`Edit`/`Glob`/`Grep`/`NotebookEdit`) and memory (`CLAUDE.md` + auto-memory) — and recognize that 'the filesystem as a context engine' is an engineering *principle*, not a documented Claude Code feature name.

Before we start — agents, ReAct, "long-horizon," harnesses, and the four pillars

Skim this if you're comfortable with what an agent is, the idea of a context window filling up, and the subagents from Chapter 7. If any of that is fuzzy, read it first — this final chapter assembles ideas from across the whole book into one architecture.

An agent (recap). An agent is an LLM that doesn't just answer once — it decides, in a loop, to call tools (search, read a file, run a command), looks at the results, and decides what to do next, until a goal is met. Chapters 1–10 had you driving one (Claude Code). This chapter looks under the hood.

The ReAct loop. The original, foundational agent pattern is ReAct ("Reason + Act," from a 2022 paper): the model reasons about what to do, acts by calling a tool, receives the result as an observation, and loops — reason → act → observe → reason → … — until it can answer. Almost every modern agent traces back to this shape.

Shallow vs. deep. A shallow agent is a short ReAct loop — great for a handful of steps (look something up, call one tool, answer). A deep agent is built to run long — minutes, hours, even days — across many steps, adapting its plan as it goes. **Important and stated up front: "deep agent" is a community term (articulated clearly by the LangChain team), not an official Anthropic or Claude Code label. Anthropic's docs and engineering writing more commonly discuss long-running / long-horizon agentic work, context engineering, and agents/workflows**, rather than defining "deep agent" as an official term. We use "deep agent" because that's the chapter's title and the industry's word, but we'll keep it labeled as the conceptual framing it is.

"Long-horizon" and context rot. A long-horizon task is one needing many iterations of reasoning and information-gathering (implement a feature; research a topic deeply). The enemy of long-horizon work is context rot — the way an agent's context window fills with accumulated tool results until quality degrades (you met this in Chapters 1 and 9). Managing that is the whole game.

An agent harness. The book's word for the application layer built on top of a model to make a capable agent: a ready-to-use environment that supplies the default prompts, tool handling, planning, and file access so you don't wire it all from scratch. Claude Code is a harness; the LangChain DeepAgents package is another. Most current innovation is here, in the harness — not only in the base model.

The four pillars (one line each), which the chapter is organized around:

1. System prompt — a big, carefully-written instruction set that gives the agent its reasoning framework.
2. Planning tool — an explicit, dynamic to-do list the agent keeps rewriting.
3. Subagents — specialized helpers that work in their own isolated context and hand back a summary.
4. Filesystem — disk used as memory and as a way to pull in only the context a step needs.

How to read this chapter. Each numbered section ends with an > Analogy — … box that restates the idea in plain language. Lean on them or skim them as you like.

Why this chapter matters

Every earlier chapter taught you to operate Claude Code — permissions, MCP, hooks, subagents, output styles, the desktop app. This one is different: it's the capstone that explains the architecture underneath all of it. Why does Claude Code keep a to-do list? Why does it spin up subagents instead of doing everything in one thread? Why does it read and write files so aggressively, and lean on CLAUDE.md? The answer is a single design problem — keeping a finite context window useful across a long task — and four recurring moves that solve it.

Two payoffs make the abstraction worth your time. First, transfer: once you can see the four pillars, you can recognize them in any deep agent — Cursor, Devin, a deep-research agent, or one you build yourself with a harness like LangChain DeepAgents — and you'll know which pillar to reach for when an agent misbehaves on a long task. Second, it closes the loop on the book: the context engineering of Chapter 1, the subagents of Chapter 7, the planning of Chapter 6, and the skills/memory of Chapters 3 and 9 turn out to be the same four pillars, viewed from different angles. This chapter names the pattern they all belong to.

A note on sources and currency. The four-pillar framing is LangChain's (Harrison Chase's "Deep Agents" post), and we treat it as exactly that — a useful industry articulation, not Anthropic documentation. Claude Code behavior claims (the planning tools, subagents, file tools, memory) are verified against the official docs, which move fast: the planning tool the book calls TodoWrite/TodoRead is now the **Task* family** (the older TodoWrite is disabled by default). And "the filesystem as a context engine" is an engineering principle (from Anthropic's context-engineering post), not a Claude Code feature name. Each of these is flagged inline and recorded in the source ledger.

Lesson

1. The agent taxonomy — where coding agents sit

Before defining "deep," the chapter draws a map of the agents actually running in production. Start at the top: the domain of agents covers everything from fully autonomous systems to lighter agentic applications — a common example being a hybrid RAG architecture where an LLM decides, step by step, whether to search, call a tool, or answer.

Within that domain, the foundational shape is the ReAct agent (Reason + Act). Its loop: the LLM decides whether to use a tool; if so, the system runs it and feeds the result back as an observation; the LLM then decides whether it has enough to answer, and if not, loops again. This loop "initiated the broader agent paradigm" — most modern agent architectures trace back to it.

The map then splits agents into two families:

• Shallow agents — short ReAct loops (the next section explains the limits).
• Deep agents — long-horizon systems, which themselves split into deep-research agents (Perplexity's and ChatGPT's "research" modes, Claude Code's research option, the open-source GPT Researcher) and coding agents (Claude Code, Cursor, Devin, Gemini CLI) — a specialized subset tailored to software-development workflows, and "one of the strongest demonstrations in the industry."

The chapter's sharpest framing is where the progress is coming from: base LLMs improve incrementally, but the application layer built on top of them is advancing fast. By composing agents and layering abstractions, you get capable systems — and that application layer is the agent harness (Claude Code, LangChain DeepAgents). The lesson: much of today's leap isn't a smarter model, it's harness engineering — how we wrap the model.

Analogy — vehicles on the road All agents are vehicles. A shallow ReAct agent is a bicycle: perfect for a quick errand a few blocks away, and a huge amount of the world's trips are exactly that. A deep agent is a long-haul truck built to run for days across the country — and a coding agent is that truck fitted out for one trade (a mobile workshop). The striking part isn't that engines got slightly better this year (the model); it's how much further you can go because someone built the truck around the engine (the harness).

2. Shallow agents and why they hit a wall

A ReAct agent is classed as shallow — not because it's useless (it's foundational and powerful), but because it can't sustain thorough, extended work. The reason is mechanical, and it's the engine of this whole chapter.

A ReAct agent runs on function calling: at each step the model picks a tool, the system runs it, and the result is injected back into the prompt. One or two iterations? Fine. But as iterations pile up, the context grows and grows — every observation stays in the window. That growth is context rot: bloat, contradiction, and pollution accumulate until the model's quality degrades and it can "go off the rails." And it costs you twice — more tokens mean higher latency and expense, for worse answers.

This is exactly the wall you hit on complex, long-running tasks — implementing a feature, deep research, a multi-stage workflow that needs continuous reasoning. They're a different animal from a one-shot request like "book a flight." For the short tasks, shallow agents are genuinely the right tool and run successfully in countless production systems. For long-horizon work, something has to manage the context instead of letting it balloon — and that is precisely what makes an agent "deep."

Analogy — a desk that's never cleared A shallow agent is someone who solves problems by piling every document they touch onto their desk and never filing anything. For a two-step task, the pile is tiny — no problem. But on a week-long project the desk becomes a mountain: they re-read contradictory drafts, lose the important page under junk, slow to a crawl, and start making mistakes. The fix isn't a smarter person — it's a system for clearing the desk. Deep agents are that system.

3. What makes an agent "deep" — the four pillars

There's no strict formal definition. In practice, an agent is "deep" if it can perform complex, long-running tasks with quality and reliability — and to do that it must solve the context problem from §2. So the defining challenge of a deep agent is context engineering and smart context management; without it, long-horizon execution breaks down.

When you examine modern deep-agent implementations, the same four ideas show up (this is the LangChain team's articulation, after studying many systems — and again, "deep agent" is their term, not an Anthropic one):

1. A detailed system prompt — encodes instructions, constraints, and the agent's operational behavior (§7).
2. A planning tool — the agent plans explicitly before and during execution, via a dynamic to-do list (§4).
3. Subagents — specialized workers that run in isolated contexts, so heavy sub-work doesn't bloat the main thread and can run in parallel (§5).
4. A filesystem — intermediate state is written to disk instead of being held entirely in context, preventing uncontrolled growth (§6).

We take the pillars below in the book's teaching order — planning first (§4), the detailed system prompt last (§7) — but each keeps the number it has in this list (so §4 covers Pillar 2, the planning tool, and §7 covers Pillar 1, the system prompt).

Notice that three of the four are, at heart, context-management moves: planning keeps the plan small and in view; subagents keep sub-work out of the main window; the filesystem keeps state off the context entirely. The system prompt is the one that supplies judgment. Together they're what let a deep agent run for hours without rotting.

Analogy — what makes an expedition, not a walk Anyone can take a walk (a shallow task). An expedition that lasts weeks needs four things a walk doesn't: a plan you revise as conditions change (planning tool), specialists you send ahead to scout and report back without dragging the whole party along (subagents), base camps where you stash supplies so you're not carrying everything at once (filesystem), and a field manual of principles for decisions no one anticipated (system prompt). Strip any one away and a long expedition falls apart — even with the fittest climbers (the best model).

4. Pillar 2 — explicit planning via a dynamic to-do list

The first thing every deep agent has is a planning tool. The key word is explicit: instead of planning implicitly through chain-of-thought reasoning buried in the model's head, a deep agent keeps a visible, dynamic to-do list — tasks marked pending, in progress, or completed — and rewrites it as it works. When a task fails, it doesn't blindly retry as a raw ReAct loop would; it updates the plan.

Here's the subtle, important part (straight from LangChain's analysis): the planning tool is almost a no-op computationally — calling it doesn't do much. Its real job is context management. Writing the current plan back into the context window re-orients the agent every few steps: "here's the goal, here's what's done, here's what's next." On a long task, that running summary is what keeps the model on the rails. It's the same thing you do naturally — break big work into tracked sub-tasks — formalized inside the agent.

In Claude Code. The planning tool is internal, but you can see it act. The book describes the actions as TodoWrite (creates/updates the to-do list, taking a {todos: Todo[]} parameter) and TodoRead (reads it). Drift to note: as of writing, that's the legacy surface — Claude Code's current task-tracking tools are the **Task* family (TaskCreate, TaskList, TaskGet, TaskUpdate, TaskStop), and the older TodoWrite is disabled by default**. (There's no documented command to view the internal task list — the checklist surfaces inline when Claude shows it; don't confuse it with the /tasks command, which is a different feature for the background tasks running in your session.) The concept the book teaches — an explicit, dynamic to-do list kept in context — is exactly right and current; only the tool names moved. (In LangChain DeepAgents the equivalent is a write_todos tool, wired in by a TodoListMiddleware.)

Don't confuse this with plan mode. Chapter 6's plan mode (/plan, the Shift+Tab cycle, --permission-mode plan) is a read-only permission mode — Claude explores and proposes a plan before it's allowed to edit anything, and you approve. The dynamic to-do list here is different: it's in-session task tracking the agent maintains while doing the work. One gates when editing is allowed; the other keeps a long task organized as it runs. They're complementary, not the same feature.

Analogy — the whiteboard the surgeon keeps glancing at In a long operation the team keeps a whiteboard: steps done, step in progress, steps to come. Writing on it doesn't perform surgery — it's "almost a no-op" — but every glance re-orients everyone to where they are in a hours-long procedure, so nobody loses the thread or repeats a step. The dynamic to-do list is the agent's whiteboard: cheap to update, and the thing that keeps a long job coherent.

5. Pillar 3 — subagents and hierarchical delegation

The second pillar is the one you already built in Chapter 7, now seen as part of the bigger picture. A deep agent uses subagents for hierarchical delegation: the main agent spawns specialized workers — each with its own system prompt, its own description, and its own set of tools — and hands each a scoped task.

The defining property is isolation. A subagent works in its own context window, executes independently, and returns only its final result — not the full chain of intermediate reasoning and observations. The main agent (the orchestrator) never sees the messy middle; it gets the clean answer. That does two things at once: it keeps the orchestrator's context lean (the sub-work's bloat stays quarantined), and it enables parallelism (several subagents can run at the same time). Efficiency and depth improve together.

This is delegation as it works in real life: you don't just assign a task — you give the right person the right tools and a clear brief, they go off and do it with their own equipment, and they bring back the outcome, not a transcript of every move. In Claude Code you've watched exactly this: the main agent spawning an exploration subagent to go search for, say, authentication patterns while it keeps working — built-in support for subagents and hierarchical delegation. Mechanically, delegation happens through the Agent tool (renamed from Task; Task remains an alias).

The pattern has a name in the engineering literature — orchestrator-workers: a central agent dynamically decomposes a task, delegates pieces to workers, and synthesizes their results (the subtasks are decided at runtime, not pre-scripted). Anthropic's multi-agent research write-up reports this style beating a single agent on a research eval — while using substantially more tokens (as reported, roughly an order of magnitude). Treat those numbers as reported background, not Claude Code mechanics; the durable point is the §3 one — isolation is a context-management move.

Analogy — the general contractor and the trades A general contractor renovating a house doesn't personally rewire the panel and re-plumb the bathroom. They call an electrician and a plumber — each shows up with their own tools and expertise, works in their own area, and reports back "done, inspected, here's what you need to know." The contractor never watches every wire stripped; they get the result and keep coordinating. That's hierarchical delegation: specialists in isolated workspaces, returning outcomes, leaving the orchestrator free to run the whole job.

6. Pillar 4 — the filesystem as persistent state and a context engine

The third pillar is filesystem access, and it's the most important context-management move of all. The idea: instead of holding every intermediate result in the context window, the agent writes it to disk — and later reads back only what it needs.

In Claude Code this is a concrete set of tools: Read (file contents, incl. images/PDFs/notebooks), Write (create/overwrite), Edit (precise string replacements), plus Glob (find files by pattern) and Grep (search contents by regex), and NotebookEdit. LangChain DeepAgents exposes a parallel interface — ls, read_file, write_file, edit_file, glob, grep — deliberately abstract, so the "filesystem" could be backed by local disk, Firestore, DynamoDB, anything. The interface is fixed; the storage is pluggable.

Why this matters — the three-box model of context selection. Picture three nested regions:

• All available context (the big box): every codebase, doc, web result, and database the agent could draw on — vast and messy.
• Selected context (what the agent actually pulls into its window this step — what it chose to read or search).
• Required context (the small box: what the task genuinely needs to succeed).

The whole job of context engineering is to make the selected set small while still fully covering the required set. When selection misses, you get the classic failure modes: under-retrieval (you grabbed only part of what was needed), misaligned retrieval (you searched the wrong place entirely), and context-window limits (you tried to grab too much and quality degraded). As Anthropic's context-engineering work puts it, the window is a finite attention budget that depletes with every token — so how information is structured and retrieved often matters more than the prompt itself.

The filesystem is the engine that makes good selection possible, in two moves: (1) write context out to persistent storage — intermediate results, retrieved info, notes — so it leaves the window instead of bloating it; and (2) select it back precisely with glob/grep (and targeted, paginated reads — "read_file(path, limit=100) to scan, then read the section you need") rather than re-loading everything. That's the same pair of context-engineering principles from Chapter 9 — write context out, retrieve it selectively — now recognizable as a building block of every deep agent. (Claude Code's memory is the same idea for durable state: CLAUDE.md for human-written instructions and the auto-memory subsystem for Claude-written notes that persist across sessions.)

Drift to note: "the filesystem as a context engine" is an engineering principle (from Anthropic's Effective context engineering post and LangChain's filesystem post), not a documented Claude Code feature name. Claude Code genuinely ships the file tools and the memory system; the "context engine" framing is the why, not a button.

Analogy — the detective's case room, not their pockets A detective on a months-long case doesn't carry every document in their coat. They keep a case room: everything filed on the walls and in cabinets (the filesystem / all available context), and for each interview they pull just the few folders that matter (selective retrieval via glob/grep), leaving the rest on the wall. Stuff it all in your pockets and you can't find anything and your coat tears (context rot). The case room is the engine that lets one detective work a huge case without drowning in it.

7. Pillar 1 — the detailed system prompt (the cognitive baseline)

The fourth pillar supplies what the other three can't: judgment. "System prompts are important" is a cliché, but the practice of industry leaders shows how load-bearing it is — state-of-the-art system prompts run to hundreds of lines, heavily augmented with injected tool descriptions, and teams pour engineering effort into curating and refining them as models evolve. For a deep agent, the system prompt is "the fundamental architecture of its reasoning, identity, and operational behavior" — the cognitive baseline.

What makes one good leverages what strong LLMs are best at — pattern-matching and applying general rules to novel cases:

• A reasoning framework, not a flowchart. Instead of brittle if/then branching, give a repeatable framework (e.g. understand → act → verify). This teaches the model how to approach problems, so it copes with situations no one scripted.
• Heuristic principles, not exhaustive lists. A compressed rule like "always choose the simplest solution" acts like a greedy heuristic — it steers thousands of edge cases without burning tokens enumerating them.
• Language efficiency. No wasted words, no overlapping or repeating instructions that could confuse the model or push it toward contradictory behavior.

LangChain DeepAgents ships a built-in base system prompt (MIT-licensed, in its repo) that reads exactly like this — short, principled directives: read files before editing; mimic existing conventions; understand → act → verify; prefer specialized tools over shell equivalents; paginate large reads (read_file(path, limit=100)) to avoid context overflow; give brief progress updates on long tasks. You've met Claude Code's version of all this already: it ships its own carefully-engineered system prompt, which output styles can modify (Chapter 8) and the Agent SDK can replace or append to — those are the direct system-prompt surfaces. Your CLAUDE.md (Chapter 2) shapes the same pillar from a different mechanism: it's persistent project memory/context that Claude loads into the conversation (the docs note Claude "treats them as context, not enforced configuration"), not a system-prompt edit. Different levers, same cognitive baseline. The takeaway the chapter lands on: the system prompt is the cognitive baseline — over-specific hardcoding strangles the model's reasoning; vague instructions produce chaos. The art is principled middle ground.

And that's what binds the four pillars: the system prompt tells the agent how to think; the planning tool keeps it oriented; subagents let it delegate depth; the filesystem lets it manage state. Take the model's raw reasoning and wrap it in those four, and a short ReAct loop becomes a system that can work for hours — a deep agent.

Analogy — the constitution, not the to-do list The other three pillars are operations; the system prompt is the constitution. It doesn't list every action — it sets the principles a good actor applies to situations the authors never foresaw ("prefer the simplest remedy," "understand before you change things"). A rulebook that tries to script every case is unusable and still has gaps; no rules at all is chaos. A short, principled constitution is what lets a capable agent act well in genuinely new territory — which long-horizon work is full of.

The whole chapter in one image — the expedition, and the whole book

Analogy — pedagogical summary, drawing on all seven sections, and closing the book

A shallow agent is a day-hike (a ReAct loop): reason, act, observe, repeat — perfect for a quick errand, and most of the world's tasks are quick errands. But send a day-hiker on a month-long expedition (a long-horizon task) and the pack becomes a mountain of everything they ever touched — they slow, contradict themselves, and lose the trail. That's context rot, and it's why "deep" exists.

A deep agent is the expedition, properly outfitted — four pillars a walk never needed. A field manual of principles for the unforeseen (the system prompt). A route plan revised at every camp (the planning tool — cheap to update, and the thing that keeps a long journey coherent). Specialists sent ahead to scout and report back the finding, not the footsteps (subagents in isolated contexts). And base camps that hold the supplies, so you carry only what the next leg needs (the filesystem — write state out, retrieve it selectively). Three of the four exist to keep a finite pack useful over a long distance — that's context engineering, the ground everything stands on.

And that's the whole book in one frame. Context engineering (Ch 1) was the ground. CLAUDE.md and the permission gate (Ch 2–3), MCP and plugins (Ch 4), unattended GitHub runs (Ch 5), planning and parallelism (Ch 6), subagents (Ch 7), output styles (Ch 8), skills (Ch 9), and the desktop/cloud orchestration (Ch 10) were all, it turns out, pillars of the same structure — the deep agent you've been driving all along. Now you can see the architecture, name its parts, and recognize it in any harness — Claude Code, LangChain DeepAgents, or one you build yourself. **That's the point of the chapter, and the book: not just to use a deep agent, but to understand one.**

Activity — Find the four pillars in a tool you use

Ten minutes, individual, no setup required. You'll practice the §3–§7 lens — the durable takeaway of this chapter — on agents from your own world.

1. Pick a deep agent you actually use (Claude Code, Cursor, a deep-research mode, Devin, …).
2. Locate each of the four pillars in it. For each — system prompt, planning tool, subagents, filesystem — write one line: how does this tool surface it? (e.g. for Claude Code: the system prompt, with CLAUDE.md as project memory; the in-session to-do list via the Task* tools; the Agent/subagents; the Read/Write/Glob/Grep tools + CLAUDE.md/auto-memory.) Mark any pillar you can't find.
3. Tie each pillar to a failure it prevents. Match each pillar to one §2 failure mode it guards against (context rot, going off-plan, main-context bloat, under-/misaligned-retrieval). Which pillar, if removed, would hurt your longest task most?
4. Spot the context-management move. Three of the four pillars are really about managing a finite window. Which three, and what does each keep out of the main context? (Plan stays small; sub-work stays isolated; state goes to disk.)
5. Name the term you'd correct. Where would you push back on loose language — e.g. someone calling "deep agent" an Anthropic feature, or "the filesystem context engine" a Claude Code button? Write the one-sentence correction.

Keep your answers — they're the lens you'll carry to the next agent you meet.

Practical exercise — Watch the four pillars run in Claude Code

~35–45 minutes. Hands-on. No new framework, no npm, no API keys, no LangChain install — just Claude Code (which you already have), git, and a throwaway sandbox. Rather than build a deep agent, you'll drive Claude Code through a long-ish task and watch each of the four pillars do its job — turning this conceptual chapter into something you can see. (An optional read-only stretch points you at the LangChain DeepAgents base prompt to compare.)

Everything happens in a throwaway sandbox — nothing here touches the training repo.

Setup (4 min). Create a small multi-file sandbox worth exploring:

mkdir -p ~/cct-ch11-lab/src && cd ~/cct-ch11-lab
git init -q
printf 'def login(user, pw):\n    return verify(user, pw)\n' > src/auth.py
printf 'def verify(u, p):\n    return u == "admin" and p == "secret"\n' > src/crypto.py
printf 'def total(items):\n    return sum(i["price"] for i in items)\n' > src/cart.py
printf '# Lab app\nA tiny multi-module sandbox.\n' > README.md
git add . && git commit -q -m "init deep-agent lab"

Part 1 — Pillar 2, the planning to-do list (8 min). Start claude in the sandbox and give it a deliberately multi-step task so it plans explicitly:

Audit this repo for security issues, then write a one-paragraph summary to FINDINGS.md, then suggest one fix. Track your work as a task list.

Watch the to-do list appear and update inline as Claude surfaces it — items moving pending → in progress → completed. (There's no documented viewer command for the internal list; just watch it as Claude works. The /tasks command is unrelated — it's for background processes in the session.)

Expected outcome: you see an explicit, dynamic plan, not just prose — Pillar 2's planning tool. Note the tool names in play: as of writing these are the **Task* tools** (TaskCreate/TaskUpdate/…); the book's TodoWrite/TodoRead is the legacy form. (This is the in-session to-do list — distinct from Chapter 6's read-only plan mode, which you could enter with Shift+Tab before a task to see the "propose-before-editing" behavior instead.)

Part 2 — Pillar 3, a subagent in an isolated context (8 min). Ask the main agent to delegate exploration:

Use a subagent to explore how authentication flows through this repo, and report back just a summary.

Expected outcome: the main agent spawns a subagent (the Agent tool / /agents), which explores in its own context and returns a condensed summary — you don't see its every step in the main thread. That's hierarchical delegation: depth without bloating the orchestrator (Chapter 7, now as Pillar 3). Run /context before and after to see the main window stayed comparatively lean.

Part 3 — Pillar 4, the filesystem as a context engine (12 min). Make Claude use the disk as memory and retrieve selectively:

Write your full audit notes to NOTES.md. Then, WITHOUT re-reading the whole repo, use grep/glob to find only the file that defines password checking, and propose a fix to just that file.

Expected outcome: Claude writes state out to NOTES.md (it leaves the window) and then selects back precisely with Grep/Glob (finding crypto.py's verify) instead of re-loading everything — the write-out / select-back pair from §6. cat NOTES.md to confirm the offloaded state is real. This is "precise context selection": small selected set, still covering what's required.

Part 4 — Pillar 1, the system prompt / cognitive baseline (8 min). Shift the agent's judgment and watch behavior change. Add a heuristic to CLAUDE.md:

printf '# Project rules\n- Always choose the simplest possible fix.\n- Read a file before editing it.\n- Explain your reasoning in one sentence before any change.\n' > CLAUDE.md

/clear (or restart claude), then re-ask for a fix to crypto.py.

Expected outcome: the response now follows your principles (one-sentence reasoning first; simplest fix; reads before editing) — a reasoning framework, not a flowchart. You shaped the agent's cognitive baseline (Pillar 1) via CLAUDE.md — but note the mechanism: CLAUDE.md is persistent project memory/context (Claude loads it into the conversation; it's "context, not enforced configuration"), not a system-prompt edit. The direct system-prompt levers are output styles (Chapter 8) and the Agent SDK's system-prompt API — different mechanism, same pillar.

Optional stretch — compare a real base prompt (read-only, 3 min). Open the LangChain DeepAgents base system prompt in your browser (https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/base_prompt.md) and spot the §7 traits: understand → act → verify, "prefer specialized tools over shell equivalents," paginate large reads, brief progress updates. No install — just see how a production harness writes Pillar 1.

Success checklist

• [ ] You watched Claude maintain an explicit, dynamic to-do list on a multi-step task (Pillar 2 / planning) — and know it's the Task* tools now, not the legacy TodoWrite.
• [ ] You delegated to a subagent and saw it return a summary from an isolated context (Pillar 3), with the main window staying lean (/context).
• [ ] You made Claude write state to a file and retrieve selectively with grep/glob (Pillar 4 / filesystem as context engine).
• [ ] You changed the agent's judgment with a CLAUDE.md heuristic and saw behavior shift (Pillar 1 / system prompt).
• [ ] You can state, in a sentence, how three of the four pillars are context-management moves.

Common pitfalls - Calling "deep agent" an Anthropic feature. It's a community/LangChain term; Anthropic's word is "long-horizon execution." Use it as a concept, not a documented product feature. - Looking for a TodoWrite tool. The book's name is legacy — current Claude Code uses the Task* family (TodoWrite is disabled by default). Verify at the tools-reference docs. - Confusing the to-do list with plan mode. The dynamic to-do list tracks work during a task; plan mode is a read-only permission mode before editing. Different features (§4). - Treating "the filesystem context engine" as a button. It's a principle (write state out, retrieve selectively) implemented with ordinary file tools + memory — not a documented Claude Code feature name. - Thinking subagents are about speed only. Their first job is isolation — keeping sub-work out of the orchestrator's context; parallelism is the bonus (§5).

Knowledge check — try the quiz

Once you've read the lesson and worked the lab, take the chapter quiz from the navigation bar. Six questions: five grounded in the book chapter, one synthesis question that ties the four pillars together as context-management moves and to the orchestrator-workers pattern. Passing score is 5/6 — retake it until you're confident. (This is the final chapter — when you pass, you've completed the course.)

Further reading & enrichment sources

• LangChain — "Deep Agents" (https://www.langchain.com/blog/deep-agents). The canonical articulation of the four pillars (detailed system prompt, planning tool, sub-agents, file system) and the source of the "deep agent" term. The framework author's own statement — treat it as LangChain's design philosophy, not Claude Code behavior.
• LangChain — deepagents docs & repo (https://docs.langchain.com/oss/python/deepagents/overview, https://github.com/langchain-ai/deepagents). The pillars as concrete API: create_deep_agent(), the write_todos planning tool, the filesystem interface, and sub-agents (wired in as middleware). The repo evolves — verify exact feature names there.
• LangChain — "How agents can use filesystems for context engineering" (https://blog.langchain.com/how-agents-can-use-filesystems-for-context-engineering/). The source of §6's three-box model (all-available ⊃ selected vs. required context) and the under-/misaligned-retrieval failure modes.
• Anthropic engineering — "Effective context engineering for AI agents" (https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents). The strongest Anthropic anchor for this chapter: the attention budget, just-in-time context (load lightweight identifiers, retrieve at runtime), files-as-memory, and sub-agents returning condensed summaries. The "filesystem as a context engine" is a principle from here, not a Claude Code feature.
• Anthropic engineering — "Building Effective AI Agents" (https://www.anthropic.com/research/building-effective-agents) and "How we built our multi-agent research system" (https://www.anthropic.com/engineering/multi-agent-research-system). The orchestrator-workers pattern behind §5 (and the isolated-context subagents). Token/eval figures are "as reported" background, never Claude Code behavior.
• Anthropic cookbook — "Orchestrator-workers" (https://platform.claude.com/cookbook/patterns-agents-orchestrator-workers). Runnable code for a coordinator that decomposes a task, delegates to workers, and synthesizes — the §5 pattern in practice.
• Anthropic docs — Subagents / Tools reference / Permission modes / Memory (https://code.claude.com/docs/en/sub-agents, …/tools-reference, …/permission-modes, …/memory). Ground for the Claude Code mapping: the Agent tool and isolated subagents; the Task* task tools (and legacy TodoWrite); plan mode (distinct from the to-do list); and the CLAUDE.md + auto-memory model.
• "ReAct: Synergizing Reasoning and Acting in Language Models" (https://arxiv.org/abs/2210.03629). The 2022 paper behind §1–§2's reason→act→observe loop — the foundation the whole agent paradigm traces back to.