Skip to main content

2.4 Software engineering foundations

The largest single skill in Domain 2 after application design. Items pair ordinary engineering practice with the Claude-specific consequence.

REST and the Messages API​

REST conceptHow the Claude API expresses it
Resource + verbPOST /v1/messages, POST /v1/messages/batches, POST /v1/files, GET /v1/models
Auth headerx-api-key: <key>, or Authorization: Bearer <token> for OAuth (with the OAuth beta header)
VersioningThe anthropic-version header — pinned, not negotiated
Opt-in featuresanthropic-beta header (or the SDK betas array)
StatelessnessEvery request carries the full conversation; there is no session on the Messages API
IdempotencyNot automatic. A retried POST /v1/messages produces a new completion — see below
Status codes400 malformed, 401 auth, 403 permission, 404 missing, 413 too large, 429 rate limited, 5xx server, 529 overloaded

Idempotency is your job. A network timeout on a request that actually succeeded, then retried, produces a second completion and a second charge — and, if the tool it called was a payment, a second payment. The fix is a caller-generated key stored with the result on your side: derive a deterministic key from the input, check for an existing result before calling, and make tool handlers idempotent by key so a repeated tool_use for the same operation is a no-op.

JSON handling​

RuleWhy
Parse tool_use.input with JSON.parse / json.loadsEscaping (Unicode, forward slashes) varies by model; string matching is a latent bug
Never trust model-produced JSON without validatingUse output_config.format or strict: true, then still validate — see 6.3
Serialize tool results deterministicallyKey order changes bust the prompt cache
Model the absent case explicitlyNullable/optional fields beat a hallucinated placeholder
Do not build schemas the model cannot satisfyDeeply nested, 60-field, all-required schemas produce validation failures, not better data

Asynchronous programming​

Three distinct kinds of async, and items conflate them on purpose:

KindMechanismUse
StreamingSSE within one requestShow partial output; avoid request timeouts on long generations
ConcurrencyPromise.all / asyncio.gather over independent requestsCut wall-clock time on independent work — bounded by your rate limit
DeferredMessage Batches APILatency-tolerant bulk work at 50% cost

Concurrency discipline that items reward:

  • Bound it. A semaphore or worker pool, not an unbounded fan-out that trips 429s.
  • Back off with jitter on 429 and 5xx, honouring retry-after when present.
  • Execute parallel tool calls concurrently, then return every tool_result in a single user message.
  • Do not parallelise a dependent chain — step N+1 needs step N's output.
  • Cap total wall clock: SDK timeouts are per attempt and are retried, so budget timeout × (retries + 1).

Version control​

Prompts, tool descriptions, schemas, evals, and CLAUDE.md are source artifacts. Consequences:

PracticeDetail
Prompts in the repo, not in a database blob or a UIDiffable, reviewable, revertable, and attributable to a commit
One logical change per commitA prompt change and a schema change in one commit cannot be bisected
Eval results tied to the commit"Which version scored 94%?" must be answerable
Model ID in config, changed via PRA model bump is a reviewable change (2.6)
Secrets never committedEnvironment variables or a secret manager (7.4)
Generated agent output reviewed before mergeAgent-authored commits go through the same gate as human ones

Code review​

Reviewing Claude-related code, look forFailure it catches
stop_reason handled exhaustively, max_tokens not treated as successSilent truncation stored as a result
Every tool_use gets a matching tool_result, errors includedDangling tool_use, broken loop
Tool inputs parsed as JSON, not string-matchedEscaping-dependent bug
Model IDs pinned and configurableBehaviour changing without a deploy
usage loggedNo cost or cache observability
Untrusted content delimited and never granted authorityPrompt injection (7.1)
Retries bounded, backed off, and idempotentRetry storms, duplicate side effects
Output validated before it reaches a database or an APISchema-invalid writes
Prompts and tool descriptions read as specsAmbiguity the model will resolve badly

Claude Code performs review as a workflow — a /review command or a CI job that comments on a diff — but the reviewer's checklist above is what makes the output useful. Explicit criteria beat "review this code".

Refactoring: small and large scale​

ScaleApproach
Small — one function, one file, a renameOne pass, tests as the gate, direct edit. Cheap enough that the review cost dominates
Medium — a module, a pattern applied across a packagePlan first, then apply file by file with a verification step per file
Large — a cross-repo migration, an API version bump, a framework swapDecompose into focused passes, each with its own verification: inventory, mechanical transform, semantic fixups, dead-code removal
Why one giant refactor prompt fails

Asking for a 40-file migration in a single pass produces output that is inconsistent between files: attention dilutes across a long context and early instructions lose against late content. A bigger context window does not fix this. Decompose into passes with a deterministic check between them — the correct answer to "the output is inconsistent across many files" is almost never "increase the context window".

Mechanical transforms belong in mechanical tools. If a codemod, a formatter, or a compiler can do it deterministically, use it and reserve the model for the judgment steps — the semantic fixups a regex cannot express.

SDLC integration​

StageIntegration
Pre-commitFormatters, linters, secret scanning — deterministic hooks, not model calls
PRAutomated review comments; eval suite for prompt/schema changes
CIHeadless Claude Code in a non-interactive job with explicitly allowed tools
ReleasePinned model and prompt versions; canary
Post-deployUsage, cost, stop_reason, and validation-failure dashboards (2.2)

Quiz​

  1. Question 1

    A tool call that charges a customer occasionally runs twice. Traces show one request timed out at the client, was retried, and both attempts reached the payment backend. What is the correct fix?

  2. Question 2

    A 40-file framework migration is issued as one request covering the whole diff scope, which fits the context window comfortably. The output is internally inconsistent: early files use the new pattern, later ones drift back to the old one. What is the most effective change?

  3. Question 3

    A service fans out 500 concurrent Messages API requests, immediately starts receiving 429s, and ends up with lower overall throughput than it had at 50 concurrent requests. What is the correct response?