{"slug": "claude-certified-developer-foundations-certification-overview", "title": "Claude Certified Developer - Foundations certification Overview", "summary": "A developer completed Anthropic's Claude Certified Developer - Foundations certification and published an overview of its curriculum, which covers model fundamentals, production-grade prompting, agents and tool use, Claude Code and MCP integration, production engineering with evals and security, and accelerators. The writeup details token-based pricing and context windows, sampling and temperature, non-determinism, structural versus semantic output testing, LLM-as-judge evaluation, and Claude's model tiers from Haiku to Fable. The certification course itself is restricted to Anthropic partners.", "body_md": "I recently completed the Claude Certified Developer - Foundations certification.\n\nThis certification is based on the official course from Anthropic: [https://anthropic-partners.skilljar.com/path/claude-certified-developer-foundations](https://anthropic-partners.skilljar.com/path/claude-certified-developer-foundations)\n\nHowever, this course is only available to Anthropic partners. Below is my overview of the modules and structure of the Prep Course.\n\nThe course consists of the following main modules:\n\n**MSO Foundations**\n\nLearn the model fundamentals and technical foundations the rest of the Developer Foundations course builds on.\n\n**Production-Grade Prompting, Agents & Tool Use**\n\nBuild your first production integration on Claude, with reliable prompts, tools, context management, and agent loops.\n\n**Claude Code, MCP & Integration**\n\nLearn to make a working Claude integration configurable, shareable, and safe to connect to real systems.\n\n**Production Engineering, Evals & Security**\n\nLearn to take an agent that works in development and prove it holds up under real production traffic.\n\n**Accelerators & IP Contribution**\n\nPackage a build that works into one that survives reuse, review, and deployment beyond the engagement that created it.\n\n**1.1.1 Tokens**\n\nEverything Claude processes (prompt, history, tools, results, output) is measured in tokens, not words/characters, and both pricing and context budget are token-based. Output tokens cost more than input tokens.\n\n**1.1.2 Context Window**\n\nThe max tokens allowed in a single request — system prompt, user prompt, documents, history, tool results, and output combined. Exceeding it returns a `model_context_window_exceeded` stop reason.\n\n**1.1.3 Sampling & Temperature**\n\nClaude samples the next token from a probability distribution rather than picking one fixed \"best\" token. Temperature (a request parameter) tunes this: lower = more repeatable, higher = more varied/creative.\n\n**1.1.4 Non-Determinism**\n\nSampling means identical inputs can yield different, equally valid outputs, so exact-string-match tests are unreliable. Test for properties instead — e.g., \"required field present\" or \"value within range.\"\n\n**1.1.5 Testing Model Output: Structural vs. Semantic Correctness**\n\n| Check Type | Definition | Examples | \n|---|---|---|\n| Structural correctness | Deterministic, yes/no checks | Regex match, valid JSON, exact substring, value within tolerance | \n| Semantic correctness | Meaning-based checks, can't be scripted deterministically | Summary captures key points, correct tone, accurate despite different phrasing | \n\nSemantic checks need an **LLM-as-judge**: a separate model call scores the output, often against a rubric/reference answer.\n\n**1.1.6 Evals**\n\nA testing framework for non-deterministic outputs: scores quality across many test cases and reports an aggregate pass rate (e.g., \"87% passed\"). Consists of test inputs, correctness criteria (structural or LLM-judge), and an aggregation method.\n\n**1.2.1 Claude Model Family**\n\nFour tiers trading off cost, latency, capability, and quality:\n\n| Tier | Description | \n|---|---|\n| Sonnet | Balanced default for most production workloads | \n| Haiku | Optimized for speed/cost within its capability range | \n| Opus | For demanding work beyond Sonnet's envelope | \n| Fable | Highest-capability tier, for the hardest reasoning/coding/agentic tasks | \n\n**1.2.2 Model Selection Strategy**\n\nStart with Sonnet by default; move up a tier only when an eval shows it fails the quality bar, or down to Haiku only when an eval shows the quality drop is acceptable. Model choice should be eval-driven, not assumed.\n\n**1.2.3 Reasoning Modes**\n\nReasoning mode (on/off, separate from model choice) lets the model spend extra tokens \"thinking\" before answering; current models use adaptive thinking tuned via an effort setting (the older `budget_tokens` control is deprecated, now returns a 400 error). Thinking is hidden by default and worth the cost only on hard, multi-step problems — not simple lookups.\n\n**1.3.1 Zero-shot / One-shot / Multi-shot (Few-shot) Prompting**\n\nDistinguished by how many worked examples are given in the prompt:\n\n| Mode | Examples Given | Best Used When | \n|---|---|---|\n| Zero-shot | None (instruction only) | Task is simple, output shape is obvious | \n| One-shot | One input/output example | A single reference clarifies expected output | \n| Multi-shot (Few-shot) | Several examples | Needs specific structure, casing, or edge-case handling | \n\n**1.3.2 Cost Tradeoff of Examples**\n\nEach example consumes tokens on every call and eats into context budget, so examples aren't free — they trade quality/precision against cost.\n\n**1.3.3 Interaction with Model Choice**\n\nMore capable models often succeed zero-shot where smaller ones need few-shot examples, so added examples can substitute for a cheaper model. Best practice: start with the simplest model and fewest examples meeting your eval bar, then add either only if needed.\n\n**1.4.1 SDK vs. Raw REST API**\n\nClaude is accessed via an HTTP REST API (JSON over your API key); the SDK just wraps auth, request construction, retries, and parsing. Both hit the same API and models.\n\n**1.4.2 Response Delivery Patterns**\n\n| Pattern | Description | \n|---|---|\n| Synchronous | Send request, wait for full response, then act — simplest pattern | \n| Streaming | Delivered in pieces via server-sent events as generated; output appears immediately, client reassembles the final message | \n| Asynchronous ( `AsyncAnthropic` ) | Non-blocking async/await enables concurrency without blocking, while each call still returns in real time | \n| Message Batches API | High-volume/offline: submit a batch, poll for completion; up to 24h latency for lower per-token cost | \n\n**2.1.1 Diagnosing Prompt Failures Instead of Adding Words**\n\nWhen a prompt fails, fix it by identifying which structural technique is missing — not by rewording or adding instructions. Rewording doesn't fix boundary confusion or format drift; only the matching technique does.\n\n**2.1.2 The Four Failure → Fix Mapping**\n\n| Symptom | Missing Technique | Why | \n|---|---|---|\n| Wrong output shape (prose instead of JSON/label) | Output constraint | Nothing specified the response's form/stopping point | \n| Content/scope drift over turns | System prompt (or a more specific one) | Behavioral contract too vague to hold across turns | \n| Right task, invented structure | Few-shot examples | Claude can't infer exact structure from description alone | \n| Works on tested inputs, breaks on edge case | Constraint covering that variant | Prompt only validated against a narrow input set | \n\n**2.1.3 System Prompts**\n\nCarry the persistent behavioral contract for the whole session — role, output format, rules that must not change between turns. Write once as a stable instruction layer.\n\n**2.1.4 XML Tags**\n\nUsed to separate instructions from examples/data (e.g., `<sample_input>`, `<ideal_output>`) so Claude doesn't misread examples as part of the task itself.\n\n**2.1.5 Few-Shot Examples**\n\nShow the exact input→output pattern (structure, casing, format) rather than describing it — closes gaps written instructions leave open, especially for edge cases.\n\n**2.1.6 Output Constraints**\n\nExplicitly define the exact form of the response (e.g., \"return only one label, no other text\") — controls form independent of content, preventing parser-breaking variability.\n\n**2.1.7 When to Stack vs. Simplify vs. Diagnose**\n\nStack all four techniques for complex tasks with defined output contracts and edge cases; simplify for simple tasks (e.g., plain summarization). If a prompt has grown longer over 3+ re-prompts without improving, stop and diagnose the missing technique instead of adding more text.\n\n**2.1.8 Worked Postmortem: Six-Pass Classification Prompt**\n\nA ticket-classifier prompt was revised 6 times, growing longer without fixing inconsistency — Pass 4 added description instead of a constraint, Pass 5's verbosity induced verbose output (latency regression, no accuracy gain). Pass 6 fixed it by replacing prose with an output constraint + 2 few-shot examples.\n\n**2.1.9 Structured Outputs: Moving Control from Prompt to API**\n\nInstead of asking for a shape via prompt text, you give the API a JSON schema and the model is constrained at generation time (constrained decoding) — only schema-matching tokens can be produced.\n\n| Mechanism | What It Does | \n|---|---|\n| JSON outputs | Set `output_config.format` to`type: json_schema` + your schema — constrains the final response text | \n| Strict tool use | Set `strict: true` on a tool definition — constrains/validates arguments before your code runs | \n\nTradeoffs: first request on a new schema is slower (grammar compiled, cached 24h); input tokens rise slightly (format-description system prompt injected); a guaranteed schema doesn't guarantee success — check `stop_reason` for `refusal`/` max_tokens`; incompatible with message prefilling.\n\n**2.2.1 What It Does**\n\nWhen enabled, Claude reasons step-by-step in a separate thinking block before the final answer. On newest models this content is hidden by default — request a summarized display to see it.\n\n**2.2.2 Adaptive Thinking / Effort Setting**\n\nEnabled via the `thinking` parameter (off by default); depth is tuned via an effort setting, not a fixed token budget. The older `budget_tokens` control is deprecated (400 error on newest models), and thinking tokens bill the same as output tokens.\n\n**2.2.3 When to Use Extended Thinking**\n\n| Task | Decision | \n|---|---|\n| Multi-step reasoning (math, multi-hop logic, dependent action planning) | Enable, match effort to problem depth | \n| Mechanical tasks (classification, format conversion, lookups) | Leave off — no benefit, wastes tokens | \n| Agentic loops planning across tool calls | Enable, budget for the planning step | \n\n**2.2.4 The Carry-Back Rule (Critical Constraint)**\n\nIn tool-use loops with thinking enabled, every thinking block must be sent back unchanged next turn — each has a signature, and editing/dropping it (even redacted blocks) breaks the signature and the API rejects the request. Manage context bloat via context engineering, never by stripping thinking blocks.\n\n**2.3.1 Tool-Use and Schema Design**\n\nCovered indirectly via structured outputs/strict tool use (see 2.1.9); explicit schema-design content beyond tool descriptions affecting routing appears under Agent Construction (see 2.6).\n\n**2.4.1 Why Streaming**\n\nSends the response in pieces as generated (via server-sent events) instead of waiting for the full message, removing blank-screen wait on long responses. Your code must reassemble blocks itself and handle early termination.\n\n**2.4.2 Event Sequence and Handler Actions**\n\n| Event | Meaning | Handler Action | \n|---|---|---|\n| `message_start` | New message beginning | Initialize empty content array | \n| `content_block_start` | New block opening (text/tool_use/thinking) | Create slot at that index | \n| `content_block_delta` | Incremental fragment of a block | Append to block; tool_use JSON isn't parseable until block closes | \n| `content_block_stop` | Block complete | Finalize block (first point tool_use JSON is parseable) | \n| `message_delta` | Top-level changes (stop_reason, usage) | Record stop_reason | \n| `message_stop` | Stream complete | Assembled content is now the finished message | \n\n**2.4.3 Never Act on a Partial Block**\n\n`tool_use` inputs arrive as fragmented JSON strings, invalid until `content_block_stop`. Parsing/running tools before block closure causes malformed JSON or missing arguments.\n\n**2.4.4 Commit to History Only After `message_stop`**\n\nOnly add a streamed assistant turn to history once `message_stop` arrives and every block is fully assembled — a turn from an interrupted stream has an incomplete `tool_use` block and violates tool-use pairing rules on the next request.\n\n**2.4.5 Handling Interrupted Streams**\n\nTreat accumulated content as provisional until `message_stop`; on interruption, discard the partial turn and retry. Check `stop_reason` from `message_delta` before continuing a loop — `tool_use` means calls are ready to run.\n\n**2.4.6 Postmortem: \"Read Loop Ended\" ≠ \"Message Complete\"**\n\nA handler that commits history whenever its read loop exits (instead of gating on `message_stop`) can silently commit corrupted `tool_use` blocks — the validation error surfaces on the *next* request, not the one that caused it.\n\n**2.5.1 Model Selection Recap**\n\nFour-tier family (Fable, Opus, Sonnet, Haiku) trading cost/latency/capability — start with Sonnet, move tiers only on eval results. Confirm current lineup/identifiers against docs at build time.\n\n**2.5.2 Context Window Is a Shared, Finite Budget**\n\nCovers system prompt, history, every persisting tool result, and output. An over-budget request is rejected pre-generation; hitting the ceiling mid-response returns partial output with `model_context_window_exceeded` — neither path auto-trims, so the app must manage it, and production sessions fill context faster than dev/test.\n\n**2.5.3 Four Strategies for Managing Context Budget**\n\n| Strategy | What It Does | When to Use | What's Lost | \n|---|---|---|---|\n| Pruning | Rewind to an earlier message, drop everything after | After an unproductive/dead-end path | Everything after the rewind point | \n| Compaction ( `/compact` ; server-side beta or manual summarization) | Summarizes history into a condensed version | Approaching context ceiling, want to retain knowledge | Any detail not captured in the summary | \n| Clearing ( `/clear` ; new API session) | Starts fresh, empty context | Next task is unrelated | All session context (persist elsewhere, e.g. CLAUDE.md) | \n| Subagent handoffs | Spawn isolated subagent with task-specific context; returns summary | Self-contained delegable subtasks | Visibility into subagent's intermediate reasoning | \n\n**2.5.4 Prompt Caching & Token Counting**\n\nPrompt caching reuses processing of a stable prefix at a fraction of cost via `cache_control` (`type: ephemeral`, up to 4 breakpoints) — the highest-leverage cost reduction for multi-turn sessions. `count_tokens` returns a request's token count without running inference, for dev validation and production budget gating.\n\n**2.5.5 RAG: Three Failure Points**\n\nRAG lets an LLM retrieve external documents via chunking → embedding match → assembly → answer. Chunking must balance size (too small loses context, too large dilutes matches); embedding match can miss exact-term matches (pair with lexical search); sloppy assembly causes the model to ignore retrieved content entirely.\n\n**2.5.6 Indexed vs. Iterative RAG**\n\nIndexed (fetch-once) is inspectable/testable but needs an index to build/maintain/secure — good for a stable corpus. Iterative (search-across-rounds) avoids staleness but costs more tokens/time and is less inspectable — better for changing corpora or multi-step questions.\n\n**2.5.7 Compaction: Summarizer Prompt Design**\n\nA vague summarizer prompt (\"summarize so far\") loses task-critical detail; a well-specified one (preserve file paths, decisions, errors/resolutions) retains what matters. Under-specified summarizers are a leading cause of multi-session agent failures.\n\n**2.5.8 Subagent Handoffs for Long-Horizon Tasks**\n\nInstead of growing the context window, decompose the task and give each subagent only a scoped task, minimal context, relevant prior results, needed tools, and clear exit conditions. Keeps per-turn cost low at the expense of implementation overhead.\n\n**2.5.9 Postmortem: Context Budget Not Tested Against Production Data**\n\nA receipt-processing agent's 40k-token self-imposed cap worked fine against 800-token/call dev fixtures but was exhausted by turn 8 against real 3,200-token production tool outputs, crowding out system instructions. Fix: prune tool outputs after use and compact proactively — always measure actual production-scale token costs before shipping.\n\n**2.6.1 Definition**\n\nAn agent is a multi-step tool-use loop with managed context and a defined goal. Key upfront question: does the problem actually require an agent, given the added coordination overhead, context cost, and failure surface?\n\n**2.6.2 Workflow vs. Agent Decision**\n\n| Choose a Workflow When... | Choose an Agent When... | \n|---|---|\n| Steps can be enumerated in code | Path can't be enumerated in advance | \n| Error cost is high, step-level guardrails needed | Non-determinism acceptable, actions constrained by toolset | \n| Standard observability tooling required | Inputs vary unpredictably | \n| Inputs are well-constrained | Task requires creative tool sequencing | \n\n**2.6.3 Three Wiring Paths**\n\n| Path | Who Runs the Loop | You Own | Best For | \n|---|---|---|---|\n| Raw API loop | Your code | Everything: loop, execution, context mgmt, retries, exit conditions | Full control / learning / library constraints | \n| Agent SDK | SDK, in your process | Tool execution + app; SDK gives loop structure, context mgmt, tool registration | Claude Code's scaffolding without rebuilding it | \n| Claude Managed Agents (public beta) | Anthropic (server-side, via SSE) | App layer + agent definition as a versioned resource | Long-running tasks (mins–hours), avoid building sandbox/loop | \n\n**2.6.4 Managed Agents Specifics**\n\nAnthropic runs the loop/sandbox/retries server-side with stateful stored sessions; not currently eligible for Zero Data Retention or HIPAA BAA (rules out PHI/ZDR workloads). Requires the `managed-agents-2026-04-01` beta header; common path is prototyping on Agent SDK then re-expressing config as a Managed Agents resource for production.\n\n**2.6.5 Four Steps Common to Every Agent Loop**\n\n(1) Register tools with consistent schema, (2) set a system prompt scoped to the agent's task/toolset, (3) handle the tool-use loop — every `tool_use` block must get a `tool_result` and all blocks from one turn resolved together, (4) define explicit exit conditions rather than relying on Claude to volunteer completion.\n\n**2.6.6 Human-in-the-Loop (HITL) Insertion Points**\n\n| Insertion Point | Trigger | Risk Addressed | \n|---|---|---|\n| Before destructive tool call | Write/delete/send operation | High — irreversible actions | \n| After a planning step | Plan generated, about to execute | Medium — wrong plan even if execution is correct | \n| On unexpected output | Error flag, empty result, out-of-bounds value | Variable — catches failures retries won't fix | \n\n**2.6.7 Tool Orchestration: Over-Tooling vs. Under-Tooling**\n\nToo many overlapping tools causes erratic routing (the more common production problem, from registering tools \"just in case\"); too few causes hallucinated paths. Start with the minimum tool set and add only on confirmed capability gaps.\n\n**2.6.8 Regulated Data Constraints Determine Delivery Route**\n\n| Constraint | Rules Out | Survives Review | \n|---|---|---|\n| Attorney-client privilege | Unaudited consumer Claude.ai calls | Direct API/SDK via firm's SSO-authenticated app, routed through firm-approved LLM gateway with full logging | \n| HIPAA (PHI) | Any endpoint without a covering BAA | BAA-covered direct API, or Bedrock/Vertex on a HIPAA-eligible account (BAA excludes Console, Workbench, betas, consumer plans) | \n| GDPR / data residency | Routes without pinned execution region; direct API (no EU residency) | Bedrock/Vertex with region pinned to the covered jurisdiction | \n| FedRAMP / government | Any non-authorized endpoint, incl. dev/test on commercial endpoint | Claude for Government (C4G), Bedrock GovCloud, Vertex Assured Workloads (Claude Enterprise on AWS Marketplace is NOT FedRAMP authorized) | \n| Internal data-residency policy | Any vendor outside the approved list | Delivery route on the approved vendor only | \n\n(SOC 2 governs system operation, not endpoint selection — covered in Module 4.)\n\n**2.7.1 Memory Scope**\n\n| Scope | Persists | Cost | Use When | Lost | \n|---|---|---|---|---|\n| In-context | Within a single session | Zero retrieval overhead, token cost grows with conversation | Short sessions fitting fully in context | Everything at session end | \n| External storage | Across sessions/users/instances, in a DB | Retrieval latency + read/write engineering | Cross-session continuity needed | Nothing (cost is latency/complexity) | \n| Summarized memory | Condensed version injected next session | Lower cost than full replay, drops detail | Long-running conversations exceeding budget | Anything summarizer didn't preserve | \n| Stateless (none) | Nothing | Zero overhead | Self-contained, one-off jobs | All prior context | \n\n**2.7.2 Design-Time Decision, Not Refactor-Time**\n\nChoosing memory scope during design avoids costly production refactors; a common failure pattern defaults to full in-context history, which works until token cost/latency climbs and hits the context ceiling.\n\n**2.7.3 Skills: Reusable, On-Demand Instruction Sets**\n\nA Skill is a reusable `SKILL.md` (frontmatter: name, description + instructions body) that Claude loads only when the description matches an incoming request — unlike in-context memory, instructions aren't resident every session.\n\n**2.7.4 Skills vs. CLAUDE.md vs. In-Context Instructions**\n\n| Pattern | Loads | Context Cost | Best For | \n|---|---|---|---|\n| Skill | On-demand, when description matches | Low (only name+description loaded upfront) | Task-specific expertise not needed every session | \n| CLAUDE.md | Every session unconditionally (CLI); controlled by `settingSources` in Agent SDK | Fixed overhead per session | Always-on project-wide standards | \n| In-context instructions | Every turn in that session | Grows with session length, doesn't survive session end | Short, one-off sessions | \n\n**2.7.5 Skills on the Messages API (Beta)**\n\nRequires two beta headers (`code-execution-2025-08-25`, `skills-2025-10-02`); Skills run inside the code execution container, not the app's own environment, affecting available tools/filesystem access.\n\n**2.7.6 Subagents and Skills**\n\nSubagents don't automatically inherit Skills or conversation history from the parent (clean context on delegation), but do inherit the parent's permission context. A subagent needing a Skill must have it explicitly listed in its own configuration.\n\n**2.7.7 Postmortem: In-Context Memory Filling by Session Four**\n\nAn escalation-support agent worked fine in dev (long continuous sessions) but failed in production, where many shorter sessions accumulated state until injected history exceeded 40k tokens by session 4 — before any tool call. Fix: refactor to external storage, though this took longer under production pressure than doing it at design time.\n\n**2.8.1 Cumulative Debug Task**\n\nApplied exercise combining prior concepts, not new theory. Observed bug-diagnosis mapping: vague tool descriptions → schema/routing failure; interrupted streams/stripped thinking blocks → carry-back rule violation; orphaned `tool_result` without matching `tool_use` → context/pairing violation; concatenated full session transcripts → memory scope failure at scale.\n\n**2.9.1 Image Token Cost**\n\nImages process in 28×28-pixel patches: cost = ⌈width/28⌉ × ⌈height/28⌉ visual tokens (e.g., 1000×1000px ≈ 1,296 tokens). Each tier has a max native resolution (oversized images downscaled first) — confirm current limits against docs, and measure production image token cost before building a pipeline.\n\n**2.9.2 Three Ways to Send an Image/File**\n\n| Method | Mechanism | Overhead | Best For | \n|---|---|---|---|\n| Inline base64 | Encode bytes directly in the message | Full payload sent every request | One-off images unlikely to be reused | \n| URL reference | Pass a public URL; Claude fetches it | No payload, but URL must stay stable/public/reachable | Already-hosted, stable public images | \n| Files API (beta; not on Bedrock/Vertex) | Upload once → get `file_id` → reference later | One-time upload cost, near-zero overhead thereafter | Reused assets, large files, multi-turn conversations | \n\n**2.9.3 Sending PDFs**\n\nUses a document block type (vs. image) with the same source structure (base64/URL/file_id); no required `name` field, optional `title`/` context` fields, same token-cost and Files API reuse mechanics.\n\n**2.9.4 Prompting Technique Carryover to Multimodal**\n\nThe same four prompting techniques apply to image/PDF analysis, but images introduce visual ambiguity (overlapping objects, depth, occlusion) that prompts should explicitly instruct how to handle.\n\n**2.9.5 Message Batches API**\n\nFor high-volume async processing — up to 100,000 requests or 256MB per batch. Submit → get `batch_id` → poll → download results (arbitrary order, matched via `custom_id`). Lower per-token cost, latency up to 24h — suited to offline pipelines/evals/bulk jobs, not real-time interactions.\n\n**2.9.6 Postmortem: \"Chunked Loop\" Mistaken for Batching**\n\nLooping over a list calling the synchronous API per item (even in smaller chunks) is not batching — it's serialized calls still hitting the same rate limits at volume. True batching requires the actual Batch API.\n\n**2.9.7 Use-Case Fit**\n\n| Scenario | API | Why | \n|---|---|---|\n| User uploads photo, expects immediate result | Synchronous | Real-time required | \n| Nightly job classifying 5,000 records | Batches API | No latency constraint; cost savings matter | \n| Eval run against 2,000 examples | Batches API | Offline, no real-time need | \n| Chatbot reply generation | Synchronous | User is actively waiting | \n\n**2.9.8 Two Failure Modes Combining Multimodal + Batch**\n\n(1) Misreading latency needs — using batch for a user-facing image flow fails because the user is waiting; (2) underestimating context cost — multiple large images/PDFs per request can blow past token limits at scale.\n\n**3.1.1 Module Orientation**\n\nClaude Code is a terminal-native dev partner running the same agent loop as the API, plus a permission layer, config system, and team-sharing features; MCP enables secure external-service integration. Core theme: configs that \"work on your machine\" often fail once shared, deployed, or run against production.\n\n**3.2.1 The Three-Phase Loop**\n\nClaude Code works in three phases: Explore (reads files, traces logic, no edits), Plan (proposes a structured edit description, requires human approval), Code (writes/executes changes only after approval) — this sequence reduces wrong assumptions.\n\n**3.2.2 Plan Mode as the Hook Point**\n\nPlan mode holds the agent in the explore phase, blocking all edits/commands until released — a good default for unfamiliar or high-stakes codebases.\n\n**3.3.1 Permission Modes**\n\n| Mode | Auto-Approves | Still Gated | Limitations | \n|---|---|---|---|\n| Default | Reads only | All edits/commands | Safe but slow; baseline for new/unfamiliar projects | \n| AcceptEdits | Reads, file edits, common filesystem commands ( `mkdir` ,`touch` ,`rm` ,`rmdir` ,`mv` ,`cp` ,`sed` ) in working dir | All other shell commands; writes outside working dir; protected paths | Good for trusted local work; not for running scripts | \n| Plan | Reads only | All edits/commands until plan approved | Exploration on sensitive/unfamiliar code; not for tasks needing output | \n| Auto | Everything, but a classifier reviews each action and blocks escalation/hostile intent | Production deploys, migrations, mass deletes, credential exfiltration, force-push to main | Research preview — not a safety guarantee; varies by plan/model | \n| DontAsk | Only pre-approved allow-listed tools + read-only commands | Everything else auto-denied | Built for locked-down CI/scripts, not for reducing local friction | \n| BypassPermissions | All tool calls, no prompts, no safety checks | Nothing (except catastrophic `rm -rf /` or`rm -rf ~` ) | Only safe in isolated/disposable containers — never on a live dev workstation | \n\n**3.4.1 Configuration Hierarchy**\n\n| Level | Location | Scope | Use For | \n|---|---|---|---|\n| User | `~/.claude/settings.json` | Every project on the machine, not committed | Personal defaults (e.g., preferred mode) | \n| Project | `.claude/settings.json` (committed) | Everyone who clones the repo | Team-wide conventions, allow/deny rules | \n| Local project | `.claude/settings.local.json` (git-ignored) | Personal overrides for one project | Individual preferences not meant for the team | \n| Enterprise | `managed-settings.json` (admin-set) | Cannot be overridden by users/projects | Org-wide security controls | \n\n**3.4.2 Rule Precedence**\n\nA deny rule always wins over an allow rule regardless of mode; enterprise-level deny rules are the most durable — they can't be removed by any developer and apply even under bypass mode.\n\n**3.5.1 The Governing Question & Gate Placement**\n\nAsk \"what's the worst outcome if this action runs unchecked?\" — let low-stakes reversible actions through, gate hard-to-undo/sensitive-path actions via deny rules or prompts, and always require human review before merging changes to team-flagged sensitive code.\n\n**3.5.2 Postmortem: BypassPermissions Removed a Safety Prompt**\n\nBypass mode skipped the confirmation prompt and protected-path guard that would have caught an overly broad file-pattern match, causing accidental deletion of production config files. Mitigation: set explicit deny rules on sensitive directories first; prefer classifier-gated modes (e.g., Auto) over full bypass.\n\n**3.6.1 CLAUDE.md Basics & `/init`**\n\n`CLAUDE.md` at the project root loads into every session, prepended before any user message, so conventions/constraints/commands persist without restating; `/init` generates a starter file by scanning the codebase (validate before relying on it).\n\n**3.6.2 Size Dilution Failure Mode**\n\nAs the file grows, each instruction becomes a smaller fraction of loaded context, reducing the chance any single rule is followed — keep `CLAUDE.md` to behavior-changing constraints and move everything else into on-demand Skills.\n\n**3.6.3 Postmortem: 847-Line CLAUDE.md**\n\nA real path restriction (line 347) was diluted among hundreds of unrelated lines (historical logs, archived notes) and the agent violated it. Fix: keep it as a working rule set, move path-specific rules to rules files, historical context to reference docs, non-negotiable constraints to hooks.\n\n**3.7.1 Rules Files: Path-Scoped Context**\n\nLive in `.claude/rules/`, scoped via a `paths` glob in YAML frontmatter, loading into context only when Claude works with matching files — avoiding `CLAUDE.md`-style dilution.\n\n**3.7.2 Scoping Comes from Frontmatter, Not Location**\n\nA rules file without a `paths` field loads unconditionally at launch (same priority as `CLAUDE.md`) regardless of subdirectory; pattern is broad/universal → `CLAUDE.md`, narrow/path-specific → rules files (e.g., `.claude/rules/database.md` with `paths: [\"src/db/**/*.sql\"]`).\n\n**3.8.1 Hooks: Deterministic Lifecycle Control**\n\nHooks intercept/control tool calls at fixed lifecycle points deterministically, unlike a `CLAUDE.md` instruction the model might follow inconsistently — defined in settings files, configured via `/hooks`.\n\n**3.8.2 Hook Events**\n\n| Event | Timing | Can Block? | Use For | \n|---|---|---|---|\n| `PreToolUse` | Before tool call executes | Yes — exit code 2 blocks it, stderr shown to agent | Access control enforcement | \n| `PostToolUse` | After tool call completes | No | Formatting, tests, audit logging | \n| `UserPromptSubmit` | On prompt submission, before processing | — | Inject context, validate request | \n| `Stop` | When model finishes responding | — | Notifications, cleanup, audit commits | \n| `Notification` | On Claude Code notifications (permission requests, 60s idle) | — | Route to external channel/logging | \n| `SessionStart` | Session start/resume | — | Initialize state, validate env vars | \n| `SessionEnd` | Session end | — | Teardown, final audit writes | \n\n**3.8.3 Hook vs. Convention**\n\nA `PreToolUse` hook enforces a constraint (e.g., blocking edits to a production config path) at every tool call, every session, regardless of permission mode — the difference between a guardrail (hook) and a convention (`CLAUDE.md` instruction).\n\n**3.9.1 Subagents: Isolated Context**\n\nSpecialized assistants that run tasks in an isolated context — no inheritance of main conversation history, accumulated files, or session state; return only their output.\n\n**3.9.2 Built-in vs. Custom Subagent Behavior**\n\nBuilt-in `Explore`/` Plan` subagents skip `CLAUDE.md` and git status (optimized for speed, so project rules don't apply); `general-purpose` loads both. Custom subagents don't auto-inherit skills — list needed skills explicitly in the subagent's frontmatter (`.claude/agents`).\n\n**3.9.3 Mechanism Comparison**\n\n| Mechanism | Loads | When | Context Cost | Belongs | \n|---|---|---|---|---|\n| CLAUDE.md | Full file, prepended | Every session | Persistent, dilutes with size | Universal constraints/commands | \n| Rules file | File contents | On matching file access (or session start if unscoped) | Path-scoped: only when triggered; unscoped: same as CLAUDE.md | Path-specific guidance | \n| Hook | Runs a script | At configured lifecycle event | Minimal | Guardrails, automation, audit | \n| Subagent | Task context only | When dispatched | Returns summary only | Exploration/investigation, parallelizable work | \n\n**3.10.1 Skills: Portable Markdown Procedures**\n\nA Skill is a portable `SKILL.md` in `.claude/skills` (frontmatter identifies/describes it, body holds steps); the same file can run in Claude Code, via Messages API, or via Agent SDK — only where it runs and what it can access changes.\n\n**3.10.2 Skill Runtimes**\n\n| Runtime | How It Loads | Where Steps Run | Key Requirement | \n|---|---|---|---|\n| Claude Code | Filesystem discovery (description match or invoke by name) | Local terminal, under active permission mode/deny rules | Filesystem-based, governed by settings layer | \n| Messages API | Sent with request, runs in code execution container | Anthropic's container, not local machine | Requires code-execution + skills beta headers; no local file/tool assumptions | \n| Agent SDK | Loaded by agent; controlled by `settingSources` (TS) /`setting_sources` (Python) | The SDK's own process, once filesystem sources are enabled | Must explicitly set `settingSources` — no reliable default | \n| Claude Managed Agents | Defined once as an API resource (model, prompt, tools, MCP, skills) | Anthropic-provisioned sandbox | Requires `managed-agents-2026-04-01` beta header; not ZDR/HIPAA-eligible; skills attached at agent-definition time | \n\n**3.10.3 Three Portability Rules**\n\n(1) Write the skill's description as a precise matching criterion; (2) don't assume local filesystem/tools exist — document dependencies explicitly; (3) subagents don't inherit skills in any runtime — must be explicitly listed.\n\n**3.11.1 Custom Commands (Legacy vs. Skills)**\n\nSkills are now the recommended format for both explicit (`/skill-name`) and automatic invocation; the older `.claude/commands/` format still works but is legacy. Use `disable-model-invocation: true` in frontmatter for commands that should only run when explicitly called.\n\n**3.11.2 Plugin Namespacing**\n\nA plugin name becomes the command prefix (e.g., `/payments:run-tests`), preventing collisions across plugins; renaming a plugin renames all its commands.\n\n**3.11.3 Plugins & Marketplaces**\n\nA plugin is a versioned bundle of skills, hooks, subagents, and MCP servers distributed via a marketplace. Anthropic's official marketplace is available by default; third-party ones are added via `/plugin marketplace add <owner/repo>`. Enterprise admins can deploy plugins org-wide via managed settings, gated by a managed marketplace allowlist, paired with `extraKnownMarketplaces` to auto-register for all users; managed-scope settings sit above user/project settings and cannot be overridden.\n\n**3.11.4 Packaging Decision Table**\n\n| Layer | Reach For When | \n|---|---|\n| Skill | Task-specific procedure should stay out of context until needed | \n| Custom command | Predictable, explicit high-frequency entry point wanted | \n| Plugin | A working local setup needs to be shared/versioned across a team | \n\n**3.11.5 Postmortem: Plugin Portability Failure**\n\nA plugin skill referenced an author's absolute local path and an undocumented env var — installed fine everywhere, but execution failed for every teammate. Fix: use `$CLAUDE_PROJECT_DIR` / `${CLAUDE_PLUGIN_ROOT}` for paths, bundle dependent assets, document/validate env vars at install, and test on a clean machine; note a locally-relied-on deny rule/hook isn't auto-included in a plugin bundle.\n\n**3.12.1 What MCP Is**\n\nMCP (Model Context Protocol) separates tool definitions from individual applications into a standalone server process exposing tools, resources, and prompts to any connecting client — build once, reuse everywhere.\n\n**3.12.2 Tools, Resources, Prompts**\n\nTools are actions the model can call; Resources are read-only data fetched directly into context (not via a tool call) — direct (fixed address) or templated (parameterized), used when cheap predictable injection beats a tool call (client support varies); Prompts are pre-written, vetted instruction templates exposed by name for consistent wording across clients.\n\n**3.13.1 Transport Options**\n\n| Transport | Mechanism | Use For | \n|---|---|---|\n| stdio | Local subprocess via standard input/output | Local tools, personal scripts, dev servers on your own machine — not shareable/remote | \n| HTTP | Standard network connection via URL | Recommended for any non-local server — shared team servers, hosted integrations | \n| SSE | Legacy transport predating HTTP | No longer recommended for new servers; treat as legacy if encountered | \n\n**3.13.2 Context Cost & Tool Discovery**\n\nConnected servers' tool definitions would occupy context if loaded upfront; Claude Code defers loading and searches to discover/load only relevant tools per task by default (an opt-in mode loads upfront if definitions fit within ~10% of the context window). Connect only needed servers to keep requests lean.\n\n**3.14.1 How Prompt Caching Works**\n\nCaches processing of a stable request prefix so follow-up requests reuse it at a fraction of cost; the first request writes to cache, and an exact match is required — a single changed character before the cache point invalidates it. Best candidates: long system prompts, large tool-definition sets, frequently-queried reference docs.\n\n**3.14.2 Cache Configuration Details**\n\nEnabled via `cache_control: {type: ephemeral}` on the last block to cache (up to 4 breakpoints); request order is fixed (tools → system prompt → messages), so a breakpoint after tools caches definitions while messages stay dynamic. Default lifetime is 5 minutes from last read; opt-in 1-hour via `ttl: \"1h\"`; a minimum token threshold applies (1,024 for most current models).\n\n**3.15.1 Classical RAG vs. Agentic Search**\n\nClassical RAG pre-chunks and embeds source material into a database, matched by similarity at query time (index built in advance); agentic search has no pre-built index — the model searches/fetches live sources on demand (e.g., MCP tool discovery, Projects surfacing relevant sections). Both retrieve a relevant slice and generate from it — the difference is timing.\n\n**3.15.2 Two Properties of Retrieval**\n\n(1) Scales flat — request cost stays roughly constant as source material grows, since only a relevant slice is retrieved per query; (2) quality depends on retrievability — if retrieval misses the needed document the model never sees it, so well-named, well-organized files matter.\n\n**3.16.1 Scope Levels**\n\n| Scope | Location | Applies To | Use For | \n|---|---|---|---|\n| Local | `~/.claude.json` (per-project entry) | Current project only, not shared | Project-specific, not-yet-shared config | \n| User | Personal Claude settings | All your projects, still personal | Personal utilities used everywhere | \n| Project | `.mcp.json` (committed to repo) | Everyone who clones the repo | Team-wide shared server access | \n| Enterprise | Centrally managed config (admin-controlled) | Entire organization | Shared internal services, security tooling | \n\n**3.16.2 Note on Project-Scoped stdio Servers**\n\nA project-scoped stdio server still runs from each teammate's own machine — each clone needs the runtime (e.g., Node for an `npx`-launched server) installed locally.\n\n**3.17.1 Per-Tool Permission Rules**\n\nMCP tools are identified as `mcp__server__tool`, so rules can target individual tools rather than the whole server — an allow rule on one tool lets it run without prompting while others on the same server still prompt; a deny rule on a write-capable tool blocks it while read-only tools remain available, and deny always overrides allow.\n\n**3.17.2 API MCP Connector: Scope vs. Governance**\n\nAn `mcp_toolset` object with a per-tool `enabled` flag controls whether the model even sees a tool (context/scope control), distinct from a permission rule controlling whether an exposed tool may run (governance control) — often used together; verify exact syntax/beta headers against docs.\n\n**3.18.1 GitHub MCP Setup**\n\nTransport: HTTP (remote, hosted by GitHub), registered via server URL; scope: Project for whole-team access, local for individual use; auth: a Personal Access Token passed as a Bearer token, supplied via environment variable and referenced in config — never committed inline (a committed token enters repo history permanently).\n\n**3.18.2 OAuth Alternative**\n\nFor services authenticating individual users via browser sign-in (e.g., Linear MCP) — client redirects to the provider's sign-in page, token issued/stored automatically after approval, no manual credential handling; right pattern when authorization is tied to user identity.\n\n**3.18.3 MCP Setup Reference**\n\n| Context | Transport | Scope | Secrets Handling | \n|---|---|---|---|\n| Personal local tool | stdio | Local | Env vars only, never in config file | \n| Shared team server | HTTP | Project ( `.mcp.json` ) | OAuth or env vars; never committed | \n| Personal experiment | stdio/HTTP | Local | Env vars only | \n| Org-wide deployment | HTTP | Enterprise | Admin-managed secrets, config locked | \n\n**3.19.1 Auth Method by Service Type**\n\n| Service Type | Auth Method | Secret Location | \n|---|---|---|\n| Remote, user identity (SaaS/cloud) | OAuth (server returns 401 → browser sign-in) | Token issued/stored by client | \n| Remote, service identity (internal API) | API key via environment variable | Environment only, injected by CI/pipeline runner | \n| Local, filesystem access | stdio, no network auth | Filesystem permission model + deny rules as governance | \n\n**3.19.2 Secret Management: Three Practices**\n\n(1) Separation — config holds only a variable reference, never the value, since committed values persist in repo history; (2) storage — env var for local/short-lived secrets, a secret store for shared/audited ones (enables single-point rotation); (3) rotation — replace on a schedule and immediately after suspected exposure, scoped narrowly per credential.\n\n**3.20.1 Beyond Authentication: Three Requirements**\n\n(1) Configuration lock — enterprise managed settings prevent developers from overriding auth setup; (2) audit logging — a `PostToolUse` hook logging every tool call/parameters, firing deterministically and unskippable by the model; (3) data residency — an HTTP endpoint pinned to a region plus a platform deployment enforcing regional processing.\n\n**3.20.2 Authentication/Integration Checklist**\n\n| Service Type | Auth | Secrets | Logging | Config Lock | \n|---|---|---|---|---|\n| Remote, user identity | OAuth | Client-stored token | PostToolUse hook | Enterprise managed settings | \n| Remote, service identity | API key (env var) | Environment only | PostToolUse hook | Enterprise managed settings | \n| Local | Filesystem permissions | None needed | PostToolUse hook | Deny rules in managed settings | \n\n**3.20.3 Postmortem: OAuth Staging-to-Production Failure**\n\nOAuth redirect URIs are registered per host, so a working staging connection doesn't guarantee production works — the production host's URI isn't automatically authorized, and regulated customers often require separate app registrations per environment. Fix: add the new host's redirect URI before cutover and include this in the deployment checklist.\n\n**3.21.1 Modernization Risk Profile**\n\nLegacy modernization concentrates high blast radius, unpredictable dependencies, and limited reversibility; the Explore/Plan/Code loop and Plan mode hold the agent in read-only review, hooks guard sensitive paths during high-risk phases, and CLAUDE.md carries target-pattern conventions so the agent doesn't drift back to legacy patterns.\n\n**3.21.2 Three Scoping Questions**\n\nBefore high-risk agentic work, ask: (1) what's the blast radius — which systems depend on this code; (2) how are changes audited — is a `PostToolUse` hook logging every tool call sufficient; (3) who approves each phase before the next begins — Plan mode enforces the explore/execute boundary, but the approval process itself must be defined beforehand.\n\n**4.1.1 Core Theme: Production Reveals What Development Hides**\n\nSuccess criteria never written down, retriable errors never given a path, budgets never instrumented, action boundaries never enforced — these are decisions, not bugs, and must be made on paper before failures happen live.\n\n**4.1.2 The Design Document — Four Decisions**\n\n| Decision | What It Defines | \n|---|---|\n| Success criteria | Concrete, checkable output definitions (e.g., \"a two-sentence summary listing every action item and owner\") — what the eval set is built from | \n| Failure handling | Expected production errors, each marked retriable/terminal, and what the user sees on unrecoverable failure | \n| Cost and latency budget | Per-request budget, monthly cost ceiling, latency target, minimum reliability floor — set before architecture | \n| Trust boundary | Which inputs are untrusted, and the smallest set of actions/access the feature needs — turns least privilege into an enforceable hook, not a remembered setting | \n\n**4.2.1 What an Eval Is**\n\nA fixed set of input cases + expected behavior + grading, run and averaged into a trackable score — turns \"done\" from a feeling into a number. Write the eval before building the feature, forcing success to be defined upfront.\n\n**4.2.2 Minimal Eval Pipeline**\n\nLoad dataset → run each case → grade output → average scores. Change one variable (prompt, tool, or model) at a time between runs so you know what caused any score movement.\n\n**4.2.3 Three Grading Methods**\n\n| Method | Best For | Catches | Blind Spot | \n|---|---|---|---|\n| Exact/string match | Output with exactly one correct form | Wrong answer, zero ambiguity, near-zero cost | Fails on any valid paraphrase or reordering | \n| Code-graded check | Structured/code output | Invalid JSON, unparseable code, out-of-range values, missing fields | Confirms well-formedness only, not content quality | \n| LLM-as-judge | Open-ended quality (faithfulness, instruction-following, tone) | What no code rule can express | Noisy, costly, produces a confident-looking but meaningless number until calibrated | \n\n**4.2.4 Cost Dimension**\n\nExact match/code checks run locally at near-zero cost (thousands per change); a judge is a second model call per case — grade format/structure with code on every commit, reserve judge calls for slower scheduled quality passes.\n\n**4.2.5 Building/Calibrating a Judge**\n\nPrompt the judge for strengths, weaknesses, and reasoning alongside the score, or it drifts to a \"safe middle\" (~6) regardless of quality. Calibrate by running it against a human-labeled set and measuring agreement — low agreement means an untrustworthy score, fixed by tightening the rubric.\n\n**4.2.6 Coverage Over Perfection**\n\nA larger, noisier automated eval set usually reveals more than a small hand-graded one; use Claude to generate additional edge cases from a small labeled starting set, then spot-check them.\n\n**4.2.7 Iteration Workflow**\n\nSet goal → write initial prompt → run eval → read per-case failures → apply one change → re-run. Per-case breakdown matters as much as the average (can hide fixes canceling breaks); categorize failure cause (formatting, retrieval, long-input) to target the next fix.\n\n**4.2.8 Postmortem: Field-Extraction Two-Date Failure**\n\nA feature passed ~12 manual checks (all single-date messages) and shipped with shape-only validation; a message with two dates extracted the wrong one, since validation confirmed shape, not correctness, and no holdout set covered that case. Fix: define graded cases including model-generated edge cases before shipping — the eval guards against regressions, it doesn't fix the underlying prompt.\n\n**4.3.1 Four Test Levels**\n\n| Level | Isolates | Cannot Catch | \n|---|---|---|\n| Unit | One function (parser, tool wrapper) alone | How components fit together | \n| Functional | One Claude call returns expected shape for an input | Failures in the surrounding system | \n| Integration | The handoff/seam between two components (e.g., retrieval → model) | Whole-flow behavior emerging only end-to-end | \n| End-to-end | Full flow as a user would run it | Where the break is — slowest, hardest to localize | \n\n**4.3.2 Integration Seam Failures**\n\nMost silent production failures live at the integration seam — each side passes its own tests while the handoff between them is broken (e.g., one returns a list of dicts, the other expects a plain string).\n\n**4.3.3 Tracing**\n\nRecords each run step (prompt, tool calls, intermediate outputs, timing), turning \"the case failed\" into \"step 4: parser raised KeyError on a field the model didn't return\" — a 5-minute fix instead of a day of investigation.\n\n**4.3.4 Retrieval Routing (Cost-Aware)**\n\nA cheap classifier routes simple lookups to fetch-once retrieval and multi-part questions to iterative/agentic search, avoiding defaulting everything to the expensive or shallow path. Skip the router if all traffic is one shape.\n\n**4.3.5 Postmortem: Unit/Functional Passed, End-to-End Failed**\n\n`retrieve()` returned a list of dicts while `build_prompt()` expected a plain string, causing malformed context and the model to answer from memory instead of retrieved content — only an integration test exercising the real handoff would catch this.\n\n**4.4.1 Retriable vs. Terminal**\n\n| Category | HTTP Status Codes | Examples | \n|---|---|---|\n| Retriable | 429, 529, 500, 502, 503, 504 | Rate limit, overload, transient server fault, timeout | \n| Terminal | 400, 401, 403, 404 | Bad request, auth failure, missing resource, permissions problem | \n\nMisclassifying as terminal fails loudly and gets fixed (safe default when unsure); misclassifying as retriable hammers the service and hides the real problem.\n\n**4.4.2 SDK-Level Retries**\n\nAnthropic client libraries auto-retry transient failures with progressive delays up to a configurable cap — avoid stacking a custom retry loop on top (multiplies attempts against a rate limit); either let the SDK own retries or turn them off and own the whole path.\n\n**4.4.3 `retry-after` Header**\n\nPresent on 429/529 responses, gives the exact wait time — more precise than blind backoff. Read it first; fall back to exponential backoff only when absent.\n\n**4.4.4 Tool Errors & Refusals**\n\nTool errors must return to Claude explicitly with `is_error: true` — a silent empty result is treated as valid data, producing a confident-but-wrong answer. A refusal (`stop_reason: \"refusal\"`) is a 200 at the HTTP layer, so the retriable classifier won't catch it — treat it as terminal, raise and log, never retry.\n\n**4.4.5 Error-Handling Decision Table**\n\n| Error | Retriable? | Strategy | Fallback | \n|---|---|---|---|\n| Rate limit (429) | Yes | Exponential backoff + jitter, honor `retry-after` , capped attempts | Clean error or cached/simpler result after cap | \n| Overloaded (529) | Yes | Backoff (Anthropic-side load, not a rate-limit signal) | Fail over or graceful error if persists | \n| Bad request (400) | No | No retry | Fix/reject input, surface to caller | \n| Tool result error | Depends | Retry only if cause is transient | Return error flag to Claude, never silence | \n| Refusal (200, `stop_reason: refusal` ) | No | No retry | Raise to caller, log, never treat as valid output | \n\n**4.4.6 Postmortem: Unhandled Rate Limit + Retry Storm**\n\nA loop with no error handling worked in low-volume dev; the first production 429 raised an unhandled exception, and the instinct to add immediate retries deepened the rate limit. Fix: honor `retry-after` first, fall back to capped exponential backoff with jitter, and fail fast on terminal statuses (400/401/403/404).\n\n**4.4.7 Model Selection in Production**\n\nFamily order: Fable (hardest reasoning/coding/agentic) → Opus (above Sonnet's envelope) → Sonnet (balanced default) → Haiku (speed/cost-optimized). Start with Sonnet, move up only when an eval shows a missed quality bar, move down only when an eval shows an acceptable drop — defaulting to the most capable model \"just in case\" is the most common, expensive mistake. Route bulk traffic to a default model, override via a cheap signal (task type, length, difficulty) only where needed.\n\n**4.5.1 Observability: Three Metrics**\n\nInstrument token usage (input/output), latency, and error rate per call from the start — per-call logging turns \"why is the bill high?\" into \"which step, on which request type, is responsible?\"\n\n**4.5.2 Cost/Latency Levers: Model Selection & Streaming**\n\nRoute simpler work to smaller/faster models, reserve capable ones for steps that need them. With streaming + tool use, accumulate `content_block_delta` events by index and never act on a `tool_use` block until the stream closes — a broken mid-stream response needs a full retry, not partial output passed downstream.\n\n**4.5.3 Prompt Caching Economics**\n\nCache writes cost a premium (1.25x base for 5-min TTL, 2x for 1-hour); cache reads cost ~0.1x standard input — only pays off when reads outnumber writes. Two modes: automatic (single flag, system manages breakpoints) or explicit `cache_control` breakpoints.\n\n**4.5.4 Message Batches API**\n\nAsync processing at lower per-request cost in exchange for non-immediate completion — right for non-urgent, high-volume work (overnight jobs, backfills), wrong for anything a user is waiting on; compounds with prompt caching when a batch reuses shared context.\n\n**4.5.5 Multi-Agent Orchestration (Orchestrator-Worker)**\n\nA lead agent decomposes a task, delegates to parallel subagents, then synthesizes results — genuinely helps independently-splittable tasks (e.g., research) but Anthropic's internal eval showed it costs ~15x a normal chat interaction, and is less effective on tightly coupled tasks like coding where steps can't be parallelized. Use a capable lead with cheaper subagents to reduce the multiplier; failure handling multiplies with agent count.\n\n**4.5.6 Reliability Floor**\n\nDefine a base (retry budget, latency ceiling) first, then tune cost above it, never below — cost pressure is more visible daily than reliability pressure, so the eval's pinned baseline score is what makes the floor enforceable before shipping.\n\n**4.5.7 Postmortem: Fan-Out on a Tightly-Coupled Task**\n\nParallel fan-out applied to a sequential, dependent-step task tripled the bill with barely improved quality, since subagents mostly waited on each other. Reverting to single-agent restored cost with equal quality.\n\n**4.6.1 Prompt Injection: The Core Threat**\n\nThe model processes its entire context as one undifferentiated token stream — no structural boundary separates trusted instructions from untrusted data, so hidden instructions in fetched content are read as commands.\n\n**4.6.2 Defense: Treat Content as Data**\n\nTreat all fetched/user-supplied content as data to examine, never instructions to follow — trusting your own users doesn't help, since the hostile instruction typically arrives via retrieved content. Delimiter-wrapping helps but is a soft boundary; the reliable boundary is what the agent is allowed to do.\n\n**4.6.3 Threat Scope & Jailbreak vs. Injection**\n\nAny content someone else can write is a vector (shared docs, DB records, emails, chained tool outputs), direct or hidden. Jailbreaks target the model's own safety constraints; injections hijack the application's instructions — both need the same layered defense.\n\n**4.6.4 Secure-by-Design Identity and Access**\n\nAgent identity carries only the narrowest permission set the task requires; secrets live in env vars or a secret manager, never committed config. Least privilege bounds the blast radius of a successful injection; committed secrets are permanent exposures since only rotation (impossible for a hardcoded value) fixes a leak.\n\n**4.6.5 Hook-Based Guardrails**\n\nA `PreToolUse` hook blocks a tool call before execution and logs every privileged action — enforced control vs. an unenforced prompt-level rule. Precedence when rules conflict: deny > ask > allow.\n\n**4.6.6 Scoping for Regulated Review**\n\nThree early questions: where is data processed (residency), how is access logged (per-action audit trail), and can configuration be centrally administered (prevents developers quietly widening permissions).\n\n**4.6.7 ZDR Note**\n\nZero Data Retention eligibility varies by model and platform, not guaranteed even under an existing agreement — confirm against Anthropic's Trust Center (and Bedrock/Vertex/Foundry retention policies separately) at scoping time.\n\n**4.6.8 Layered Security Model**\n\nModel training + classifiers (reduce injection landing) → treating content as data (reduce acted-upon injections) → least privilege + locked config (bound blast radius) → hooks (enforce + record) → regulated-review scoping (make it auditable) — no single layer is sufficient alone.\n\n**4.6.9 OS-Level Sandboxing**\n\nIsolates at the process level regardless of hook/identity config: filesystem isolation restricts the agent to its working directory, network isolation restricts outbound connections to a named endpoint set. Holds even when a hook is missing or bypassed — typically the first thing enterprise security reviewers ask about.\n\n**4.6.10 Postmortem: Hidden Instruction Redirected a Write**\n\nAn internal-only agent skipped validating fetched web content, assuming trusting the user meant trusting the request; a hidden instruction in a fetched page redirected the agent's write to an unintended path. Fix: treat fetched content as data plus a `PreToolUse` hook denying writes outside the permitted path.\n\n**4.6.11 Defense Checklist**\n\n| Threat | Entry Point | Control | Logged | \n|---|---|---|---|\n| Prompt injection | Hidden instructions in fetched content | Treat as data + hook refusing untrusted-triggered actions | Source, attempted action, block | \n| Jailbreak | Crafted user prompt | Input validation + model action constraints | Flagged prompt, refusal | \n| Over-broad access | Identity scoped wider than needed | Least privilege, secrets manager, locked auth config | Every privileged action + identity | \n| Sandbox escape | Steered agent reaching uncovered paths/endpoints | OS-level filesystem/network isolation | Every denied access attempt + trigger | \n\n**4.7.1 Cumulative Task Structure**\n\nA single runnable application containing three planted defects, one per layer (eval/testing, failure-handling, security) — e.g., an agent that writes based on untrusted fetched content without a hook, a retry loop with no real backoff that retries terminal errors too, and no `is_error` handling on tool results.\n\n**5.1.1 Core Theme**\n\nA build that works is not yet a build that survives reuse, review, or deployment — templates aren't configurable, contributions aren't verifiable by a stranger, models aren't pinned, platforms haven't cleared compliance, and trust boundaries haven't been mapped. Much of this work is driven by the customer's cloud/compliance posture, not technical preference.\n\n**5.2.1 Accelerator Definition**\n\nA solution packaged so future engagements start from a working foundation instead of a blank repo — separating engagement-specific code from a parameterized reusable core. Package while the build is fresh, before the reasoning behind hardcoded values is lost.\n\n**5.2.2 Three Asset Types**\n\n| Asset Type | What It Bundles | Correct Packaging Requires | \n|---|---|---|\n| Agent Template | System prompt, tool schemas, loop structure | Pull domain values into configuration with documented defaults — new team sets values, doesn't edit the loop | \n| MCP Server Package | Exposed tools, their inputs, controllable scope | Document each tool input; let the installing team set scope — installs without code edits | \n| Eval Suite | Graded test set + judge rubric | Ship dataset and rubric together as the deployment gate (run against a pinned baseline before promoting a new model version) | \n\n**5.2.3 Common Failure: Loose Scripts**\n\nShipping an agent as loose scripts instead of a template looks reusable because it \"runs,\" but customer-specific values stay buried across files, so the next team copies and diverges instead of configuring one asset.\n\n**5.2.4 Documentation & Audit Bundling**\n\nDocumentation must cover environment assumptions, expected inputs, handled failure modes, and the defining eval, or the next team treats the asset as a black box. Bundle the audit log (data touched, identity acted under) too — a regulated reviewer asks for this at the first security review.\n\n**5.2.5 Packaging Checklist**\n\n| Asset Type | Parameterize | Document | Bundle for Audit | \n|---|---|---|---|\n| Agent template | Prompts, paths, scopes, credentials by reference, thresholds | Environment assumptions, expected inputs, handled failures, defining eval | Data touched, identity acted under, action log | \n| MCP Server | Scopes, credentials by reference, per-customer paths | Expected inputs per tool, scope boundaries, handled failures | Data touched, identity acted under, action log | \n| Eval Suite | Thresholds, dataset paths | Rubric logic, what scores mean, pinned baseline | Data touched, identity acted under, action log | \n\n**5.2.6 Postmortem: Hardcoded Values Labeled Reusable**\n\nA team hardcoded customer-specific values into a template to hit a deadline, then labeled it \"reusable\"; a second team couldn't configure it (no parameters, no documentation, no bundled eval) and had to rewrite it fully. A template that runs has not been packaged for reuse — these are different finishing states.\n\n**5.3.1 Definition**\n\nMoving an asset from private reuse to shared infrastructure through a documented channel carrying version, install steps, and components as one unit — an asset already packaged for internal reuse is already close to what a maintainer needs.\n\n**5.3.2 Matching Contribution to Channel**\n\nThe Claude Cookbook takes self-contained, single/multi-pattern reference implementations demonstrated end to end, not a full application; open-source MCP servers/tools each have their own repo and conventions. Misplacement — sending a full multi-component app to the Cookbook — is one of the most common reasons a contribution never gets reviewed.\n\n**5.3.3 Four Things That Make Verification Possible**\n\n(1) Does one thing, (2) an example shows it running, (3) a test proves it works, (4) a short statement names the assumptions — the bar is set by what needs checking, not code cleverness.\n\n**5.3.4 Rights and Attribution Come First**\n\nLicensing decides whether a contribution can be accepted at all; code carried in from a customer engagement may have constraints on where it can go. Confirming the right to contribute and attributing prior work is a gate that must be passed before technical review.\n\n**5.3.5 Contribution-Readiness Reference**\n\n| Channel | What a Maintainer Checks | Licensing/Attribution | Example/Test Bar | \n|---|---|---|---|\n| Cookbook (focused example) or tool/server's own repo | Code does one thing, fully readable | Confirm right to contribute engagement code, prior work attributed | Runnable example + a test proving behavior, not just description | \n\n**5.3.6 Postmortem: Unreviewed PR for Three Weeks**\n\nA PR sat unreviewed because it had no test, no example, and no stated environment assumptions — the maintainer couldn't verify it without reconstructing the developer's work. A contribution the reviewer can't verify sits at the back of the queue regardless of code correctness.\n\n**5.4.1 From Business Problem to Functional Requirements**\n\nA functional requirement states what the system must do with enough detail to check (e.g., \"classify each ticket into one of four queues... never auto-send without human approval,\" not \"help agents answer faster\") — a specific goal becomes an eval line and a review criterion.\n\n**5.4.2 Deriving Infrastructure Requirements**\n\nNon-functional constraints derived by asking: latency (how fast, measured where?), scale (how many requests, at what peak?), residency (where must data be processed?), identity (who acts, under what credentials, what's auditable?) — these four most often decide the deployment platform.\n\n**5.4.3 Documenting Requirements**\n\nA short record of functional behaviors, infrastructure constraints, and the regulation each derives from lets a platform choice be defended as following from requirements rather than familiarity.\n\n**5.5.1 Seven Phases**\n\nRequirements (capture functional/infrastructure needs) → Design (platform, model, trust boundaries) → Build (agent, tools, prompts) → Test (evals, unit/integration/e2e) → Deploy (pin version, gate on eval) → Operate (instrument cost/latency/errors, enforce guardrails) → Iterate (feed production findings back into requirements).\n\n**5.5.2 Gating Between Phases**\n\nA gate is the decision point to move between phases where a regulated engagement retains control (e.g., don't move design→build until the platform satisfies residency). Refusing to skip a gate is what keeps an application reviewable; a one-off experiment may collapse phases, a regulated deployment cannot.\n\n**5.6.1 Platform Choice Driven by Customer's Cloud**\n\n| Platform | Identity/Data Model | When to Choose | \n|---|---|---|\n| First-party Claude API | Anthropic identity and terms | No binding cloud/residency constraint; wants newest capabilities first | \n| Claude Platform on AWS | Anthropic identity/terms via customer's AWS account; inference outside the AWS boundary | On AWS but wants Anthropic model IDs/lifecycle parity with first-party API | \n| Claude in Amazon Bedrock | Messages API at `/anthropic/v1/messages` ; data stays inside customer's AWS boundary | On AWS, wants feature parity + compliance posture there | \n| Claude on Amazon Bedrock (legacy) | AWS identity/billing; `InvokeModel` /`Converse` APIs, ARN-versioned IDs | Existing (unmigrated) Bedrock integration | \n| Google Vertex AI | Google Cloud identity/IAM/billing; regional or global endpoints | On Google Cloud with compliance posture there | \n| Third-party (e.g., Microsoft Foundry) | Wrapping product's identity/billing | Already runs the platform embedding Claude; residency depends on hosting form (Azure-hosted vs. Anthropic-hosted) per model | \n\n**5.6.2 Identity and Residency Answered by Platform**\n\nBedrock uses AWS identity and keeps data in the customer's AWS boundary; Vertex uses Google Cloud identity/boundary; both offer regional routing. Matching platform to the customer's existing compliance agreement avoids a residency review from scratch.\n\n**5.6.3 Pinning Versions**\n\nEvery model ID points to a specific snapshot; aliases (e.g., \"Opus,\" \"Sonnet\") evolve over time, so pin the full model ID, not the alias (e.g., `claude-haiku-4-5-20251001` vs. the moving `claude-haiku-4-5`), and version prompts/assets alongside code with a rollback-ready prior version.\n\n**5.6.4 Promote via the Eval**\n\nSend a new version to a portion of traffic, compare against the pinned baseline, promote or roll back on the result — the eval is the deployment gate, not just a one-time test.\n\n**5.6.5 Deployment-Platform Versioning**\n\n| Platform | Versioning | \n|---|---|\n| First-party API | Pin full model ID, keep prior snapshot | \n| Claude Platform on AWS | Same ID format as Claude API; lifecycle follows Anthropic's schedule | \n| Claude in Amazon Bedrock | Pin full model ID with `anthropic.` prefix; partner retirement dates differ | \n| Claude on Amazon Bedrock (legacy) | Pin via ARN-versioned identifiers | \n| Google Vertex AI | Pin full model ID before rollout; partner retirement dates differ | \n| Third-party platform | Pin per the platform's own versioning controls | \n\n**5.6.6 Postmortem: Moving Alias Broke Production**\n\nA deployment shipped against a moving alias (\"opus\"); it silently advanced to a new version, breaking downstream parsing with no pinned prior version to roll back to, forcing a hotfix instead. Lesson: pin the full model ID, retain the prior pinned version, gate promotions through the eval.\n\n**5.7.1 Latency**\n\nDepends on platform location relative to the customer and feature-access timing (first-party API usually gets new capabilities first) — must be measured from the customer's actual region/payload. Within Bedrock, global vs. regional endpoints is the primary residency control and can affect cost.\n\n**5.7.2 Compliance Often Ends the Debate**\n\nA customer already certified on one cloud is unlikely to re-certify on another; residency/certifications/audit access differ by platform and are pass-or-fail for regulated customers. First-party API may lack EU residency (Bedrock/Vertex typically required); on Foundry, hosting is per-model. Raise compliance constraints at scoping, not at contract review.\n\n**5.7.3 Cost Beyond Per-Token Rate**\n\nToken rates are broadly aligned across platforms; total cost is driven by egress, platform fees, and integration effort — instrument cost per call per platform rather than comparing token price alone.\n\n**5.7.4 Cross-Platform Comparison Reference**\n\n| Dimension | How It Differs | How to Measure | Winner | \n|---|---|---|---|\n| Latency | In-region platform shortens round trip; first-party API gets features first | From customer's actual region + payload | In-region cloud wins on latency; first-party wins on feature access | \n| Compliance | Residency, certifications, audit controls vary by platform | Against customer's existing certification/residency requirements at scoping | The already-certified platform wins | \n| Cost | Token price, egress, platform fees, integration effort all vary | Total cost per call including egress/integration | Lowest total cost for the actual workload | \n\n**5.7.5 Postmortem: Familiar Platform Failed Residency Review**\n\nA team picked the platform they knew best for a regulated customer since migration was fast; it passed functional tests but failed the customer's residency requirement at security review, requiring a rebuild. Familiarity optimizes for build speed, not for whether the deployment is allowed to ship.\n\n**5.8.1 Multi-Component Coordination**\n\nAn app might chain an API request → Claude Code task → MCP server reaching a customer system; each connection creates a place where identity, secrets, and untrusted input can cross — map what each component does before connecting anything.\n\n**5.8.2 Least Privilege Applies to the Whole Application**\n\nEach component operates under its own identity, scoped to only what its task needs — the application is only as contained as its most privileged seam, so one overly-broad component becomes the weak point even if others are properly scoped.\n\n**5.8.3 Regulated Review Requirements**\n\nRequires justifying audit logging, data-residency decisions, and permission controls across the full application, not per component — confirm ZDR/HIPAA BAA eligibility for each individual component against the Trust Center before scoping.\n\n**5.8.4 Multi-Component Integration Map**\n\n| Component | Contributes | Trust Boundary at Seam | Control | \n|---|---|---|---|\n| First-party API | Orchestrates workflow, holds entry point | Request entering the app from outside | Input validation + identity the call runs under | \n| Claude Code task | Runs agentic work, may fetch external content | Content it fetched — untrusted downstream | Treat fetched content as data at the next seam | \n| MCP server | Reaches a customer system to read/act | System access held on the app's behalf | Scope to least privilege + log the access | \n\n**5.8.5 Postmortem: Untrusted Content Passed as Trusted Input**\n\nThree components each passed their own tests; content fetched by the Claude Code task was passed directly into the next call as trusted input with no boundary control at that seam — a hidden instruction there would have executed. A component being trusted in isolation says nothing about the seam leaving it.\n\n**5.9.1 Cumulative Task Structure**\n\nA single deployed accelerator with three planted defects: a hardcoded customer-specific value where a parameter belongs (packaging), a moving model alias instead of a pinned full ID (versioning), and fetched untrusted content passed directly into the next call with no boundary control (trust boundary). Task: identify all three, explain the runtime consequence, and write the corrected lines.", "url": "https://wpnews.pro/news/claude-certified-developer-foundations-certification-overview", "canonical_source": "https://dev.to/yashnigam/claude-certified-developer-foundations-certification-overview-4n07", "published_at": "2026-09-13 20:02:28+00:00", "updated_at": "2026-09-13 20:20:30.086835+00:00", "lang": "en", "topics": ["large-language-models", "ai-agents", "ai-tools", "developer-tools", "ai-research"], "entities": ["Anthropic", "Claude", "Claude Code", "MCP", "Claude Certified Developer - Foundations"], "alternates": {"html": "https://wpnews.pro/news/claude-certified-developer-foundations-certification-overview", "markdown": "https://wpnews.pro/news/claude-certified-developer-foundations-certification-overview.md", "text": "https://wpnews.pro/news/claude-certified-developer-foundations-certification-overview.txt", "jsonld": "https://wpnews.pro/news/claude-certified-developer-foundations-certification-overview.jsonld"}}