Claude Certified Developer - Foundations certification Overview

I recently completed the Claude Certified Developer - Foundations certification.

This certification is based on the official course from Anthropic: https://anthropic-partners.skilljar.com/path/claude-certified-developer-foundations

However, this course is only available to Anthropic partners. Below is my overview of the modules and structure of the Prep Course.

The course consists of the following main modules:

MSO Foundations

Learn the model fundamentals and technical foundations the rest of the Developer Foundations course builds on.

Production-Grade Prompting, Agents & Tool Use

Build your first production integration on Claude, with reliable prompts, tools, context management, and agent loops.

Claude Code, MCP & Integration

Learn to make a working Claude integration configurable, shareable, and safe to connect to real systems.

Production Engineering, Evals & Security

Learn to take an agent that works in development and prove it holds up under real production traffic.

Accelerators & IP Contribution

Package a build that works into one that survives reuse, review, and deployment beyond the engagement that created it. 1.1.1 Tokens

Everything 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.

1.1.2 Context Window

The 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.

1.1.3 Sampling & Temperature

Claude 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.

1.1.4 Non-Determinism

Sampling 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."

1.1.5 Testing Model Output: Structural vs. Semantic Correctness

Check Type	Definition	Examples
Structural correctness	Deterministic, yes/no checks	Regex match, valid JSON, exact substring, value within tolerance
Semantic correctness	Meaning-based checks, can't be scripted deterministically	Summary captures key points, correct tone, accurate despite different phrasing

Semantic checks need an LLM-as-judge: a separate model call scores the output, often against a rubric/reference answer.

1.1.6 Evals

A 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.

1.2.1 Claude Model Family

Four tiers trading off cost, latency, capability, and quality:

Tier	Description
Sonnet	Balanced default for most production workloads
Haiku	Optimized for speed/cost within its capability range
Opus	For demanding work beyond Sonnet's envelope
Fable	Highest-capability tier, for the hardest reasoning/coding/agentic tasks

1.2.2 Model Selection Strategy

Start 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.

1.2.3 Reasoning Modes

Reasoning 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.

1.3.1 Zero-shot / One-shot / Multi-shot (Few-shot) Prompting Distinguished by how many worked examples are given in the prompt:

Mode	Examples Given	Best Used When
Zero-shot	None (instruction only)	Task is simple, output shape is obvious
One-shot	One input/output example	A single reference clarifies expected output
Multi-shot (Few-shot)	Several examples	Needs specific structure, casing, or edge-case handling

1.3.2 Cost Tradeoff of Examples

Each example consumes tokens on every call and eats into context budget, so examples aren't free — they trade quality/precision against cost.

1.3.3 Interaction with Model Choice

More 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.

1.4.1 SDK vs. Raw REST API

Claude 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.

1.4.2 Response Delivery Patterns

Pattern	Description
Synchronous	Send request, wait for full response, then act — simplest pattern
Streaming	Delivered in pieces via server-sent events as generated; output appears immediately, client reassembles the final message
Asynchronous ( AsyncAnthropic )	Non-blocking async/await enables concurrency without blocking, while each call still returns in real time
Message Batches API	High-volume/offline: submit a batch, poll for completion; up to 24h latency for lower per-token cost

2.1.1 Diagnosing Prompt Failures Instead of Adding Words

When 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.

2.1.2 The Four Failure → Fix Mapping

Symptom	Missing Technique	Why
Wrong output shape (prose instead of JSON/label)	Output constraint	Nothing specified the response's form/stopping point
Content/scope drift over turns	System prompt (or a more specific one)	Behavioral contract too vague to hold across turns
Right task, invented structure	Few-shot examples	Claude can't infer exact structure from description alone
Works on tested inputs, breaks on edge case	Constraint covering that variant	Prompt only validated against a narrow input set

2.1.3 System Prompts

Carry 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.

2.1.4 XML Tags

Used to separate instructions from examples/data (e.g., <sample_input>, <ideal_output>) so Claude doesn't misread examples as part of the task itself.

2.1.5 Few-Shot Examples

Show the exact input→output pattern (structure, casing, format) rather than describing it — closes gaps written instructions leave open, especially for edge cases.

