running-a-proof-of-concept

Phase 3 (Proof of Concept) guide détaillé pour un initiative shepherd. Livrables : une ou plusieurs PR démontrant le pattern recommandé dans le vrai code Bitwarden, examen du Architecture Council, et un brouillon d'ADR dans le repository centralisé contributing-docs (pas par repository). Budget temporel : 2–4 semaines, 40–80 heures de temps du shepherd. Les PoC qui s'éternisent au-delà de 4 semaines signalent généralement soit une portée inadaptée (trop ambitieuse), soit une approche inadaptée (la recommandation ne fonctionne pas).

À quoi sert le PoC

Trois choses, dans l'ordre :

1. Prouver que l'approche fonctionne dans le vrai codebase Bitwarden — pas dans un bac à sable, pas sur un repository vierge, pas en théorie. Code de qualité production sur une tranche représentative.
2. Mettre au jour les frictions que l'évaluation n'a pas pu prévoir. Toute approche semble bonne sur le papier. Le PoC est où vous découvrez que le pattern choisi nécessite un raffinement d'interface TypeScript, ou que l'infrastructure de test ne peut pas représenter la nouvelle limite, ou que la télémétrie existante de l'équipe réceptrice casse avec la nouvelle structure.
3. Donner aux équipes réceptrices quelque chose de concret pour réagir. Une PR PoC est une bien meilleure base de transmission qu'un document d'architecture seul. Les équipes s'orientent plus vite sur du code que sur du texte.

Si le PoC ne satisfait pas aux trois critères, la phase suivante en paiera le prix.

Sélection de la zone PoC

C'est la décision à plus haut levier dans la phase. Le guide du funnel : représentatif mais contenu, idéalement ~1–5 fichiers ou un module démontrant les patterns clés.

Comment choisir :

• Choisir une zone qui exerce les parties de l'approche les plus susceptibles d'échouer. Si l'approche concerne la gestion d'erreurs asynchrone, choisir un service avec des chemins asynchrones non triviaux. Si c'est une nouvelle librairie de gestion d'état, choisir une fonctionnalité avec des transitions d'état réelles.
• Éviter le cas le plus simple possible. Un PoC sur une tranche triviale ne prouve rien que l'évaluation n'aurait déjà affirmé.
• Éviter le pire cas possible. Un PoC sur le module le plus pathologique du codebase échouera pour des raisons sans rapport avec l'approche. Vous apprendrez quelque chose, mais pas ce que vous aviez besoin d'apprendre.
• Coordonner avec le tech lead de l'équipe propriétaire. Ses remarques sur la bonne tranche sont généralement décisives. Il sait quelle zone est illustrative et laquelle est un piège. Il sait aussi quelle zone son équipe a la capacité d'accueillir pour l'examen de la PR PoC.

Une fois sélectionnée, identifier un point de contact dans l'équipe propriétaire (généralement un senior engineer, parfois le tech lead) qui pourra vous accompagner ou examiner votre travail. Ils n'adoptent pas le travail — ils sont votre partenaire pour révéler où ça ne s'ajuste pas.

C'est aussi le bon moment de consulter Skill(architecting-solutions) dans bitwarden-tech-lead pour les contraintes architecturales au scope de l'équipe qui façonneront votre PoC (security mindset, réalité multi-client, compatibilité V+/-2, etc.). Le PoC s'expédie face à ces contraintes dès le départ, pas en retrofit.

Construction du PoC

Framework / Fondation

Si l'approche nécessite un scaffolding partagé — middleware, classes de base, définitions de types, librairies partagées — le construire d'abord. C'est la pièce réutilisable sur laquelle dépend le déploiement plus large. Le framework lui-même fait partie de ce que le PoC valide.

Deux principes :

• Qualité production. Couper les coins sur la portée, pas sur la qualité. Le guide du funnel est explicite : « ne couper pas les coins — cela teste si l'approche fonctionne réellement. » Les PoC qui coupent les coins répondent à la question « cela pourrait-il marcher si tout était parfait ? » — pas celle que vous devez vraiment poser.
• Correspondre aux patterns existants où ils existent. Du nouveau code qui ignore les conventions établies de Bitwarden échouera la review pour des raisons qui obscurcissent si l'approche elle-même a fonctionné. Lire d'abord. Construire aux côtés, pas en opposition, de ce qui existe déjà.

Exemple(s) d'implémentation

Implémenter 1–3 exemples démontrant le nouveau pattern dans la zone choisie. Chaque exemple doit être suffisamment autonome pour qu'un reviewer voie le pattern en action, mais assez réaliste pour tester la complexité du monde réel. Exemples du guide du funnel : migrer un endpoint API, un composant UI, ou un module de service.

Pour chaque exemple, capturer :

• Ce qui a fonctionné. Les cas où le pattern s'ajuste proprement.
• Quels défis ont émergé. Cas limites, frictions d'intégration, endroits où le framework a dû être ajusté, choses qui vous ont surpris.
• Ce qui devrait changer pour un déploiement complet. Parfois le PoC révèle que le framework doit être refactorisé avant l'expansion ; parfois il révèle que le déploiement lui-même doit être phasé.

