Home › Study guides › CCAR-P › Domain 6 › Lesson 6.2

CCAR-P · Domain 6 · 14% of the exam · Lesson 6.2 · 24 min read

Communicating architecture decisions: records, audiences and honest trade-offs

How to write a decision record, present one decision to executives, security and engineers, state trade-offs honestly, and change course when evidence moves.

Written against objective 6.2 of the official CCAR-P exam guide (Version 1.0, effective July 2026). An independent resource, not affiliated with Anthropic; the practice questions are written from scratch.

6.2.1 Why a sound design can still be turned down

Yasmin is the solution architect at Tidewright Lines, a global container-shipping line. Customers send about 2,400 booking amendments a day, such as moving containers to a later sailing. A customer-operations desk answers them in about four hours, and a slow answer can leave a container on the quay.

Yasmin recommends a routing workflow. Claude labels each request with its type, and code sends the six standard types down fixed paths. On each path Claude fills in the change, and code checks it against the booking rules before applying it. An agent, in which Claude chooses its own steps and tools, handles only the exceptions and drafts a resolution for a person to approve. On 500 past amendments, this design matched a fully agentic one on the standard types at about a fifth of the model cost.

She presents it to three people in one meeting, with one 30-slide deck. Gunnar, the CIO (chief information officer), has seen a vendor demo in which a single agent handled every amendment, and asks why Tidewright should build something with more parts. Beatrix, the CISO (chief information security officer), asks where booking data goes and what can write to the booking system; the only diagram shows components, not data. Mateus, head of customer operations, asks what his desk will do on the first Monday, and no slide answers him. The meeting ends with "let's take this offline", which is how sound designs quietly die.

Nothing was wrong with the design; the communication failed. The decision was never written down in a form each person could check. Every audience got the same material instead of the answer to its own question. And the measured comparison with the design the CIO already liked never reached the deck. The tools that fix this are a decision record that states the choice once, a view of it per audience, trade-offs stated as measured rates, and a few pictures that carry the argument.

6.2.2 The decision record: one choice, written down once

Here is the question that catches architects out: the design is already in the slides, tickets and code, so why write it down again? Because none of those say WHY. Six months after launch, someone will ask why the agent cannot write to the booking system, and the answer will live in one person's memory. A decision record, often called an architecture decision record (ADR), captures one significant choice: what forced it, the options considered, the choice, and what it costs. It is short, numbered and dated, and every presentation draws from it.

Each part answers a question a stakeholder will ask; the last column shows how it fails in practice.

Here is Yasmin's record. Look at the options line, which includes the design Gunnar prefers, and at the consequences, which name what the chosen design gives up.

ADR-014: Booking amendments run as a routing workflow; an agent drafts only the exceptions.
Status: Accepted, 12 September 2026. Supersedes: none. Owner: Yasmin (architecture). Decides: Gunnar (CIO). Consulted: Beatrix (CISO), Mateus (customer operations), booking-platform engineering.
Context: about 2,400 amendment requests a day, answered in about four hours; 85% fall into six standard types. A wrong amendment can put cargo on the wrong sailing. Requirements: standard amendments applied within 15 minutes; every write to the booking system passes a rule check or a named person; model usage costs less than the desk hours it frees.
Options considered: (A) one agent handles every amendment, with read and write tools. (B) a router sends the six standard types down fixed paths with checks in code, and exceptions to a read-only agent that drafts for the desk. (C) keep the desk and add reply templates. All three measured on the same 500 past amendments.
Decision: B. It matched A on standard types (97% against 96% applied correctly) at about a fifth of the model cost per amendment, and no model output reaches the booking system without a code check or a person.
Consequences: standard amendments applied in under a minute. Exceptions (about 15%) still wait for the desk, now with a draft; A's drafts were slightly better (64% usable as written against 61%). The router is a new component to evaluate and monitor. On the test set, about 1 in 100 standard amendments would have been applied wrongly and the rule check sent another 2 in 100 to the desk; every customer receives a confirmation of the change.
Assumptions: the exception share stays near 15%; the booking platform delivers an amendment-only write permission before the pilot.
Dissent: Gunnar prefers one agent for flexibility; accepted B on the evidence, reopen as below. Mateus asked for the agent to apply exceptions directly; declined by Beatrix for now, because a wrong draft costs a person a minute and a wrong write can cost a sailing.
Revisit when: exceptions exceed 25% of volume for four weeks; one exception type is approved unchanged in at least 98% of 500 or more drafts; a new model changes the evaluation results.

Three details make it defensible. Every option was measured on the same 500 amendments, so nobody argues from a demo against a test. The consequences include a number that favours the rejected option, which makes the rest believable. And the triggers are conditions a dashboard can watch, so "revisit it someday" becomes a commitment.

