技术领导力与架构决策体系：把「我写最好的代码」变成「团队持续做出可回滚的好决策」

过去十几篇我们一直在往深处挖：C++ 对象模型、Qt 元对象系统、事件循环、渲染管线、CMake 工程体系。这些能力解决的是「我一个人能不能做对」；但从 Team Leader 走向桌面客户端架构师，真正的瓶颈会换一个位置——变成「一个十人团队，在两年时间里，能不能持续做对」。技术决策的不可逆程度决定了它比任何一次代码提交都更贵：一次提交写错了，revert 一分钟；把整个客户端的技术栈押在某个渲染方案上，错了要还两年。

所以今天要学的不是某个 API，而是一套把技术判断变成组织能力的基础设施：用 ADR 记录决策、用单向门/双向门给决策分级、用三层评审保证质量下限、用康威定律审视组织结构、用技能矩阵把个人能力变成团队能力。这套东西在 Web 前端团队里你其实已经零散见过（RFC、PR Review、lint 规则），只是当时没有被你显式地建成体系。

2.1 两种门：不可逆性决定流程成本

贝索斯提出的 one-way door / two-way door 是团队管理里性价比最高的一条判据。双向门决策可以低成本回退（日志库换个实现、某个类的接口调整），过重流程只会拖慢团队；单向门决策回退代价极高（Qt 版本基线的选定、Widgets 还是 QML 作为主 UI 技术、进程模型是单进程还是多进程 + IPC、是否引入商业授权依赖），必须上会、必须记录、必须留下复审触发器。管理者的核心动作是把决策预先分类，而不是把所有事情都用一套流程处理——把双向门也送进评审会，是团队节奏被拖死的第一原因。

2.2 ADR：架构决策记录的四要素

Michael Nygard 在 2011 年提出的 Architecture Decision Record，本质是把「决策」当成一个版本化制品。一条 ADR 只需四件事：Context（当时的约束与事实，例如「Qt 5.15 已进入商业支持末期、我们要跨平台且必须用 CMake」）、Decision（明确的一句话决定，用主动语态：「我们采用 Qt6 + CMake target 体系」）、Status（proposed / accepted / superseded / deprecated）、Consequences（正反面后果都写，包括「旧插件 ABI 需要重新编译」这种疼的地方）。再补两块工程化字段：Alternatives considered（考虑过什么、为什么没选，这是半年后别人不推翻你的唯一保险）和 Revisit trigger（什么条件出现时应当重新评估，例如「Qt6 某模块被弃用」「团队 QML 人力达到 3 人」）。ADR 放在仓库 docs/adr/0007-qt6-migration.md 里跟代码同生命周期——文档不入仓，等于没写。

2.3 三层评审：各管一件事

• 设计评审（Design Review，决定前）：审的是 ADR 与接口契约，参与者含上下游与测试；目标是把错误拦在写代码之前，成本最低。
• 代码评审（Code Review，合入前）：审正确性、契约、可维护性；风格不该由人评——clang-format / clang-tidy / CTest 能自动化的，一律自动化，人只评审机器判断不了的。
• 复盘（Postmortem / Retro，出事后或定期）：审的是流程与系统，而不是某个人；输出可执行的改进项，并且要有人跟踪关闭。

把三层混用是常见失控点：在 PR 里吵架构，等于让最重要的问题在最晚、信息最少的时间点被讨论。

2.4 康威定律与团队边界

康威定律：系统架构必然映射组织的沟通结构。你有「UI 组」和「内核组」，最后就得到一个沟通成本极高的分层接口；你想让插件体系成功，就必须先有能独立拥有插件的团队。Team Topologies 把团队分为 stream-aligned（对齐业务流的交付团队）、platform（提供内部平台，如构建/发布/UI 组件库）、enabling（短期赋能其他团队，如 Qt 性能小组）、complicated-subsystem（专攻难题，如渲染器）。对客户端团队可直接套用：架构师常常应当是 platform 或 enabling 角色，而不是「什么都自己写的那个人」。架构调整要问一句：这次改动是不是需要同步调整团队的交互模式（长期配对、内源贡献）？

2.5 决策权：不要用共识冒充决策

