A Study Guide for Building on Claude

The knowledge you need to design on Claude.

What this guide covers

The Claude Certified Developer – Foundations (CCD-F) exam is scenario-based. You’re the lead engineer on a new project with constraints (latency, volume, budget, compliance, autonomy), and you choose the model, API features and architecture. The right answer is the simplest design that meets every constraint.

Outline

1. The API and SDKs: the stack, the agent loop, tools and MCP, and settings
2. Delivery and reliability: streaming, batching, rate limits, errors and retries
3. Caching and costs: what you pay for, how the cache works, and how to pay less
4. Prompt engineering: the anatomy of a request, techniques and structured outputs
5. Context engineering: subagents, compaction, context editing and memory
6. Agent patterns: from single calls to orchestrators and agents
7. Evals and safety: measuring quality, versioning prompts, prompt injection, agent permissions, keys and data residency

Module 1: The API and SDKs

Every option below makes the same stateless API call. What changes is how much of the work around it your code does.

The stack

Each layer moves the line between your code and the platform. The split to remember: with the Client SDK your code runs the loop and the tools. With the Agent SDK, the SDK does.

The agent loop

At any layer, an agent is this loop: call the model, read stop_reason, act on it, call again.

• Append, never edit. Add the assistant turn exactly as returned, thinking blocks included, then one user message with every tool_result, matched by tool_use_id. To change the rules later, append a mid-conversation system message: editing system, tools or earlier turns misses the cache, and the API can reject the earlier thinking blocks with a 400.
• Read blocks by type. A reply’s content is a list of blocks (thinking, text, tool_use), and it can start with a thinking block. So content[0].text breaks: loop over content and keep the blocks whose type is "text".
• Cap the loop with a turn or token limit. The tool runner (beta) runs this loop for you, capped by max_iterations.
• Run independent tools in parallel. Claude can request several tools in one reply. Run them together and return every tool_result in one user message.
• Report tool failures, don’t crash. When a tool fails, return its tool_result with is_error: true and a short message. Claude can then retry or try another way.

Tools and MCP

A tool has three parts: a name, a description and an input_schema (JSON Schema). Set strict: true on the tool to guarantee that Claude’s inputs always match that schema, with no missing fields or wrong types.

Claude decides when to call a tool from its description, which the docs call “by far the most important factor in tool performance.”

• Be detailed. Cover what the tool does, when to use it and when not to, what each parameter means, and its limits.
• Make tools easy to tell apart. Group related actions into one tool with an action parameter, and prefix names by service, such as github_list_prs.

MCP (Model Context Protocol) is an open standard for plugging tool servers into an agent.

With many tools, tool search loads definitions on demand instead of filling the context. It’s on by default in the Agent SDK.

Extending an agent

Each extension point changes something different: what Claude knows, what it can reach, or what always happens.

Settings: who overrides whom

Claude Code and the Agent SDK read settings from up to five files, so the same key can be set in more than one place. The higher level wins.

Module 2: Delivery and reliability

Module 1 covered a single call. In production you also choose how replies arrive, and you plan for limits and failures. Pick the delivery mode by who is waiting.

Streaming

Streaming returns the reply as server-sent events, so users see text as it is generated. The events always arrive in the same order.

The SDK requires streaming when a request may run long. If you only need the final result, use messages.stream() with get_final_message().

Batching

When nobody is waiting, the Batch API runs requests asynchronously at half price.

Results can come back in any order. Give each request a unique custom_id and match results on it, never on position.

Rate limits

• On a 429, wait the seconds in retry-after. A 429 without it means the spend cap is reached, and retrying won’t help.
• Read the headers. anthropic-ratelimit-* show each limit, what’s left and when it resets.
• Limits are per organization and refill continuously (a token bucket), not once a minute. Workspaces can have lower limits of their own.
• Scale gradually. Limits rise with your usage tier, and a sudden spike can hit acceleration limits.

Errors: transient vs. permanent

• Back off with jitter. Retry transient errors only.
• Cap it. Limit both attempts and total time, and set max_retries=0 if you add your own loop.
• Degrade under load. Log the request-id, and under sustained 529s queue or shed work instead of hammering the API.

Module 3: Caching and costs

You pay per token, and output costs more than input. Prompt caching is the biggest single lever on input cost.

What is billed

Two traps: thinking is billed as output even when hidden, and newer models use a tokenizer that produces up to about 35% more tokens for the same text.

Prompt caching

Mark a cache_control breakpoint, and on the next call everything before it is served from cache.

• A hit needs an identical prefix. The API looks back up to 20 blocks from each breakpoint for a match.
• Short prompts fail silently. Below the minimum (512 tokens on the newest models, 1,024 to 4,096 on older ones) nothing is cached and no error is returned.
• Automatic mode (a top-level cache_control) moves the breakpoint forward as the conversation grows. It uses one of the 4 slots.
• A write costs more than no cache, so it pays off only if the prefix is read before it expires. Caching stacks with the batch discount.

What breaks the cache

The prefix runs tools, then system, then messages. A change invalidates its own level and every level after it.

Other levers

Measuring spend

Both cache fields at 0 on a repeated call means the prefix changed or is under the minimum.

Module 4: Prompt engineering

Write the prompt as a spec for a contractor who has never seen your codebase. If a colleague with no context would be confused, Claude will be too.

