上周让 Claude Code 协助重构一个旧模块。它相当听话，三分钟内给出了一个近乎完美的方案，然后我盯着屏幕陷入了沉思。
因为它提出的设计模式，正是三年前我决定不再采用的那种。问题并不出在 AI 本身，而在于当初那个决定——那个决策从来没有被记录下来，AI 自然无从得知。
没有把“为什么不做”写下来。
1. 我们最值钱的经验，都在脑子里“睡大觉”
20 世纪英国哲学家迈克尔·波兰尼（Michael Polanyi）有个著名论断：We know more than we can tell——我们所知道的，远比能够表达出来的多。
这句话在软件行业显得格外刺骨。
回想一下，日常工作中多少判断是靠“直觉”作出的： - 为什么这个模块“只能这么写”？答案往往是“经验告诉我的”。 - 为什么那个接口“千万别动”？因为踩过坑，吃过亏。 - 为什么这个架构“虽然丑但稳”？别问，问就是历史包袱。
这些“只可意会”的东西，才是资深工程师真正的护城河。
但问题是，AI 只能看到静默的代码，读不到脑中的“为什么”。
一个真实场景
有位同事老张，在修复一个 Bug 时，AI 给出了五种方案。他随手选了一个看似最快的。
结果两周后，另一个功能崩了。原因很简单——那个“最快方案”无意间破坏了一个隐式的业务约束。
老张很郁闷：“我怎么知道它不知道这个约束？”
答案或许有些残酷：因为你从没把它写下来。
2. AI 成了“最笨的读者”：它不懂你的潜台词
过去写文档，是为了“整理已经想清楚的事”。
现在让 AI 干活，必须写“那些从未想清楚过的事”。
为什么？
因为 AI 有一个显著特点：它不理解和接受模糊指令。
# 你以为你说了“足够清楚”
“优化一下这个函数”
# AI 看到的
“随便改，只要跑起来就行”
# 你想要的是
“优化这个函数，但要保证：
1. 不破坏向后兼容（因为 V2 API 还在用）
2. 不能增加超过 50ms 延迟（SLA 约束）
3. 保留原有的错误重试逻辑（业务要求）”
看清了吗？那些“理所当然”的假设，AI 根本看不到。
被迫“显性化”的代价
前阵子整理项目的 project.md，列了一份“十不做”清单：
不做继承超过两层的抽象 不做“未来可能用到”的扩展点 不在业务代码里加
V2、V3这种命名 不让if-else嵌套超过三层 ...（还有五条）
写着写着突然意识到：这些规则，从未正式跟团队成员说过。
想说，一直想说，但始终没有说清楚。
直到 AI 的出现，逼着把这些规则写下来。
3. 三种知识，三种“显性化”难度
不是所有知识都难写。根据经验，大致可以分成三类：
显性知识（最容易）
就是那些“能写进教科书”的内容。
比如：
- Redis 是内存数据库
- Git 用 commit 提交代码
- RESTful API 用 GET/POST/PUT/DELETE
AI 已经很擅长处理这些，不用再费心教。
不过有意思的是——知道“是什么”和知道“为什么选它”，完全是两码事。
隐性知识（中等难度）
需要“做给你看”的知识。
比如：
- 怎么用 gdb 调试段错误
- 怎么看日志定位性能瓶颈
- 怎么在 Code Review 里温和地拒绝一个方案
这部分，AI 现在能帮忙“抄下来”。
举个例子，让 AI 观察如何使用 kubectl 排查 Pod 启动失败，它总结了七步排查法。现在新人直接照着做就行。
缄默知识（最难）
还是波兰尼所说的“只可意会不可言传”的部分。
比如：
- “这个需求感觉不对劲”（但说不出为什么）
- “这段代码看着就别扭”（但能跑）
- “选方案 A 不选 B”（因为某些历史原因）
这部分，AI 会逼着第一次进行“文本化”。
一个有效的做法是写 TASTE.md（品味文档），不写硬性规则，只记录偏好：
# 我们的「品味」
1. 宁可复制粘贴，也不做“可能有用的抽象”
2. 认为“能跑的丑代码”好过“优雅的过度设计”
3. 更信任“一眼能看懂的 50 行”而不是“精巧的 10 行”
4. 相信“显式的错误处理”胜过“优雅的异常链”
这称不上“规则”，最多算是偏好的影子——尽管，有影子总比没有影子好。
说到底，Harness engineering 和 AI agent Skill 的编写，本质上就是把“只可意会”的缄默知识，一步步结构化为显性知识的过程。
当写下 TASTE.md、WHY.md、NO.md，做的不是“写文档”——而是把那些从未被文本化的工程判断力，变成了可复用、可传承、可被 AI 理解的资产。
这就是从“我知道怎么做”到“我知道为什么这么做”的认知显性化。
4. 坑：别把“品味”变成“KPI”
这里有个坑，亲眼见过不少团队掉进去。
有个团队把“代码品味”量化成了数十条规则，然后用 AI 自动检查。
结果如何？
代码确实“合规”了，但没人敢再改动任何东西（生怕触犯某条规则）。新需求来了，大家先问“规则允许吗”，而不是“用户需要吗”。
这就是 Goodhart 定律：凡被度量的，都会被扭曲。
建议：留出“不可度量”的空间
在项目里故意留了四个“不写清楚”的地方：
战略方向感 → 只能聊，不能写（一写就僵化） 价值观底线 → 规则化就会出现“规则没禁止所以可以做” 肌肉记忆式禁忌 → 一旦被理性化就失效了 审美争论 → 两个资深工程师为代码吵一下午，本身就是健康信号
AI 是工具，不是老板。别让它替你做价值判断。
5. 从今天开始“显性化”：AI 不是缰绳，是镜子
如果想试试，有一个“三步走”方案值得参考：
第一步：写一份 WHY.md
别写“怎么做”，写“为什么”。
# 为什么这个模块这么丑？
因为 2023 年试过微服务化，结果：
- 网络延迟增加 30ms
- 调试复杂度指数级上升
- 新人入职周期从 1 周变成 1 个月
所以不是不会优雅设计，是代价太大。
AI 看到这个，就不会再建议“拆成微服务”了。
第二步：把“不”写下来
创建 NO.md 或 A VOID.md：
# 我们不做的事
1. ❌ 不要用多于两层继承（超过两层就拆）
2. ❌ 不缓存用户会话（因为一致性问题踩过坑）
3. ❌ 不在周五下午发布（血的教训）
4. ❌ 不用 `V2/V3` 命名（会让人觉得旧版还能用）
这些“不”，才是真正的经验财富。
第三步：定期“复盘”你的品味
每月花半小时，和团队一起聊：
“最近哪段代码让你觉得『别扭』？” “AI 给的方案哪里不对劲？” “如果重新来，你会改什么？”
把聊出来的东西，补充到 TASTE.md 里。
经验的影子，比规则有温度。
AI 只是逼着第一次面对那些“以为自己知道，其实从未想清楚”的事。
这哪里是效率工具？这是一场被迫的认知大扫除。
而且，这场扫除，才刚刚开始。
如果想试试“显性化”，从写下第一份 WHY.md 开始吧。你会发现，那些“说不清”的东西，才是你最值钱的资产。
