Task statement 2.5 · Applications and integration

2.5 · Claude Application Design

In Shelfwise, the course example, the same model meets the team's instructions in claude.ai, in Claude Code and in the service, which sends its stock rules as its own system_prompt string with setting_sources=[], so no settings files are added. Designing the application means deciding what each channel carries, how the stock tool's schema reads, how long a conversation lives and which plugins the team shares.

Why it's tested

The usual shortcut is to tune a prompt in claude.ai until it behaves, then paste it into the service and expect the same answers. It fails because claude.ai added Anthropic's own system prompt to those test chats, and the service sends only the team's own prompt and tools.

Start hereThree terms this section adds

CLAUDE.md
A Markdown file of project instructions that Claude Code loads into every session as context. The Agent SDK loads it too when its setting sources include that file's level.
plugin
A directory that Claude Code installs and enables as one unit. It holds Skills, plus commands, agents, hooks and MCP servers. Each Skill is built around SKILL.md, a file of instructions Claude loads when relevant.
compaction
Replacing a conversation's history with a summary (1.3). In Claude Code, /compact runs it on demand.

KnowledgeWhat each interface adds before your instructions

Claude interprets an instruction alongside everything else in the request, and each interface puts its own instructions there before yours arrive. The claude.ai web interface and the mobile apps open every conversation with Anthropic's own system prompt, which gives the current date and encourages behaviours such as code in Markdown, and its release notes say these prompts do not apply to the Claude API. Claude Code sends its own system prompt with tool guidance and safety instructions, adds CLAUDE.md as a user message after it, and lets its permission mode decide which actions run without asking. CLAUDE.md is context rather than enforced configuration, so a rule that must always hold belongs in a Claude Code hook (1.2).

A Messages API request carries your system prompt and your messages, plus a short tool-use system prompt that the API builds from any tools you define, so behaviour you saw in claude.ai has to be written into your own system prompt. The Client SDKs for Python and TypeScript send exactly that request. The Agent SDK loads more: with no system prompt set it uses a minimal one that covers tool calling, the claude_code preset gives it the prompt Claude Code uses, and append adds your lines after it. Its settingSources option (setting_sources in Python) decides which settings files and CLAUDE.md files load, and when you omit it the SDK reads the same user, project and local settings and CLAUDE.md files as the CLI.

Interactive · what reaches Claude before your instruction

Four columns, one per interface, each listing what reaches Claude from top to bottom in request order. claude.ai or Desktop chat: Anthropic's system prompt, then your message. Claude Code: Claude Code's system prompt, then CLAUDE.md as a user message, then your prompt. Agent SDK: a minimal prompt or the claude_code preset with append, then CLAUDE.md if setting sources allow, then your prompt. Messages API: a tool-use prompt only if tools are set, then your system prompt, then your messages. claude.ai · Desktop Anthropic system prompt DATE, HOUSE BEHAVIOURS your message YOURS PROMPT PUBLISHED IN THE RELEASE NOTES Claude Code Claude Code prompt TOOL GUIDANCE, SAFETY CLAUDE.md AS A USER MESSAGE your prompt YOURS PERMISSION MODE DECIDES WHAT RUNS UNASKED Agent SDK minimal or claude_code PRESET, PLUS YOUR APPEND CLAUDE.md IF settingSources ALLOW your prompt YOURS NO systemPrompt SET: THE MINIMAL PROMPT Messages API tool-use prompt ONLY IF tools ARE SET your system prompt YOURS your messages YOURS CLIENT SDKS SEND THIS REQUEST AS IS Each column reads downward in request order.

Choose the interface the instruction is sent from.

