Claude application design: surfaces, instruction placement and output schemas

1.Same prompt, different surface: CLI versus Agent SDK

What Claude does with a request depends on what surrounds the request. In an interactive Claude Code session, your CLAUDE.md files, auto memory, MCP tool names and skill descriptions are all in context before you type anything, on top of Claude Code's own system prompt. If you move a workflow from claude -p into a service built on the Agent SDK, the prompt text stays the same, but the instructions around it can change without any warning.

The system prompt is the first thing to check. In the TypeScript reference, the default for systemPrompt is undefined (minimal prompt). If a headless agent loses the CLI's behaviour after a port, it is usually missing one option: { type: 'preset', preset: 'claude_code' } (system_prompt in Python). Put your own additions in the preset's append field. That extends Claude Code's prompt instead of replacing it. If you pass a plain string, it becomes a custom prompt and the preset is not used.

The SDK gives you three ways to fill the system prompt, and each suits a different product. The preset, with or without append, fits a coding tool where a human watches and steers. A custom string fits an agent with a different identity, surface or permission model, such as a support bot; the SDK sends only what you provide, so you must supply any tool guidance and safety instructions it still needs. Leaving systemPrompt out gives a thin tool-calling loop in which all behaviour travels in the user prompt.

    # AFTER (v0.1.0) - Uses minimal system prompt by default
    # To get the old behavior, explicitly request Claude Code's preset:
    async for message in query(
        prompt="Hello",
        options=ClaudeAgentOptions(
            system_prompt={"type": "preset", "preset": "claude_code"}  # Use the preset
        ),
    ):
        print(message)

Filesystem instructions are controlled by a separate option, settingSources. It decides which of the user, project and local sources load, along with the CLAUDE.md files, rules, skills, subagents and settings each source carries. If you leave it unset, it follows the CLI defaults and loads all sources. Passing [] turns off user, project and local settings, but endpoint-managed policy still loads. The two options cause different symptoms. Without the preset, Claude behaves differently. With a narrowed settingSources, your team's written conventions never arrive. When a port goes wrong, check both.

Claude Code sessions are not limited to the terminal, and the surface you see is not always the place the session runs. The Desktop app and the VS Code extension are further surfaces for Claude Code, while claude.ai chat is not Claude Code at all. A Cloud session runs on Anthropic-managed or self-hosted VMs. Remote Control shows the session in a browser, but the session still runs on your machine, so it uses your local files. If you rename a Remote Control session from claude.ai or the Claude app, the CLI shows the same name.

Sources1234567

2.Instruction file or prompt: placing content and drawing the content boundary

An instruction file and a prompt do different jobs. [CLAUDE.md hierarchy, AGENTS.md and path-scoped rules](lesson:2.6) sets out where each file loads from. The design question is what goes in them. Instruction files load in every session, so they should hold what is true for every task: build commands, coding standards, architecture. The prompt holds what is true for this task only: the bug, the ticket, the file to change. You know a fact belongs in a file when you keep repeating it. Signs include typing the same correction you typed last session, or a code review catching something Claude should already have known about the codebase.

Every line in an instruction file costs context in every session, so keep the files lean. Aim for under 200 lines per CLAUDE.md, write checkable rules such as "Run npm test before committing", and remove contradictions, because Claude may pick between conflicting instructions arbitrarily. If a rule only matters for one part of the repository, make it a path-scoped rule. It then loads only when Claude works with matching files.

This split also defines the content boundary. A system prompt, an append string, an instruction file and a plugin skill all reach Claude as instructions. Untrusted text, such as a customer email, a ticket body or a fetched web page, must never be pasted into any of these. In an instruction file it would be read with the same standing as your own rules, every session. Pass it in the per-task message instead, as material to work on. [Prompt injection and jailbreaks (two threat models)](lesson:7.1) covers the attacks themselves. Claude Code enforces one edge of this boundary for you: if an @path import points outside your working directory, you must approve it before it loads.

Sources8910

3.Designing an output schema and passing it through each API

A schema is the contract between Claude and the code that reads its output. [Structured outputs (JSON schema via output_config.format)](lesson:6.3) explains how constrained decoding enforces that contract. Writing a good contract is up to you. Name each field after what it means: plan_interest and demo_requested tell the reader more than field2 and flag. Add every field your downstream code reads to required, and set additionalProperties: false so no extra keys slip through. If a value can legitimately be absent, type the field as nullable, as errors: list[dict] | None does below, so that the schema itself allows the absence.

class APIResponse(BaseModel):
    status: str
    data: dict
    errors: list[dict] | None
    metadata: dict

Some constraints are not supported by the API. minimum, maximum, minLength and maxLength are removed from the schema that is sent, and SDK helpers copy each one into the field's description. If your helper validates responses, it still checks them against your original schema. A field with minimum: 100 reaches Claude as a plain integer, but the response is still checked against 100.

How you pass the schema depends on the surface. With the Messages API, put the schema in output_config.format with type: "json_schema". In Python, client.messages.parse(output_format=Model) converts a Pydantic model, sends it, validates the reply and returns parsed_output. If your schema comes from a file or an OpenAPI spec, put it in output_config yourself, optionally after running it through transform_schema(). In the Agent SDK, the outputFormat option takes { type: 'json_schema', schema: JSONSchema }, and the parsed result arrives in the result message's structured_output.

 ? ={
        "format": {
            "type": "json_schema",
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "email": {"type": "string"},
                    "plan_interest": {"type": "string"},
                    "demo_requested": {"type": "boolean"},
                },
                "required": ["name", "email", "plan_interest", "demo_requested"],
                "additionalProperties": False,
            },
        }
    },

When Claude Code runs non-interactively with -p and --json-schema, a response that fails validation is retried. MAX_STRUCTURED_OUTPUT_RETRIES sets the cap, five attempts by default (a first attempt plus four retries), and after that many failures with no valid output the run fails. In the Agent SDK, check the result message before reading structured_output: the errors field is populated only on the error_* subtypes, so a failed run carries no usable value.

Sources1121210

Exam traps

Each one states something that sounds right. Open it to see what is actually true.

1. 1.An SDK agent that has lost Claude Code's behaviour must be skipping CLAUDE.md, because the SDK loads no filesystem settings by default.Why is that wrong?

   When settingSources is unset it follows the CLI defaults and loads all sources. The usual gap is the minimal default system prompt, which you fix with the claude_code preset.

   Covered in Same prompt, different surface: CLI versus Agent SDK

2. 2.Constraints such as minimum or maxLength are silently dropped from a structured-output schema and never enforced.Why is that wrong?

   The helper removes them from the schema it sends and moves them into field descriptions. A helper that validates responses still checks every original constraint.

   Covered in Designing an output schema and passing it through each API