技术笔记写给三个月后的自己

一、收藏不等于记录

我以前的笔记库里有几百条链接，每条都配一句「这个有用」。当时确实觉得有用，可能是在查某个报错时顺手存的。三个月后翻出来，我一条都想不起来为什么要存，点进去也认不出它解决了什么。那些链接大多能用搜索重新找到，真正丢掉的是我当时为什么需要它。

更隐蔽的是另一类：抄了一遍文档，或者复制了一段命令，看起来很像笔记。这类内容更麻烦，因为它给了「我记过」的错觉。真遇到问题时，我还是得从头查，而且记的时候以为懂了的地方，其实并没有懂。

二、判断标准只有一个

现在我用一个很笨的问题筛笔记：三个月后的我，能不能照着这篇东西复现或者排错？能，留下；不能，删掉或者重写。这个标准会砍掉大部分内容，但留下的那部分真的有用。

「照着做」不是要求写成教程，而是要求它能回答三个具体的提问：当时的环境和前提是什么、我试过哪几种做法、为什么最后选了这个。这三问答得出来，三个月后的我至少能少走一半弯路。

三、五段式模板

我把技术笔记固定成五段。它不长，一篇通常十几分钟能写完，但足够让以后的自己接上手。

【一句话结论】用一行写出最终做法和它适用的场景。

【假设与约束】当时依赖什么、不能改什么、有哪些前提没被验证。

【试过的方案与结果】按顺序列出，每个方案一行结果，包括放弃的那个。

【失败原因】每个被放弃的方案，写清是哪里不行，而不是「不好用」。

【最后选择与复现步骤】为什么选它，以及从头再做一遍要做的几步。

每段写多少，我也给自己划了上限。写不动的时候先按这个量级填，填完再判断要不要补。

段落	要写什么	大概字数
一句话结论	做法 + 适用场景	不超过 50 字
假设与约束	版本、环境、不能动的东西、未验证的前提	3 到 5 条
试过的方案与结果	方案名 + 结果，一行一个	每条一行
失败原因	具体卡在哪一步、报错是什么	每条 1 到 3 句
最后选择与复现步骤	选择理由 + 可照做的步骤	5 到 8 步

模板里我最常省掉、也最不该省的是第二段。写假设与约束很别扭，因为它要求承认「有些事我没验证过」。但恰恰是这一段，在三个月后最救急：它告诉我当年在什么条件下成立，换了环境要不要重新做一遍。

四、命名和索引

文件名我改成「问题—结论」的形式，例如「启动慢—先查初始化顺序」「批量导入超时—分批加幂等」。这样即使想不起内容，看文件名也知道有没有相关记录。以前那种「学习笔记3」「临时记录」的命名，等于给未来的自己设了一道门。

一个主题一个文件，不按日期分。同一个问题我可能会遇到三四次，都追加到同一个文件里，下面标上日期。末尾固定留三行「相关」，链接到相邻主题的文件——通常是排错时顺手发现的另一条线索。三行是上限，多了就不再是索引，而是又一个收藏夹。

五、只在三种时刻写

不设「每天写笔记」的目标。那样的目标最后产出的是日记，不是技术记录。我只在三种时刻动笔：

做了一个不太显然的决定：例如选了一个不常见的参数，或者绕开了一个看起来该用的方案
踩了超过半小时的坑：半小时是个分界，低于它的不值得记，高于它的一定要记
同一个问题第二次出现：第一次可以不写，第二次说明它会再来，这时候写最省事，因为两边的差异刚好清楚

三种时刻的共同点是：写完能立刻省下下一次的时间。其余时候我不写，也不觉得欠了什么。以前我试过按周整理，整理出来的内容大半是「本周读了几篇文章」，对排错没有帮助。

六、三个月自测

这个方法我也验证过。挑三篇三个月前的旧笔记，找一台干净的环境，照着做一遍，不查别的资料。哪一步卡住，卡住的那句话就是要补的地方。

我第一次自测，三篇里有两篇卡在同一个位置：没说清当时用的是哪个版本，命令在原环境能跑，在新环境报错。补上版本这一行之后，这两篇才真正变成能用的记录。自测不用多，一季度一次，每次三篇，半小时左右。

七、三个常见的坑

第一个坑是写成教程体。「第一步、第二步、第三步」写得很整齐，但把前提和失败方案都磨掉了，读起来像文档，用起来还是不知道怎么判断。技术笔记的重点是判断依据，不是步骤的完整性。

第二个坑是只记结论不记约束。结论离开约束就不成立，甚至会有害——同一个做法在另一种数据量下可能是灾难。这也是我把「假设与约束」单独设成一段的原因。

第三个坑是复制日志不写上下文。几十行报错贴进去，没有说明是在什么操作之后出现的、之前改过什么。这样的日志三个月后连我自己都读不懂。现在我只留三到五行关键信息，并在上面写一句「在什么操作之后出现」。

笔记这件事，写得少一点、写清楚一点，反而更愿意写。我现在一个月大概只新增两三篇，但没有一篇是三个月后读不懂的。这个数量，比我以前存几百条链接的时候有用得多。