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.
share
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
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.
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.
Ask directly
One function, and you already know every caller.
Then: read the diff and run the tests.
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.
- 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:
AsyncAnthropicorquery()under a semaphore, never the synchronous client insideasync def. - Keep prompts, schemas and evals in git, let Claude review each pull request, and keep the merge decision in your own checks.