Contact: Website | LinkedIn | GitHub | O'Reilly | YouTube
Reference architectures, code examples, and practice scenarios for the Claude Architect role. This 4-hour O'Reilly Media live training is skills-first for Segments 1-3, then closes with a CCA-F certification capstone in Segment 4 (cert briefing + weighted practice questions). It teaches the production patterns that define a Claude Architect (agentic orchestration, tool design with MCP, Claude Code workflows, prompt engineering, context management) and gives you a runway to Anthropic's CCA-F exam.
Anthropic's Claude Certified Architect: Foundations (CCA-F) exam is currently restricted to Anthropic partners. The five reference files in this repo map to the published 5-domain exam blueprint, and
CERT-PROGRAM-BRIEFING.mdwalks through exam mechanics, prep stack, and a week-before punchlist.
New:
EXAM-STUDY-PATH.mdis the learner-facing bridge from this workshop's notebooks to CCA-F domains and scenario families. Read it after the course-at-a-glance table below if you are aiming at the exam.
The Claude Architect is an emerging job role focused on designing and building production-grade applications with Claude Code, the Claude Agent SDK, the Claude API, and Model Context Protocol (MCP). Organizations across the Claude Partner Network are hiring for this skillset.
| Segment | Duration | Topic | Key deliverable |
|---|---|---|---|
| 1 | 50 min | Building AI Agents That Use Tools | Customer support agent with hook-enforced policy |
| 2 | 50 min | Tool Design, Integration, and Claude Code Workflows | MCP config walkthrough + Claude Code hierarchy demo |
| 2.5 | self-study | Control Surfaces, Tool Enumeration, Console Assets | All tool_choice modes live, stop_sequences / max_tokens / pause_turn, MCP list_tools, and the live Claude Console asset surface (memory_stores, vaults, agents, sessions). Q&A overflow / cohort homework, not on the 4-hour clock. |
| 3 | 50 min | Structured Output, Context, and Production Reliability | Invoice extractor with retry + triage scorecard |
| 4 | 50 min | CCA-F Certification Capstone | Cert briefing + 10 weighted practice questions + take-home punchlist |
Total live class time: 4 hours (4 × 50-min segments + 3 × 10-min breaks). Segment 2.5 is a deep-dive notebook taught only as Q&A overflow or post-class homework. Instructors and learners should start at COURSE-FLOW.md.
| Domain | Weight | Reference file | Focus |
|---|---|---|---|
| 1 - Agentic Architecture & Orchestration | 27% | domain-1-agentic.md | Agentic loops, multi-agent coordination, hooks, session management |
| 2 - Tool Design & MCP Integration | 18% | domain-2-tools-mcp.md | Tool descriptions, structured errors, scoped distribution, MCP config |
| 3 - Claude Code Configuration & Workflows | 20% | domain-3-claude-code.md | CLAUDE.md hierarchy, skills, slash commands, plan mode, CI/CD |
| 4 - Prompt Engineering & Structured Output | 20% | domain-4-prompts.md | Explicit criteria, few-shot prompting, JSON schemas via tool use, batch API |
| 5 - Context Management & Reliability | 15% | domain-5-context.md | Context preservation, escalation, error propagation, provenance |
Exam mechanics: 60 multiple-choice questions, 120 minutes, scaled 100-1000 with 720 passing, proctored via ProctorFree, one attempt only, $99 (partner discount available). See CERT-PROGRAM-BRIEFING.md for the full briefing.
claude-architect/
├── COURSE-FLOW.md # Master instructor punchlist (4 segments × 50 min)
├── docs/ # Reference scaffolds and instructor/learner guides (moved out of repo root)
│ ├── INSTRUCTOR-SETUP.md # Multi-day setup arc (machine config, env vars, repo clone, backup plans)
│ ├── PRE-CLASS-CHECKLIST.md # Instructor pre-flight (PowerShell)
│ ├── EMERGENCY-CARD.md # One-page live-class recovery card (what to do when a demo goes sideways)
│ ├── CERT-PROGRAM-BRIEFING.md # Segment 4 talk-track: exam mechanics, domain weights, week-before punchlist
│ ├── EXAM-STUDY-PATH.md # Learner-facing bridge from notebooks to CCA-F domains and scenarios
│ ├── PRACTICE-QUESTIONS.md # 60-question practice bank, hand-maintained (cohort take-home)
│ ├── COOKBOOK-INDEX.md # Index of the vendored Anthropic cookbook notebooks cited by the course
│ ├── scenario-cicd-integration.md # Exam scenario 5: `claude -p` headless in a GitHub Actions PR review
│ ├── domain-1-agentic.md # Reference: Agentic Architecture & Orchestration
│ ├── domain-2-tools-mcp.md # Reference: Tool Design & MCP Integration
│ ├── domain-3-claude-code.md # Reference: Claude Code Configuration & Workflows
│ ├── domain-4-prompts.md # Reference: Prompt Engineering & Structured Output
│ └── domain-5-context.md # Reference: Context Management & Reliability
├── practice-questions.json # Machine-readable practice-question source
├── .mcp.json # Segment 2 Demo A anchor (6 servers, 3 transports; the course's own server is `oreilly-cca-mcp`)
├── .vscode/mcp.json # VS Code / GitHub Copilot agent-mode MCP config (sibling schema to .mcp.json)
├── hooks-example.py # Agent SDK hooks: compliance enforcement
├── coordinator-subagent-sketch.py # Domain 1 coordinator-subagent scaffold (read-only reference)
├── start-sidecar-group.ps1 # Brings up the teaching sidecars (JupyterLab, MCP Inspector, MCP CLI REPL); idempotent
├── stop-sidecar-group.ps1 # Takes the same sidecars back down
├── CLAUDE.md # Claude Code project instructions for this repo
├── notebooks/ # Tim's seven teaching notebooks (five live + one self-study deep dive + one exam-mastery reference), plus two self-paced suites
│ ├── segment-0-pre-flight.ipynb
│ ├── segment-1-customer-support-agent.ipynb
│ ├── segment-2-tool-design-and-mcp.ipynb
│ ├── segment-2-5-control-surfaces.ipynb # self-study; control surfaces + Console assets
│ ├── segment-3-invoice-extractor.ipynb
│ ├── segment-4-cca-f-capstone.ipynb
│ ├── cca-f-exam-mastery.ipynb # off-clock; all five domains, all 30 task statements
│ ├── 00-prerequisites/ # 10 Messages API primer notebooks - the on-ramp to the raw API
│ └── 06-managed-agents/ # 6 Managed Agents notebooks - Anthropic hosts the loop, domain-banded
├── claude-cookbooks-main/ # Vendored snapshot of Anthropic's official Claude Cookbooks (MIT, Copyright (c) 2023 Anthropic). See claude-cookbooks-main/NOTICE.md
├── examples/ # One runnable example suite (self-paced study, not on the 4-hour clock)
│ └── mcp_cli/ # Reference MCP CLI (FastMCP server + client + chat), from Anthropic's Skilljar course. See examples/mcp_cli/NOTICE.md
├── slides/ # Course slide deck (rebuilt from scripts/build-deck.py)
└── scripts/
├── build-notebooks.py # Rebuilds the seven teaching notebooks from source (sha256-deterministic, idempotent)
├── preflight-class.ps1 # Read-only go/no-go board for class day. Exit 0 = GO. Changes nothing
├── run-jupyter.ps1 # Lifecycle helper: starts JupyterLab on port 8888 with Jupyter AI v3 persona override
├── stop-jupyter.ps1 # Lifecycle helper: port-scoped clean shutdown with PID fallback for Windows half-states
├── run-mcp-cli.ps1 # Lifecycle helper: bootstraps and starts the vendored MCP CLI REPL
├── run-mcp-inspector.ps1 # Lifecycle helper: starts the MCP Inspector against the FastMCP demo server
├── smoke-cookbooks.ps1 # Smoke-runs the 8 heavy-rotation vendored cookbooks against notebooks/.venv
├── voice-lint.ps1 # Voice-lint sweep (no em dashes, no AWS, etc.) - run via `npm run lint:voice`
├── preflight.ps1 # Instructor pre-flight - run via `npm run preflight`
├── build-deck.py # Rebuilds the slide deck
└── extract-practice-questions.py # RETIRED extractor (practice-question files are now hand-maintained)
- Python 3.13+ (every notebook and demo in this course runs against the Python
anthropicSDK, pinned>=0.40,<1.0innotebooks/pyproject.toml) - uv (the Python package manager):
pip install uvorwinget install astral-sh.uv - Claude Code CLI installed and authenticated. On Windows the native installer is the fastest path:
irm https://claude.ai/install.ps1 | iex - An Anthropic API key set as
ANTHROPIC_API_KEY(PowerShell:$env:ANTHROPIC_API_KEY = "sk-ant-...", or place it in a gitignored.envat repo root) - VS Code with the Python and Jupyter extensions (the seven teaching notebooks open here)
- Optional, instructors only: Node.js 18+ for the two npm scripts (
npm run lint:voice,npm run preflight). Learners can skip Node entirely.
git clone https://github.com/timothywarner-org/claude-architect.git
cd claude-architect
uv run --project notebooks jupyter lab notebooks/That is the entire learner setup. First run auto-creates notebooks/.venv/, installs all dependencies from notebooks/pyproject.toml, and launches Jupyter. Subsequent runs reuse the venv and start in seconds. The Anthropic cookbook ships in the repo at claude-cookbooks-main/, so you don't need a second clone. Instructors who run the voice-lint scripts also need npm install; learners don't.
Fallback if uv isn't available: pip install -r notebooks/requirements.txt still works; the requirements file is kept in sync with pyproject.toml.
Interactive teaching sessions should use the lifecycle helpers instead of a bare Jupyter invocation:
.\scripts\run-jupyter.ps1 # default port 8888, overrides Jupyter AI default persona to Jupyternaut
.\scripts\stop-jupyter.ps1 # port-scoped clean shutdown with PID fallbackrun-jupyter.ps1 sets the Jupyter AI v3 default persona to Jupyternaut so chat messages route to someone (the upstream default points at the older package ID and silently routes to nobody). stop-jupyter.ps1 matches the server by root_dir, falls back to Stop-Process on the exact PID if the graceful path hangs (Jupyter AI can leave the server half-interrupted on Windows). For headless smoke runs (nbconvert --execute) neither script is needed - nbconvert spawns its own kernel.
Three scripts cover the live-teaching lifecycle. Run them in this order:
.\scripts\preflight-class.ps1 # read-only go/no-go board. Exit 0 = GO
.\start-sidecar-group.ps1 # brings the teaching sidecars up
.\stop-sidecar-group.ps1 # takes them back downscripts/preflight-class.ps1 is read-only and changes nothing. It checks tooling, secrets, both venvs, the claude-architect kernelspec, both MCP configs, that all seven notebooks parse, and that the ports it needs are free. An exit code of 0 means you're clear to teach.
start-sidecar-group.ps1 brings up the three teaching sidecars: JupyterLab, the MCP Inspector, and the MCP CLI REPL. It's idempotent, so it skips any sidecar that's already running rather than starting a second copy. Four flags shape what it does: -Restart cycles everything, -SkipPreflight bypasses the go/no-go check, -NoMcpCli leaves the REPL out, and -NoJupyter skips the JupyterLab server. If you teach from VS Code rather than JupyterLab, -NoJupyter is the flag you want - the VS Code Jupyter extension spawns its own kernel and never talks to a JupyterLab server, so starting one just burns a port. stop-sidecar-group.ps1 takes the same set back down.
When a demo goes sideways mid-class, docs/EMERGENCY-CARD.md is the one-page recovery card. Keep it open on a second monitor.
notebooks/ is the unified course tree: the seven live-taught segment notebooks at its root, plus two self-paced suites that bookend them - an on-ramp for people new to the raw API and a managed-agents counterpart to the loops the course hand-rolls. examples/ now holds only the standalone mcp_cli/ reference app, a separate vendored uv project. None of the self-paced material is on the 4-hour clock, and all of it is runnable.
If you've never called the Claude API directly, start here, before Segment 1. Ten notebooks in notebooks/00-prerequisites/ walk the Messages API one concept at a time: 001_requests, 002_system_prompt, 003_temperature, 004_streaming, and 005_controlling_output, with _exercise variants of 001, 002, and 005 for hands-on reps, plus first_request.ipynb and multi_turn_conversation.ipynb as the two bookends. They're adapted from jaozc/building-with-the-claude-api, and every one of them is smoke-verified green against the live API. They request the claude-architect kernel, so once the notebook venv exists they open and run without any further setup.
The live course teaches you to hand-roll the agentic loop, because you can't reason about a loop you've never written. The six notebooks in notebooks/06-managed-agents/ are the counterpart: the same patterns, but with Anthropic running the loop for you through the Managed Agents beta (anthropic-beta: managed-agents-2026-04-01). They're banded by exam domain:
| Notebook | Domain focus |
|---|---|
01_agentic_loop_and_sessions |
Domain 1: the managed loop and session lifecycle |
02_coordinator_and_subagents |
Domain 1: multi-agent coordination |
03_tools_and_structured_errors |
Domain 2: tool design and structured errors |
04_structured_output_and_validation |
Domain 4: schema-guaranteed output |
05_context_and_escalation |
Domain 5: context preservation and escalation |
06_cca_f_capstone |
All five domains end to end |
All six are smoke-verified green, and all six archive the resources they create, so a full run leaves nothing behind in your Console workspace. Read them after the live segments, not before - the managed loop is much easier to trust once you've written the unmanaged one.
The vendored examples/mcp_cli/ Skilljar reference app gets the same on-rails treatment via a wrapper that auto-bootstraps its .env and hands off to uv:
.\scripts\run-mcp-cli.ps1First run creates examples/mcp_cli/.env from the template, lifts ANTHROPIC_API_KEY from your repo-root .env, and then runs uv run --directory examples/mcp_cli main.py. Subsequent runs go straight to the REPL. The wrapper sits in scripts/run-mcp-cli.ps1 and never touches the vendored examples/mcp_cli/ tree, preserving the NOTICE.md modification count at 2. Its FastMCP server is what .mcp.json registers as oreilly-cca-mcp, and it's the server scripts/run-mcp-inspector.ps1 points the MCP Inspector at.
- New to the Claude API? Run
notebooks/00-prerequisites/first. Ten short notebooks take you from a bare request to streaming and controlled output, which is the vocabulary every later segment assumes. - Read COURSE-FLOW.md for the full 4-segment teaching arc.
- Walk the five
domain-*.mdreference files in order. Each maps to a course segment and points at runnable cookbook notebooks. - Run the five live-teaching notebooks in
notebooks/in order, plus thesegment-2-5-control-surfaces.ipynbself-study deep dive when time allows. These are the primary teaching surface - markdown cells carry the concepts, code cells run the demos, and each one closes with a "Going further" appendix that links the rest of the repo's assets. Anthropic's official cookbooks ship alongside inclaude-cookbooks-main/as the bundled-in reference library (full attribution inclaude-cookbooks-main/NOTICE.md). - Then run
notebooks/06-managed-agents/. Once you've hand-rolled an agentic loop in Segment 1, these six notebooks show you the same patterns with Anthropic managing the loop. The contrast is the lesson. - Work through
CERT-PROGRAM-BRIEFING.mdand thePRACTICE-QUESTIONS.mdbank if you're aiming at the CCA-F exam. - Build something. The reference architectures only land when you wire one of these patterns into a real workflow.
Each scenario frames a realistic production context that a Claude Architect would encounter. The CCA-F exam draws 4 scenarios at random from a pool of 6:
| # | Scenario | Primary competencies |
|---|---|---|
| 1 | Customer Support Resolution Agent | Domains 1, 2, 5 |
| 2 | Code Generation with Claude Code | Domains 3, 5 |
| 3 | Multi-Agent Research System | Domains 1, 2, 5 |
| 4 | Developer Productivity Tooling | Domains 1, 2, 3 |
| 5 | CI/CD Integration with Claude Code | Domains 3, 4 |
| 6 | Structured Data Extraction Pipeline | Domains 4, 5 |
Send request -> Check stop_reason -> "tool_use"? Execute tool, append tool_result, loop
-> "end_turn"? Done
-> "pause_turn"? Resume in next request
- Descriptions drive selection. Detailed descriptions beat clever tool names.
- Cap at 4-5 tools per agent. More tools degrade selection accuracy.
- Structured errors as tool_result content. Never raise exceptions from tool implementations.
| Mode | Forces what? | When to pick |
|---|---|---|
{"type": "auto"} |
nothing | default |
{"type": "any"} |
a tool call (model picks which) | action required, model picks verb |
{"type": "tool", "name": "X"} |
call to tool X | forced structured output (Segment 3) |
{"type": "none"} |
no tool calls | "explain, don't act" turns |
add disable_parallel_tool_use: true |
one tool per turn | ordering matters (write-then-read, lookup-then-act) |
Branch on stop_reason, never parse prose to decide control flow. Six values: end_turn, tool_use, max_tokens, stop_sequence, pause_turn, refusal. stop_sequences gives you a deterministic cutoff token (matched value comes back in resp.stop_sequence, the token itself is excluded from the output). max_tokens doubles as a deliberate cutoff lever: set it low, replay the partial assistant turn in the next call to resume.
- Static - iterate the
tools=[...]array you registered - Runtime loop - log scoped tools +
tool_choiceper iteration - MCP
list_tools- the pattern that scales beyond hand-registered tools - Claude Code harness - separate surface from API
tool_use, discovered via/helpand~/.claude/
All reachable from the SDK with anthropic-beta: managed-agents-2026-04-01:
client.beta.memory_stores- persistence that survives restarts (Domain 5)client.beta.vaults(+.credentials.mcp_oauth_validate) - secrets hygiene with MCP OAuth (Domain 3)client.beta.agents+client.beta.sessions- the managed-loop alternative to a hand-rolled agentic loop (Domain 1)
- User-level
~/.claude/CLAUDE.mdfor personal defaults - Project-level
./CLAUDE.mdat repo root for team conventions - Subtree
<subdir>/CLAUDE.mdloads on demand claude -pfor headless / CI/CD usage
tool_usewith JSON schema = guaranteed schema compliance. Define output as a tool'sinput_schema, force the model to call it withtool_choice: {"type": "tool", "name": "..."}.- Few-shot examples > temperature. Two or three input-output pairs beat tuning sampling parameters.
cache_control silently no-ops if the cacheable prefix is below the model's floor. Sonnet 4.x: 1024 tokens. Haiku 4.5: 4096 tokens (4x higher). A cell can exit clean with cache_creation=0 and cache_read=0 if the prefix sits between the two floors; the smoke output, not the exit code, is what tells you caching engaged. Target +25% above the floor for safety margin against tokenizer drift.
- Haiku 4.5 default everywhere. Production-quality tool use, agentic loops, and MCP discovery at ~1/5 the Sonnet cost.
- Sonnet 4.6 reserved for two cells: Segment 3's nested invoice schemas with retry-on-validation-error, and the Part 4 forced-extraction cell of the off-clock
cca-f-exam-mastery.ipynb. - Opus never used in code in this repo. Console-managed agents carry their own configured model field (Deep Researcher resolves to Sonnet 4.6); the SDK respects what the Console sets.
- Pin case-facts at the top of long sessions
- Summarize resolved turns; keep verbatim history only for the active issue
- Escalate on explicit human request, policy gaps, or low confidence - never on sentiment alone
Tim Warner is a Microsoft MVP (Azure AI), Pluralsight Principal Author (200+ courses, 1M+ learners), Microsoft Press / Pearson senior content developer, and O'Reilly Live Learning instructor with 28+ years on the Microsoft stack. He teaches Feynman-style: first principles, no fluff, real demos.
- Website: TechTrainerTim.com
- LinkedIn: @timothywarner
- GitHub: @timothywarner-org
- YouTube: TechTrainerTim
- O'Reilly: Author page
This repo bundles several distinct bodies of work. The split matters for attribution and for reuse:
- Original content by Tim Warner. Everything in
notebooks/, includingnotebooks/06-managed-agents/, the fivedomain-*.mdreference files,COURSE-FLOW.md,CERT-PROGRAM-BRIEFING.md,PRE-CLASS-CHECKLIST.md,INSTRUCTOR-SETUP.md,CLAUDE.md, and everything underscripts/is authored by Tim Warner and licensed under MIT via this repo'sLICENSEfile. - Vendored Anthropic content.
claude-cookbooks-main/is a vendored copy of Anthropic's official Claude Cookbooks, MIT licensed, Copyright (c) 2023 Anthropic. Full attribution, upstream commit reference, and the unmodified MIT license live inclaude-cookbooks-main/NOTICE.mdandclaude-cookbooks-main/LICENSE. It is committed here so learners get the entire reference library ongit clonewithout a second clone step. - Reference application from Anthropic's Skilljar course.
examples/mcp_cli/is a complete MCP CLI application (stdio FastMCP server + client + interactive chat with@doc-idretrieval and/prompt-namecommands) distributed as starter material with Anthropic's Claude with the Anthropic API Skilljar course. Treated as Anthropic-authored instructional reference; full attribution and the two minor modifications (rename.envto.env.example, addNOTICE.md) are documented inexamples/mcp_cli/NOTICE.md. Segment 2 of the course opens itsmcp_server.pysource during Demo A. - Practice bank with split provenance. In
PRACTICE-QUESTIONS.mdthe question stems, options, and correct answers are community-sourced from Paul Larionov's study repo; the answer explanations are this repo's own work, grounded in Anthropic documentation. The file is hand-maintained (see the Disclaimer below for the full provenance and calibration-only framing). - Adapted community content. The primer notebooks in
notebooks/00-prerequisites/are adapted from jaozc/building-with-the-claude-api, with three portability fixes for this repo: the install cell shells out touv pip installrather than%pip(uv venvs ship without pip), the model is pinned toclaude-haiku-4-5per this repo's model policy, and the demo prompts are Azure-first. Attribution is in each notebook's first cell and inexamples/README.md. The managed-agents notebooks innotebooks/06-managed-agents/are original work by Tim Warner and fall under this repo's MIT license. - Point-in-time snapshots, not submodules. Both
claude-cookbooks-main/andexamples/mcp_cli/are static snapshots, not git submodules. Refresh procedures are documented in each directory'sNOTICE.md.
This is an unofficial study guide built around Anthropic's publicly documented CCA-F exam blueprint. Practice questions in PRACTICE-QUESTIONS.md are community-sourced from Paul Larionov's study repo and are intended for calibration only, not as exam predictors. The authoritative source for exam content, registration, and policy is Anthropic (see the public CCA-F page and the Exam Policy). Use Anthropic's own Practice Exam to gauge readiness before scheduling.
Contributions are welcome. See CONTRIBUTING.md for guidelines.
MIT - see LICENSE.
Found this useful? Open an issue with questions or feedback - I read every one.