Le workflow de développement agentique : planifier, exécuter, vérifier

L’autocomplétion et les erreurs collées dans une fenêtre de chat, c’est utile, mais ce n’est pas de la délégation. Les agents de code changent l’unité de travail : tu confies une tâche, et l’agent lit les fichiers, modifie le code, lance des commandes et te fait un compte rendu.

Quand ça marche, c’est comme travailler en binôme avec un junior infatigable. Quand ça ne marche pas, tu ramasses les dégâts de quelqu’un qui a réécrit la moitié de ton codebase avec une confiance totale. La différence, c’est rarement le modèle. C’est le workflow autour.

1. 🧭PlanifierDimensionner la tâche, écrire le brief, réviser le plan de l'agent
2. ↓→
3. ⚙️ExécuterL'agent travaille à l'intérieur des tests, des types et du lint
4. ↓→
5. 🔍VérifierTu vérifies le diff : fichiers, tests, puis code

↺ Commit quand c'est vert, jette sans hésiter, recommence avec la prochaine petite tâche

Le changement de mentalité : de taper à déléguer

Avec l’autocomplétion, tu es l’auteur. Avec un agent, tu te rapproches du rôle de tech lead : tu définis le travail, tu fixes les limites et tu révises le résultat.

🃏 Les trois compétences qui comptent le plus maintenant

Touchez une carte pour la retourner

DécompositionDécouper le travail en morceaux qu'un agent peut terminer et que toi, tu peux vérifier.SpécificationDire ce que « terminé » veut dire avant que quiconque écrive du code.RevueLire un diff rapidement et repérer ce qui cloche.

Étape 0 : bien dimensionner la tâche

La taille de la tâche, c’est le meilleur indicateur de succès que je vois. Trop petite, et le brief ne vaut pas la peine : tape le code toi-même. Trop grosse, et l’agent perd le fil et te livre un diff de 40 fichiers impossible à réviser.

✅ Une tâche est bien dimensionnée quand…

0 / 4 complété

• Tu peux décrire l'objectif en deux ou trois phrases.
• Tu peux dire comment tu vas savoir que c'est fini (un test passe, un endpoint retourne X, une page affiche Y).
• Le diff se révise d'un coup, à peu près la taille d'une pull request normale dans ton équipe.
• Elle touche une seule zone du codebase, ou un petit ensemble de zones connues.

↺ Réinitialiser

🎮 Déléguer ou garder?

1 / 9 · Pointage: 0

Confierais-tu ça à un agent comme une seule tâche?

Bonne tâche d'agentGarder / découper d'abord

Suivant →

/ 9

↺ Recommencer

Si une tâche est trop grosse, ne la confie pas telle quelle. Demande à l’agent de t’aider à la découper, puis délègue les morceaux un à la fois.

Étape 1 : écrire un vrai brief de tâche

Un prompt d’une ligne suffit pour les changements triviaux. Pour le reste, un court brief prend deux minutes et en sauve vingt.

1. 1

   Objectif

   Ce qui doit être vrai quand la tâche est finie, et pourquoi.

2. 2

   Contraintes

   Ce que l'agent ne doit pas faire ou doit respecter : aucune nouvelle dépendance, ne pas changer l'API publique, suivre le pattern du fichier X.

3. 3

   Critères d'acceptation

   Des conditions concrètes et vérifiables. Idéalement, des commandes qui passent.

4. 4

   Fichiers pertinents

   Où commencer à chercher, pour que l'agent n'erre pas.

Un brief pour une petite fonctionnalité :

## Objectif
Ajouter une pagination par curseur à GET /api/orders. L'app mobile
charge présentement toutes les commandes d'un coup et expire pour les
gros comptes.

## Contraintes
- Garder la forme de réponse existante; ajouter `nextCursor` au premier niveau.
- Aucune nouvelle dépendance.
- Suivre le pattern de pagination déjà utilisé dans `src/api/invoices.ts`.
- Ne pas modifier le schéma de la base de données.

## Critères d'acceptation
- Paramètre `limit`, par défaut 50, max 200.
- Paramètre `cursor` qui retourne la page suivante, triée par createdAt desc.
- Nouveaux tests dans `tests/api/orders.test.ts` qui couvrent : première page,
  page suivante, dernière page (nextCursor null), curseur invalide (400).