claude.ai or a Desktop chat (the note below the diagram explains why Desktop's Chat tab counts here): Anthropic's system prompt opens the conversation, with the date and house behaviours, so your message is read alongside it. That prompt never reaches an API request.

Claude Code: its own system prompt comes first, CLAUDE.md follows as a user message, then your prompt. CLAUDE.md is context, not enforcement, and the permission mode decides what runs without asking.

Agent SDK: with no systemPrompt it sends a minimal prompt; the claude_code preset sends Claude Code's prompt, with append adding your lines. CLAUDE.md loads only from the setting sources that are enabled.

Messages API and the Client SDKs: only your system prompt and messages, plus a tool-use prompt the API builds when you define tools. Anything you relied on elsewhere has to be written in here.

Amber is added by the interface, blue is loaded from your project's files, green is what you wrote for this request. Your instruction always competes with everything above it in its column.

More precise than the guide. The guide names Desktop separately, but the docs publish the conversation system prompts for claude.ai and the mobile apps, and describe the Desktop app as Chat, Cowork and Code tabs, with Code running Claude Code on the CLI's settings files (as of 2026-10-04). No Anthropic page publishes a separate Desktop chat prompt, so the course treats the Chat tab as claude.ai. Exam answer: a Desktop chat starts with Anthropic's system prompt like claude.ai, Desktop's Code tab behaves like Claude Code, and the API adds only what you send.

KnowledgeContent boundaries keep data out of the instruction channel

A content boundary is the line between the instructions you trust and the content Claude should only read. The request has a channel for each: the system prompt for your application's instructions, the user turn for the person's request, and tool_result blocks for what tools bring back, such as a web page or a stock record. Inside a turn, XML tags such as <question> and <document> mark where each piece starts and ends, and the docs suggest JSON-encoding third-party strings so that a stray quote or tag cannot end the data early. Data pasted into the system prompt gains the authority of your instructions, while your own instruction placed inside a tool result may be ignored or flagged, because Claude treats tool-result content as untrusted. Prompt injection, an attack that hides instructions inside content, belongs to 7.1, AI Application Security. The design rule here is one channel for each kind of content, as one Shelfwise turn shows:

system:      stock rules # the team's instructions, cached
user:        Branch: Leeds · 3 Oct
             <question>Any 4 mm drill bits?</question>
tool_result: {"source": "stock_feed", "sku": "DB-4MM", "count": 12,
              "feed_time": "10:00"} # data only, never rules

KnowledgeSchema design: schemas are instructions too

A tool's input_schema and the schema for structured outputs, the JSON shape Claude's answer must follow, act as instructions as well as checks, because Claude reads every field name, description and enum value when it decides what to send. Mark a field required only when the source always holds its value. Under structured outputs or an extraction schema, a required field with no source value pushes Claude to fabricate one, because the output must include every required field. With a tool's input_schema, Claude can instead ask for the missing information before calling. A value that may be absent should be optional, or required but nullable ("type": ["string", "null"]), so that "no value" is an answer. Use an enum where the receiving code accepts a fixed set, and write each description as an instruction: what goes in the field and when to leave it empty. Keep schemas small and flat. With strict: true the API compiles the schema into a grammar and allows at most 20 strict tools, 24 optional parameters and 16 union-typed parameters per request, nullable type arrays included. 2.4 covers what strict guarantees.

SkillSession hygiene: when to resume, fork or start fresh

Session hygiene is choosing when a conversation goes on and when it ends. A session is the history that Claude Code and the Agent SDK save as an agent works: each prompt, tool call, tool result and response. Every turn resends that history, so a session that runs too long costs more per request, fills the context window and keeps old tool results that read as current. In the Agent SDK, resume continues the session whose ID you pass. continue_conversation=True (continue: true in TypeScript) picks the most recent session in the directory, which suits an app that runs one conversation at a time. fork_session=True copies a history into a new session ID and leaves the original unchanged. A session stores the conversation, not the files: forking does not branch or revert file changes, and resuming does not refresh old tool results. In Claude Code, /clear starts an empty context and saves the old conversation for /resume, /compact replaces the history with a summary, and /branch or --fork-session copies it. The docs advise /clear between unrelated tasks and after two failed corrections. Section 6.1 covers compaction in depth. An early Shelfwise build shows a session that never ended:

# symptom: Saturday 15:10, Leeds asks "Any 4 mm drill bits?"
answer "12 in stock" (the 09:40 count from another chat, no lookup)
request input ≈52,000 tokens; every afternoon answer over the $0.01 ceiling
# cause: continue_conversation=True put every chat in the most recent session
fix: new chat → new session; store its session_id; follow-up → resume=chat.session_id
outcome: ≈7,000 input tokens on a chat's first request, each count from its own lookup

A multi-user service needs one session per chat, tracked by ID, not one conversation for the whole day.

KnowledgePlugin management

A plugin's Skills run under its name, as /plugin-name:skill. Plugins come from marketplaces, catalogues you add once with /plugin marketplace add, and Anthropic's official claude-plugins-official is added for you. The scope you install at decides which settings file lists the plugin under enabledPlugins. User scope uses ~/.claude/settings.json, the settings file in your home directory, and applies to you in every project. Project scope uses the committed .claude/settings.json and applies to everyone in the repository. Local scope uses .claude/settings.local.json and applies to you in that repository only. Committing a project-scope entry turns the plugin on for colleagues without downloading it, so each colleague installs it once. Anyone who wants it off sets it to false in .claude/settings.local.json, which wins over the project file (2.6 covers how settings files combine). An enabled plugin's descriptions sit in context on every turn and its hooks run as you, so disable what nobody uses. Plugin dependencies belong to 2.6 and writing plugins to 8.3.

Before the next request, ask: does it continue the same conversation, with the same goal and facts that are still current? Yes → resume that session by its ID, and fork it if you want to try a second approach. No → start a new session, carrying over only a short summary if anything.
Takeaway
  • claude.ai chats start with Anthropic's system prompt, and Claude Code with its own plus CLAUDE.md; the API carries only what you send.
  • Instructions go in the system prompt, the person's request in the user turn and third-party content in tool results, each delimited.
  • Project scope turns a plugin on for the whole repository; local scope lets one person turn it off.

check yourself

0 / 4 answered

A team's TypeScript Agent SDK script reviews pull requests in CI. It passes systemPrompt: "Flag any SQL built by string concatenation." and nothing else. On the same diffs, claude -p followed Claude Code's tool guidance and safety checks, but the script's reviews skip them and only look for SQL.Which change restores Claude Code's own system prompt while keeping the team's SQL rule?

Select one.

A legal-research agent fetches court rulings with a get_ruling tool. To keep summaries consistent, the tool appends "Summarise in three bullets and cite paragraph numbers" to the end of every tool_result. Claude follows that line only some of the time, and twice it warned the user that a ruling "contains embedded instructions".What is the most likely root cause?

Select one.

A retailer's Python Agent SDK agent spent 45 turns profiling a messy customer table, and that analysis is still current. The team now wants two cleaning plans drafted from that point, one deleting duplicates and one merging them. Each plan must see the full profiling history but none of the other plan's turns, and the profiling session must stay unchanged.Which approach best meets all three requirements?

Select one.

A data-platform team publishes a sql-lint plugin in its private marketplace. It should be on for everyone who works in the warehouse repository and in no other repository. One analyst finds its hooks slow and wants it off on her own machine, without changing anything for the rest of the team.Which TWO steps best meet both needs?

Select two.

sources

  1. Claude Platform Docs, "System prompts" (release notes): claude.ai and the mobile apps use a system prompt that gives the current date and encourages behaviours such as Markdown code; these updates do not apply to the Claude API. Checked 2026-10-04.
  2. Claude Code Docs, "Desktop application": the Chat, Cowork and Code tabs; the desktop app reads the same settings files as the CLI; permission modes. Checked 2026-10-04.
  3. Claude Code Docs, "How Claude remembers your project": CLAUDE.md is delivered as a user message after the system prompt; context, not enforced configuration; vague or conflicting instructions; a hook to block an action. Checked 2026-10-04.
  4. Claude Code Docs, "Modifying system prompts": the minimal default, the claude_code preset with append, a custom string sends only what you provide; CLAUDE.md loads through setting sources. And "Use Claude Code features in the SDK": omitting settingSources reads the CLI's user, project and local settings; [] turns them off. Checked 2026-10-04.
  5. Claude Platform Docs, "Define tools": the API constructs a tool-use system prompt from tool definitions and your system prompt; detailed descriptions; enum; required and optional parameters. Checked 2026-10-04.
  6. Claude Platform Docs, "Prompting best practices": XML tags separate instructions, context and variable inputs. And "Mitigate jailbreaks and prompt injections": untrusted content only in tool results, never in system prompts; JSON-encode third-party strings; don't put your own instructions in tool results. Checked 2026-10-04.
  7. Claude Platform Docs, "Structured outputs": schemas compile into a grammar that guarantees field types and required fields; limits of 20 strict tools, 24 optional parameters and 16 union-typed parameters per request; reduce optional parameters and flatten nesting. Checked 2026-10-04.
  8. Claude Code Docs, "Work with sessions" (Agent SDK): what a session stores; continue, resume and fork; one session per user needs resume by ID; sessions persist the conversation, not the filesystem. Checked 2026-10-04.
  9. Claude Code Docs, "Manage sessions" and "Best practices for Claude Code": /clear saves the previous conversation for /resume; /compact; /branch and --fork-session; clear between unrelated tasks and after two failed corrections. Checked 2026-10-04.
  10. Claude Code Docs, "Plugins overview", "Install and manage plugins" and "Plugin loading reference": plugin components and /plugin-name:skill; marketplaces and claude-plugins-official; user, project and local scopes and their settings files; project scope does not download the plugin; local overrides project; per-turn context cost. Checked 2026-10-04.
  11. The point that a required field with no source invites a fabricated value is course framing, carried from the Architect Foundations course (a different exam's guide), not a sourced claim. Shelfwise's empty setting_sources, its stock record, the early build's continue_conversation bug, its 52,000-token requests and the 09:40 count are this course's example details.