running-an-architectural-assessment

针对倡议负责人开展的 Phase 2（研究）深度调研指南。交付成果：架构评估——一份位于 EN 空间评估文件夹中的 Confluence 页面，记录完善后的问题陈述、当前状态、2–4 个经过评估的解决方案选项，以及附有理由的建议。时间预算：3–5 周，倡议负责人投入 40–80 小时。分为 A 部分（约第 1–2 周）：了解问题；B 部分（约第 3–5 周）：找到合适的方向。

A 部分：了解问题（约第 1–2 周）

利益相关者访谈

访谈3–5 位受问题影响或了解问题的人。如果倡议涉及许多团队或影响运营系统，应扩大范围；如果问题是明确的技术问题，则应缩小范围。

访谈对象：

• 将要修改其代码库的团队中的技术负责人。
• 多次遇到该问题且对其有深入了解的工程师（即使他们不是技术负责人）。
• 如果问题涉及其领域，访谈 SRE、BRE、DbOps、AppSec 或 QA 负责人。
• 曾尝试过相关方案的任何人——即使尝试失败，尤其是失败的情况。

要询问的问题：

• “请详细说说这个问题在实际工作中是如何影响你们团队的。”
• “目前有哪些变通方案？”
• “之前尝试过哪些方案？为什么没有坚持下去？”
• “如果接下来一个季度我们什么都不做，会有什么变化？”
• “哪些技术、组织或时间方面的约束会影响解决方案？”

要记录的内容：

• 每位受访者的观点，按照他们自己的表述记录（可以转述，但保留他们的用词）。
• 尽可能量化痛点。“每季度约 3 个 bug”“每个 sprint 因此损失约 4 小时”“2026-02-14 的事故追溯到此问题。”模糊的痛点会导致模糊的提案。
• 各项约束，尤其是隐性约束——安全承诺、V+/-2 兼容性、可自托管、多客户端一致性。
• 受访者之间的分歧。这些是有效信号，而非噪声。

当前状态分析

调查代码库中的现有实现。调查范围取决于倡议的内容——错误处理、可观测性、身份验证、数据访问、构建/测试工具。重点关注：

• 不一致之处。 五个团队用五种方式解决同一个问题。两个服务的共享模式版本已经分化。
• 变通方案。 仅因缺少所需模式而存在的代码。引用了从未解决的问题单的注释。
• 技术债务。 因重写成本不值得而保留的旧模式——但现在保留它们的代价已超过重写成本。
• 影响。 尽可能提供数据：该领域的 bug 发生频率、性能指标、与该领域相关的值班告警次数、代码评审此类代码所花的时间。

历史背景

• 阅读有关该主题的过往 PR、设计文档和 Slack 讨论串。在 Confluence 中搜索同一问题领域的既往评估。
• 找出曾推动相关工作的前任倡议负责人、EM 或工程师。简短交流就能省下数周的重复调研时间。
• 找出以往方案未能坚持或成功坚持的原因。这些原因通常能帮助判断这次如何才能成功。

B 部分：找到合适的方向（约第 3–4 周）

方案研究

研究业界模式、可比代码库以及 Bitwarden 自身的先例。此阶段的目标是先拓宽范围，再权衡取舍，而不是深入研究最看好的方案。

• 确定 2–4 个候选方案。少于 2 个意味着你跳过了比较；多于 4 个通常说明你还没有做好分类。
• 明确记录每种方案的取舍：复杂度、迁移成本、性能、安全态势、运维影响、对可自托管部署的影响、V+/-2 兼容性、由谁构建框架、由谁采用。
• 与当前或以往负责相邻计划的 shepherd 合作。分享研究结果有助于及早发现依赖关系和冲突。
• 如果取舍涉及单个团队的代码库，请使用 bitwarden-delivery-tools 中的 Skill(architecting-solutions)；该技能包含团队范围内的架构判断启发方法。

如实说明最有优势的候选方案，但撰写评估时要像 2–4 个候选方案都有可能胜出一样。如果你只认真记录一种方案，领导层和 Architecture Council 就无法真正做出决定，只能对你的方案盖章通过。

架构评估文档

将文档放在 EN 空间的评估文件夹下（漏斗文档会链接到规范位置）。遵循“Architectural Assessments”模板；以下部分是漏斗页面指定的内容。

