Task statement 2.4 · Applications and integration

2.4 · Software Engineering Foundations

In Shelfwise, the course example, the code around the Claude calls is ordinary software: HTTP requests and JSON on the wire, many questions in flight at once, prompts and stock rules in git, and a pull request for every change. The engineers also run Claude Code on that repository, so they need to know when it should plan first.

Why it's tested

The tempting shortcuts here look like finished work. Wrapping each Claude call in async def while keeping the synchronous client looks concurrent, but each call holds the program until its reply arrives, so the requests still run one at a time. Asking Claude Code for a cross-file change directly, because the request fits in one line, finds the second copy of the code only after the first edit.

Start hereThree terms this section adds

idempotent
A request whose effect on the server is the same whether it is sent once or several times. GET, PUT and DELETE are idempotent; POST is not.
event loop
The scheduler inside an asynchronous program. It runs one coroutine until that coroutine waits, for example on a network reply, then runs another.
semaphore
A counter that limits how many tasks run a block at once. asyncio.Semaphore(2) lets two requests proceed and makes the third wait.

KnowledgeThe Messages API as a REST resource

The Claude API is a REST API: each resource has a URL, and the HTTP method says what to do with it, so POST /v1/messages asks for a new message and GET /v1/models lists the models. Every request carries anthropic-version, content-type: application/json and a credential, and every response carries a request-id header, which 2.2 logs. The status code says whose fault a failure is. A 400 invalid_request_error or a 401 authentication_error means the client erred, so sending it again fails again. A 429 rate_limit_error, a 500 or a 529 overloaded_error is worth retrying after a wait, and a rate-limit 429 gives the wait in its retry-after header.

Retrying blindly is safe only for idempotent requests, and RFC 9110 says a client should not retry a POST automatically unless it knows the request is idempotent or can tell the first attempt never took effect. The SDKs still retry POST /v1/messages on connection errors, 408, 409, 429 and 5xx, twice by default, with exponential backoff, a wait that grows after each failure. That is acceptable because a Messages call has no lasting effect beyond its bill, so a repeat only costs a second answer. Your own endpoints need the same thought: if the Shelfwise widget resubmits a question after a timeout, the service runs the whole agent twice and that question costs double.

KnowledgeJSON in, JSON out

Both bodies are JSON, the format RFC 8259 defines: objects of name–value pairs, arrays, strings, numbers, true, false and null, encoded as UTF-8 between systems. A tool definition describes its input in input_schema with a JSON schema, a document listing the fields, their types and which are required, and when Claude calls the tool, the tool_use block's input arrives as a parsed object. Without strict: true on the tool, that object can still break the schema, for example "2" where an integer was declared, so validate it before acting on it. With strict: true, it is guaranteed to match. Two JSON rules catch teams out. Parsers disagree about an object that repeats a name. Only integers within ±(253 − 1), about 16 digits, are guaranteed to keep their exact value, so an 18-digit ID sent as a number can arrive with different final digits. Declare identifiers as strings.

KnowledgeAsynchronous programming: many requests in flight

Most of a Claude call is spent waiting for the reply, so asynchronous programming lets one process overlap many calls. In Python, AsyncAnthropic has the same methods as Anthropic, each one awaited, and the Agent SDK's query() is already an async iterator. asyncio.gather runs a list of awaitables concurrently and returns their results in the list's order. A synchronous client called inside async def undoes this, because it blocks the event loop until its reply arrives. Unbounded concurrency fails the other way. Shelfwise's eval runner, started on all 150 recorded questions at once, sends about a million input tokens before any cache exists, against a workspace cap of 100,000 a minute, so the API answers with 429s. Under a semaphore of 2 it runs about 15 questions a minute, roughly 47,000 uncached input tokens, which leaves room for the Saturday peak's 31,000, and finishes in about 10 minutes instead of 20 one at a time.

Interactive · how many questions the eval runner keeps in flight

Three timelines of the same six eval questions, time running downward at about 8 seconds a question. Left: one at a time, six questions stacked one after another, 48 seconds. Middle: all six start together; two finish and four are turned away with 429 errors. Right: a semaphore of 2 runs three waves of two questions, 24 seconds. One at a time TIME question 1 · 8 s question 2 question 3 question 4 question 5 question 6 6 questions: 48 s 150 QUESTIONS ≈ 20 MIN All at once TIME 2 ANSWERED 4 × 429 ≈1M input tokens at once CAP 100,000 A MINUTE → 429s Semaphore of 2 TIME q1 q2 q3 q4 q5 q6 6 questions: 24 s 150 ≈ 10 MIN · ≈47,000 TOKENS/MIN Six of the 150 eval questions, drawn at about 8 s each.

