1. Pourquoi un handbook d'ingénierie ?

Pourquoi ce chapitre existe

Une équipe peut avoir des personnes compétentes, une suite de tests conséquente et une CI rapide, tout en livrant régulièrement des régressions. Cela paraît contradictoire seulement si l'on réduit la qualité à une propriété du code ou à la quantité de contrôles effectués. Dans la pratique, une régression est le résultat d'une décision prise avec une compréhension incomplète du système et d'un dispositif qui n'a pas permis de corriger cette compréhension à temps.

Ce chapitre pose le problème auquel répond ce handbook : rendre la création de logiciel plus prévisible sans réduire l'ingénierie à une bureaucratie.

Les idées essentielles

• Une régression est un comportement qui cesse de satisfaire une attente existante, qu'elle ait ou non été documentée.
• Le risque ne disparaît pas : il est déplacé, réduit, détecté plus tôt ou rendu plus facile à corriger.
• Les contrôles de qualité sont des sources de preuve. Leur valeur dépend de la question à laquelle ils répondent.
• Les défaillances répétées sont d'abord des informations sur le système de travail, avant d'être des informations sur une personne.

La régression est un phénomène de système

Considérons une modification de la règle qui détermine si une facture peut être remboursée. Le développeur couvre le nouveau cas demandé. La QA vérifie le parcours visible. Quelques jours plus tard, un traitement nocturne rejette des factures anciennes. La cause n'est pas nécessairement l'absence d'un test supplémentaire. Le système contenait une dépendance temporelle non visible, et aucun mécanisme n'a obligé l'équipe à l'examiner.

Ce schéma est fréquent : un changement local traverse des frontières qui ne sont pas explicites — données historiques, consommateurs d'API, règles métier adjacentes, jobs asynchrones, droits d'accès, tableaux de bord, procédures de support. La qualité du diff peut être excellente sans que l'impact du changement ait été correctement compris.

La réponse instinctive est d'ajouter une étape : plus de validation manuelle, plus d'approbateurs, plus de règles. Parfois c'est justifié. Souvent, cela ajoute du délai sans ajouter d'information pertinente. Une validation manuelle ne détecte pas une incompatibilité de schéma si personne ne sait qu'un consommateur dépend de ce schéma. Une approbation n'est une preuve que si l'approbateur possède un contexte que l'auteur n'a pas.

Du blâme à l'apprentissage

Après un incident, la question « qui a laissé passer cela ? » est séduisante parce qu'elle donne l'illusion d'une cause simple. Elle produit toutefois deux effets coûteux : les personnes cachent les signaux faibles, et l'organisation s'arrête avant d'avoir compris les conditions qui ont rendu l'erreur plausible.

Une enquête utile demande plutôt :

• Quelle attente a été violée et pour qui ?
• Quelles informations étaient disponibles au moment de la décision ?
• Quels signaux auraient pu révéler le problème plus tôt ?
• Quelle barrière a échoué, et pour quelle raison était-il raisonnable de s'y fier ?
• Que changer dans le système rendrait une erreur semblable moins probable ou moins dommageable ?

Cette approche ne nie pas la responsabilité individuelle. Elle refuse simplement de confondre responsabilité et simplification causale. Une personne doit pouvoir expliquer une décision ; l'organisation doit créer les conditions permettant de prendre une bonne décision.

Un handbook est un système de décision partagé

Dans une petite équipe stable, une grande part du savoir reste orale. Cela fonctionne jusqu'au jour où le produit, l'équipe ou le rythme de changement dépasse la mémoire collective. Les mêmes discussions se répètent, les décisions sont incohérentes d'un périmètre à l'autre, et les nouveaux arrivants apprennent les règles réelles après leurs premiers incidents.

Un bon handbook rend explicites les raisonnements qui méritent d'être réutilisés. Il ne remplace pas le dialogue ; il évite de recommencer à zéro. Il peut dire, par exemple, pourquoi les migrations de données doivent être pensées comme des déploiements, ce qu'une revue de code cherche à découvrir, ou pourquoi un rollback n'est pas une stratégie suffisante pour une écriture non réversible.

Sa valeur se mesure moins à son exhaustivité qu'à sa capacité à influencer une décision concrète. Si une règle n'aide personne à mieux concevoir, mieux vérifier ou mieux réagir, elle encombre le livre et doit être retirée.

Exemple filé — Une option « sans conséquence » qui devient un incident

Une équipe ajoute une option permettant aux administrateurs d'appliquer immédiatement une nouvelle politique de prix à tous les abonnements en cours. Le ticket précise la nouvelle règle et l'écran. L'implémentation est courte : une mise à jour de configuration et un recalcul lors de la prochaine facture. Les tests couvrent le nouveau taux et la revue confirme que le code est lisible.

Deux semaines plus tard, les factures de certains clients ne correspondent plus au montant annoncé lors de leur souscription. L'équipe découvre que l'ancienne règle était implicitement figée pour les contrats annuels, alors que les contrats mensuels suivaient la politique courante. Ce comportement n'était écrit ni dans le ticket, ni dans le code de l'écran. Il vivait dans une condition de facturation et dans une procédure support.

