Étapes de workflow

Les étapes de workflow sont les unités de travail individuelles au sein d’un pipeline CodeCourier. Chaque étape représente un rôle spécifique qu’un agent IA joue pendant l’exécution du workflow. CodeCourier définit dix types d’étapes, chacun conçu pour un objectif distinct dans le cycle de vie du développement logiciel. Les étapes sont configurées via des personas et assemblées en pipelines dans le workflow builder.

Référence des types d’étapes

Le tableau ci-dessous résume tous les types d’étapes disponibles et leurs caractéristiques principales.

type StepRole =
  | "designer"      // Primary implementation agent
  | "checker"       // Review and verdict agent
  | "optimizer"     // Code polish agent
  | "prompter"      // Prompt refinement agent
  | "investigator"  // Codebase research agent
  | "deep-dive"     // Deep analysis agent
  | "evaluator"     // Quality scoring agent
  | "judge"         // Multi-branch comparison agent
  | "answerer";     // Question-answering agent

Types d’étapes

Designer

Le designer est l’agent de codage principal. Il reçoit le prompt de la tâche (ou le prompt affiné d’une étape précédente) et implémente la solution. Les étapes designer produisent des changements de code, créent des fichiers, installent des paquets et effectuent tout travail de développement nécessaire pour répondre aux exigences.

• Outil par défaut : Claude Code
• Modèle par défaut : claude-opus-4-6
• Accepte une entrée : Oui - reçoit le prompt et le contexte des étapes précédentes
• Produit une sortie : Oui - changements de code et résultats d’implémentation
• Peut boucler : Oui - couramment associé à un checker dans une boucle d’itération

Le designer est le cheval de bataille de la plupart des workflows. Dans un workflow simple, une seule étape designer peut suffire. Dans des pipelines plus complexes, le designer travaille au sein d’une boucle où un checker passe en revue sa sortie et la renvoie pour révision si nécessaire.

Les étapes designer incluent un comportement d’auto-validation intégré. Le system prompt indique au designer d’exécuter la compilation TypeScript (npx tsc --noEmit), le linting (npx next lint) et la validation du schéma Convex avant de commiter. Cela détecte les erreurs courantes avant même que le checker n’examine le travail.

Checker

Le checker est un agent de revue qui évalue la sortie de l’étape précédente. Il produit un verdict - une réponse structurée avec un booléen pass et une chaîne feedback. Si le checker passe, le pipeline continue vers l’étape suivante. S’il échoue, la boucle redémarre avec le feedback du checker incorporé dans le prompt du designer suivant.

• Outil par défaut : Claude Code
• Modèle par défaut : claude-sonnet-4-6
• Accepte une entrée : Oui - passe en revue la sortie du designer
• Produit une sortie : Oui - verdict (pass/fail) et feedback
• Peut boucler : Oui - toujours associé à un designer dans une boucle

Le system prompt du checker met l’accent sur les tests de bout en bout. Par défaut, les checkers sont instruits de :

1. Détecter et déployer tout changement de backend (Convex, base de données, etc.).
2. Installer les dépendances et démarrer le serveur de dev.
3. Exécuter des tests de bout en bout à l’aide d’un navigateur headless.
4. Vérifier chaque exigence du prompt d’origine.
5. Produire un verdict structuré basé sur de vrais résultats de test.

Optimizer

L’optimizer s’exécute après qu’une boucle designer-checker passe. Son travail consiste à nettoyer et polir le code sans changer les fonctionnalités. Les étapes optimizer gèrent généralement :

• La suppression du code mort et des imports inutilisés.
• L’amélioration du nommage des variables et fonctions.
• L’ajout ou l’amélioration de la documentation et des commentaires.
• Le refactoring pour la lisibilité et la maintenabilité.
• Le maintien d’un style de code cohérent.

• Outil par défaut : Claude Code
• Modèle par défaut : claude-sonnet-4-6
• Accepte une entrée : Oui - travaille sur le code approuvé
• Produit une sortie : Oui - changements de code nettoyés
• Peut boucler : Généralement non - s’exécute une fois après approbation

Prompter

Le prompter est un agent qui affine ou développe une description de tâche vague en un prompt détaillé et actionnable. Il analyse la codebase, comprend la structure du projet et produit une spécification approfondie que les étapes designer suivantes peuvent implémenter efficacement.

