The 6 concepts of M00B

Tap any concept to jump to its 5-card cluster.

• 1Why Three Approaches?The abstraction ladder — raw, SDK, spec
• 2Approach 1 — Raw Messages APIThe hand-rolled tool-use loop
• 3Approach 2 — claude-agent-sdkDeclarative tools, the loop goes away
• 4Approach 3 — Spec-DrivenWrite the spec, Claude Code writes the agent
• 5Side-by-Side ComparisonSame agent, three abstractions, measured
• 6When to Use WhichDecision rules for learning, shipping, scaling

Three rungs on the same ladder

There is exactly one HTTP call at the bottom of every Claude agent: messages.create. Everything else — the loop, the tool dispatch, the JSON schemas, the retries — is scaffolding that you can either write yourself, get from a library, or generate from a spec. Three rungs, same call underneath.

This module shows you all three rungs at once with the same toy agent (a time-lookup helper). You'll see the raw loop you'll learn to write in M01–M11, the SDK pattern you'll use from M12 onward, and the spec-driven workflow that powers M15B and every Tier 3 capstone. By the end you'll know why the course climbs the ladder in that order — not just what each rung looks like.

Three ways to make coffee

BEFORE: Picture three ways to make a latte. You can grind the beans by hand, heat water on the stove, weigh the dose, and pour over — every variable yours. You can press one button on a bean-to-cup espresso machine — it handles grind, dose, pressure, temperature. Or you can tell your smart kitchen, "make my usual before 7am," and an appliance follows the recipe you wrote last week.

PAIN: If you only ever press the button, you panic the day the machine breaks. If you only ever grind by hand, you can't make coffee at scale. If you only ever write recipes, you're lost when someone hands you raw beans and a stove.

MAPPING: Raw API is grinding by hand. The SDK is the espresso machine — one button, every detail handled. Spec-driven is the recipe — you describe the latte, the appliance assembles it. Same drink, three abstractions. Knowing all three is what makes you fluent.

The abstraction ladder

1. Rung 1 — Raw Messages APIYou write the tool-use loop, dispatch tools by name, accumulate messages, check stop_reason. ~50 lines of which exactly one is the API call. Mental load: high. Visibility: total.
2. Rung 2 — claude-agent-sdkYou declare tools with a decorator and options with one config object, then call query() and iterate. ~25 lines. Loop is gone. Hooks, sessions, permissions are built in.
3. Rung 3 — Spec-DrivenYou write a markdown spec describing the agent. Claude Code reads it, generates agent.py, tests, and a README. Zero lines of agent code from you — the spec is the source of truth.
4. What stays the sameEvery rung still bottoms out at messages.create. The same Claude model. The same prompt-and-response protocol. Only the scaffolding above it changes.

How the course uses each rung

The ladder is intentional. Tier 1 builds the protocol intuition. Tier 2 reveals the SDK by contrast. Tier 3 lets you stop writing agent code and start designing agents in markdown.

Misconceptions

Write the loop yourself, once

The raw Messages API is the lowest-level path. You write a while loop that sends messages to Claude, inspects stop_reason, runs any tools Claude asked for, appends the tool_result, and sends again. Nothing is hidden — every line of the agent loop lives in your file.

About 50 lines total. Roughly one of them is the actual API call; the other 49 are loop control, tool dispatch, and bookkeeping. That ratio is the whole point: once you see it, the SDK stops feeling like magic and starts looking like a useful abstraction.

The home cook with a chef's knife

BEFORE: Picture a home cook who sharpens their own knife, butchers the chicken themselves, chops every herb by hand, and watches the pan because they don't trust a timer. Every step they own.

PAIN: It takes them an hour to plate one dish. They can't scale to twenty diners. But the day the gas oven misfires they know exactly which part is broken — they've touched every component of the meal.

MAPPING: Raw API is the home cook with the chef's knife. Slower per dish, but every part of the agent — the loop, the tool dispatch, the message accumulation — is in your hand. When something goes wrong later (in the SDK, in production), you'll instantly know which layer to blame.