2.1.6 Output Constraints

Explicitly 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.

2.1.7 When to Stack vs. Simplify vs. Diagnose

Stack 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.

2.1.8 Worked Postmortem: Six-Pass Classification Prompt

A 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.

2.1.9 Structured Outputs: Moving Control from Prompt to API

Instead 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.

Mechanism	What It Does
JSON outputs	Set output_config.format totype: json_schema + your schema — constrains the final response text
Strict tool use	Set strict: true on a tool definition — constrains/validates arguments before your code runs

Tradeoffs: 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.

2.2.1 What It Does

When 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.

2.2.2 Adaptive Thinking / Effort Setting

Enabled 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.

2.2.3 When to Use Extended Thinking

Task	Decision
Multi-step reasoning (math, multi-hop logic, dependent action planning)	Enable, match effort to problem depth
Mechanical tasks (classification, format conversion, lookups)	Leave off — no benefit, wastes tokens
Agentic loops planning across tool calls	Enable, budget for the planning step

2.2.4 The Carry-Back Rule (Critical Constraint) In 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.

2.3.1 Tool-Use and Schema Design

Covered 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).

2.4.1 Why Streaming

Sends 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.

2.4.2 Event Sequence and Handler Actions

Event	Meaning	Handler Action
message_start	New message beginning	Initialize empty content array
content_block_start	New block opening (text/tool_use/thinking)	Create slot at that index
content_block_delta	Incremental fragment of a block	Append to block; tool_use JSON isn't parseable until block closes
content_block_stop	Block complete	Finalize block (first point tool_use JSON is parseable)
message_delta	Top-level changes (stop_reason, usage)	Record stop_reason
message_stop	Stream complete	Assembled content is now the finished message

2.4.3 Never Act on a Partial Block

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.

2.4.4 Commit to History Only After message_stop

Only 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.

2.4.5 Handling Interrupted Streams

Treat 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.

2.4.6 Postmortem: "Read Loop Ended" ≠ "Message Complete"

A 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.

2.5.1 Model Selection Recap

Four-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.

2.5.2 Context Window Is a Shared, Finite Budget

Covers 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.

2.5.3 Four Strategies for Managing Context Budget

Strategy	What It Does	When to Use	What's Lost
Pruning	Rewind to an earlier message, drop everything after	After an unproductive/dead-end path	Everything after the rewind point
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
Clearing ( /clear ; new API session)	Starts fresh, empty context	Next task is unrelated	All session context (persist elsewhere, e.g. CLAUDE.md)
Subagent handoffs	Spawn isolated subagent with task-specific context; returns summary	Self-contained delegable subtasks	Visibility into subagent's intermediate reasoning

2.5.4 Prompt Caching & Token Counting

Prompt 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.

2.5.5 RAG: Three Failure Points

RAG 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.

2.5.6 Indexed vs. Iterative RAG

Indexed (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.

2.5.7 Compaction: Summarizer Prompt Design

A 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.

2.5.8 Subagent Handoffs for Long-Horizon Tasks

Instead 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.

2.5.9 Postmortem: Context Budget Not Tested Against Production Data

A 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.

2.6.1 Definition

An 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?

2.6.2 Workflow vs. Agent Decision

Choose a Workflow When...	Choose an Agent When...
Steps can be enumerated in code	Path can't be enumerated in advance
Error cost is high, step-level guardrails needed	Non-determinism acceptable, actions constrained by toolset
Standard observability tooling required	Inputs vary unpredictably
Inputs are well-constrained	Task requires creative tool sequencing

2.6.3 Three Wiring Paths

Path	Who Runs the Loop	You Own	Best For
Raw API loop	Your code	Everything: loop, execution, context mgmt, retries, exit conditions	Full control / learning / library constraints
Agent SDK	SDK, in your process	Tool execution + app; SDK gives loop structure, context mgmt, tool registration	Claude Code's scaffolding without rebuilding it
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

2.6.4 Managed Agents Specifics

Anthropic 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.

2.6.5 Four Steps Common to Every Agent Loop

(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.

2.6.6 Human-in-the-Loop (HITL) Insertion Points

Insertion Point	Trigger	Risk Addressed
Before destructive tool call	Write/delete/send operation	High — irreversible actions
After a planning step	Plan generated, about to execute	Medium — wrong plan even if execution is correct
On unexpected output	Error flag, empty result, out-of-bounds value	Variable — catches failures retries won't fix

2.6.7 Tool Orchestration: Over-Tooling vs. Under-Tooling

Too 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.

2.6.8 Regulated Data Constraints Determine Delivery Route

Constraint	Rules Out	Survives Review
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
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)
GDPR / data residency	Routes without pinned execution region; direct API (no EU residency)	Bedrock/Vertex with region pinned to the covered jurisdiction
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)
Internal data-residency policy	Any vendor outside the approved list	Delivery route on the approved vendor only

