Designing Simple Systems

Start with a contract

When a side project feels chaotic I write down the entrypoints. A good contract lists the shape of data, the boundary between UI and domain logic, and the optional things that can safely be removed.

type Contract = {
  inputs: Record<string, unknown>;
  outputs: Record<string, unknown>;
};

The act of writing this tiny interface usually exposes assumptions I forgot to question.

Cut scope when naming hurts

If it takes me longer than five minutes to name a module, it means the module is doing more than one thing. I split it—no ceremony, just enough refactoring to let each concept breathe.

Batching decisions

I reserve a single hour per week to revisit project structure. The rest of the time I bias toward finishing features. The cadence keeps me honest without turning refactors into a hobby.