running-an-architectural-assessment

イニシアチブの推進担当者向け、フェーズ 2（調査）の詳細な進行ガイドです。成果物はアーキテクチャ評価です。問題の明確化された記述、現状、評価した 2～4 個の解決策、根拠を添えた推奨案をまとめた Confluence ページを、EN-space の assessments フォルダーに作成します。所要期間は 3～5 週間、推進担当者の作業時間は 40～80 時間です。前半の A（1～2 週目）は問題の理解、後半の B（3～5 週目）は適切な方向性の検討に充てます。

Part A：問題の理解（1～2 週目）

ステークホルダーへのインタビュー

問題の影響を受けている人、または問題に詳しい人に3～5 人インタビューします。複数のチームにまたがる、または運用システムに影響するイニシアチブでは対象を広げ、明確な技術的課題の場合は対象を絞ります。

話を聞く相手：

• コードベースを変更するチームのテックリード。
• 問題に何度も直面し、実践的な理解を持つエンジニア（テックリードでなくても構いません）。
• 問題が担当領域に関わる場合は、SRE、BRE、DbOps、AppSec、QA のリード。
• 関連するアプローチを以前試した人。たとえ失敗していたとしてもです。特に失敗した場合は、必ず話を聞きます。

質問する内容：

• 「この問題が、実際にチームでどのように現れるのか、順を追って教えてください」
• 「現在、どのような回避策がありますか？」
• 「これまでにどのような試みがあり、なぜ定着しなかったのでしょうか？」
• 「このままあと四半期何もしなかった場合、何が変わりますか？」
• 「技術面、組織面、時期など、解決策を形作る制約は何ですか？」

記録する内容：

• 各インタビュー対象者の見解を、その人自身の言い回しで記録します（言い換えても構いませんが、使われた表現は保ちます）。
• 可能な限り、問題の影響を数値化します。「四半期あたり約 3 件のバグ」「スプリントごとに約 4 時間をこの問題で失う」「2026-02-14 のインシデントはこれが原因と判明」などです。影響が曖昧だと、提案も曖昧になります。
• 制約、特に暗黙の制約を記録します。セキュリティ上のコミットメント、V+/-2 互換性、セルフホスト可能であること、複数クライアント間の同等性などです。
• インタビュー対象者間の意見の相違も記録します。これはノイズではなく、重要な兆候です。

現状分析

コードベース全体の既存実装を調査します。調査対象はイニシアチブによって異なります。エラー処理、オブザーバビリティ、認証、データアクセス、ビルド／テストツールなどです。次の点を確認します。

• 不整合。 同じ問題を 5 つのチームがそれぞれ異なる方法で解決している。共通パターンのバージョンが 2 つのサービスで乖離している。
• 回避策。 望ましいパターンがないためだけに存在するコード。解決されないままのチケットに言及するコメント。
• 技術的負債。 書き直す価値がないと判断され、古いパターンが残されている状態。ただし、今では残し続けるコストの方が書き直すコストを上回っている場合があります。
• 影響。 可能であれば、対象領域のバグ発生頻度、パフォーマンス指標、その領域に関係するオンコール通知の件数、この種のコードのコードレビューにかかる時間など、数値を添えます。

過去の経緯

• このテーマに関する過去の PR、設計ドキュメント、Slack スレッドを読みます。同じ問題領域の過去の評価がないか、Confluence で検索します。
• 関連する作業を推進した以前の担当者、EM、エンジニアを探します。短い会話でも、何週間もの再調査を省けます。
• 過去のアプローチが定着した、または定着しなかった理由を特定します。その理由から、今回成功するための手がかりが得られることがよくあります。

Part B：適切な方向性の検討（3～4 週目）

ソリューションの調査

業界や類似するコードベース、Bitwarden 独自の先行事例からパターンを調査します。この段階の目標は、まず幅広く検討し、その後トレードオフを評価することです。第一候補を深掘りすることではありません。

• 候補となるアプローチを2～4個特定します。2個未満では比較を省略したことになり、4個を超える場合は分類が不十分なことがほとんどです。
• 各アプローチについて、複雑さ、移行コスト、パフォーマンス、セキュリティ態勢、運用上の影響、セルフホストへの影響、V+/-2 の互換性、フレームワークの構築担当者、採用する担当者などのトレードオフを明示します。
• 関連する取り組みを担当する現任または過去のシェパードと連携します。調査結果を共有することで、依存関係や競合を早期に発見できます。
• トレードオフが1つのチームのコードベース内にある場合は、bitwarden-delivery-tools の Skill(architecting-solutions) を活用します。このスキルには、チームのスコープにおけるアーキテクチャ判断のヒューリスティックが含まれています。

有力な候補について率直に評価しつつ、2～4個のどの候補も選ばれる可能性があるものとして評価を書きます。1つのアプローチだけを真剣に記述していては、リーダーシップチームと Architecture Council は実際に判断できず、あなたの案を追認するだけになります。

アーキテクチャ評価ドキュメント

EN スペースの評価フォルダーに配置します（ファネルドキュメントに正規の場所が記載されています）。「Architectural Assessments」テンプレートに従います。以下のセクションは、ファネルページで指定されているものです。

