How do you record why the team chose one architecture over another?
Why B is the answer
A decision record with the options, evidence and trade-offs
Code shows what was built, not why. A decision record stops the same debate recurring and shows when to revisit a choice.
In detail
- Code shows what was built, not why.
- A decision record stops the same debate recurring.
- It also shows when to revisit a choice.
- Note what would change the decision.
Use case
An illustrative scenario, not a real incident.
A team chose hybrid search after a long debate. A short decision record lists the options, evidence and trade-offs, so a new architect need not reopen it.
See it in different ways
sequenceDiagram participant S as Sponsor participant A as Architect S->>A: A broad ask A->>S: Problem, baseline and target A->>A: Build and measure A-->>S: Result, limits and options S->>A: Named decision
mindmap
root(("Decision record"))
n1["Options"]
n2["What was considered"]
n3["Evidence"]
n4["What was measured"]
n5["Trade-offs"]
n6["What was given up"]Key point: Code shows what was built, not why.
Why the other options are wrong
- A. Nothing, because the code itself shows what was decided
- Code cannot show the options that were rejected.
- C. A long chat thread that people can search through later
- Chat threads are hard to find, and they lack a clear outcome.
- D. A note in the sprint board, removed when the task closes
- The note disappears when the task closes.