• Outil par défaut : Claude Code
• Modèle par défaut : claude-opus-4-6
• Accepte une entrée : Oui - reçoit le prompt d’origine
• Produit une sortie : Oui - prompt affiné/développé
• Peut boucler : Généralement non - s’exécute une fois au début

Le prompter est particulièrement utile lorsque vos descriptions de tâches sont de haut niveau. Au lieu de « ajouter l’authentification », le prompter pourrait produire une spécification de plusieurs paragraphes couvrant quel provider d’auth utiliser, quelles pages nécessitent une protection, où ajouter les boutons de login et comment gérer l’état de session.

Investigator

L’investigator est un agent de recherche qui explore la codebase pour comprendre un problème avant que d’autres agents n’agissent dessus. Les étapes investigator sont utiles pour les workflows de débogage - l’investigator lit le code, exécute des tests et produit un rapport que les étapes suivantes utilisent comme contexte.

• Outil par défaut : Claude Code
• Modèle par défaut : claude-opus-4-6
• Accepte une entrée : Oui - reçoit la description du problème
• Produit une sortie : Oui - rapport d’investigation et conclusions
• Peut boucler : Généralement non - s’exécute une fois avant les étapes designer

Deep-Dive

L’étape deep-dive est un agent d’analyse intensive qui effectue des recherches approfondies sur des issues complexes. Similaire à l’investigator mais conçu pour des problèmes plus difficiles qui nécessitent de lire de nombreux fichiers, de tracer des chemins d’exécution et de comprendre l’architecture du système en profondeur.

• Outil par défaut : Claude Code
• Modèle par défaut : claude-opus-4-6
• Accepte une entrée : Oui - reçoit l’issue ou la question
• Produit une sortie : Oui - rapport d’analyse détaillé
• Peut boucler : Non - s’exécute une fois

Evaluator

L’étape evaluator note la sortie actuelle du pipeline par rapport à plusieurs dimensions de qualité. Elle produit un objet qualityScores qui quantifie à quel point l’implémentation répond aux critères de qualité définis. L’evaluator est configuré séparément via la page evaluator-setup, où vous définissez le contexte qu’il utilise, les skills qu’il applique et toutes les commandes ou scripts de setup qu’il exécute avant l’évaluation.

• Identifiant de type d’étape : evaluator
• Outil par défaut : Claude Code
• Modèle par défaut : claude-opus-4-6
• Accepte une entrée : Oui - évalue l’état actuel de la codebase
• Produit une sortie : Oui - objet qualityScores
• Peut boucler : Généralement non - s’exécute une fois après l’approbation de la conception

L’evaluator génère des scores de qualité sur cinq dimensions :

qualityScores: {
  correctness: number,       // 0-100: Does implementation meet requirements?
  typeSafety: number,        // 0-100: Are TypeScript types correct and complete?
  codeStyle: number,         // 0-100: Does code follow project conventions?
  testCoverage: number,      // 0-100: Are changes covered by tests?
  completeness: number,      // 0-100: Is the implementation fully finished?
  composite: number,         // 0-100: Weighted average of all dimensions
  thresholdResult: boolean,  // True if composite meets the configured threshold
}

Le booléen thresholdResult indique si le score composite atteint le seuil de qualité configuré sur la persona evaluator. Ce champ peut être utilisé par les étapes en aval pour décider s’il faut continuer ou déclencher un raffinement supplémentaire. L’enregistrement global du run porte aussi un champ qualityScore de premier niveau (le composite de toutes les étapes evaluator) pour un filtrage et des analytics rapides.

Judge

L’étape judge compare les sorties de branches parallèles et détermine laquelle est meilleure. Elle est utilisée dans les scénarios d’évaluation multi-branches où deux implémentations ou plus ont été produites - par exemple, en exécutant le même workflow avec des modèles ou des instructions différents - et où une décision finale sur laquelle conserver est nécessaire.

• Identifiant de type d’étape : judge
• Outil par défaut : Claude Code
• Modèle par défaut : claude-opus-4-6
• Accepte une entrée : Oui - reçoit les sorties de plusieurs branches pour comparaison
• Produit une sortie : Oui - un verdict identifiant la branche gagnante et sa justification
• Peut boucler : Non - s’exécute une fois après l’achèvement de toutes les branches

Le judge est un type d’étape avancé pour les équipes qui veulent exécuter des expériences A/B avec leurs configurations de workflow. Plutôt que de revoir manuellement deux implémentations, l’agent judge les évalue par rapport aux exigences d’origine et produit une comparaison structurée.