(SOC 2 governs system operation, not endpoint selection — covered in Module 4.)

2.7.1 Memory Scope

Scope	Persists	Cost	Use When	Lost
In-context	Within a single session	Zero retrieval overhead, token cost grows with conversation	Short sessions fitting fully in context	Everything at session end
External storage	Across sessions/users/instances, in a DB	Retrieval latency + read/write engineering	Cross-session continuity needed	Nothing (cost is latency/complexity)
Summarized memory	Condensed version injected next session	Lower cost than full replay, drops detail	Long-running conversations exceeding budget	Anything summarizer didn't preserve
Stateless (none)	Nothing	Zero overhead	Self-contained, one-off jobs	All prior context

2.7.2 Design-Time Decision, Not Refactor-Time

Choosing 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.

2.7.3 Skills: Reusable, On-Demand Instruction Sets

A 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.

2.7.4 Skills vs. CLAUDE.md vs. In-Context Instructions

Pattern	Loads	Context Cost	Best For
Skill	On-demand, when description matches	Low (only name+description loaded upfront)	Task-specific expertise not needed every session
CLAUDE.md	Every session unconditionally (CLI); controlled by settingSources in Agent SDK	Fixed overhead per session	Always-on project-wide standards
In-context instructions	Every turn in that session	Grows with session length, doesn't survive session end	Short, one-off sessions

2.7.5 Skills on the Messages API (Beta)

Requires 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.

2.7.6 Subagents and Skills

Subagents 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.

2.7.7 Postmortem: In-Context Memory Filling by Session Four

An 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.

2.8.1 Cumulative Debug Task

Applied 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.

2.9.1 Image Token Cost

Images 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.

2.9.2 Three Ways to Send an Image/File

Method	Mechanism	Overhead	Best For
Inline base64	Encode bytes directly in the message	Full payload sent every request	One-off images unlikely to be reused
URL reference	Pass a public URL; Claude fetches it	No payload, but URL must stay stable/public/reachable	Already-hosted, stable public images
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

2.9.3 Sending PDFs

Uses 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.

2.9.4 Prompting Technique Carryover to Multimodal

The 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.

2.9.5 Message Batches API

For 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. 2.9.6 Postmortem: "Chunked Loop" Mistaken for Batching

Looping 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.

2.9.7 Use-Case Fit

Scenario	API	Why
User uploads photo, expects immediate result	Synchronous	Real-time required
Nightly job classifying 5,000 records	Batches API	No latency constraint; cost savings matter
Eval run against 2,000 examples	Batches API	Offline, no real-time need
Chatbot reply generation	Synchronous	User is actively waiting

2.9.8 Two Failure Modes Combining Multimodal + Batch

