Record the reasoning while it is still fresh. An architecture decision record (ADR) helps the next person understand a consequential choice without reconstructing the conversation.
One decision, one record
Give it a title, date and status, then the constraints, credible alternatives, the choice and the costs accepted. Keep it beside the code, and write for someone who was absent. Keeping an order service in one deployable for simple operations is a fine decision; record the cost, that releases stay coupled. When a decision changes, supersede the record and link its replacement.
Who decides
Central architecture review does not scale. Andrew Harmel-Law’s advice process replaces it with one rule: anyone can make an architecture decision after seeking advice from the people it affects and the people with relevant expertise. Advice must be considered but need not be followed. The person who decides owns the outcome, and the ADR records who advised what.
Name the debt
A shortcut is a decision too. Oskar Dudycz argues that calling it “debt” hides the trade-off, such as speed over tests, and parks it at the bottom of the backlog. Record it like any other choice: the trade-off, who accepted it, the friction it causes, and when it will be revisited.
Draw the right level
Pair the record with a diagram at the level its reader needs. Simon Brown’s C4 model offers four: system context, containers, components and code. Start with context, add containers when readers need the technical structure, and stop when the question is answered.
Next: Modernize one slice at a time · Make architecture rules testable