The Human Architect: Judgment, Communication, and Leadership

Why it matters#

The first eighteen chapters were about building a system. This one is about the person building it. AI has made producing code, diagrams, and documents cheap, which moves the scarce work up a level: choosing among options, explaining choices to people who'll live with them, judging whether generated work is right, and taking responsibility for the result.

That work has always been part of architecture. It matters more now for three reasons:

• More output needs more judgment. An agent can draft ten designs in an hour. Somebody has to know which one fits the constraints, and why.
• Fluent isn't the same as correct. Generated documents read well whether or not they're true. Chapter 13 described a study in which people using an AI assistant wrote less secure code yet were more likely to believe it was secure (Perry et al., 2023). Confidence has to come from evidence.
• Decisions affect people. The early-alert request isn't a technical question with a technical answer. It touches students' trust, advisors' workload, privacy rules, and the product's original promise. An architect who can only speak to engineers can't help make it.

Learning objectives#

After this chapter you will be able to:

1. Make architecture decisions under constraints, distinguishing reversible from irreversible choices and documenting assumptions and uncertainty.
2. Present a design to engineers and to product and business stakeholders, each in their own terms.
3. Write concise decision records and run an architecture review.
4. Keep accountability with people when agents do much of the work, with review gates, ownership, and mentoring.
5. Evaluate architecture quality with scenarios, traceability, fitness functions, and evidence-backed tradeoff narratives.
6. Produce a five-slide design review, an ADR bundle, and a risk-response memo.

19.1 Architecture is decision-making under constraints#

Balancing speed, cost, reliability, and security#

Every chapter's decision table had the same shape: context, constraints, options, decision, tradeoffs. That shape is the job. You rarely get to maximize everything. Faster delivery usually means less verification; more reliability costs money; tighter security adds friction. The architect's contribution is making the trade explicit, so the people who own each concern can see what they're giving up.

For Dr. Hale's request, the concerns pull in different directions:

No option satisfies every row. Saying so out loud is the start of a good decision.

Reversible and irreversible decisions#

Not every decision deserves the same care. In his 2015 letter to shareholders, Jeff Bezos distinguished one-way doors, consequential decisions that are hard or impossible to reverse and should be made slowly and carefully, from two-way doors, reversible decisions that should be made quickly by individuals or small groups with good judgment. He warned that organizations tend to apply the slow process to everything, and become slow and afraid to experiment as a result (Bezos, 2016).

The distinction maps well onto architecture:

• Two-way doors: a library choice behind an interface, a prompt version behind a flag (chapter 17), a cache setting, a feature tried with three courses. Decide quickly, measure, adjust.
• One-way doors: data that leaves your system, promises made to users, schema changes that discard information, public APIs others build on, a vendor contract with a long commitment. Slow down, consult, write it down.

Sending a student's Behind flag to an advisor is a one-way door. Once an advisor has read it, it can't be unread, and a student who feels reported doesn't forget. Expanding to 25,000 students can be made mostly two-way: staged, course by course, with a way to pause.

A good architect also turns one-way doors into two-way doors where possible: a pilot instead of a launch, a flag instead of a migration, an opt-in instead of a default.

flowchart TD
    D["A decision to make"] --> Q1{"Can it be undone cheaply,<br/>including for users and data?"}
    Q1 -- "Yes: two-way door" --> F["Decide quickly in the team.<br/>Flag it, measure it, short ADR."]
    Q1 -- "No: one-way door" --> Q2{"Can we make it<br/>reversible first?"}
    Q2 -- "Yes" --> P["Pilot, opt-in, flag, or prototype.<br/>Then decide with evidence."]
    Q2 -- "No" --> S["Slow down: options, consultation,<br/>review with stakeholders, full ADR,<br/>named owner and revisit trigger."]
    P --> Q1

Documenting assumptions and uncertainty#

Decisions are made with incomplete information. Write down what you don't know, so others can see how much the decision depends on it, and so you notice when an assumption turns out wrong. For each important assumption, record:

