Documenter les règles métier des applications IA en langage clair

Pourquoi des règles floues créent des apps peu fiables

Les règles métier disent à une application quoi faire dans des situations réelles. Elles répondent à des questions comme qui peut approuver une demande, comment un total est calculé, et ce qui se passe quand un cas sort du schéma habituel.

Si ces règles sont vagues, l'application doit quand même choisir une voie. Elle risque simplement de ne pas choisir celle que vous attendiez.

Prenez une règle comme «les dépenses importantes nécessitent l'approbation d'un manager.» Une personne peut trouver cela clair. Un·e développeur·se ne le sera pas. Qu'est-ce qu'une dépense importante : 500 $, 5 000 $ ou tout montant au‑delà d'un budget d'équipe ? Quel manager : le manager direct, le chef de département ou la finance ? Si personne ne répond sous deux jours, la demande attend‑elle, expire‑t‑elle ou est‑elle transférée à quelqu'un d'autre ?

C'est pourquoi les règles vagues conduisent à des apps peu fiables. Le·la développeur·se ne peut être régulier·ère que dans la mesure des instructions reçues. Quand la formulation laisse place au guesswork, l'app peut se comporter d'une façon aujourd'hui et d'une autre demain pour un cas légèrement différent.

Les plus gros problèmes apparaissent souvent dans quelques domaines :

• calculs avec détails manquants, comme l'arrondi, les taxes, les remises ou les plages de dates
• exceptions que tout le monde suppose mais que personne n'écrit
• étapes d'approbation sans propriétaire, ordre ou plan de secours clair

Un exemple simple montre le problème. Un·e fondateur·rice construit une application interne de frais dans Koder.ai et écrit : «Rembourser les frais de déplacement sauf s'ils paraissent inhabituels.» Cela paraît raisonnable, mais l'app n'a aucun moyen fiable de juger ce qui est «inhabituel». Une dépense en taxi d'un·e employé·e est approuvée, une autre dépense similaire est signalée, et personne ne sait pourquoi.

Un comportement fiable commence par des règles que l'on peut suivre de la même façon à chaque fois. Des mots comme «important», «urgent» et «cas spécial» doivent être remplacés par des limites, conditions et actions précises. Si deux personnes différentes appliqueraient la règle de la même façon, l'app a beaucoup plus de chances de faire de même.

À quoi ressemble une règle métier claire

Une règle claire couvre une décision ou une action, pas un processus entier. Cela compte plus que ce que la plupart des équipes imaginent. Quand une règle tente de couvrir à la fois approbation, tarification, exceptions et notifications, le·la développeur·se doit deviner quelle partie est prioritaire.

Une bonne règle se lit facilement à voix haute. Quelqu'un hors de votre équipe devrait la comprendre sans votre jargon interne. Remplacez des termes comme «fast‑track», «cas standard» ou «signature du manager» par un langage simple qui dit exactement ce qui se passe.

La plupart des règles claires répondent à quatre questions de base :

• Qui prend la décision ou effectue l'action ?
• Quand la règle s'applique‑t‑elle ?
• Qu'est‑ce qui change dans l'app ?
• Que se passe‑t‑il ensuite ?

Cette structure maintient la règle liée à un comportement concret. Au lieu d'écrire «Les commandes importantes nécessitent une revue», écrivez «Si une commande dépasse 5 000 $, le·la responsable commercial doit l'approuver avant qu'elle puisse être envoyée à la réalisation.» Une phrase, une décision, un résultat.

Il est aussi utile de garder les règles liées séparées. La règle d'approbation doit pouvoir tenir seule. La règle d'envoi d'email doit être séparée. La règle de blocage d'expédition aussi. Cela rend chaque règle plus facile à tester, mettre à jour et corriger.

La différence est facile à voir :

«Les clients Premium reçoivent un traitement prioritaire» est flou.

«Si le client a un plan Premium, la demande de support est marquée Priorité Haute lors de la création du ticket» est clair.

La seconde version nomme le déclencheur, la condition et le changement dans l'app. Elle dit au·à la développeur·se à quoi doit ressembler un comportement fiable.

Si vous utilisez un constructeur basé sur le chat, ce type de formulation fait une grande différence. Les règles claires n'ont pas besoin d'un langage juridique. Elles ont besoin de mots simples, d'une idée à la fois, et d'un résultat attendu qui tienne en une seule phrase.

Rédiger des calculs en langage simple