• 问题陈述（根据研究细化）。 这是你现在能够写出的版本，而在 Identification 阶段还无法写出。
• 当前状态分析。 不一致之处、变通方案、量化影响。引用具体代码或工单证据。
• 考虑过的解决方案（2–4 个）。 对每个方案简要描述关键取舍、粗略工作量估算和风险。不必为每个方案撰写完整提案；关键是进行清晰客观的比较。
• 建议方案。 选定一个。漏斗文档明确指出，这是领导层要决定的内容；含糊其辞会使评估失去意义。
• 理由。 说明为何选择此方案而非其他方案。与访谈中发现的限制条件和当前状态分析中的影响相结合。
• 粗略的高层工作量估算。 如有帮助，可参考以往计划。采用 T 恤尺码估算，或估算 shepherd 和团队分别需要多少周即可。
• 风险和待解决问题。 哪些因素可能推翻建议？哪些问题需要通过 PoC 解答？

漏斗文档中的优秀示例：

问题：“Web 密码库、浏览器扩展和桌面应用之间的状态管理不一致，导致同步错误” **评估的方案：**RxJS observables、Redux Toolkit、Zustand、自定义事件系统 **建议：**采用 Redux Toolkit，并制定清晰的迁移路径 **理由：**TypeScript 支持、开发者工具、团队熟悉度、渐进式采用路径 **下一步：**验证其在浏览器扩展设置模块中是否可行

应避免的薄弱模式（同样来自漏斗文档）：

• “我们应该使用 GraphQL，因为它很现代”——没有问题分析，也没有其他方案。
• “规模更小的服务可以解决我们的扩展性问题”——没有当前状态分析，也没有取舍评估。

分享草案并征求意见

• 将草案分享给你访谈过的人。他们比其他任何人都更能及时发现对其团队实际情况的误述。
• 分享给负责相邻计划的 shepherd。此时最容易发现跨计划冲突。
• 对于重大计划，可在正式的 Phase 3 PoC 评审之前，选择在 Architecture Council 上预览。此阶段 Council 提供的是指导性意见，而非关卡。
• 根据反馈完善文档。初稿和提交给决策者的版本不应是同一份文档。

退出标准

漏斗文档规定了第 2 阶段结束时的关口：

• 交付物： 完成的架构评估文档，包含 2–4 个解决方案选项和建议方案。
• 决策者： 工程领导层，并听取架构委员会的意见。
• 可能的决策： 继续进行 PoC / 继续研究（延长 1–2 周）/ 暂缓（未来某个季度重新评估）/ 拒绝。

向决策者提交评估时，你需要准备：

• 一场 5–10 分钟、可独立呈现的讲解——问题、选项、建议、理由和风险。
• 明确的请求。几乎总是“批准启动 PoC，以验证领域 Y 中的选项 X”。
• 如实说明 PoC 要回答的未决问题。

更新 BW Initiative

研究期间，更新 BW Initiative（规范结构请参阅 Idea-Based Initiatives）：

• Description： 如果对问题的理解发生了实质性变化，请进行调整。保持在摘要层面——架构评估才是详细文档。
• “Relates to” 链接： 这个阶段相关链接的增长最快。应链接所有以往尝试、相邻团队的工作和现有工具。
• Comments： 使用评论记录重要的研究发现、决策节点，以及不适合写入评估文档、但应留在 Initiative 时间线上的利益相关方反馈。
• ARCH idea 状态： 在 JPD 中更新为“2️⃣ Research”。

常见错误

• 撰写评估文档，为预先确定的答案寻找理由。 领导层通常看得出来。评估文档应体现团队的判断，而不是掩盖判断。
• 跳过量化。 与“这造成了困扰”相比，“过去 3 个冲刺中，这导致约 6 个冲刺小时用于调试”更容易推动行动。尽可能获取数据。
• 不提及之前失败的尝试。 如果之前的尝试没有持续下去，那么评估文档若不正视这段历史，提出的建议也不会正视它。
• 把架构委员会当作必须通过的关卡。 委员会提供意见，建议由你负责。带上真正的问题，而不是推销方案。
• 在研究上投入过多。 真正的代码验证要在 PoC 阶段进行。如果研究已超过 5 周，请思考你是否因为怀疑 PoC 会揭示某些问题而在回避它。

参考资料

• Software Initiative Funnel §2 — 阶段说明、进入/退出标准和示例的规范说明。
• Idea-Based Initiatives — 如何在研究期间更新 BW Initiative。
• Technical Strategy Ideas — 上游 TSI 的 Stakeholder & Engagement Map 有助于确定评估中应指出哪些摩擦点。
• 相关内容：总览手册 Skill(shepherding-an-initiative)、介绍研究成果如何用于后续工作的 Skill(running-a-proof-of-concept)，以及 bitwarden-delivery-tools 中的 Skill(architecting-solutions)，用于在选项位于单个团队的职责范围内时，应用团队范围的架构判断启发式。