La ou les PR

• Marquer « PoC » dans le titre si non destinée à la fusion — le guide du funnel accepte l'une ou l'autre, mais soyez explicite sur l'intention.
• Dans la description de la PR, écrire les trois points ci-dessus (ce qui a marché, quels défis, ce qui changerait). La description de la PR est l'artefact le plus lu du PoC ; les équipes la reliront des mois après que la PR PoC a été ouverte.
• Lier à l'Évaluation Architecturale pour que les reviewers comprennent pourquoi le pattern se présente ainsi.

Architecture Council Walkthrough

Le guide du funnel recommande fortement de présenter le PoC au Architecture Council à cette phase. Format :

• Walkthrough de 15–30 minutes des conclusions du PoC.
• Ajouter à un prochain ordre du jour du Council — coordonner le timing avec le facilitateur du Council.
• Apporter : la ou les PR du PoC, le résumé de l'évaluation, votre lecture honnête de ce qui a fonctionné et ce qui ne l'a pas, votre direction proposée (avancer / réviser / retourner à Recherche / décliner).
• Optionnel : faire assister le point de contact de l'équipe propriétaire. Leur perspective sur le terrain porte souvent plus de poids que le framing du shepherd.

Ce que le Council fournit : guidance au niveau du pattern, conscience inter-initiatives (cette approche est-elle en conflit avec quelque chose d'autre en cours ?), validation de la direction proposée, et identification des préoccupations concernant le déploiement.

Ce que le Council ne fournit pas : un feu vert indépendant du go/no-go du leadership d'ingénierie à la fin de la phase. Le Council recommande ; le leadership décide.

Rédaction de l'ADR

Si le PoC valide l'approche, rédiger un Architecture Decision Record suivant le template ADR Bitwarden. Les ADR vivent dans le repository centralisé bitwarden/contributing-docs sous docs/architecture/adr/ (rendu à contributing.bitwarden.com/architecture/adr/). Il n'y a pas de répertoire ADR par repository — les décisions architecturales de Bitwarden sont intentionnellement centralisées pour être découvrables dans tous les codebases que la décision touche.

Ouvrir une PR contre contributing-docs avec le nouveau fichier ADR, numéroté séquentiellement après l'ADR accepté le plus récent. Exemple de référence : 0020-observability-with-opentelemetry.md.

L'ADR n'est pas le plan architecturale — cela vient dans Scoping. L'ADR est l'artefact de décision. Sections par le template :

• Context and problem statement. Un résumé autonome ; ne pas supposer que le lecteur a l'évaluation ouverte.
• Decision (chosen solution). Spécifique. Nommer le pattern, la librairie, ou l'approche.
• Alternatives considered. Des 2–4 options de l'évaluation. Bref — les trade-offs complets sont dans l'évaluation.
• Rationale for decision. Lier aux conclusions du PoC, pas juste à l'évaluation.
• Consequences (positive and negative). Ce qui change pour le codebase, les équipes, les opérations, la posture de sécurité. Les conséquences négatives y appartiennent — l'ADR est honnête, pas promotionnel.
• Status: Proposed. Il passe à « Accepted » durant Phase 4 une fois que le leadership s'est engagé.

L'ADR est l'artefact durable qui survit au départ du shepherd. Six mois à partir de maintenant, quelqu'un frappera une décision connexe et lira cet ADR pour comprendre pourquoi le codebase est façonné de la manière qu'il est. Écrire pour ce lecteur.

Établissement des patterns de documentation

L'ADR capture la décision. Le PoC est aussi le moment d'établir la documentation fonctionnelle que le nouveau pattern a besoin d'être découvrable et utilisable par les équipes qui l'adopteront durant Phase 5. Per Documentation Patterns, Bitwarden divise la documentation en deux emplacements que vous devriez délibérément viser :

• Proche du code (fonctionnel, quoi). Vit aux côtés du code dans le repository. GitHub rend ces fichiers README.md automatiquement quand les engineers naviguent, ce qui est le chemin de découverte qui fonctionne vraiment. Utiliser Mermaid pour les diagrammes afin qu'ils se rendent sur place.
• Centralisé (logistique et architectural, comment et pourquoi). Vit dans le repository bitwarden/contributing-docs, rendu à contributing.bitwarden.com. Les ADR, guides de configuration, procédures opératoires de feature-flag, et références architecturales transversales y vont.

Ce que le PoC devrait livrer dans chaque emplacement :

• Aux côtés du code du framework, un README.md expliquant ce qu'est le framework, son interface, comment l'étendre ou l'appliquer, et quels trade-offs ont été délibérément faits. Référencer l'ADR pour la logique de décision. Exemples à modeler : EventIntegrations, DbSeederUtility, EmergencyAccess.
• Près de la ou les implémentations d'exemple, de courtes notes au niveau du dossier qui renvoient au README du framework et à l'ADR. Même une mince documentation de dossier aide les futurs engineers à trouver leur chemin vers le contexte canonique.
• L'ADR lui-même dans contributing-docs comme couvré ci-dessus.
• Documentation inline appropriée à la tech-stack. Commentaires XML ou JSDoc pour TypeScript/Angular/.NET ; rustdoc et README au niveau crate/module pour Rust. La page Documentation Patterns a le rubrique par stack.
• Mises à jour CLAUDE.md où le PoC introduit un nouveau pattern. Si le nouveau pattern est quelque chose que les engineers (et les outils Claude) doivent suivre à l'avenir, l'ajouter au root ou folder-area CLAUDE.md — lier le README.md via la syntaxe @ et l'ADR par URL. Les plugins bitwarden-init et claude-config-validator aident à bootstrapper et examiner ceux-ci.

La forme de la documentation importe parce que le PoC est ce sur quoi les équipes réceptrices en Phase 4 vont réagir. Une PR PoC + un framework README + un ADR est beaucoup plus lisible qu'une PR PoC seule — et la différence se montre par des réunions de transmission plus rapides et moins de « attends, quel était le pattern prévu ici ? » durant Implémentation.

Mises à jour de l'initiative BW

Pendant PoC (voir Idea-Based Initiatives) :

• Liens / description : Ajouter des liens « Relates to » aux PR PoC (ou les référencer dans la description s'ils n'ont pas de tickets Jira séparés).
• Commentaires : Enregistrer le retour du Architecture Council, les conclusions du PoC (ce qui a marché, ce qui ne l'a pas, ce qui a changé par rapport à l'évaluation), et la décision d'ADR. La session du Council elle-même génère généralement plusieurs moments qui méritent un commentaire.
• Description : Si le PoC a révélé un changement significatif par rapport à l'évaluation, mettre à jour la description pour refléter la direction actuelle. La description représente toujours l'état actuel de l'initiative, pas son historique.
• Statut d'idée ARCH : Mettre à jour vers « 3️⃣ Proof of Concept ».

Critères de sortie

Par le guide du funnel :

• Livrables : Une ou plusieurs PR démontrant la solution (même si non fusionnées) ; examen du Architecture Council complété ; ADR rédigé (si avançant) ; le point de contact de l'équipe supportif de l'approche.
• Décideur : Leadership d'ingénierie avec recommandation du Architecture Council.
• Décisions possibles : Avancer vers Scoping / Réviser PoC (pivoter vers une alternative de l'évaluation) / Retourner à Recherche / Décliner.

Pour l'examen du leadership, apporter :

• Un résumé de 5–10 minutes du résultat du PoC.
• La demande claire — généralement « approbation pour avancer vers Scoping avec X équipes sur Y timeframe ».
• Reconnaissance honnête de toute préoccupation soulevée par le Council ou le point de contact.

Erreurs courantes

• Couper les coins sur la qualité du PoC. Puis plus tard se demander pourquoi le framework casse à l'échelle. Le guide du funnel est sans ambiguïté : qualité production.
• Choisir une zone PoC trop petite pour être représentative. « Regarde, ça marche sur ce seul cas trivial » ne survit pas au contact avec la réalité de l'équipe suivante.
• Choisir une zone PoC à l'intérieur d'une équipe dont le tech lead n'a pas été consulté. Le PoC est aussi une relation — s'assurer que l'équipe est disposée à l'accueillir.
• Traiter l'ADR comme de la paperasse. C'est l'artefact de décision durable. Ça vaut l'heure.
• Sauter le Architecture Council pour gagner du temps. La conscience inter-initiatives du Council est le moyen le moins cher de détecter les conflits qui seraient coûteux à résoudre plus tard.
• S'éloigner tranquillement de la recommandation d'évaluation durant PoC. Si le PoC suggère une direction différente, la surfacer explicitement — ne pas livrer un PoC qui ne correspond pas à l'évaluation sans nommer pourquoi.

Référence

• Software Initiative Funnel §3 — description de phase canonique, exemples de PoC efficaces vs. inefficaces.
• Template ADR Bitwarden — structure ADR canonique, servie depuis le repository centralisé bitwarden/contributing-docs.
• Documentation Patterns — guidance canonique sur documentation proche du code vs. centralisée, meilleures pratiques tech-stack-spécifiques, et conventions CLAUDE.md.
• Idea-Based Initiatives — comment mettre à jour l'initiative BW durant PoC.
• Connexe : Skill(shepherding-an-initiative) pour le playbook parapluie, Skill(running-an-architectural-assessment) pour le travail phase Recherche en amont que le PoC valide, Skill(scoping-and-handing-off-to-teams) pour ce que le PoC alimente, Skill(architecting-solutions) (dans bitwarden-tech-lead) pour les contraintes architecturales au scope de l'équipe qui façonnent la conception PoC.