Workflow agentique : les principes fondateurs

Après Cursor IDE, après GitHub Copilot, après une première vague d’outils qui “suggéraient du code”, on est entrés dans quelque chose de différent. Les agents de coding ne suggèrent plus — ils exécutent, lisent des fichiers, lancent des tests, committent du code. Le changement n’est pas de degré, il est de nature.

Ce guide documente les principes qui font qu’un workflow agentique fonctionne réellement en production — pas les demos YouTube, pas les benchmarks en chambre. Ce qui marche sur un projet Symfony de 80k lignes au quotidien.

Qu’est-ce qui change vraiment avec les agents ?

L’erreur la plus commune est de traiter un agent IA comme un moteur d’autocomplétion amélioré. On lui demande une fonction, il la génère, on copie-colle.

Ce qui change avec les agents, c’est la granularité de délégation. On ne délègue plus une ligne ou un bloc — on délègue une intention avec un périmètre défini :

“Refactorise le service OrderRepository pour extraire la logique de calcul des remises dans un DiscountCalculator dédié. Les tests existants doivent passer. Crée les tests manquants pour les cas edge identifiés dans les commentaires TODO.”

L’agent lit les fichiers, comprend le contexte, écrit le code, lance les tests, corrige les erreurs, et présente le résultat. En une session de 20 minutes, on obtient ce qui prenait 2 heures — avec les tests.

Le gain n’est pas “l’IA écrit le code à ma place”. Le gain est le changement de niveau d’abstraction auquel on travaille.

Comment décomposer une tâche pour un agent ?

La décomposition est la compétence centrale d’un workflow agentique. Un agent mal briefé produit du code qui compile mais ne fait pas ce qu’on voulait. Un agent bien briefé produit exactement ce qu’on lui a demandé — ce qui révèle souvent que ce qu’on lui a demandé n’était pas ce qu’on voulait.

Principe 1 : une session = un livrable vérifiable

Chaque session doit se terminer par quelque chose qu’on peut valider objectivement : les tests passent, la PR est lisible, le bug est reproduit puis corrigé. Si on ne peut pas définir la condition de sortie, la tâche est trop grande.

❌ "Améliore le service de paiement"
✅ "Ajoute la gestion du cas où le paiement est refusé par l'API Stripe (code 402) 
    avec retry automatique × 2, log d'erreur, et notification dans l'admin. 
    Les tests unitaires doivent couvrir les 3 cas : succès, refus, timeout."

Principe 2 : le contexte minimum viable

Charger toute la codebase dans le contexte est contre-productif. Plus le contexte est grand, plus le context rot est rapide. La bonne pratique est de ne charger que les fichiers directement liés à la tâche, et d’utiliser des fichiers de contexte persistants (CLAUDE.md, AGENTS.md) pour les informations structurelles du projet.

# OpenCode — charger seulement les fichiers pertinents
> /add src/Service/OrderService.php src/Repository/OrderRepository.php
> /add tests/Service/OrderServiceTest.php

Principe 3 : les instructions de contrainte

Dire à l’agent ce qu’il ne doit pas faire est aussi important que lui dire quoi faire. Sans contrainte, l’agent optimise pour “faire quelque chose qui ressemble à une solution” plutôt que “respecter les conventions du projet”.

"Ne modifie pas l'interface publique du service. 
 Utilise les helpers d'assertion existants dans AbstractServiceTest. 
 Respecte la convention de nommage : les tests unitaires se terminent en Test.php."

Comment gérer le contexte sur la durée ?

Le context window d’un LLM est une ressource finie qui se dégrade. À mesure qu’une session s’allonge, les premières instructions perdent de leur influence sur les décisions de l’agent. C’est le context rot — et c’est le problème n°1 des workflows agentiques en production.

Couper les sessions au bon moment

La règle empirique : couper une session après 3-4 fichiers modifiés ou quand la tâche initiale est terminée. Pas de session “fourre-tout” qui enchaîne les sujets.

Fichiers de contexte persistants

Un fichier CLAUDE.md ou AGENTS.md à la racine du projet est lu automatiquement par la plupart des agents. Il doit contenir ce que l’agent a besoin de savoir sur le projet pour travailler correctement, pas l’histoire du projet :

# Conventions de ce projet

- PHP 8.3 + Symfony 7.1 + API Platform 3.x
- Tests : PHPUnit 11, namespacing App\Tests\[Domain]
- Les repositories héritent de AbstractRepository, pas directement de Doctrine
- Environnement de test : DATABASE_URL_TEST dans .env.test.local
- Pour les migrations : `php bin/console doctrine:migrations:diff` puis review manuelle

Ce fichier est la mémoire permanente de l’agent sur ton projet. Il compense le fait que le LLM n’a pas de mémoire entre les sessions.

Multi-session avec handoff

Pour les tâches longues, on structure en sessions avec des checkpoints explicites :

Session 1 : "Analyse le service X et produit un plan de refactoring dans REFACTOR_PLAN.md"
Session 2 : "Implémenter les étapes 1 et 2 du plan dans REFACTOR_PLAN.md"
Session 3 : "Implémenter les étapes 3 et 4, vérifier que tous les tests passent"

Le fichier de plan est à la fois le livrable d’une session et le contexte de la suivante.

Quels sont les anti-patterns à éviter ?

L’agent comme oracle

Demander à l’agent “quelle est la meilleure architecture pour X” et appliquer sa réponse sans réfléchir. L’agent optimise pour la cohérence de sa réponse, pas pour ton contexte métier. Il est bon pour implémenter des décisions, pas pour les prendre à ta place.

Le yolo commit

Merger directement le code de l’agent sans review. Même avec les meilleurs prompts, l’agent peut introduire des bugs subtils, des conventions non respectées, ou des optimisations prématurées. La review humaine n’est pas optionnelle — elle est l’endroit où se passe la vraie ingénierie.

Le contexte infini

Passer toute la codebase en contexte “pour que l’agent comprenne mieux”. En pratique, ça dilue les instructions et accélère le context rot. Contexte focalisé = meilleurs résultats.

Les instructions ambiguës

“Améliore les performances” ou “nettoie le code”. Sans critère de succès défini, l’agent invente son propre critère — qui ne correspond généralement pas au tien.

Ce que ça change concrètement dans un workflow

Après plusieurs mois d’usage quotidien sur un projet Symfony/TypeScript en production, voici les changements durables :

La granularité des tâches a diminué. On découpe plus finement, ce qui réduit le risque de chaque changement et accélère les revues. Des PRs de 500 lignes sont devenues des PRs de 50-100 lignes avec un périmètre clair.

Le temps passé sur la “plomberie” a chuté. Tests boilerplate, migrations de schéma, documentation d’API, ajout de validation — tout ce qui est mécanique et prévisible est délégué. L’attention se concentre sur la logique métier et les décisions d’architecture.

La documentation est meilleure. Quand on brief l’agent, on est forcé d’articuler ce qu’on veut précisément. Ces briefs deviennent souvent la base de la documentation de la tâche.

Le feedback loop est plus court. Avec un agent qui exécute les tests en temps réel, on sait si quelque chose est cassé en 2 minutes plutôt qu’en 20. Ça encourage les petits commits vérifiables.

Ressources & références

• OpenCode — agent terminal-first, MIT, multi-provider
• Anthropic : building effective agents — référence sur les patterns d’agents en production
• Model Context Protocol — standard d’extension des agents via des serveurs d’outils
• Guide : Gérer le contexte dans des workflows multi-agents
• Guide : Prompt engineering pour les agents de coding