• The assumption: “About 20% of students are Behind in a typical week.”
• The evidence so far: measured in the pilot? estimated? guessed?
• What changes if it's wrong: “At 40%, advisors receive 10,000 alerts a week and ignore them.”
• How and when you'll check it.

Use plain labels throughout your documents: measured, estimated, assumed. The failure clinic shows what happens when an estimate is written as a measurement.

Knowing when to prototype rather than commit#

When the uncertainty is about whether something works at all, or whether people will use it, a prototype is cheaper than a debate. Prototype when:

• the open question can be answered in days by building something small;
• the decision is otherwise a one-way door;
• stakeholders disagree about what users will do.

With agents, prototypes are cheap, which is the opportunity and the trap. A prototype answers one question and is then thrown away or rebuilt properly. Label it, give it an end date, and don't let it quietly become production.

19.2 Communicating architecture#

Presenting to engineers#

Engineers want to know how the design works, where it can fail, and what it means for their next week. Show the C4 container and component views, data flows, the failure modes and fallbacks, the decision records, and what the work looks like as tasks. Expect hard questions about edge cases, and welcome them; they're free testing.

Presenting to product and business stakeholders#

Stakeholders outside engineering decide on outcomes, risks, and money. The C4 model's system context diagram is built for this audience: the system as one box, its users, and the systems it talks to, readable without technical knowledge (Brown, C4 model). Beyond that one diagram, speak in their terms:

• Lead with the decision you need from them, then the recommendation.
• Show options, not just your answer, each with what it means for users, cost, risk, and time.
• Put risks in their language: “a student wrongly flagged gets a worried email from an advisor,” not “false positive rate on the weekly state transition.”
• Say what you don't know, and how you'll find out.
• Keep the deck short. Answer questions from backup material, not from the main story.

Writing concise decision records#

Chapters 5 through 18 wrote ADRs with Nygard's sections: title, context, decision, status, consequences (Nygard, 2011). For larger proposals, a design document explains the problem and the proposed design before building. Malte Ubl's description of design docs at Google emphasizes that their value is in the trade-offs: a design doc records the context, the goals and explicit non-goals, the design, and the alternatives considered, which he calls one of the most important sections because it shows why the chosen design is best for the goals. He also warns against writing one when the document would just be an implementation manual with no real trade-offs to discuss (Ubl, 2020).

Keep both short. An ADR fits on one page. A design doc for a feature like early alerts should be a few pages, readable before the meeting.

Agents are useful drafters here, as long as you write the decision. Ask an agent to draft the context from the repository and list options; then write the recommendation, the tradeoffs, and the revisit trigger yourself. If you can't write those, you haven't decided yet.

Conducting architecture reviews#

An architecture review is a meeting where people with different stakes examine a design before it's built or before a big change. It can be a lightweight comment thread on a design doc or a formal meeting; Ubl notes that reviews add value but can become a trap of overhead, so match the weight to the decision (Ubl, 2020).

Run reviews of one-way doors like this:

1. Send a pre-read at least two days before: the design doc or a one-page summary, with the decision being asked for.
2. Invite the people who own the concerns: security, privacy, users or their representatives, operations, the business owner.
3. Open with the decision and the options, not the architecture.
4. Walk through scenarios (section 19.4), each owner raising theirs.
5. Close with a recorded outcome: approved, approved with conditions, or not yet, with the conditions, owners, and dates.
6. Write it into the ADR the same day.

Mediating disagreements#

Reviews surface disagreement, and that's their purpose. Dr. Hale and Priya wanted different things for good reasons; neither was wrong. The architect's job is to turn a clash of positions into a comparison of options against shared goals.

Google's code review guidance offers principles that work beyond code. Technical facts and data overrule opinions and personal preferences. Design questions are rarely pure preference; weigh them on principles, and if several options are equally valid, accept the author's choice. When written discussion stalls, talk face to face, then record the outcome where future readers will find it. If that fails, escalate to someone with the authority to decide, rather than letting the work sit (Google, The Standard of Code Review).

In practice:

