35 工程师最值钱的东西不是知识是「当时为什么这么决定」一、一个找不到的坑去年有天下午我要查一个构建问题。不是难题恰恰相反——是一个三个月前我自己踩过、当时花了两天、后来靠某个开关绕过去的坑。我记得很清楚这个问题我解决过答案就在我的笔记里。然后我打开了十几个目录。~/技术笔记/ ├── c/ ├── qt/ ├── cmake/ ├── python/ ├── ai/ ├── 踩坑合集/ ├── 临时记录/ ├── 未整理/ └── 新建文件夹(3)/四十分钟后我关掉了编辑器。那两条记录确实存在。但它们是这么写的 QCMake 的 PUBLIC 和 PRIVATE 有什么区别 A一个是自己用一个是自己用也传出去。……所以我等于没记。那天晚上我把笔记翻了一遍做了一件当时看起来很反常的事删掉了其中八成。二、我的笔记出了什么问题我不是不写。我写得不少——这个工作区里现在就躺着 7 份系列规划、上百篇技术长文几十个目录。但那天晚上我意识到一个问题我一直在记录「是什么」从来没记录「为什么」。2.1 ❌ 三种看起来很努力、其实没用的记录第一种知识点搬运❌ 把官方文档用自己的话抄一遍 QCMake 的 target_include_directories 为什么要用 PRIVATE A为了不污染其他 target 的包含路径。 三个月后读到这里我还是不知道什么时候该用 PRIVATE。这不是笔记这是伪装成笔记的文档副本。它让我产生了「我已经学过了」的错觉而错觉比空白更危险。第二种结论无出处❌ 一句孤立的结论不带任何上下文 静态库改 SHARED 之后单例会分裂。 为什么分裂成几份在什么加载方式下会分裂我当时是在哪个项目上遇到的 ——全都没记。这种记录最坑的地方在于**它短、它清楚、它看起来很专业。**但它无法被复用因为它没有坐标。第三种临时记录永不归档❌ 排障现场随手记解决问题后从来不清理 tmp/ debug1.txt debug2.txt 终于好了.txt debug2-真的最终版.txt我电脑里长期存在一个叫tmp的目录里面躺着三年来的临时记录。2.2 三个判据这条笔记到底该不该留那天晚上我给每一条笔记过了一遍筛子。判据只有三个判据 1半年后还能找到吗 → 判据它在不在一个有结构的目录里 而不是躺在「未整理」或某个人的桌面 → 不通过 → 归档或删掉 判据 2它能直接指导下一个决策吗 → 判据读完之后我能不能在没有上下文的情况下 做出一个不同的选择 → 不通过 → 它是知识不是资产 判据 3它带具体的坐标吗 → 判据有文件路径、函数名、开关名、参数名吗 → 不通过 → 它是浮空的三个判据砍掉了八成。剩下的那两成第一次变得真正有用。三、正面教材一份审计报告长什么样我第一次感受到「记录也可以是资产」是在 AutoPlatform 这个项目里。那个项目有 2000 个左右的源文件、C17 Qt6 MSVC x64。任何人第一次打开它都会懵。但项目里有一份《项目现状与问题报告》。那份报告只有几十页我读完之后对整个项目的判断清晰了一个量级。它厉害在哪它同时做了两件互相矛盾的事既夸自己又骂自己。3.1 ✅ 优秀实践举三条真实记录✅ 优秀实践 1bootstrap 清单与源码同步 9 个引导模块按 priority 分层排布 Logger5 → SplashScreen9 → Config10 → Database20 → PluginLoader100 → Hal400 → Device500 → Scheduler600 → Scripting700 数值之间留了间隔方便以后插入新模块。 位置app/bootstrap/*_module.cpp注意这段记录里有什么有优先级数字有顺序有间隔策略有文件路径。半年后我读到它不用问任何人就能明白当时的设计意图。✅ 优秀实践 2SHARED 链接约束写进了 README 显眼位置 extensionsystem 与 container 必须保持 SHARED 链接 改成静态的话单例会在每个 DLL 里各存一份。 位置README.md 注意事项第 1 条这段为什么值钱因为它记录的是一个会导致静默失败的坑。这种知识只能靠踩过才能获得而踩过的人如果不说它就永远消失。✅ 优秀实践 3分批小步转换每批一个独立提交 不一口气改完出了问题能定位到具体是哪一批。 位置git 提交 f9897e6 / b3772f6 / 07f41223.2 ❌ 可改进之处举三条真实记录❌ 可改进 1死选项 DEVICE_*_BUILD 这组开关文档写着可以 -DDEVICE_ZG13_BUILDON 打开 实际构建行为纹丝不动。 它看起来是个功能实际是个谎言。 ❌ 可改进 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_BUILDON 即可启用 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 ⏰三层的分工必须清楚层作用特征01-项目/原始记录允许粗糙、允许过期一次性写允许重复02-判断/提炼产物全是可以迁移的原则必须写清适用条件03-待验证/自欺的照妖镜半年到期强制复核03-待验证/这一层是我最推荐加的。它逼你承认你现在知道的很多东西是有保质期的。没有这一层你会误以为自己已经掌握了全部。七、一个诚实的自检写到这儿我想做一件不太舒服的事区分一手经验与二手知识。我笔记里的东西其实分三类① 一手经验我在真实项目里被它咬过 · 静态库改 SHARED 之后单例分裂 · 启动链的 priority 顺序不能乱onShutdown 要与 onBoot 相反 · OBB 的角度不能直接当 C 倾角用否则 97% 的样本会被误旋 · 调试产物会污染仓库根目录 特征我说得出「当时项目是什么状态、我改了什么、结果如何」 ② 二手知识官方文档写得比我清楚 · CMake 的 PUBLIC / PRIVATE / INTERFACE 语义 · 深度学习的基本概念、损失函数、梯度下降 · 各种算法的推导过程 特征我能讲清楚但没为它付出过代价 ③ 听起来很有道理 · 各类「最佳实践」「一文读懂」 特征说得很顺但我说不出它在哪个项目上救过我一次第 ③ 类是最危险的因为它和第 ① 类读起来一模一样。区别只在于你能不能说出它具体是从哪个项目、哪次故障、哪行代码里长出来的。所以我给自己加了一条判定规则一条知识如果我讲不出「它从哪来」那我在文章和评审里就不该拿它当依据。这不是谦虚这是自我保护——因为半年后有人问我「这个结论哪来的」我必须答得上来。八、写在最后那天晚上删掉八成笔记之后我并没有变得更博学。事实上我变得更笨了——我知道的东西少了因为我把假的和过期的都扔了。但我第一次有了一种可靠的感觉凡是我现在说得出「我知道」的我都真的知道。这种感觉很奇怪它不像学会一个新框架那么兴奋。它更像——把一个房间里所有的灯都打开 你会发现角落里其实堆着 30 年没人动过的箱子。 你没有力气全搬出去。 但你至少可以 · 贴上标签写清是什么 · 标出日期承认它可能过期 · 标出路径方便真要查的时候能找到知识资产的目标不是「记住」。是让你下一次不用从零踩一遍。删掉八成之后我第一次开始期待「翻开自己笔记」这个动作。这感觉大概就类似于终于把家里收拾干净了客人来的时候不用再为「你为什么还没收拾」道歉。本期互动你的笔记里有多少条是「我到底为什么这么决定」而不是「这个东西是什么」你的知识库里有没有一个明确标记「待验证」的目录你删过笔记吗删的时候是什么感觉欢迎在评论区聊聊。 评论区聊聊我想问一个很具体的问题你的项目里有哪些文档是「你不敢完全相信」的我先说我的某个声称可以打开设备驱动的编译开关文档和构建完全对不上。我那次白白的半小时就是拜它所赐。评论区说说你的。我很好奇这件事到底是普遍现象还是只有我们这些接手存量项目的人才懂。 觉得有用记得收藏 转发如果你也维护着某个笔记目录这篇也许能帮你下一次做减法。转给那个「笔记最多但最不敢信」的朋友。