- `npm test` et `npm run typecheck` passent.

## Fichiers pertinents
- src/api/orders.ts
- src/api/invoices.ts (pattern de référence)
- src/db/queries/orders.ts

Remarque la raison (pour que l’agent fasse des arbitrages sensés), le pattern de référence (pour qu’il n’en invente pas un) et une définition de « terminé » qu’une machine peut vérifier.

Un brief pour une correction de bug :

## Objectif
Corriger : les utilisateurs avec une apostrophe dans leur nom de famille
(ex. O'Brien) reçoivent une erreur 500 en modifiant leur profil.

## Reproduction
1. Créer un utilisateur avec le nom de famille « O'Brien ».
2. PATCH /api/profile avec n'importe quel changement.
3. Les logs du serveur montrent une erreur de requête dans updateProfile.

## Contraintes
- Corriger la cause racine, pas le symptôme. Pas de bricolage d'échappement.
- Ne pas toucher aux requêtes non reliées, même si elles se ressemblent.
  Liste-les plutôt dans ton résumé et je déciderai.

## Critères d'acceptation
- Écrire D'ABORD un test qui échoue et reproduit le bug; montre-moi qu'il échoue.
- Ensuite, corriger et montrer le test qui passe.
- Toute la suite de tests passe.

## Fichiers pertinents
- src/services/profile.ts
- src/db/queries/users.ts

🧠 Teste tes briefs

Pointage: 0 / 4

1. 1. Quel critère d'acceptation est le plus utile pour un agent?

   Que ça marche biennpm test et npm run typecheck passent, avec de nouveaux tests pour le cas du curseur invalideSuivre les bonnes pratiques

   Une condition vérifiable par une machine permet à l'agent de valider son propre travail.

2. 2. Pourquoi inclure un fichier de référence comme src/api/invoices.ts?

   Pour donner plus de lecture à l'agentPour qu'il suive un pattern existant au lieu d'en inventer unLa plupart des agents l'exigent

   Pointer vers le pattern prévient la structure inventée.

3. 3. Pourquoi donner la raison derrière l'objectif (« l'app mobile expire »)?

   Par politesseÇa aide l'agent à faire des arbitrages sensésÇa allonge le brief

4. 4. Dans un brief de correction de bug, qu'est-ce qui vient avant le correctif?

   Un refactor du code voisinUn test qui échoue et reproduit le bugLa mise à jour des dépendances

   Le test qui échoue prouve le bug et devient la spec du correctif.

↺ Recommencer

Étape 2 : donner le contexte du repo une seule fois

Tu ne devrais pas répéter « on utilise pnpm, pas npm » dans chaque brief. La plupart des agents chargent un fichier d’instructions à la racine du repo, souvent nommé quelque chose comme AGENTS.md ou CLAUDE.md. Vérifie dans la doc de ton outil le nom exact qu’il lit.

Traite ce fichier comme du code : révise les changements, garde-le à jour, supprime les lignes mortes. Si l’agent répète la même erreur, ajoute une ligne ici plutôt que de te répéter dans chaque prompt.

Étape 3 : planifier d’abord, puis réviser le plan

Pour tout ce qui dépasse le trivial, demande un plan avant les modifications. Plusieurs agents ont un mode plan ou lecture seule; sinon, dis « Ne modifie aucun fichier pour l’instant. Lis le code pertinent et propose un plan. »

Un plan utile liste les fichiers qui vont changer et pourquoi, l’approche en quelques étapes, les suppositions et la façon de vérifier le changement. Le lire, c’est la revue la moins chère que tu feras jamais : attraper « je vais ajouter une nouvelle librairie de cache » ici coûte une phrase, pas une réécriture.

🃏 Drapeaux rouges dans un plan

Touchez une carte pour la retourner

Dérive de portéeDes fichiers qui ne devraient pas être touchés pour cette tâche.Structure inventéeDe nouvelles abstractions, helpers ou couches alors qu'un existant ferait l'affaire.Mauvaises suppositions« Je vais supposer que l'ID utilisateur est un nombre » alors que c'est un UUID.Vérification absenteAucune mention de tests, ou des tests qui ne couvrent que le cas nominal.