The five-step loop

1. SendPost the conversation so far to Claude with your list of tool definitions attached.
2. Check stop_reasonIf it's end_turn, Claude produced the final answer — return the text and exit. If it's tool_use, Claude wants you to run a tool.
3. Run the toolFind each tool_use block in the response, look up the named tool, call it with the supplied arguments.
4. Append both sidesAppend the assistant's response, then a user message containing one tool_result for every tool call. tool_use_id must match exactly.
5. LoopGo back to step 1. Continue until stop_reason says end_turn.

Memorise this. Domain 2 of the Claude Certified Architect exam tests it directly.

Pseudocode

The toy agent: a time-lookup helper with one tool, get_time(city).

# --- Tool definition (what Claude sees) ---
DEFINE tool "get_time":
  input: city (string, required)
  returns: "HH:MM on Weekday, DD Mon YYYY"

# --- The loop ---
FUNCTION run_agent(user_message):
  messages = [user_message]

  WHILE true:
    response = CREATE_MESSAGE(
      model = sonnet,
      tools = [get_time],
      messages = messages
    )

    IF response.stop_reason == "end_turn":
      RETURN response.text

    # stop_reason == "tool_use" — run each tool
    messages.append(assistant = response.content)
    results = []
    FOR EACH block IN response.content:
      IF block.type == "tool_use":
        out = DISPATCH(block.name, block.input)
        results.append(tool_result(block.id, out))
    messages.append(user = results)

Note: each tool_result's tool_use_id must equal the matching tool_use's id. Off-by-one here is the #1 cause of "agent froze".

Misconceptions

Declare. Don't loop.

The claude-agent-sdk replaces the hand-rolled loop with a single async iterator. You declare tools using a decorator, you declare options in one config object, then you call query() and consume messages as they arrive. There is no while. There is no stop_reason check. The loop runs inside the SDK.

You gain hooks (PreToolUse, PostToolUse, can_use_tool), MCP server wiring, permissions, sessions, and subagents — all the production scaffolding you'd otherwise build yourself. From M12 onward this is the default in the course.

The bean-to-cup espresso machine

BEFORE: Picture a commercial espresso machine. You pick the bean, the cup size, and the milk. Inside the box, a calibrated grinder, a temperature-controlled boiler, and a pressure pump do the rest.

PAIN: Make ten lattes by hand and you'll be exhausted by number three. Hand-tune temperature on every shot and your shop never opens. You need consistent throughput.

MAPPING: The SDK is the espresso machine. You declare what you want (a tool, a system prompt, a model, an allow-list) and the machine runs the loop, dispatches the tools, and streams results. The protocol you wrote by hand in Approach 1 is now a service you configure.

What the SDK adds

1. @tool decoratorTurns a plain function into an MCP tool with auto-generated schema. The JSON you wrote by hand in Approach 1 disappears.
2. create_sdk_mcp_serverWires your tools into an in-process MCP server. Local and remote tools end up with the same call shape.
3. ClaudeAgentOptionsOne config object holds the system prompt, model, max turns, allowed tools, hooks, and permission callbacks. No more loose arguments scattered through your code.
4. query() async iteratorOne call replaces the entire while loop. It yields messages as they stream — assistant text, tool calls, tool results — in order.
5. Hooks & permissionsPreToolUse, PostToolUse, and can_use_tool let you gate, log, or rewrite tool calls without rewriting the loop. You meet these in M16, M17, and M26.

Pseudocode

Same agent, no loop:

# --- Tool: decorator generates the schema for you ---
@tool("get_time", "current time in a city", {city: string})
FUNCTION get_time(args):
  RETURN text("HH:MM on Day, DD Mon YYYY")

# --- Wire the tool into an in-process MCP server ---
server = CREATE_MCP_SERVER(tools=[get_time])

# --- One config object for everything ---
options = AGENT_OPTIONS(
  system_prompt = "You are a time assistant.",
  mcp_servers   = {time: server},
  allowed_tools = ["mcp__time__get_time"],
  max_turns     = 4,
  model         = sonnet
)

