He spent 3 weeks playing code archaeologist just to understand WHY
our codebase looks the way it does.
Not what the code does. That was fast. But the reasoning behind decisions:
– Why Redis over in-memory cache?
– Why GraphQL for this one service but REST everywhere else?
– Why that strange exception in the auth flow for enterprise users?
Answers were buried in closed PRs with no descriptions, 18-month-old
Slack threads, and the heads of two engineers who left last year.
We tried ADRs. Lasted 6 weeks. Nobody maintained them.
We tried PR description templates. Ignored within a month.
We have a Notion architecture doc. Last updated 14 months ago.
Every solution requires someone to manually write something. Nobody does.
Curious how teams at HN actually handle this:
1. Do you have a system that actually works long-term?
2. Has anyone automated any part of this?
3. Or is everyone quietly suffering through this on every new hire?
