Running Effective Architecture Reviews: A Lightweight Process for Growing Engineering Teams

A team ships a new service. Six months later, it has become a load-bearing part of the system that nobody fully understands. The engineer who built it is gone. The code works, but it is tightly coupled to three other services in ways that make the current migration nearly impossible. Someone suggests a refactor. In the review, the team discovers that most of the coupling was a known problem when the service was built. It was just never written down or raised with anyone who could have influenced the design.

The architecture review would have caught this. Except there was no architecture review, because the team was moving fast and reviews felt like bureaucracy.

This is the situation most growing engineering teams find themselves in: either no formal review process, or a formal process so heavy that engineers route around it. Neither produces good outcomes. What follows is a lightweight process that sits between those two failure modes.

Why Most Architecture Reviews Fail

Before getting to what works, it is worth naming what does not.

Too late. The most common failure is scheduling the review after the design is already committed to. When an engineer presents a system they have already spent three weeks building, the review is not evaluating a proposal. It is a retrospective with a few suggestions. The real architectural decisions were made alone, without input, and the review exists to satisfy a checkbox.

Too formal. Some teams adopt review processes that require a 20-slide deck, a written spec with sign-off from three people, and a scheduled meeting with the full architecture committee. Engineers, rationally, avoid triggering these processes. Small services get built without review because nobody wants to go through that. The process designed to improve decisions ends up preventing review of the decisions that matter most.

Wrong audience. A review with eight people around a table produces eight competing opinions. Nobody is sure whose voice carries weight. The loudest or most senior person wins. Engineers who disagree stay quiet to avoid conflict. The review feels thorough but produces no useful signal.

No follow-through. The review happens, feedback is given verbally, and then everyone returns to their normal work. Three weeks later, the engineer ships the original design. The feedback was absorbed selectively, or genuinely forgotten, or overridden by deadline pressure. Without a written record of the decision, there is no way to know whether the concerns raised were addressed or ignored.

When to Trigger a Review

Not every technical decision needs a review. Running every choice through a formal process creates noise that makes the signal meaningless. The question is: what makes a change worth a review?

A useful set of triggers:

Scope thresholds. New service or system. Any change that introduces a new persistence layer (database, cache, queue). Any public API that other services or clients will consume. Any component expected to handle more than roughly 10% of production traffic.

Risk signals. Irreversible or expensive-to-reverse decisions. Changes that cross service or team boundaries. Third-party integrations where failure modes are not fully understood. Work that bypasses existing patterns in ways that may set precedent.

Explicit request. Any engineer can request a review. This is important. Reviews should not be triggered only top-down. An engineer who is uncertain about their own design should be able to say “I want to run this by someone” without that being treated as a sign of weakness.

The inverse is equally important: know what does not need a review. Adding a new endpoint to an existing service. Changing internal implementation details. Refactors that do not change observable behavior. Dependency version bumps. Keep the bar clear so engineers are not wondering whether their work qualifies.

Who Attends

Two to four people. Not a committee.

The default composition:

• The engineer proposing the design (always)
• One engineer with deep familiarity with the affected systems (the person who will feel the downstream effects most directly)
• One engineer who can challenge the design from a different angle: security, scalability, operational complexity
• The technical lead or senior engineer responsible for the area, if not already covered above

Four people maximum. When you have more, two things happen: the people with the least direct stake in the decision start filling time with abstract opinions, and the people who should be speaking start deferring to seniority. Both reduce the quality of the review.

If multiple teams are affected, each team sends one representative, not several. That representative is responsible for gathering input from their team before the review and bringing it in consolidated form.

The reviewer role is not to design the system. It is to ask questions the author has not asked themselves, surface tradeoffs the author may have weighted incorrectly, and ensure the decision is made consciously rather than by default.

What the Author Prepares

One page. Not a slide deck.

The goal of the design document is to surface what the author actually decided and why. Slide decks are optimized for presenting conclusions. Design documents are optimized for exposing the reasoning behind them. These are different things, and only one of them is useful in a review.

Here is a practical template:

# Design: [Short Title]