Records belong together in a decision log, a numbered list under version control beside the architecture documents, so every change has an author and a date. A status of proposed, accepted, rejected or superseded tells a reader at a glance whether a record still holds. The log is append-only, like a ship's logbook: a wrong entry is never erased, a later one corrects it, and the page still shows what the officer knew at the time. So you never rewrite an accepted decision; a new record supersedes it. Write a record when a choice is costly to reverse, contested, or crosses a team boundary such as security or operations.

6.2.3 One decision, several audiences

Does tailoring mean telling each audience a different story? No. Tailoring changes the entry point and the depth, never the facts. Think of a building's drawing set: the owner sees the elevations, the electrician the wiring plan, the fire inspector the escape routes, and every sheet describes the same building. Each stakeholder arrives with a decision they must make or a risk they own. A view that starts there gets read; a view that starts anywhere else gets skimmed.

The executive and security views differ the most, so here are both.

Executives read the top of a page and stop, so the decision you need from them goes first. Here is the top of Gunnar's page; every number on it comes from the record.

Decision needed: approve a pilot on the Asia to North Europe lane, and the booking-platform work it depends on (ADR-014).
Outcome: the six standard types (85% of amendments) applied in under a minute instead of about four hours; the desk keeps the other 15%, each with a drafted resolution.
Cost: about $0.05 of model usage per amendment, roughly $3,600 a month at today's full volume; the single-agent design measured about $0.24.
Main risk: on the test set, about 1 in 100 standard amendments would have been applied wrongly. Every customer receives a confirmation of the change, and the desk corrects reported errors.
Timeline: pilot live in 10 weeks; a go or no-go decision on agreed targets after 12 weeks of live traffic.

Beatrix needs the opposite shape: less value, more mechanism. Her key sentence comes from Anthropic's tool-use documentation: the model never executes anything on its own. For tools you define, it emits a structured request, and your code runs the operation. So Claude returns labels, fields or drafts, and only the workflow service, holding an amendment-only permission, writes to the booking system after its checks pass. Her view ends with the risk that remains and who owns it: a misread request that still passes the rule check, caught when the customer reads the confirmation, and owned by Mateus.

Engineers get the contracts behind it: the amendment schema, the router's labels, the permission scope and cut-off handling. The one rule across all views is consistency. If Gunnar hears "fully automated" and Mateus hears "your desk keeps 15%", they will compare notes, and trust leaves with the discrepancy.

6.2.4 Stating trade-offs without overselling

After six weeks of work you want a yes, and the easiest way to get one is to sell. Resist it. An oversold decision wins the first meeting and loses every one after it: the first wrong amendment in production is measured against "the system handles amendments", not "about 1 in 100".

Start by naming what each option buys and what it pays. Anthropic's model guide frames model choice as balancing capabilities, speed and cost, and its guidance on agents says agentic systems often trade latency and cost for better task performance. Add a fourth currency, control, and say out loud what your choice gives up, as Yasmin's record does: the router is a new component that can misroute.

Next, state quality as a measured rate, never an adjective. Claude's behaviour is probabilistic: the same request can come back worded differently on another run, and a request near a category boundary can be classified differently. Anthropic's hallucination guidance says even the most advanced models sometimes generate text that is factually incorrect or inconsistent with the given context, and suggests comparing several runs of the same prompt to spot it.

Think of a good weather forecaster. She never promises sunshine; she says "70% chance of rain", and people trust her because it rains on about 70% of those days. Anthropic's evaluation guide makes the same point: it calls "safe outputs" a weak success criterion and a rate over a stated number of trials a strong one. So Yasmin says "97% of 425 standard amendments", then says what happens to the rest.

Averages also hide the segment someone owns. Dangerous-goods amendments are 2% of volume and barely move the headline, yet a wrong one is a safety incident that the dangerous-goods team answers for. So they get their own line in every view: all of them go to the desk. Finally, list what the design does not solve: phone amendments stay manual, wrong master data stays wrong, and exceptions still need people.

6.2.5 Pictures that carry the argument

Which diagrams belong in a decision pack? Fewer than you think, each answering one question. A context diagram shows what is inside the system and every person and system it talks to; it is the first picture for every audience. A data-flow diagram follows the data itself: what crosses which trust boundary, where each control sits, and what can write where. An option comparison table shows what you chose from, and on what evidence.

For Beatrix, the data-flow view splits by path, because the two paths carry different risks.

What leaves Tidewright for the Claude API? The request text and the booking lines needed to answer it, never payment details. What happens to it there? Yasmin quotes the arrangement Tidewright actually has, from its contract and Anthropic's data-retention page. Under zero data retention (ZDR), which Anthropic enables per organization on request, Anthropic does not store prompts or responses after returning the response. Even the model choice shows up here: the same page lists models, Claude Fable 5.1 among them, that require 30-day retention and are not available under ZDR unless Anthropic expressly authorizes it. Vendor documents cover the vendor's side of the boundary; the diagram covers Tidewright's.

The comparison table is where the argument is won or lost. Anthropic's evaluation guide notes that most use cases need evaluation along several criteria, and the table shows them side by side.

