claude-architect: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this repo is

Teaching and reference material for the Claude Architect Foundations 4-hour live training (O'Reilly Media). The course is skills-first for Segments 1-3, then closes with a CCA-F certification capstone in Segment 4 (cert briefing + weighted practice questions). Domain 5 (Context Management) is folded into Segment 3 alongside Domain 4.

The class is taught from the five live-teaching Jupyter notebooks in ./notebooks/. Each notebook IS its segment - markdown cells carry the concepts, code cells carry the demos. A sixth self-study deep-dive notebook (Segment 2.5) ships alongside for cohort homework and Q&A overflow but is not on the 4-hour clock. A seventh standalone exam-mastery reference (cca-f-exam-mastery.ipynb) maps 1:1 to all five domains and all 30 task statements; it is off-clock post-class study, not live-taught. The reference scaffold .md files live in ./docs/.

As of the 2026-07-14 unification, notebooks/ is the single course tree - 23 notebooks, one venv, one kernel. It nests two more self-study suites as subdirectories: notebooks/00-prerequisites/ (the Messages API on-ramp, was examples/messages_api/) and notebooks/06-managed-agents/ (the Managed Agents counterpart, was examples/agents_api/). Numeric prefixes place them before and after the five live segments in a plain file listing, so the sequence is readable from the directory alone, not just from prose. examples/ now holds only mcp_cli/, a genuinely separate vendored app with its own uv project.

The repo ships these artifacts:

• notebooks/segment-0-pre-flight.ipynb - top-of-class environment verification (5 min, optional)
• notebooks/segment-1-customer-support-agent.ipynb - Segment 1 (Domain 1)
• notebooks/segment-2-tool-design-and-mcp.ipynb - Segment 2 (Domains 2 + 3)
• notebooks/segment-2-5-control-surfaces.ipynb - Segment 2.5 self-study deep dive (all five domains): full tool_choice modes + disable_parallel_tool_use, stop_sequences and max_tokens as control levers, MCP list_tools discovery, and the Claude Console asset surface (memory_stores, vaults, agents, sessions). Not live-taught.
• notebooks/segment-3-invoice-extractor.ipynb - Segment 3 (Domains 4 + 5)
• notebooks/segment-4-cca-f-capstone.ipynb - Segment 4 (cert briefing + weighted practice questions)
• notebooks/cca-f-exam-mastery.ipynb - standalone exam-mastery reference (built by scripts/_notebooks/segment_5_exam_mastery.py). Seven parts, one per domain plus a mechanics-and-coverage part, mapping every CCA-F task statement (TS1.1-TS5.6) to a runnable minimal demo. Off the 4-hour clock; post-class study. Uses claude-haiku-4-5 throughout except the Part 4 forced-extraction cell, which uses claude-sonnet-4-6 (same reasoning-depth exception as Segment 3).
• notebooks/README.md, notebooks/pyproject.toml, notebooks/uv.lock, notebooks/requirements.txt - notebook setup (uv-native, pip fallback), smoke commands, voice-lint
• scripts/build-notebooks.py + scripts/_notebooks/*.py - source-of-truth Python builders; the .ipynb files are generated artifacts
• COURSE-FLOW.md - master instructor punchlist (4 segments × 50 min, demos, exercises, bridges)
• docs/PRE-CLASS-CHECKLIST.md - instructor pre-flight (PowerShell)
• docs/domain-1-agentic.md through docs/domain-5-context.md - post-course reference scaffolds, one per CCA-F exam domain
• docs/CERT-PROGRAM-BRIEFING.md - Segment 4 talk-track reference (exam mechanics, domain weights, week-before punchlist, all public-sourced)
• docs/PRACTICE-QUESTIONS.md - 60-question cohort take-home. Hand-maintained. Question stems are community-sourced; the answer explanations are repo-authored, with per-distractor rationale and Anthropic-doc citations grounded via Context7.
• docs/INSTRUCTOR-SETUP.md, docs/EXAM-STUDY-PATH.md, docs/COOKBOOK-INDEX.md, docs/scenario-cicd-integration.md - supporting reference docs (instructor setup, study-path map, cookbook wire-up index, CI/CD scenario walkthrough)
• docs/EMERGENCY-CARD.md - one-page live-class recovery card. What to run when a sidecar drops mid-segment.
• scripts/preflight-class.ps1 - read-only go/no-go board, run before class. Checks tooling (uv, node, npx, git), secrets (both .env files plus GITHUB_TOKEN), both venvs, the claude-architect kernelspec's argv[0], both MCP configs (they parse, and the demo-server name is in sync across them), that all 23 notebooks under notebooks/ parse, and the sidecar ports. Exit 0 means GO. It changes nothing, so it is safe to run repeatedly.
• start-sidecar-group.ps1 (repo root) - brings up the three class-day sidecars, each in its own window: JupyterLab (8888), MCP Inspector (6274 web UI plus 6277 proxy), and the MCP CLI REPL. Idempotent: it skips any sidecar whose port is already held, so a re-run repairs gaps instead of stacking duplicates. Flags: -Restart, -SkipPreflight, -NoMcpCli, -NoJupyter.
• stop-sidecar-group.ps1 (repo root) - delegates to scripts/stop-jupyter.ps1, then frees 6274 and 6277. It deliberately does not stop the MCP CLI REPL: that process holds no port, so the only way to find it is pattern-matching pwsh, which risks closing the instructor's own terminal.
• practice-questions.json - machine-readable practice-question source, hand-maintained (Segment 4 notebook samples 10 from this). Stays at repo root, not in docs/. Its explanations are the shorter originals; the enriched per-distractor rationale lives only in docs/PRACTICE-QUESTIONS.md, so the two diverge by design.
• scripts/extract-practice-questions.py - RETIRED. Was the build-time extractor for the two practice-question files; retired because a regeneration from the upstream HTML would overwrite the hand-authored explanations in docs/PRACTICE-QUESTIONS.md. Both files are now hand-maintained; edit them directly.
• .mcp.json - Segment 2 MCP config anchor (6 servers, 3 transports, env-var expansion). This is the only project-scoped MCP file Claude Code reads. There is no .claude/mcp.json; that path is silently ignored. .claude/settings.json holds permissions, hooks, and env only - its sole MCP-adjacent keys are the enabledMcpjsonServers / disabledMcpjsonServers approval toggles, never server definitions. The other two scopes (local and user) both live in ~/.claude.json, outside this repo. Two servers here are course-owned and stdio: oreilly-cca-mcp points Claude Code at the course's own FastMCP demo (examples/mcp_cli/mcp_server.py), and cca-study-mcp points at the CCA Cert Buddy server (cca-cert-buddy/mcp-server/index.ts).
• .vscode/mcp.json - VS Code / GitHub Copilot agent-mode MCP config. Sibling schema to .mcp.json, NOT the same file: VS Code keys servers under servers (Claude Code uses mcpServers), allows JSONC comments, and uses ${workspaceFolder} / ${env:VAR} / ${input:id} variables. Carries the same oreilly-cca-mcp server. The two files must be kept in sync by hand. Note: this file is local-only (untracked), not committed; only .vscode/settings.json is in version control.
• hooks-example.py - real PreToolUse / PostToolUse reference cited from Segment 1
• coordinator-subagent-sketch.py - Domain 1 coordinator-subagent scaffold (renamed from the old testing.md)
• examples/mcp_cli/ - vendored reference MCP CLI app from Anthropic's Skilljar course (Segment 2 anchor; separate uv project with its own pyproject.toml, uv.lock, and .python-version pinning 3.13). Attribution in examples/mcp_cli/NOTICE.md. examples/ holds only this now - see below.
• notebooks/00-prerequisites/ - ten Messages API primer notebooks (001_requests through 005_controlling_output plus three _exercise variants, first_request.ipynb, and multi_turn_conversation.ipynb), adapted from jaozc/building-with-the-claude-api. Three portability fixes vs. the upstream source: the install cell shells out to uv pip install --python sys.executable instead of %pip (uv venvs ship without pip); model = "claude-haiku-4-5" per repo model policy; and the streaming/controlled-output demo prompts are Azure-first (Event Grid, Azure CLI). They read notebooks/.env via python-dotenv and stamp the claude-architect kernel (see below). Attribution lives in each notebook's first cell and in notebooks/00-prerequisites/README.md. Moved here from examples/messages_api/ in the 2026-07-14 unification; filenames unchanged.
• notebooks/06-managed-agents/ - managed-agents notebooks (Console asset surface). Validated and in the teaching path: all six are committed, all six are smoke-verified green against the live API, and all six archive the resources they create, so a run leaves nothing behind. The live notebooks' "Going further" appendices link them. Coordinate before large structural edits; small fixes are fine. Moved here from examples/agents_api/ in the 2026-07-14 unification; filenames unchanged.
• claude-architect Jupyter kernel - a user-scoped kernelspec whose argv[0] is the absolute path to notebooks/.venv/Scripts/python.exe, so it always lands in the writable uv venv regardless of PATH. All 23 notebooks under notebooks/ stamp kernelspec.name = "claude-architect" so the correct kernel auto-selects on open - this was inconsistent before the 2026-07-14 unification (3 notebooks stamped generic python3 by mistake, and the 7 root segment notebooks used python3 throughout); now it's uniform. Register on a fresh clone with uv run --project notebooks python -m ipykernel install --user --name claude-architect --display-name "Claude Architect (notebooks/.venv)". The trap it avoids: a bare "python" in argv resolves to whatever is first on PATH (on Tim's box, the non-writable machine-wide C:\Python314), which makes the uv install cell fail with an Access-denied os error 5.
• claude-cookbooks-main/ - vendored copy of Anthropic's official Claude Cookbooks (MIT, Copyright (c) 2023 Anthropic). Attribution in claude-cookbooks-main/NOTICE.md.
• slides/warner-claude-architect-july-2026.pptx - course deck for the July 2026 delivery (89 slides). Hand-authored, not emitted by scripts/build-deck.py (that script generates a smaller scaffold cut and would overwrite the shipped file). No PDF is committed; export fresh from the .pptx if a cohort needs one.
• images/social-preview.png - the GitHub repo social-preview asset (1280 x 640, <1 MB), uploaded via Settings -> Social preview. Regenerate via the prompt + processing pipeline documented in images/social-preview-prompt.md. Do NOT overwrite images/cover.png (that's the README hero, a different surface).