Les calculs paraissent souvent simples jusqu'à ce que quelqu'un essaie de les construire. L'approche la plus sûre est de commencer par une phrase simple qui dit exactement ce que l'app doit faire.

Une bonne règle ressemble à ceci : «Le montant du remboursement égale les miles approuvés multipliés par le taux au mile.» C'est beaucoup plus clair que «calculer la paie de déplacement» ou «appliquer le remboursement standard.»

Après cette première phrase, définissez chaque entrée que l'app doit utiliser. Soyez suffisamment précis·e pour que le·la développeur·se n'ait pas à deviner.

Ce qu'il faut définir pour chaque calcul

Pour chaque calcul, précisez :

• les entrées, avec des noms simples et des unités
• d'où provient chaque valeur
• les règles d'arrondi
• toute valeur minimale ou maximale
• ce qui se passe si une valeur manque

Les petits détails comptent. «Arrondir le montant final à 2 décimales» donne un résultat différent d'un arrondi par ligne. S'il y a un plafond, dites si l'app doit s'arrêter au plafond ou afficher un avertissement.

Une règle écrite en langage simple pourrait ressembler à ceci : «Le remboursement de déplacement = miles approuvés x 0,67 $. Arrondir le montant final à 2 décimales. Le remboursement maximal est de 300 $ par déplacement. Si les miles approuvés sont vides, ne pas calculer le montant. Marquer la demande comme incomplète et demander à l'utilisateur de saisir les miles.»

Ajoutez ensuite un ou deux exemples chiffrés. Les exemples révèlent les lacunes plus vite que des formules abstraites.

Exemple 1 : «Si les miles approuvés sont 120, le remboursement est 120 x 0,67 $ = 80,40 $. Comme c'est inférieur au plafond de 300 $, le montant final est 80,40 $.»

Exemple 2 : «Si les miles approuvés sont 500, le remboursement est 500 x 0,67 $ = 335,00 $. Comme le maximum est 300 $, le montant final est 300,00 $.»

Ce style est plus facile à relire pour des personnes et plus simple pour un·e développeur·se qui doit transformer la règle en comportement applicatif.

Capturer les exceptions sans confusion

La plupart des apps ne plantent pas sur le chemin normal. Elles plantent sur les cas limites.

Le chemin normal peut être simple, mais le travail réel inclut des remboursements après la date limite, des clients VIP, des documents manquants et des approbations ponctuelles. Si les exceptions sont oubliées, l'app comble le vide elle‑même, et c'est là que commencent les résultats incohérents.

Une façon simple d'écrire les exceptions est d'utiliser de courtes règles if‑then. Gardez chacune focalisée sur une condition et un résultat.

• Si la dépense est inférieure à 100 $, alors auto‑approuver.
• Si la dépense est inférieure à 100 $ mais soumise après 30 jours, alors envoyer en revue manuelle.
• Si l'employé·e fait partie de l'équipe exécutive, alors ignorer la limite de 100 $ et router vers la finance.
• Si un·e admin finance marque la demande comme urgente, alors l'override manuel s'applique et la demande monte en tête de file.

Ce format rend la logique cachée visible. Il aide aussi à repérer les chevauchements avant qu'ils ne deviennent des bugs.

Tout aussi important : dites quelle règle prévaut quand deux règles s'affrontent. Un client peut bénéficier d'une remise, mais la commande peut aussi tomber dans une période de blackout. Écrivez la priorité en langage simple : «Si une règle de blackout pour les jours fériés entre en conflit avec une règle de remise client, la règle de blackout prévaut.»

Soyez précis·e sur les limites. Les dates, types d'utilisateurs, emplacements, statuts de compte et overrides manuels changent souvent l'issue. Au lieu d'écrire «les soumissions tardives nécessitent une approbation», écrivez «Si une demande est soumise plus de 14 jours calendaires après l'événement, alors l'approbation du manager est requise.»

Indiquez aussi ce que l'app doit afficher à l'utilisateur·rice pour chaque exception. Une bonne règle ne s'arrête pas à la décision. Elle définit aussi le message, par exemple «Soumis après 14 jours. Approbation du manager requise» ou «Override manuel appliqué par l'admin finance.»

Quand les exceptions sont écrites de cette façon, les cas inhabituels cessent d'être inhabituels. Ils deviennent des comportements normaux et testables.

Décrire la logique d'approbation pas à pas

