Start Here: Student Follow-Along Guide

This workbook is the student version of the one-day intensive. It removes instructor-only delivery notes and turns the course into a practical follow-along reference. Keep the GitHub repository open while you read, because the examples, anti-patterns, pre-work, and commands are part of the exercise flow.

How to use each module

1. Read the framing and vocabulary before the live block starts.
2. Open the linked example and anti-pattern artifacts from the repo.
3. Build the named artifact for that block.
4. Use the critique prompt: What would make this better as a downstream input?
5. Keep your final artifacts short enough for another operator to use without reopening the whole conversation.

Module 1 · 70 minutes

Build Claude Code Primitives

If you have only ever used Claude Code as one long chat box, this is where that habit breaks. The move that separates a casual user from a team-scale operator is small but total: instead of pouring everything into a single endless conversation, you start reaching for the right building block (a command, a skill, a subagent, a hook) for each kind of work. Do not try to memorize the catalog yet. By the end of this module you will have built one of each with your own hands, and the judgment for which to reach for starts to feel obvious once you have made the call a few times.

Why primitive design is the first skill

Most failed AI-assisted engineering sessions do not fail because the model is incapable. They fail because the work is routed to the wrong primitive. A developer asks for a broad implementation when the real need is investigation. A team writes a permanent rule into a one-off prompt. A repeated checklist stays trapped in someone’s memory instead of becoming an executable skill. A heavyweight model is used for cheap file discovery, while a complex design decision is handed to a fast model with insufficient reasoning depth.

A Claude Code operating model therefore begins with vocabulary. Not vocabulary for its own sake, but vocabulary that gives the team a shared way to decide where work should live. Once the team can say “this is a command,” “this is a skill,” “this belongs in memory,” “this should be a subagent,” “this is a hook,” or “this needs a headless run,” the tool stops being mysterious and starts becoming an engineering system.

The primitive build lab

Think of Claude Code as a workbench with several surfaces. The interactive session is where a human and model negotiate a task. Tools are the model’s hands: reading files, running commands, searching repositories, editing code, and interacting with configured integrations. Commands are named entry points that standardize common activities. Skills package reusable procedures. Agents and subagents isolate specialized work. Plugins and marketplace content extend what is available across projects or organizations. Headless execution turns the same operating model into automation.

The practical question is not “which feature is coolest?” The practical question is: where should this work be represented so that another engineer can reuse it without rediscovering it?

Interactive versus headless work

Interactive mode is for discovery, negotiation, and judgment. A human can interrupt, correct assumptions, ask for alternatives, and decide whether the model’s next step is safe. Headless mode, Claude Code’s non-interactive print mode invoked with claude -p (--print), is for work that has already been bounded. It needs clear inputs, allowed tools, expected outputs, and stop conditions. If the task still requires a human to decide what the task is, it is not ready for headless execution.

A good rule is this: interactive sessions produce artifacts; headless sessions consume artifacts. During a live session you might create an Implementation Plan, Explore findings, or Review. Once those artifacts are stable, a headless run can implement a bounded change, run a review, or generate a report from known inputs.

Goal mode and debate mode

Two conversational modes matter today. Goal mode is useful when you want the model to drive toward a defined outcome. Debate mode is useful when you want the model to challenge a plan before code is written. Goal mode helps with forward motion; debate mode helps with error prevention. Both are most useful when paired with artifacts.

For example, a developer might ask Claude to draft an Implementation Plan in goal mode. Once the brief exists, the developer can switch into a debate posture: “Challenge this brief. Identify hidden assumptions, underspecified acceptance criteria, and likely regression risks.” The output of the debate should not be a wandering conversation. It should be a better brief.

Model selection for the job

Model selection is part of work primitive design. Cheap, fast models are appropriate for bounded lookup, file discovery, and summarizing known material. Balanced models are appropriate for routine implementation and review. The strongest reasoning models are appropriate for architecture, tricky debugging, multi-file refactors, and decisions where a bad plan is more expensive than slower planning.

Building the Claude Code primitive kit

The primitive kit is the first durable artifact of the day. It is the set of primitives you have actually crafted (a tool posture, a command, a skill, a subagent, and a plugin decision), each written down with explicit boundaries. Give every primitive a compact spec so another engineer can pick it up without guessing: what it does, which mode and model it runs in, what it needs as input, what it produces, and when it should stop. Keep the kit small enough to live in a repo, onboarding guide, or team operating doc, and concrete enough to describe the actual next version of the team’s workflow rather than an aspiration.

Below is a real, working code-review plugin that bundles every primitive in one place. Use the dropdown to walk through each: the plugin manifest that ties them together, a command, a skill, a subagent, a hook, and a bundled tool (a CLI script). Edit any of them and the box turns green when the format is valid.

It is one connected plugin, not six unrelated files: the /review-pr command runs the pr-review skill and delegates to the pr-reviewer subagent, which runs the check-diff tool and the github MCP server. That is how primitives stitch into a workflow. The layout mirrors a real plugin: closedloop-ai/claude-plugins/plugins/code.

