我写了上百篇技术笔记，然后删掉了八成

35+ 工程师最值钱的东西不是知识，是「当时为什么这么决定」

一、一个找不到的坑

去年有天下午，我要查一个构建问题。

不是难题，恰恰相反——是一个三个月前我自己踩过、当时花了两天、后来靠某个开关绕过去的坑。

我记得很清楚：这个问题我解决过，答案就在我的笔记里。

然后我打开了十几个目录。

~/技术笔记/
├── c++/
├── qt/
├── cmake/
├── python/
├── ai/
├── 踩坑合集/
├── 临时记录/
├── 未整理/
└── 新建文件夹(3)/

四十分钟后，我关掉了编辑器。

那两条记录确实存在。但它们是这么写的：

> Q：CMake 的 PUBLIC 和 PRIVATE 有什么区别？
> A：一个是自己用，一个是自己用也传出去。

……所以我等于没记。

那天晚上我把笔记翻了一遍，做了一件当时看起来很反常的事：

删掉了其中八成。

二、我的笔记出了什么问题

我不是不写。我写得不少——这个工作区里现在就躺着 7 份系列规划、上百篇技术长文，几十个目录。

但那天晚上我意识到一个问题：我一直在记录「是什么」，从来没记录「为什么」。

2.1 ❌ 三种看起来很努力、其实没用的记录

第一种：知识点搬运

❌ 把官方文档用自己的话抄一遍

> Q：CMake 的 target_include_directories 为什么要用 PRIVATE？
> A：为了不污染其他 target 的包含路径。

三个月后读到这里：我还是不知道什么时候该用 PRIVATE。

这不是笔记，这是伪装成笔记的文档副本。它让我产生了「我已经学过了」的错觉，而错觉比空白更危险。

第二种：结论无出处

❌ 一句孤立的结论，不带任何上下文

> 静态库改 SHARED 之后单例会分裂。

为什么？分裂成几份？在什么加载方式下会分裂？我当时是在哪个项目上遇到的？
——全都没记。

这种记录最坑的地方在于：**它短、它清楚、它看起来很专业。**但它无法被复用，因为它没有坐标。

第三种：临时记录永不归档

❌ 排障现场随手记，解决问题后从来不清理

tmp/
debug1.txt
debug2.txt
终于好了.txt
debug2-真的最终版.txt

我电脑里长期存在一个叫 tmp 的目录，里面躺着三年来的临时记录。

2.2 三个判据：这条笔记到底该不该留

那天晚上我给每一条笔记过了一遍筛子。判据只有三个：

判据 1｜半年后还能找到吗？
→ 判据：它在不在一个有结构的目录里，
而不是躺在「未整理」或某个人的桌面
→ 不通过 → 归档或删掉

判据 2｜它能直接指导下一个决策吗？
→ 判据：读完之后，我能不能在没有上下文的情况下
做出一个不同的选择
→ 不通过 → 它是知识，不是资产

判据 3｜它带具体的坐标吗？
→ 判据：有文件路径、函数名、开关名、参数名吗
→ 不通过 → 它是浮空的

三个判据，砍掉了八成。

剩下的那两成，第一次变得真正有用。

三、正面教材：一份审计报告长什么样

我第一次感受到「记录也可以是资产」，是在 AutoPlatform 这个项目里。

那个项目有 2000 个左右的源文件、C++17 + Qt6 + MSVC x64。任何人第一次打开它都会懵。

但项目里有一份《项目现状与问题报告》。那份报告只有几十页，我读完之后对整个项目的判断清晰了一个量级。

它厉害在哪？它同时做了两件互相矛盾的事：

既夸自己，又骂自己。

3.1 ✅ 优秀实践（举三条真实记录）