(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.

3.1.1 Module Orientation

Claude 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.

3.2.1 The Three-Phase Loop

Claude 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.

3.2.2 Plan Mode as the Hook Point

Plan mode holds the agent in the explore phase, blocking all edits/commands until released — a good default for unfamiliar or high-stakes codebases.

3.3.1 Permission Modes

Mode	Auto-Approves	Still Gated	Limitations
Default	Reads only	All edits/commands	Safe but slow; baseline for new/unfamiliar projects
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
Plan	Reads only	All edits/commands until plan approved	Exploration on sensitive/unfamiliar code; not for tasks needing output
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
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
BypassPermissions	All tool calls, no prompts, no safety checks	Nothing (except catastrophic rm -rf / orrm -rf ~ )	Only safe in isolated/disposable containers — never on a live dev workstation

3.4.1 Configuration Hierarchy

Level	Location	Scope	Use For
User	~/.claude/settings.json	Every project on the machine, not committed	Personal defaults (e.g., preferred mode)
Project	.claude/settings.json (committed)	Everyone who clones the repo	Team-wide conventions, allow/deny rules
Local project	.claude/settings.local.json (git-ignored)	Personal overrides for one project	Individual preferences not meant for the team
Enterprise	managed-settings.json (admin-set)	Cannot be overridden by users/projects	Org-wide security controls

3.4.2 Rule Precedence

A 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.

3.5.1 The Governing Question & Gate Placement

Ask "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.

3.5.2 Postmortem: BypassPermissions Removed a Safety Prompt

Bypass 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.

3.6.1 CLAUDE.md Basics & /init

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).

3.6.2 Size Dilution Failure Mode

As 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.

3.6.3 Postmortem: 847-Line CLAUDE.md

A 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.

3.7.1 Rules Files: Path-Scoped Context

Live in .claude/rules/, scoped via a paths glob in YAML frontmatter, into context only when Claude works with matching files — avoiding CLAUDE.md-style dilution.

3.7.2 Scoping Comes from Frontmatter, Not Location

A 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"]).

3.8.1 Hooks: Deterministic Lifecycle Control

Hooks 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.

3.8.2 Hook Events

Event	Timing	Can Block?	Use For
PreToolUse	Before tool call executes	Yes — exit code 2 blocks it, stderr shown to agent	Access control enforcement
PostToolUse	After tool call completes	No	Formatting, tests, audit logging
UserPromptSubmit	On prompt submission, before processing	—	Inject context, validate request
Stop	When model finishes responding	—	Notifications, cleanup, audit commits
Notification	On Claude Code notifications (permission requests, 60s idle)	—	Route to external channel/logging
SessionStart	Session start/resume	—	Initialize state, validate env vars
SessionEnd	Session end	—	Teardown, final audit writes

3.8.3 Hook vs. Convention

A 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).

3.9.1 Subagents: Isolated Context

Specialized assistants that run tasks in an isolated context — no inheritance of main conversation history, accumulated files, or session state; return only their output.

3.9.2 Built-in vs. Custom Subagent Behavior

Built-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).

3.9.3 Mechanism Comparison

Mechanism	Loads	When	Context Cost	Belongs
CLAUDE.md	Full file, prepended	Every session	Persistent, dilutes with size	Universal constraints/commands
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
Hook	Runs a script	At configured lifecycle event	Minimal	Guardrails, automation, audit
Subagent	Task context only	When dispatched	Returns summary only	Exploration/investigation, parallelizable work

3.10.1 Skills: Portable Markdown Procedures

A 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.

3.10.2 Skill Runtimes

Runtime	How It Loads	Where Steps Run	Key Requirement
Claude Code	Filesystem discovery (description match or invoke by name)	Local terminal, under active permission mode/deny rules	Filesystem-based, governed by settings layer
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
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
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

3.10.3 Three Portability Rules