A note on tools: you rarely “define” a tool. Claude already uses its built-in tools and any CLI binary on your PATH (run via Bash under your permission rules), so it is usually smart enough to just use them. The two ways to extend the set are to ship a helper script in the plugin (like check-diff.sh) or to add an MCP server, which exposes entirely new tools.

Task: Review a PR for auth regressions
Primitive: security-reviewer agent + /code-review command
Mode: interactive for local development; headless only after the rule set is stable
Model: balanced model for normal review, stronger reasoning for high-risk auth changes
Inputs: diff, Implementation Plan, REVIEW.md, relevant auth rules
Output: findings-first review with severity, evidence, and recommended fix
Stop condition: no important findings or explicit residual risk accepted by human

What good looks like

A good primitive kit has three qualities. First, it is specific. “Use Claude for coding” is not useful; “use an explorer subagent to identify files before reading them into the main session” is useful. Second, it is bounded. Each entry says what the primitive should and should not do. Third, it is teachable. A new engineer should be able to read the kit and make the same primitive design decision as a senior engineer most of the time.

Anti-patterns

• The mega-prompt: A long prompt that mixes stable policy, one-time instructions, codebase facts, and a workflow checklist. Split it into memory, project instructions, skill, and task prompt.
• The everything-agent: A custom agent named “senior engineer” that can do anything. Specialized agents should have a narrow lens, clear tools, and a predictable output shape.
• Premature plugin packaging: A workflow is packaged before the team has run it enough times to know its inputs, failure modes, and stop conditions.
• Headless ambiguity: A non-interactive run is launched with vague goals and no acceptance criteria. Headless work should consume a brief, not invent one.

From primitives to workflows

Crafting primitives is only half of Module 1. The other half is noticing that primitives are meant to be stitched together. A real task rarely uses one primitive in isolation: an explorer subagent finds the files, a command kicks off the change, a review agent checks the diff, a skill packages the verification. The sequence that connects them is a workflow, and Module 5 is where you design one deliberately.

That immediately raises the question this course spends the rest of the day answering: once you can stitch primitives into a workflow, how do you tell that workflow what to accomplish? A workflow with no clear goal, no boundaries, and no definition of done will wander no matter how good its primitives are. That is exactly the problem Module 2 picks up.

Module recap

Notice what you just did: you stopped asking "how do I word this prompt?" and started asking "where should this work live?" That is the whole shift. Prompt cleverness fades the moment the conversation ends; a primitive you crafted keeps paying out every time you or a teammate reaches for it. Carry that instinct into the rest of the day, because every module from here builds on primitives you now know how to make.

Module 2 · 55 minutes

Planning and Context Management

Module 1 ended on a question: once you can stitch primitives into a workflow, how do you tell it what to accomplish? Planning is the answer. In Claude Code, planning is not a ceremonial step before coding; it is the act of shaping context so the next operator (human, model, agent, or headless workflow) can act without reopening the entire problem.

The plan is a compression artifact

Claude Code sessions can accumulate enormous context: pasted requirements, file contents, terminal output, attempted fixes, test failures, screenshots, and corrections from the human. Without deliberate compression, the session becomes expensive and fragile. The model is forced to infer what still matters from a long transcript. Humans are forced to remember why earlier decisions were made. Downstream operators inherit noise instead of a plan.

A useful plan is not a transcript. It is a lossily compressed representation of the work. It preserves the facts, decisions, constraints, risks, and next actions that matter. It discards the conversational path that produced them. That is why this session treats planning as context management.

Separate facts, assumptions, and open questions

The simplest improvement to most AI coding sessions is to stop blending known facts with guesses. Models are very good at continuing a confident narrative. If the prompt says “the auth middleware probably owns refresh-token invalidation,” the model may proceed as if that is true. A disciplined brief separates evidence from inference.

The Implementation Plan

The Implementation Plan is the central planning artifact. It should fit on one or two pages, but it should be complete enough for another operator to execute. The brief is not just a summary. It is an instruction-bearing artifact with a clear contract: here is the problem, here is the known context, here are the boundaries, here is the proposed path, and here is how we will know whether the work is done.

# Implementation Plan

## Goal
Implement refresh token rotation without changing the existing login response contract.

## Known facts
- JWT validation happens in src/auth/middleware.ts.
- Session persistence is implemented in src/auth/session-store.ts.
- Existing tests cover login success and expired access tokens.

## Assumptions to verify
- Old refresh tokens are not currently invalidated after rotation.
- Token reuse should be treated as suspicious but not immediately lock the account.

## Open questions
- Should reuse detection emit an audit event?
- Is token family tracking already present in the database schema?

## Context map
- Auth middleware: request validation and session lookup
- Session store: token persistence and expiration
- Test suite: integration tests under tests/auth/