Answerer

L’étape answerer est utilisée dans les answering sessions pour répondre aux questions et hypothèses découvertes pendant les sessions d’investigation d’issue. Lorsqu’une session d’issue fait remonter des ambiguïtés ou des questions qui nécessitent une clarification humaine ou automatisée, l’answerer fournit des réponses qui permettent au pipeline de continuer sans intervention manuelle.

• Identifiant de type d’étape : answerer
• Outil par défaut : Claude Code
• Modèle par défaut : claude-sonnet-4-6
• Accepte une entrée : Oui - reçoit les questions et hypothèses de la session d’issue
• Produit une sortie : Oui - réponses structurées qui résolvent les ambiguïtés
• Peut boucler : Non - s’exécute une fois par answering session

L’answerer s’intègre au workflow de session d’issue pour boucler la boucle de feedback entre investigation et implémentation. Il est le plus couramment utilisé dans les pipelines qui incluent une étape investigator ou deep-dive, où la phase d’investigation peut faire remonter des questions ouvertes qui doivent être résolues avant que l’implémentation ne commence.

Configuration des étapes

Chaque étape d’un pipeline est configurée via sa persona. La persona définit :

{
  // Role determines the step type and execution behavior
  type: "designer" | "checker" | "optimizer" |
        "prompter" | "investigator" | "deep-dive" |
        "evaluator" | "judge" | "answerer",

  // CLI tool override (falls back to workflow default)
  cliId: "claude",     // or "opencode", "codex", "pi"

  // Model override (falls back to workflow default)
  model: "claude-opus-4-6",

  // Thinking effort for this step
  thinkingEffort: "high",

  // Custom instructions appended to the step's system prompt
  instructions: "Focus on TypeScript type safety...",

  // Skills enabled for this persona
  selectedSkills: ["vitest-testing", "seo-integration"],

  // Whether to inject compiled learnings
  learningsEnabled: true,
}

Détails d’exécution des étapes

Enregistrements de run step

Chaque exécution d’étape crée un enregistrement dans la table runSteps. Cet enregistrement suit :

• runId - Référence du run parent.
• sandboxId - La sandbox E2B utilisée pour cette étape.
• personaId - La persona qui a défini cette étape.
• cliId - L’outil CLI utilisé (par exemple, « claude »).
• modelId - Le modèle IA utilisé (par exemple, « claude-opus-4-6 »).
• iteration - À quelle itération globale cette étape appartient.
• loopId - L’ID du groupe de boucle (si dans une boucle).
• loopIteration - L’itération au sein de la boucle.
• role - Le type d’étape (designer, checker, evaluator, etc.).
• status - pending, running, completed ou failed.
• verdict - Verdict du checker (pass/fail + feedback).
• qualityScores - Scores de qualité de l’evaluator (correctness, typeSafety, codeStyle, testCoverage, completeness, composite, thresholdResult). Rempli uniquement pour les étapes evaluator.
• startedAt / completedAt - Informations de timing.

Timeline des étapes

La vue détaillée du run affiche une timeline visuelle des étapes qui montre chaque étape comme un nœud avec son rôle, son statut et sa durée. Cliquer sur une étape ouvre la sortie de sa sandbox. La timeline facilite le traçage du flux d’exécution, la visualisation des itérations qui ont passé ou échoué, et l’identification des goulots d’étranglement.

Logique conditionnelle

Le système de workflow de CodeCourier utilise un modèle conditionnel basé sur les verdicts plutôt qu’un branchement if/else explicite. Le verdict pass/fail du checker est le point de décision principal :

• Pass - Continuer vers le block suivant dans le pipeline.
• Fail - Boucler et réessayer (si dans les limites d’itération).
• Nombre max d’itérations atteint - Forcer la continuation quel que soit le verdict.

Ce modèle garde la configuration du workflow simple tout en fournissant la boucle de feedback nécessaire à l’amélioration itérative de la qualité.

Exécution parallèle

Au sein d’un seul workflow run, les étapes s’exécutent séquentiellement - l’étape 2 attend que l’étape 1 se termine. Cependant, CodeCourier prend en charge l’exécution parallèle au niveau du run. Vous pouvez démarrer plusieurs runs du même workflow simultanément, chacun travaillant sur une tâche différente sur une branche différente. C’est ainsi que fonctionnent les sprint chains - plusieurs sprints peuvent s’exécuter en séquence, mais les étapes internes de chaque sprint sont séquentielles.