Blog
« Cette réponse d’API ne semble pas correspondre au design Figma, non ? »
C’est vendredi, juste avant la release. Un seul message sur Slack fige toute l’équipe.
Le PM avait consciencieusement mis à jour les tickets Jira. Le designer avait peaufiné les fichiers Figma. Les ingénieurs avaient livré des PR à plein régime. Chacun faisait un excellent travail dans son domaine — et pourtant, au moment où tout se rejoignait, le décalage était flagrant.
Ce qui suit est prévisible : de l’archéologie Slack un vendredi soir. « Où est-ce que cette spec a été décidée ? » « Cette API ne correspond pas au ticket original — qui l’a modifiée ? » Personne n’a la réponse, parce que le contexte derrière la décision n’a jamais été capturé nulle part.
Nous sommes tombés dans cet enfer du « ce n’est la faute de personne, mais tout brûle » plus souvent que nous ne voudrions l’admettre. Beaket est né de cette expérience.
Les specs sont conçues pour mentir
Ce n’est pas que les specs soient mauvaises. C’est que la structure qui les entoure est cassée.
L’information vit naturellement dans des endroits différents — les PM vivent dans Jira, les designers dans Figma, les ingénieurs dans GitHub. C’est normal. Chaque outil excelle dans sa spécialité, et il ne faut pas lutter contre ça.
Le problème, c’est l’acte de tout recopier dans une seule « source de vérité ».
Dès que vous transcrivez quelque chose dans Notion ou un wiki, il existe désormais deux copies. Quand l’une est mise à jour, l’autre devient un mensonge. Une spec qui cesse d’être maintenue perd le raisonnement derrière les décisions passées et devient une relique qui s’éloigne de plus en plus de l’implémentation réelle.
Ce n’est pas un problème de discipline. C’est un problème structurel. Tant que des copies existent, la dérive est inévitable.
Relier, pas copier
Alors nous avons abandonné l’approche « tout centraliser ». Construire un wiki de plus n’aurait mené qu’au même résultat.
Ce que Beaket fait à la place, c’est dessiner des relations entre les informations qui existent déjà.
Vous ne copiez pas vos designs Figma ou vos discussions GitHub dans Beaket. Chaque outil reste la source de vérité pour son domaine. Beaket connecte simplement ces sources à travers le contexte de pourquoi une décision a été prise.
Concrètement, il structure les décisions de projet autour de trois types de nœuds :
- Spec — L’exigence métier. Que construisons-nous, et pourquoi ?
- Brief — Le compte-rendu de décision design. Qu’est-ce qui a été décidé du point de vue du design, pourquoi, et qu’est-ce qui se casse sans ça.
- ADR — Le compte-rendu de décision technique. Pourquoi cette approche ? Quelles alternatives ont été envisagées et rejetées ?
Ces trois éléments se connectent entre eux par des arêtes, formant un graphe de décisions. Vous ne rédigez pas de spécifications détaillées dans Beaket. Vous capturez ce qui a été décidé, pourquoi, et à quoi c’est relié — rien de plus.
La règle du « écrire moins »
Honnêtement, c’est l’aspect le plus débattu du produit.
« Ne devrait-on pas laisser les gens écrire plus de détails ? » Bien sûr que la question s’est posée. Mais dès que vous autorisez l’écriture détaillée, vous avez construit un autre wiki. Et les wikis pourrissent toujours.
Nous avons donc intentionnellement intégré une contrainte dans Beaket : écrire moins.
L’heuristique est simple — est-ce que votre vous du futur viendra chercher le raisonnement dans six mois ? Si oui, notez-le. Sinon, non. Les listes de paramètres et les étapes d’implémentation appartiennent à GitHub. Beaket ne contient que l’unité minimale du pourquoi.
C’est un compromis délibéré. Beaket ne sera jamais un outil de documentation de design complet. C’est voulu.
Le flag Ready : une poignée de main, pas une approbation
Il y a un dernier mécanisme que nous sommes contents d’avoir construit.
Après qu’une Spec est rédigée, le designer et l’ingénieur activent indépendamment un flag « Ready ». Le designer signale « Je comprends les exigences du point de vue de l’UI. » L’ingénieur signale « Je les comprends du point de vue technique. » Ce n’est que lorsque les deux flags sont activés que la Spec devient « Ready ».
Ce n’est pas un workflow d’approbation. C’est une poignée de main.
Pas « je l’ai lu », mais « de mon point de vue, on est bons ». C’est un garde-fou structurel contre le lancement d’une implémentation sur des exigences ambiguës.
Et si une Spec change après avoir été marquée Ready, le rayon d’impact — chaque Brief et ADR connecté — est automatiquement mis en évidence. Plus besoin de fouiller dans l’historique Slack.
Suivre la piste des décisions
Beaket suit l’historique des changements au-delà du simple qui a changé quoi, quand. Il capture aussi le pourquoi.
Sélectionnez n’importe quel passage de texte, et vous pouvez retracer quand il a été modifié, par qui, et pour quelle raison. Nous appelons ça la Piste des Décisions (Decision Trail).
Ce n’est pas une fonctionnalité spectaculaire. Mais dans six mois, quand quelqu’un demandera « pourquoi est-ce que cette spec est comme ça ? » — la réponse sera là. Rien que ça change la vitesse à laquelle une équipe peut prendre des décisions.
Ce que nous ne savons pas encore
Nous ne pensons pas que Beaket convienne à toutes les équipes.
Pour une petite équipe assise dans la même pièce, où le contexte est naturellement partagé, ça pourrait être excessif. Pour des organisations de centaines de personnes, nous n’avons pas encore suffisamment validé.
Ce dont nous sommes certains, c’est ceci : perdre le contexte derrière les décisions a toujours un coût. Et ce coût croît de manière exponentielle à mesure que les équipes grandissent et que le temps passe.
Beaket est un outil pour maintenir ce coût sous contrôle — structurellement. Ce n’est pas une solution miracle. C’est plutôt une assurance.
Si votre équipe a déjà vécu une situation où personne ne pouvait expliquer pourquoi une décision de design avait été prise — commencez par connecter une seule décision. Voyez où ça vous mène.