Rédigez un brief de tâche pour un agent

Décrivez une modification évaluable

« Ajouter un export des clients » laisse plusieurs décisions ouvertes. Qui peut exporter les enregistrements ? Quels enregistrements et champs sont inclus ? Que se passe-t-il si une requête échoue ? Un agent peut combler ces lacunes par des choix plausibles. Ces choix peuvent pourtant être inadaptés au métier.

Commencez par l’utilisateur et le problème. Décrivez ensuite le comportement attendu. Incluez les preuves qui montreront si le résultat est acceptable.

Le brief doit réduire l’incertitude sans figer chaque choix interne de conception. Précisez une limite de données obligatoire. Laissez l’implémentation suivre les conventions existantes du dépôt, sauf raison de les changer.

Utilisez un exemple concret

Le brief suivant concerne une application de support fictive. C’est un exemple pédagogique, pas une spécification complète pour la production.

Résultat : Un responsable du support peut télécharger une liste de clients.
Acteur : Un manager de l’organisation courante.
Données : Uniquement les clients actifs de cette organisation.
Champs : ID du client, nom de l’entreprise et statut du compte.
Format : CSV UTF-8 avec une ligne d’en-tête.
Requête refusée : Renvoyer l’erreur d’autorisation existante.
Résultat vide : Renvoyer un CSV valide contenant uniquement l’en-tête.
Périmètre : Utiliser la route d’export et le mécanisme d’audit existants.
Exclusions : Aucun nouveau rôle, aucune dépendance ni aucun déploiement.
Preuves : Tests des requêtes autorisées, refusées, vides et interorganisations.

Ce brief décrit un comportement utile et ses limites. Il fait aussi apparaître d’autres questions. Le système doit-il limiter la taille de l’export ? Un champ peut-il contenir une formule de tableur ? Qui peut accéder à la trace d’audit ? Résolvez les questions importantes avant l’implémentation. Ne traitez pas cet exemple comme une checklist universelle.

Distinguez les exigences des hypothèses

Une exigence définit un comportement que la modification doit respecter. Une hypothèse est un fait non encore vérifié. Gardez cette distinction.

Par exemple, « utilisez le mécanisme d’audit existant » suppose qu’un mécanisme adapté existe. Demandez à l’agent de le trouver. S’il n’y en a pas dans le dépôt, l’agent doit signaler ce prérequis manquant avant d’inventer un nouveau système d’audit.

Une contrainte peut aussi contredire le résultat recherché. La route existante peut avoir été conçue pour renvoyer toutes les organisations. L’agent doit montrer le conflit et proposer une correction limitée. Il ne doit ni supprimer discrètement la limite de données ni transformer la tâche en refonte d’architecture.

Incluez les preuves dans la condition de fin

Demandez un compte rendu qui explique le comportement final, les changements de périmètre et les contrôles effectués. Exigez les commandes et les résultats exacts lorsqu’ils sont pertinents. Distinguez un contrôle réussi d’un contrôle qui n’a pas pu s’exécuter.

La pull request doit conserver la raison de la modification. Une personne chargée de la maintenance pourra voir le code sans la conversation initiale. Donnez assez de contexte pour expliquer les champs exclus de l’export et la manière dont les accès sont contrôlés.

Les recommandations de Google sur les descriptions de modifications constituent une référence utile. La description doit expliquer la modification et son objectif. Après les corrections issues de la revue, gardez-la conforme à l’implémentation finale.

Adaptez le brief à la tâche

Une petite correction de texte peut avoir un brief court. Un export de données demande davantage de détails, car ses défaillances peuvent divulguer des informations. Un nouveau processus de paiement exige encore plus d’analyse et de revue.

Ne mesurez pas la qualité du brief à sa longueur. Demandez-vous si une personne compétente pourrait distinguer un résultat correct d’un résultat incorrect. Si deux implémentations raisonnables divergent sur un comportement aux conséquences importantes, clarifiez d’abord ce comportement.