Most rewrites trace back to three choices made in the first fortnight, long before anyone had enough information to make them well. The useful question is not how to avoid those choices, but which ones deserve a week of argument and which can be decided in an hour.
Three categories behave differently under change. Code is cheap to replace. Interfaces between systems are expensive. Data models are the most expensive of all, because every other decision eventually encodes an assumption about them, and those assumptions live in places nobody thinks to look.
Decide the record, then the framework
On a replacement project, the first weeks should produce almost no interface. What they should produce is the record that every system involved can agree on. Every screen built afterwards is a view over that record, which is what makes replacing a module later a two-week job rather than a quarter.
If a decision is hard to reverse, spend the week. If it is easy to reverse, stop discussing it and ship something to learn from.
Three questions we ask before writing code
- What happens to this design when the volume is ten times higher and the team is half the size?
- Which part of this will the client's own engineers have to operate without us?
- If this assumption turns out to be wrong in month eight, what is the cost of the correction?
The third question is the one that changes plans. It converts an argument about preference into an estimate, and estimates are easier to agree on than opinions.
-- one record, every system reads the same shape
create table account (
id uuid primary key,
external_refs jsonb not null default '{}', -- legacy system ids
created_at timestamptz not null default now()
);None of this is novel. It is simply the order of operations that survives contact with a real deadline, and the reason we run discovery as a paid stage rather than a sales activity.
