What you will be able to do
- Explain why an instruction that works on one Claude surface (Claude Code, the Agent SDK, the Messages API) is ignored on another, and move it to where that surface reads it
- Pick a conversation-state design (a resent history, a beta message thread, or an Agent SDK continue, resume or fork) that fits a stated requirement
- Identify what content leaves the application on each request, and what the API keeps afterwards
- Choose between JSON outputs, strict tool use and prompting alone for a schema requirement, and check model IDs and feature availability before building on a cloud platform
Key concept
The request is the boundary — Claude only sees what the request carries. On the Messages API that means your system prompt, your tool definitions and the messages you send. On Claude Code and the Agent SDK it also includes whatever files that runtime is configured to load. Every design question in this lesson comes down to which content crosses into the request, and who puts it there.
1.Where each surface gets its instructions
The same model reads instructions from different places depending on the surface that calls it. On the Messages API the instructions come from what the request carries. When you pass tools, the API builds one system prompt from the tool definitions, the tool configuration and the system text you supplied. Nothing outside the request reaches the model: no repository files, no editor state, no settings folder.
Claude Code is a runtime that reads a project from disk. A repository's CLAUDE.md, its .claude/settings.json and its rules files are things Claude Code loads, not things the model knows about. Suppose a team tunes prompts in Claude Code while CLAUDE.md says to format ticket references as TCK-<number>. They then send the same user prompts from a backend through the Messages API, and the rule has disappeared. Nothing is wrong with the model: the rule just never crossed into the request. Put the rule into the system parameter itself. Passing a file path there doesn't help, because the API reads the text it receives, not files that text names.
State the rule in full when you move it. A model reading a bare system prompt has no other context to fall back on, so the prompt should spell out the format and, ideally, why it matters. A one-sentence role in system already shifts behaviour and tone.
The Agent SDK sits between these two. It can load Claude Code's filesystem configuration, but only from the sources listed in its settingSources option. The project source loads the project settings.json and hooks, the project CLAUDE.md and .claude/rules/*.md, and project skills, commands and subagents. Paths are resolved from the working directory. Settings and hooks come from <cwd>/.claude/, and CLAUDE.md and rules from <cwd> and each of its parent directories. The user source reads from ~/.claude/, which is a separate scope that a server has no reason to copy from a laptop.
| settingSources value | What it loads | Where it looks |
|---|---|---|
| project | Project settings.json and hooks; project CLAUDE.md and .claude/rules/*.md; project skills, commands, subagents | <cwd>/.claude/ for settings and hooks; <cwd> and every parent directory for CLAUDE.md and rules |
| user | User settings.json; user CLAUDE.md and ~/.claude/rules/*.md; user skills, commands, subagents | ~/.claude/ |
| local | CLAUDE.local.md, .claude/settings.local.json | <cwd>/.claude/ for settings.local.json; <cwd> and every parent directory for CLAUDE.local.md |
Here is how that plays out in production. A project behaves correctly on developers' laptops, but the deployed Agent SDK service ignores both the repository's CLAUDE.md and its .claude/settings.json. Mounting the files somewhere isn't enough, and neither is pointing cwd at them: those files are only read when a source that covers them is enabled. A full fix has two parts. Include project in settingSources, and run the service with the repository checkout as its working directory so the lookup paths resolve.
Checkpoint 1 of 9· Check yourself
A team tunes prompts in Claude Code, where the repository's CLAUDE.md says to write ticket references as TCK-<number>. Their backend sends the same user prompts, with tools, straight to the Messages API, and the ticket format is gone from the replies. What fixes this?
The Messages API builds its system prompt only from what the request carries: tool definitions, tool configuration and your system text. CLAUDE.md is loaded by Claude Code, so the rule has to go into system as text. A file path or a file sitting on disk never reaches the model.
“the API constructs a special system prompt from the tool definitions, tool configuration, and any user-specified system prompt”Source: platform.claude.com
Checkpoint 2 of 9· Exam question
A team tuned its prompts in Claude Code, where the repository's CLAUDE.md says to always format ticket references as TCK-<number>. Their new backend calls the Messages API with the same user prompts, and the format rule is ignored. What explains this, and what fixes it?
Correct answer: A — CLAUDE.md is a Claude Code feature that API requests do not carry along; the backend should place the ticket rule in the system parameter.
- A. Correct. CLAUDE.md is loaded by Claude Code as project context, and a Messages API request contains only what the application sends. The rule therefore has to be written into the request, typically in the
systemparameter. - B. Incorrect.
temperatureis a real parameter, but it only controls randomness. The formatting rule never reaches the model in the backend's requests, so lowering temperature cannot make the model follow an instruction it was never given. - C. Incorrect. Prefilling the assistant turn is a real technique, but it only fixes how the reply begins, not ticket references that appear later in the text. Claude Code does not enforce the format by post-processing replies; the rule is simply missing from the backend's requests.
- D. Incorrect. The API has no mechanism that loads instruction files from referenced paths and cannot open files at all. A path string in
systemgives the model no rule text, so the rule's content has to be included in the request.
Checkpoint 3 of 9· Exam question
A service built on the Agent SDK uses default options. On developers' laptops the same project behaves according to the repo's CLAUDE.md and .claude/settings.json, but the deployed service ignores both. What is the best fix?
Correct answer: C — Include project in the SDK's settingSources option, and deploy the repo checkout to the server as the directory the service runs in.
- A. Incorrect. The
claude_codepreset only changes the system prompt. CLAUDE.md and.claude/settings.jsonare read through setting sources, which default options do not enable, so shipping the file changes nothing. - B. Incorrect. The user-level folder is a separate source, and with default options the SDK loads no filesystem settings from any source. The project's CLAUDE.md and settings.json do not depend on it, so the service still ignores them.
- C. Correct. Default SDK options load no filesystem settings, so the project source must be enabled through
settingSources. The repo's CLAUDE.md and.claudefolder must also be present in the directory where the agent runs. - D. Incorrect. Pointing
cwdat the checkout and mounting the files puts them in the right place, but with default options the SDK still does not read them. Without enabling the project setting source, both files stay ignored.
2.Conversation state and session decisions
The Messages API remembers nothing between calls, so the client owns conversation state. Each request carries every earlier user and assistant turn in messages, followed by the new user turn. Since the client controls the history, earlier turns don't have to be real model output. An application can insert synthetic assistant messages. Leaving the system prompt unchanged doesn't keep history alive, and neither API keys nor time windows do.
message = anthropic.Anthropic().messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=[
{"role": "user", "content": "Hello, Claude"},
{"role": "assistant", "content": "Hello!"},
{"role": "user", "content": "Can you describe LLMs to me?"},
],
)
print(message)Two features change this default, and each has its own conditions. Message threads, a beta feature, let the API keep the conversation so later requests send only new messages. A thread expires five minutes after its last request, though, so a user who comes back after lunch needs a design that can rebuild the history. Mid-conversation system messages, with role: system placed right after a user turn, add an instruction partway through a conversation. They carry the same authority as the top-level system field. Their placement matters because of prompt caching: the API can cache the unchanged opening part of a request (its prefix) so that later requests reuse it, and editing anything earlier in the request invalidates that cache. A message appended at the end changes nothing before it, so earlier cached prefixes stay valid. They work only on the models listed for the feature, and the message can't be the first entry in messages.
The Agent SDK handles state differently. It saves session history and offers three ways back into it. Continue picks up the most recent session in the current directory, which works when the application runs one conversation at a time. Resume takes a specific session ID, which the application has to track. You need resume once there are several sessions, such as one per user. Fork branches from an existing session into a new ID and leaves the original unchanged.
| Requirement | Mechanism | Constraint to check |
|---|---|---|
| Single prompt, no follow-up | One query() call | None |
| Multi-turn chat in one process | ClaudeSDKClient (Python) or continue: true (TypeScript) | One conversation at a time |
| Return to one specific past session, e.g. one per user | Capture session_id and pass it to resume | Session file must exist on the current machine |
| Try an alternative without losing the original | resume plus fork_session=True | Fork gets its own ID, distinct from the original |
| Nothing written to disk | persistSession: false (TypeScript only); CLAUDE_CODE_SKIP_PROMPT_HISTORY in Python | Session lives in memory for the call only |
How you key sessions decides who can see whose history. If a support portal keeps one session ID per chat room and lets different customers join that room, it hands every customer the same transcript. The session key has to follow the privacy boundary the requirement sets, which usually means one session per user. Sessions are also bound to one machine. A service spread across several hosts can't resume a session whose file lives on another host's disk.
Checkpoint 4 of 9· Match them up
Match each Agent SDK session mechanism to the requirement it fits.
Tap a term, then the definition that fits it.
Continue needs no ID but only finds the most recent session in the directory. Once there are several sessions, such as one per user, the app must track IDs and use resume. Fork gives the branch its own ID, and persistSession: false keeps the session out of disk storage.
“Resume takes a specific session ID. You track the ID. Required when you have multiple sessions (for example, one per user in a multi-user app)”Source: code.claude.com
Checkpoint 5 of 9· Check yourself
A chat feature uses the beta message threads so each request sends only new messages. A user leaves for lunch and comes back 90 minutes later to carry on the same conversation. What does the design need?
A message thread expires five minutes after its last request, so after a long gap the API no longer holds the conversation. The client has to be able to rebuild the history and send it in full. An unchanged system prompt doesn't keep history alive, and a mid-conversation system message only adds an instruction.
“A thread expires 5 minutes after its last request and is deleted no more than 1 hour after its last use.”Source: platform.claude.com
Checkpoint 6 of 9· Exam question
Which statement correctly describes how conversation state works when an application calls the Messages API?
Correct answer: B — The API keeps no memory between calls, so the client includes earlier user and assistant turns in the messages array on each request.
- A. Incorrect. The Messages API returns no conversation ID and has no server-side conversation object to refer back to. A request carrying only the newest user message is treated as a fresh conversation with no prior context.
- B. Correct. The Messages API is stateless, so nothing carries over between calls. Continuity exists only because the client sends the earlier user and assistant turns in
messageson each request. - C. Incorrect. The API does not retain recent turns per key, so there is no retention period to wait out. Prompt caching only reduces the cost of a prefix that is still sent, and the client must include the history in each request.
- D. Incorrect. The
systemparameter is instruction text sent with a single request and is neither stored nor used as memory. Earlier turns must be included inmessageswhether or not the system prompt changes.
3.What leaves the application, and what stays behind
Everything you put in a request becomes prompt content, including content that looks like configuration. Tool definitions go into the system prompt the API builds. So do input_examples: optional sample tool inputs attached to a tool definition to show Claude how to call it. They are sent with the tool schema and cost prompt tokens, about 20–50 tokens for a simple example and 100–200 for a complex nested one. So a large tool catalogue is paid for on every call, and whatever it contains is visible to the model. Writing tool descriptions well is covered in tool design.
Different parts of a request are kept for different lengths of time. Strict tool use and JSON outputs (both defined in the next section) share one grammar pipeline: the API compiles your schema into a grammar that constrains which tokens the model may generate, and it caches that compiled grammar, apart from message content, for up to 24 hours after its last use. Prompts and responses aren't kept past the API response. The design rule follows directly: put sensitive values in messages, never in schemas. Patient names don't belong in an enum, case identifiers don't belong in a const, and personal data doesn't belong in a pattern regex. Schemas built at runtime from user records are the risky case, because they quietly move user data into the cached part of the request.
Checkpoint 7 of 9· Match them up
You are reviewing what a request sends to the API. Pair each part of the request with how the API handles it once it leaves the application.
Tap a term, then the definition that fits it.
Each part of a request is retained differently. Message content isn't kept after the response, but the compiled schema is cached for up to 24 hours, so user data must never feed into schemas. Tool definitions and input_examples become prompt content, so you pay for them on every call and the model can see them.
“Tool schemas are temporarily cached for up to 24 hours since last use. Prompts and responses are not retained beyond the API response.”Source: platform.claude.com
4.Choosing a schema mechanism against the requirement
A requirement that downstream code must be able to parse every reply calls for a guarantee, not a prompt. Even a carefully prompted model can return malformed JSON, leave out required fields or use the wrong types. Two features remove that risk with constrained decoding: while Claude generates, it can only produce tokens that the compiled schema allows, so field types and required fields cannot come out wrong. JSON outputs (output_config.format with type: "json_schema") constrain Claude's reply, which arrives as JSON in a text content block. Strict tool use (strict: true on a tool definition) constrains tool names and tool inputs. For example, a booking tool that declares passengers as an integer always receives 2, never "two" or "2". You can use either feature on its own or both in the same request.
| Requirement | Mechanism | What it guarantees |
|---|---|---|
| Claude's reply must be parseable JSON in a known shape | output_config.format (JSON outputs) | Valid JSON matching the schema, in the text content block |
| Your functions must receive correctly typed arguments | strict: true on the tool | Tool input follows input_schema; tool name is always valid |
| Format should usually match, failures tolerable | Prompting alone | No guarantee; expect parse errors and retries |
Neither guarantee covers every tool or every schema feature. The computer use and browser use toolsets reject strict: true outright. The schema language is a subset of JSON Schema. SDK helpers handle unsupported constraints such as minimum by removing them from the schema Claude sees, noting them in the field description, and then checking the response against your original schema in your own code. Because the grammar is built from the simplified schema, decoding never enforces the removed constraint. It holds only if your code validates it. A Pydantic dict field shows another limit. The helpers add additionalProperties: false to every object, so an object with no declared properties can contain no keys at all, and Claude can return only {} for the dict field. When you know the field's keys, declare them in a nested Pydantic model instead of a dict. Parsing and validation details are covered in structured output and defensive parsing.
Checkpoint 8 of 9· Check yourself
An extraction model declares quantity as an integer with minimum: 1 and is sent with JSON outputs through an SDK helper. When the reply comes back, what is actually enforcing the minimum?
SDK helpers strip unsupported constraints such as minimum from the schema Claude receives and add them to the field description instead. Decoding then guarantees only the integer type, and the minimum holds only because the helper validates the response against your original schema in your own code.
“Claude receives a simplified schema, but a helper that validates responses still enforces every constraint in your code.”Source: platform.claude.com
5.Model IDs and feature availability across platforms
Moving to a cloud platform changes the strings you send as well as the endpoint you call. Each Claude model ID pins one model version, but the ID's format depends on the platform. The first-party API uses claude-{name}-{major}[-{minor}], for example claude-opus-5. Amazon Bedrock adds a prefix, as in anthropic.claude-opus-5. On Bedrock's bedrock-runtime endpoint, models served through cross-region inference need an inference profile ID such as global.anthropic.claude-fable-5-2. If code hard-codes first-party IDs, it breaks when it's deployed to Bedrock.
Cross-region inference means AWS serves a model through profiles that can route requests across regions, instead of offering it as on-demand throughput in one region. An inference profile ID is the base model ID with a prefix such as global. or us.. A request that passes the base ID for such a model fails with an HTTP 400 error telling you to retry with the ID or ARN of an inference profile, and the models that need the profile form include Claude Fable 5.2 and Claude Mythos 5.2. Which prefixes a model accepts varies, so check the model's row in the Bedrock table before choosing one.
| Surface | ID format | Example |
|---|---|---|
| Claude API | claude-{name}-{major}[-{minor}] | claude-opus-5 |
| Amazon Bedrock | anthropic.claude-{name}-{major}[-{minor}] | anthropic.claude-opus-5 |
| Bedrock bedrock-runtime, cross-region models | Inference profile prefix plus base ID | global.anthropic.claude-fable-5-2 |
Feature availability is checked per feature and per model. Mid-conversation system messages work only on a named list of models. Message threads are in beta. Structured outputs list their supported platforms explicitly: Claude API, Amazon Bedrock, Claude Platform on AWS, Claude Models on Google Cloud, and Microsoft Foundry. So if compliance requires the application to run on a particular cloud offering, confirm before committing that every feature the design depends on is listed for that platform and model. Pinning model IDs per environment is covered in configuration and SDLC integration.
Checkpoint 9 of 9· Check yourself
Compliance requires an application to run on Microsoft Foundry. Its design depends on JSON outputs and on mid-conversation system messages. What should the team confirm before committing to this design?
Availability is checked separately for each feature and each model. Structured outputs names the platforms it supports. Mid-conversation system messages work only on the models named for that feature. Equal authority with the top-level system field says nothing about which models support the feature.
“This works on Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1, Claude Mythos 5.1”Source: platform.claude.com
Sources
(9)
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.
“the API constructs a special system prompt from the tool definitions, tool configuration, and any user-specified system prompt”
↩︎ Where each surface gets its instructions“Examples are included in the prompt alongside your tool schema”
↩︎ What leaves the application, and what stays behind“An array of example input objects that show Claude how to use the tool.”
↩︎ What leaves the application, and what stays behind“the API constructs a special system prompt from the tool definitions, tool configuration, and any user-specified system prompt”
↩︎ Key concept - 2.
“<cwd>/.claude/ for settings.json and hooks; <cwd> and every parent directory for CLAUDE.md and rules”
↩︎ Where each surface gets its instructions“Project settings.json and hooks; project CLAUDE.md and .claude/rules/*.md”
↩︎ Exam trap 1 - 3.https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practicesOfficial docs
“Setting a role in the system prompt focuses Claude’s behavior and tone for your use case.”
↩︎ Where each surface gets its instructions - 4.
“The Messages API is stateless, which means that you always send the full conversational history to the API.”
↩︎ Conversation state and session decisions“A mid-conversation system message has the same authority as the top-level system field”
↩︎ Conversation state and session decisions“it does not invalidate any cached prefix that came before it”
↩︎ Conversation state and session decisions“A thread expires 5 minutes after its last request and is deleted no more than 1 hour after its last use.”
↩︎ Exam trap 2“A thread expires 5 minutes after its last request and is deleted no more than 1 hour after its last use.”
↩︎ Checkpoint“This works on Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1, Claude Mythos 5.1”
↩︎ Checkpoint - 5.https://code.claude.com/docs/en/agent-sdk/sessionsOfficial docs
“Required when you have multiple sessions (for example, one per user in a multi-user app)”
↩︎ Conversation state and session decisions“Same machine only: the session file still needs to exist on the current machine.”
↩︎ Conversation state and session decisions“Resume takes a specific session ID. You track the ID. Required when you have multiple sessions (for example, one per user in a multi-user app)”
↩︎ Checkpoint - 6.
“Strict tool use compiles tool input_schema definitions into grammars using the same pipeline as structured outputs.”
↩︎ What leaves the application, and what stays behind“Your prompts and Claude’s outputs are not stored. Only the JSON schema is cached, for up to 24 hours since last use.”
↩︎ What leaves the application, and what stays behind“Setting strict: true on a tool definition guarantees Claude’s tool inputs match your JSON Schema”
↩︎ Choosing a schema mechanism against the requirement“constraining the model’s token sampling to schema-valid outputs”
↩︎ Choosing a schema mechanism against the requirement“Tool schemas are temporarily cached for up to 24 hours since last use. Prompts and responses are not retained beyond the API response.”
↩︎ Exam trap 3“Do not include PHI in input_schema property names, enum values, const values, or pattern regular expressions.”
↩︎ Prediction“Tool schemas are temporarily cached for up to 24 hours since last use. Prompts and responses are not retained beyond the API response.”
↩︎ Checkpoint - 7.
“Structured outputs guarantee schema-compliant responses through constrained decoding”
↩︎ Choosing a schema mechanism against the requirement“The SDK sends a dict field as an object with empty properties, so Claude can only return {} for it.”
↩︎ Choosing a schema mechanism against the requirement“Add additionalProperties: false to all objects”
↩︎ Choosing a schema mechanism against the requirement“Claude receives a simplified schema, but a helper that validates responses still enforces every constraint in your code.”
↩︎ Choosing a schema mechanism against the requirement - 8.
“Each Claude model ID identifies a pinned version of the model.”
↩︎ Model IDs and feature availability across platforms“On Amazon Bedrock, the corresponding format is:”
↩︎ Model IDs and feature availability across platforms“take an inference profile ID: the base model ID with a prefix such as global. or us., for example global.anthropic.claude-fable-5-2”
↩︎ Exam trap 4 - 9.
“AWS offers newer Claude models through cross-region inference rather than on-demand throughput.”
↩︎ Model IDs and feature availability across platforms“The inference profile ID is the base model ID with a prefix from a column marked “Yes” in the following table”
↩︎ Model IDs and feature availability across platforms