Building with the Claude API

• QuestionWhat is "Place instruction in system vs user"?Tap to revealAnswer`system` is for stable rules and role; `user` is for the actual per-call question. If the content is the same every call, it belongs in system.
• QuestionIn "Place instruction in system vs user", explain:Tap to revealAnswer`system` = privileged, persistent, role-setting. Same on every call.
• QuestionIn "Place instruction in system vs user", explain:Tap to revealAnswer`user` = conversational, per-turn, what changes call-to-call.
• QuestionIn "Place instruction in system vs user", explain:Tap to revealAnswerSystem content outranks user content when they conflict.
• QuestionIn "Place instruction in system vs user", explain:Tap to revealAnswerDecision rule: same on every call → system; varies per call → user.
• QuestionAnalogy for "Place instruction in system vs user":Tap to revealAnswerThink of `system` as the contract you signed with a contractor (rules, scope, who they are) and `user` as today's request ('paint the kitchen blue'). The contract doesn't change per task; the task does.
• QuestionWhat is "Few-shots as alternating turns"?Tap to revealAnswerShow the model examples as actual conversation turns (user / assistant / user / assistant), not as a list inside one message. It pattern-matches better.
• QuestionIn "Few-shots as alternating turns", explain:Tap to revealAnswerFew-shots as alternating user/assistant turns, not as inline bullet lists.
• QuestionIn "Few-shots as alternating turns", explain:Tap to revealAnswerFinal turn = actual user input, with no example marker.
• QuestionIn "Few-shots as alternating turns", explain:Tap to revealAnswerMatches the conversational pattern the model was trained on.
• QuestionIn "Few-shots as alternating turns", explain:Tap to revealAnswerWin is biggest for tasks with non-trivial output structure.
• QuestionAnalogy for "Few-shots as alternating turns":Tap to revealAnswerImagine teaching a kid to play a card game. You can describe ten example hands in a paragraph (bulleted few-shots), or you can play three quick demo rounds with them (turn-based few-shots). The demo rounds work better — same idea here.
• QuestionWhat is "Trace tool-use loop / stop_reason"?Tap to revealAnswerTool use is a back-and-forth loop. The model says 'run this tool', you run it and reply with the result, repeat until the model says it's done (`stop_reason: end_turn`).
• QuestionIn "Trace tool-use loop / stop_reason", explain:Tap to revealAnswerTool use is a loop. `stop_reason: tool_use` → run tool, return result. `stop_reason: end_turn` → done.
• QuestionIn "Trace tool-use loop / stop_reason", explain:Tap to revealAnswerParallel tools: multiple `tool_use` blocks in one turn → multiple `tool_result` blocks in matched-ID order.
• QuestionIn "Trace tool-use loop / stop_reason", explain:Tap to revealAnswertool_result must reference the prior tool_use_id; mismatches are rejected.
• QuestionIn "Trace tool-use loop / stop_reason", explain:Tap to revealAnswerFull history replays each turn — cost grows with loop depth.
• QuestionAnalogy for "Trace tool-use loop / stop_reason":Tap to revealAnswerIt's like a phone call where one side keeps asking the other to look something up. 'Hey, can you check X?' → you check, give answer → 'OK and Y?' → you check, answer → 'Great, here's the summary.' The summary is `end_turn`.
• QuestionWhat is "Place cache_control marker"?Tap to revealAnswerThe cache marker says 'everything above this is the same every call — please cache it.' Put it right after the stable stuff and before anything that changes.
• QuestionIn "Place cache_control marker", explain:Tap to revealAnswercache_control: ephemeral marks a cache breakpoint. Above = cached; below = fresh.
• QuestionIn "Place cache_control marker", explain:Tap to revealAnswerPlace after the largest stable prefix, before per-request content.
• QuestionIn "Place cache_control marker", explain:Tap to revealAnswerCache reads ≈ 10% of input cost. Cache writes ≈ 125% of input cost (one-time).
• QuestionIn "Place cache_control marker", explain:Tap to revealAnswerTTL ~5 minutes, refreshes on hit. High-frequency = sustained savings.
• QuestionAnalogy for "Place cache_control marker":Tap to revealAnswerIt's like saving a takeaway order. If your usual order is the same and only the day's special varies, you save 'the usual' as a template and add the special. If you save 'the usual + today's special', you have to re-save it every day.
• QuestionWhat is "Tool-schema vs prompt-only structured output"?Tap to revealAnswerIf code is going to parse the output, define a tool whose schema is the output shape. Tool-schemas use constrained decoding — the model can't break the format. Prompts can only ask politely.
• QuestionIn "Tool-schema vs prompt-only structured output", explain:Tap to revealAnswerPrompt-only structured output is a soft request. Fails ~3–10% silently.
• QuestionIn "Tool-schema vs prompt-only structured output", explain:Tap to revealAnswerTool-schema structured output uses constrained decoding. Schema-controlled fields cannot violate the schema.
• QuestionIn "Tool-schema vs prompt-only structured output", explain:Tap to revealAnswerDecision rule: machine-consumed output → tool-schema. Human-consumed output → prompt-only OK.
• QuestionIn "Tool-schema vs prompt-only structured output", explain:Tap to revealAnswerThe reliability gap is structural, not a prompt-quality issue.
• QuestionAnalogy for "Tool-schema vs prompt-only structured output":Tap to revealAnswerPrompt-only is asking someone to write JSON 'cleanly' on a napkin. Tool-schema is giving them a form with labelled boxes — they can't put a date in the email field even by accident.
• QuestionWhat is "Detect system-field leak"?Tap to revealAnswerIf anything that changes per call (date, user ID, request UUID) ends up in the system prompt, you've leaked. It breaks caching and pollutes the privileged role.
• QuestionIn "Detect system-field leak", explain:Tap to revealAnswerSystem-field leak = volatile per-request data in the system prompt.
• QuestionIn "Detect system-field leak", explain:Tap to revealAnswerTwo consequences: cache breaks (key changes per call) + privileged-layer pollution.
• QuestionIn "Detect system-field leak", explain:Tap to revealAnswerDetect via low cache hit rate, high cost on supposedly cached endpoints, code review.
• QuestionIn "Detect system-field leak", explain:Tap to revealAnswerFix: move volatile data into the user message, re-establish byte-stable system prefix.
• QuestionAnalogy for "Detect system-field leak":Tap to revealAnswerIt's like printing today's date on the cover of a reference book and then complaining it can't be re-shelved. The cover changes daily; the contents are stable; put the date inside the day's note, not on the cover.

1. 1Outline the core idea

   Analyse~10 min

   In your own words, outline the central idea of "Place instruction in system vs user". Aim for one paragraph, no jargon you haven't earned.

   Done when: A non-expert could read your paragraph and explain it back to you.

   Re-read the source concept

2. 2Apply it to a real situation

   Apply~15 min

   Find a real situation from your own work / life where "Detect system-field leak" applies. Apply the idea — describe the situation, the move you'd make, and the alternative you considered first.

   Done when: You can name a specific situation (not a hypothetical), state your move, and explain the trade-off in one paragraph.

   Re-read the source concept

3. 3Teach it back

   Evaluate~5 min

   Pick someone (a colleague, a peer, a rubber duck) and explain the section to them in under 5 minutes. Use your own example, not the one from the lesson.

   Done when: Your listener can repeat the core idea + the trade-off back to you without prompting.

Why this matters. Reading + quizzing prove recall; applying it in a real situation is the only evidence of transfer. Treat at least one of these as non-negotiable before you move on.