设计新功能或架构时，用第一性原理避免跟风式复杂化

在架构设计、功能规划、方案评审或头脑风暴时，判断该做什么、用什么工具、加多少复杂度，避免做出「X 的翻版」或过早复杂化。

适用场景

解决思路

1. 先问核心问题：我是在创造新东西，还是在评论已有东西？不要做「X but for Y」，先确认 Y 是否真的需要 X。
2. 默认从最简单架构起步，只有当痛点可测量时才增加复杂度；把复杂度当作有息技术债。
3. 按阈值触发升级：SQLite→Postgres（>10 并发写、>100GB、需 PostGIS/全文搜索）；单文件→多文件（>约 500 行或职责多重）；单体→服务（团队无法在同一代码库协作或需真正规模隔离）；静态托管→服务器（需认证、实时或服务端计算）；本地状态→云同步（多设备是已验证需求而非假设）。
4. 框架选择看是否提供真实杠杆：Next.js 用于全栈 React/SSR；Remix 用于数据密集与渐进增强；Astro 用于内容站与局部水合；SvelteKit 用于小包体且团队愿学；Rails/Django 用于快速 CRUD 与后台；FastAPI 用于 Python 异步 API；Hono/Elysia 用于边缘与轻量 API。反问：是框架服务于创造，还是创造服务于框架？
5. 需要单一能力而非生态、想掌控架构、退出成本重要时选库；团队有经验、上市时间关键、约定优于配置且框架观点契合时选框架。
6. API 暴露原语：便捷方法可以有，但高级用户能访问底层，不要隐藏机器。
7. 降低退出成本：数据可导出为标准格式，避免专有锁定，即使不用也记录退出路径。
8. 配置保持人类可读：YAML/JSON 可以，但避免 500 行嵌套条件；新成员应能在 10 分钟内读懂并修改，非显然设置就地注释。
9. 错误信息要教学：说明发生了什么、为什么、怎么办，复杂时链接文档。
10. 日志要可理解：机器用结构化 JSON，开发用人类可读格式，含时间戳、上下文、严重级别，无需专用工具即可搜索。
11. 文档与代码同处：每个重要目录放 README，API 文档从代码生成，记录架构决策（ADR），外部 wiki 仅用于入职与流程。
12. 本地优先：核心功能离线可用，数据用 SQLite/本地存储，计算尽量客户端，认证用本地会话；云仅用于同步、备份、多设备、OAuth/SSO、重计算。
13. 状态可检查：可序列化到文件用于调试，状态机显式而非隐式，可从快照复现。
14. 同步作为增强：本地尽量为真相源，同步失败不破坏应用，冲突解决显式且用户可控。
15. 云按需使用：Serverless 用于尖峰负载，边缘函数用于延迟敏感操作，托管数据库在运维成本高于费用时用，自托管在控制/成本/合规需要时用；反问云是服务用户还是服务你对规模的假设。
16. UI 即时反馈：用户操作 <100ms，长操作给诚实进度；安全时用乐观更新，进度指示反映真实工作，spinner 可以但不要伪造进度，可预测加载用骨架屏。
17. 加载状态要显示正在发生什么、尽量估计时间、长操作可取消、绝不伪造进度。
18. 状态可见：无需深挖即可看到状态，后台进程浮现，错误显著不隐藏，非显然时系统解释决策；无黑盒，重要操作有审计轨迹，开发工具中可检查状态。
19. 空间一致：加载后不布局偏移，不为用户重排，肌肉记忆有效，组件位置一致；导航可预测，后退可用，URL 可书签可分享，刷新后状态保留，深链可用。
20. 撤销与恢复在数据层实现而非仅 UI：默认软删除，有价值处版本化状态，记录恢复路径，「你确定吗？」不能替代撤销；不可逆操作要确认，永久删除前有宽限期，清楚说明后果。
21. 尊重注意力：通知需用户显式选择加入、有意义、适当批量、易调整或关闭；模态与打断由用户发起、可关闭、不必要不困住焦点、键盘可访问；音频绝不自动播放，视频仅在用户明确意图下播放，动效尊重 prefers-reduced-motion；用良好默认值消除设置，高级选项可用但不必需，复杂度渐进。
22. 拒绝衍生思维：不问 Y 是否需要 X 就做「X but for Y」、因竞品有而加功能、因教程用而用模式、因 FAANG 用而用架构。
23. 拒绝货物崇拜工程：照搬不同规模公司的「最佳实践」、3 人团队上微服务、单服务器负载上 Kubernetes、内部工具上 OAuth。
24. 拒绝过早复杂：为未来灵活性加抽象层、在规模问题出现前做规模架构、基础未稳先做功能、单用户未跑通先做实时。
25. 拒绝流程压过思考：用 Scrum 仪式替代真实思考、为合规而非清晰写文档、开会讨论开会、用路线图假装预测。
26. 评审设计时做第一性原理检查：这创造了什么新东西？为什么必须存在？什么因此变得可能？
27. 评审时做简单性检查：复杂度是挣来的还是假设的？新开发者能一小时内理解吗？解决核心问题的最简版本是什么？
28. 评审时做工具契合检查：工具选择服务创造还是创造服务工具？框架是否由团队经验与问题契合度证明？云依赖是必要还是假设？
29. 评审时做人类可读检查：配置能读懂吗？错误信息能教学吗？文档在开发者能找到的地方吗？
30. 评审时做 UI/UX 检查：反馈即时或诚实渐进吗？用户能看到系统在做什么吗？一切可恢复/可撤销吗？打断由用户发起吗？
31. 生成方案时先问：我们创造什么真正新的东西？使其可行的最简架构是什么？哪些复杂度由真实约束挣来？
32. 默认：能用的最简工具；团队熟悉且契合就用框架；尽量本地优先；云只在真正需要时用。
33. 增加复杂度仅当：痛点可测量而非理论、团队同意权衡、回到简单的路径已记录。
34. 偏离默认时写下一句理由（注释、ADR 或 README）；有效理由包括团队经验、业务时间线、合规要求、实测性能需求、用户研究反证；无效理由包括「大家都这样」「以后可能用」「教程用了」「这是最佳实践」。

适用边界 · 注意事项

• 当团队经验强烈偏向另一方案、业务时间线要求更快路径、有监管/合规要求、有实测性能需求或用户研究反证时，不应机械套用这些默认值。
• 不要把这些默认当法律；无文档理由的偏离和「大家都这样」「以后可能用」式理由不成立。
• 不适用于需要真正规模隔离、多用户协作、重计算或合规强制云依赖的场景，此时应显式升级并记录理由。