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 concept | How the Claude API expresses it |
|---|---|
| Resource + verb | POST /v1/messages, POST /v1/messages/batches, POST /v1/files, GET /v1/models |
| Auth header | x-api-key: <key>, or Authorization: Bearer <token> for OAuth (with the OAuth beta header) |
| Versioning | The anthropic-version header — pinned, not negotiated |
| Opt-in features | anthropic-beta header (or the SDK betas array) |
| Statelessness | Every request carries the full conversation; there is no session on the Messages API |
| Idempotency | Not automatic. A retried POST /v1/messages produces a new completion — see below |
| Status codes | 400 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
| Rule | Why |
|---|---|
Parse tool_use.input with JSON.parse / json.loads | Escaping (Unicode, forward slashes) varies by model; string matching is a latent bug |
| Never trust model-produced JSON without validating | Use output_config.format or strict: true, then still validate — see 6.3 |
| Serialize tool results deterministically | Key order changes bust the prompt cache |
| Model the absent case explicitly | Nullable/optional fields beat a hallucinated placeholder |
| Do not build schemas the model cannot satisfy | Deeply 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:
| Kind | Mechanism | Use |
|---|---|---|
| Streaming | SSE within one request | Show partial output; avoid request timeouts on long generations |
| Concurrency | Promise.all / asyncio.gather over independent requests | Cut wall-clock time on independent work — bounded by your rate limit |
| Deferred | Message Batches API | Latency-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-afterwhen present. - Execute parallel tool calls concurrently, then return every
tool_resultin 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:
| Practice | Detail |
|---|---|
| Prompts in the repo, not in a database blob or a UI | Diffable, reviewable, revertable, and attributable to a commit |
| One logical change per commit | A 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 PR | A model bump is a reviewable change (2.6) |
| Secrets never committed | Environment variables or a secret manager (7.4) |
| Generated agent output reviewed before merge | Agent-authored commits go through the same gate as human ones |
Code review
| Reviewing Claude-related code, look for | Failure it catches |
|---|---|
stop_reason handled exhaustively, max_tokens not treated as success | Silent truncation stored as a result |
Every tool_use gets a matching tool_result, errors included | Dangling tool_use, broken loop |
| Tool inputs parsed as JSON, not string-matched | Escaping-dependent bug |
| Model IDs pinned and configurable | Behaviour changing without a deploy |
usage logged | No cost or cache observability |
| Untrusted content delimited and never granted authority | Prompt injection (7.1) |
| Retries bounded, backed off, and idempotent | Retry storms, duplicate side effects |
| Output validated before it reaches a database or an API | Schema-invalid writes |
| Prompts and tool descriptions read as specs | Ambiguity 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
| Scale | Approach |
|---|---|
| Small — one function, one file, a rename | One pass, tests as the gate, direct edit. Cheap enough that the review cost dominates |
| Medium — a module, a pattern applied across a package | Plan first, then apply file by file with a verification step per file |
| Large — a cross-repo migration, an API version bump, a framework swap | Decompose into focused passes, each with its own verification: inventory, mechanical transform, semantic fixups, dead-code removal |
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
| Stage | Integration |
|---|---|
| Pre-commit | Formatters, linters, secret scanning — deterministic hooks, not model calls |
| PR | Automated review comments; eval suite for prompt/schema changes |
| CI | Headless Claude Code in a non-interactive job with explicitly allowed tools |
| Release | Pinned model and prompt versions; canary |
| Post-deploy | Usage, cost, stop_reason, and validation-failure dashboards (2.2) |
Quiz
- 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?
- 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?
- 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?
Links
- https://platform.claude.com/docs/en/api/messages
- https://platform.claude.com/docs/en/api/errors
- https://platform.claude.com/docs/en/api/rate-limits
- https://en.wikipedia.org/wiki/Representational_state_transfer
- https://en.wikipedia.org/wiki/Idempotence
- https://en.wikipedia.org/wiki/Exponential_backoff
- https://en.wikipedia.org/wiki/Code_refactoring