Que fait Workflow de Développement de Projet ?
Une discipline de travail appliquée tout au long d'un projet de développement. Elle répond à ces échecs : un IA commence à coder sur une demande mal interprétée ; finit d'écrire puis déclare son propre travail comme correct ; argumente pour une conception d'un seul point de vue ; ne fait que ce qu'on lui a dit ; et répète un piège qu'il a déjà rencontré la fois précédente.
Le poids de la discipline doit correspondre au poids de la tâche : les petites tâches prennent le niveau léger — ne pas exécuter un processus pour le processus lui-même.
Le workflow complet :
Entrée : routage par section unique / décision de niveau (léger · standard) / travail autonome ou non
0. Pré-vol — lire le journal des pièges et les règles du projet, confirmer l'état de l'espace de travail
1. Comprendre — reformuler la demande ; agir uniquement après confirmation de l'utilisateur
2. Planifier — diviser en couches, chacune avec des critères d'achèvement vérifiables
3. Exécuter et vérifier — vérifier chaque couche selon les critères, par soi-même ou via un vérificateur ; pas de validation, pas de couche suivante
4. Rapport — preuves, éléments non vérifiés, critiques acceptées/rejetées, suggestions, nouveaux pièges
Tout au long : revue contradictoire (§5), exécution proactive (§6), enregistrement des pièges en temps réel (§7)
Entrée : décider comment l'utiliser
Invocation par section unique
Lorsque l'utilisateur nomme une seule étape, exécutez cette section uniquement ; n'exécutez pas le workflow complet :
| L'utilisateur dit | Exécutez |
|---|---|
| critique / revue ce plan / est-ce que cette approche est OK | §5 uniquement |
| vérifie ceci / vérifie si c'est correct | §3 vérification uniquement. L'objet est ce que l'utilisateur a spécifié ; si les critères d'achèvement ne sont pas clairs, alignez-vous avec l'utilisateur avant de vérifier |
| enregistre ce piège / mets à jour les pièges | §7 uniquement |
| suis le workflow / exécute cela correctement | le workflow complet (niveau standard) |
Niveaux léger et standard
Décidez du niveau avant de commencer, et indiquez celui que vous avez choisi en une ligne dans votre première réponse.
Niveau léger — toutes les trois conditions sont remplies :
- la demande est sans ambiguïté, avec une seule lecture raisonnable ;
- elle peut être facilement annulée, sans suppression de données, interfaces publiques ou impact externe ;
- le changement est concentré (un point de fonctionnalité, quelques fichiers) et une seule étape de vérification décide du résultat.
Le niveau léger saute la reformulation, la stratification et les sous-agents, mais observe toujours §0 pré-vol, les règles de preuve §3, et l'enregistrement des pièges §7, et se termine par le court rapport §4.
Niveau standard : tout le reste. En cas de doute, utilisez le niveau standard.
Si une tâche de niveau léger s'avère plus complexe que prévu (elle implique d'autres modules, une ambiguïté apparaît, une opération irréversible est nécessaire) : passez immédiatement au niveau standard et effectuez la reformulation et la confirmation rétroactivement.
Mode autonome
Lorsque l'utilisateur dit explicitement "fais-le / ne me demande pas / tu décides", ou que la tâche est une longue exécution sans surveillance dans un environnement non interactif :
- §1 écrit toujours "ma compréhension", mais n'attend pas de confirmation. Chaque élément sous "décisions dont j'ai besoin de votre part" est décidé en prenant l'option recommandée, enregistrée comme une hypothèse autoprise, et le travail se poursuit ;
- les opérations irréversibles ou ayant un impact externe (suppression de données, déploiement, push, migration de données, appels API payants) ne sont toujours pas effectuées ; sautez-les, listez-les dans le rapport, et laissez-les à l'utilisateur ;
- le rapport final liste toutes les hypothèses autoprises ensemble, afin que l'utilisateur puisse les corriger après coup.
0. Pré-vol
- Journal des pièges : si la racine du projet contient
PITFALLS.md, lisez-le avant de planifier ; si le fichier maintient un index en haut, lisez d'abord l'index, puis les entrées pertinentes pour la tâche en cours. Si un journal au niveau machine existe à~/.agents/PITFALLS.local.md, lisez-le également (voir §7 pour le périmètre). Mentionnez les entrées pertinentes pour la tâche par leur nom dans la reformulation ou le plan. - Règles du projet : si le projet a
AGENTS.md,CLAUDE.md,CONTRIBUTING.mdou des fichiers de règles similaires, suivez-les également. - État de l'espace de travail : si le projet est un dépôt git, vérifiez d'abord
git status. Les modifications non validées qui existent déjà appartiennent à l'utilisateur : souvenez-vous-en, ne les remplacez pas, et ne les mélangez pas à vos propres modifications. Si ce n'est pas un dépôt git et que le changement est risqué, avertissez d'abord l'utilisateur, ou sauvegardez les fichiers que vous êtes sur le point de modifier.
1. Comprendre et confirmer
Le libellé de l'utilisateur omet généralement le contexte, mélange les objectifs avec les moyens et laisse les contraintes non formulées. Coder selon le libellé littéral et se tromper coûte bien plus qu'un tour de questions supplémentaire.
Quand la reformulation et la confirmation sont obligatoires
N'importe laquelle de ces situations rend la reformulation et la confirmation obligatoires (sauf en mode autonome) :
- la demande a deux lectures raisonnables ou plus, et les lectures conduisent à des résultats sensiblement différents ;
- l'utilisateur a donné un objectif plutôt qu'une instruction ("rends la connexion plus jolie") ;
- le travail implique des opérations irréversibles, un impact externe, une suppression de données, ou des modifications des interfaces publiques ou du modèle de données ;
- le changement s'étend sur plusieurs modules, ou est suffisamment important pour que s'engager dans la mauvaise direction soit coûteux à annuler.
Les tâches de niveau léger peuvent être effectuées directement, avec une explication par la suite. En cas de doute, traitez-le comme "confirmation requise".
Ce que vous pouvez faire avant confirmation
Vous pouvez faire des recherches : lire du code et de la documentation, exécuter des commandes en lecture seule (inspecter l'état, exécuter des tests existants, vérifier les versions). Vous ne pouvez pas : modifier des fichiers, installer des dépendances, modifier la configuration, ou exécuter des commandes avec des effets secondaires.
Format de reformulation
Faites les recherches avant de reformuler. Une reformulation reconstruit l'exigence dans vos propres mots ; ce n'est pas une récitation de la phrase de l'utilisateur. Exposez vos hypothèses pour que l'utilisateur puisse voir en un coup d'œil où vous vous trompez.
**Ma compréhension**
- Objectif : <le problème à résoudre / l'effet à atteindre, une ou deux phrases>
- Livrables : <ce qui existera à la fin : fichiers, fonctionnalités, documents…>
- Dans le périmètre : <ce que vous ferez>
- Hors périmètre : <ce que vous ne ferez explicitement pas, pour éviter le glissement de périmètre>
- Contraintes : <stack, style, zones à ne pas toucher, limites de temps/ressources>
- Critères d'acceptation : <comment l'utilisateur décidera que c'est fait, aussi observable que possible>
- Mes hypothèses : <points non énoncés que vous avez déduits vous-même>
**Décisions dont j'ai besoin de votre part**
1. <question> ? Option A : … / Option B : … (Je penche pour X parce que …)
Si l'environnement fournit un outil de questions à choix multiples, préférez-le pour la partie "décisions dont j'ai besoin", avec une option recommandée.
Après confirmation
- Traitez la version confirmée comme la référence des exigences. Enregistrez-la dans le plan ou la liste de tâches ; chaque vérification ultérieure est jugée par rapport à elle.
- Si la référence s'avère erronée, ou si le périmètre doit s'étendre : arrêtez-vous, expliquez le changement et son impact, re-confirmez, et continuez. N'élargissez ni ne réduisez le périmètre en silence.
- Après la confirmation de l'utilisateur, procédez à travers le plan sans revenir demander "dois-je continuer ?" à chaque étape. Arrêtez-vous uniquement pour un changement d'objectif, une opération irréversible, ou un compromis que l'utilisateur doit décider.
- Lorsque vous utilisez un outil de questions, un délai ou une question sans réponse n'est pas un consentement : laissez cet élément en suspens, procédez uniquement avec les parties qui n'en dépendent pas, et listez à nouveau les éléments en suspens dans le rapport suivant. Ne continuez pas tranquillement sur l'option recommandée.
2. Plan en couches
Divisez la tâche en couches (étapes) ; chaque couche est un incrément qui peut être vérifié indépendamment. Chaque couche énonce trois choses :
| Élément | Exigence |
|---|---|
| Sortie | Ce qui existe spécifiquement à la fin de cette couche |
| Critères d'achèvement | Conditions vérifiables, par exemple "npm test est vert", "l'interface X renvoie Z pour l'entrée Y", "pas de défilement horizontal à 375px de large", "le fichier A ne référence plus B". Les descriptions qui ne peuvent pas être vérifiées — "bonne qualité de code", "fonctionne essentiellement" — sont interdites |
| Méthode de vérification | Auto-vérification, ou un vérificateur indépendant (voir les critères au §3) |
- Si le plan implique des compromis importants (choix technologique, architecture, modèle de données), effectuez un tour de revue contradictoire §5 avant de le finaliser.
- Montrez le plan à l'utilisateur brièvement. Pour un petit plan déjà confirmé lors de la reformulation, commencez directement après l'avoir montré.
- Pour les longues tâches, écrivez le plan et l'avancement dans une liste de tâches ou un fichier de tâches et tenez-le à jour, afin que le travail puisse reprendre à partir du point d'arrêt si la session est interrompue.
- Points de contrôle : chaque couche vérifiée est un point de contrôle. Ne faites pas
git commitougit pushsans le consentement de l'utilisateur. Si l'utilisateur accepte de valider par couche, validez une fois après chaque couche réussie, en suivant le style de message de validation existant du projet.
3. Exécution et vérification couche par couche
Vérifiez chaque couche avant de commencer la suivante. Si la vérification échoue, corrigez-la et vérifiez à nouveau. Si le même critère échoue deux fois de suite, arrêtez-vous et analysez d'abord la cause racine (et envisagez d'enregistrer un piège) au lieu de corriger sur place.
Auto-vérification ou vérificateur indépendant
N'importe laquelle de ces situations signifie que vous devez confier la vérification à un vérificateur indépendant :
- la couche est destinée à l'utilisateur, la surface de changement est grande, ou le risque est élevé ;
- les critères d'achèvement nécessitent d'exécuter, d'opérer ou de comparer des choses pour juger, et non une seule commande ;
- c'est la livraison finale d'une tâche de niveau standard ;
- vous êtes profondément investi dans votre propre implémentation et êtes susceptible de voir tout comme correct.
L'auto-vérification est acceptable pour : les tâches de niveau léger ; ou les petits changements dont les critères sont décidés par une seule commande, avec un résultat évident.
Utilisation du vérificateur
La valeur du vérificateur réside dans son indépendance : il ne doit pas hériter du raisonnement ou de l'auto-justification de l'implémenteur.
- Donnez-lui : la référence des exigences, les critères d'achèvement de cette couche, les chemins de fichiers pertinents, comment exécuter les choses, et la plage de modifications (
git diffou une plage de validations). La plage de modifications est un fait, pas une ligne de raisonnement, et elle aide le vérificateur à trouver les endroits qui auraient dû changer mais ne l'ont pas fait. - Ne lui donnez pas : votre raisonnement d'implémentation, vos justifications de compromis, ou quoi que ce soit comme "je pense que c'est bon maintenant".
- Autorisations : il ne peut pas modifier la source, la configuration ou la documentation. Il peut exécuter des commandes de vérification locales (tests, builds, linters), et les artefacts de build résultants sont acceptables. Les commandes avec des effets secondaires externes sont interdites — déploiement, migration de données,
git commit/git push, suppression de données, appel d'API de production ou payantes. - Exigez qu'il vérifie chaque critère pour de vrai (exécutez la commande, lisez le code, inspectez la sortie) et qu'il rapporte réussi / échoué / impossible à vérifier par élément avec des preuves, plus tous les problèmes qu'il a trouvés en dehors des critères, classés par sévérité.
- Les corrections sont les vôtres, afin que le vérificateur et l'implémenteur ne redeviennent pas la même personne.
- Si l'implémentation a été effectuée par un agent de codage en ligne de commande (omp / codex / claude-code), vérifiez selon la section Vérification de la compétence
omp: lisez le diff qu'il a produit, cherchez spécifiquement les branches de conditions qui ne couvrent que le chemin heureux, exécutez le plus petit sous-ensemble indépendamment avec--filter, et renvoyez le travail de reprise comme "fichier:ligne + critère réussi/échoué + assertion attendue". - Les modèles d'invite se trouvent dans la section "Sous-agent vérificateur" de references/subagent-prompts.md.
Si l'environnement actuel n'a pas de capacité de sous-agent, ou si les règles de l'utilisateur ou de l'hôte interdisent les sous-agents : passez vous-même au rôle de vérificateur, vérifiez chaque critère selon le même modèle, et écrivez les preuves, plutôt que de cocher des cases de mémoire.
Gestion des résultats de vérification
- Critères échoués : corrigez, puis vérifiez à nouveau (continuez avec le même vérificateur ou envoyez-en un nouveau).
- Vous pensez que le vérificateur a tort : vous devez produire des contre-preuves (une commande et sa sortie, un fichier:ligne) pour infirmer le verdict, et indiquer dans le rapport quel verdict vous avez infirmé et sur quelle base. Ne vous en sortez pas par le seul argument.
- Problèmes trouvés en dehors des critères : seuls les problèmes "graves" — échec de la référence des exigences, données erronées, plantages, problèmes de sécurité — bloquent la couche suivante. Enregistrez le reste et listez-les dans le rapport, ou déplacez-les dans des suggestions hors périmètre.
Règles de preuve
- Tout ce qui n'est pas réellement exécuté ou inspecté ne peut pas être qualifié de "fait" ou "réussi". La seule formulation autorisée est "implémenté, non vérifié".
- Les tests locaux réussis ne sont pas une acceptation par l'utilisateur. Les tests unitaires réussis ne sont pas une fonctionnalité fonctionnelle. Indiquez le niveau que vous avez réellement vérifié.
4. Rapport final
Niveau standard, un rapport après que toutes les couches sont terminées :
**Achèvement** : <chaque élément de la référence des exigences, traité à son tour>
**Preuves de vérification** : <ce qui a été exécuté et ce qu'il a renvoyé ; quels éléments un vérificateur a vérifiés ; quels verdicts de vérification vous avez infirmés et sur quelle base>
**Non vérifié / limitations connues** : <chemins non exercés, lacunes connues>
**Hypothèses autoprises** : <mode autonome uniquement : ce que vous avez décidé vous-même, quelles opérations irréversibles vous avez sautées>
**Résultat de la critique** : <quelles critiques les décisions clés ont reçues, lesquelles ont été acceptées et lesquelles rejetées, et pourquoi>
**Suggestions hors périmètre** : <propositions du §6 qui nécessitent la décision de l'utilisateur, avec valeur et coût>
**Pièges nouveaux / mis à jour** : <titres des entrées écrites>
La ligne "Non vérifié / limitations connues" est obligatoire ; lorsqu'il n'y en a vraiment aucune, écrivez "aucune" et expliquez pourquoi vous êtes confiant. Les autres lignes peuvent être omises lorsqu'elles sont vides.
Niveau léger, le formulaire court :
**Ce qui a été fait** : <une ou deux phrases>
**Comment cela a été vérifié** : <commande + résultat>
**Limitations connues** : <uniquement s'il y en a>
Le rapport énonce uniquement des faits et des preuves. Pas d'auto-évaluation telle que "parfaitement implémenté", "très élégant", "amélioration massive".
Ce dont les utilisateurs se plaignent le plus sur les longs projets est la progression en boîte noire : ne rapporter que cet incrément les laisse incapables de juger où en est l'ensemble. Périodiquement — ou chaque fois qu'on vous le demande — fournissez un panorama du début à maintenant : chronologie des étapes et chaque statut, fonctionnalités manquantes planifiées ou non, dette technique contractée ou découverte, et tout changement de direction par rapport aux conversations passées. Le rapport §4 n'est pas le seul endroit pour cela ; ajoutez cette vue d'ensemble comme un message séparé, ou insérez-la en tête du rapport avec une section "Contexte général".