Stakeholder Communication & Lifecycle Management · Lesson 4 of 5

5.4 - Documenting an Architecture and Giving Implementation Guidance

Produce an architecture document, diagrams, decision records and runbooks for a Claude system, and hand implementation guidance to a build team as constraints, rationale and acceptance criteria rather than a code dump.

Architecture documentation is a communication tool for a reader who was not in the room: the build team, the on-call engineer, the security reviewer, the successor who inherits the system in a year. Its test is whether that reader can build, operate, question and safely change the system without you. For Claude systems the standard content (context, views, interfaces, quality attributes, operations) needs some additions, because the behaviour of the system depends on artifacts that traditional documents omit: prompts, model configuration, tool contracts and evaluation sets.

What the document must contain

Organise the document so each section answers a question a reader will actually have.

Context and goals: the problem, scope and explicit non-goals, key requirements, the architecturally significant quality attributes (latency, accuracy, availability, cost, auditability) and the success criteria from discovery (lesson 5.1).
Constraints and assumptions: each marked confirmed or assumed, with an owner for resolving the assumed ones.
Views: context, container and runtime diagrams (below).
Components and interfaces: responsibilities and contracts. For Claude systems this includes the prompt set as a versioned artifact, tool definitions with input schemas, permissions and side effects, retrieval sources and their freshness, the model configuration (pinned model ID and settings such as effort or output limits), validation and guardrail steps, and the points where a human reviews or approves.
Data: what enters prompts, how it is classified, what is logged, and the retention and residency arrangement chosen.
Failure modes and resilience: API errors, timeouts, refusals or malformed output, truncated responses, and the defined degraded mode.
Quality and evaluation: where the eval set lives, who owns it, the thresholds, and the regression gate that protects changes (lesson 5.3).
Observability, cost, security: what is logged and alerted, the cost levers, credential handling, environment separation, least privilege for tools.
Decisions, risks, open questions: a link to the decision log and a dated list of what remains unresolved.
Operations: owners, on-call, and links to runbooks.

Key concept

In a Claude system the prompts, model ID and settings, tool schemas and eval set are architectural artifacts, not tuning details. They determine behaviour, they change over time, and they must be documented, versioned and owned like code and configuration. A document that describes only boxes and arrows leaves the most volatile part of the system unrecorded.

Diagrams that earn their place

The C4 model gives a useful hierarchy: a system context diagram shows the system, its users and neighbouring systems and orients any audience; a container diagram shows the major building blocks and technology choices for technical readers; a component diagram opens up one container for developers; and a code-level view is rarely worth drawing by hand. C4 also describes supplementary dynamic diagrams (behaviour over time) and deployment diagrams (runtime infrastructure), and it is notation and tooling independent.

For a Claude system, add three things regardless of notation. Show where the non-deterministic component sits and what validates its output. Show trust and data boundaries: what leaves your environment, to which service, under which data-handling arrangement. And show where humans intervene. A dynamic diagram of a single request or agent loop (assemble prompt, call model, execute tool, validate, review, act) is often the most valuable picture in the document, because it exposes the failure and review points. Give each diagram one message and a legend, and keep its source in version control.

Decision records and the living document

The architecture document describes the current design; the decision log explains how it got here. Keep both, and link them. Write a record for each significant, hard-to-reverse choice: platform, pattern (single call, workflow or agent), model selection, retrieval approach, human-review placement, data handling. Records follow the format in lesson 5.2 (context, decision, consequences, status), are never edited to hide history, and are marked superseded when replaced. When the document and a record disagree, the document is stale; assign an owner and a review trigger, such as every model change and every architecture-affecting release, so it does not drift.

Runbooks: turning architecture into operations

A runbook maps a symptom to diagnosis and action for someone woken at night. Write them from the failure modes in the architecture, keep them short, and rehearse them. Claude-specific examples grounded in Anthropic's documented behaviour:

Symptom	First checks	Action
Rising 429 responses	Which limit (requests, input tokens or output tokens) using the rate-limit response headers; workspace limits; a recent traffic ramp; whether the error carries a retry-after header	Back off and smooth traffic; raise limits if legitimate. A 429 with no retry-after can mean a monthly spend cap, where retries keep failing until access resumes, so escalate rather than retry
529 overloaded or 5xx	The public status page; error rate across regions or workloads	Backoff, queue asynchronous work, switch to the degraded mode; include the request ID when contacting support
Spike in parse or schema failures	Recent prompt, model or schema change; truncated outputs; a new input type	Roll back the last change, run the regression set, add the failing inputs to the eval set
Quality alert with no code change	Model ID and prompt version in logs; the deprecation page; sampled outputs	Collect examples with request IDs. Anthropic notes that infrastructure around a fixed model ID can change and cause minor differences, so raise it with support and re-run evals

Log the request ID (Anthropic returns one in every response for support cases), model ID, prompt version and token usage on every call, and use separate workspaces for development, staging and production.

