AnthropicClaude Certified Architect – Professional2026-106.4 Document architectures and provide implementation guidance
Specify outcomes builders can verify
Completed by the knowledge check
Learning objective
Write implementation guidance: specifications, interface and error-handling contracts, and acceptance criteria for builders.
Core idea
For an architect coordinating several builders, a tool schema and a specialist prompt are starting interfaces. The professional task is to specify the complete behavior around them: who may invoke an operation, what business result counts as success, how failures propagate, and what proves the implementation acceptable.
Write an implementation specification for each consequential path. It connects requirements to interfaces, failure outcomes, and executable acceptance cases. Keep the approved release inventory in 6.4.1 and the architectural rationale in 6.4.2; this lesson turns those choices into buildable obligations.
How it works
State the behavior before assigning work
Identify the actor, preconditions, accepted inputs, effects, postconditions, and prohibited outcomes. Separate what the application guarantees from what the model proposes. For a case-routing service, the proposal can identify a destination team; the application must still enforce which destinations that employee may use.
Give each requirement an identifier and an acceptance-case reference. A requirement such as “route safely” cannot settle an implementation disagreement. “A request from tenant A cannot create a case under tenant B, including when retrieved text requests that action” gives the builder and tester the same observable target.
Name the authoritative data source, expected freshness, and behavior when a prerequisite cannot be verified. When multiple teams own the path, state which service makes the final decision. NIST MAP 1.6 calls for elicited system requirements, and MAP 2.2 calls for documentation sufficient for relevant actors to make decisions. An unresolved owner is a specification defect, not an invitation for each team to choose independently.
Complete the interface around the schema
Assume the tool and specialist definitions exist. Extend them with caller identity, authorization rules, result semantics, compatibility version, deadlines, and side-effect guarantees. Mark application-defined status names explicitly so builders do not mistake them for Anthropic fields.
For example, a route_case handler might return application outcomes routed, needs_review, or unavailable. Specify the required case identifier for routed, the permitted reason categories for needs_review, and whether unavailable means that no write occurred or that the result is uncertain. Those are different promises and require different recovery paths.
Also define specialist completion criteria and how the coordinator rejects an incomplete result. A specialist returning a plausible summary has not necessarily fulfilled a requirement to provide source locations and unresolved conflicts. The specification should name the validator, its owner, and the terminal outcome when the result cannot be accepted.
For writes, name the backend’s duplicate-prevention and reconciliation mechanism. If a case service implements a client-generated operation key and a lookup by that key, document both as application facilities. If the backend supplies neither, do not promise safe automatic replay after an uncertain timeout. Require reconciliation or human handling before another write.
Specify failures at the boundary that owns them
Separate transport, generation, tool, and business failures; each needs its own owner and recovery rule.
Anthropic’s Claude API error page names 401 authentication_error and 403 permission_error. The official SDKs retry transient failures such as connection errors, rate limits, and 5xx responses; assign credential and permission failures to the integration owner. Configure retries through Python max_retries or TypeScript maxRetries. Your implementation guidance must name the deployed language’s setting and identify whether the SDK or application owns retries. It should not add an independent outer loop without accounting for the SDK’s attempts.
An HTTP success does not settle completion. Specify the accepted Messages API stop_reason values and assign every other outcome an owner. For a client-tool integration without custom stop sequences or server-tool continuation, use this application contract:
stop_reason | Cause and owned outcome |
|---|---|
end_turn | Natural completion: the application validates the result before accepting it. |
tool_use | Tool request: the authorized handler validates and executes complete calls. |
max_tokens | Output ceiling reached: the integration owner retries with higher max_tokens within budget. For an incomplete tool_use, retry the request; never continue or execute the partial call. If no retry fits the budget, return an incomplete outcome to the review owner. |
refusal | Claude declined: inspect stop_details; the review owner handles the request under the application’s refusal policy. |
model_context_window_exceeded | Context filled: treat output as truncated and route to the integration owner for context repair. |
stop_sequence, pause_turn, or an unrecognized value | Outside this integration’s accepted paths: stop and escalate to the integration owner; do not accept the payload. |
A failed client-tool execution uses a correlated tool_result with is_error: true. Define the safe error content and which failures the model may attempt to repair. Keep authorization denial distinct from a temporary dependency failure: a repair attempt must not gain permission by choosing a different identifier. The tool-call documentation supplies the protocol; the specification supplies the permitted business recovery.
For streaming integrations, Anthropic documents that an error can occur after HTTP 200. Require a test for that path and define what the consumer receives when output is incomplete. The builder must not mark a task successful merely because the connection began successfully.
Make acceptance executable and owned
Each acceptance criterion names the tested configuration, case population, observable assertion, threshold, and decision owner. Anthropic recommends specific, measurable, achievable, relevant success criteria and multidimensional evaluation. Apply those properties to quality, authorization, latency, and failure handling rather than selecting one average score.
Keep deterministic interface assertions distinct from stochastic quality measures. “All unauthorized writes are rejected in this security test set” tests an enforcement requirement. “At least 95% of 400 adjudicated routing cases choose the correct queue” evaluates model-assisted task quality. Neither assertion proves the other, and a finite passing set does not establish zero production risk. The thresholds here illustrate a specification; the business and security owners select their actual values.
Give builders representative request, success, failure, and boundary fixtures plus one tested reference path. State how they run the checks and where results are reviewed. Include error branches in the reference path.
Key distinctions and trade-offs
Schema versus implementation contract: A schema describes data shape. The surrounding contract fixes authority, effects, deadlines, and recovery behavior.
Specification versus reference implementation: The specification is the obligation. The example demonstrates one conforming approach and needs its own owner; it cannot silently redefine the requirement.
Acceptance criterion versus production objective: A release test establishes a bounded result on named cases. Production monitoring checks behavior under the live workload. Carry identifiers across both without claiming they are identical measurements.
Precise contracts cost design effort. Concentrate it where teams exchange data or cause effects; incompatible recovery assumptions create integration rework.
Architecture / decision scenario
A healthcare scheduling provider gives two delivery teams three weeks to build an appointment-routing assistant. The assistant may propose a clinic, but only the scheduling service may create the booking. The tempting plan is to divide work using the existing tool schema and approve the integration after a successful demonstration.
The architect rejects that plan because a demonstration cannot distinguish an uncreated booking from a timed-out response after creation. The implementation specification requires the scheduling service’s operation-key lookup before replaying an uncertain write. It defines needs_review and unavailable as application outcomes, identifies the authorization owner, and specifies failure delivery through tool_result and is_error: true where the conversation continues.
Acceptance includes zero cross-clinic authorization violations in 80 adversarial fixtures, correct routing in at least 380 of 400 adjudicated cases, and no duplicate booking in the lost-response fixture. A stream interrupted after HTTP 200 must terminate as incomplete. These are illustrative project thresholds, signed by the clinical operations and security owners, rather than universal vendor guarantees.
The receiving leads build and test against the same versioned specification. A model-quality miss returns to the routing team; a duplicate write returns to the scheduling-service owner. The result is an actionable division of work, with failure behavior defined before the teams implement incompatible recovery loops.
Common exam traps
- Handing builders only a schema and expecting them to infer business semantics.
- Treating HTTP 200 as proof that a streamed task completed.
- Adding application retries without documenting the SDK retry setting.
- Promising safe replay when the backend cannot identify a previous write.
- Letting a strong average quality score conceal failed authorization checks.
What to remember
Implementation guidance connects observable requirements to owned interfaces, failure outcomes, and acceptance cases. Specify authority and uncertain side effects as carefully as payload shape. Builders should agree on what to return, what to retry, and what blocks acceptance before they write the integration.
Knowledge check
A create_booking tool handler calls a scheduling service that offers no operation key and no way to look up a previous write. A call times out, and the handler cannot tell whether the booking was created. What should the implementation specification require next?
is_error: true so the model can retry with a different slotunavailable , meaning that no booking was madeA streaming Claude integration marks a drafting task successful as soon as the Messages API response arrives with HTTP 200. The acceptance suite has no other completion check for streamed output. What should the specification add?
A Python service uses the official Anthropic SDK with its default retry settings. Builders add an application loop that retries each failed Messages call three more times. The service must keep attempts within an agreed request deadline, but the specification says nothing about retries. What should it state?
max_retries setting and one retry owner with a bounded attempt budgetmax_retries here, and decides whether the SDK or the application owns retries. Authentication and permission errors go to the integration owner rather than to a retry loop.A release has two acceptance criteria. At least 95% of 400 adjudicated routing cases must choose the correct queue, and no unauthorized write may succeed in an 80-case security fixture set. Routing scores 97%, but two of the 80 cross-tenant writes succeed. The release manager notes that the combined pass rate over all 480 cases exceeds 95%. What is the acceptance decision?
References
- NIST, Artificial Intelligence Risk Management Framework (AI RMF 1.0)
- Anthropic, Errors
- Anthropic, Stop reasons and fallback
- Anthropic, Handle tool calls
- Anthropic, Define success criteria and build evaluations