La logique d'approbation fonctionne mieux quand elle est écrite comme une séquence de décisions, pas comme une politique vague. Chaque étape doit répondre à cinq questions : qui agit, quel est le déclencheur de leur revue, quelles limites s'appliquent, combien de temps ils ont, et quel statut la demande reçoit après leur décision.

Commencez par nommer le rôle, pas seulement l'équipe. Au lieu d'écrire «la finance révise les demandes importantes», écrivez «Le·la Finance Manager peut approuver, rejeter ou renvoyer toute demande supérieure à 5 000 $.» Cela supprime l'incertitude et facilite la construction.

Définissez ensuite le déclencheur pour chaque étape. Un déclencheur est la condition qui envoie la demande à la personne suivante. Il peut se baser sur le montant, le département, le niveau de risque, le type de demande ou un mélange de ces éléments.

Par exemple :

• Si la demande est inférieure à 500 $, le team lead la révise.
• Si la demande est entre 500 $ et 5 000 $, le manager de département la révise après approbation du team lead.
• Si la demande dépasse 5 000 $, la finance la révise après approbation du manager de département.
• Si la demande est marquée à haut risque, la conformité doit la revoir avant l'approbation finale.

Les seuils doivent avoir des bornes exactes. Ne dites pas «important» ou «sensible». Dites «au‑delà de 5 000 $», «du département Commercial», ou «score de risque 8 ou plus». Si deux seuils peuvent s'appliquer simultanément, dites lequel prime. Par exemple : «Le haut risque va toujours à la conformité, même si le montant est faible.»

Vous avez aussi besoin d'une règle de timeout. Si personne ne répond, l'app ne doit pas rester en limbe indéfiniment. Dites ce qui arrive après un délai défini, comme 48 heures ou 3 jours ouvrés. La demande peut être escaladée vers le manager de l'approbateur, réassignée à un approbateur de secours ou automatiquement annulée.

Enfin, définissez le statut après chaque décision. Gardez les libellés courts et cohérents :

• Approuvé : la demande avance ou est complétée.
• Rejeté : la demande est clôturée et aucune action ultérieure n'est prise.
• Renvoyé : le·la demandeur·e doit modifier et renvoyer.
• Escaladé : la demande passe à un·e approbateur·rice de secours ou supérieur.

Quand la logique d'approbation est écrite de cette façon, le·la développeur·se a moins de place pour deviner et le flux de travail devient beaucoup plus fiable.

Un modèle de règle simple réutilisable

Si vous voulez un comportement cohérent, donnez à chaque règle la même forme. Des styles d'écriture mélangés créent souvent des résultats mélangés.

Un format simple fonctionne pour la plupart des cas : déclencheur, conditions, action, résultat. C'est assez court pour être écrit rapidement et assez clair pour être relu.

Utiliser une règle = une unité

Gardez chaque règle sur sa propre ligne, carte ou bloc. Ne regroupez pas plusieurs idées dans un même paragraphe. Si une règle couvre la tarification, l'approbation et une exception en même temps, elle devient difficile à tester et facile à mal lire.

Un template pratique ressemble à ceci :

Trigger: When [event happens]
Conditions: If [facts must be true]
Action: Then [the app does this]
Result: So [expected outcome]
Assumption: [anything not yet confirmed]
Example: [short sample input and output]

Vous n'avez pas besoin de chaque champ à chaque fois. Mais garder le même ordre aide les gens à parcourir les règles rapidement.

Par exemple :

Trigger: When an employee submits an expense claim
Conditions: If the total is over $500 and no receipt is attached
Action: Then send the claim back for correction
Result: So incomplete claims are not forwarded to a manager
Assumption: Receipt is required for all claims above $500
Example: A $620 taxi claim without a receipt is returned to the employee

Notez que l'exemple se trouve sous la règle, pas dedans. Cela garde la règle propre. L'exemple ne fait que démontrer le comportement attendu.

Indiquez clairement les hypothèses au lieu de les cacher dans la phrase. Une petite note comme «Assumption» ou «Needs confirmation» rend les questions ouvertes faciles à revoir avant la mise en production.

Il aide aussi de garder une formulation cohérente. Commencez toujours les déclencheurs par «When», les conditions par «If» et les actions par «Then». Ces petits schémas réduisent la confusion, surtout quand les règles sont traduites en logique applicative.

