Architecture Review Gate Workflow
Route changes that alter cross-team contracts, add dependencies, or shift data ownership through a lightweight architecture gate before code.
Objective
Catch direction-level mistakes (wrong dependency, wrong owner, wrong coupling) before code review, with a gate light enough not to become a bottleneck.
Environment
- A defined threshold list for what triggers architecture review
- A small architecture group or rotating reviewers
- A one-page design note format
Steps
1. Define the trigger thresholds
List what qualifies: new cross-service dependency, schema shared across teams, new infrastructure component, or changing a published contract.
Expected state: A short trigger list exists that ordinary PRs do not trip.
2. Require a one-page design note
For triggered changes, require a short note covering the problem, the chosen shape, alternatives rejected, and the blast radius.
Expected state: The note is one page; reviewers can absorb it in ten minutes.
3. Review with a fixed question set
Run the gate with consistent questions: does the dependency direction fit the map, who owns the new data, how does this evolve, what reverses if wrong.
Expected state: Every gate review asks the same questions and records answers.
4. Bind the decision to the code review
The approved note links into the resulting PRs, so code reviewers verify implementation matches the reviewed shape rather than re-litigating it.
Expected state: PRs reference the approved note; scope changes bounce back to the gate.
5. Audit the gate's own weight
Track gate latency and the rate of reversals, keeping the process light enough that people route to it rather than around it.
Expected state: Median gate time stays within days, and evasion attempts trend to zero.
Expected outcome
Direction-level decisions made deliberately before code, with a gate fast enough to be routed to rather than dodged, and decisions traceable into PRs.
Verification
Recent cross-team changes carry approved notes; gate median latency stays within target; no major coupling surprise arrived via a PR that skipped the gate.
Some mistakes are cheaper to catch before the code exists
Code review catches implementation errors well and direction errors expensively: the wrong dependency direction works perfectly and costs a quarter to unwind. A light architecture gate — trigger list, one-page note, fixed questions — catches direction while it is still cheap.
trigger list (what goes to the gate):
new dependency between services
schema shared across >1 team
new infrastructure component (db, queue, cache)
change to a published contract/API
design note (1 page):
problem / chosen shape / rejected alternatives
+ blast radius + reversal path
gate questions (fixed):
Q1 dependency direction fits the map?
Q2 who owns the new data, lifecycle?
Q3 how does this evolve at 10x?
Q4 what reverts if this is wrong?
PR #5210 header: "gate note #88 approved 10-21"
reviewer verifies shape, not re-argues itThe reversal question is the sharpest tool
What reverts if this is wrong separates reversible choices (a flag, a table) from commitments (a shared schema, a bidirectional dependency). Making the cost of wrong explicit often improves the design on the spot, before any reviewer opinion lands.
The gate must stay lighter than the workaround
Architecture gates fail by weight: when a review takes three weeks, teams route changes as routine to skip it. Median latency in days, a fixed question set, and a visible reversal-rate metric keep the gate useful enough that engineers choose it.