# --- The entire agent loop, replaced by one line ---
FOR EACH msg IN SDK.QUERY(prompt=question, options=options):
  IF msg is assistant_text:
    PRINT msg.text

No while, no stop_reason, no tool_result assembly. The SDK runs the loop you wrote in Approach 1 — reliably, with hooks built in.

Misconceptions

Write the spec. Claude writes the code.

Spec-driven flips the role. Instead of writing agent.py by hand, you write spec/agent-spec.md — a markdown document that describes what the agent does, what tools it has, what tests must pass, and what's out of scope. Then you run one Claude Code command and an entire SDK-based project appears.

Claude Code reads the spec, generates the agent, the tests, the requirements file, and the README, then runs the tests and shows you the results. When you want to change behaviour, you edit the spec and regenerate. The spec is the source of truth; generated code is a build artefact.

The architect and the engineer

BEFORE: On a real engineering team, an architect writes a design doc — system shape, interfaces, invariants, tests. An engineer implements it. When the design changes, you update the doc and the engineer rebuilds; you don't patch the binary.

PAIN: If the design doc and the code drift apart, every new engineer reads the code instead of the doc, and the doc rots. The fix is to make the doc executable — to wire it directly into the build.

MAPPING: In spec-driven, you are the architect and Claude Code is the engineer. The spec is your design doc, and it's executable: one claude command turns it into a working project. When the design changes you edit the spec, not the code.

The spec-driven workflow

1. Write the specSave a markdown file at spec/agent-spec.md with sections: Overview, Agent Configuration, System Prompt, Tools, Files to Generate, Tests, and Out of Scope.
2. Run Claude CodeOne command: claude "Read spec/agent-spec.md and build the entire project as described." Claude Code reads the file, plans, and generates.
3. Claude generates the projectagent.py, tests/test_agent.py, requirements.txt, and README.md appear. The agent uses claude-agent-sdk under the hood — spec-driven sits on top of Approach 2.
4. Tests run automaticallyClaude Code runs pytest and shows you the results. If a test fails, it iterates and fixes — or surfaces the failure to you.
5. Iterate on the spec, not the codeTo add a city, fix a tone, or tighten a behaviour, edit the markdown and regenerate. The discipline keeps spec and code in lockstep.

Pseudocode

The whole workflow in two blocks — the spec sketch and the build command:

# --- spec/agent-spec.md (your single source of truth) ---
SPEC:
  overview        = "a time-lookup helper agent"
  model           = sonnet
  framework       = claude-agent-sdk
  system_prompt   = "You are a time assistant..."
  tools           = [get_time(city) -> "HH:MM on Day, ..."]
  files_to_emit   = [agent.py, tests/, requirements.txt, README.md]
  tests_must_pass = [
    "Tokyo returns matching regex",
    "Unknown city returns 'Unknown city:'",
    "Lookup is case-insensitive"
  ]
  out_of_scope    = [sessions, hooks, permissions]

# --- Build the project from the spec ---
READ spec/agent-spec.md
GENERATE project   # Claude Code emits all files
RUN pytest         # auto-verifies the spec's contract

# --- To change behaviour, edit spec; never patch generated code ---
EDIT spec/agent-spec.md
REGENERATE

The spec is short, complete, and testable. The "out of scope" list is as load-bearing as the in-scope items — it stops Claude Code from inventing features you didn't ask for.

Misconceptions

One agent, three abstractions, measured

Same toy agent — the time-lookup helper — built three ways. Same model, same tool behaviour, same final answer. The interesting differences are not in what the agent does but in what you write to make it do that thing, and in where the loop lives.

Putting the three side by side makes the trade obvious: lines of code, where logic lives, how you test, how you change behaviour. None of the three is "best" universally — each wins in a specific situation. The comparison itself is the lesson.

Three drivers, one destination

BEFORE: Three drivers leave the same city at 9am and meet at the same restaurant at noon. One drives a stick-shift with no GPS. One drives an automatic with lane-keep. One sits in the back of an autonomous car reading the newspaper.