**Author:** [Name]
**Date:** YYYY-MM-DD
**Status:** Proposed
**Reviewers:** [Names]

## Problem

What are we solving? Why now? What happens if we do nothing?
One paragraph. Be specific about the constraint or failure mode
being addressed.

## Proposed Approach

What is the design? Describe the architecture in enough detail
that someone unfamiliar with the system can understand the
key decisions. Include a simple diagram if the data flow is
non-obvious. No more than half a page.

## Alternatives Considered

### Option A: [Proposed approach name]

**Pros:**
- [Specific advantage, with numbers if available]

**Cons:**
- [Specific tradeoff or risk]

### Option B: [Alternative]

**Pros:**
- [Specific advantage]

**Cons:**
- [Why this was not chosen]

### Option C: [Do nothing / Status quo]

Why the status quo is not acceptable.

## Tradeoffs

| Concern | Impact | Notes |
|---|---|---|
| Latency | Low | Async path, no p99 impact expected |
| Operational complexity | Medium | Adds one new dependency to monitor |
| Migration path | High | Requires coordinated deploy with order-service |

## Open Questions

- [Question 1: something the author is genuinely uncertain about]
- [Question 2: an assumption that needs validation]

## What Success Looks Like

How will you know this worked? What metrics change?
What does failure look like early enough to catch it?

The most important section is “Alternatives Considered.” An author who cannot articulate why they chose this approach over the alternatives has not yet made a real decision. They have made an assumption. The review is where that distinction becomes visible.

The “Open Questions” section is equally important. It signals intellectual honesty and focuses the review on where input is actually needed, rather than letting reviewers rehash decisions the author is already confident in.

Send the document to reviewers 24 hours before the meeting. Not five minutes before. Reviewers who read the doc in the meeting are not reviewing. They are reading.

How the Review Runs

30 minutes. Structured. One person takes notes.

First five minutes: The author gives a two-minute summary of the problem and the proposed approach. No more. If the author needs more than two minutes to explain the problem, the design document did not do its job.

Next 20 minutes: Reviewers ask questions. The author answers. The person taking notes captures decisions and action items, not a transcript of the conversation.

Questions that produce good reviews:

• What does failure look like for this approach?
• What would make you choose Option B instead?
• What is the hardest part of this to operate at 3am?
• What are you most uncertain about?
• What assumption in this design would most change the outcome if it turned out to be wrong?

Questions that do not produce good reviews:

• Have you considered using [technology the reviewer prefers]?
• Wouldn’t it be cleaner if you [suggested approach that would require a full redesign]?
• Why didn’t you use [pattern that is irrelevant to the actual constraints]?

Last five minutes: The reviewers state a recommendation. This is a real decision point. The options are:

• Proceed as proposed: No significant concerns.
• Proceed with changes: Specific changes required before shipping. List them explicitly.
• Revisit: The design has a fundamental problem that requires rethinking before the review can conclude. This is the rarest outcome and should be treated seriously, not as a default when reviewers are uncertain.

The recommendation and any required changes get written down before anyone leaves the room. Not in someone’s head. In a document. Usually the design doc itself, updated with a Decision section.

Common Review Types

New service or system. Focus on: service boundaries (is this the right level of abstraction?), data ownership (who owns what, and where does the source of truth live?), failure modes (what happens when downstream dependencies are unavailable?), and operational footprint (what is added to the on-call surface?).

Major migration. Focus on: rollback strategy (can you abort mid-migration without a production incident?), data consistency during cutover (dual-write, shadow read, or big-bang?), and the coordination cost across services that depend on the migrated system.

Third-party integration. Focus on: fallback behavior when the third party is down, data residency and privacy implications, contractual rate limits and their production impact, and whether the abstraction layer is thick enough to swap the vendor without a full rewrite.

Scaling preparation. Focus on: which specific metric is the trigger (not “when we get big” but “when we cross N requests/second or Y GB/day”), whether the proposed approach solves the bottleneck or moves it, and whether the added complexity is justified given the projected timeline to that threshold.

Anti-Patterns

Review by committee. Eight engineers in a room means the loudest voice wins. Keep the audience small and the role of each participant explicit.

