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.
share
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,
/compactruns 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
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.
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.
- 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.