Corrige le plan en langage clair; deux rondes, c’est normal. À la quatrième, la tâche est trop floue ou trop grosse : réécris le brief. La planification sert aussi à découper : « Propose une séquence de petites étapes fusionnables indépendamment pour aller d’ici à X. »

Étape 4 : exécuter dans une boucle de rétroaction serrée

Un agent sans vérificateur devine. Avec une suite de tests rapide, un typechecker et un linter, il voit ses propres erreurs et les corrige avant que tu regardes.

✅ Mise en place de la boucle de rétroaction

0 / 4 complété

• Les commandes de test, typecheck et lint sont dans le fichier d'instructions et fonctionnent sur un checkout propre.
• Elles sont rapides, ou tu as documenté comment lancer un seul fichier ou un sous-ensemble.
• Le brief dit à l'agent de les lancer avant d'annoncer que c'est fini.
• La sortie est lisible : les avertissements bruyants n'enterrent pas la vraie erreur.

↺ Réinitialiser

Le TDD fonctionne étonnamment bien avec les agents

1. RougeL'agent écrit un test qui échoue pour le comportement voulu
2. ↓→
3. RevueTu révises le test : c'est la spec
4. ↓→
5. VertL'agent le fait passer sans modifier le test
6. ↓→
7. RefactorL'agent nettoie avec les tests au vert

Une règle sur laquelle je suis strict : l’agent n’a pas le droit de modifier un test pour le faire passer, sauf si on s’est entendu que le test était faux. Écris-le dans le brief.

Étape 5 : de petits commits, et git comme bouton d’annulation

Les agents font beaucoup de changements très vite. C’est git qui rend ça sécuritaire.

Le code était peu coûteux à générer; ton attention, elle, ne l’est pas. Savoir jeter du travail, c’est une vraie compétence.

Étape 6 : faire rouler des agents en parallèle, prudemment

Deux ou trois agents sur des tâches indépendantes, c’est un vrai bond de productivité. La clé, c’est l’isolation : deux agents dans le même répertoire de travail vont se marcher sur les pieds.

Options d’isolation : des git worktrees séparés (chaque agent a son propre répertoire et sa branche sur le même repo; mon choix par défaut), des clones séparés si tes outils n’aiment pas les worktrees, ou des agents distants ou en sandbox si ton outil en offre.

Étape 7 : réviser les diffs d’agent efficacement

Le travail d’un agent doit être révisé, point. Le truc, c’est de le faire plus vite que d’écrire le code toi-même.

1. 1

   Lire le résumé sans rien croire encore

   « Tous les tests passent », c'est une affirmation, pas un fait.

2. 2

   Lancer les vérifications

   Tests, typecheck, lint, toi-même ou via la CI.

3. 3

   Parcourir la liste de fichiers

   Tout fichier qui n'est pas évidemment lié à la tâche est un drapeau rouge. Commence par là.

4. 4

   Lire les tests avant l'implémentation

   Affirment-ils quelque chose de significatif? Échoueraient-ils si la fonctionnalité brisait?

5. 5

   Lire l'implémentation

   Cherche les modes d'échec ci-dessous, pas le style. Les formateurs s'occupent du style.

6. 6

   Vérifier ce qui manque

   Gestion d'erreurs, cas limites des critères d'acceptation, docs ou types à mettre à jour.

Un diff trop gros pour être révisé confortablement, c’est un signal sur la taille de la tâche, pas une raison de survoler. Rejette-le et découpe la tâche.

Les modes d’échec courants et comment les attraper

Les patterns que je vois le plus, dans mon propre travail et avec les équipes que j’accompagne. Retourne chaque carte pour voir comment les attraper et les prévenir.

🃏 Modes d'échec des agents

Touchez une carte pour la retourner