PAIN: Compare only the destination and they're identical. Compare effort, attention, repair-ability, and "what happens when something breaks" and they're radically different cars.

MAPPING: Three agents arrive at the same answer. The interesting comparison is what each cost you to operate: how many lines, who runs the loop, who knows when something failed, who can teach you the protocol when the magic stops working.

What changes, what stays the same

1. What stays the sameThe model, the prompt-and-response protocol, the final answer the user sees. Every rung calls Claude with messages and tools and gets back text + tool_use blocks.
2. Lines you write~50 (raw) → ~25 (SDK) → 0 lines of agent code (spec; you wrote a ~40-line markdown spec instead).
3. Where the loop livesYour while (raw) → inside query() (SDK) → inside the generated agent that uses query() (spec).
4. How you change behaviourEdit Python (raw) → edit config + Python (SDK) → edit markdown and regenerate (spec).
5. What you give up at each stepVisibility → less of it but you gain hooks/permissions → less of it but you gain a single source of truth and automatic tests.

The numbers that actually matter

Numbers are from the actual files in the M00B desktop lab. They'll match within ~10% on your machine.

Misconceptions

Match the rung to the moment

There is no single "right" approach — there's a right approach for your current situation. Are you learning the protocol? Debugging an SDK issue? Shipping a production endpoint with hooks and audit logs? Bootstrapping a brand-new agent whose design isn't fixed?

Each rung wins in a specific situation and loses in the others. The skill is not picking "the best" rung once — it's recognising the situation and reaching for the matching rung. The decision framework on the next two cards gives you a checklist.

The carpenter's three saws

BEFORE: A carpenter owns a hand saw, a circular saw, and a CNC router. The hand saw is slow and precise. The circular saw is fast and rough. The CNC router is programmed once and cuts a hundred identical pieces.

PAIN: The apprentice who only knows the CNC can't make a custom shelf for a friend. The veteran who refuses to use the CNC can't deliver fifty kitchens a month. The wrong tool wastes the project.

MAPPING: Raw API is the hand saw — precise, slow, teaches you everything. The SDK is the circular saw — fast, productive, the daily driver. Spec-driven is the CNC — design once, mill many. A complete carpenter owns and uses all three, on purpose.

Three situations, three winners

1. Use Raw API when learningYour first agent should be hand-rolled. Once you can write the five-step loop from memory, the SDK stops feeling magical and starts looking like a useful tool.
2. Use Raw API for unusual controlCustom retry policies, exotic streaming, embedding the call in an existing event loop, or debugging an SDK problem. Raw stays in your kit even after you adopt the SDK.
3. Use the SDK when shippingHooks, sessions, permissions, MCP servers, subagents. Anything heading to production with observability and audit logs starts here.
4. Use Spec-Driven for new projectsWhen the design isn't fixed, iterate on the spec instead of the code. You converge on the design without committing to an implementation that's expensive to throw away.
5. Use Spec-Driven for handoffsThe spec is both the design doc and the build prompt. A new team-mate reads one markdown file and can regenerate the entire project from it.

Which rung, right now?

# What is your current situation?

IF you are learning the protocol for the first time:
  USE Raw Messages API
  # Write the five-step loop once, by hand

ELIF you are debugging the SDK or need unusual control:
  DROP to Raw Messages API for the affected path
  # The SDK and raw API coexist in one project

ELIF you are shipping production with hooks/audit/sessions:
  USE claude-agent-sdk
  # Default for everything from M12 onward

ELIF the design is unfixed OR the project is a Tier 3 capstone:
  USE Spec-Driven on top of the SDK
  # Iterate on the spec, regenerate the code

ELSE:
  DEFAULT to claude-agent-sdk
  # When unsure, the SDK is the safest default

These approaches stack. By M15B you'll write a spec that generates an SDK-based agent, with one tight raw-API code path inside it for retries — all in the same project.

Misconceptions

Quick Quiz

Six questions, one per concept. Tap to reveal the answer.