running-a-proof-of-concept

イニシアチブの推進担当者向け、フェーズ 3（概念実証）の詳細プレイブックです。成果物：Bitwarden の実際のコードで推奨パターンを実証する 1 件以上の PR、Architecture Council によるレビュー、および一元管理された contributing-docs リポジトリのドラフト ADR（リポジトリごとではありません）。所要時間：2～4 週間、推進担当者の作業時間 40～80 時間です。4 週間を超える概念実証は、通常、スコープが誤っている（野心的すぎる）か、アプローチが誤っている（推奨案が機能していない）ことを示します。

概念実証の目的

次の 3 つです。

1. Bitwarden の実際のコードベースでアプローチが機能することを証明する — サンドボックスでも、クリーンなリポジトリでも、仮定の環境でもなく、代表的な範囲を対象に、製品品質のコードで実証します。
2. 評価では予測できなかった摩擦を明らかにする。 どのアプローチも、書面上ではよく見えます。概念実証では、選んだパターンに TypeScript インターフェースの改良が必要だとわかったり、テストインフラストラクチャが新しい境界を表現できないとわかったり、受け入れ側のチームで既存のテレメトリが新しい構造のもとで機能しなくなったりすることを発見します。
3. 受け入れ側のチームが具体的に意見を出せる材料を提供する。 概念実証の PR は、アーキテクチャドキュメントだけよりも、引き継ぎの基盤としてはるかに優れています。チームは文章よりもコードを見たほうが、状況をすばやく把握できます。

概念実証がこの 3 つをすべて達成しなければ、次のフェーズでその代償を払うことになります。

概念実証の対象領域の選定

このフェーズで最も効果の大きい判断です。ファネルのドキュメントでは、代表的でありながら範囲を限定できる対象を選ぶよう推奨しています。理想的には、約 1～5 個のファイル、または主要なパターンを実証できる 1 つのモジュールです。

選び方：

• アプローチが最も失敗しやすい部分を試せる領域を選びます。 アプローチが非同期エラー処理に関するものなら、複雑な非同期処理を含むサービスを選びます。新しい状態管理ライブラリに関するものなら、実際の状態遷移がある機能を選びます。
• 考え得る限り最も単純なケースは避けます。 単純な範囲で概念実証をしても、評価で既に主張したことの裏付けにはなりません。
• 考え得る限り最悪のケースは避けます。 コードベースで最も問題の多いモジュールを対象にすると、アプローチとは無関係な理由で失敗します。何かは学べますが、知る必要があったことはわかりません。
• 担当チームのテックリードと調整します。 適切な範囲についての意見は、通常、決定的な助けになります。どの領域が代表的で、どの領域が厄介な問題を抱えているかを知っているからです。また、概念実証の PR レビューを受け入れる余力がチームにある領域も把握しています。

選定したら、担当チームの窓口となる担当者（通常はシニアエンジニア、場合によってはテックリード）を決め、ペア作業や成果物のレビューを依頼します。この担当者が作業を引き継ぐわけではありません。作業が適合しない点を見つけるためのパートナーです。

この段階で、bitwarden-delivery-tools の Skill(architecting-solutions) を参照し、概念実証に影響するチームスコープのアーキテクチャ上の制約（セキュリティの考え方、複数クライアントの実情、V+/-2 の互換性など）を確認するのもよいでしょう。概念実証は、後から制約を取り入れるのではなく、最初からそれらを踏まえて実施します。

概念実証の構築

フレームワーク／基盤

アプローチで共通の足場（ミドルウェア、基底クラス、型定義、共有ライブラリなど）が必要なら、まずそれを構築します。これは、より広い展開が依存する再利用可能な要素です。フレームワーク自体も、概念実証で検証する対象の一部です。

2 つの原則：

• 製品品質を保ちます。 品質ではなく、スコープを絞ります。ファネルのドキュメントには、「手を抜かないこと。これは、アプローチが実際に機能するかを検証するものです」と明記されています。手を抜いた概念実証で答えられるのは、「すべてが完璧なら機能するだろうか」という問いであり、本当に答える必要がある問いではありません。
• 既存のパターンがあれば、それに合わせます。 Bitwarden で確立された規約を無視する新しいコードは、アプローチ自体の有効性がわかりにくくなる理由でレビューに通らないことがあります。まず読みましょう。既存のものに対抗するのではなく、それと並行して構築します。

実装例

