Pit of Success：让正确调用成为默认路径

是什么 这条点赞指向 Sahaj 发布的“/pit-of-success”技能说明。它把“让正确行为成为默认路径”落实为一套 API 审查与重构清单：先定位公共 seam，再检查自然调用是否会触发隐藏前置条件或非法状态。内容不是框架教程，而是在讨论接口语义如何承载不变量。

核心设计 论证链条从遍历 seam 的所有调用方开始，执行 footgun test；修复优先让原 API 直接安全，其次收窄类型或 Schema，再通过重命名或拆分让危险路径显式，最后才考虑 helper。完成后删除本地 wrapper、重复 helper 与解释陷阱的注释，并用 focused test、类型断言和 grep 证明默认调用仍正确、旧绕过已消失。

关键洞察 价值在于把依赖团队记忆的约定迁回接口边界：坏状态最好不可表示，安全行为最好无需额外步骤。对 Agent 生成代码和多人维护尤其有启发，因为最自然的调用往往也是最可能被写出的调用。

边界与风险 这是接口设计与研发效能原则，不替代完整测试、兼容性评估或运行时安全审计。过度收窄类型、强行改变 seam 也可能破坏真实需求；应先确认不变量，再审查全部调用方。