## Work packages
1. Verify current token rotation behavior.
2. Add invalidation logic or token-family tracking.
3. Extend integration tests for old-token reuse.
4. Produce Review.

## Acceptance criteria
- New refresh token is issued on rotation.
- Previous refresh token cannot be reused.
- Existing login response shape is unchanged.
- Tests demonstrate success, expiration, and reuse behavior.

Context maps

A context map tells the model where to look and why. It is not a full dump of file contents. It is a pointer layer: directories, files, functions, commands, external systems, and documents that are likely relevant. Good context maps reduce token use because Claude can read the right files in the right order instead of scanning the repository blindly.

A context map should include both primary and secondary context. Primary context is required to make the change. Secondary context helps review risk, verify behavior, or understand why the system is shaped the way it is.

## Context map
Primary:
- src/auth/middleware.ts: request authentication boundary
- src/auth/session-store.ts: refresh token persistence
- db/schema.sql: session and token tables
- tests/auth/refresh-token.test.ts: integration behavior

Secondary:
- docs/security/auth-model.md: intended auth posture
- .claude/rules/api-security.md: project-specific security rules
- recent PRs touching auth middleware: intent and regression context

Debate review before coding

Before code is written, ask Claude to attack the plan. The goal is not to win the debate; the goal is to improve the artifact. A debate review should look for ambiguous goals, missing constraints, unsupported assumptions, hidden coupling, risky files, weak acceptance criteria, and likely regression paths.

Review this Implementation Plan as a skeptical senior engineer. Identify unsupported assumptions, missing context, and acceptance criteria that would fail to catch a regression. Do not implement. Return a revised brief outline and a list of questions that must be answered before coding.

The output of debate review should be folded back into the brief. If the debate produces useful insights that remain trapped in conversation history, the next operator still cannot use them. Artifact-first planning means the artifact is the durable memory.

What makes a plan reusable downstream?

A reusable plan has clear boundaries. It names the exact goal, the non-goals, the files likely involved, the evidence already gathered, the assumptions still open, and the stop condition. It also includes enough review criteria to prevent the model from declaring success too early.

Goal

What outcome should exist after the work is complete?

Non-goals

What tempting adjacent work should not be done?

Facts

What has been directly observed?

Assumptions

What might be true, but needs verification?

Context map

Where should the next operator look first?

Work packages

What are the smallest implementation units?

Acceptance criteria

What evidence will prove the work is complete?

Review focus

What risks should review emphasize?

Module recap

Planning in Claude Code is not about slowing down. It is about preserving momentum by producing a compact artifact that can survive compaction, handoff, review, and automation. The better the brief, the less the model has to infer and the easier it is for humans to hold the work accountable.

Module 3 · 60 minutes

Intent Recovery and Dynamic Evidence

A plan tells the model what to do; this module makes sure the plan is built on why the code looks the way it does. When a codebase is old enough, the current code is rarely the whole story. You will recover intent from Git history, issues, PRs, logs, tests, command traces, and screenshots before asking Claude to change behavior.

Bloated (costs tokens twice: once now, again on every later turn):
  [pastes full pnpm test output, full middleware.ts, full session-store.ts]

Compressed (same signal, a fraction of the tokens):
  Evidence:  refresh-token.test.ts:42, old token reuse returns 200, expected 401
  Evidence:  PR #184 added rotation; diff shows no invalidation step
  Inference: invalidation likely belongs in session-store.ts, not middleware.ts
  Unknown:   does the schema already track token families?
  Pointer:   src/auth/session-store.ts:88 (rotate fn)

Find the why before the what

Claude can usually explain what code does from the current files. The harder question is why it does that. Was a strange branch added for a customer-specific edge case? Did a test encode a production incident? Was a confusing abstraction introduced to support a migration that has since finished? Current code often hides the reason for its own shape.

Intent recovery is the discipline of gathering enough historical and runtime evidence to avoid undoing deliberate behavior. It is especially important when the requested change appears simple. Simple changes are dangerous when they cut across hidden intent.

Static code is not enough

Reading the current file gives one kind of evidence. Git history gives another. Tests reveal expected behavior. Issues and PRs reveal tradeoffs. Logs reveal runtime reality. Screenshots reveal UI states that code alone may not make obvious. CLI traces reveal exact failure modes. Documentation and MCP-backed systems can provide external context that is not stored in the repository.

Evidence versus inference

A strong Explore findings labels evidence. It does not say “the bug is caused by stale cache” unless there is direct evidence. It says “the failure appears after the cache read path; logs show cache hit with outdated value; no write-through event appears in the trace; inference: stale cache is likely.” This distinction matters because the next model turn will use the memo as context. If guesses are written like facts, the model will build on them.

# Explore Findings
# Builds on the Module 2 Implementation Plan: "refresh token rotation".

## Question
Why is an old refresh token still accepted after rotation issues a new one?