Implementation guidance and handoff

Good guidance gives a build team constraints, rationale and acceptance criteria, and leaves room for their engineering judgement. Distinguish clearly between non-negotiables (data may not leave a boundary, a human approves before any irreversible action, the model ID is pinned, releases pass the eval gate) and team choices (framework, code structure, libraries).

Suggest a build order that reduces risk early: an evaluation harness and a thin end-to-end slice first, then broaden. This matches Anthropic's advice to test extensively in sandboxed environments, keep designs simple and start evaluation from a small set of real cases. Define “done” through the eval thresholds, the runbooks and the monitoring, not through feature completion alone. Put prompts, tool schemas and model configuration in the repository and in one configuration source, so a change is reviewable and revertible.

The handoff itself is a process: a walkthrough of the document and decisions, an agreed channel and contact for questions, checkpoints at design review and before launch, and a rule that deviations from a non-negotiable become a new decision record rather than a quiet change.

Common exam distractor

Distractors here include a document that is only a diagram plus a technology list (no rationale, quality attributes or operations), one that treats prompts and model settings as implementation detail left out of the design, and a handoff that consists of finished code and then silence. Equally wrong is a runbook that says “retry until it works” for every error. The strong answer packages requirements, views, interface and artifact specifications, decision records, quality gates, runbooks, explicit non-negotiables and open questions, and stays reachable through the build.

Exam traps

An architecture document made of one box-and-arrow diagram and a list of chosen technologies.

It omits requirements, quality attributes, rationale, failure modes, data handling, evaluation and operations. The reader cannot judge the design, build to the intent, or run the system.
Leaving prompts, model ID and settings, tool schemas and the eval set out of the architecture because they are 'implementation details' that developers will tune.

In an LLM system these artifacts determine behaviour and change frequently. They need versioning, ownership and a change gate, so they belong in the architecture and its configuration management.
Handing the build team complete pseudocode and finished prompts, then withdrawing.

Prescriptive code hides the reasons behind the design and prevents adaptation. Effective handoff supplies constraints, rationale and acceptance criteria, separates non-negotiables from team choices, and keeps a channel open for questions and deviations.
A runbook instructing operators to retry any failed API call with backoff until it succeeds.

Failure causes differ. A monthly spend-cap 429 carries no retry-after and persists until access resumes, a quality regression needs rollback and evals, and an overload needs a degraded mode. Runbooks must map symptoms to distinct diagnoses and actions.

Practice question

You designed a Claude-based document triage service and will not join the build team. The team has strong engineers but limited LLM experience, and operations will take over at launch. Which handoff package is best?

A An architecture document with requirements and quality attributes; C4 context and container views plus a dynamic request-flow view; prompt, tool-contract and pinned-model specs; a decision log; an eval set with release-gate thresholds; draft runbooks; non-negotiables versus team choices; scheduled reviews and a named contact. Correct
It supplies constraints, rationale and acceptance criteria, covers the volatile LLM artifacts, gives operations something usable, and keeps a feedback channel for deviations.
B Finished prompts and scaffolding code with instructions to follow them exactly, a short README on the code layout and a promise to review the first pull requests; the eval set and runbooks can be created after launch, when real issues show what is actually needed, and questions about intent can be answered from the code comments.
Deferring evaluation and operations removes the quality gate and leaves operators without procedures at the riskiest time. Code alone does not convey rationale or constraints.
C A single architecture slide deck with the context diagram and a technology list, plus a recording of the design walkthrough, on the basis that strong engineers will fill in the details themselves and ask questions whenever they need to, so nothing more is required and the deck can double as the operations reference.
It omits rationale, quality attributes, data handling, failure modes, evaluation and runbooks. The team cannot infer non-negotiables and operations has nothing to run on.
D A pointer to Anthropic's documentation, the discovery summary and a request that the team design the system themselves, with you available for questions on request while you move on to the next project and leave operations to work out their own procedures and escalation paths during the first weeks.
General docs describe the platform, not your requirements, decisions or constraints. This abandons the architect's responsibility for architectural integrity.

Build exercise: Draft an architecture document skeleton, a dynamic diagram, a runbook and a handoff checklist

Advanced · 75 minutes

You'll practice:

Structure an architecture document that includes Claude-specific artifacts (prompts, model configuration, tool contracts, eval set)
Choose diagram levels for different audiences and mark trust boundaries and human review points
Write runbook entries that distinguish failure causes rather than prescribing blanket retries
Separate non-negotiables from team choices in implementation guidance and define done via acceptance criteria

Pick a scenario (for example a Claude-based invoice-processing service that extracts fields and routes exceptions to a human). Create a document skeleton with the sections from the lesson. Under each heading write one to three sentences of real content for your scenario, and mark any assumed items with an owner.

Filling every section with real content, however brief, reveals which decisions are missing before anyone writes code.

