Skip to main content

2.5 Claude application design

The heaviest skill on the exam (8.6%). It is about where a piece of behaviour belongs.

How instructions reach Claude, per interface​

InterfaceInstruction channelsLoaded whenShared with the team?
Claude API / SDKssystem parameter; messages; tool descriptions; output_config; mid-conversation system messagesEvery request, because the API is statelessOnly through your code
Claude CodeCLAUDE.md hierarchy, .claude/rules/, settings.json, skills, slash commands, subagent definitions, hooksCLAUDE.md always; rules on matching paths; skills and commands on invocationYes, when the files are committed
Claude Agent SDKOptions object (system prompt, allowed tools, agents, hooks, MCP servers) plus the same file-based configPer query, per sessionThrough the repo
Claude Desktop / claude.aiProject instructions, per-conversation context, connected MCP serversPer project or conversationOnly within the workspace/project
The channel decides the guarantee

The same sentence has different force in different channels. In a system prompt it is a strong prior. In CLAUDE.md it is a strong prior that costs tokens on every session. In a tool description it steers selection. In a hook it is an enforced invariant. When an item says "must always", the answer is the enforced channel — not the most emphatic wording.

Where to put a rule​

The rulePut it
Applies to every request of this applicationsystem prompt (cached prefix)
Applies to everyone working in this repoProject CLAUDE.md, committed
Applies only under src/api/**.claude/rules/ with a path glob
Applies only to one recurring taskA skill or slash command, loaded on demand
Describes when to use a capabilityThe tool's description
Must hold every time, with no exceptionA hook or a server-side check
Is a per-request detailThe user message, after the cache breakpoint
Is an operator instruction arriving mid-conversationA mid-conversation system message in messages

Content boundaries​

Every application has a boundary between instructions you authored and data that arrived from elsewhere. Design it explicitly.

ZoneContentsAuthority
Trusted instructionsSystem prompt, tool descriptions, hook logicMay direct behaviour
Semi-trustedAuthenticated user messagesMay request actions within that user's permissions
Untrusted dataRetrieved documents, web pages, tool output from third parties, file uploads, other users' contentData only. Never authority

Mechanics that implement the boundary:

  • Delimit and label untrusted content — an XML-ish tag with a name, and a statement that its contents are data to analyse, not instructions to follow.
  • Never concatenate untrusted text into the system prompt.
  • Scope the tools available on a turn that processes untrusted content to read-only ones.
  • Gate the sensitive action on your side, so an injected instruction has nothing to reach (7.1).
  • Do not echo untrusted content back into a privileged channel (a CLAUDE.md, a stored system prompt, a memory file) without review.

Schema design​

Schemas appear in three places — tool inputs, structured outputs, and your own persistence layer — and the same design rules apply.

RuleWhy
One purpose per tool, one meaning per fieldOverloaded fields force the model to guess
Describe every fieldThe description is the model's only spec; a bare "type": "string" invites format drift
Constrain with enum where the value set is closedRemoves a whole class of invalid output
Make absence representableNullable or optional fields, so "not present in the document" is expressible without invention
required only what is truly requiredOver-required schemas convert unknowns into hallucinations
additionalProperties: false plus strict: trueGuarantees validated tool input
Flat over deepDeep nesting raises error rates and token cost
Version the schemaDownstream consumers need to know which shape they got
Carry provenanceSource, page, confidence, or a flag — so the consumer can decide, not guess

Session hygiene​

The API is stateless, so a "session" is whatever your code keeps. Poor hygiene shows up as cost, latency, and drift.

PracticeDetail
Bound the historyA turn limit, a token budget, or compaction — history grows the bill on every turn
Prune tool output before appendingKeep the fields that matter; drop the payload
Keep the cacheable prefix stableNo timestamps, request IDs, or reshuffled tool lists inside it
Externalise durable factsA memory store or scratchpad file, not reliance on the transcript surviving
Reset deliberatelyA new task gets a new session rather than inheriting an unrelated 60-turn context
Isolate per userOne session per authenticated user; never share a conversation across identities
Separate concerns across sessionsTwo unrelated tasks in one context interfere with each other

In Claude Code the same hygiene is expressed with /clear, /compact, resuming a specific session, and delegating verbose exploration to a subagent.

Plugin management​

Plugins package configuration — commands, skills, subagents, hooks, and MCP server definitions — so a team installs one thing instead of copying files.

ConcernPractice
SourceInstall from a known marketplace or repository; review what the plugin's hooks and MCP servers can do before enabling
ScopeProject-level for team-wide capability; user-level for personal preference
PinningPin a version; an auto-updating plugin changes behaviour without a deploy
DependenciesRecord which MCP servers, binaries, and environment variables a plugin needs (2.6)
Least privilegeA plugin's tools and hooks inherit real power — audit allowed-tools and any command it can run
ConflictsTwo plugins defining the same command name, or overlapping tool names, need explicit resolution

Quiz​

  1. Question 1

    A coding convention must apply to every developer on a repository from the moment they pull, and must not depend on anyone configuring their machine. Where does it belong?

  2. Question 2

    An extraction schema marks all 14 fields required, with no nullable types. Invoices that genuinely lack a field come back with plausible invented values. Which schema change removes the pressure to invent?

  3. Question 3

    A support agent summarises ticket attachments written by third parties. Which design does the most to stop instructions embedded in an attachment from being acted on?