给未来的自己留一份使用说明

前阵子办备案，走到某一步的时候我停下来，发现自己完全想不起来上一步做了什么。

初审的电话是什么时候接的？那条短信核验点没点？当时明明觉得「这个不用担心，到时候自然知道」。

事实证明不会知道。

这类记录是写给谁的

我开始认真记东西，不是因为觉得应该记，是吃过亏。

这些东西没什么宏大目的，它只有一个读者：三个月后那个什么都不记得的我。

三个月足够忘掉几乎所有细节，但三个月后又往往需要重新捡起来。中间那段时间差，就是这件事存在的意义。

几件我确实忘了的事

备案其实有三道关，每关的联系方式都不一样：

• 云服务商初审：一到两个工作日，会打电话核实，两次联系不上就驳回
• 工信部短信核验：12381 发六位验证码，24 小时内必须完成，超时自动退回重来
• 管局审核：八到二十个工作日，结果通过短信和邮件告知

这三件事我在一周之内就全忘了顺序。更麻烦的是第二关有硬性时限，忘了就等于从头再来一遍。

还有一件：一台 2 核 2G 的服务器装不了 MySQL 8.0。宝塔对它的内存门槛是 3700MB，我只有 2048MB，差了 1.6GB。作为对比，5.7 只要 1560MB，5.6 只要 768MB。这几个数字当时我查了小半天，现在如果让我重查一遍，还是得小半天。

关于「为什么」，代码是不会说的

后来我才知道，这类记录在工程领域有个正式名字，叫架构决策记录，简称 ADR。

GitHub 的博客里有一句话我很喜欢：ADR 不是为你写的，是为未来的你写的。它帮你在六到十二个月之后，重新回到当时做决定的心智状态。

我看到过一个特别精准的例子。有位独立开发者在做预约系统的时候，决定把价格直接存在预约记录里，而不是每次去引用服务当前的价格。代码本身很清楚，价格就在那儿。但代码没说的是为什么——改服务价格不应该追溯改变过去已经谈好的预约，这在开票场景下是有法律意义的。

问题在于，一年半以后他自己（或者任何接手的人）看到这段代码，很可能觉得这是个疏忽，然后动手把它「修」掉。而那个修复会引入一个真正的 bug。

原文那句话说得很准：代码看起来是错的，但它没错，而这个差别是看不见的。

不需要工具，只需要习惯

ADR 听起来很正式，好像得配一套流程和模板。其实不用。

那位开发者说得很实在：一个决策日志可以就是一个放编号 Markdown 文件的目录，甚至可以是代码里一句恰到好处的注释，写清楚「这里是有意这么做的，原因如下」。

他的格式很简单：决定是什么、日期、考虑过哪些替代方案、是什么约束把其他方案排除了，以及什么情况下会重新考虑。最后一条我觉得最重要。决定不是永久的，当初让它成立的那个约束可能会消失。

多久写一次也有个宽松的标准：这件事以后会不会有人需要？改起来麻不麻烦？两个都答「是」，就写一条。

有人分享过坚持下来的实际效果。他们攒了十四条记录，新人入职一次坐下就能读完；从入职到第一次有意义的提交，时间从大概一个月缩短到一两周。有两次计划中的改动，在写记录的阶段就被推翻了，因为老实把替代方案列出来之后，第一个想法自己就站不住了。

他们提到的一个细节我印象很深：重构模块时，「移除了一个没人看得懂的临时方案」这类事故降到了零。因为在动手之前，你能先看到当初为什么那么写，于是要么有意保留，要么安全删掉。

---

所以我现在记东西的标准放得很低。不追求结构完整，不追求措辞好看，只要下次打开的时候能让我想起来，就够了。

那位开发者最后写了一句话，我也抄下来了：你会忘记。写下来。