Comment écrire un document d'architecture avec l'IA : un modèle en six sections, où l'IA aide, et où elle invente des contraintes

À quoi sert un document d'architecture

Il répond à une question pour la personne suivante : pourquoi le système a-t-il cette forme ? Pas comment l'exploiter (c'est le runbook), pas ce qu'il fait pour les utilisateurs (c'est le PRD), mais quelles pièces existent, comment les données circulent entre elles, et quels choix ont été faits exprès plutôt que par accident.

Le lecteur est un ingénieur qui arrive dans six mois, ou vous après une longue pause. Si le document ne se lit pas en dix minutes, il ne sera pas lu. Deux pages, un schéma, un tableau de décisions.

Le modèle en six sections

La colonne « qui rédige » est le sujet de cet article. Le modèle en lui-même est ordinaire ; la répartition est ce qui rend l'IA utile plutôt que dangereuse.

Contexte

Deux phrases et un lien. L'agent fait cela bien parce qu'il résume un document qu'on lui a donné. Faites-lui nommer ce qui existe aujourd'hui : « Les rappels n'existent pas ; la synchronisation d'agenda et l'envoi de courriels existent. »

Contraintes

Les limites dures que la conception doit respecter. « Les données clients restent dans la région UE. » « Le fournisseur de courriel limite à 100 par minute. » « Deux ingénieurs, un cycle. » « Ne pas modifier la couche de synchronisation, remplacée le trimestre prochain. »

Écrivez cette section vous-même, avant que l'agent voie le document. Un agent à qui l'on demande des contraintes en produira de plausibles : « doit supporter 10 000 utilisateurs simultanés », « doit être horizontalement scalable », « doit supporter un basculement multi-région ». Aucune n'est la vôtre. Une fois dans le document, la section des composants conçoit pour elles, et vous vous retrouvez avec une file, un cache et une région de secours pour une fonctionnalité qui envoie quarante courriels par jour.

Composants

Le premier jet de l'agent est en général une liste raisonnable des pièces touchées. Votre travail est de couper : retirez les composants ajoutés pour satisfaire des contraintes inventées, et ajoutez la ligne « non touché : X, Y » pour les parties que vous laissez délibérément tranquilles. La liste « non touché » est plus utile à un relecteur que la liste des pièces touchées.

Flux de données

Une séquence numérotée : « 1. Le cron se déclenche à l'heure pile. 2. Requête des réservations des prochaines 24 h sans marqueur d'envoi. 3. Rendu du modèle. 4. Envoi via le fournisseur. 5. Marquage envoyé. » L'agent rédige cela depuis le PRD et les composants ; vous vérifiez chaque étape contre le code existant. L'étape 2 est là où vivent la plupart des bugs, et l'agent ne saura pas que la table des réservations a une colonne de suppression logique.

Décisions

Une ligne par choix que quelqu'un pourrait questionner plus tard : options, retenue, pourquoi. L'agent est bon pour lister des options auxquelles vous n'aviez pas pensé ; il est mauvais pour choisir, parce qu'il ne connaît ni votre équipe ni votre histoire. Demandez-lui des alternatives, puis écrivez vous-même les cellules « retenue » et « pourquoi ». Trois à six lignes, c'est normal. Si vous en avez douze, le document couvre deux fonctionnalités.

Risques

L'agent en listera quinze. Gardez-en cinq, chacun avec une atténuation en une ligne. Un risque sans atténuation est une inquiétude, pas un risque.

Où l'IA aide et où elle nuit

Elle aide :

• Premier jet du contexte, des composants et du flux de données à partir d'un PRD. Elle lit un document et le reformule structurellement, ce qu'elle fait bien.
• Alternatives sous chaque décision. « Que pourrait-on faire d'autre ici ? » produit de façon fiable une option que vous n'aviez pas envisagée.
• Vérifications de cohérence. « Chaque composant du flux de données apparaît-il dans la section des composants ? » attrape les oublis d'un humain fatigué.
• Brainstorming de risques, à condition d'élaguer.

Elle nuit :

• Contraintes. Inventées, plausibles et structurantes. Voir plus haut.
• Choisir entre des options. Elle prend la réponse du manuel, pas celle qui convient à une équipe de deux avec une échéance.
• Affirmations sur l'état actuel. « La couche de synchronisation existante expose un webhook » alors que non. Tout ce que l'agent dit du système d'aujourd'hui doit être vérifié contre le code.
• Échelle. Livrée à elle-même, elle conçoit pour l'échelle de ses données d'entraînement, pas la vôtre.

La règle que nous appliquons : l'agent peut écrire tout ce qui reformule une entrée qu'on lui a donnée ; un humain écrit tout ce qui est un fait sur le monde ou un choix.

Le faire dans Atrix

