running-a-proof-of-concept

面向倡议推进者的阶段 3（概念验证）深入实践指南。交付成果：一个或多个 PR，展示在 Bitwarden 实际代码中采用推荐模式的效果；架构委员会评审；以及在集中式 contributing-docs 仓库中编写 ADR 草案（而非分别放在各个仓库中）。时间预算：2–4 周，推进者投入 40–80 小时。概念验证若超过 4 周，通常说明范围不当（过于宏大）或方法不当（推荐方案行不通）。

概念验证的目的

按优先顺序，有三点：

1. 证明该方法在 Bitwarden 的真实代码库中可行——不是在沙盒中，不是在干净的仓库中，也不是纸上谈兵。要在有代表性的代码片段上交付达到生产质量的代码。
2. 暴露评估阶段无法预见的阻力。 每种方法在纸面上看起来都不错。概念验证能让你发现：所选模式需要完善 TypeScript 接口；测试基础设施无法表达新的边界；或者接收团队现有的遥测在新结构下会出问题。
3. 提供具体成果，供接收团队评估。 相比单独的架构文档，概念验证 PR 是更好的交接依据。团队理解代码比理解文字更快。

如果概念验证未能实现这三点，下一阶段就得为此付出代价。

选择概念验证范围

这是本阶段影响最大的决策。漏斗文档建议：选择有代表性但范围受限的内容，最好约 1–5 个文件，或一个能展示关键模式的模块。

选择方法：

• 选择最能检验该方法中可能出问题部分的范围。 如果要解决的是异步错误处理，就选择异步路径不简单的服务。如果要引入新的状态管理库，就选择有真实状态转换的功能。
• 避免选择最简单的情况。 在一个极简单的代码片段上做概念验证，无法证明任何超出评估阶段结论的内容。
• 避免选择最棘手的情况。 在代码库中病态情况最严重的模块上做概念验证，可能会因与该方法无关的原因而失败。你会有所收获，但不是你需要了解的内容。
• 与负责该代码的团队技术负责人协调。 他们对合适范围的建议通常至关重要。他们知道哪些部分有代表性，哪些是陷阱。他们也知道团队是否有余力承接概念验证 PR 的评审。

确定范围后，找到负责团队的联系人（通常是高级工程师，有时是技术负责人），与其结对或请其评审你的工作。他们不是来接手这项工作，而是作为你的合作伙伴，帮助发现哪些地方行不通。

此时也适合查阅 bitwarden-delivery-tools 中的 Skill(architecting-solutions)，了解将影响概念验证的团队范围架构约束（安全思维、多客户端现实、V+/-2 兼容性等）。概念验证从一开始就应满足这些约束，而不是事后补做。

构建概念验证

框架 / 基础

如果该方法需要共享脚手架——中间件、基类、类型定义、共享库等——先构建它。这是后续大范围推广所依赖的可复用部分。框架本身也是概念验证要验证的内容。

两项原则：

• 达到生产质量。 可以缩小范围，但不能牺牲质量。漏斗文档明确指出：“不要偷工减料——这项工作要验证该方法是否真的可行。”偷工减料的概念验证回答的是“如果一切都完美，这能行吗？”而不是你真正需要回答的问题。
• 遵循现有模式。 如果已有成熟模式，新代码却忽略 Bitwarden 的既定规范，就会因无关原因而在评审中失败，无法看出该方法本身是否可行。先阅读，再在现有模式的基础上构建，而不是与之对立。

示例实现

在选定领域中实现 1–3 个示例，展示新模式。每个示例都应足够独立，让评审者能够看出该模式如何发挥作用，同时也应足够贴近实际，以便检验现实场景中的复杂性。漏斗文档中的示例：迁移一个 API 端点、一个 UI 组件或一个服务模块。

对于每个示例，请记录：

• 有效之处。 该模式适用顺畅的场景。
• 遇到的挑战。 边缘情况、集成摩擦、需要调整框架的地方，以及令你意外的情况。
• 全面推广前需要做出的改变。 有时，PoC 会发现框架需要重构才能扩大推广；有时则会发现推广本身需要分阶段进行。

PR