共识驱动在技术决策上常常是最慢又最模糊的路径——每个人都有否决权，于是没人有责任。实践里常用 DACI/RACI 明确四种角色：Driver（推进者）、Approver（唯一决策者）、Contributor（提供输入）、Informed（被告知）。架构师的成熟标志是：愿意在信息不完整时给出可撤销的决定，并明确谁是 Approver。技术评审不是投票，而是「决策者听完反对意见后负责」。

2.6 能力梯队：技能矩阵与传帮带

把团队能力当成可观测系统：一张技能矩阵（行是人，列是能力项如 Modern C++ 语义、Qt Model/View、并发与线程亲和性、CMake 与打包、调试与性能剖析），每格标 0–3 级。矩阵立刻暴露三类风险：单点（某项只有一人 3 级）、断层（没人 2 级以上）、错配（人成长目标与项目任务长期不一致）。配套动作是评审轮值和结对：让 1 级的人评审 2 级人的代码、3 级的人只做兜底，是性价比最高的培养方式。

3.1 Qt5 → Qt6 迁移：一份 ADR 决定三年开发效率

这是典型单向门。约束事实包括：Qt 5.15 的商业支持窗口收尾、Qt6 全面转向 CMake（qmake 不再是主力）、QRegExp/QTextCodec/QString::split 默认行为等 API 变化、Qt6 的 QML 编译（qmlcachegen、qt_add_qml_module）显著改善启动性能。这些事实不改，迁移理由会随时间自我强化——所以正确做法是把事实与决定分开写进 ADR，而不是在群里说「Qt6 是新版本，该升了」。反面案例很常见：团队没有记录备选方案（例如分模块灰度迁移、先迁构建体系再迁 API），两年后新人会重新提出一遍已经被否决过的方案。

3.2 Widgets 还是 QML：技术题，实际是组织题

判据往往不是「哪个更好」，而是你的团队和产品节奏长什么样。VSCode 的界面高度自定义、需要密集文本与命令流，选择了自绘（Canvas/DOM 与自定义渲染）+ 命令式编程，性能与可控性优先，风格由主题系统而非回退到框架动效；而不少国内 IM 类客户端（QQ、微信等）在皮肤、动效、多端一致性上投入大，向声明式 UI 靠拢收益更高。结论不是某一个选项对，而是：决策必须写明「我们的团队现在拥有什么能力、产品未来两年最需要什么」。如果团队只有 0.5 个人懂 QML，却因为「QML 更现代」把主界面押过去，那是一次以组织能力赌技术趋势的错误下注。

3.3 Code Review 的工业共识：假设作者是对的

Google 的工程实践文档里有一条反直觉的规则：评审者应当默认批准，除非能证明这次提交使代码质量下降。它设计出来是为了对抗两种失败模式——评审者把自己变成守门人，导致评审成为团队瓶颈；以及评审沦为风格战场。同理，JetBrains 这类公司把「设计评审」作为正式环节：先看接口与责任划分，再看实现。改变代码质量下限的从来不是天才，而是评审标准被写下来、被自动化、被持续执行。

3.4 康威定律在客户端项目里的具象后果

如果你有两个仓：client-ui 与 client-core，由两个团队分别拥有，那么最终接口一定会变成「又厚又稳定、谁都不敢改」的窄腰，跨仓改动要两轮排期。插件化架构（09-04 那篇）能不能落地，先看团队边界是否允许插件作者独立发布。当架构卡住时，先看组织结构；当组织优化时，别忘了架构也需要同步调整。平台组（platform team）存在的意义正是把这种跨团队的公共能力（构建、发布、UI 组件、日志与崩溃上报）从每个交付团队身上剥出来。