Choose how many eval questions run at the same time.

One at a time: each question waits for the one before it, so the process sits idle through every reply. At about 8 s a question, the 150 take about 20 minutes.

All at once: every question's first request goes out before any cache exists, about a million input tokens against a cap of 100,000 a minute, so the API turns most of them away with 429s.

Semaphore of 2: the third question waits until one of the first two finishes. About 15 questions a minute, roughly 47,000 uncached input tokens, so even with the Saturday peak's 31,000 the workspace stays under its cap, and all 150 finish in about 10 minutes.

Time runs downward in each column. Blue is a question that ran, amber a request turned away with a 429; the totals scale six questions up to 150.

KnowledgeVersion control and SDLC integration

Version control records what changed in prompts as well as code. Shelfwise keeps its prompt, stock rules, tool schemas and eval set in git, so each change is a commit on a branch, reviewed in a pull request, and a bad one is undone with git revert, which records a new commit that reverses it without rewriting history. When a regression appears and nobody knows which commit caused it, git bisect runs a binary search between a known-good and a known-bad commit. With git bisect run it checks out each candidate and runs a script, where exit code 0 means good, 125 means skip and any other code from 1 to 127 means bad, so an eval script becomes the test and about eight runs search 200 commits.

SDLC integration puts Claude inside those same steps instead of beside them. The Claude Code GitHub Action (anthropics/claude-code-action@v1) runs Claude Code in a workflow: with no prompt input it answers @claude mentions in issues and pull requests, and with one it runs on any event, such as every push to a pull request. Anthropic's managed Code Review, a research preview for Team and Enterprise plans, instead posts inline findings tagged by severity, and its check run always ends neutral, so it never approves or blocks a merge. The merge gate stays with the team: a Shelfwise pull request merges only when the tests pass, the eval scores 150/150 and an engineer approves. Headless runs and their configuration belong to 3.1, Claude Code Operation.

SkillCode review and refactoring with Claude Code

Code review works best from a fresh context. The session that wrote a change still holds the reasoning behind it, while a reviewer in its own context window sees only the diff and the criteria, which is why the docs recommend a separate reviewer session or a subagent (1.1). Claude Code's /code-review works that way: it runs as a background subagent, reports correctness bugs, and applies its findings when given --fix. A finding is still a claim for the engineer to check, not a verdict.

Refactoring changes structure without changing behaviour, and its scale decides how to ask for it. A small-scale refactoring touches one function whose callers you already know, such as renaming fmt() to format_stock_answer() in answer.py, so you ask Claude Code for it directly, then read the diff and run the tests. A large-scale refactoring crosses files, and its full extent is unknown until someone reads the code. Plan mode lets Claude read files and propose a plan, but blocks edits until you approve it (unless bypass permissions are available). It hands the reading to the built-in, read-only Plan subagent, which maps every use in its own context window and returns only a summary to the session.

Small-scale

Ask directly

One function, and you already know every caller.

Then: read the diff and run the tests.

Large-scale

Plan mode first

Several files, and nobody has mapped them yet.

Then: a subagent maps the code, you approve the plan, Claude edits.

Shelfwise's move of its stock rules out of a Python string shows why the second path exists:

# task: move STOCK_RULES from service/agent.py into prompts/stock_rules.md
direct edit → PR #41: agent.py loads the file, CI eval 150/150
Claude review on PR #41: evals/run_eval.py:12 defines its own STOCK_RULES,
  a duplicate the service no longer loads, so the next rule change reaches one copy
# fix: plan mode, Plan subagent finds STOCK_RULES in 2 files; plan: both load the file
outcome: one copy in git, eval re-run 150/150 against the file the service loads

Started directly, the change looked complete, because the eval still passed on its own duplicate. The review found that copy after the edit, and the plan would have found it before. Left in place, the next rule change would have reached the service but not the eval.

