Communicating architectural decisions and trade-offs

1.What a well-stated trade-off contains

The clearest model for communicating an architectural decision is the way Anthropic documents its own architectural options. Take the advisor tool, where a faster executor model consults a higher-intelligence advisor mid-generation. The documentation does not simply recommend it. It names the gain in one sentence — you get "close to advisor-solo quality while the bulk of token generation happens at executor-model rates" — and immediately prices that gain against the alternative you would otherwise pick.

The pricing is stated per starting position, not in the abstract. For a team already on Haiku, adding an Opus or Fable advisor means: "Expect higher cost than Haiku alone, but lower than switching the executor to a larger model." That is the shape a stakeholder can actually use. It compares the proposal to the thing they would have done instead, in the currency they care about, rather than asserting that the new option is better.

The missing element is the negative case. The same page says the pattern is a "weaker fit for single-turn Q&A (nothing to plan)" and for workloads where every turn needs the stronger model anyway. Publishing the conditions under which your own recommendation fails is what makes the rest of it credible — and it is the part architects most often omit when presenting to a decision-maker who has already heard the upside.

Finally, the doc bounds its own confidence: "Results are task-dependent. Evaluate on your own workload." A decision communicated without its uncertainty invites the stakeholder to treat your estimate as a guarantee, and you inherit the gap when reality differs. The Claude Code advisor page compresses all of this into a two-column table of pairings against when to use each — for example, Sonnet main with an Opus advisor, where "Sonnet handles routine work and escalates planning, ambiguous failures, and completion checks to Opus". Each row is a decision, its rationale, and its intended situation, in one line.

Sources12

2.Putting the options in front of the decision-maker

A single recommendation with its trade-offs attached is one artefact. A genuine architectural choice usually needs several candidates visible at once, because stakeholders compare before they commit. Claude Code's artifacts feature is built for exactly this use: among its listed uses is to "Lay out several design or implementation options side by side", published as a page rather than pasted as a wall of text.

The worked prompt on that page is a good template for the format itself: "Make an artifact with four distinctly different layouts for the settings panel." — and crucially, "lay them out as a grid with a one-line tradeoff under each." Four options, one line of trade-off apiece. The discipline of one line per option forces you to identify the single dimension on which each candidate actually differs, which is the comparison the audience is trying to make.

The same pattern appears in Anthropic's prompting guidance for design work, where the recommended prompt has the model propose distinct directions with a one-line rationale each and then "Ask the user to pick one, then implement only that direction." Propose, let the owner choose, then build only the chosen thing. Presenting options is not indecision; it is how you avoid spending implementation effort before the decision has an owner.

Delivery format follows audience. The artifacts page frames publishing as a way to "Send a teammate a link instead of pasting output into Slack", with the page living somewhere the reviewer can open it later. Claude Design makes the audience split explicit in its export options, which differ depending on whether you are "getting stakeholder feedback, handing off to engineering, or presenting to a group". The content of the decision is the same in all three cases; the container is not, and choosing the wrong container is a common reason a sound architectural argument fails to land.

Sources345

3.Making the decision outlive the conversation

A decision communicated once, in a meeting or a thread, decays. The people who join later inherit the architecture without the reasoning, and quietly re-open settled questions. Communication is therefore not finished at the presentation — it finishes when the decision is written somewhere the work itself reads.

In a codebase, that place is the project's context file. Claude Code's best-practices guidance lists "Architectural decisions specific to your project" among the things worth including in CLAUDE.md, alongside conventions and the non-obvious gotchas every new engineer trips on — and excludes anything a reader could work out from the code. The filter is rationale: record what could not be reconstructed by inspection, which is precisely the decision and its trade-off, not the implementation that resulted.

Keep the record short enough to stay read. The guidance is to "Aim for a file that is short and signal-dense", with every line earning its place in context, and to "Review the draft, remove anything inaccurate, and commit it" when starting from a generated draft. One entry it explicitly rules out is worth naming to stakeholders: "Aspirational rules the team does not actually follow." A decision record that describes the architecture you wish you had trains everyone who reads it to distrust the rest of the document.

Sources67