Dérive de contexteDans les longues sessions, les contraintes du début sont ignorées. Attraper : règles violées tard. Prévenir : une tâche par session; règles durables dans le fichier d'instructions.Modifications qui débordentTu voulais un correctif, tu reçois un « ménage » dans 12 fichiers. Attraper : la liste de fichiers. Prévenir : « change seulement le nécessaire; liste le reste ».Tests faussement vertsAssertions affaiblies, tests sautés, mock de ce qu'on teste, cas spéciaux pour les entrées de test. Prévenir : aucune modif de test sans accord; réviser les tests d'abord.API hallucinéesDes méthodes ou options plausibles qui n'existent pas. Attraper : types et tests. Prévenir : pointer l'agent vers le code ou la doc de la version installée.Résumés faux mais confiants« Fini, tous les tests passent » sans les avoir lancés. Attraper : vérifier soi-même. Prévenir : exiger les commandes exactes et leur sortie.Tourner en rondCorrectif, échec, variante, échec encore. Attraper : la même erreur trois fois. C'est ton signal pour reprendre le volant.

Quand reprendre le volant

Déléguer, ce n’est pas abdiquer.

✅ Interviens quand…

0 / 5 complété

• L'agent a échoué de la même façon trois fois. Il lui manque de l'information ou l'approche est mauvaise.
• Le problème demande un jugement que l'agent n'a pas : décisions produit, arbitrages d'affaires, sécurité ou argent.
• Tu ne comprends pas le code qu'il a écrit. Si tu ne peux pas expliquer le diff, ne le fusionne pas.
• Ce serait plus rapide de le taper toi-même.
• Le domaine t'est peu familier. Utilise l'agent pour expliquer et explorer; écris ou supervise de près le code toi-même.

↺ Réinitialiser

Reprendre le volant peut être partiel : règle toi-même la partie délicate, commite-la et redonne le reste.

## Objectif
J'ai implémenté la nouvelle logique de retry dans src/jobs/retry.ts (voir
le dernier commit). Applique le même pattern aux trois autres handlers de jobs.

## Contraintes
- Reproduire l'implémentation de retry.ts exactement; ne pas l'« améliorer ».
- Un commit par handler.
- Si un handler ne cadre pas proprement avec le pattern, arrête-toi et
  dis-le-moi au lieu de l'adapter.

## Critères d'acceptation
- src/jobs/email.ts, src/jobs/export.ts, src/jobs/sync.ts utilisent withRetry.
- Les tests existants de chaque handler passent encore.
- Un nouveau test par handler pour le cas « échec, retry, puis succès ».

## Fichiers pertinents
- src/jobs/retry.ts (référence)
- tests/jobs/retry.test.ts (test de référence)

Tout mettre ensemble

1. 1

   Dimensionner

   Pour que le diff soit révisable.

2. 2

   Écrire le brief

   Objectif, contraintes, critères d'acceptation, fichiers pertinents.

3. 3

   Planifier

   Et réviser le plan avant tout code.

4. 4

   Exécuter

   Avec les tests, les types et le lint comme vérificateur.

5. 5

   Commiter

   À chaque point vert; jeter sans hésiter.

6. 6

   Réviser

   Liste de fichiers, tests, puis implémentation.

7. 7

   Reprendre le volant

   Quand l'agent tourne en rond ou qu'il faut du jugement.

Rien d’exotique là-dedans. C’est déjà comme ça que les bonnes équipes délèguent à des humains; les agents font juste apparaître plus vite les étapes sautées.

Essaie ça sur ta prochaine tâche

✅ Ton premier cycle planifier-exécuter-vérifier

0 / 9 complété

• Choisis une tâche qui donnerait une pull request de taille normale.
• Assure-toi que ton repo a un fichier d'instructions avec les commandes exactes de test, typecheck et lint.
• Écris un brief avec objectif, contraintes, critères d'acceptation et fichiers pertinents.
• Demande un plan d'abord. Lis-le et corrige au moins une chose avant d'approuver.
• Exige que l'agent lance les vérifications et colle les commandes qu'il a lancées.
• Pars d'un working tree propre sur une nouvelle branche.
• Révise la liste de fichiers d'abord, puis les tests, puis l'implémentation.
• S'il échoue de la même façon trois fois, arrête et réécris le brief.
• Après coup, ajoute une ligne à ton fichier d'instructions selon ce qui a mal tourné.

↺ Réinitialiser