## Evidence gathered
- Reproduces: pnpm test tests/auth/refresh-token.test.ts: old-token reuse returns 200, expected 401.
- Server logs show the session store resolves the previous token after rotation.
- Git history shows rotation added in PR #184 with no invalidation step.
- src/auth/middleware.ts validates tokens but never deletes the prior record.

## Inferences
- Rotation issues a new token but does not invalidate the previous one.
- Invalidation likely belongs in the session store, not the middleware.

## Open questions
- Where should the previous token be invalidated: session store or middleware?
- Should reuse of an old token emit an audit event?

## Recommended next step
Trace refresh-token writes and invalidation in src/auth/session-store.ts before changing code.

Dynamic evidence sources

Dynamic evidence is information that changes with execution: logs, test runs, database state, browser behavior, CLI output, screenshots, observability traces, and external tool responses. It is powerful because it grounds the model in reality. It is also noisy. A good operator does not paste raw dynamic output indiscriminately. They capture the relevant excerpt, label how it was produced, and explain why it matters.

When collecting dynamic evidence, include command provenance. The model should know not only the output, but the command, environment, timestamp or branch, and whether the result was reproducible.

Command: pnpm test tests/auth/refresh-token.test.ts --runInBand
Branch: refresh-token-rotation
Result: failed, 1 test
Relevant output:
  expected old refresh token reuse to return 401
  received 200
Interpretation:
  Existing implementation issues a new refresh token but does not invalidate the previous token.

Why “that didn’t work” fails as feedback

The phrase “that didn’t work” is almost useless to the model. It omits what was attempted, what was expected, what actually happened, what evidence was observed, and what changed between attempts. Good feedback is a bundle: action, expectation, observation, evidence, hypothesis, and next constraint.

The Request Changes pattern

A Request Changes review is a structured correction that improves the next model turn. It should be short, but it must contain enough evidence for the model to update its plan. Use it whenever Claude’s first implementation fails, when a test result contradicts an assumption, or when a human reviewer spots a gap.

# Request Changes

## Attempted change
Added token rotation logic in src/auth/middleware.ts.

## Expected result
Old refresh token reuse should return 401.

## Actual result
Old refresh token reuse returns 200.

## Evidence
Test: pnpm test tests/auth/refresh-token.test.ts
Failure: expected 401, received 200
Trace: old token still resolves in session-store lookup.

## Updated hypothesis
Middleware is not the right layer for invalidation. The session store accepts both token records.

## Next instruction
Inspect session-store token persistence and invalidation. Do not change response shape.

Module recap

Intent recovery prevents well-intentioned regressions. Dynamic evidence prevents hallucinated debugging. Request-Changes reviews convert failure into useful context. Together, they turn Claude Code from a code generator into an evidence-driven collaborator.

Module 4 · 60 minutes

Review, Test, and Verify

The work is not done when code changes. It is done when the diff has been reviewed against the plan, the verification evidence is explicit, and the residual risk is clear enough for a human to accept or reject.

Review the diff against the plan

A Claude-assisted review should not ask “does this code look good?” That question is too broad and too subjective. The stronger question is: “does this diff satisfy the Implementation Plan without violating constraints or introducing unacceptable risk?” The brief becomes the review contract.

Findings-first review means the reviewer leads with issues, not narrative. Each finding should state severity, evidence, affected file or behavior, why it matters, and a recommended fix. If there are no blocking findings, the review should still describe what was checked and what residual risk remains.

# Review Finding

Severity: Important
Area: Refresh token invalidation
Evidence: tests/auth/refresh-token.test.ts covers successful rotation but not reuse of the old token.
Why it matters: The acceptance criteria require old refresh tokens to be rejected.
Recommended fix: Add a regression test that attempts reuse of the previous token after rotation and expects 401.

Scope drift

Scope drift is any change that is not required by the brief. Some drift is harmless cleanup. Some drift is dangerous because it changes behavior the team did not intend to change. Claude can drift when it sees adjacent improvements, especially if the prompt rewards broad helpfulness. Review must therefore compare the diff against explicit goals and non-goals.

Testing is one gate, not the only gate

Passing tests are necessary evidence, but they are not proof of correctness. Tests only cover what they assert. A Review should include test results, manual checks when relevant, static review, diff review, command outputs, and residual risk. The point is not to create paperwork. The point is to prevent the phrase “tests pass” from hiding an unreviewed assumption.

For LLM-assisted work, verification should also include provenance: what files changed, what commands were run, what evidence was observed, and what the model did not check. This gives the human reviewer a clear map of confidence and uncertainty.

The Review

# Review

## Plan alignment
Goal: Refresh token rotation rejects old token reuse.
Status: Implemented and tested.

## Changed files
- src/auth/session-store.ts: invalidates previous refresh token on rotation
- tests/auth/refresh-token.test.ts: adds old-token reuse regression test

## Evidence
- pnpm test tests/auth/refresh-token.test.ts: passed
- pnpm test tests/auth/login.test.ts: passed
- Manual API check: old refresh token returns 401 after rotation

