Design review

Teams run design reviews because the cheapest moment to change a design is before anyone has built it. A review also spreads knowledge of the design beyond its author and leaves a written decision that the team can point to later.

Why does a design review matter?

• It catches expensive mistakes early. A wrong data model found in review costs an afternoon. Found in production, it costs a migration.
• It brings in people who will live with the design. The engineers who operate the system, own neighboring systems or hold security know things the author does not.
• It produces a decision. The output is not a discussion but an approval, a revision request or a rejection, with the reasons written down.
• It aligns the team. By the end, everyone who will build or depend on the design has read it.

How does a design review work?

The diagram at the top of this page shows the usual flow and who does each step.

The author does the system design and writes it up in a design document, typically one to three pages, with the problem, the proposed design, the alternatives considered and the open questions. The document includes an architecture diagram, often at the C4 model container level, so reviewers can see the structure rather than reconstruct it from prose.

Reviewers then comment asynchronously for two to five working days. Most issues get resolved in the comments. The review meeting exists for the questions that remain, and it should be short because the reading has already happened.

A named decision owner, usually the technical lead or an architect, decides: approved, or not yet. Approval leads to the build, an architecture decision record for the significant choices and a list of follow-ups tracked as tickets. Anything else goes back to the author, who revises the document with the open comments resolved and brings the next draft back through the same loop.

What should a design review cover?

• The problem. Is it stated clearly, and does the design solve that problem rather than a neighboring one?
• Requirements. Are the functional and non-functional requirements written down, with numbers where they matter?
• The design. The system architecture: the components, their responsibilities, the data each one owns, the interfaces between them and the architecture pattern it follows.
• Alternatives. What else was considered and why it lost. A design with no alternatives has not been designed.
• Failure modes. What happens when each dependency is slow, down or returns bad data.
• Operations. How it is deployed, monitored, scaled and rolled back.
• Security and privacy. Where data crosses a trust boundary, who can call what and what is stored.
• Cost and timeline. What it costs to run and how long it takes to build.

Who attends a design review?

• The author, who presents and answers questions but does not decide.
• Two to five reviewers: engineers from the team, at least one from a team that depends on the design, a specialist where it matters, such as security or data, and the solution architect when the design is part of a wider solution architecture.
• The decision owner, who may also be a reviewer. There should be exactly one.
• Optional observers, such as newer engineers who learn from watching. They read and listen but do not need to comment.

Beyond about eight people the meeting stops being a review and becomes a presentation.

What is a design review checklist?

A short checklist keeps reviews consistent and stops reviewers from spending the whole session on naming.

1. The problem and the success criteria are stated.
2. The non-functional requirements have numbers: latency, throughput, availability, data retention.
3. Every component has one owner and one clear responsibility.
4. Every interface between components is named, with its protocol and its failure behavior.
5. Each kind of data has one source of truth.
6. At least two alternatives are described, with reasons for rejecting them.
7. The rollout and the rollback are described.
8. The diagram matches the text.
9. Open questions are listed, each with an owner.

What are common design review mistakes?

• Reviewing too late. If the code is half written, the review becomes a formality because nobody wants to throw the work away. Review when the document is the only artifact.
• No decision owner. A review with five opinions and no decider ends in a second meeting.
• Reviewing the prose instead of the design. Comments on wording are fine in the document. The meeting is for structure, risk and trade-offs.
• Skipping the diagram. Reviewers who have to build the picture in their heads miss the problems in it.
• Treating approval as the end. Follow-ups that are not tracked do not happen, and become technical debt.
• Reviewing everything. When every small change needs a review, reviewers stop reading carefully.

How does a design review relate to ADRs and architecture review boards?

A design review is an event, and an architecture decision record is the durable output of it. The review examines the whole design; the ADR captures the one or two decisions in it that will matter in a year, such as a choice of database or a messaging pattern, with the context and consequences. Teams that write ADRs from their reviews stop having the same argument twice.

An architecture review board is the organization-level version of the same idea: a standing group that reviews designs for fit with standards, shared platforms and strategy. Team design reviews should happen for every significant change. The board sees the subset that crosses team boundaries, introduces a new platform or commits serious money. Running both, with the team review first, keeps the board from becoming a bottleneck.

What tools help with design reviews?

• Document tools with comments. The asynchronous phase needs inline comments and a way to mark them resolved. Any shared document tool that does this works.
• Diagram-as-code tools. Keeping the diagram as text in the same pull request as the design document means both get reviewed together and stay in sync. See diagram as code.
• AI diagramming tools. Tools like Eraser turn a draft design document into an architecture diagram that reviewers can comment on and the author can keep editing between drafts, which removes the most common reason a design arrives at review without a picture.

For more on this kind of document, see design docs.

Frequently asked questions