(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.

3.11.1 Custom Commands (Legacy vs. Skills)

Skills 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.

3.11.2 Plugin Namespacing

A plugin name becomes the command prefix (e.g., /payments:run-tests), preventing collisions across plugins; renaming a plugin renames all its commands.

3.11.3 Plugins & Marketplaces

A 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.

3.11.4 Packaging Decision Table

Layer	Reach For When
Skill	Task-specific procedure should stay out of context until needed
Custom command	Predictable, explicit high-frequency entry point wanted
Plugin	A working local setup needs to be shared/versioned across a team

3.11.5 Postmortem: Plugin Portability Failure

A 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.

3.12.1 What MCP Is

MCP (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.

3.12.2 Tools, Resources, Prompts

Tools 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.

3.13.1 Transport Options

Transport	Mechanism	Use For
stdio	Local subprocess via standard input/output	Local tools, personal scripts, dev servers on your own machine — not shareable/remote
HTTP	Standard network connection via URL	Recommended for any non-local server — shared team servers, hosted integrations
SSE	Legacy transport predating HTTP	No longer recommended for new servers; treat as legacy if encountered

3.13.2 Context Cost & Tool Discovery

Connected servers' tool definitions would occupy context if loaded upfront; Claude Code defers 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.

3.14.1 How Prompt Caching Works

Caches 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.

3.14.2 Cache Configuration Details

Enabled 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).

3.15.1 Classical RAG vs. Agentic Search

Classical 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.

3.15.2 Two Properties of Retrieval

(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.

3.16.1 Scope Levels

Scope	Location	Applies To	Use For
Local	~/.claude.json (per-project entry)	Current project only, not shared	Project-specific, not-yet-shared config
User	Personal Claude settings	All your projects, still personal	Personal utilities used everywhere
Project	.mcp.json (committed to repo)	Everyone who clones the repo	Team-wide shared server access
Enterprise	Centrally managed config (admin-controlled)	Entire organization	Shared internal services, security tooling

3.16.2 Note on Project-Scoped stdio Servers

A 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.

3.17.1 Per-Tool Permission Rules

MCP 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.

3.17.2 API MCP Connector: Scope vs. Governance

An 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.

3.18.1 GitHub MCP Setup

Transport: 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).

3.18.2 OAuth Alternative

For 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. 3.18.3 MCP Setup Reference

Context	Transport	Scope	Secrets Handling
Personal local tool	stdio	Local	Env vars only, never in config file
Shared team server	HTTP	Project ( .mcp.json )	OAuth or env vars; never committed
Personal experiment	stdio/HTTP	Local	Env vars only
Org-wide deployment	HTTP	Enterprise	Admin-managed secrets, config locked

3.19.1 Auth Method by Service Type

Service Type	Auth Method	Secret Location
Remote, user identity (SaaS/cloud)	OAuth (server returns 401 → browser sign-in)	Token issued/stored by client
Remote, service identity (internal API)	API key via environment variable	Environment only, injected by CI/pipeline runner
Local, filesystem access	stdio, no network auth	Filesystem permission model + deny rules as governance

3.19.2 Secret Management: Three Practices

(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.

3.20.1 Beyond Authentication: Three Requirements

(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.

3.20.2 Authentication/Integration Checklist

Service Type	Auth	Secrets	Logging	Config Lock
Remote, user identity	OAuth	Client-stored token	PostToolUse hook	Enterprise managed settings
Remote, service identity	API key (env var)	Environment only	PostToolUse hook	Enterprise managed settings
Local	Filesystem permissions	None needed	PostToolUse hook	Deny rules in managed settings

3.20.3 Postmortem: OAuth Staging-to-Production Failure OAuth 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.

3.21.1 Modernization Risk Profile

Legacy 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.

3.21.2 Three Scoping Questions

Before 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.

4.1.1 Core Theme: Production Reveals What Development Hides

Success 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.

4.1.2 The Design Document — Four Decisions

Decision	What It Defines
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
Failure handling	Expected production errors, each marked retriable/terminal, and what the user sees on unrecoverable failure
Cost and latency budget	Per-request budget, monthly cost ceiling, latency target, minimum reliability floor — set before architecture
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

4.2.1 What an Eval Is

A 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.

4.2.2 Minimal Eval Pipeline

Load 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.

4.2.3 Three Grading Methods

Method	Best For	Catches	Blind Spot
Exact/string match	Output with exactly one correct form	Wrong answer, zero ambiguity, near-zero cost	Fails on any valid paraphrase or reordering
Code-graded check	Structured/code output	Invalid JSON, unparseable code, out-of-range values, missing fields	Confirms well-formedness only, not content quality
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

4.2.4 Cost Dimension

Exact 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.

4.2.5 Building/Calibrating a Judge

Prompt 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.

4.2.6 Coverage Over Perfection

A 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.

4.2.7 Iteration Workflow

Set 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.

4.2.8 Postmortem: Field-Extraction Two-Date Failure A 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.

4.3.1 Four Test Levels

Level	Isolates	Cannot Catch
Unit	One function (parser, tool wrapper) alone	How components fit together
Functional	One Claude call returns expected shape for an input	Failures in the surrounding system
Integration	The handoff/seam between two components (e.g., retrieval → model)	Whole-flow behavior emerging only end-to-end
End-to-end	Full flow as a user would run it	Where the break is — slowest, hardest to localize

4.3.2 Integration Seam Failures

Most 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).

4.3.3 Tracing

Records 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.

4.3.4 Retrieval Routing (Cost-Aware) A 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.

4.3.5 Postmortem: Unit/Functional Passed, End-to-End Failed

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.

4.4.1 Retriable vs. Terminal

Category	HTTP Status Codes	Examples
Retriable	429, 529, 500, 502, 503, 504	Rate limit, overload, transient server fault, timeout
Terminal	400, 401, 403, 404	Bad request, auth failure, missing resource, permissions problem

Misclassifying as terminal fails loudly and gets fixed (safe default when unsure); misclassifying as retriable hammers the service and hides the real problem.

4.4.2 SDK-Level Retries

Anthropic 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.

4.4.3 retry-after Header

Present 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.

4.4.4 Tool Errors & Refusals

Tool 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.

4.4.5 Error-Handling Decision Table

Error	Retriable?	Strategy	Fallback
Rate limit (429)	Yes	Exponential backoff + jitter, honor retry-after , capped attempts	Clean error or cached/simpler result after cap
Overloaded (529)	Yes	Backoff (Anthropic-side load, not a rate-limit signal)	Fail over or graceful error if persists
Bad request (400)	No	No retry	Fix/reject input, surface to caller
Tool result error	Depends	Retry only if cause is transient	Return error flag to Claude, never silence
Refusal (200, stop_reason: refusal )	No	No retry	Raise to caller, log, never treat as valid output

4.4.6 Postmortem: Unhandled Rate Limit + Retry Storm

A 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).

4.4.7 Model Selection in Production

Family 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.

4.5.1 Observability: Three Metrics

Instrument 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?"

4.5.2 Cost/Latency Levers: Model Selection & Streaming

Route 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.

4.5.3 Prompt Caching Economics

Cache 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.

4.5.4 Message Batches API

Async 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.

**4.5.5 Multi-Agent Orchestration (Orchestrator-Worker)**

A 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.

4.5.6 Reliability Floor

Define 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.

4.5.7 Postmortem: Fan-Out on a Tightly-Coupled Task Parallel 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.

4.6.1 Prompt Injection: The Core Threat

The 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.

4.6.2 Defense: Treat Content as Data

Treat 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.

4.6.3 Threat Scope & Jailbreak vs. Injection

Any 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.

4.6.4 Secure-by-Design Identity and Access

Agent 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.

4.6.5 Hook-Based Guardrails

A 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.

4.6.6 Scoping for Regulated Review

Three 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).