## Scope review
No public response contract changes observed.
No unrelated auth routes modified.

## Residual risk
Database cleanup of invalidated token records is not addressed. Existing retention behavior remains unchanged.

## PR handoff note
Reviewer should focus on token-store concurrency and whether invalidated token retention meets audit expectations.

Regression risk

Regression risk is not just the probability that something breaks. It is the product of likelihood, blast radius, and detectability. A small likelihood with a huge blast radius still deserves attention. A likely bug with easy rollback may be acceptable if the release path is safe. Claude can help enumerate risks, but the team must decide what risk is acceptable.

What makes a handoff PR-ready?

A PR-ready handoff gives the reviewer the shortest path to an informed decision. It should contain the problem statement, brief link or summary, changed files, review focus, verification evidence, known non-goals, and residual risk. The reviewer should not need to reconstruct the story from chat history.

Going further · Level 4

Review as a fleet, not a reviewer

Everything above describes one reviewer making one pass. That is the right default, and for most diffs it is enough. But a single reviewer has a single blind spot, and on a high-risk change (auth, a migration, anything touching money or user data) one pass is a gamble. The advanced move is to stop treating "the review" as one agent and start orchestrating a small fleet.

Two ideas do most of the work. The first is lens diversity: instead of one general review, fan out several reviewers in parallel, each pinned to a single question, then merge what they find. A reviewer told only "hunt for security holes" catches things a generalist skims right past.

The second idea is adversarial verification, and it is the one that keeps Claude honest. A model will state a finding with total confidence whether or not it is real. So before you act on a finding, spawn a skeptic whose only job is to refute it, and keep the finding only if the skeptic cannot. For a critical change, use a small panel and keep a finding only when it survives a majority. This is exactly how a serious automated review pipeline is built, and how Claude Code's own /code-review works under the hood: parallel hunters and an auditor surface candidates, a verifier pass then tries to falsify each one, and synthesis reports only what survived.

Orchestrated review (shape, not syntax):

  fan out  →  [correctness] [security] [scope] [regression] [tests]   one lens each, in parallel
  collect  →  merge and dedupe the raw findings
  verify   →  for each finding, spawn a skeptic that tries to refute it
  keep     →  only the findings the skeptic could not refute
  report   →  severity-ranked, each with the evidence that survived

Module recap

Review and verification discipline turns model output into engineering evidence. The goal is not to make Claude “sound confident.” The goal is to make the work auditable: what changed, why it changed, how it was checked, and what remains uncertain.

Module 5 · 45 minutes

Workflow Design and Minimal Improvement Loop

Module 1 introduced workflows as the way to stitch primitives together; this is where you design one deliberately. The session closes by turning the day’s isolated practices into a single named workflow (with handoffs, gates, stop conditions, and one lightweight Workflow retro) so the next run can improve without expanding into a full operating-system redesign.

From good sessions to repeatable workflows

By now the individual moves should feel routine, so this module asks more of you: stop thinking about a single good session and start engineering a system that produces good sessions on demand. A brilliant one-off that no one can reproduce is, organizationally, a dead end. The discipline here is to capture the sequence that made the session work (how the work was framed, what artifacts were produced, which agents or skills carried each phase, where a human had to sign off, and what evidence counted as done) and harden it into something named, bounded, and reusable. Get this right and the payoff is not linear: a named workflow runs again next week, transfers to the next project, and onboards a new teammate without you re-teaching the whole system. That is the leverage that compounds.

This module is intentionally compact. The goal is not to design a full engineering operating system; it is to leave with one workflow you can try next week and improve after one run.

A compact multi-agent workflow

Before the design, a word on what a workflow physically is. In Claude Code a workflow is not a special file format or a piece of product UI; it is just a markdown file that describes the sequence: the trigger, the roles, the handoffs, the gates, and the stop condition. You make it runnable by saving it as a slash command (.claude/commands/<name>.md) or as a skill (.claude/skills/<name>/SKILL.md), at which point invoking it replays the whole sequence. That is the entire mechanism: the workflow below is the content of one such markdown file.

Multi-agent workflow design should begin with work boundaries, not agent names. Each agent or subagent should own a distinct lens or phase. If two agents need the same broad context and produce overlapping output, the workflow is probably not decomposed well.

# Workflow

Name: Evidence-first bug fix

Trigger:
A bug report has enough detail to reproduce or investigate.

Artifacts:
1. Explore findings
2. Compact Implementation Plan
3. Implementation diff
4. Review

Roles:
- Explorer subagent: identify relevant files, history, and evidence sources
- Planner: compress evidence into Implementation Plan
- Implementer: make bounded code changes from the brief
- Reviewer: compare diff against brief and produce findings

Gates:
- Do not implement until facts, assumptions, and open questions are separated.
- Do not review until acceptance criteria are explicit.
- Do not hand off until verification evidence and residual risk are written.