• 1）先分类，再选流程（何时用 / 何时不用）。每个决策先回答「它可回退吗」。可逆决策：不要开会，作者自决 + 在 PR 描述里留一句理由；中等可逆：一位 Approver + 24 小时异议窗口；不可逆：ADR + 设计评审 + 复审触发器。Trade-off 很清楚——流程越重越慢，但拦下的错误越贵。团队真正的效率来自把重流程只花在最贵的地方。
• 2）ADR 入仓、只增不删、用状态演进。决策被推翻时，新开一条 ADR 并把旧的标为 superseded by 0012，而不是编辑历史。好处是新人能从时间线看到「为什么当年那么选」。何时不用：一次性的技术尝试（spike）不要写 ADR，用实验记录即可；真正的单向门才值得。
• 3）评审三层分明，风格一律交给工具。设计评审看接口与责任边界；代码评审按固定优先级看：正确性与资源语义 → 接口契约 → 可维护性 → 风格（自动化）。给评审意见分级 blocking / suggestion / nit，nit 不阻塞合入。约定 Review SLA（如工作日 4 小时首次响应）与轮值评审人，避免某个资深工程师成为唯一瓶颈。
• 4）决策权显式化，一人负责。用 DACI 写清 Driver/Approver/Contributor/Informed。技术评审不是投票：Approver 必须听完反对意见后拍板，并允许「有条件的决定」（例：先按 QML 做原型，三个月后按性能与人力数据复审）。这比强行共识更快，也比一言堂更有纠错能力。
• 5）用技能矩阵消灭单点，用轮值评审制造传帮带。每季度更新一次矩阵（0–3 级），针对每个「单人 3 级」的项目指定培养对象并安排结对；让 1 级的人评审 2 级的代码、3 级只做兜底。管理者要提醒自己：你亲自写掉的那部分最难代码，恰恰可能是团队最需要成长的地方。
• 6）复盘只看系统，不看人；改进项必须闭环。Blameless postmortem 的产出是流程/工具/测试的修改，每条都要有负责人与截止日，下次复盘先检查上次的改进项是否关闭。否则复盘会退化成情绪会议。

作为前端出身的架构师，你手里有一副现成的牌，只是没被当成制度用起来。

RFC 流程 ↔ ADR。Vue 3 的每个重大特性都先走 RFC（Request for Comments）：写清动机、设计、备选方案、缺点，公开讨论后才实现；这正是 ADR 的「决策前制品」形态。你在前端团队里可能只是「拉个群讨论」，到了 C++ 世界，把讨论固化成 Markdown 入仓就是同一件事的更严版本。

ESLint / Prettier / lint-staged ↔ clang-format / clang-tidy / pre-commit。前端早就承认「风格问题不该由人评审」，所以才有格式化工具与 CI 卡口。C++ 的等价物是 .clang-format + .clang-tidy + CTest 门禁；你在前端建立的「机器管风格、人管设计」原则可直接平移，只是 C++ 里机器能救你的地方更多——未初始化成员、悬垂引用、隐式拷贝这类问题，静态分析和 -Wall -Wextra -Werror 都能在合入前拦住。

平台组 ↔ 前端组件库 / 构建基建团队。前端的 monorepo + 组件库 + CI 模板团队，就是 Team Topologies 里的 platform team；在客户端项目里对应「构建与发布、UI 组件库、日志与崩溃上报」的公共能力团队。康威定律在前端同样成立：微前端拆分的边界，最终就是组织结构与团队自治边界的映射——插件化架构（09-04）和微前端是同一个组织问题的两种技术表达。

版本与依赖矩阵 ↔ 运行时/框架兼容矩阵。前端有 Node LTS 策略、浏览器兼容矩阵、canary 版本；客户端有 Qt LTS 与商业支持窗口、编译器（MSVC/GCC/Clang）与 C++ 标准版本矩阵、vcpkg 依赖治理。它们的决策结构完全相同：支持多久、谁负责升级、什么时候必须升级——所以这些天然就是 ADR 题目。

理解层面：你的产出不再是代码行数，而是「团队决策的平均质量」与「决策的返工成本」。首先要抵抗的冲动是替所有人做决定——那会让团队失去判断力，也让你成为瓶颈；其次才是建立流程。判断自己做得对不对，看两件事：团队里有多少「不需要问你也能做对」的决策，以及不可逆决策的返工率。

指导层面：用问题代替答案（「这个接口下一年谁改它？」「如果 QML 人力只剩一人，这个方案还成立吗？」），让成员自己写出 Consequences。给成长路径配任务：想升到架构的成员，第一课不是写更难的代码，而是独立产出一份能被评审通过的 ADR，并负责它在三个月后的复审。

Code Review 关注点（C++/Qt 专用顺序）：①生命周期与资源语义——RAII 是否完整、有无悬垂引用/裸 new、对象是否在正确线程（QObject 亲和性与信号槽连接类型）；②接口契约——const 正确性、错误处理策略是否统一（异常 vs std::expected）、拷贝与移动语义是否明确；③可维护性——职责是否单一、是否有测试；④风格——交给工具。评审意见要说明「为什么」（尤其涉及未定义行为与性能时），对新人用提问式评论，对重复出现的同类问题，转化为规则或静态检查项，而不是第 N 次口头提醒。

