Chapter 21 Flashcards — Architectural Decisions
flashcards fsa architectural-decisions adrs
Antipatterns
Q: What is the Covering Your Assets antipattern?
A: An architect avoids or indefinitely delays making architectural decisions out of fear of being wrong, causing team paralysis while waiting for certainty that never arrives.
Q: What is the solution to the Covering Your Assets antipattern?
A: Make the decision with clearly documented reasoning. If it turns out wrong later, the documentation demonstrates the reasoning was sound given what was known. Own mistakes rather than avoiding decisions.
Q: What is the Groundhog Day antipattern?
A: The same architectural decision gets relitigated repeatedly in meetings because no record of the original decision’s why was kept, causing teams to debate the same ground from scratch each time the topic resurfaces.
Q: What is the solution to the Groundhog Day antipattern?
A: Document decisions in ADRs so the rationale is captured, searchable, and authoritative. Anyone wanting to re-open a decision must read the ADR first; if the context has genuinely changed, they propose a superseding ADR.
Q: What is the Email-Driven Architecture antipattern?
A: Architectural decisions are made in email threads or chat messages, buried in inboxes, and never captured in a shared searchable location — causing architectural knowledge to decay and become tribal knowledge.
Q: Why does Email-Driven Architecture fail?
A: New team members have no access to the history; existing members can’t find old threads; the architectural rationale exists only in the heads of a shrinking group of senior people, creating dangerous key-person risk.
Q: What is the solution to the Email-Driven Architecture antipattern?
A: Any architecturally significant decision must be extracted from email/chat and recorded in a version-controlled ADR. Email threads can inform the ADR’s context section but are not a substitute for it.
Architectural Significance
Q: Name the four criteria that make a decision architecturally significant.
A: (1) Involves significant tradeoffs between competing concerns, (2) affects nonfunctional characteristics (performance, security, scalability, etc.), (3) affects multiple teams, (4) is hard or expensive to reverse.
Q: Why should architects delegate non-architecturally-significant decisions?
A: Over-claiming decision authority makes architects bottlenecks, buries important decisions in noise, and slows team delivery. Architectural governance should focus on decisions that genuinely meet the significance criteria.
Q: Give an example of an architecturally significant decision and one that is NOT.
A: Significant: choosing a primary database technology (hard to reverse, affects nonfunctional characteristics). Not significant: choosing a local variable naming convention within a single service (low-cost to reverse, no nonfunctional impact).
ADR Structure
Q: What is an Architectural Decision Record (ADR)?
A: A short, structured document that captures a single architecturally significant decision — including the context that drove it and the consequences of choosing it — stored in version control alongside the codebase.
Q: List the five fields in the basic ADR structure.
A: (1) Title, (2) Status, (3) Context, (4) Decision, (5) Consequences.
Q: What should the Title field of an ADR contain?
A: A short imperative phrase naming the decision, e.g., “Use PostgreSQL as the Primary Database.” It identifies the decision at a glance without requiring the reader to open the document.
Q: What does the Context field of an ADR capture?
A: Why the decision is needed — the forces at play, constraints, and situation that make the decision necessary. It describes the problem space without containing the solution.
Q: What does the Decision field of an ADR contain, and how should it be phrased?
A: The chosen approach, stated positively as “We will use X” rather than “We decided not to use Y.” Positive framing makes the decision unambiguous and actionable.
Q: What does the Consequences field of an ADR capture?
A: The tradeoffs of the decision — both what becomes easier (positive consequences) and what becomes harder or more costly (negative consequences). This is the field most often neglected and most valuable.
Q: What three extended fields can be added to a basic ADR for complex decisions?
A: (1) Alternatives Considered (with reasons each was rejected), (2) Governance (how the decision will be enforced and the exception process), (3) Notes (timestamps, authors, links to related tickets).
ADR Status
Q: List the four ADR status values and what each means.
A: Proposed (under discussion, not yet adopted), Accepted (approved and in effect), Deprecated (no longer recommended but not superseded), Superseded (replaced by a newer ADR, with a link to it).
Q: What happens to an ADR when it is superseded?
A: It is marked Superseded with a reference to the new ADR — it is never deleted. The full history of decisions is preserved as an audit trail.
Q: Why is the “Proposed” status useful in the ADR lifecycle?
A: It allows a decision to be circulated for review and feedback before being formally adopted, making the ADR a lightweight RFC (Request for Comments) process for architectural decisions.
Storing ADRs
Q: Where should ADRs be stored, and why?
A: In version control alongside the code, in a /docs/adr/ directory. This ensures ADRs are versioned, reviewed in pull requests, and always co-located with the implementation they govern.
Q: What is the recommended file naming convention for ADRs?
A: Sequential four-digit number followed by a short kebab-case description: NNNN-short-title.md, e.g., 0004-use-postgresql.md.
Q: Why should ADRs NOT be stored in a wiki disconnected from the codebase?
A: Wikis go stale, lose version history, and are abandoned when teams change. ADRs in a wiki quickly fall out of sync with the actual architecture and lose the review discipline that version control provides.
ADR Archaeology
Q: What is ADR archaeology?
A: The practice of retroactively writing ADRs for an existing system with no prior ADR history, by reconstructing past decisions from the codebase, commit history, and surviving documentation.
Q: How should retroactive ADRs be marked?
A: Clearly with their reconstruction date and confidence level, to distinguish them from decisions that were documented at the time they were made.
Generative AI
Q: Name three ways LLMs can assist in ADR authoring.
A: (1) Generate a complete ADR draft from a brief description (overcoming the blank-page problem), (2) enumerate alternatives the architect may not have considered, (3) brainstorm positive and negative consequences.
Q: What is the key limitation of using AI to author ADRs?
A: LLMs do not know your specific organizational context — team skills, risk tolerance, vendor relationships, or past decision history. AI-generated ADRs will be generic and require significant human editing to be accurate.
Q: What is the appropriate role of generative AI in architectural decision-making?
A: AI is a starting point — to draft documents, enumerate options, and pressure-test reasoning. The architect must supply the specific context, validate consequences against reality, and make the actual judgment call. AI should never produce a final ADR without substantial human review.
Synthesis
Q: How does an ADR’s Alternatives Considered section help prevent the Groundhog Day antipattern?
A: It shows that the team already evaluated the alternatives being re-proposed, with specific reasons each was rejected. A skeptic can see their preferred option was considered rather than overlooked, cutting off unproductive debate.
Q: What is the single most important insight about ADRs — what makes context more valuable than the decision itself?
A: Code and diagrams show what was built; ADRs explain why. Without the why, future architects either blindly follow past decisions or blindly overturn them. The reasoning is what survives team turnover and preserves institutional knowledge.
| Field | Value |
|---|---|
| Total Cards | 28 |
| Review Time | ~35 minutes |
| Priority | HIGH |
| Last Updated | 2026-05-29 |