4.6.7 ZDR Note

Zero 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.

4.6.8 Layered Security Model

Model 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.

4.6.9 OS-Level Sandboxing

Isolates 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.

4.6.10 Postmortem: Hidden Instruction Redirected a Write

An 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.

4.6.11 Defense Checklist

Threat	Entry Point	Control	Logged
Prompt injection	Hidden instructions in fetched content	Treat as data + hook refusing untrusted-triggered actions	Source, attempted action, block
Jailbreak	Crafted user prompt	Input validation + model action constraints	Flagged prompt, refusal
Over-broad access	Identity scoped wider than needed	Least privilege, secrets manager, locked auth config	Every privileged action + identity
Sandbox escape	Steered agent reaching uncovered paths/endpoints	OS-level filesystem/network isolation	Every denied access attempt + trigger

4.7.1 Cumulative Task Structure

A 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.

5.1.1 Core Theme

A 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.

5.2.1 Accelerator Definition

A 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.

5.2.2 Three Asset Types

Asset Type	What It Bundles	Correct Packaging Requires
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
MCP Server Package	Exposed tools, their inputs, controllable scope	Document each tool input; let the installing team set scope — installs without code edits
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)

5.2.3 Common Failure: Loose Scripts

Shipping 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.

5.2.4 Documentation & Audit Bundling

Documentation 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.

5.2.5 Packaging Checklist