Stop condition:
The change is PR-ready or blocked by a named open question.

Handoffs

A handoff is where one operator’s output becomes another operator’s input. In Claude Code workflows, handoffs should be artifact-based. The explorer hands off Explore findings. The planner hands off an Implementation Plan. The implementer hands off a diff plus notes. The reviewer hands off findings and verification evidence. If a handoff requires the next operator to read the entire chat transcript, the handoff failed.

Gates and stop conditions

Gates prevent premature motion. Stop conditions prevent infinite motion. A gate says what must be true before the workflow can advance. A stop condition says when the workflow is complete, blocked, or unsafe to continue. Claude workflows need both because models tend to continue helping unless told what “done” means.

Good gates are observable. “Make sure the plan is good” is not a gate. “The brief includes goal, non-goals, facts, assumptions, open questions, context map, work packages, and acceptance criteria” is a gate. Good stop conditions are explicit. “Continue until fixed” is vague. “Stop when the Review shows the acceptance criteria pass, or when an open question blocks safe implementation” is actionable.

A useful test for a good gate: could a teammate who was not in the room mark it pass or fail without asking you? The examples below all pass that test.

Weak (a preference)            →  Strong (an observable gate)
"the plan is good"             →  "the Implementation Plan names goal, non-goals,
                                   facts, assumptions, open questions, context map,
                                   work packages, and acceptance criteria"
"investigation is done"        →  "every claim in the Explore findings cites a
                                   file:line, command, or commit"
"it's been reviewed"           →  "the Review lists each acceptance criterion as
                                   pass/fail with evidence, and residual risk is named"
"tests look fine"              →  "pnpm test exits 0 and a regression test for the
                                   reported bug exists and passes"

Going further · Level 4

Orchestration patterns for bigger workflows

The Evidence-first workflow above is linear: explorer, then planner, then implementer, then reviewer, one after another. That is the right shape to learn on. But once a workflow grows past a couple of agents, how they run starts to matter as much as what each one does, and a handful of patterns separate a workflow that merely works from one that is fast, thorough, and reproducible.

Two rules keep orchestration from turning into a liability. First, put the control flow (the loops, the conditionals, the fan-out) in the workflow itself, not in the model's head; deterministic orchestration is reproducible, while model-driven orchestration is a fresh roll of the dice every run. Second, set limits before you fan out: cap how many agents run at once, give the run a token budget so a runaway loop cannot drain it, and when several agents edit files in parallel, give each its own git worktree so they do not clobber one another.

Guarding the main branch against slop

Orchestration makes a workflow productive; this is what keeps it safe. The faster Claude produces code, the easier it is for plausible-looking slop (code that compiles, reads fine, and is quietly wrong, out of scope, or never actually verified) to slip onto a branch. The defense is two layers that back each other up: cheap automated gates that catch mechanical slop, and human gates that own the judgment a machine should not make.

The first layer is CI checks. A workflow's stop condition is a promise; CI is what enforces that promise when no one is watching. Past the table stakes (lint, typecheck, and tests must be green), wire in checks aimed squarely at AI output:

Because a workflow is just a markdown file (the point from earlier in this module), you can run the review itself headless in CI: feed claude -p the diff plus the Implementation Plan, and fail the pipeline if the change drifts from the plan or a blocking finding cannot be verified away. That turns the review fleet into a merge gate that runs on every push, not a courtesy a human remembers to perform.

# .github/workflows/ai-review.yml (shape, not a full config)
- run: npm run lint && npm run typecheck && npm test     # table stakes
- run: scripts/check-plan-drift.sh                          # diff matches the plan's scope
- run: |                                                    # headless review gate
    claude -p "Review this diff against PLAN.md. Output BLOCKING findings only,
    each verified against the code. Exit non-zero if any survive." \
      --allowedTools Read,Grep,Bash(git diff:*) > review.txt
- run: scripts/fail-if-blocking.sh review.txt               # red build on surviving slop

The second layer is human guards, and no amount of automation removes it. ClosedLoop's milestone model (Draft → In Review → Approved → Executed → Done) exists precisely so a person signs off before an AI-produced change advances. Some calls stay human on purpose:

• Accepting residual risk. CI can surface the risk; a person has to decide it is acceptable to ship. That decision carries a name.
• No agent self-merge. An agent can open the PR and make it green, but a human approves the merge. The machine does the work; the human owns the outcome.
• Scope changes. If the diff exceeds the brief, that is a conversation, not an auto-approval, no matter how green the build is.
• High-blast-radius changes. Auth, migrations, money, and anything user-visible get a named approver, even when every automated gate passes.

One lightweight Workflow retro

A Workflow retro is a short retrospective: a five-minute, structured look back you run after a workflow completes, asking what worked, what did not, and the single thing to change before the next run. It is the same idea as a sprint retro, but pointed at the workflow itself (its artifacts, evidence, and gates), not at the team. The improvement loop should be small enough that the team actually uses it. Pick one Workflow retro that can be completed after a workflow run in five minutes. The Workflow retro should measure the workflow, not the model’s personality. It should ask whether artifacts were reusable, whether evidence was sufficient, whether context was controlled, whether review caught issues, and what should change next run.

