Your senior engineer just spent six weeks building a new event processing system. They chose Kafka over RabbitMQ, PostgreSQL over DynamoDB, and a saga pattern over distributed transactions. Each decision made sense to them at the time.

Nobody else knew about these decisions until the pull request.

The PR has 4,000 lines of code. It’s too late to question the fundamental approach. The reviewer approves it because they trust the author, not because they evaluated the architecture. Six months later, the event processing system can’t handle the load because the saga pattern requires three database writes per event, and nobody caught that during review because there was no architecture review.

This is the architecture review that nobody runs. It’s the most absent practice in software engineering — not because teams don’t know about it, but because the cost of running it feels immediate while the cost of skipping it is deferred.

Why Architecture Reviews Matter More Than Code Reviews

Code review catches implementation bugs — an off-by-one error, a missing null check, a SQL injection vulnerability. These are important, and most teams have code review practices.

Architecture reviews catch design bugs. And design bugs are 10-100x more expensive to fix than implementation bugs because they require rewriting systems, not tweaking functions. A bug in a function costs you hours. A bug in your service boundaries costs you months.

The most expensive mistakes in software engineering are never in the code — they’re in the decisions about what code to write. Which database to use. How to handle eventual consistency. Where to draw service boundaries. What to cache and what to compute. Whether to build synchronously or asynchronously. Whether to couple or decouple.

These decisions deserve the same scrutiny as a $500K capital expenditure — because that’s roughly what they cost when they’re wrong. The six engineer-months spent building an event system with the wrong consistency model isn’t free. The three months of rework after discovering the architecture doesn’t scale isn’t free. The attrition when good engineers leave because they’re tired of firefighting architectural debt isn’t free.

The Three Architecture Review Tools

1. Architecture Decision Records (ADRs)

The simplest and most impactful architecture review tool is the ADR — a short, structured document that captures a single architectural decision:

• Context: What situation prompted this decision? What constraints exist?
• Decision: What did we decide? Be specific.
• Alternatives considered: What else could we have done? Why was each rejected?
• Consequences: What are the trade-offs? What becomes easier? What becomes harder?
• Status: Proposed, accepted, deprecated, superseded

ADRs are not proposals. They’re records. They document what was decided and why, so that the engineer who inherits the system two years from now understands the reasoning instead of just seeing the result and wondering “why did they do it this way?”

A good ADR takes 30 minutes to write. A missing ADR can cost weeks of investigation when someone needs to understand why the system was designed a particular way — and the original authors have left the company.

The key insight: ADRs are cheap to write and enormously expensive to not have. Every team that adopts them says the same thing after six months: “We can’t believe we operated without these.”

2. The Lightweight Design Review

For significant changes — new services, new databases, new integration patterns, changes to data models — run a 30-minute design review before writing code:

1. The author presents a one-page design document covering the problem, proposed solution, alternatives, and trade-offs
2. Two to three reviewers — ideally including someone not on the immediate team — ask questions and raise concerns
3. The group discusses trade-offs and alternatives, with specific attention to failure modes and scalability
4. The author revises the design if needed and documents the decision as an ADR

This isn’t a formal approval gate. It’s a conversation. The goal is to catch major design issues when they’re cheap to fix — before six weeks of implementation has created momentum behind a flawed approach.

The time invested in a 30-minute design review is recovered many times over in three ways: avoided rework (because fundamental issues are caught early), faster code reviews (because reviewers already understand the design), and better onboarding (because the design is documented for future team members).

3. The RFC Process

For the largest decisions — new platform capabilities, major re-architectures, cross-team integrations — a formal Request for Comments (RFC) process provides structured feedback from a broader audience.

An RFC is more detailed than an ADR but follows the same principles:

• Problem statement: What are we solving and why?
• Proposed design: How we plan to solve it, at the appropriate level of detail
• API contracts: What interfaces will change or be created
• Data model changes: What schema changes are required
• Migration plan: How we get from the current state to the proposed state
• Risks and mitigations: What could go wrong and how we’ll handle it
• Open questions: What we don’t know yet and how we’ll resolve it

The RFC is circulated for review over 3-5 days, collecting written feedback from engineers, product managers, and other stakeholders. The author then revises the RFC, addresses feedback, and publishes the final decision.

The Organizational Resistance

Despite being obviously valuable, architecture reviews face consistent organizational resistance. Understanding why helps you overcome it.

“We don’t have time.” This is the most common objection and the most self-defeating. Teams that don’t run architecture reviews spend more time reworking bad decisions than they would have spent reviewing them. The 30 minutes spent in a design review saves weeks of rework — but the savings are invisible because they’re counterfactual.

“It slows us down.” This confuses activity with progress. Writing code faster toward the wrong design isn’t progress. A team that spends two days on design review and ships in four weeks has accomplished more than a team that starts coding immediately and spends two months iterating toward a workable design.

“We trust our senior engineers.” You should trust your senior engineers. Architecture reviews aren’t about trust — they’re about coverage. No single engineer has visibility into all the systems that might be affected by an architectural decision. The review brings in perspectives that the author can’t have alone, no matter how senior they are.

“It feels bureaucratic.” A 30-minute conversation and a one-page document is not bureaucracy. Twenty-page design documents that require VP approval and take three weeks to process — that’s bureaucracy. Architecture reviews scale to the size of the decision: small decisions get lightweight treatment, large decisions get thorough treatment.

How to Start

If your team has no architecture review practice, don’t try to implement a full RFC process on day one. Start small and let the practice grow organically:

Week 1: Agree that any new service, new database, or new integration pattern requires a one-page design document shared with the team before coding begins. Post it in Slack. Get two thumbs-up reactions before proceeding.

Month 1: Start writing ADRs for every significant decision. Keep them in a /docs/adr/ directory in the repository. Number them sequentially. Make them part of the onboarding reading list for new engineers.

Month 3: Formalize design reviews into 30-minute calendar events. Run them weekly for any pending design decisions. Cancel when there’s nothing to review.

Month 6: Evaluate whether an RFC process is needed for larger decisions. If your team is under 20 engineers and ships to internal consumers, you may never need it. If you’re a platform team serving multiple product teams, an RFC process becomes essential.

The Compound Effect

Architecture reviews don’t just prevent individual bad decisions. They create organizational learning. When the team regularly discusses trade-offs, alternatives, and failure modes, every engineer’s design judgment improves. Junior engineers learn from watching senior engineers evaluate designs. Senior engineers sharpen their thinking by articulating their reasoning to others.

Over time, the team develops shared architectural principles — not documented in a style guide (though that helps too) but internalized through practice. The design conversations become faster and more productive because the team has a shared vocabulary and shared values.

If your team is too busy for architecture reviews, your team is too busy because of architecture mistakes they didn’t catch. The fix isn’t to run faster. The fix is to look where you’re going.

---

The Garnet Grid perspective: Architecture decisions compound over years. We help organizations establish design review practices that improve decision quality without slowing delivery. Explore our architecture audit →