Notre propre agent IA produit un document d'architecture comme l'une des trois sorties d'une exécution Develop, avec les exigences et les tickets planifiés, à partir du brief et du PRD que vous lui donnez. Il suit la répartition ci-dessus parce que nous le briefons ainsi : le brief de l'exécution nomme les contraintes comme entrée, et l'agent a pour consigne de ne pas en ajouter. Le document arrive comme une page dans Docs, avec historique des versions, commentaires et coédition en direct, de sorte que les modifications de l'ingénieur sur les composants et les décisions apparaissent comme un diff par rapport au brouillon de l'agent.

Le schéma en blocs se dessine sur le tableau blanc à l'intérieur de la page. Les tableaux blancs dans Atrix sont des tableaux Excalidraw : vous dessinez les boîtes et les flèches à la main, et le dessin reste modifiable à côté du texte. Il n'y a pas de génération de diagramme à partir de texte ; si vous voulez que l'agent produise un diagramme, demandez-lui un flux de données numéroté et dessinez à partir de là, ce qui prend une dizaine de minutes pour une fonctionnalité à six composants. Les outils qui génèrent des diagrammes depuis du texte, comme l'IA de Miro et DiagramGPT d'Eraser, sont traités dans un autre article.

Un exemple réel, abrégé

Contexte : rappels de réservation ; PRD v3 ; aujourd'hui pas de rappels, la synchronisation d'agenda et l'envoi de courriels existent.

Contraintes (humain) : aucune modification de la couche de synchronisation ; limite fournisseur de 100 courriels par minute ; un ingénieur, un cycle ; données UE seulement.

Composants (rédigés par l'agent, coupés par l'humain) : planificateur de rappels (nouveau), modèle de rappel (nouveau), requête des réservations (existante, lecture seule), envoi de courriels (existant). Non touché : couche de synchronisation, interface de l'agenda.

Flux de données : les cinq étapes listées plus haut, avec l'étape 2 corrigée pour exclure les réservations supprimées logiquement après vérification de la table.

Décisions : cron ou file (cron ; le volume est de quarante par jour, une file est un second système à exploiter) ; envoi par réservation ou par lot (par lot, pour rester sous la limite du fournisseur) ; stockage du modèle (page dans Docs, pas de nouvelle table).

Risques : envois en double si les crons se chevauchent (atténuation : marqueur d'envoi écrit avant l'envoi) ; panne du fournisseur (atténuation : nouvel essai l'heure suivante, pas d'alerte sous une heure) ; erreurs de fuseau horaire (atténuation : stocker et comparer en UTC, rendre dans le fuseau de la réservation).

Le brouillon de l'agent avait ajouté une file Redis et un « service de notification » pour satisfaire une contrainte de scalabilité qu'il avait écrite lui-même. Les deux ont été coupés, et le document tient sur une page et demie.

FAQ

Que doit contenir un document d'architecture ?

Six sections : contexte, contraintes, composants (touchés et non touchés), flux de données en séquence numérotée, un tableau de décisions avec options et raisons, et cinq risques avec atténuations. Deux pages et un schéma, c'est la cible.

L'IA peut-elle écrire un document d'architecture logicielle ?

Elle peut rédiger le contexte, les composants, le flux de données et les alternatives à partir d'un PRD, et elle le fait bien. Elle ne doit pas écrire les contraintes ni prendre les décisions, parce qu'elle invente des contraintes et choisit les options du manuel. Traitez-la comme un outil de brouillon avec un humain responsable de chaque fait et de chaque choix.

Quelle est la différence entre un document d'architecture et un ADR ?

Un architecture decision record couvre une décision : contexte, options, choix, conséquences. Le document d'architecture d'une fonctionnalité contient plusieurs décisions dans un tableau, plus les composants et le flux de données autour. Les petites équipes gardent en général le tableau dans le document et promeuvent une ligne en ADR seulement quand elle concerne plus d'une fonctionnalité.

Quelle longueur pour un document d'architecture ?

Deux pages, lues en dix minutes. S'il est plus long, il décrit deux fonctionnalités ou il a absorbé le runbook. Sortez le détail opérationnel.

Le document d'architecture doit-il contenir un schéma ?

Oui, un schéma en blocs des composants avec des flèches pour le flux de données principal. Dessinez-le à la main depuis le flux numéroté ; cela prend dix minutes, et le fait de dessiner révèle les flèches manquantes.

Quand écrire le document d'architecture ?

Après le gel du PRD et avant la création des tickets, parce que la section des composants détermine comment le travail se découpe. L'écrire une fois les tickets créés en fait une description de ce qui a été fait, ce qui est un autre document.

Prochaine étape

Prenez votre fonctionnalité en cours, écrivez la section des contraintes à la main en cinq minutes, puis donnez le PRD et ces contraintes à l'agent que vous utilisez et demandez-lui les cinq autres sections. Le modèle de PRD fournit à l'agent les exigences numérotées dont il a besoin, et dans Atrix une exécution Develop de l'agent IA renvoie le document d'architecture comme une page que vous éditez avec l'équipe.