• 問題の説明（調査を踏まえて精緻化）。 Identification の段階では書けなかった、現時点で書ける内容です。
• 現状分析。 不整合、回避策、定量化した影響を記述します。具体的なコードやチケットの証拠を参照します。
• 検討したソリューションの選択肢（2～4個）。 それぞれについて、簡単な説明、主なトレードオフ、大まかな作業量の見積もり、リスクを記載します。それぞれの詳細な提案書を書く必要はありません。明確で偏りのない比較が必要です。
• 推奨するアプローチ。 1つ選びます。ファネルドキュメントでは、これをリーダーシップチームが決定すると明記されています。曖昧なままでは評価の目的が損なわれます。
• 根拠。 他の選択肢ではなく、この選択肢を選ぶ理由を説明します。インタビューで明らかになった制約と、現状分析で示された影響に結び付けます。
• 大まかな高レベルの作業量見積もり。 参考になる場合は過去の取り組みに言及します。Tシャツサイズ、またはシェパードの週数とチームの週数で十分です。
• リスクと未解決の質問。 推奨を覆す可能性があるものを示します。PoC で検証する必要がある内容を記載します。

ファネルドキュメントにある優れた例：

問題：「Web vault、ブラウザー拡張機能、デスクトップアプリで状態管理に一貫性がなく、同期の不具合が発生している」 評価したソリューション： RxJS observables、Redux Toolkit、Zustand、カスタムイベントシステム 推奨： 明確な移行パスを備えた Redux Toolkit 根拠： TypeScript のサポート、開発ツール、チームの習熟度、段階的な導入パス 次のステップ： ブラウザー拡張機能の設定モジュールで動作を実証する

避けるべき弱いパターン（こちらもファネルドキュメントから）：

• 「GraphQL は最新だから採用すべき」— 問題分析も代替案もありません。
• 「サービスを小さくすればスケーリングの問題を解決できる」— 現状分析もトレードオフの評価もありません。

ドラフトの共有

• インタビューした人たちにドラフトを共有します。彼らは、他の誰よりも早く自分たちのチームの実情が正確に反映されているかを確認できます。
• 関連する取り組みを担当するシェパードにも共有します。取り組み間の競合を見つけるには、この段階が最も効率的です。
• 大規模な取り組みでは、正式な Phase 3 PoC レビューの前に、Architecture Council で任意のプレビューを行います。この段階での Council からの意見は方向性を示す助言であり、承認の関門ではありません。
• 意見をもとに内容を改善します。最初のドラフトと意思決定者に提出する版は、同じ文書であってはなりません。

終了基準

ファネルのドキュメントでは、フェーズ 2 の終了時に設けるゲートを次のように定めています。

• 成果物： 2〜4 個のソリューション案と推奨アプローチを含む、完成したアーキテクチャ評価ドキュメント。
• 意思決定者： アーキテクチャ評議会の意見を取り入れたエンジニアリングリーダーシップ。
• 想定される判断： PoC に進む／調査を継続する（1〜2 週間延長）／保留する（次の四半期に再検討）／却下する。

評価結果を意思決定者に提示する際は、次のものが必要です。

• 単独で内容が伝わる 5〜10 分の説明（課題、選択肢、推奨案、根拠、リスク）。
• 明確な依頼。ほとんどの場合、「領域 Y で選択肢 X を検証する PoC の開始承認」です。
• PoC で答えを出す予定の未解決事項を、正直に認めること。

BW Initiative の更新

調査中は、BW Initiative を更新してください（標準的な構成についてはアイデアベースのイニシアチブを参照してください）。

• Description： 課題に対する理解が大きく変わった場合は、内容を見直します。概要レベルにとどめ、詳細な成果物はアーキテクチャ評価にまとめます。
• 「Relates to」リンク： リンク一覧が最も急速に増えるのはこの段階です。過去の取り組み、関連チームの作業、既存のツールなど、すべてリンクしてください。
• コメント： 評価に含める必要はないものの、イニシアチブの履歴に記録しておくべき重要な調査結果、判断の節目、ステークホルダーからのフィードバックをコメントに記録します。
• ARCH アイデアのステータス： JPD で「2️⃣ Research」に更新します。

よくある間違い

• あらかじめ決めた結論を正当化するために評価を書く。 リーダーシップにはたいてい見抜かれます。評価はチームの判断を表す場であり、それを隠す場ではありません。
• 定量化を省く。 「問題が起きている」よりも、「過去 3 回のスプリントで、デバッグに約 6 スプリント時間を費やした」のほうが対処しやすくなります。可能な限り数値を集めてください。
• 過去に失敗したことを明記しない。 過去の取り組みが定着しなかった場合、その経緯を踏まえない評価からは、その経緯を踏まえない推奨案が生まれます。
• アーキテクチャ評議会を通過すべきゲートとして扱う。 評議会は意見を提供する場です。推奨案にはあなたが責任を持ちます。売り込みではなく、実際に答えを求めている質問を持ち込みましょう。
• 調査に過剰に投資する。 アプローチを実際のコードで検証するのは PoC です。調査が 5 週間を超えている場合、PoC で何かが明らかになると予想しているために、開始を避けていないか検討してください。

参考資料

• ソフトウェアイニシアチブファネル §2 — フェーズの標準的な説明、開始基準と終了基準、例。
• アイデアベースのイニシアチブ — 調査中に BW Initiative を更新する方法。
• 技術戦略アイデア — 上流の TSI にあるステークホルダーとエンゲージメントのマップを参考に、評価で取り上げる摩擦点を判断します。
• 関連項目：全体的なプレイブックについては Skill(shepherding-an-initiative)、調査の成果を引き継ぐ先については Skill(running-a-proof-of-concept)、選択肢が 1 つのチームの領域内にある場合に適用するチームスコープのアーキテクチャ判断のヒューリスティクスについては bitwarden-delivery-tools 内の Skill(architecting-solutions)。