選択した領域で新しいパターンを示す例を1〜3件実装します。各例は、レビュー担当者がパターンの実際の動作を確認できる程度に自己完結している一方、実際の複雑さを検証できるだけの現実味も必要です。ファネルのドキュメントにある例：APIエンドポイント、UIコンポーネント、サービスモジュールをそれぞれ1つ移行します。

各例について、以下を記録します。

• うまくいった点。 パターンが無理なく適合するケースです。
• 発生した課題。 エッジケース、統合時の摩擦、フレームワークの調整が必要だった箇所、予想外だったことです。
• 全面展開に向けて変更が必要な点。 PoCによって、規模を拡大する前にフレームワークのリファクタリングが必要だと判明することもあれば、段階的な展開が必要だと分かることもあります。

PR

• マージを意図していない場合は、タイトルに「PoC」を付けます。ファネルのドキュメントではどちらも認められていますが、意図を明確にしてください。
• PRの説明には、上記の3点（うまくいった点、課題、変更が必要な点）を記載します。PRの説明はPoCの成果物の中で最もよく読まれるものです。チームはPoCのPRが作成されてから数か月後にも目を通します。
• アーキテクチャ評価へのリンクを記載し、レビュー担当者がそのパターンになった背景を把握できるようにします。

アーキテクチャ評議会での説明

ファネルのドキュメントでは、この段階でPoCをアーキテクチャ評議会に提示することを強く推奨しています。形式は以下のとおりです。

• PoCの調査結果を15〜30分で説明します。
• 今後の評議会の議題に追加します。日程については評議会の進行役と調整してください。
• 以下を用意します：PoCのPR、評価の概要、うまくいった点といかなかった点についての率直な見解、提案する方針（進める／修正する／調査に戻す／見送る）。
• 任意：担当チームの窓口担当者にも参加してもらいます。現場の視点は、推進担当者の説明よりも重視されることがよくあります。

評議会が提供するもの：パターンレベルの指針、複数の取り組みを横断した状況把握（このアプローチが進行中の別の取り組みと競合していないか）、提案する方針の妥当性確認、展開に関する懸念の提示です。

評議会が提供しないもの：このフェーズの最後にエンジニアリングリーダーシップが下す実施可否の判断とは独立した承認です。評議会は推奨し、リーダーシップが決定します。

ADR の草案作成

PoC でアプローチの妥当性が確認できたら、Bitwarden ADR テンプレートに従ってアーキテクチャ決定記録を作成します。ADR は中央管理されている bitwarden/contributing-docs リポジトリの docs/architecture/adr/ に保存されます（contributing.bitwarden.com/architecture/adr/ で公開されます）。リポジトリごとの ADR ディレクトリはありません。Bitwarden のアーキテクチャ上の決定は、その決定が関わるすべてのコードベースから参照できるよう、意図的に一元管理されています。

新しい ADR ファイルを追加し、直近の承認済み ADR に続く連番を付けて、contributing-docs に対する PR を作成します。参考例：0020-observability-with-opentelemetry.md。

ADR はアーキテクチャ計画ではありません。それはスコーピングで作成します。ADR は決定を記録するものです。テンプレートに沿ったセクションは次のとおりです。

• コンテキストと問題の説明。 それだけで内容がわかる要約にします。読者が評価資料を開いていることを前提にしないでください。
• 決定（選択した解決策）。 具体的に記述します。パターン、ライブラリ、またはアプローチを明記します。
• 検討した代替案。 評価資料にある 2～4 個の選択肢を記載します。簡潔にまとめてください。詳細なトレードオフは評価資料に記載されています。
• 決定の根拠。 評価資料だけでなく、PoC の結果に結び付けて説明します。
• 結果（肯定的および否定的）。 コードベース、チーム、運用、セキュリティ態勢にどのような変化があるかを記載します。否定的な結果もここに含めます。ADR は宣伝資料ではなく、正直な記録です。
• ステータス：提案済み。 リーダーシップが決定にコミットした後、フェーズ 4 で「承認済み」に変更します。

ADR は、推進担当者が離れた後も残る永続的な記録です。6 か月後、関連する決定に直面した誰かがこの ADR を読み、コードベースが現在の形になっている理由を理解することになります。その読者に向けて書いてください。

ドキュメントのパターンを確立する

ADR には 決定 を記録します。PoC は、新しいパターンを Phase 5 で採用するチームが見つけやすく、使いやすくなるように、必要な 機能面 のドキュメントを整える機会でもあります。Documentation Patterns にあるように、Bitwarden ではドキュメントを 2 つの場所に分けています。意図を持って適切な場所に配置してください。