• Restate each position until its holder agrees you've got it right. Many disagreements end here.
• Find the shared goal. Dr. Hale and Priya both wanted struggling students to get help.
• Ask what evidence would change each mind, then go and get it, or design a pilot that will.
• Name who decides. For the early-alert question, the university decided; the team's job was to make the options and consequences clear.

19.3 Working with people and agents#

Accountability can't be delegated to a model#

An agent can write the code, the tests, the deck, and the memo. It can't be accountable for them. Accountability means someone who can be asked “why?”, who can be wrong and fix it, and who answers to the people affected. A model can't attend the review, can't be trusted by Ms. Duarte, and can't apologize to the 38 students in a way that means anything.

Google's code review guidance puts it simply: the reviewer has ownership and responsibility for the code they review (Google, The Standard of Code Review). When an agent writes and another agent reviews, a person still approves, and that person owns the result.

In practice:

• Every change, document, and decision has a named human owner, recorded in the pull request or ADR.
• The owner can explain it without asking the agent. If not, it isn't ready.
• “The agent did it” is never a cause in a postmortem. The cause is what let an unchecked change through.

Human review gates for risky changes#

Chapter 4 named the risky zones; chapter 11 set agent autonomy levels. As the team grows, make the gates explicit, with an owner for each:

Gates should be few and meaningful. Google's guidance argues reviewers should approve a change once it clearly improves the code's health even if it isn't perfect, and should mark minor points as optional so they don't block progress (Google, The Standard of Code Review). Save the hard stops for what can hurt people.

Collaboration, code ownership, and mentoring#

With three people, ownership is simple: Maya owns architecture, security, and data; Sam owns testing, releases, and operations; Lena, two days a week since April, owns the summary and notifications modules. Each module's instruction file names its owner.

Mentoring needs more thought, because AI changes how people learn. In a randomized study by Anthropic researchers, 52 mostly junior developers learned a new Python library with or without an AI assistant. The AI group scored 17% lower on a quiz about the concepts they'd just used (50% versus 67%), with the largest gap on debugging. How people used AI mattered: those who asked conceptual questions or requested explanations scored much better than those who delegated the work. The authors note the sample was small and the quiz immediate (Shen & Tamkin, 2026).

For Lena, Maya and Sam adopted three habits:

• Explain-back. Before an agent's pull request is merged, its owner explains to a teammate what it does and why, without reading from the agent's summary.
• First drafts by hand. Lena writes the first draft of ADRs for her modules herself; the agent critiques it, not the other way round.
• Debug before delegating. When something breaks in her modules, she spends the first half hour diagnosing without an agent, then uses one to check her reasoning.

Code review is mentoring, too. Google's guidance encourages educational comments that help a developer learn, marked as optional when they aren't required (Google, The Standard of Code Review).

Responsible use of AI in team workflows#

Write the team's rules down, in the repository, where agents read them too:

• Approved tools only for code and data, with the provider settings recorded (chapter 15). No student data pasted into personal accounts.
• Disclose AI's part in pull requests and documents: what was generated, what was checked, by whom.
• Claims need evidence. Numbers, test results, and compliance statements in any document link to their source or are labeled as estimates.
• People decide anything about users' rights, privacy, fairness, or access. Agents may list the questions.
• Credit and blame are human. Praise the person who caught the problem; fix the process that let it through.

19.4 Evaluating architecture quality#

How do you know an architecture is good? Not by how it looks. By whether it does what its stakeholders need, under the conditions it will face, and whether you can show it.

Scenario-based review#

The Software Engineering Institute's Architecture Tradeoff Analysis Method (ATAM) evaluates an architecture against quality goals using scenarios: concrete situations, each with a stimulus and a desired response. The analysis identifies risks, non-risks, sensitivity points (decisions a quality depends on heavily), and tradeoff points (decisions that affect several qualities at once). A full ATAM takes a trained team three to four days with the architects and stakeholders (SEI, ATAM).

A small team can borrow the core idea in an afternoon (an adaptation, not the full method). Each stakeholder brings two or three scenarios; the team walks each through the design:

Five scenarios, and the real issues surface: accuracy, capacity evidence, transparency, and deletion. None of them was on the twenty-two slides.