Anatomy of a request

A request has four places to put instructions, and each technique below has a natural home in one of them.

Techniques

Putting the question last can improve answers by up to 30% on long, multi-document inputs (Anthropic’s tests).

Structured outputs

Still validate before passing output downstream: a refusal or a max_tokens cutoff can leave output that doesn’t match the schema.

Don’t ask the model to write out its reasoning, in a field or in <thinking> tags: it can be declined with a reasoning_extraction refusal. Raise effort instead.

Module 5: Context engineering

Prompt engineering is what you say. Context engineering is what the model sees at each step. The window is limited working memory: every token costs on every turn, and quality drops as it fills.

The toolkit

Subagents

A subagent spends its own context and returns only a summary. That costs more tokens overall, so use one when keeping the main context clean is worth it.

Compaction and context editing

• Compaction is opt-in on the Messages API, and Anthropic’s recommended default for long conversations. In the Agent SDK and Claude Code it runs automatically, and /compact <focus> steers what’s kept.

• It loses detail, so anything that must survive goes in memory or CLAUDE.md.

• Context editing (beta) runs on the server, so your client keeps the full history.

Module 6: Agent patterns

Anthropic’s rule from Building effective agents: start with the simplest design, and add complexity only when evals show it helps.

The patterns

Each LLM box below is an augmented LLM: one model call with retrieval, tools and memory. Often that single call is enough.

What separates the patterns is who decides the steps. In the first five, the workflows, your code fixes the shape. In the agent loop, the model picks each step. Since any box can itself be an agent loop, the bottom row shows ways to coordinate several of them.

When a lead agent delegates, give each subagent a budget, an output schema and a clear handoff, and check outputs before passing them on.

Pipeline vs. graph

Draw any pattern as boxes and arrows and you get one of three shapes. In a pipeline or a static graph, your code fixes every step and branch before the run starts. In a dynamic graph, the model picks the next step while it runs, so you only see the full shape afterward.

Module 7: Evals and safety

A lead engineer has to answer two questions before shipping: how do we know it works, and what is the worst it can do?

Evals

Good criteria are specific, measurable, achievable and relevant (“accurate sentiment classification”, not “good performance”). Most systems need several: task fidelity, consistency, tone, privacy, latency and price.

Prefer many auto-graded cases over a few hand-graded ones, and include edge cases: ambiguous, overlong, irrelevant and harmful inputs. Re-run the set when you change the prompt, the model or effort.

For coding agents, ask for a general solution and for wrong tests to be reported, never hardcoded around.

Evals are one layer of testing. The code around the model needs the usual layers too.

To debug a change such as new refusals, start from the traces of the failing requests (input, system prompt, context, stop_reason), then compare them with past successes.

Versioning prompts

A prompt is code: it changes behavior, so it needs history, review and rollback. The Console Playground, which replaced the Workbench, doesn’t store prompts or versions, so your repository is the source of truth.

Roll a new version out gradually, behind a flag or a percentage, and keep the previous one ready. Expect a burst of cache writes after each deploy, since a changed prefix starts a new cache. On a model upgrade, adapt the prompt to the new model and re-run evals before switching. When a parameter is deprecated, add regression tests for its current behavior, then migrate call sites in batches validated against them, well before the removal date.

In CI, run Claude Code headless with claude --bare -p "..." --output-format json. --bare skips local hooks, plugins, MCP servers and CLAUDE.md, so every run is the same, and --allowedTools limits what the job can touch.

Prompt injection

The second question is what the worst case is. Jailbreaks and prompt injection try to make Claude ignore your instructions, and each source of attack needs its own defense.

For rules that must never break, filter Claude’s output in code before it reaches users. A prompt alone is not enforcement.

Agent SDK permissions

The last line of defense is what the agent is allowed to do. In the Agent SDK, every tool call passes these checks in order, and the first that decides wins:

Rules, modes and callbacks interact in ways that are easy to miss. allowed_tools pre-approves the tools you list but doesn’t restrict bypassPermissions, which still approves everything else. Calls approved by a mode or an allow rule never reach canUseTool, so put checks that must always run in a PreToolUse hook, and back hard limits with deny rules. Subagents inherit the parent’s mode, so a bypassPermissions parent hands every subagent full access. And a scoped deny such as Bash(rm *) only blocks calls written that way (/bin/rm gets through), while a bare name such as Bash in disallowed_tools removes the tool entirely. For a locked-down headless agent, pair allowed_tools with dontAsk.

Scope each hook with a matcher to the risky tools, such as Bash, Write or sensitive data access, so safe calls don’t pay for the check.

Permissions stop what the agent can do. In the prompt, also ask it to confirm before anything irreversible or shared, such as git push --force or dropping a table.

Keys and data residency

Give each environment (dev, staging, prod) its own API key, as recommended: a leaked key can then be revoked without stopping the others. Keep keys in a secret manager, never in code or prompts, and rotate them.

The Claude API can keep inference in the US (inference_geo: "us", at 1.1× the price) but has no EU option, and workspace data is stored in the US. If data must stay in the EU, call Claude through Amazon Bedrock or Google Cloud (Google managed) in an EU region, where the endpoint sets the region. Zero data retention is enabled per organization through Anthropic sales, and it doesn’t cover every feature: the Batch API, code execution and the Files API keep data.