• 如果不打算合并，请在标题中标注“PoC”——漏斗文档允许两种做法，但请明确说明意图。
• 在 PR 描述中写明上述三点（有效之处、遇到的挑战、需要做出的改变）。PR 描述是 PoC 中最常被阅读的材料；团队可能会在 PoC PR 创建数月后才阅读它。
• 链接到架构评估，以便评审者了解该模式为何如此设计。

架构委员会演示

漏斗文档强烈建议在此阶段向架构委员会演示 PoC。形式如下：

• 用 15–30 分钟讲解 PoC 的发现。
• 将演示加入即将召开的委员会议程——与委员会协调人商定时间。
• 准备材料：PoC PR、评估摘要、对有效之处和不足之处的坦诚看法，以及你建议的方向（继续 / 修订 / 返回研究阶段 / 否决）。
• 可选：邀请负责团队的联络人参加。他们对一线情况的了解往往很有分量，是引导者的表述方式所无法替代的。

委员会会提供：模式层面的指导、跨项目的整体认知（该方案是否与其他正在开展的工作冲突？）、对建议方向的验证，以及对推广的关注点。

委员会不会提供：独立于阶段结束时工程领导层是否继续推进的决定之外的放行许可。委员会提出建议；领导层作出决定。

起草 ADR

如果 PoC 验证了该方案，请按照 Bitwarden ADR 模板起草一份架构决策记录。ADR 集中存放在 bitwarden/contributing-docs 仓库的 docs/architecture/adr/ 目录下（可在 contributing.bitwarden.com/architecture/adr/ 查看）。各仓库中都没有单独的 ADR 目录——Bitwarden 有意将架构决策集中存放，以便在决策涉及的所有代码库中都能查阅。

针对 contributing-docs 提交一个 PR，其中包含新的 ADR 文件，编号按顺序接在最新一份已接受的 ADR 之后。可参考示例：0020-observability-with-opentelemetry.md。

ADR 不是架构计划——架构计划将在范围界定阶段制定。ADR 是决策文件。模板要求包含以下部分：

• 背景和问题陈述。 提供一段完整的摘要；不要假设读者已经打开了评估文档。
• 决策（选定的方案）。 具体说明。写明所采用的模式、库或方法。
• 考虑过的替代方案。 取自评估中的 2–4 个选项。简要说明即可——完整的权衡分析在评估文档中。
• 决策理由。 结合 PoC 的发现，而不只是评估结果。
• 影响（正面和负面）。 说明对代码库、团队、运维和安全态势的影响。负面影响也应写在这里——ADR 应实事求是，而非一味宣传。
• 状态：Proposed。 在第 4 阶段领导层作出承诺后，状态将变为 “Accepted”。

ADR 是一份持久的记录，即使推动者离开后也会留存。六个月后，有人遇到相关决策时，会阅读这份 ADR，以了解代码库为何采用当前的设计方式。请为这样的读者撰写。

建立文档模式

ADR 记录的是_决策_。PoC 也是建立_功能性_文档的时机，让 Phase 5 期间将采用新模式的团队能够发现并使用它。根据 Documentation Patterns，Bitwarden 将文档分为两个归属位置，你应有意识地选择文档的归属位置：

• 靠近代码（功能性，是什么）。 与代码一同存放在代码库中。工程师浏览时，GitHub 会自动呈现这些 README.md 文件，这是实际有效的发现途径。使用 Mermaid 绘制图表，以便直接在页面中呈现。
• 集中存放（流程和架构，如何_与_为什么）。 存放在 bitwarden/contributing-docs 代码库中，并呈现在 contributing.bitwarden.com。ADR、设置指南、功能标志操作流程以及跨领域架构参考文档都应放在这里。

PoC 应在各个位置提交以下内容：

