writing-tech-breakdowns

Le modèle de décomposition technique de Bitwarden est l'artefact standard qu'une équipe produit avant de commencer l'implémentation d'une modification non triviale. Il capture la conception technique — ce qui est construit, ce qu'il affecte, quelles alternatives ont été considérées, quel est l'impact inter-équipes — au niveau de précision qu'un autre ingénieur ou une autre équipe peut exploiter. Cette compétence est le manuel de travail pour rédiger le contenu technique (parties 1, 2, 4, 5, 6) et gérer le cycle de vie du statut du document. La partie 3 (approbations inter-équipes) et la liste de contrôle de communication finale vivent dans la compétence associée Skill(coordinating-cross-team-breakdown).

Quand la structure canonique du modèle est nécessaire, récupérez la page 2920349776 via get_confluence_page ; ce document est le résumé opérationnel, pas la source de vérité.

Qui rédige une décomposition technique

Le responsable technique possède traditionnellement la décomposition pour le travail de l'équipe, mais les ingénieurs logiciels contribuent largement ou rédigent entièrement des sections. Deux modèles de propriété courants :

• Dirigé par un ingénieur : un ingénieur prend un élément de périmètre et rédige la décomposition de bout en bout, le responsable technique la relisant avant qu'elle passe à PROPOSED.
• Dirigé par le responsable technique : le responsable technique cadre le problème, remplit les parties 1 et 2 avec l'équipe, et divise les artefacts de spécification de la partie 4 entre les ingénieurs.

Cette compétence est écrite pour celui qui tape. Les activités sont les mêmes ; le chemin de révision diffère.

Avant de commencer : orienter sur l'initiative

Si la modification existe sous une plus grande initiative Bitwarden — une épopée que l'équipe a reçue d'un berger via le Software Initiative Funnel — exécutez d'abord Skill(navigating-the-initiative-funnel). Cela fait remonter le contexte qui alimente plusieurs parties de la décomposition :

• L'épopée d'initiative d'origine, son plan d'architecture et les PoC PRs que le berger a produits — ce sont les sources pour les parties 1, 2 et 4.
• Les critères de succès et contraintes énoncés par le berger — les questions de la partie 2 obtiennent des réponses par rapport à ceux-ci, pas contre des suppositions.
• Les épopées des équipes sœurs sous la même initiative — elles remplissent le lien "Related breakdowns" dans la partie 1 et alimentent le tableau d'approbation de la partie 3 (géré dans Skill(coordinating-cross-team-breakdown)).
• Le berger lui-même — escaladez les questions de périmètre ambigus ou d'interfaces inter-équipes vers lui plutôt que de les résoudre unilatéralement.