• コードの近く（機能面、何を）。 リポジトリ内でコードと一緒に管理します。エンジニアが移動する際に、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 およびクレート／モジュールレベルの README を使用します。Documentation Patterns ページに、スタックごとの基準が記載されています。
• PoC で新しいパターンを導入する場合は、CLAUDE.md を更新します。 新しいパターンを今後エンジニア（および Claude のツール）が踏襲する必要がある場合は、ルートまたはフォルダー領域の CLAUDE.md に追加します。@ 構文で README.md に、URL で ADR にリンクしてください。bitwarden-init と claude-config-validator のプラグインは、これらの準備とレビューに役立ちます。

ドキュメントの構成は重要です。Phase 4 で引き継ぎ先のチームが検討するのは PoC だからです。PoC の PR だけの場合よりも、PoC の PR とフレームワークの README、ADR をそろえたほうが、はるかに内容を把握しやすくなります。その違いは、引き継ぎ会議の短縮や、実装時に「ここで意図されていたパターンは何だったのか」と悩む場面の減少につながります。

BW イニシアチブの更新

PoC の実施中は、Idea-Based Initiatives を参照し、次のとおり対応します。

• リンク／説明： PoC の PR への「Relates to」リンクを追加します（別の Jira チケットがない場合は、説明内で参照します）。
• コメント： Architecture Council からのフィードバック、PoC で得られた知見（うまくいったこと、うまくいかなかったこと、評価から変更した点）、ADR の決定を記録します。通常、Council のセッションではコメントに値する内容がいくつも生まれます。
• 説明： PoC によって評価から大きな変更が判明した場合は、現在の方針を反映するように説明を更新します。説明には履歴ではなく、常にイニシアチブの現在の状態を記載します。
• ARCH アイデアのステータス： 「3️⃣ Proof of Concept」に更新します。

終了基準

ファネル文書に従います。

• 成果物： ソリューションを示す1件以上のPR（マージされていなくても可）、Architecture Councilのレビュー完了、ADRの作成（続行する場合）、チームの窓口担当者がアプローチを支持していること。
• 意思決定者： Architecture Councilの推奨を受けたエンジニアリング部門のリーダーシップ。
• 決定の選択肢： スコーピングに進む／PoCを見直す（評価で挙がった代替案に方向転換する）／リサーチに戻る／却下する。

リーダーシップによるレビューには、以下を用意します。

• PoCの結果をまとめた5～10分の説明。
• 明確な依頼事項。通常は「XチームとYの期間でスコーピングに進むことの承認」です。
• Councilまたは窓口担当者から挙がった懸念を率直に認めること。

よくある間違い

• PoCの品質を妥協する。 その後、フレームワークが大規模運用で機能しない理由を考えることになります。ファネル文書では、本番品質であることが明確に求められています。
• 代表性のないほど小さな領域をPoCに選ぶ。 「ほら、この単純なケースでは動きます」では、次のチームの実情に直面したときに通用しません。
• テックリードに相談していないチーム内の領域をPoCに選ぶ。 PoCは人間関係を築く機会でもあります。チームが受け入れる意向があることを確認してください。
• ADRを事務手続きとして扱う。 ADRは長期にわたって参照できる意思決定の記録です。作成に1時間かける価値があります。
• 時間を節約するためにArchitecture Councilを省略する。 Councilが複数のイニシアチブを横断して把握していることは、後で解決に費用がかかる競合を見つける最も低コストな方法です。
• PoC中に、評価での推奨事項からひそかに離れる。 PoCで異なる方向性が示された場合は、明確に提示してください。理由を明らかにせず、評価と食い違うPoCを提出してはいけません。

参考資料

• Software Initiative Funnel §3 — フェーズの正式な説明と、効果的なPoCと効果的でないPoCの例。
• Bitwarden ADR template — ADRの正式な構成。中央管理されている bitwarden/contributing-docs リポジトリから提供されています。
• Documentation Patterns — コードに近いドキュメントと一元管理するドキュメントに関する正式な指針、技術スタック固有のベストプラクティス、CLAUDE.mdの規約。
• Idea-Based Initiatives — PoC中にBW Initiativeを更新する方法。
• 関連項目：全体的なプレイブックは Skill(shepherding-an-initiative)、PoCで検証する上流のResearchフェーズの作業は Skill(running-an-architectural-assessment)、PoCの成果を引き継ぐ先については Skill(scoping-and-handing-off-to-teams)、PoCの設計を形作るチームスコープのアーキテクチャ上の制約については bitwarden-delivery-tools の Skill(architecting-solutions) を参照してください。