The Decision Record and the System That's Never Done

A diagram tells you what the system is. It does not tell you why it is that way, and six months later that missing why is what costs you. Someone on the operating team stares at a mid-tier model choice and a human gate on refunds, decides those look like inefficiencies, and “optimizes” them away. Nothing in the diagram recorded that the model tier was a deliberate cost-quality tradeoff the VP signed off on, or that the refund gate was a compliance requirement. Architecture documentation exists to prevent exactly that. This chapter is about what documentation is for. And it is about a harder fact: for a Claude system the document is never finished, because the system never is.

What architecture documentation is for

Documentation has two jobs, and most teams do only the first.

The first job is the handoff. You, the architect, are usually not the team that builds, runs, and operates the system for years. The document is how the design survives the transfer from your head to theirs: the components, how they connect, what each is responsible for, where the boundaries are. This is the part people remember to write, because it is the part that looks like documentation.

The second job pays off later: the document is a record of decisions and their rationale. Not what the system is, but why it is that and not the obvious alternative. Why the mid-tier model instead of the flagship. Why RAG instead of fine-tuning. Why a human gate on refunds above a threshold. Why the policy corpus is chunked one way and not another. Each was a real choice among real alternatives, made under constraints that were true at the time, and the reasoning is invisible in any diagram. A diagram shows the what. Only a decision record preserves the why, and the why is what a future engineer needs before they are safe to change anything.

The lightweight, durable form of this is the Architecture Decision Record, an ADR: one short entry per significant decision. Each entry captures four things. The context (what was true and what forced a choice), the decision (what you chose), the alternatives you rejected, and the consequences you accepted. A dozen of these tells the next team more than a hundred-page design manual. It gives them the shape of the reasoning, not just the shape of the boxes.

What to document, and what not to

The instinct is to document the diagram in exhausting detail and stop. Invert it. The diagram is the cheap part and drifts fastest; the reasoning is the expensive part and stays true longest.

Document, in order of value:

• The decisions and their rationale, the ADRs above.
• The requirements the design is meeting, especially the non-functional ones: the SLAs and constraints from discovery, so a future change can be checked against them.
• The interfaces and contracts between components: what each tool takes and returns, what the RAG layer promises.
• The operational runbook: how to tell it is healthy, what the alerts mean, what to do when each fires.
• And then the structural diagram.

Skip, or keep deliberately thin, the things that change faster than you can maintain the document. Exact prompt wording lives in version control, where it belongs, and a copy in a doc is a lie waiting to happen. Same for line-level implementation detail and anything the code already states clearly. Documentation you cannot keep true is worse than none, because it earns a trust it will betray. Write down the decisions, which are stable, and point at the code for the details, which are not.

The lifecycle, and the architect’s role in each phase

An architecture is not a deliverable you hand over and forget. It moves through phases, and the architect has a distinct job in each.

• Discovery. Turning a stated want into functional and non-functional requirements and a success metric, covered in the previous chapter. The architect leads. The output is the problem, the constraints, and the number that defines success.
• Design. Choosing the shape: the pattern, the model tiers, the RAG pipeline, the tool boundaries, the guardrails and human-in-the-loop gates. The architect leads, and the output is the design plus the decision records that explain it.
• Handoff. Transferring the design to the team that builds and operates it. The architect’s job here is to make the why transfer, not just the what, so the operators can make good local decisions later without re-litigating the whole design. This is where the ADRs and the runbook earn their existence.
• Monitoring. Watching the running system against the requirements: the SLAs, the cost ceiling, the quality metric, and the safety guardrails. The architect defines what to watch and what threshold means trouble, even when another team runs the dashboards. A system with no defined health signals is a system nobody can tell is failing until a customer does.
• Iteration. Feeding what monitoring reveals back into the design and changing it. The architect governs which changes are safe and which need re-evaluation. Some changes touch a constraint, a compliance boundary or an SLA, that cannot be moved without a new decision and a new sign-off.

The shape to hold: the architect leads discovery and design, ensures the handoff carries the reasoning, defines the health signals for monitoring, and governs iteration so changes stay inside the constraints. The role does not end at launch. It changes character.