• Camille Fournier《The Manager's Path》——技术人转管理的阶段地图，从 Tech Lead 到管理多个团队每一步的职责变化讲得最具体，读完能准确判断自己卡在哪一级。
• Will Larson《An Elegant Puzzle: Systems of Engineering Management》——把组织问题当系统问题处理：人力模型、流程排队、团队规模与架构的匹配，适合喜欢用工程思维做管理的架构师。
• Matthew Skelton & Manuel Pais《Team Topologies》——康威定律的现代操作手册，四种团队类型与三种交互模式，直接可用于客户端团队的组织切分。
• Neal Ford 等《Software Architecture: The Hard Parts》——讲架构权衡与「决策记录」如何落地，对分布式与耦合取舍的分析最适合有跨模块治理需求的人。
• Michael Nygard, “Documenting Architecture Decisions”（2011，cognitect 博文）——ADR 的原始定义，只有几页，是这条实践的标准源头；配合 Google eng-practices 的 Code Review 指南一起读，就能拿到「决策记录 + 评审文化」的完整底座。

目标：把「决策分级 + 必备字段」变成可执行的规则，而不是口头约定。程序对每条 ADR 判断它是单向门还是双向门，检查必备字段，给出应走的评审路径，并在缺字段时以非零退出码阻塞 CI。

代码（C++17，adr_gate.cpp，可直接编译）：

#include <iostream>
#include <string>
#include <vector>

struct Adr {                       // 一条架构决策记录的精简视图
    std::string id, title, door, status;
    bool hasConsequences, hasAlternatives, hasRevisit;
};

std::vector<std::string> missingFields(const Adr& a) {
    std::vector<std::string> m;
    if (a.title.empty())      m.push_back("Title");
    if (a.status.empty())     m.push_back("Status");
    if (!a.hasConsequences)   m.push_back("Consequences");
    if (a.door == "one-way") {     // 单向门：额外强制两项
        if (!a.hasAlternatives) m.push_back("Alternatives considered");
        if (!a.hasRevisit)      m.push_back("Revisit trigger");
    }
    return m;
}

int main() {
    const std::vector<Adr> adrs = {
        {"0007", "Qt6 迁移",        "one-way", "accepted", true,  true,  true },
        {"0008", "日志库换 spdlog", "two-way", "accepted", true,  false, false},
        {"0009", "主界面改用 QML",  "one-way", "proposed", true,  false, false},
    };
    int blockers = 0;
    for (const auto& a : adrs) {
        const bool oneWay = (a.door == "one-way");
        const auto miss = missingFields(a);
        std::cout << "[" << a.id << "] " << a.title
                  << "  door=" << a.door << "  status=" << a.status << "\n";
        std::cout << "  评审路径: "
                  << (oneWay ? "设计评审 + 唯一 Approver + ADR 入仓"
                              : "作者自决 + PR 留理由（事后通知）") << "\n";
        if (oneWay && a.status != "accepted")
            std::cout << "  ⚠ 未决单向门：禁止开工，先补齐评审\n";
        if (miss.empty()) {
            std::cout << "  字段完整 ✓\n";
        } else {
            ++blockers;
            std::cout << "  缺失: ";
            for (const auto& f : miss) std::cout << f << " ";
            std::cout << "→ 阻塞合入\n";
        }
    }
    std::cout << "门禁结果: " << (blockers ? "阻塞 " : "通过 ")
              << blockers << " 条待补齐\n";
    return blockers ? 1 : 0;       // 非零退出码即可接入 CI
}

CMakeLists.txt：

cmake_minimum_required(VERSION 3.16)
project(adr_gate LANGUAGES CXX)
add_executable(adr_gate adr_gate.cpp)
target_compile_features(adr_gate PRIVATE cxx_std_17)

运行（也可不用 CMake，直接编译）：g++ -std=c++17 -Wall -Wextra -O2 adr_gate.cpp -o adr_gate && ./adr_gate; echo "exit=$?"，或用 Qt 项目一贯的 cmake -S . -B build && cmake --build build。