Écrire une analyse technique avant de coder : options comparées, ADR léger et assistants IA
Énoncé du problème, état actuel, tableau d'options, décision et raisons, points ouverts, et ce que l'IA apporte ou fausse.
Le réflexe de coder tout de suite coûte cher : on découvre la contrainte qui tue la solution après trois jours. J'écris donc une courte note d'analyse avant le code : un fichier Markdown à côté du projet, qui sert de brouillon de réflexion puis de trace de la décision.
Le plan de la note
- Énoncé du problème : deux ou trois phrases. Quel est le besoin, pour qui, quel symptôme ou quelle limite l'a déclenché ?
- État actuel : comment cela fonctionne aujourd'hui, avec uniquement des faits vérifiés (relecture du code, requête en lecture seule, documentation officielle). Les hypothèses sont marquées comme telles.
- Options comparées dans un tableau.
- Décision et ses raisons.
- Points ouverts : ce qui reste à confirmer, et par qui.
Comparer les options dans un tableau
Un tableau force à utiliser les mêmes critères pour toutes les options :
| Critère | A : sauvegarde exportée en fichier | B : copie géo-répliquée | C : ne rien faire |
|---|---|---|---|
| Effort de mise en place | Moyen | Faible | Nul |
| Coût récurrent | Stockage | Base secondaire | Nul |
| Délai de restauration | Long | Court | Inchangé |
| Risque principal | Fichier incomplet | Bascule mal testée | Limite atteinte |
| Réversible ? | Oui | Oui | Oui |
Les options ci-dessus sont un exemple générique. Je garde toujours « ne rien faire » comme référence, et une ligne « réversible ? » : une décision réversible peut être prise plus vite.
Un ADR léger
Un ADR (Architecture Decision Record) est la partie « décision » de la note, réduite à l'essentiel :
## Décision : copier la base par une file de demandes
- Statut : accepté
- Contexte : les copies manuelles sont longues et non tracées.
- Décision : on traite les demandes par une file, avec approbation.
- Raisons : traçabilité, reprise après échec, pas de droits directs.
- Conséquences : un composant à maintenir ; la file doit être surveillée.
- Alternatives écartées : script manuel (non tracé), service tiers (coût).
Le point clé est la section « Raisons ». Dans six mois, personne ne se souviendra pourquoi on a choisi ceci plutôt que cela : le fichier le dit. Si la décision change, on n'efface rien : on ajoute un nouvel ADR qui remplace l'ancien (statut « remplacé »).
Les assistants IA : aide et pièges
Ce qui marche bien :
- Reformuler le problème et poser les questions auxquelles je n'ai pas pensé.
- Proposer des options et des critères de comparaison.
- Relire la note pour détecter une contradiction ou un trou.
- Lire le code pour décrire l'état actuel, avec références aux fichiers.
Là où il trompe :
- Fonctionnalités inventées : une option, un paramètre ou une limite de service qui n'existe pas. Je vérifie dans la documentation officielle avant de l'écrire.
- Confiance uniforme : une hypothèse est présentée avec le même aplomb qu'un fait. J'exige la source de chaque fait.
- Biais de confirmation : si je présente ma solution préférée, il la valide. Je demande plutôt les arguments contre.
- Décider à ma place : l'assistant éclaire, la décision et ses raisons restent les miennes.
Retour d'expérience
- Écrire l'état actuel avant les solutions. La moitié des mauvaises idées disparaissent quand le fait est établi.
- Rester court. Une note d'une page est relue ; dix pages ne le sont pas.
- Dater la note et indiquer son statut (brouillon, décidé, remplacé).
- Garder les points ouverts visibles. Une question non résolue écrite vaut mieux qu'une certitude fausse.
- Faire le lien avec les modèles d'architecture : une décision structurelle déclenche la mise à jour des vues.