Un test rapide est utile : quelqu'un peut‑il tester cette règle, et quelqu'un peut‑il la mal interpréter ? Si la réponse à la première est non, ou à la seconde est oui, resserrez la formulation.

Exemple : une app d'approbation de frais

Une application de remboursement de frais employé est un bon cas de test parce que la politique est familière et les cas limites apparaissent vite. Le personnel peut réclamer des repas, taxis, hôtels et petits frais clients, mais chaque demande a des limites, exceptions et étapes d'approbation. C'est exactement le genre de processus où le langage clair compte.

Politique d'exemple

Rédigez la règle des repas ainsi : les employé·es peuvent réclamer jusqu'à 40 $ par jour pour les repas lors de journées de travail normales. L'app doit totaliser tous les reçus de repas pour une même date et comparer ce total à la limite journalière, pas chaque reçu séparément.

Si l'employé·e dépense 12 $ pour le petit‑déjeuner et 22 $ pour le déjeuner le mardi, le total est 34 $, donc la demande passe. S'il·elle ajoute un dîner à 15 $ le même jour, le total devient 49 $, l'app doit signaler la demande comme dépassant la limite.

Ajoutez maintenant une exception. Si le repas a eu lieu pendant un déplacement professionnel approuvé ou une réunion client, la limite journalière passe à 75 $. Cette exception ne s'applique que lorsque l'employé·e sélectionne Voyage = Oui ou Réunion client = Oui et ajoute une courte note avec le nom du client ou l'objet du déplacement.

C'est plus fiable que des formulations vagues comme «les cas spéciaux peuvent être autorisés» parce que l'exception est liée à des conditions claires.

Étapes d'approbation

La logique d'approbation peut rester tout aussi simple :

• Les demandes inférieures à 100 $ sont approuvées par le manager de l'employé·e.
• Les demandes entre 100 $ et 500 $ nécessitent l'approbation du manager, puis celle de la finance.
• Les demandes supérieures à 500 $ nécessitent l'approbation du manager, de la finance et du chef de département.
• Toute demande marquée «voyage» nécessite aussi une revue par la finance, même si le montant est inférieur à 100 $.

Vous pouvez tester la règle avec quelques cas simples. Une note repas de 36 $ un jour normal doit être approuvée si les reçus sont attachés. Une note de 60 $ en déplacement doit passer si le voyage est marqué et la note remplie. Une note de 60 $ un jour normal doit être rejetée ou renvoyée pour correction. Une réservation d'hôtel à 650 $ doit passer par les trois étapes d'approbation.

C'est l'objectif : la règle doit produire le même résultat à chaque fois que quelqu'un la teste avec des cas réels.

Erreurs courantes qui mènent à de mauvais résultats

Une règle peut sembler claire pour une personne et pourtant embrouiller un·e développeur·se. Cela arrive généralement quand le document est vague, entasse plusieurs idées ou manque de cohérence d'une ligne à l'autre.

Une erreur fréquente est de compresser plusieurs règles dans un long paragraphe. Par exemple : «Les managers approuvent les déplacements sauf si le total est élevé, la finance vérifie les reçus, et les demandes urgentes peuvent éviter la revue.» Cela peut sembler efficace, mais cela cache plusieurs décisions distinctes. Séparez‑les en règles distinctes pour que chaque action ait un déclencheur et un résultat.

Un autre problème est le langage flou. Des mots comme normal, important, urgent ou récent ne fonctionnent que si vous les définissez. Si «dépense importante» signifie plus de 2 000 $, dites‑le. Si «urgent» signifie nécessaire sous 24 heures, écrivez cette condition exacte.

Les données manquantes sont une autre source majeure de mauvais résultats. Les équipes décrivent souvent le chemin heureux et oublient de dire ce qu'il faut faire quand l'information est incomplète ou erronée. Si une demande n'a pas de montant, pas de département ou pas de reçu, la règle doit préciser la suite.

Les erreurs qui posent le plus de problèmes sont généralement :

• combiner plusieurs règles dans un paragraphe
• utiliser des termes non définis pour la taille, le temps ou la priorité
• oublier les cas d'erreur et les champs manquants
• laisser l'autorité d'approbation finale floue
• changer de terme pour désigner la même chose en cours de document

L'autorité finale compte plus que ce que beaucoup d'équipes imaginent. Si un manager et un réviseur finance sont en désaccord, qui tranche ? Si personne ne possède l'étape finale, l'app peut se bloquer ou envoyer le travail en boucle.