Traceability from requirements to evidence#

Traceability is being able to follow a line from each requirement to the decision that addresses it and the evidence that it's met. Without it, “we meet NFR-6” is an opinion.

flowchart LR
    R["Requirement<br/>NFR-6: deletion within 7 days"] --> S["Scenario<br/>student deletes account<br/>after a restore"]
    S --> D["Decision<br/>ADR on deletion replay"]
    D --> F["Fitness function<br/>deletion replay test in CI;<br/>quarterly restore drill"]
    F --> E["Evidence<br/>last drill: date, result,<br/>214 orphaned files found and fixed"]
    E --> ST["Status<br/>met, with link"]

Keep a traceability table in the repository: requirement, decision, check, latest evidence, status. Agents are good at building and updating it; people check that each evidence link really shows what it claims.

Architecture fitness functions#

A fitness function, a term borrowed from evolutionary computing and popularized by the book Building Evolutionary Architectures, is an objective, automated assessment of an architectural property; it can be a test, a metric, or a monitor. Thoughtworks recommends them as a way to communicate, validate, and preserve architectural characteristics continually (Thoughtworks, 2017).

The Learning Coach already has several, built in earlier chapters without the name:

When you make an architecture decision, ask: what fitness function will tell us if we stop meeting it? If there isn't one, the decision will erode.

Evidence-backed tradeoff narratives#

A tradeoff narrative is a short paragraph that explains a decision to someone who wasn't in the room: what you chose, what you gave up, the evidence, and what would change your mind. It's what you say when Dr. Hale asks “why not just send the flags?”

We recommend letting students choose to share a weekly progress summary with their advisor, instead of sending Behind flags automatically. We give up reaching students who don't opt in, which matters, because those may be the students who most need help. We chose this because the flag has been wrong at scale once already (38 students in March), because students told us they'd stop entering real dates if flags were shared (pilot interviews, 11 of 14), and because data sent to the university can't be recalled under our deletion promise. We'll measure opt-in rates and advisor outcomes in three courses this fall. If fewer than a third of students opt in, or advisors report the summaries aren't useful, we'll bring this decision back to the panel.

Every claim in it points to evidence or is labeled. That's what makes it persuasive to a skeptical audience.

Architect's decision: how should the Coach support early alerts?#

AI collaboration recipe#

Agents can help you prepare to decide and communicate. They shouldn't decide, and they shouldn't speak for you without your check.

1. Draft for an audience.

Here is our design doc and ADR-016 draft. Write a five-slide outline for a review panel of: an associate provost, an IT security lead, a privacy officer, a faculty member, and a student representative. Slide 1 states the decision we need. Use no diagrams except one system context diagram. For each slide, list the questions each panel member is likely to ask and where the answer is in our documents.

2. Find the scenarios we're missing.

For each stakeholder role above, propose three scenarios (stimulus and desired response) that could reveal a risk in this design. Mark which ones our current documents don't address.

3. Claim check.

List every factual claim in this memo: numbers, test results, comparisons, compliance or legal statements. For each, give the source in the repository that supports it (file, test run, dashboard link), or mark it UNSUPPORTED. Don't rewrite anything.

4. Red team the recommendation.

Argue as strongly as you can against ADR-016's decision, from the viewpoint of the associate provost who wants automatic alerts. Then list what evidence would settle each argument.

Boundaries to state every time:

• “Draft and list; don't decide.”
• “Mark anything you can't source as UNSUPPORTED.”
• “No legal or compliance conclusions; list them as questions for the privacy office.”
• “Use only the documents provided; say when something isn't in them.”

Worked example: five slides and a second review#

1. Restart from the decision. Maya wrote one sentence before touching slides: “We need the panel to choose how the Coach supports advisors, and to approve a staged expansion.” Everything else had to serve it.

2. Gather the stakes. Sam and Maya spent an hour with each panel member before the meeting. Ravi's concern was single sign-on and who would be on call. Ms. Duarte's was the legal basis and deletion. Dr. Okafor's was instructor workload. Priya brought 14 short student interviews from the pilot courses; 11 said automatic sharing would change what they entered.