Read it by the requirements that decide. C misses the 15-minute target, and A lets model output write without a check, so B is the only option that meets both. The row where A wins stays in, because a table that only shows your option winning reads as a sales pitch.

6.2.6 Disagreement, and changing your mind in the open

Gunnar still prefers the single agent. What now: argue harder, or quietly build whatever the most senior person in the room wants? Neither. First work out what kind of disagreement it is, because each kind is settled differently.

• About facts ("the agent costs about the same"). Settle it with evidence: run the contested option on the same test set.
• About priorities ("flexibility matters more than cost"). The accountable decision maker weighs the criteria, and the record states the weighting.
• About risk appetite ("let the agent write exceptions directly"). The owner of that risk decides, which for a security control is Beatrix.

Running the vendor's design on the same 500 amendments had already settled the facts. The priorities were Gunnar's to weigh as the accountable executive, and with the measured costs in front of him he chose B while still valuing flexibility. So the record answers his preference with a trigger: if exceptions pass 25% of volume, the case for a broader agent reopens. Mateus's request for direct writes went to Beatrix as a risk question, and she declined it for now. Both objections sit in the record as dissent, each with the condition that would change the answer. That is disagree and commit: everyone builds the decision fully, and nobody relitigates it, because the route back is written down.

Four months after launch, a trigger fires. Reefer amendments (temperature settings for refrigerated containers) prove predictable: the desk approved 99% of about 11,000 agent drafts unchanged. Yasmin writes ADR-021, which restates the design with reefer corrections on a workflow branch of their own, checked in code against the cargo's allowed temperature range. ADR-014's status becomes "Superseded by ADR-021"; its text stays as it was, so anyone can see what was decided then and why. Then each audience hears what changes: Mateus's exception queue drops from 15% to about 11% of volume, Beatrix hears that every write still passes a code check, and Gunnar's cost per amendment falls slightly.

A reversal made this way does not cost credibility: the triggers were agreed in advance, so the change is the process working, not the architect backing down. What destroys trust is the same change made quietly in configuration, with the record still describing a system that no longer exists.

6.2.7 The exam traps

Every trap is a shortcut that ends a meeting sooner and costs trust later.

• ✗ One deck for every audience, or a technical specification sent to executives. ✓ One decision record, and a view per audience that starts from what it decides or owns.
• ✗ Different facts for different audiences: "fully automated" for the board, "assistive" for operations. ✓ The same numbers in every view, each pointing back to the record.
• ✗ Showing only the recommended option, or answering a favoured alternative with opinion. ✓ Every serious option, the status quo and the stakeholder's favourite included, measured on the same evidence.
• ✗ Quality as an adjective, an average or a demo. ✓ A rate on a named test set, segmented where a stakeholder owns the segment, with what happens to the failures and what stays unsolved.
• ✗ Answering the security reviewer with vendor certifications and the model's safety training. ✓ The system's own data flows, the control at each step and the residual risk with its owner; vendor documents cover only the vendor's side.
• ✗ Settling disagreement by seniority, or changing a decision by quietly editing the old record. ✓ Settle it by its kind, record the dissent, and supersede with a new record when a trigger fires.

6.2.8 Put it together: write the record and present it three ways

You now have every piece: the record, the audience views, honest trade-offs, the pictures, and a way to change course. The quickest way to make it stick is to build the pack for a real decision, then watch one careless edit break it.

The rest of Domain 6 builds on this pack. Managing expectations and SLAs (6.3) turns the rates in your record into commitments stakeholders can hold you to. Documenting architectures (6.4) grows the engineering view into implementation guidance for the build team. Supporting the lifecycle (6.5) turns revisit triggers into signals you monitor after launch.

Key takeaways

• ✓ A sound design still stalls if the decision is not written down, not answered in each audience's terms, and not set beside the option someone already prefers on the same evidence.
• ✓ A decision record states one choice: status and owners, context and deciding requirements, options on the same evidence, the decision, consequences, assumptions, dissent and revisit triggers, kept in an append-only decision log.
• ✓ Tailor the entry point, never the facts: outcome, risk, cost and timeline for executives; data flows, controls and residual risk for security; interfaces and constraints for engineers.
• ✓ State trade-offs honestly: what each option buys and pays, quality as a measured rate segmented by what stakeholders own, and what the design does not solve.
• ✓ A context diagram, a data-flow diagram and an option comparison table carry most arguments, and the table keeps the rows your choice loses.
• ✓ Settle disagreement by its kind, record dissent with the condition that reopens it, and when a trigger fires, supersede the record in the open and tell each audience what changes.

Check your understanding

4 questions written for this lesson, then one from the CCAR-P question bank on the same topic. Every answer option is explained, including the ones you did not pick. Nothing is stored.

Sources

• Building effective agents
• Choosing the right model
• Define success criteria and build evaluations
• Reduce hallucinations
• How tool use works
• API and data retention
• The CCAR-P exam guide, summarised