Architecture astronauts. Reviewers who propose solutions that are theoretically elegant but operationally expensive for the team’s actual size. A distributed event-sourced CQRS architecture is not an improvement over a straightforward Postgres-backed service for a team of six. The review should evaluate the design in the context of the team’s operational capacity, not an idealized future state.

Rubber stamping. Reviews that consistently conclude with “proceed as proposed” within five minutes are not reviews. Either the trigger threshold is too low (reviews being called for things that do not warrant them), the reviewers are not doing the preparation required, or the culture has made disagreement feel unsafe. All three are problems worth diagnosing separately.

Bikeshedding. Spending 20 minutes debating naming conventions or color choices in a diagram while skipping the question of whether the data model is correct. Strong reviews focus on the irreversible or expensive decisions. The reversible ones can be handled in code review.

Connecting Reviews to ADRs

The architecture review and the ADR are complementary, not redundant.

The review is a process: a meeting, a conversation, a decision. The ADR is the record: what was decided, why, and what alternatives were rejected. Without the ADR, the review produces a decision that lives in someone’s memory. Without the review, the ADR records a decision that may not have been seriously examined.

The workflow that connects them:

1. Engineer identifies a decision that meets the review threshold.
2. Engineer writes the lightweight design doc and schedules the review.
3. Review runs. Decision is recorded in the design doc.
4. Engineer writes an ADR based on the design doc, with Status: Accepted and a pointer to the design doc for full context.
5. ADR is committed to the repo alongside the code that implements the decision.

docs/
  adr/
    0014-migrate-sessions-to-redis.md
  design/
    2026-03-15-session-storage-redesign.md

The design doc stays as the detailed record of the review. The ADR is the authoritative short-form record that engineers encounter when they hit the code later. The ADR’s Context section can reference the design doc for anyone who wants the full conversation.

## Context

Session storage is currently on Postgres, which is responsible for roughly
30% of p99 latency on the authentication path. At current write volume
(~2,000 sessions/second), single-master replication is the bottleneck.

Full design doc and review notes: docs/design/2026-03-15-session-storage-redesign.md

This is the chain that makes decisions durable: the review ensures the decision was examined, the ADR ensures the decision is findable, and the design doc ensures the reasoning is recoverable.

Maturity Progression

Teams do not go from no process to a fully functioning review practice overnight. Here is a realistic progression:

Stage 1: Ad-hoc. No formal process. Reviews happen informally when someone happens to ask for input. Most decisions are made solo. This is the starting state for most early-stage teams, and it is fine at small scale with high trust and low headcount.

Stage 2: Triggered reviews. The team agrees on a set of triggers (new service, new database, public API). When a trigger fires, the author is expected to write a brief design doc and get two to three engineers to review it before shipping. No formal meeting required. Comments on a PR or a shared document are sufficient. ADRs are optional but encouraged.

Stage 3: Structured reviews. The team has a template, a consistent meeting format, and a habit of recording decisions as ADRs. Reviews happen on a predictable cadence. Reviewers know their role. The process is fast enough that engineers do not resist triggering it.

Stage 4: Review culture. Reviews are integrated into how the team thinks about technical work, not a separate process. New engineers learn the pattern through participation before they are asked to lead one. The ADR index is used during onboarding. Decisions that were made three years ago are recoverable and challenge-able without a tribal knowledge problem.

The jump from Stage 1 to Stage 4 in one step is a guaranteed failure. Teams that try to install a mature review process before the underlying habit is formed produce the worst outcome: a formal process that engineers work around, generating paperwork instead of better decisions.

Start with Stage 2. Run five reviews. Fix what felt wrong. Run five more. The process that sticks will be one the team built through iteration, not one installed from the outside.

---

The point of an architecture review is not to gatekeep. It is to give the author of a design a chance to have their reasoning challenged by people who care about the outcome, before the cost of changing direction becomes prohibitive. Done right, reviews make engineers more confident in their decisions, not less. The author leaves knowing their design was examined by people who asked hard questions and still said proceed. That is worth 30 minutes.