Claude Code: Building Production Agents That Actually Scale

Build a Claude Code agent that your team can test, govern and recover when something goes wrong. This practical course takes you from the agent loop to a production-readiness dossier: the controls, tests and operational evidence needed to review an agent before release.

You will design tool and permission boundaries, manage context and memory, evaluate model routing, work with MCP and hooks, and test failure and recovery paths. Practical labs ask you to implement controls and record evidence, not just follow a successful demo.

Across eight modules, the written lessons, worked examples, labs and assessments help you assemble a routing policy, context controls, evaluation cases, an observability plan, a recovery procedure and release evidence. Video material supports the course; a video is not promised for every lesson.

This is the hands-on course companion to Thomas De Vos's book, Claude Code: Building Production Agents That Actually Scale. The book is a separate product and an optional reference, not a required purchase. This course focuses on applying the ideas through practical work and assessments.

For software engineers, technical leads, platform engineers, solution architects and security engineers. You should be comfortable with a terminal, Git, configuration files, tests and normal software-delivery workflows. Prior experience with the Claude Agent SDK is not required.

Leanpub offers a 60-day refund policy, subject to its course exclusions: a course is not refundable after you generate its certificate or fail its last or sole permitted attempt. Read the current policy at leanpub.com/refunds before purchasing.

About the instructor

Thomas De Vos is an architect and technical author with more than 25 years of experience. He is a Google Cloud Generative AI Leader and Google Cloud Authorised Trainer. His teaching focuses on the engineering decisions, practical controls and evidence needed to operate AI systems responsibly.

Free sample: CC-001 lesson and practical lab

This written sample contains the first lesson and its practical lab. The course video, worksheet download and following knowledge-check assessment are not included in this sample. For the lab, use a blank document as your Agent Loop Canvas and record each boundary listed in the instructions.

CC-001: The Agent Loop, Explained and Enforced

An agent is not a clever answer. It is a sequence of decisions and side effects, with evidence and control at every boundary.

Estimated lesson time: 38 min

Learning objectives

• Trace a Claude Code task as model decisions, tool requests, observations and termination decisions.
• Distinguish a proposed tool call from an authorized and completed side effect.
• Design pre-action validation using schema checks, permissions, policy, sandboxing, state preconditions and approval.
• Verify postconditions and define stop, retry and escalation behaviour for a bounded run.

Start with the loop, not the chat transcript

Claude Code wraps a language model in an agentic harness. The model receives the current prompt, conversation, instructions and tool definitions. It can answer in text or request a tool. Claude Code executes an authorized request, returns the result to the model, and the model decides what to do next. The loop ends when the model produces a final response without another tool request, or when the runtime stops it.

The useful production unit is therefore not one answer. It is a chain of state transitions. Each transition should have an input, a proposed action, an authorization decision, an observed result and a new state. If the team stores only the final prose, it cannot reliably explain what changed or why.

Anthropic's Agent SDK documentation calls each model-and-tool round trip a turn. A single task can use many turns. In the example below, reading a file changes only the agent's knowledge; editing a file changes repository state; running tests produces new evidence; the final answer changes neither.

• Turn: 1. Model decision: Inspect manifests and repository rules. Runtime event: Read tools return CLAUDE.md and package files. State after the event: The agent knows scope, current versions and constraints.
• Turn: 2. Model decision: Propose a manifest edit. Runtime event: Permission and policy checks run before Edit. State after the event: Either no change, an approval request, or a tracked file change.
• Turn: 3. Model decision: Verify the candidate patch. Runtime event: Approved test command runs in the sandbox. State after the event: A test result and artifact become new evidence.
• Turn: 4. Model decision: Finish or repair. Runtime event: No tool call means the loop returns a result. State after the event: The run ends with status, evidence and remaining uncertainty.

Common misconception

The model does not directly 'use the terminal'. It requests a tool call. The Claude Code runtime, permissions, hooks and operating environment determine whether and how that call executes.

Validation is a stack of different questions

The earlier line - 'validate the proposed action before the side effect occurs' - was directionally right but educationally incomplete. Validation is not one magic function. It is a sequence of gates, and each gate answers a different question. Passing one gate does not imply the others passed.

Run deterministic checks before judgement-based ones. A malformed tool request should fail schema validation before it reaches a policy model or a human. A forbidden path should be denied by policy even if the patch itself looks correct. A permitted action can still need approval because the consequence is high.

1. Schema: is the tool name known, and are required fields present with valid types and normalized paths?
2. Authorization: is this tool and operation allowed, denied or always subject to approval for this project and identity?
3. Policy: does the target, command, data class, branch, amount or destination satisfy business and security rules?
4. Precondition: is the world still in the state on which the proposal was based - for example, the expected Git revision and a clean working tree?
5. Containment: can the command run inside the configured filesystem and network sandbox without broader host access?
6. Approval: if policy says 'ask', does an accountable person receive enough evidence to approve this exact action?
7. Execution and postcondition: after the side effect, did the intended state change occur, and did forbidden state remain unchanged?

Production note

A validator should return an explicit outcome: allow, deny, ask, or - where the integration supports it - rewrite a narrow input. It should also record the rule, evidence and reason.

How Claude Code enforces the pre-action boundary