Why a Claude system is never “done”

Traditional software, left alone, keeps behaving the same way. The code that passed its tests on launch day passes them a year later. A Claude system does not have that property, and this is the single most important thing to internalize about its lifecycle: it drifts even when you never touch it. Three forces guarantee it.

Models change. The model behind your system is not frozen. New versions ship and old ones deprecate on a schedule. Even a version bump you want can shift behavior on the exact edge cases your prompts were tuned against. A prompt that produced clean structured output on one model can regress subtly on its successor. The migration is not optional, because the old model retires, and it is not free, because the behavior can move. So a Claude architecture has to treat model change as a scheduled event it plans for, not a surprise.

Data drifts. The RAG corpus is a living thing. Policies get rewritten, the catalog turns over, help articles are added and go stale. The retrieval that grounded a correct answer in January grounds a wrong one in June, because the document it retrieved is now out of date. The stale-corpus failure from discovery is not a one-time check. It is a standing condition the system must be monitored against.

Requirements move. The business changes. A new SLA, a new regulation, a new product line, a new definition of a resolved ticket. The system that met the requirements is now measured against different ones.

Because of these three, monitoring and iteration are first-class architectural concerns, not afterthoughts you bolt on if there’s time. A design with no plan for how it will be watched and changed is not a finished design. It is an unfinished one that happens to run. You budget for the iteration loop up front, the same way you budget for the model tier, because you know with certainty that you will need it.

The iteration loop, fed by evals

The engine that makes iteration safe rather than superstitious is evaluation. The evals built in Arc 4 are not a one-time gate you clear before launch and retire. They are the instrument that closes the lifecycle loop. Monitoring detects that quality has slipped or a new failure pattern has appeared. The eval suite quantifies it and localizes it. You change the design or the prompt or the corpus, then re-run the same evals to prove the change helped and broke nothing else. Without that suite, every iteration is a guess and every model migration is a leap of faith. With it, “the new model is better for us” and “the corpus refresh fixed the refund answers” become claims you can demonstrate rather than hope. The eval harness is what turns the system is never done from a threat into a managed, ongoing practice.

The bookshop platform, documented and operated

Give the bookshop support platform the treatment.

Its decision record is a handful of ADRs, each one a rejected alternative made legible:

• Mid-tier model with difficulty-based escalation. Rejected: flagship throughout, too costly for a mostly-simple ticket mix. Rejected: small model throughout, misses the quality bar on hard cases.
• RAG over the policy corpus. Rejected: fine-tuning, because policies change weekly and retrieval keeps answers current where a fine-tune would freeze them.
• Human gate on refunds above a threshold. Rejected: full autonomy, because the action is irreversible and the compliance boundary requires review.

Anyone who later wants to “simplify” the escalation logic or drop the refund gate reads why it is there before they touch it.

The handoff to the ops team carries the runbook: the SLAs to watch (p95 latency, cost per ticket, resolution rate), the quality signal from the eval suite, the guardrail alerts, and what each alert means and who acts on it. It tells them what healthy looks like, so they can see unhealthy.

The iteration loop is live from day one. When the next model version ships, they re-run the evals against it before migrating, because model change is scheduled, not surprising. When the policy corpus is refreshed, the retrieval evals confirm the assistant still answers refund questions correctly. When resolution rate on enterprise accounts dips, the failure-diagnosis evals localize whether it is retrieval, the model tier, or a drifted requirement. The platform is never done, and the documentation and the eval suite are exactly what let it keep being good anyway.

What the exam is really checking

Domain 6 items here probe whether you treat a Claude system as a project that ends or a system that lives. The trap answers document the diagram and call it finished, treat launch as the finish line, or assume a system that passed its evals once will keep passing them untouched. The credited answers do four things. They record the decisions and their rationale, not just the boxes. They carry the why through the handoff. They define what monitoring watches. And they budget for iteration, because model drift, data drift, and moving requirements make it inevitable. An architect who can name the lifecycle phases and say why a Claude system is never done is answering the real question these items ask.

Next: enabling the team that builds and operates it — Claude Code conventions for a team, AI-assisted developer workflows, and supporting operational issue resolution.