你如何记录工程决策背后的原因，而不仅仅是记录决策的内容？
我们最近招募了一位经验丰富的高级工程师，拥有8年的工作经验。他花了3周的时间像代码考古学家一样，试图理解我们的代码库为何会呈现现在的样子。
他关注的不是代码的功能，这个很快就能搞明白，而是决策背后的原因：
- 为什么选择Redis而不是内存缓存？
- 为什么这个服务使用GraphQL，而其他地方都用REST？
- 为什么企业用户的认证流程中会有那个奇怪的异常？
答案埋藏在没有描述的关闭PR中、18个月前的Slack讨论串，以及两位去年离职工程师的脑海中。
我们尝试过使用ADR（架构决策记录），但只坚持了6周，没人维护。我们也尝试过PR描述模板，但一个月内就被忽视了。我们有一个Notion架构文档，但上次更新是在14个月前。
每个解决方案都需要有人手动撰写内容，但没有人去做。
我很好奇HN的团队是如何处理这个问题的：
1. 你们有长期有效的系统吗？
2. 有没有人自动化了这个过程的某个部分？
3. 还是说每个人在每次新员工入职时都默默忍受这一切？
查看原文
We onboarded a senior engineer recently strong, 8 years experience.
He spent 3 weeks playing code archaeologist just to understand WHY
our codebase looks the way it does.<p>Not what the code does. That was fast. But the reasoning behind decisions:<p>- 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?<p>Answers were buried in closed PRs with no descriptions, 18-month-old
Slack threads, and the heads of two engineers who left last year.<p>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.<p>Every solution requires someone to manually write something. Nobody does.<p>Curious how teams at HN actually handle this:<p>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?