You should see: A skeleton of about a dozen sections, each with concrete content for your scenario and at least three items tagged 'assumed' with owners.
Hints
1. ```
Which section is hardest to fill in? That is likely where discovery or design is incomplete.
```
2. ```
Cover context and goals, constraints, views, components and interfaces (prompts, tools, model configuration), data, failure modes, quality and evaluation, observability and cost, security, decisions, operations.
```
3. ```
Example line: 'Model configuration: pinned model ID stored in one config file; extraction prompt v1.3 in repo; output validated against a JSON schema; any validation failure routes to the exceptions queue (owner: ops lead).'
```
Draw (in text, Mermaid or on paper) a C4 context diagram and a dynamic diagram of one request through the system. On the dynamic diagram mark the non-deterministic step, the validation step, each trust or data boundary, and each human intervention. Add a legend.

The dynamic view exposes failure and review points, and marking boundaries forces the data-handling conversation.

You should see: Two diagrams: a context view with users and external systems, and a sequence-style view with at least six steps where the model call, validator, boundary crossing and human review are visibly distinguished.
Hints
1. ```
Where can a wrong answer enter the system, and what stops it?
```
2. ```
Show numbered steps: receive document, assemble prompt, call model, validate against schema, route exceptions to a human, write to the ledger, log request ID and versions.
```
3. ```
Example legend: 'dashed line = data leaves our network to the model API (retention arrangement: see Data section); double border = component whose output is probabilistic; person icon = human decision point.'
```
Write two runbook entries for your system: one for a burst of 429 responses (including the case with no retry-after header) and one for a sudden rise in schema-validation failures after a release. Use the columns symptom, first checks, action, escalation and owner. Verify the error names and headers against Anthropic's current errors and rate-limit pages.

Runbooks written from the failure modes in the design prove that the design is operable and prevent 'retry until it works' folklore.

You should see: Two entries that give different diagnoses and actions, reference the request ID for support escalation, and cite the current documentation you checked.
Hints
1. ```
What is the very first thing an on-call engineer should look at, and what distinguishes one cause from another?
```
2. ```
For 429: read which limit was hit and whether retry-after is present; treat no retry-after with a spend message as a budget or cap escalation. For schema failures: compare against the last prompt, model or schema change, roll back, run the regression set.
```
3. ```
Example: 'Symptom: 429 with no retry-after and body mentioning a monthly usage threshold. Check: spend limits and tier cap in the console. Action: stop retries, page the owner, route to the manual queue, request a cap or limit change.'
```
Write the implementation guidance page for the build team: a list of five non-negotiables with a one-line reason each, a list of five team choices you deliberately leave open, the recommended build order (evaluation harness and thin slice first), and the definition of done tied to eval thresholds and runbooks.

This is the constraints-rationale-acceptance format that lets a team adapt sensibly instead of copying your code.

You should see: A one-page guidance sheet whose non-negotiables each have a rationale and whose definition of done refers to measurable gates rather than 'feature complete'.
Hints
1. ```
If the team hit a situation you did not anticipate, would the rationale help them decide correctly?
```
2. ```
Non-negotiables are about data boundaries, human approval of irreversible actions, pinned model and prompt versioning, and release gates. Team choices include framework, code layout and internal libraries.
```
3. ```
Example: 'Non-negotiable: no invoice is posted to the ledger without schema validation and, for amounts above the agreed limit, human approval (reason: an incorrect posting is costly to reverse). Team choice: queue technology, language and framework.'
```
Create the handoff checklist: walkthrough session, decision log links, eval set and thresholds, runbooks reviewed by operations, named contact and office hours, review checkpoints, document owner and review triggers. Then critique your own package: which single missing item would most increase the chance of an incident in the first month?

Handoff is a process with an owner. Naming the most dangerous gap makes you prioritise before launch.

You should see: A checklist of eight to ten items with owners and dates and a one-paragraph self-critique naming the biggest gap and how to close it.
Hints
1. ```
Who will be paged first at launch, and have they seen the runbook?
```
2. ```
Weigh each item by the probability that its absence causes a serious incident, and include operations in the review.
```
3. ```
Example critique: 'Biggest gap: operations has never exercised the spend-cap escalation. Action: run a tabletop with the on-call team before launch and record the outcome in the runbook.'
```

Sources

The C4 model for visualising software architecture - Simon Brown (C4 model)
Documenting Architecture Decisions (Michael Nygard) - Cognitect (Michael Nygard)
Architectural Decision Records (ADR GitHub organization) - ADR GitHub organization
Anthropic - Claude API errors - Anthropic
Anthropic - Rate limits - Anthropic
Anthropic - Workspaces - Anthropic
Anthropic - Model IDs and versioning - Anthropic
Anthropic - Building effective agents - Anthropic
Anthropic - Demystifying evals for AI agents - Anthropic