Claude Code permissions provide allow, ask and deny rules. Deny takes precedence over ask, and ask over allow. Allow means pre-approved, not exclusive: a tool that is absent from the allow list can still follow the active permission flow. To remove or universally block capability, use deny rules or omit the tool from an SDK run.

A PreToolUse hook runs before the normal permission decision and can inspect a proposed call. This is the right place for controls that must evaluate every matching tool request, such as approved file paths or command patterns. A canUseTool callback in the Agent SDK handles unresolved approvals, but it is not a universal enforcement point because earlier rules can resolve a request first.

Sandboxing is a separate boundary. On supported systems it constrains Bash filesystem and network access using operating-system enforcement. It does not replace permissions, and it does not sandbox built-in Read, Edit or Write tools. Production design normally needs both.

Example: Illustrative project policy in .claude/settings.json

{
  "permissions": {
    "allow": [
      "Read",
      "Grep",
      "Bash(npm test *)"
    ],
    "ask": [
      "Edit",
      "Write",
      "Bash(git push *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./secrets/**)",
      "Bash(rm -rf *)"
    ]
  },
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": true
  }
}

Common misconception

A CLAUDE.md sentence such as 'never edit deployment files' is useful guidance, but it is context, not hard enforcement. Put non-negotiable restrictions in permissions, hooks, tool wrappers or the sandbox.

A worked validator for a dependency-update agent

Suppose the agent may propose changes to package.json and package-lock.json, run npm test, and prepare a draft pull request. It may not edit workflow files, read secrets, push to the default branch or merge. The model requests an Edit to .github/workflows/release.yml because a newer action version appears necessary.

A strong system does not ask whether the model sounds confident. It evaluates the action against the contract. The normalized path is outside the write allow-list, so the request is denied before execution. The denial becomes an observation in the loop: the agent can revise its plan, explain that the workflow change requires a different authorized process, or stop.

Example: Validator decision record - not an LLM opinion

{
  "decision": "deny",
  "tool": "Edit",
  "target": ".github/workflows/release.yml",
  "rule": "manifest-paths-only",
  "reason": "target is outside the approved write set",
  "observed_revision": "8f31c2a",
  "side_effect_occurred": false
}

Worked example: Evaluate one proposed Edit

Proposed action: Edit .github/workflows/release.yml at repository revision 8f31c2a.

1. Schema passes: Edit has a path and replacement content.
2. Path normalization resolves the target inside the repository; no traversal or symlink escape is accepted.
3. Authorization fails: the task contract permits writes only to package.json and package-lock.json.
4. The runtime records deny, rule=manifest-paths-only, proposal hash and current revision. No edit occurs.
5. Claude receives the denial reason and can propose an in-scope patch or escalate the workflow-file change to a human-owned task.

Result: The run remains useful without granting the model broader authority. A denied action is a controlled branch of the loop, not a runtime failure.

Postcondition checks prove what actually happened

Pre-action validation proves only that an attempt is permitted under the observed state. It does not prove success. A command can return an error after partially changing state; a network timeout can leave an external action completed but unconfirmed; a test can pass because the agent edited the test rather than fixed the product.

After each side effect, re-read the affected state and compare it with explicit postconditions. For a patch, inspect the diff, confirm only approved files changed, run the required immutable checks and retain their exit codes. For an external create operation, reconcile by idempotency key before retrying. The tool result should distinguish success, failure and unknown - not collapse all three into prose.

• Action: Edit manifest. Precondition: Expected revision; approved target. Postcondition: Diff contains only intended dependency fields. On uncertainty: Re-read file and diff; do not claim success.
• Action: Run tests. Precondition: Approved command and isolated environment. Postcondition: Required suite ran; exit status and artifacts captured. On uncertainty: Mark verification incomplete.
• Action: Create draft PR. Precondition: Authenticated bounded identity; branch exists. Postcondition: PR ID exists and is draft; no merge occurred. On uncertainty: Query by idempotency key before retry.
• Action: Finish run. Precondition: Acceptance criteria evaluated. Postcondition: Result contains status, evidence and unresolved items. On uncertainty: Return incomplete or escalated, not 'done'.

Common misconception

Exit code zero is evidence for a particular command, not proof that the whole task is correct. Verification must match the acceptance criteria and threat model.

Stopping is part of the design

An agent loop needs more than a success condition. Define maximum tool-use turns, elapsed time, spend, retries per action, repeated-state detection and escalation conditions. In the Agent SDK, maxTurns bounds tool-use round trips and maxBudgetUsd bounds estimated spend. When a limit is reached, the result reports a specific error subtype rather than pretending the task finished.

A useful termination policy distinguishes completed, safely incomplete, denied, escalated and failed. Stop when acceptance criteria pass; when the next required action is forbidden; when critical evidence is missing; when two attempts return the same failure without new information; or when a budget is exhausted. Continuing to 'try harder' without a state change is not autonomy. It is an unbounded loop.

Production note

The production loop is: observe → decide → propose → authorize → execute → verify → update state → continue or stop. Every arrow needs an owner and evidence.

Practical lab

Design the boundary for one side effect

Choose one real action - edit a file, create a ticket, send a message or open a pull request. Write its schema checks, allow/ask/deny policy, state preconditions, sandbox or tool boundary, approval packet, postconditions, idempotency rule and stop behaviour. Then test one allowed, one denied and one ambiguous outcome.

Deliverable: A completed Agent Loop Canvas plus three decision traces showing allow, deny and unknown outcomes.