✅ 优秀实践 1：bootstrap 清单与源码同步
9 个引导模块按 priority 分层排布：
Logger=5 → SplashScreen=9 → Config=10 → Database=20
→ PluginLoader=100 → Hal=400 → Device=500
→ Scheduler=600 → Scripting=700
数值之间留了间隔，方便以后插入新模块。
位置：app/bootstrap/*_module.cpp

注意这段记录里有什么：有优先级数字，有顺序，有间隔策略，有文件路径。

半年后我读到它，不用问任何人，就能明白当时的设计意图。

✅ 优秀实践 2：SHARED 链接约束写进了 README 显眼位置
extensionsystem 与 container 必须保持 SHARED 链接，
改成静态的话，单例会在每个 DLL 里各存一份。
位置：README.md 注意事项第 1 条

这段为什么值钱？因为它记录的是一个会导致静默失败的坑。这种知识只能靠踩过才能获得，而踩过的人如果不说，它就永远消失。

✅ 优秀实践 3：分批小步转换，每批一个独立提交
不一口气改完，出了问题能定位到具体是哪一批。
位置：git 提交 f9897e6 / b3772f6 / 07f4122

3.2 ❌ 可改进之处（举三条真实记录）

❌ 可改进 1：死选项
DEVICE_*_BUILD 这组开关，文档写着可以
-DDEVICE_ZG13_BUILD=ON 打开，
实际构建行为纹丝不动。
它看起来是个功能，实际是个谎言。

❌ 可改进 2：孤儿静态库
33 个库编译产出但零链接
（services 11 / business 7 / data 3 / device 12）。
编译成本一直在付，收益是零。

❌ 可改进 3：调试产物污染仓库
仓库根目录残留 crash dump、main.obj、
stdout/stderr.txt、nul 占位文件。

现在回头看这三条「可改进」——它们比我抄过的所有 API 文档加起来都值钱。

可改进之处比优秀实践值钱，因为前者可执行，后者只可欣赏。

优秀实践告诉你「哦，原来还可以这么写」。

可改进之处告诉你「这里会死，别碰」。

对一个 35 岁的工程师来说，第二种知识才是真正的资产。

四、我现在用的记录格式

从那份报告身上，我偷了一个格式。后来它变成了我所有系列规划的固定板块，叫项目双面分析：

┌─────────────────────────────────────────────────┐
│ 项目双面分析 │
│ │
│ 优秀实践（≥3 条） 可改进之处（≥3 条） │
│ ─────────────── ─────────────────── │
│ ✅ 具体做法 ❌ 具体问题 │
│ ✅ 为什么这样有效 ❌ 为什么会发生 │
│ ✅ 引用文件位置 ❌ 引用文件位置 │
│ ✅ 可复用 ❌ 优先级 + 根治动作 │
│ │
│ 引用文件清单： │
│ – 具体文件路径 │
│ – 具体函数/开关名 │
│ – 具体 git 提交号 │
└─────────────────────────────────────────────────┘

四个硬性要求，一个都不能少：

4.1 一条记录的最小格式

这是我现在实际在用的模板，一分钟能填完：

## 现象
一句话说清楚遇到了什么。
（不写「系统不稳定」这种无法定位的描述）

## 环境
项目 / 版本 / 配置：能不能复现？
位置：具体文件路径 + 函数名 + 开关名

## 我当时怎么想的
这一步是关键。
记录我为什么做出那个判断，而不只是我做了什么。

## 实际结果
– 对的：→
– 错的：→
– 意外发现：→

## 下次怎么做
一条可执行的规则，必须具体到能照做。

## 引用
– 文件：…
– 提交：…

第三栏「我当时怎么想的」，是我后来加的。

加完之后，我那八成被删掉的笔记，有一部分可以救回来。 因为判断还在，只是丢了坐标和上下文。

五、过期文档比没有文档更危险

这是我最想警告同行的部分。

5.1 一次真实的信任崩塌

我在 AutoPlatform 里踩过一个具体的坑：想打开某个设备型号的驱动。

项目文档写得很清楚：

启动参数里加 -DDEVICE_ZG13_BUILD=ON
即可启用 zg13 驱动的编译

我照着做了。

编译通过了。产物里没有这个驱动。运行时它还是没加载。

我把那行参数改了十几次，每改一次就重编一次。半小时之后我才反应过来——这不是我配错了，是这个开关是死的。

文档说： 这是一个功能，你这样就能用
构建说： 这是一段装饰，你怎样都没用

5.2 信任是怎么被消耗的

第一次踩坑： 我怀疑自己
第二次踩坑： 我怀疑这个项目
第三次踩坑： 我不再相信任何文档，只相信我亲手验过的

第三步是不可逆的。

一个假开关消耗的不是 CPU，是团队对文档的信任。 而信任一旦崩塌，所有文档的价值都归零——因为没人敢不看代码了。

5.3 所以知识资产的唯一 KPI 不是数量，是过期率

这是我改掉「笔记越多越好」这个执念的原因。

❌ 旧指标：笔记条数、知识库体积、覆盖的技术点数量
→ 都会让人误以为「存下来就是资产」

✅ 新指标：过期率
有多少条记录在半年后被验证为仍然成立？
多少条因为项目演进而失效了？

不测过期率的笔记系统，一定会变成垃圾场。

因为知识会过期，而过期的知识比没有知识危险。

我现在的做法很土：任何一条记录，如果半年后没被重新验证过，我就给它打个标记。到了那个标记时间，我要么去看一眼确认它还成立，要么就删掉。

宁可少，不可旧。

六、我的目录长什么样

不优雅，但它能用。核心是三层，每层只解决一个问题：

职业笔记/
│
├── 01-项目/ ← 层一：按项目隔离
│ ├── Aether/
│ │ ├── 01-优秀实践.md
│ │ ├── 02-可改进之处.md
│ │ └── 03-踩坑记录.md
│ ├── AutoPlatform/
│ │ ├── 01-优秀实践.md
│ │ ├── 02-可改进之处.md ← 死选项、孤儿静态库在这
│ │ └── 03-踩坑记录.md
│ └── AOI/
│
├── 02-判断/ ← 层二：跨项目可迁移的原则
│ ├── 分批改造的收益.md
│ ├── 死选项的识别方法.md
│ └── 文档必须与构建同步.md
│
└── 03-待验证/ ← 层三：给自己上的枷锁
├── 2024-11-CMake生成器表达式.md ⏰
├── 2025-03-OBB角度折算.md ⏰
└── 2025-08-ONNX opset兼容性.md ⏰

三层的分工必须清楚：

03-待验证/ 这一层是我最推荐加的。

它逼你承认：你现在知道的很多东西，是有保质期的。

没有这一层，你会误以为自己已经掌握了全部。

七、一个诚实的自检

写到这儿，我想做一件不太舒服的事：区分一手经验与二手知识。

我笔记里的东西，其实分三类：

① 一手经验：我在真实项目里被它咬过
· 静态库改 SHARED 之后单例分裂
· 启动链的 priority 顺序不能乱，onShutdown 要与 onBoot 相反
· OBB 的角度不能直接当 C++ 倾角用，否则 97% 的样本会被误旋
· 调试产物会污染仓库根目录
特征：我说得出「当时项目是什么状态、我改了什么、结果如何」

② 二手知识：官方文档写得比我清楚
· CMake 的 PUBLIC / PRIVATE / INTERFACE 语义
· 深度学习的基本概念、损失函数、梯度下降
· 各种算法的推导过程
特征：我能讲清楚，但没为它付出过代价

③ 听起来很有道理
· 各类「最佳实践」「一文读懂」
特征：说得很顺，但我说不出它在哪个项目上救过我一次

第 ③ 类是最危险的，因为它和第 ① 类读起来一模一样。

区别只在于：你能不能说出它具体是从哪个项目、哪次故障、哪行代码里长出来的。

所以我给自己加了一条判定规则：

一条知识如果我讲不出「它从哪来」，那我在文章和评审里就不该拿它当依据。

这不是谦虚，这是自我保护——因为半年后有人问我「这个结论哪来的」，我必须答得上来。

八、写在最后

那天晚上删掉八成笔记之后，我并没有变得更博学。

事实上我变得更"笨"了——我知道的东西少了，因为我把假的和过期的都扔了。

但我第一次有了一种可靠的感觉：凡是我现在说得出「我知道」的，我都真的知道。

这种感觉很奇怪，它不像学会一个新框架那么兴奋。

它更像——

把一个房间里所有的灯都打开，
你会发现角落里其实堆着 30 年没人动过的箱子。

你没有力气全搬出去。
但你至少可以：
· 贴上标签，写清是什么
· 标出日期，承认它可能过期
· 标出路径，方便真要查的时候能找到

知识资产的目标不是「记住」。

是让你下一次不用从零踩一遍。

删掉八成之后，我第一次开始期待「翻开自己笔记」这个动作。

这感觉大概就类似于：终于把家里收拾干净了，客人来的时候，不用再为「你为什么还没收拾」道歉。

本期互动

• 你的笔记里，有多少条是「我到底为什么这么决定」而不是「这个东西是什么」？
• 你的知识库里，有没有一个明确标记「待验证」的目录？
• 你删过笔记吗？删的时候是什么感觉？

欢迎在评论区聊聊。

💬 评论区聊聊

我想问一个很具体的问题：

你的项目里，有哪些文档是「你不敢完全相信」的？

我先说我的：某个声称可以打开设备驱动的编译开关，文档和构建完全对不上。我那次白白的半小时，就是拜它所赐。

评论区说说你的。我很好奇，这件事到底是普遍现象，还是只有我们这些接手存量项目的人才懂。

👉 觉得有用，记得收藏 + 转发

如果你也维护着某个笔记目录，这篇也许能帮你下一次做减法。

转给那个「笔记最多但最不敢信」的朋友。