Les changements de termes créent des erreurs silencieuses. Si vous commencez par «demande» puis appelez plus loin «soumission» ou «ticket», les lecteurs·rices peuvent penser qu'il s'agit d'objets différents. Choisissez un terme et conservez‑le dans tout le document.

Cela compte encore plus dans un constructeur basé sur le chat, où le langage naturel pilote le comportement. Les règles claires n'ont pas besoin d'être formelles. Elles doivent être spécifiques, cohérentes et complètes.

Liste de contrôle rapide avant de construire

Avant de transformer les exigences en écrans, flux ou invites, faites une dernière relecture. Un court contrôle maintenant peut éviter des heures à corriger des comportements étranges plus tard.

Rendez chaque règle testable. Chaque règle doit se terminer par un résultat clair comme oui ou non, approuver ou rejeter, appliquer des frais ou ne pas appliquer. Si deux personnes peuvent lire la même phrase et donner des réponses différentes, la règle doit être retravaillée.

Énoncez chaque calcul. Nommez les entrées, la formule et le moment du calcul. Ajoutez l'arrondi, la devise, la gestion des dates et ce qui se passe si une valeur est manquante ou égale à zéro.

Séparez les exceptions. Écrivez d'abord la règle par défaut, puis ajoutez les exceptions sur leur propre bloc. La limite principale de dépense ne doit pas être enfouie dans un cas spécial pour des contractuels, des achats urgents ou des voyages pré‑approuvés.

Cartographiez le chemin d'approbation complet. Pour chaque seuil, indiquez qui approuve et ce qui se passe ensuite. Soyez précis·e sur les bords aussi : dites si une règle s'applique au‑delà de 500 $ ou à partir de 500 $ inclus.

Faites ensuite le test du·de la nouveau·elle coéquipier·e. Donnez la règle à quelqu'un qui n'a pas travaillé dessus et demandez‑lui de la reformuler avec ses propres mots. S'il·elle a besoin de contexte supplémentaire, la règle est encore trop vague.

Un petit exemple montre pourquoi cela compte. «Le manager approuve les dépenses importantes» paraît clair jusqu'à ce que quelqu'un demande si 500 $ compte comme important. «Le manager approuve les dépenses supérieures à 500 $. Le directeur approuve les dépenses supérieures à 2 000 $. Les dépenses de 500 $ ou moins sont auto‑approuvées» laisse beaucoup moins de place à l'erreur.

Transformer les règles en une application fonctionnelle

Une fois les règles claires, relisez‑les avec les personnes qui utilisent le processus au quotidien. Managers, coordinateurs, équipes finance et approbateurs·rices remarquent souvent des détails mineurs qui ne figurent pas dans le document. Ces détails sont généralement ce qui rend une app fluide ou frustrante.

Considérez le document de règles comme des instructions de travail, pas comme un brouillon unique. Il doit expliquer ce qui se passe, qui décide, quelles sont les exceptions et ce que l'app fait quand l'information manque.

Avant de construire l'app complète, testez quelques scénarios réels issus du travail récent. Utilisez à la fois des cas propres et des cas désordonnés : une demande standard qui doit passer, une demande avec information manquante, une exception nécessitant une revue manuelle, et un cas qui franchit une limite de dépense ou un seuil d'approbation.

Cette étape révèle les lacunes tôt. Une règle peut sembler claire sur le papier mais se casser quand une demande réelle ne rentre pas dans le schéma attendu.

Quand ces scénarios tiennent la route, importez‑les dans votre constructeur. Si vous utilisez une plateforme basée sur le chat comme Koder.ai, un jeu de règles clair accélère fortement la construction parce que vous traduisez un processus défini en écrans, actions et approbations au lieu de décider au fil de l'eau.

Après le lancement, conservez le document comme source de vérité. Quand une politique change, qu'un·e nouvel·le approbateur·rice est ajouté·e, ou qu'une limite est modifiée, mettez d'abord le document à jour puis l'app. Cela simplifie les modifications futures et réduit le risque que différentes personnes se souviennent différemment de la règle.

Une petite habitude aide : révisez les règles chaque fois que le processus change, pas seulement quand l'app casse. De petites mises à jour faites tôt sont bien plus simples que de réparer un comportement confus plus tard.

Si le document reste à jour, l'app devient plus facile à tester, améliorer et faire confiance au fil du temps.