La lecture superficielle conclurait : « il manquait un test ». C'est vrai mais incomplet. L'incident révèle une chaîne : l'intention de produit n'a pas distingué les contrats ; l'impact sur les données historiques n'a pas été examiné ; l'option a été activée globalement ; aucune métrique ne comparait prix annoncé et prix facturé ; le support n'était pas associé à la découverte alors qu'il portait la connaissance de l'exception.

Étape absente ou insuffisante	Conséquence	Barrière qui aurait réduit le risque
Modèle de domaine	« Politique de prix » comprise comme unique	Exemples par type de contrat et invariant de prix figé
Analyse d'impact	Factures historiques oubliées	Cartographie des lecteurs de la règle et des données de souscription
Preuve	Seul le nouveau taux est testé	Test de caractérisation des contrats annuels et mensuels
Livraison	Activation globale	Cohorte interne, signal d'écart entre prix annoncé et facturé
Apprentissage	Incident attribué au dernier auteur	Analyse des hypothèses, contrats et feedbacks manquants

Le correctif robuste n'est pas seulement une condition supplémentaire. L'équipe distingue explicitement une décision de prix de la politique qui produit les prix futurs. Elle prépare une migration pour les contrats concernés, ajoute une réconciliation et documente la règle avec Finance et Support. Le système de travail devient plus fiable parce que l'incident a amélioré plusieurs barrières, chacune adaptée à une partie du mécanisme.

Ce que l'exemple change dans la pratique

Il ne demande pas que chaque option soit traitée comme un projet d'architecture. Il montre pourquoi l'effort de découverte doit suivre les propriétés du changement. Une modification de libellé n'aurait pas nécessité ces protections. Une modification de règle qui touche contrats, montants historiques et facturation méritait davantage de preuves et une exposition contrôlée. La maturité consiste à faire cette différence explicitement, avant que l'incident ne l'impose.

Anti-patterns

Ajouter des contrôles après chaque incident

Après une défaillance, on ajoute une signature obligatoire, une réunion ou une ligne dans une checklist. Accumulés, ces contrôles ralentissent tous les changements, y compris ceux auxquels ils ne s'appliquent pas, tandis que le mécanisme réel reste inchangé. Avant d'ajouter un contrôle, il faut formuler l'hypothèse : quelle erreur ce contrôle détectera-t-il, avec quelle information nouvelle, et à quel moment ?

Considérer la QA comme la dernière barrière

La QA apporte une expertise irremplaçable sur les scénarios, les usages et les risques. La placer en bout de chaîne transforme néanmoins cette expertise en filet de rattrapage. Elle découvre tard ce que l'équipe aurait dû apprendre dès la conception. La qualité devient une fonction séparée au lieu d'une propriété du travail collectif.

Suivre des indicateurs de conformité

« 95 % de couverture », « toutes les PR revues » ou « zéro erreur de lint » sont faciles à compter. Ils peuvent signaler une dérive, mais ne prouvent ni que les comportements importants sont protégés, ni que la revue a apporté du contexte. Un indicateur devient dangereux lorsqu'il remplace la question qu'il était censé susciter.

Bonnes pratiques

Adapter l'effort au risque, pas à l'habitude

Un changement à fort impact mérite plus de découverte, de preuves et de garde-fous qu'un changement isolé et facilement réversible. Cette évaluation doit être explicite. Elle évite deux écueils symétriques : traiter un changement sensible comme un banal correctif, ou transformer chaque modification mineure en procédure lourde.

Signal	Question à poser	Réponse possible
Données irréversibles	Une erreur peut-elle être réparée sans intervention manuelle ?	Migration en étapes, sauvegarde, contrôle de cohérence
Règle métier transverse	Qui dépend de ce comportement au-delà de l'écran modifié ?	Cartographie, tests de contrat, revue métier
Faible observabilité	Saurons-nous vite que cela échoue ?	Instrumentation, métrique et alerte avant livraison
Grand rayon d'action	Combien d'utilisateurs ou de systèmes sont exposés ?	Déploiement progressif, feature flag, limite de débit

Traiter les incidents comme des investissements de connaissance

L'action la plus précieuse après un incident n'est pas toujours la plus visible. Corriger la condition fautive restaure le service. Comprendre pourquoi le comportement n'était ni spécifié, ni testé, ni observable réduit la probabilité de toute une famille d'incidents. Les deux actions sont nécessaires, mais seule la seconde fait progresser le système.

Checklist — Avant d'ajouter une règle de processus

• Le risque visé est-il formulé comme un comportement et un impact, plutôt que comme la faute d'une personne ?
• Le nouveau contrôle apporte-t-il une information ou une barrière que les contrôles existants ne fournissent pas ?
• Son coût est-il proportionné à la fréquence et à la gravité du risque ?
• Peut-il être automatisé, ciblé ou supprimé lorsque son hypothèse n'est plus valable ?
• L'équipe saura-t-elle reconnaître les cas où ce contrôle est insuffisant ?

À retenir

Une équipe ne devient pas fiable en demandant davantage d'attention à chacun. Elle le devient lorsqu'elle transforme les erreurs possibles en risques visibles, construit des preuves pertinentes et apprend des écarts entre l'intention et la réalité. Le handbook est le support de cette mémoire et de ce raisonnement partagés.