你如何记录工程决策背后的“为什么”，而不仅仅是“是什么”？
5 分•作者: zain__t•5 个月前
我们最近招了一位经验丰富的资深工程师，拥有 8 年工作经验。
他花了 3 周时间当“代码考古学家”，仅仅是为了搞清楚**为什么**我们的代码库会是现在这个样子。
<p>不是代码的功能是什么，这很快就搞清楚了。而是代码背后决策的逻辑：
<p>- 为什么用 Redis 而不是内存缓存？
- 为什么这个服务用 GraphQL，而其他地方都用 REST？
- 为什么企业用户的身份验证流程会出现那个奇怪的异常？
<p>答案都埋藏在没有描述的已关闭的 PR 中、18 个月前的 Slack 讨论串里，以及去年离职的两位工程师的脑海里。
<p>我们试过 ADR（架构决策记录）。坚持了 6 周，没人维护。
我们试过 PR 描述模板。一个月内就被忽略了。
我们有一个 Notion 架构文档。上次更新是 14 个月前。
<p>每个解决方案都需要有人手动编写东西。但没人做。
<p>很好奇 Hacker News 上的团队实际上是如何处理这个问题的：
<p>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?