Engineering decisions without the ceremony
An architecture decision record (ADR) is a short markdown file: context, options, decision, consequences. The format is good. The failure mode is also famous: the repo has three ADRs from 2022 and the real decisions live in Slack.
This page is not “use Scribble Flow instead of ADRs.” If your team already writes MADR or Nygard files in git, keep doing that. This is for the other case: the architecture call happened, the reasoning is gone, and someone asks why Postgres and not Dynamo?
What is actually worth recording
Record the trade-off you will forget: why this library (the team can read its source), why you ripped out the queue, why the “temporary” feature flag is still there.
Do not turn every PR into a ceremony.
A useful note answers future-you:
- What we chose
- What we rejected
- The constraint that was true that week (deadline, team size, ops load)
- What would make us revisit it
Git ADRs vs a desk
| ADRs in the repo | A desk with Memory | |
|---|---|---|
| Best at | Durable, reviewable, next to the code | Capture from a thread in ten seconds |
| Weak at | You have to stop and write the file | Not a compliance ledger, not immutable |
| Use when | The decision is load-bearing and shared | The decision is still a conversation |
Priya, in the developers track, pastes a stack trace at 6pm, writes the queue-library call as a decision the same day, and asks Memory later. Connect the Dots notices the same timeout mentioned four times. That is a different job than adr new.
A lightweight habit
- Capture the snippet, the link, or “chose the smaller library because…” - just capture.
- When you decide the architecture, turn the scribble into a decision.
- After you ship, one line: regression gone, or not.
- If the decision is load-bearing, also drop an ADR in the repo. The desk held the messy middle.
The shared pattern with product and founders is the decision log.
FAQ
Is Scribble Flow ADR software? No. No supersede workflow, no git integration, no drift detection. Memory is “ADRs minus the ceremony” for a small team - the product’s own words.
Should we stop writing markdown ADRs? Not if they are working. Use the desk for the thread you will not file.
Can I paste code? Yes. Language is preserved. Read it tomorrow in Inbox.
Start with Start here or make a desk.