Chapter 7: Designing Claude Applications

1. Requirements and the Systems Life Cycle

A functional requirement is anything you can phrase as "the system shall…" — the observable behavior a stakeholder cares about. An infrastructure requirement is the operational scaffolding the user never sees but that decides whether the product survives production. Think of functional requirements as the restaurant menu and infrastructure requirements as the kitchen and plumbing: a great menu backed by a broken kitchen fails just as surely as a working kitchen with a menu nobody wants.

Solution architecture turns requirements into components, control flow, and integration patterns. Anthropic's "Building Effective Agents" guidance draws a sharp line: workflows use a predefined control flow (testable, predictable), while agents let the LLM dynamically decide the next step (flexible, suited to open-ended tasks). The core recommendation: start with workflows and graduate to agents only when the task genuinely requires dynamic routing or open-ended exploration.

Within the workflow family, five composable patterns combine like building blocks: prompt chaining, routing, parallelization, orchestrator–worker, and evaluator–optimizer. Overarching principles: keep it simple, build modularly, and make reasoning visible. Production guidance adds progressive disclosure, per-tenant system prompts with clear isolation, and connection pooling plus request queuing for traffic spikes.

The systems life cycle is the end-to-end sequence a Claude application moves through. Develop: choose the building block, define the output contract and tools, engineer prompts, design state, and budget tokens and rate limits here. Implement: wire auth via IdP, add input sanitization and injection defenses, red-team before go-live, establish CI/CD security. Operate: deploy behind rate-limit handling, retries with backoff, and pooling, with dual observability (traditional latency/error signals plus AI-specific quality signals). Maintain: monitor for injection and quality drift, track cost/ROI, manage model migration deliberately, and rotate/scope secrets.

2. Instruction Interpretation Across Interfaces

An interface is a distinct Claude surface — claude.ai and mobile, the Claude API, the Agent SDK, Claude Code, and Claude Cowork/Desktop — each with its own convention for where instructions live. On claude.ai, Anthropic automatically loads a full, date-stamped system prompt at the start of every conversation and layers organization and individual instructions on top. The Messages API gets none of that: the published claude.ai updates do not apply, the org/individual instructions live only inside claude.ai, and the API is stateless, so you must resend the full instruction set and history every request.

Claude Code ships its own extensive built-in prompt geared toward agentic coding, instructing Claude to weigh the "reversibility and blast radius" of every action. On the Agent SDK you opt into this with systemPrompt: { type: "preset", preset: "claude_code" } — but note the gotcha: the preset does not auto-load CLAUDE.md; you must set settingSources: ['project'] for those instructions to load.

The exam-relevant theme: safety guardrails are applied uniformly at the model level across all surfaces, but the system-prompt layer differs. A useful mental model is that claude.ai is a furnished apartment (lights, appliances, and house rules pre-installed) while the API is a bare shell where you supply every fixture yourself. Never assume a prototype that "just works" in claude.ai will behave identically on the API.

3. Content Boundaries and Schema Design

Content boundaries are the design decisions that separate trusted instructions from untrusted content. Claude is inherently resilient (Anthropic hardens it via RL that exposes it to injections during training), but application-level design is still required. Documented techniques: put untrusted content only in tool_result blocks (never in system or plain user text); label the content's nature and source; state an untrusted-content policy in the system prompt; JSON-encode third-party strings so escaping gives unambiguous delimiters; keep your own instructions out of tool results; apply least privilege; screen inputs and outputs with a lightweight model (e.g., Haiku 4.5) constrained to a boolean verdict; and red-team before deploying while monitoring continuously.

Think of it like a newsroom: the editor's standards (your system prompt) are trusted, and a tip that arrives in the mail (an untrusted tool result) might contain useful facts — but a professional newsroom reports on the tip; it never lets an anonymous letter rewrite editorial policy.

Schema design defines explicit, machine-checkable structures for inputs and outputs. On the output side, structured outputs constrain responses to a specific schema. JSON outputs control what Claude says; strict tool use (strict: true) validates how Claude calls your functions. The mechanism underneath is constrained decoding: the schema is compiled into a grammar that restricts token generation during inference — structurally stronger than just asking for valid JSON.

With additionalProperties: false and constrained decoding, an app can call JSON.parse with confidence and route on a field like category without defensive retry logic. Best practices: avoid recursive schemas, use additionalProperties: false, write descriptive field names/descriptions, set generous max_tokens buffers, and monitor stop_reason for refusals or truncation. Expect a small overhead (~50–200 tokens, ~2–3% cost at scale) — more than offset by eliminating retry code. A schema is a contract between Claude and the rest of the system, enforceable at generation time.

4. Session Hygiene and Plugins

Because the Messages API is stateless, sustaining a multi-turn conversation means resending the entire message array each turn, with user and assistant roles alternating and starting with user. Session hygiene is the discipline of keeping that accumulating state clean, relevant, and bounded — it matters because everything counts toward the context window. Capacity is not the whole story: as token count grows, accuracy and recall degrade, a phenomenon called context rot. The context window is a whiteboard, not a filing cabinet: once it fills, stale scribbles must be erased or you run out of room mid-thought.

The hygiene toolkit: server-side compaction (beta) summarizes earlier turns; context editing clears tool results and thinking blocks; context awareness and explicit task budgets help the model pace long tasks; and the token counting API estimates size before sending. Overflow before generation returns a 400 invalid_request_error; overflow during generation on 4.5+ models stops with stop_reason: "model_context_window_exceeded".

In Claude Code, plugins extend the tool with skills, agents, hooks, MCP servers, and LSP servers, and marketplaces are catalogs of plugins. Using one is two steps: add the marketplace (registers the catalog, installs nothing), then install individual plugins. The /plugin manager (Discover, Installed, Marketplaces, Errors) shows a context-cost estimate per plugin — a direct tie back to session hygiene. Install scopes are user, project, local, and managed. Security is central: plugins can execute arbitrary code with the user's privileges, so install only from trusted sources; organizations can restrict marketplaces via managed settings (strictKnownMarketplaces, extraKnownMarketplaces, pluginSuggestionMarketplaces).

Since the API is stateless, the developer owns the boundaries between sessions. Two practices prevent state leakage: per-tenant system prompts with clear isolation (so tenant A's history never shares a window with tenant B's), and session hygiene tooling (clearing tool results, compacting old turns, starting fresh message arrays). Statelessness is a gift here — nothing persists automatically, so leakage only happens if you carry it over.