Asset Type	Parameterize	Document	Bundle for Audit
Agent template	Prompts, paths, scopes, credentials by reference, thresholds	Environment assumptions, expected inputs, handled failures, defining eval	Data touched, identity acted under, action log
MCP Server	Scopes, credentials by reference, per-customer paths	Expected inputs per tool, scope boundaries, handled failures	Data touched, identity acted under, action log
Eval Suite	Thresholds, dataset paths	Rubric logic, what scores mean, pinned baseline	Data touched, identity acted under, action log

5.2.6 Postmortem: Hardcoded Values Labeled Reusable

A 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.

5.3.1 Definition

Moving 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.

5.3.2 Matching Contribution to Channel

The 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.

5.3.3 Four Things That Make Verification Possible

(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.

5.3.4 Rights and Attribution Come First

Licensing 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.

5.3.5 Contribution-Readiness Reference

Channel	What a Maintainer Checks	Licensing/Attribution	Example/Test Bar
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

5.3.6 Postmortem: Unreviewed PR for Three Weeks

A 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.

5.4.1 From Business Problem to Functional Requirements

A 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.

5.4.2 Deriving Infrastructure Requirements

Non-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.

5.4.3 Documenting Requirements

A 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.

5.5.1 Seven Phases

Requirements (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).

5.5.2 Gating Between Phases

A 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.

5.6.1 Platform Choice Driven by Customer's Cloud

Platform	Identity/Data Model	When to Choose
First-party Claude API	Anthropic identity and terms	No binding cloud/residency constraint; wants newest capabilities first
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
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
Claude on Amazon Bedrock (legacy)	AWS identity/billing; InvokeModel /Converse APIs, ARN-versioned IDs	Existing (unmigrated) Bedrock integration
Google Vertex AI	Google Cloud identity/IAM/billing; regional or global endpoints	On Google Cloud with compliance posture there
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

5.6.2 Identity and Residency Answered by Platform

Bedrock 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.

5.6.3 Pinning Versions

Every 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.

5.6.4 Promote via the Eval

Send 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.

5.6.5 Deployment-Platform Versioning

Platform	Versioning
First-party API	Pin full model ID, keep prior snapshot
Claude Platform on AWS	Same ID format as Claude API; lifecycle follows Anthropic's schedule
Claude in Amazon Bedrock	Pin full model ID with anthropic. prefix; partner retirement dates differ
Claude on Amazon Bedrock (legacy)	Pin via ARN-versioned identifiers
Google Vertex AI	Pin full model ID before rollout; partner retirement dates differ
Third-party platform	Pin per the platform's own versioning controls

5.6.6 Postmortem: Moving Alias Broke Production

A 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.

5.7.1 Latency

Depends 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.

5.7.2 Compliance Often Ends the Debate

A 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.

5.7.3 Cost Beyond Per-Token Rate

Token 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.

5.7.4 Cross-Platform Comparison Reference

Dimension	How It Differs	How to Measure	Winner
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
Compliance	Residency, certifications, audit controls vary by platform	Against customer's existing certification/residency requirements at scoping	The already-certified platform wins
Cost	Token price, egress, platform fees, integration effort all vary	Total cost per call including egress/integration	Lowest total cost for the actual workload

5.7.5 Postmortem: Familiar Platform Failed Residency Review

A 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.

5.8.1 Multi-Component Coordination

An 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.

5.8.2 Least Privilege Applies to the Whole Application

Each 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.

5.8.3 Regulated Review Requirements

Requires 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.

5.8.4 Multi-Component Integration Map

Component	Contributes	Trust Boundary at Seam	Control
First-party API	Orchestrates workflow, holds entry point	Request entering the app from outside	Input validation + identity the call runs under
Claude Code task	Runs agentic work, may fetch external content	Content it fetched — untrusted downstream	Treat fetched content as data at the next seam
MCP server	Reaches a customer system to read/act	System access held on the app's behalf	Scope to least privilege + log the access

5.8.5 Postmortem: Untrusted Content Passed as Trusted Input

Three 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.

5.9.1 Cumulative Task Structure

A 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.

source & further reading

dev.to — original article RTK: A High-Performance Rust CLI Proxy That Slashes AI Agent Token Costs Why Your .NET MCP Tool Classes Crash at Runtime (And the Two-Line Fix) Learn Eval Ownership by Building a Tiny Lab Witness