一、一个奇怪但真实的现象
很多团队都会遇到这种情况：
- 老系统跑得很稳
- 代码结构看起来也不算乱
- 单元测试有一些
- 接口文档也齐全
但新同事一上手，就必写 bug。
而且这些 bug 的特点是：
- 不在语法
- 不在 API 使用
- 而是在“理解偏差”
这说明一个事实：
系统在“误导使用者”。
二、系统是“认知工具”，不是“代码集合”
我们往往低估了一个事实：
代码不仅是给机器执行的，也是给人理解的。
如果一个系统：
- 接口语义模糊
- 状态命名含糊
- 行为边界不清
- 副作用隐藏在调用内部
那么它会不断诱导开发者做错事。
三、三种最常见的“误导型设计”
1️⃣ “看起来能用，其实不该用”的方法
例如：
updateOrder(Order order)
看起来很正常，对吧？
但它可能：
- 修改状态
- 写日志
- 发 MQ
- 改库存
- 触发补偿
新人会自然认为：
“那我在任何地方调用它就好了。”
然后线上就炸了。
2️⃣ “状态名正确，语义错误”
例如：
- DONE
- FINISHED
- CLOSED
- COMPLETED
它们在英文里都差不多。
但在业务里，它们可能意味着：
- 可否退款
- 可否修改
- 是否可重试
- 是否可回滚
名字骗了人。
3️⃣ “默认行为过多”
例如：
- 不传参数就走默认逻辑
- 默认开启某些副作用
- 默认重试
- 默认补偿
默认行为越多，系统越像一个“黑箱”。
四、为什么优秀系统“限制很多”，但反而更好用？
因为优秀系统遵循一个原则：
让错误变得困难，而不是让正确变得依赖经验。
它们会：
- 强制调用顺序
- 强制状态检查
- 强制显式参数
- 强制声明意图
这在短期内会被抱怨“麻烦”，
但长期来看：
bug 会急剧减少。
五、真正成熟的系统，都会“教育使用者”
你会发现：
- API 自解释
- 错误信息明确
- 非法调用立刻失败
- 不给“将就用”的机会
这种系统在“逼人写正确的代码”。
六、一个很多人从未认真想过的问题
如果一个系统必须依赖“老员工经验”才能正确使用，
那它本身就是有缺陷的。
