Skip to main content

A guided architecture exercise

Your job: make Northwind’s triage safe to automate.

A child’s injury report sat in the wrong queue for three days. Northwind now receives 4,100 tickets a week and needs a system that is fast enough to help, inexpensive enough to run, and safe enough to trust.

You win when:the service returns reliable data, keeps policy costs under control, and never lets a model approve an action beyond its authority.
You do not need to know Claude’s API yet.
  1. Learn: read a 30-second explanation and open the existing playground or lab.
  2. Decide: choose between two or three real implementation options.
  3. See: reveal the operational consequence and the exact failure signal to watch.
You are not calling a live API. Results combine checked-in measurements with clearly labeled arithmetic.

Mission briefing

Four ideas. Four decisions. One operating outcome.

Each decision teaches exactly one Claude API idea. You can open the linked explainer without losing your place, then return here to apply it.

1. Pick the modelA model is the engine that produces the answer. Smaller/faster models can cost less, but you must measure whether they still handle your important cases well.
2. Place the policy handbookPrompt caching saves a reusable beginning of a request. It only works when every byte before the cache marker stays the same; a changing date in front of it breaks the reuse.
3. Set the output contractA schema is a machine-checkable description of fields: category, urgency, confidence, and so on. Structured outputs make Claude produce that shape; your code validates it before acting.
4. Decide who has the final sayTools fetch facts from systems you control. Guardrails are ordinary server code that checks those facts and overrides an unsafe recommendation—so safety does not depend on the model obeying a sentence.
Operating pictureReady

Make a prediction to unseal the ledger. Strong engineers form a hypothesis before they look at the dashboard.

Customer delivery is a separate contract.

Symptom: the browser receives the whole reply at once, or a failed stream looks like HTTP 200.

Signal: no incremental SSE events, or an in-band error event.

Fix: disable proxy buffering, abort upstream work on disconnect, and handle done plus error. Learn it →

Carry it with you

Portable patterns

Constrain the output

Use when: A model response feeds software, not just a person.

messages.parse({ output_config: { format: zodOutputFormat(Schema) } })

Failure: Prompt-only JSON drifts until a downstream consumer breaks.

Verify: Send a boundary-case ticket and assert parsed_output matches the schema.

Read the lab →

Cache the stable prefix

Use when: A large policy or instruction block repeats across requests.

[{ text: stable, cache_control: { type: 'ephemeral' } }, { text: volatile }]

Failure: A timestamp before the breakpoint makes every request cold.

Verify: Make two equivalent calls and assert cache_read_input_tokens > 0 on the second.

Read the lab →

Re-derive authority

Use when: A tool-using agent can recommend a financially or legally bounded action.

const corrected = enforceAuthority(resolution, toolTrace)

Failure: The model repeats a forged approval as though it were a fact.

Verify: Attempt an over-limit refund and assert the returned resolution is corrected.

Read the lab →

Final milestone

Take the pattern into your world.

Turn your decisions into a private, editable engineering brief. It downloads locally as Markdown.