Planificateur d'exécution OpenCode pour plans de modèles frontière
Principe fondamental
Le plan d'un modèle frontière est une hypothèse solide, pas une vérité absolue.
Exécutez l'intention du plan étape par étape, mais validez chaque instruction par rapport au dépôt réel avant de modifier le code. Les plans de l'IA frontière échouent fréquemment sur : des noms de fichiers inexistants, des imports inventés, des bibliothèques indisponibles, des motifs qui ne correspondent pas au dépôt, des tests manquants, une architecture idéalisée et la rupture d'API internes.
Ne jamais regrouper de grandes modifications en bloc. Ne jamais sauter la vérification. Ne jamais cacher l'incertitude. Ne jamais effectuer d'actions destructrices sans approbation explicite.
Quand utiliser
- Vous recevez un plan d'implémentation détaillé et multi-étapes rédigé par une IA frontière
- Le plan comporte 3+ étapes distinctes avec des chemins de fichiers et des motifs de code spécifiques
- Vous utilisez un modèle de codage non frontière qui bénéficie d'une discipline d'exécution
- Le plan présente un risque de conflit avec la base de code réelle
Ne PAS utiliser pour :
- Modifications d'un seul fichier ou correctifs triviaux
- Plans avec seulement 1 à 2 étapes simples
- Plans que vous avez vous-même rédigés au cours de la même session
- Itération rapide où l'utilisateur privilégie la vitesse à la sécurité
Flux de travail principal
0. PRÉVOL : Établir la référence du dépôt
Avant de toucher à un fichier, comprendre l'état du dépôt et détecter les échecs préexistants.
1. git status --short # Le dépôt est-il propre ?
2. Inspecter package.json # Scripts disponibles, dépendances
3. Inspecter AGENTS.md, README.md # Conventions du projet, commandes
4. Détecter les commandes de vérification disponibles dans les scripts package.json
5. Exécuter la vérification de base la moins coûteuse si disponible (lint ou typecheck)
Si la vérification de base échoue déjà :
- Enregistrer l'échec explicitement : commande exacte, code de sortie et résumé court de l'erreur
- Ne PAS tenter un nettoyage général ou de corriger des problèmes non liés
- Continuer uniquement si la modification planifiée peut être isolée de l'échec existant
- N'attribuez pas les échecs préexistants à votre implémentation
Détection d'état dangereux :
- Si
git statusaffiche des modifications non validées sans rapport avec le plan, prévenez l'utilisateur - Si les fichiers de verrouillage sont modifiés, prévenez l'utilisateur
- Si le dépôt est dans un état de conflit/rebasage, arrêtez et demandez
Recommandation de point de contrôle :
- Si le dépôt est propre avant de commencer, recommandez de créer un commit de point de contrôle avant l'implémentation
- Ne PAS créer de commits sauf si explicitement demandé par l'utilisateur
Commit et Push automatiques
Les commits et pushes automatiques sont activés par défaut, sauf si l'utilisateur les désactive explicitement.
L'agent doit valider chaque unité logique vérifiée et la pousser vers la branche de travail distante active afin que l'utilisateur puisse examiner l'historique plus tard.
Avant l'implémentation :
- identifier la branche actuelle ;
- si sur
main,master,production,releaseou une autre branche protégée/de ligne principale, créer une nouvelle branche de travail déduite du plan ; - si déjà sur une branche de travail, continuer là ;
- ne jamais pousser directement vers les branches protégées/de ligne principale.
S'il existe des modifications non validées préexistantes :
- ne pas les inclure automatiquement dans les commits de l'agent ;
- ne mettre en scène que les fichiers liés à l'unité logique en cours ;
- si les modifications de l'utilisateur et celles de l'agent ne peuvent pas être séparées en toute sécurité, s'arrêter et signaler le conflit.
Valider uniquement après :
- l'unité logique est terminée ;
- la vérification réussit ;
- le diff a été inspecté ;
- le commit a un seul objectif cohérent.
Utiliser les Conventional Commits :
type(scope): résumé impératif concis
Exemples :
feat(auth): ajouter un assistant de validation de session
fix(api): gérer les webhooks de payload vide
refactor(billing): extraire le mapper de facture
test(auth): couvrir le flux de session expirée
1. ANALYSER : Extraire et vérifier le plan en fonction de la réalité
Lire le plan EN ENTIER. Extraire les étapes ordonnées. Pour chaque étape, effectuer une vérification de réalité :
| Vérification | Question |
|---|---|
| Fichiers | Les fichiers référencés existent-ils dans le dépôt ? |
| Bibliothèques | Les bibliothèques référencées sont-elles dans package.json ? |
| Motifs | Le dépôt a-t-il déjà un utilitaire/composant équivalent ? |
| Commandes | Les commandes de vérification du plan sont-elles disponibles ? |
| Dépendances | Cette étape dépend-elle d'une étape précédente ? |
| Risque | Faible / Moyen / Élevé — Quelle est la probabilité de casser le comportement existant ? |
Si une étape fait référence à des fichiers manquants, des bibliothèques inexistantes, des motifs obsolètes ou des commandes indisponibles : adapter l'étape avant de l'implémenter, en préservant l'intention du plan.
2. SUIVRE : Créer un suivi de progression
Utiliser todowrite (la liste de tâches d'OpenCode) si disponible.
Si todowrite est indisponible (par exemple, dans les sous-agents où il est désactivé par défaut) :
- Créer une liste de contrôle markdown visible dans votre réponse
- La mettre à jour manuellement après chaque étape
- L'utiliser comme source de vérité pour la progression
- Ne PAS prétendre que l'outil a été utilisé s'il ne l'a pas été
Chaque élément doit inclure : l'action d'implémentation, la méthode de vérification et les fichiers attendus modifiés.
3. IMPLÉMENTER : Une étape à la fois
Marquer l'étape en cours comme in_progress. Implémenter UNIQUEMENT cette étape.
- Lire les fichiers cibles avant de modifier
- Suivre les conventions existantes de la base de code (imports, nommage, motifs, architecture)
- Adapter le plan à l'infrastructure existante (par exemple, si le plan dit "créer un composant toast" mais le projet utilise Sonner, envelopper Sonner plutôt que de construire à partir de zéro)
- Faire le plus petit changement cohérent
- Ne PAS implémenter les étapes futures, mais garder à l'esprit les dépendances en aval lors des décisions de conception
- Ne PAS effectuer de nettoyage, de refactoring ou de formatage non lié
- Ne PAS installer de dépendances sauf approbation explicite
4. VÉRIFIER : Vérification à plusieurs niveaux
Après chaque étape, exécuter la vérification la plus étroite et la plus significative. Pas "lint tout" à chaque fois.
| Type de modification | Vérification minimale | Vérification plus forte |
|---|---|---|
| Nouveau fichier/composant | lint ou typecheck | typecheck concerné |
| Changement de type/interface | typecheck | tests concernés |
| Changement de logique/fonction | test unitaire ciblé | suite de tests complète |
| Changement API/serveur | test d'intégration ciblé | build + vérification de point de terminaison |
| Changement d'interface utilisateur | typecheck + build | vérification visuelle/manuelle |
| Changement de configuration/build | build | réinstallation/build propre si nécessaire |
| Changement de base de données/schéma | commande dry-run/vérification | approbation utilisateur requise |
S'il n'existe aucune vérification automatisée pour une étape : effectuer une revue manuelle et indiquer précisément ce qui a été vérifié.
Si la vérification échoue :
Premier échec — corriger et revérifier :
- Corriger uniquement les erreurs causées par l'étape en cours
- Ne PAS corriger les erreurs préexistantes ou non liées
- Revérifier immédiatement
Échecs répétés — ne pas continuer à appliquer des rustines aveuglément. Voir "Gestion des échecs répétés" ci-dessous.
Critique : Ne jamais faire passer la vérification en affaiblissant les assertions, supprimant des tests, supprimant un comportement, modifiant des API publiques, supprimant des erreurs ou cachant des échecs — sauf si le plan l'exige explicitement ET que l'utilisateur approuve. Faire cesser l'alarme n'équivaut pas à résoudre le problème.
5. DIFF : Inspecter les modifications
Une fois la vérification réussie, inspecter ce qui a réellement changé :
git diff --stat # Quels fichiers ont changé ?
git diff # Quand le diff est suffisamment petit pour être examiné
Confirmer :
- Seuls les fichiers attendus ont changé
- Aucun formatage non lié n'a eu lieu
- Aucun fichier de verrouillage n'a changé (sauf intention explicite)
- Aucun fichier généré n'a été accidentellement modifié
- Aucun secret, chemin local ou journal de débogage introduit
- Aucun code n'a été accidentellement supprimé
Si le diff dépasse la portée attendue, s'arrêter et corriger avant de continuer.
6. CONFIRMER : Marquer comme terminé
Seulement lorsque l'implémentation, la vérification ET l'inspection du diff sont propres :
- Marquer l'étape comme
completed - Résumer ce qui a changé en une phrase
- Marquer l'étape suivante comme
in_progress
7. FINAL : Vérification complète + Rapport
Après toutes les étapes :
- Exécuter la vérification la plus forte et raisonnable : lint + typecheck + build + tests (en utilisant les commandes du projet)
- Rapporter : étapes terminées, fichiers modifiés, résultats de vérification, adaptations effectuées, échecs préexistants (le cas échéant), tout ce qui nécessite une vérification par l'utilisateur
Gestion des échecs répétés
Si la vérification échoue plusieurs fois pour la même raison sous-jacente, ne continuez pas à appliquer de petits correctifs aveugles. L'objectif est de détecter si vous apprenez quelque chose de nouveau entre les tentatives ou si vous vous agitez au hasard.
Lorsqu'une étape échoue plusieurs fois :
- Arrêtez les rustines. Arrêtez de faire de petits ajustements et de relancer.
- Relisez attentivement la sortie d'erreur. La stacktrace complète, pas seulement la première ligne.
- Inspectez le diff et le code environnant.
git diff, lisez les types, interfaces et fonctions connexes. - Réévaluez l'hypothèse initiale. La stratégie d'implémentation actuelle est-elle correcte ?
- Classez l'échec :
- Hypothèse incorrecte sur la base de code ?
- Décalage entre le plan et la réalité du dépôt ?
- Mauvaise abstraction choisie ?
- Incompatibilité d'interface ou de type ?
- Dépendance manquante ?
- Artefacts générés obsolètes ?
- Problème préexistant sans rapport avec votre modification ?
- La commande de vérification elle-même est mal configurée ?
- Formez une hypothèse véritablement nouvelle. Ne réessayez que lorsque vous en avez une.
- Envisagez de réduire la portée. L'étape peut-elle être divisée en parties plus petites pour isoler l'échec ?
Règle critique : Ne répétez pas la même stratégie de correction à moins que de nouvelles informations n'aient été découvertes à partir de :
- Logs
- Stack traces
- Diffs
- Tests
- Inspection du dépôt
- Documentation
Si aucune nouvelle stratégie n'émerge après plusieurs tentatives, arrêtez et signalez clairement le blocage :
Blocage :
- commande de vérification : `npm run build`
- fichier en échec : `src/app/page.tsx`
- hypothèse de cause racine : composant serveur React important un hook côté client
- stratégies tentées :
1. déplacement de l'import vers un composant client
2. isolation du hook dans un fichier séparé
3. vérification des motifs existants dans le dépôt
- raison de l'arrêt :
aucun motif cohérent dans le dépôt pour résoudre la limite en toute sécurité
- prochaine action probable :
vérification par l'utilisateur ou clarification architecturale
Un rapport de blocage clair est toujours préférable à répéter "encore en échec" en devinant.
Adapter les plans au code existant
Les plans de l'IA frontière entrent fréquemment en conflit avec la base de code réelle. Quand c'est le cas :
- Identifier le conflit — "Le plan dit
import { X } from 'lib-non-installée'mais elle n'est pas dans package.json" - Adapter, ne pas ignorer — Utiliser l'infrastructure existante pour correspondre à l'intention du plan
- Expliquer l'adaptation — Une phrase sur ce que vous avez changé et pourquoi
- Préserver l'interface du plan — Si le plan exporte
useToast(), votre adaptation doit toujours exporteruseToast(), même si les éléments internes diffèrent
Règles critiques :
- Ne PAS créer de nouvelles abstractions si le dépôt a déjà une primitive équivalente
- Ne PAS installer de nouvelles dépendances sauf si le plan l'exige explicitement ET que l'utilisateur approuve
- Ne PAS modifier l'architecture ou les motifs sans justification
Interdit sans approbation explicite de l'utilisateur
Ces commandes nécessitent que l'utilisateur dise "oui" avant d'être exécutées :
Destructrices :
rm -rfgit reset --hardgit clean -fdgit push --force
Installation (modifie les fichiers de verrouillage) :
npm installpnpm installyarn installbun installnpm audit fix
Base de données / Infrastructure :
prisma migrateprisma db pushsupabase db pushdocker compose down -v
Configuration :
- Modifier les fichiers
.env - Modifier la configuration globale des outils
- Exécuter des commandes de déploiement/dépublier
Modifications massives :
- Formatage général (prettier/eslint --fix sur l'ensemble du dépôt)
- Rechercher et remplacer dans de nombreux fichiers sans vérification
En cas de doute sur la sécurité d'une commande, demander avant de l'exécuter.
Erreurs courantes
| Erreur | Réalité |
|---|---|
| "L'IA frontière l'a dit, donc c'est forcément juste" | Les plans frontières sont des hypothèses. Validez par rapport au vrai dépôt. |
| "Je vérifierai tout à la fin" | Les erreurs se cumulent. Vérifiez chaque étape avec la bonne granularité. |
| "J'ai déjà lu le plan, je peux tout implémenter d'un coup" | Implémentation par lots = lots d'erreurs + débogage plus difficile. |
| "Je vais corriger les erreurs de lint préexistantes pendant que j'y suis" | Le nettoyage non lié masque ce que vos modifications ont réellement fait. Ne le faites pas. |
| "Cette étape est simple, je n'ai pas besoin de vérifier le diff git" | Les modifications simples peuvent accidentellement supprimer du code ou formater des fichiers non souhaités. |
| "Je vais installer la bibliothèque manquante que le plan mentionne" | Demandez d'abord. La bibliothèque peut être intentionnellement absente ou non approuvée. |
| "npm run build est la seule vérification qui compte" | Le build est lent et large. Utilisez lint/typecheck pour les étapes intermédiaires. |
| "Si ça échoue, je vais juste ajuster et relancer jusqu'à ce que ça passe" | Corriger à l'aveugle sans nouvelles informations, c'est s'agiter. Relisez les erreurs. Formez d'abord une nouvelle hypothèse. |
| "La même erreur encore, laissez-moi essayer un autre petit changement" | Même erreur + même stratégie = même résultat. Changez la stratégie, pas le correctif. |
Drapeaux rouges — ARRÊTEZ et réévaluez
- "Je vérifierai après l'étape suivante aussi" — VÉRIFIEZ MAINTENANT.
- "Le plan frontière connaît mieux le dépôt" — Le dépôt est la source de vérité.
- "Cette bibliothèque n'est pas installée mais le plan en a besoin" — Demandez à l'utilisateur. N'installez pas en silence.
- "Le diff est plus grand que prévu mais ça devrait aller" — Inspectez et expliquez avant de continuer.
- "Je vais regrouper les étapes 2 et 3 puisqu'elles sont liées" — Une étape = un cycle de vérification + diff.
- "Erreurs de lint préexistantes, laissez-moi les corriger d'abord" — Pas votre travail. Enregistrez-les. Restez concentré.
- "Laissez-moi formater ce fichier pendant que je le modifie" — Modification séparée = étape séparée. Ne mélangez pas.
- "Toujours en échec, laissez-moi essayer un autre correctif rapide" — Arrêtez les rustines. Relisez l'erreur. Formez d'abord une nouvelle hypothèse.
- "La même erreur 3 fois, un autre petit ajustement pourrait marcher" — Même erreur + même stratégie = agitation. Changez de stratégie ou signalez un blocage.
- "Je vais juste tout réécrire et voir si ça résout le problème" — Jeter le travail sans comprendre pourquoi il a échoué n'enseigne rien. Diagnostiquez d'abord.
- "L'utilisateur est pressé, je vais sauter la vérification du diff" — 5 secondes de
git diff --statévitent des heures de débogage.
Référence rapide
| Phase | Action | Outil |
|---|---|---|
| Prélude | git status, détecter commandes, vérification de base | Bash |
| Analyse + Vérification réalité | Lire le plan, valider chaque étape par rapport au dépôt | Read + Glob |
| Suivi | Créer une liste de contrôle todowrite ou markdown | todowrite / Markdown |
| Implémentation | Une seule étape, adapter au dépôt | Read + Write |
| Vérification | Lint, typecheck, test ciblé | Bash |
| Diff | git diff --stat, git diff | Bash |
| Confirmation | Marquer comme terminé, résumer | todowrite / Markdown |
| Final | Vérification complète, rapport | Bash + Markdown |
Contributeurs
Ce skill a été initialement rédigé par @ASoudy. Voir le dépot ASoudy/AGS pour plus de détails.