# Workflow Retro

Workflow name:
Date:
Task:

1. Was the Implementation Plan usable without reopening the original conversation? 0 / 1 / 2
2. Did the Explore findings separate evidence from inference? 0 / 1 / 2
3. Did the implementation stay inside the stated scope? 0 / 1 / 2
4. Did verification include more than passing tests? 0 / 1 / 2
5. Was residual risk explicit? 0 / 1 / 2

One thing to keep:
One thing to change next run:
One artifact or rule to update:

What to improve on the next run

Do not try to improve everything after the first run. Choose one improvement. Maybe the context map was too vague. Maybe the review agent needs a narrower rubric. Maybe the Implementation Plan omitted non-goals. Maybe verification evidence was too thin. The Workflow retro turns that observation into a small change: update a template, add a rule, refine a skill, or adjust a gate.

Closing synthesis

Step back and look at the whole arc you just walked. You started by reaching for the right primitive instead of one long chat. You learned to compress a problem into a plan, to recover the intent behind code before changing it, to review a diff against that plan, and finally to wire the sequence that worked into a workflow you can run again. Each skill fed the next; together they form one loop. That loop is small enough to learn in a day and strong enough to carry a whole team. Run it on a real change this week, keep the artifacts, and you will feel the difference on the very next one: less rework, faster shipping, and a growing library of assets that make every future run cheaper and more reliable. That is what moving from operating Claude Code to mastering it actually looks like.

Appendix: Student Desk Reference and Repo Links

Core commands and settings

Context pointers

• Search before reading: use grep/file search to find paths and line numbers first.
• Read narrowly: use offsets and limits instead of loading entire files.
• Label evidence: command run, source, timestamp, relevant excerpt, and why it matters.
• Separate facts, assumptions, open questions, and inferences.
• Compact between tasks and tell compaction what to preserve.

Primary repo links

• Training repository root
• One-day intensive presentation guide
• One-day live agenda
• Demo artifacts and anti-patterns
• Plugins, skills, commands, and models
• Claude Code changelog

Concrete Examples, File Locations, and Repo Links

Tools and permissions

Tools are the model action surface: reading, searching, editing, running commands, fetching context, and calling integrations. The course examples emphasize matching tool access to task risk rather than allowing everything by default.

Permission prompt pattern:
What must Claude read?
What may Claude write?
What requires approval?
What would be dangerous if Claude guessed?
What evidence is required before widening permissions?

Commands

Commands are for short, prompt-shaped, directly invoked operations. Use them when the behavior repeats but does not need a full method, bundled assets, or a specialist role.

# .claude/commands/summarize-failing-test.md
Summarize the failing test evidence in this shape:
1. Command run
2. First failing assertion or error line
3. Relevant file and line pointer
4. Likely failure category
5. Next narrow read or command

Do not propose a fix until the failure category is grounded in evidence.

Skills

Skills are for repeatable methods with structure: required inputs, context gathering, workflow, output artifact, verification checklist, and safety rules.

# .claude/skills/flaky-test-investigation/SKILL.md
# Skill: flaky-test-investigation

## Purpose
Investigate a flaky test using evidence before proposing a fix.

## Required inputs
- failing command
- test name or file
- relevant CI/local output

## Workflow
1. Capture exact command and failure excerpt
2. Classify the failure mode
3. Identify dynamic evidence needed
4. Produce Explore findings
5. Propose the next narrow action

## Outputs
Explore findings with evidence, inference, and next step.

Agents and subagents

Agents and subagents are bounded workers with a mission, explicit tools, output shape, and stop condition. Use them when you need separate context or specialist review.

# .claude/agents/security-reviewer.md
---
name: security-reviewer
description: Review code changes for security vulnerabilities. Use proactively.
tools: Read, Grep, Glob, Bash
model: sonnet
maxTurns: 10
---

You are a security specialist. For every code change:
1. Check for injection vulnerabilities
2. Verify input validation at system boundaries
3. Check for exposed secrets or API keys
4. Verify authentication and authorization checks

Report findings by severity. Do not edit files unless explicitly asked.

Plugins and marketplace evaluation

Plugins are a distribution abstraction. A plugin can package multiple reusable units such as commands, subagents, MCP servers, hooks, skills, or workflow assets. Evaluate a plugin like dependency surface area, not like a shortcut.

Demo artifacts and anti-patterns

Setup and supporting files

• Lab 00 setup
• One-day prework checklist
• One-day live agenda
• One-day intensive presentation guide
• Demo artifacts directory
• Latest Claude Code changelog

Token Efficiency Throughout the Course

