摘要很多架构问题不是“当时没人想过”，而是“当时为什么这么选”没有被记录下来。几个月后，团队只看到一个技术方案，却不知道当初的约束、备选方案、权衡过程和风险假设。ADR（Architecture Decision Record，架构决策记录）是一种轻量文档，用来记录重要技术决策的上下文、选择、理由和后果。本文提供一套通用 ADR 模板，适用于微服务拆分、数据库选型、缓存方案、消息队列、云服务、CI/CD、可观测性、基础设施等技术决策。文中不包含任何内部系统名称、账号、密钥或业务敏感信息，可直接作为团队架构规范或 CSDN 技术文章使用。一、为什么需要 ADR团队经常会遇到这些问题：只知道用了某个技术，不知道为什么选它。新人不理解历史架构，只能猜测。同一个争论反复出现，浪费讨论成本。技术债没有记录，后续无人处理。方案失败后无法回看当初假设是否成立。ADR 解决的问题不是“写长文档”，而是把关键决策最小化记录下来：当时背景是什么？ 有哪些选择？ 为什么选这个？ 带来了什么后果？ 什么时候需要重新评估？二、哪些决策需要写 ADR不是所有技术细节都需要 ADR。推荐记录有长期影响、跨团队影响或难以回滚的决策。