• 与框架代码一同存放的 README.md，说明框架是什么、它的接口、如何扩展或应用它，以及有意做出了哪些权衡。引用 ADR 说明决策依据。可参考以下示例：EventIntegrations、DbSeederUtility、EmergencyAccess。
• 示例实现附近的简短文件夹级说明，链接到框架 README 和 ADR。即使文件夹文档内容不多，也能帮助未来的工程师找到正确的背景信息。
• 如上所述，将 ADR 本身存放在 contributing-docs 中。
• 符合技术栈的内联文档。 对 TypeScript/Angular/.NET 使用 XML 注释或 JSDoc；对 Rust 使用 rustdoc 和 crate/module 级别的 README。Documentation Patterns 页面提供了各技术栈的标准。
• 在 PoC 引入新模式时更新 CLAUDE.md。 如果工程师（以及 Claude 工具）今后需要遵循新模式，请将其添加到根目录或文件夹区域的 CLAUDE.md 中——使用 @ 语法链接 README.md，并通过 URL 链接 ADR。bitwarden-init 和 claude-config-validator 插件可帮助完成初始化和审查。

文档的组织方式很重要，因为 Phase 4 接收团队会根据 PoC 做出反馈。PoC PR + 框架 README + ADR，远比单独的 PoC PR 更清晰易懂——这一差异会体现在交接会议更高效，以及实施期间更少出现“等等，这里的预期模式是什么来着？”的情况。

BW Initiative 的更新

在 PoC 期间（参见 Idea-Based Initiatives）：

• 链接 / 描述： 添加指向 PoC PR 的“Relates to”链接（如果它们没有单独的 Jira 工单，则在描述中引用）。
• 评论： 记录 Architecture Council 的反馈、PoC 的发现（哪些有效、哪些无效、与评估相比有哪些变化）以及 ADR 决策。Council 会议本身通常会产生几条值得记录的评论。
• 描述： 如果 PoC 揭示了与评估相比的重大变化，请更新描述以反映当前方向。描述始终代表该计划的当前状态，而非其历史。
• ARCH idea 状态： 更新为“3️⃣ Proof of Concept”。

退出标准

根据流程文档：

• 交付成果： 一个或多个用于展示解决方案的 PR（即使尚未合并）；完成架构委员会评审；起草 ADR（如决定继续推进）；团队联系人支持此方案。
• 决策者： 工程领导层，参考架构委员会的建议。
• 可能的决策： 进入范围界定阶段 / 修改概念验证（转向评估中的替代方案）/ 返回研究阶段 / 拒绝。

进行领导层评审时，请准备：

• 一份 5–10 分钟的概念验证结果摘要。
• 明确的请求——通常是“批准与 X 个团队在 Y 时间范围内进入范围界定阶段”。
• 诚实说明委员会或联系人提出的任何顾虑。

常见错误

• 在概念验证质量上偷工减料。 然后到了后期才疑惑框架为什么无法大规模运行。流程文档说得很明确：必须达到生产质量。
• 选择的概念验证范围太小，缺乏代表性。 “看，这个简单案例能用”经不起下一个团队实际需求的考验。
• 选择了一个未咨询技术负责人的团队作为概念验证范围。 概念验证也是一种合作关系——确保团队愿意接手。
• 把 ADR 当作文书工作。 它是持久的决策记录。值得花一小时来完成。
• 为了节省时间而跳过架构委员会评审。 委员会对跨项目的了解，是发现潜在冲突最省成本的方式，否则这些冲突之后解决起来代价高昂。
• 在概念验证期间悄然偏离评估建议。 如果概念验证表明应采用不同方向，请明确提出——不要在不说明原因的情况下交付与评估结论不一致的概念验证。

参考资料

• 软件项目流程 §3 — 阶段说明的权威资料，以及有效与无效概念验证的示例。
• Bitwarden ADR 模板 — ADR 结构的权威资料，托管于集中管理的 bitwarden/contributing-docs 仓库。
• 文档模式 — 关于贴近代码的文档与集中式文档、特定技术栈的最佳实践，以及 CLAUDE.md 规范的权威指南。
• 基于想法的项目 — 如何在概念验证期间更新 BW 项目。
• 相关内容：Skill(shepherding-an-initiative) 提供总体操作手册，Skill(running-an-architectural-assessment) 介绍概念验证所验证的上游研究阶段工作，Skill(scoping-and-handing-off-to-teams) 说明概念验证的后续用途，Skill(architecting-solutions)（位于 bitwarden-delivery-tools 中）介绍影响概念验证设计的团队范围架构约束。