the manifest
opinions i’ll defend in a code review.
engineering isn’t religion. show me a better argument and i’ll update this file. that’s the whole point.
- 01
boring tech wins more often than exciting tech.
postgres + a monolith + a queue + a worker covers 90% of systems that ever needed "scale". the other 10% know who they are.
- 02
comments explain why, never what.
"increment i by 1" is what the code says. "// we cap retries here because the upstream returns 200 for transient 5xx" is what the code means.
- 03
if it needs seven boolean parameters, it needs an object.
and if it needs an object, you probably have two functions pretending to be one.
- 04
"we'll refactor later" is a lie you tell on day one.
later never comes. either design for the change you expect, or design the change to be cheap. both are fine. the lie isn't.
- 05
tests are a love letter to your future self.
and to whoever inherits the codebase at 2am with a pager. write the test you wish existed.
- 06
deterministic infrastructure never lives inside the non-deterministic loop.
an llm call is non-deterministic. a state machine is not. the second you let either reach into the other, a stalled token stream holds your queue hostage.
- 07
prefer "unknown" to "fine".
a green check on stale data is worse than a yellow "last seen 6h ago". trust is the only metric that compounds.
- 08
a 200ms slower page that ships today beats a 50ms faster page that ships next quarter.
shipped is a feature. perfect is a tax.
- 09
the goal of a meeting is a written decision, not consensus.
if it isn't written down, it didn't happen. if it didn't happen, we're having the meeting again next week.
- 10
delete is the most underrated feature in version control.
most code is load-bearing in the way a coat hook is load-bearing. ripping it out and watching the wall stay up is one of life's small joys.
- 11
the best error message is the one that tells you what to do next.
"invalid input" is a wall. "expected yyyy-mm-dd, got 14/03/2026" is a door.
- 12
build the smallest thing that proves the riskiest assumption.
if the assumption is wrong, you want to find out in a day, not a quarter.