Token efficiency is not a separate optimization topic. It is the connective tissue across primitive design, planning, investigation, review, and workflow design, and it is money: tokens are cost and context is speed, so disciplined context means lower cost-to-serve and more work shipped per hour. The habits below should show up in every exercise.

Module-by-module token habits

Token-efficient prompt patterns

Search first. Return only matching file paths and line numbers. Do not read full files yet.

Read only <file> lines <start>-<end>. Summarize the relevance in 3 bullets.

Delegate to a subagent. Return only: finding, evidence pointer, confidence, next action. Limit to 10 bullets.

/compact focusing on decisions made, evidence pointers, files touched, unresolved questions, and residual risk.

Review this diff against the compact plan. Return findings only with severity, file pointer, and suggested next action.

The same patterns, shown as the wasteful version next to the disciplined one:

How the Workbook Reinforces the Course

Three ideas worth carrying through the whole day

Coverage checklist

Concrete examples to keep open

• Primitive framework: plugins, skills, commands, agents, and model selection
• Tool and permissions examples
• Skill template
• Primitive framework and examples
• Explore findings example
• Review example
• Workflow retro example

Token Savings Field Guide

Token savings are not about making Claude think less. They are about keeping the context window focused on the material that changes the outcome. Read the nine moves below as a rough progression, not a checklist of rules: the early ones are reflexes you build in your first week, the later ones are habits you grow into as your sessions get more ambitious. You will not do all nine on every task, but the more advanced your work gets, the more of them you will reach for without thinking.

1. Enable RTK for noisy command output

RTK (Rust Token Killer) is a CLI proxy that compresses noisy command output before it reaches Claude's context, so a run that would have streamed hundreds of lines into the session lands as a compact, structured summary instead. It is useful when shell output is large, repetitive, or noisy. The impact compounds because command output does not just cost tokens once; it remains in the session and can be re-read on later turns.

rtk gain              # cumulative token savings this session
rtk gain --history    # per-command breakdown with savings
rtk discover          # find missed compression opportunities

Good RTK targets:
- test output
- build logs
- git status and diff noise
- package manager output
- long formatter or type-checker traces

2. Move repeated tasks to executable scripts

The third time you type roughly the same instructions, treat it as a signal rather than a chore. Every repeat costs you twice: you re-describe the workflow, and Claude re-infers what you meant, sometimes differently than last time. Pinning that sequence into a stable script makes it cheaper, faster, and far more predictable, and it frees the conversation for the judgment only you can supply.

# Example: scripts/check-pr-ready.sh
#!/usr/bin/env bash
set -euo pipefail
npm run lint
npm run typecheck
npm test
git status --short

# Prompt Claude:
# Run scripts/check-pr-ready.sh and summarize only failures,
# evidence pointers, and the next command to run.

3. Do not say “explore” without intention

Watch your own verbs for a day and you will catch yourself doing this. Words such as “explore,” “look around,” “understand this,” or “check the repo” quietly tell Claude to read broadly, and it will. Sometimes that is exactly what you want, when you are genuinely onboarding to an unfamiliar area. The skill is noticing the difference and choosing on purpose, rather than reaching for a vague verb out of habit and paying for a wide read you did not need.

4. Use permission posture as a productivity lever, not a safety shortcut

Permissions shape token efficiency because unnecessary approval prompts interrupt loops, but broad permissions can create risk. Start with read-heavy, write-light permissions, then widen only when the task and verification path are clear.

{
  "permissions": {
    "allow": [
      "Read",
      "Grep",
      "Glob",
      "Bash(git status:*)",
      "Bash(npm test:*)"
    ],
    "defaultMode": "acceptEdits"
  }
}

5. Enable and curate memory

Memory saves tokens when it prevents repeated corrections. It wastes tokens when it becomes stale, vague, or bloated.

• Use /memory to inspect what Claude has learned.
• Put durable project conventions in CLAUDE.md, not in chat history.
• Use path-scoped rules for standards that only apply to certain files.
• Use @ imports for shared docs instead of repeated pasted text.
• Prune stale assumptions and overly broad memories.

6. Share context and investigation across tasks

The cheapest context is the context already summarized well. Do not make the next task rediscover what the last task proved.

7. Bound subagent output

Subagents are powerful because they can absorb noisy exploration without polluting the main context. That benefit disappears if the subagent returns a transcript-sized report.

Delegate this investigation to a subagent.

Scope: auth middleware and token refresh only.
Tools: Read, Grep, Glob, Bash for git history.
Do not edit files.

Return exactly:
1. Findings, max 8 bullets
2. Evidence pointers: file:line or commit SHA
3. Confidence: high/medium/low
4. Recommended next action

8. Prompt with a token budget

Return paths only. Do not read files yet.

Read 40 lines around the match, not the whole file.

Summarize logs into failures, evidence, and next command.

Cap the answer at 10 bullets unless a blocking risk requires more.

/compact focusing on decisions made, evidence pointers, files touched,
unresolved questions, and residual risk.

9. End-of-task token checklist