Before asking Claude Code for a refactor, ask: do I already know every place this change has to land? Yes → ask for it directly, then review the diff and run the tests. No → plan mode first, with a subagent mapping the code, and approve the plan before any file changes.
Takeaway
  • A 4xx means fix the request; a 429, 500 or 529 is retried after a wait, and only idempotent requests are safe to repeat blindly.
  • Concurrency needs an async client and a limit: AsyncAnthropic or query() under a semaphore, never the synchronous client inside async def.
  • Keep prompts, schemas and evals in git, let Claude review each pull request, and keep the merge decision in your own checks.

check yourself

0 / 4 answered

A travel company's itinerary assistant keeps its system prompt, tool schemas and model settings in git. Over two weeks, 200 commits merged, and somewhere along the way the assistant's eval score fell from 96% to 81%. The eval script runs on any commit in about four minutes and exits non-zero below 90%.Which approach finds the commit that caused the drop with the fewest eval runs?

Select one.

A data team's nightly script classifies 400 support emails with Claude. To speed it up, an engineer moved each call into an async def function and ran all 400 with asyncio.gather, keeping the existing anthropic.Anthropic() client. The run still takes 70 minutes, like the old loop, the logs show no 429 errors, and CPU use stays low.What is the most likely root cause?

Select one.

A freight company's agent calls a track_shipment tool whose input_schema declares shipment_id as an integer. Shipment IDs are 18 digits long. The tool runs in Node.js and reads the tool_use input with JSON.parse. Most lookups fail, and each logged ID differs from the user's in its last few digits; IDs under 16 digits always work.Which change makes every lookup receive the exact shipment ID?

Select one.

A payments team will use Claude Code to replace a deprecated logging library across about 120 files. Two services format their log lines differently, and nobody has decided between a shared adapter and editing every call site. The lead wants to approve the approach before any file changes, and wants the session's context kept free for the edits.Which TWO steps best meet both of the lead's conditions?

Select two.

sources

  1. Claude Platform Docs, "API overview": a RESTful API; POST /v1/messages and GET /v1/models; the anthropic-version, content-type and credential headers; the request-id response header. Checked 2026-10-04.
  2. Claude Platform Docs, "Claude API errors": the status codes and error types; the SDK retries transient failures twice by default with exponential backoff, honouring retry-after. Checked 2026-10-04.
  3. Claude Platform Docs, "Python SDK": AsyncAnthropic with await; connection errors, 408, 409, 429 and 5xx retried twice by default. Checked 2026-10-04.
  4. Claude Code Docs, "Agent SDK reference - Python": query() returns an async iterator. Checked 2026-10-04.
  5. Claude Platform Docs, "Define tools" and "Strict tool use": input_schema is a JSON Schema object; without strict mode Claude may return "2" instead of 2; strict: true guarantees the input follows the schema. Checked 2026-10-04.
  6. IETF, RFC 9110, "HTTP Semantics": safe and idempotent methods; a client should not automatically retry a non-idempotent request; the 4xx and 5xx classes; Retry-After. And RFC 6585 §4: 429 Too Many Requests. Checked 2026-10-04.
  7. IETF, RFC 8259, "The JSON Data Interchange Format": names within an object should be unique; integers in [−(253)+1, (253)−1] are interoperable; UTF-8 between systems. Checked 2026-10-04.
  8. Python documentation, "Coroutines and Tasks", "Synchronization Primitives" and "Developing with asyncio": gather runs awaitables concurrently with results in input order, and the to_thread entry says an IO-bound function run in the main thread would block the event loop (Coroutines and Tasks); Semaphore limits concurrent access (Synchronization Primitives); blocking code called directly delays every other task (Developing with asyncio, "Running Blocking Code"). Checked 2026-10-04.
  9. Git documentation, git-revert and git-bisect: revert records new commits that reverse earlier ones; bisect's binary search and the git bisect run exit codes. Checked 2026-10-04.
  10. Claude Code Docs, "Claude Code GitHub Actions" and "Code Review": @claude mentions and the prompt input; severity-tagged inline findings that never approve or block a PR; the neutral check run; /code-review as a background subagent with --fix. Checked 2026-10-04.
  11. Claude Code Docs, "Best practices for Claude Code", "Common workflows", "Choose a permission mode" and "Create custom subagents": a fresh context improves code review; refactor in small, testable increments; plan when the change modifies multiple files, skip it for a one-sentence diff; plan mode blocks edits until approval and delegates research to the read-only Plan subagent, which returns only a summary. Checked 2026-10-04.
  12. Shelfwise's eval runner timings, the semaphore of 2, PR #41, the file paths and the merge gate are this course's example details.