Si aucune initiative n'existe — le travail est purement limité à l'équipe — ignorez cette étape et notez-le explicitement dans la partie 1 (« pas partie d'une initiative active »). Une décomposition sans initiative va bien ; une décomposition rédigée dans le vide alors qu'une initiative existe ne va pas.

Démarrer une nouvelle décomposition

Le modèle vit dans le dossier « Tech Breakdown » de l'équipe dans Confluence. Étapes de configuration du préambule du modèle :

1. Copiez le modèle dans le dossier de l'équipe. N'éditez pas la page du modèle directement.
2. Changez les permissions en lecture seule via l'icône de verrouillage en haut à droite. Les décompositions techniques sont des artefacts de référence après qu'elles soient ACCEPTED — elles ne doivent pas être silencieusement ré-éditées.
3. Supprimez la liste de contrôle du modèle en haut une fois la copie effectuée.
4. Remplissez le bloc d'en-tête : Propriétaire (l'humain responsable, pas une équipe), Date limite (quand la décomposition elle-même est censée être terminée — pas quand l'implémentation sort), Statut (commencez à IN PLANNING).

Le bloc d'en-tête est une métadonnée sur laquelle les lecteurs en aval — QA, responsables du raffinement, autres équipes — comptent. Ne le laissez pas vide.

Le cycle de vie du statut

Le modèle définit six états. Passez par eux délibérément — le statut indique comment les consommateurs inter-équipes savent s'ils doivent s'engager :

• IN PLANNING — attendu, mais pas activement travaillé. Utilisez quand la décomposition est engagée mais que l'équipe n'a pas commencé à la rédiger. Ne restez pas longtemps ici ; c'est le signal le plus faible d'intention.
• IN PROGRESS — activement rédigé. Les parties 1, 2 et les pages enfants de la partie 4 sont remplies. La révision inter-équipes n'est pas encore appropriée.
• PROPOSED — prêt pour révision. Les parties 1, 2, 4, 5 sont complètes ; le tableau d'approbation de la partie 3 identifie qui doit réviser. C'est la porte vers Skill(coordinating-cross-team-breakdown) — une fois que le doc atteint PROPOSED, le travail passe de la rédaction à la coordination.
• ACCEPTED — toutes les équipes affectées ont signé via la partie 3. La décomposition est maintenant la conception technique convenue. L'équipe peut commencer l'implémentation. L'implémentation ne doit pas commencer avant cet état quand des interfaces inter-équipes sont impliquées.
• COMPLETE — l'implémentation a été déployée et la liste de contrôle de communication finale (gérée dans Skill(coordinating-cross-team-breakdown)) s'est exécutée.
• REJECTED — la révision a surfacé des incompatibilités ou des blocages qui ne peuvent pas être résolus. La décomposition est préservée comme document historique ; une nouvelle décomposition la remplace.

Deux règles de transition d'état à garder à l'esprit :

• N'ignorez pas PROPOSED. Passer directement de IN PROGRESS à ACCEPTED masque le travail de révision inter-équipes et produit des approbations qui ressemblent à des tampons automatiques.
• Ne rouvrez pas ACCEPTED pour des changements matériels. Si la conception doit changer après que les équipes aient signé, soit remplacez par une nouvelle décomposition, soit renvoyez le changement à PROPOSED et ré-exécutez les approbations pertinentes. Les édits silencieux après ACCEPTED défont l'intérêt de l'artefact.

Si le cycle de vie sur la page canonique diffère de ce qui est décrit ici, la page canonique a raison — récupérez-la via get_confluence_page sur la page 2920349776.

Partie 1 : aperçu du problème

Trois champs. Chacun est court mais chargé d'importance.

Description de fonctionnalité et aperçu

Liez l'épopée Jira ou l'histoire, le document de fonctionnalité produit et les fichiers de conception. Puis écrivez un ou deux paragraphes cadrant le problème dans la voix de l'équipe — ce qui est construit, pour qui, pourquoi maintenant. Ne collez pas la spécification produit. Une décomposition est un document technique ; la section problème est le pont entre l'intention produit et le travail d'ingénierie, pas une copie des exigences.

Si le document de fonctionnalité produit est incomplet ou contredit ce qu'on a dit à l'équipe, soulevez-le ici comme une question ouverte (partie 5) plutôt que de deviner. L'intention produit ambiguë est la plus grande source de churn dans les décompositions.

Décompositions connexes

Si ce travail fait partie d'une initiative plus large — presque toujours quand un berger est impliqué — liez les décompositions des équipes sœurs ici. Utilisez Skill(navigating-the-initiative-funnel) pour les trouver, ou demandez directement au berger. La liaison croisée compte : un lecteur arrivant sur cette décomposition devrait pouvoir retracer vers l'initiative et à travers vers le travail des équipes pairs en deux clics.

Pour le travail limité à l'équipe sans initiative parent, écrivez « Pas partie d'une initiative active » plutôt que de laisser le champ vide.

Existe-t-il des solutions alternatives qui pourraient satisfaire les exigences produit avec moins d'effort ?

Répondez honnêtement. L'objectif de ce champ est de forcer la question — « pourrions-nous satisfaire le produit avec une modification plus petite ? » — pas de produire une longue table d'alternatives. Une ou deux phrases est généralement juste. Si une approche plus petite existe et est rejetée, nommez la raison.

Distinction avec la partie 4 : Les alternatives de la partie 1 sont « pourrions-nous ne pas construire cela du tout sous cette forme ? » Les alternatives par artefact de la partie 4 sont « étant donné que nous construisons cela, quels designs avons-nous rejetés pour chaque composant ? » Ne les confondez pas.

Partie 2 : liste de contrôle du périmètre de décomposition

C'est le cœur de la décomposition — un survey systématique de ce que le changement affecte. Chaque question a une saveur oui/non, mais la valeur réside dans les suites : quand « oui », quel est le périmètre réel, et quelles sont les implications pour la compatibilité, la sécurité et les autres équipes.

Appliquez le jugement architectural en répondant. Utilisez Skill(architecting-solutions) (dans le plugin bitwarden-tech-lead) comme lentille — évaluation du rayon de blast, parité d'accès aux données duales, compatibilité client V±2, réalité multi-client. Ne re-dérivez pas ces principes ici ; recourez à la compétence.

La liste de contrôle canonique sur la page 2920349776 est faisant autorité. Voici le résumé opérationnel :

Changements de base de données

Si oui, listez les tables, colonnes et index affectés. Puis demandez-vous : ces changements devront-ils être rétrocompatibles sous le modèle EDD (Evolutionary Database Design) de Bitwarden ? Les instances auto-hébergées ne peuvent pas annuler les migrations. Si le changement n'est pas rétrocompatible, le déploiement doit être par phases — rendez le phasing explicite ici.

Changements API

Si oui, listez les endpoints et changements de contrat. Puis demandez-vous :

• Rétrocompatibilité — même contrainte que la BD : les clients dans la nature sont à des versions variables. La compatibilité client V±2 est la lentille standard.
• Endpoints non authentifiés — si un nouveau endpoint est non authentifié, cela nécessite une architecture review. Signalez-le explicitement et ne traitez pas la décomposition comme PROPOSED-ready jusqu'à ce que l'architecture soit impliquée.

Composants d'interface utilisateur

Quels composants sont touchés, ajoutés ou modifiés ? Puis :

• Composants partagés appartenant à l'équipe. Si les composants partagés changent, envisagez de diviser ces changements dans leurs propres tâches/PRs afin qu'ils puissent être vérifiés et testés indépendamment. Re-tester tous les cas d'usage partagés ensemble est le mode défaillance.
• Changements Component Library (base). Si un composant de base est modifié, alertez l'équipe Design System et discutez de la possibilité de soutenir le travail selon le calendrier produit/design. S'ils ne peuvent pas, demandez leur approbation pour les changements API/UI que l'équipe fera.
• Nouveaux composants — listez-les. Pour chacun, demandez-vous s'il est candidat pour Component Library. Si oui, alertez l'équipe Design System et discutez de la façon de façonner l'API du composant pour une extraction future en Component Library.

Changements SDK

Si le travail touche le SDK, posez les quatre questions :

• Changements aux APIs FFI-exposées publiques ?
• Changements aux APIs internes publiques du SDK ?
• Changements aux APIs internes du SDK internes à l'équipe ?
• Opportunité de déplacer la logique existante vers le SDK — c'est la question le plus souvent ignorée. Si la logique TypeScript pourrait vivre dans le SDK et être partagée entre les clients, la décomposition est le bon endroit pour la surfacer.

Services touchés

Listez les services. Si vous touchez des services TypeScript pré-existants, demandez-vous si le travail devrait inclure la migration vers une méthode SDK de haut niveau plutôt que d'étendre le service TypeScript. N'étendez pas sans peser cela — c'est comment l'adoption du SDK stagne.

Hébergement

Cette fonctionnalité est-elle supportée sur Self-Hosted, Cloud ou les deux ? Self-hosted a des contraintes (pas d'annulation pour les migrations BD, lag de mise à niveau plus long, pas d'infrastructure centralisée sur laquelle s'appuyer) qui changent la conception.

Feature flagging

Cette fonctionnalité sera-t-elle feature-flagged, ou en direct sur une branche features de longue durée ? Si flagged, où le flag est-il appliqué — côté serveur, côté client, les deux ? Quelles surfaces UI et services sont contrôlés par lui ? Les branches features de longue durée sont généralement une mauvaise odeur ; surfacez-les afin que l'équipe puisse décider si le changement est vraiment bien façonné.

Considérations de sécurité

Répondez aux trois questions :

• Travail cryptographique — a-t-il besoin d'une révision interne, d'une révision externe, ou d'une preuve de sécurité ? Si incertain, traitez comme nécessitant une révision interne ; routez via Skill(bitwarden-security-context) (dans le plugin bitwarden-security-engineer).
• Définitions de sécurité existantes — y en a-t-il dans ce domaine ? De nouvelles peuvent-elles être construites ? Skill(threat-modeling) (dans le plugin bitwarden-security-engineer) est la source pour le format de définition.
• Changements rompants — des définitions de sécurité existantes seront-elles invalidées par ce travail ? Si oui, la décomposition est incomplète jusqu'à ce que l'ingénierie sécurité soit consultée.

Considérations de test

Quel test est nécessaire au-delà de la couverture unité/intégration standard ? Tests multiplateformes, tests de performance, tests de sécurité, tests de charge, flux QA manuels. Notez qui exécute chacun — l'équipe, QA, sécurité, une autre équipe.

Considérations de dette technique

Quelle dette technique pourrait être payée opportunément pendant que ce travail progresse ? Soyez sélectif — tirer du nettoyage sans rapport dans le périmètre est comment les décompositions gonflent. La bonne réponse est souvent « aucune, mais documenter les candidats pour le travail futur ».

Différences dans l'environnement de développement

La solution a-t-elle besoin d'un comportement différent dans les environnements de développement — des valeurs par défaut différentes, des backends de mock, une config séparée ? Notez-les afin que l'équipe ne soit pas surprise quand la parité local-vs-prod se brise.

Partie 4 : artefacts de spécification

Les décompositions plus grandes produisent une ou plusieurs pages enfants — documents de spécification qui vont plus loin que la décomposition ne peut. Chaque page enfant couvre un composant majeur ou une zone de décision : un contrat API, un schéma de données, une API de composant UI, un schéma cryptographique.

Liez chaque artefact dans le tableau de la partie 4. Pour chacun, vérifiez avant que la décomposition ne passe à PROPOSED :

• L'interface publique est définie. Les contrats API, les schémas de données, les APIs de composant sont énoncés au niveau auquel un autre ingénieur ou une autre équipe peut coder.
• Les comportements clés et cas limites sont couverts. Utilisez la liste de contrôle de la partie 2 comme lentille — si l'artefact touche BD, API, UI, SDK, hébergement, les considérations correspondantes s'affichent dans la spec.
• Les alternatives considérées sont listées. Pour chaque décision de conception significative, nommez les alternatives et pourquoi elles ont été rejetées. C'est la section alternatives de la partie 4 — différente du « pourrions-nous ne pas construire cela du tout » de la partie 1.
• L'artefact a été examiné par les équipes affectées du tableau inter-équipes de la partie 3. C'est le pont vers Skill(coordinating-cross-team-breakdown) — les pages enfants de la partie 4 ont souvent besoin de leur propre révision par équipe avant que la décomposition parent ne puisse passer à ACCEPTED.

Si la décomposition est assez petite qu'aucune page enfant n'est nécessaire, dites-le explicitement : « La spécification est contenue dans la partie 2 ci-dessus ; aucun artefact séparé requis. » Ne laissez pas la partie 4 silencieusement vide.

Partie 5 : questions ouvertes

Suivez chaque question non résolue avec un propriétaire et (idéalement) une date de résolution cible. Les questions ouvertes ne sont pas un signe d'une décomposition incomplète — c'est l'acknowlegement explicite de ce que l'équipe ne sait pas encore. Les hypothèses cachées sont le mode défaillance ; les questions suivies sont saines.

Déplacez les questions à fermé (ou supprimez-les, la résolution capturée dans les parties 1–4 selon le cas) au fur et à mesure qu'elles obtiennent des réponses. Une décomposition ne devrait pas atteindre ACCEPTED avec des questions matérielles encore ouvertes — si une question bloque, traitez-la comme un bloqueur et ne passez pas à PROPOSED.

Partie 6 : contexte IA

Ce bloc existe pour Claude (et les futurs ingénieurs utilisant Claude) revenant à la décomposition plus tard. Remplissez-le explicitement :

• Ce que cette page est. Une phrase : la décomposition pour <feature>, appartenant à <team>, actuellement à <status>.
• Ce qu'il faut lire d'abord. L'épopée Jira liée, l'initiative d'origine (si existante), la section plan d'architecture, les PoC PRs, la spécification produit.
• Ce qu'il faut lire ensuite. Les pages enfants de la partie 4 pertinentes pour la tâche actuelle.
• Arêtes vives connues. N'importe quoi qu'un ingénieur ou un assistant IA devrait savoir qui ne soit pas évident en lisant le doc de haut en bas — contexte prior supposé, sections délibérément inachevées, information connue incorrecte en attente de mise à jour.

Un bloc de contexte IA rempli est ce qui rend la décomposition utile dans les futures conversations Claude. Le sauter est une taxe sur chaque lecture future.

Quand vous passez à PROPOSED

Une fois que les parties 1, 2, 4 et 5 sont complètes et que l'équipe a revu en interne, définissez le statut sur PROPOSED. Puis invoquez Skill(coordinating-cross-team-breakdown) — le travail passe de la rédaction (cette compétence) à la coordination inter-équipes (la compétence associée). La compétence associée appartient :

• À construire ou remplir le tableau d'approbation de la partie 3.
• À parcourir la liste de contrôle inter-équipes (changements mobiles, composants en dehors du domaine de l'équipe, dépendances aux services d'autres équipes, APIs construites pour d'autres équipes).
• À chasser les approbations pour passer de PROPOSED à ACCEPTED.
• À exécuter la liste de contrôle de communication avant que la décomposition ne passe à COMPLETE.

La machine d'état vit dans cette compétence ; le flux de travail inter-équipes vit dans la compétence associée. Ils se composent par référence croisée, pas auto-invocation.

Erreurs courantes

• Rédaction dans le vide. Le contexte d'initiative — le berger, les épopées des équipes sœurs, le plan d'architecture — est l'entrée qui rend les parties 1 et 3 correctes. Ignorer Skill(navigating-the-initiative-funnel) quand une initiative existe est l'erreur upstream la plus courante.
• Coller la spécification produit dans la partie 1. La décomposition est un document technique. Liez la spec ; ne la reproduisez pas.
• Traiter la partie 2 comme une liste de contrôle oui/non. La valeur réside dans les suites. « Oui, changements BD » sans périmètre et sans analyse de compatibilité ne vaut pas mieux que de sauter la question.
• Ignorer les alternatives de la partie 4. « Nous avons choisi cette conception » sans « nous avons considéré et rejeté celles-ci » est une décomposition qui cache ses propres décisions. Les lecteurs futurs — et les réviseurs de la partie 3 — ont besoin des alternatives pour évaluer le choix.
• Laisser la partie 6 vide. Le bloc contexte IA est bon marché à remplir pendant la rédaction et coûteux à reconstruire plus tard.
• Passer à ACCEPTED sans toutes les approbations de la partie 3. Tout l'intérêt de l'état est que les équipes affectées aient signé. Le traiter cérémonieusement produit des décompositions que personne ne fait confiance.
• Éditer silencieusement une décomposition ACCEPTED. Si la conception doit changer matériellement, remplacez ou revenez à PROPOSED — ne révisez pas silencieusement.

Référence

• Tech Breakdown Template (page 2920349776) — canonique. Récupérez via get_confluence_page pour le modèle complet, les étiquettes de champ littérales et les dernières définitions d'état.
• EDD — Evolutionary Database Design — référencé dans la partie 2 pour la rétrocompatibilité des changements BD.
• Connexe : Skill(navigating-the-initiative-funnel) — charge-portante quand la décomposition se trouve sous une initiative Bitwarden ; fournit le berger, l'équipe-sœur et le contexte du plan d'architecture qui alimente les parties 1, 2, 3. Skill(coordinating-cross-team-breakdown) — approbations de la partie 3, liste de contrôle inter-équipes et le flux de travail de communication qui ferme la décomposition. Skill(architecting-solutions) (dans le plugin bitwarden-tech-lead) — la lentille de jugement architectural à appliquer à travers la partie 2.