3. Run the scenarios. The team walked the five scenarios from section 19.4 through the design. Two became conditions (load test, deletion of shared data); one became a feature (the “what's shared” view).

4. Write the design doc and ADR-016. Four pages: context, goals and non-goals (non-goal: predicting which students will fail), the three options, the recommendation, risks, and the pilot plan. Recipe prompt 4 found two arguments the doc didn't answer; Maya added both.

5. Build the five slides.

Twenty-two slides of architecture moved to a backup appendix. Ravi's single sign-on question got a backup slide of its own.

6. Pre-read, then meeting. The design doc went out three days before. The meeting took 40 minutes. Dr. Hale pushed hard for option A; the tradeoff narrative from section 19.4 answered her with evidence, and she accepted option C with a condition of her own: report opt-in rates monthly.

7. Record and follow up. ADR-016 recorded the decision, conditions, and owners the same afternoon. Maya then sent the panel a risk-response memo: each risk raised, its owner, its response, and its date. That memo is where things went wrong.

Verification: are you leading the work, not just doing it?#

Failure clinic: the number nobody measured#

Symptom. Two days after the panel approved ADR-016, Ravi replied to Maya's risk-response memo: “Item 4 says the platform was ‘load-tested to 25,000 concurrent students with p95 plan-page latency of 1.4 seconds.’ Could you send the test report? Our infrastructure team would like to review it before fall.” There was no test report. No such test had been run.

Reproduce. Maya opened the memo's history. She had asked an agent to turn the meeting notes and the repository into a risk-response memo. For the capacity risk, the agent had found chapter 16's capacity estimate (peaks estimated for 7,000 and 15,000 students), the staging load-test scripts, and the SLO dashboard. It had extrapolated to 25,000 and written the result in the past tense, as a measurement. The “1.4 seconds” came from the dashboard during December finals, at about 7,000 students. The meeting's agreed condition, a load test before stage two, had become a claim that one had already happened.

Diagnose. The agent produced a fluent, plausible document, and fluent documents get skimmed. Four things combined:

1. No claim check. The memo went out without recipe prompt 3. Maya had used it on the design doc, but the memo felt like a formality after the approval.
2. Tense hid the difference. “Load-tested to” and “estimated to handle” differ by a few words and by everything that matters.
3. Review for tone, not facts. Maya read the memo for whether it sounded right to the panel. It did.
4. The condition wasn't tracked as an open item, so nothing contradicted the claim.

Chapter 13's warning applied exactly: generated work is confident whether or not it's correct (Perry et al., 2023). And the accountability was Maya's, because her name was on the memo.

Fix.

1. Correct it promptly and plainly. Maya replied to the whole panel within the hour: the claim was wrong, the test hadn't been run, the figure was an extrapolation, and the load test remained a condition, now scheduled for July with Ravi's team invited to observe. She didn't blame the tool. Ravi's answer: “Thanks for the quick correction. That's what we need to see.”
2. Claim tables for every external document. Any document leaving the team now ends with a table: each factual claim, its evidence link, and its label (measured, estimated, assumed). Recipe prompt 3 builds the draft; a person checks every link.
3. Conditions are tracked as work. Each review condition became an issue with an owner and a date, linked from ADR-016. A claim that contradicts an open condition is easy to spot.
4. A fitness function for documents. A CI check scans documents in docs/external/ for phrases like “load-tested,” “compliant,” and “verified” and fails unless each is followed by an evidence link.

Lesson. You can delegate the writing; you can't delegate the truth of what's written. Every claim that leaves your team needs evidence you've checked, an honest label, and your name on it. When one is wrong, correct it fast and in plain words; trust survives mistakes far better than it survives excuses.

Architect's checklist#

Before your next decision or review:

• ☐ I know which decisions are one-way doors and gave them the slow process.
• ☐ I turned one-way doors into two-way doors where I could.
• ☐ Assumptions are labeled, with what changes if they're wrong.
• ☐ I prototyped where uncertainty was cheaper to test than to debate.
• ☐ My material fits its audience, and stakeholder decks lead with the decision.
• ☐ ADRs and design docs are short, list alternatives and non-goals, and I wrote the decisions.
• ☐ Reviews have a pre-read, the right owners, and a recorded outcome.
• ☐ Every change and document has a human owner who can explain it.
• ☐ Risky changes pass named human gates.
• ☐ Teammates learn as they work: explain-back, first drafts, debugging before delegating.
• ☐ Team rules for AI use are written in the repository.
• ☐ Key scenarios have been walked through the design with stakeholders.
• ☐ Requirements trace to decisions, checks, and evidence.
• ☐ Each key architectural property has a fitness function.
• ☐ Every claim leaving the team has evidence and a label.

Exercises#

Beginner. The Meal Planner's owner wants to share users' meal plans with a grocery partner for discounts. List the decisions involved and mark each as a one-way or two-way door. For the one-way doors, propose a way to make each more reversible. Then write three assumptions, each labeled measured, estimated, or assumed, with what changes if it's wrong.

Intermediate. Present a design for the Trip Planner's new group trips feature to two audiences. Write a five-slide outline for the business owner and a one-page technical summary for the engineers. Then run a claim check on both: list every factual claim and its evidence, and mark any you couldn't support.

Advanced. Run a scenario-based review of the Shop Help Chat's refund tool. Write eight scenarios across security, customer experience, cost, and operations, each with a stimulus and desired response. Walk them through the design, classifying each finding as a risk, non-risk, sensitivity point, or tradeoff point. Propose three fitness functions for the most important properties, and write a tradeoff narrative for one decision, with evidence and a revisit trigger.

Lab, artifact, and review#

Lab. Defend an architecture decision from your Learning Coach before a simulated design review panel. Choose a real one-way door (for example, a new data-sharing integration or a model provider change). Assign classmates, colleagues, or friends to play four roles: business owner, security lead, privacy officer, and user representative. Give each a one-paragraph brief of their concerns. Send a pre-read, present for ten minutes, take questions for twenty, and record the outcome.

Deliverable. Add to your portfolio:

• a five-slide design review, with a backup appendix;
• an ADR bundle: the new ADR plus any it supersedes or depends on, with a traceability table linking requirements to decisions, checks, and evidence;
• a risk-response memo listing each risk raised, its owner, response, and date, ending with a claim table.

Review. Ask one panel member to rate, from 1 to 5: Did you know what decision was being asked of you? Did you understand the options and their consequences for you? Did you trust the evidence? Then compare your claim table with what you said in the room.

Reflection#

• Which decision in your project did you treat as a two-way door that was really one-way, or the reverse?
• Who are the stakeholders of your system who've never seen its architecture, and what would they need to know?
• What's one claim you've made about your system that you couldn't immediately prove?
• How do you know your own skills are growing, not just your output?
• When did you last change your mind in a review, and what evidence did it?

Chapter 20 brings everything together. In the capstone studio, you'll design, build, and operate an AI product of your own from first idea to production, and defend it before a review panel, using every practice from this book, including the ones in this chapter.

References#

• Bezos, J. (2016, April). 2015 letter to shareholders. Amazon.com, Inc.
• Brown, S. The C4 model for visualising software architecture. c4model.com.
• Google. The standard of code review. Google Engineering Practices Documentation.
• Nygard, M. (2011, November 15). Documenting architecture decisions. Cognitect blog.
• Perry, N., Srivastava, M., Kumar, D., & Boneh, D. (2023). Do users write more insecure code with AI assistants? arXiv:2211.03622.
• SEI. Architecture Tradeoff Analysis Method collection. Carnegie Mellon University Software Engineering Institute.
• Shen, J. H., & Tamkin, A. (2026, January 29). How AI assistance impacts the formation of coding skills. Anthropic.
• Thoughtworks. (2017, November 30). Architectural fitness function. Technology Radar.
• Ubl, M. (2020, July 6). Design docs at Google. Industrial Empathy.

Links checked October 2026.