Core Concepts

CodeCourier est construit autour d’un petit ensemble de concepts interconnectés. Comprendre comment ils se relient les uns aux autres est la clé pour utiliser efficacement la plateforme. Cette page explique chaque concept, son rôle dans le système et la façon dont il se connecte à tout le reste.

Projets

Un projet est l’unité d’organisation de plus haut niveau dans CodeCourier. Toute autre ressource - sandboxes, workflows, runs, personas, contextes, assets, plans, issues, learnings, tâches récurrentes, sprint chains, membres d’équipe et clés API - appartient à exactement un projet.

Chaque projet possède un slug unique qui apparaît dans toutes les URL (p. ex., /p/my-app/dashboard), un owner et des métadonnées optionnelles telles qu’une URL de repository GitHub et un logo de projet. Les projets peuvent être liés à un repository GitHub, ce qui permet la création automatique de branches et la génération de pull requests à partir des runs de workflow.

Paramètres du projet

Les paramètres du projet contrôlent les comportements par défaut sur l’ensemble du projet :

• System prompt de sandbox - Une instruction par défaut ajoutée à chaque session de sandbox du projet
• Contenu CLAUDE.md - Du markdown écrit dans la sandbox en tant que fichier CLAUDE.md pour les outils CLI qui le prennent en charge
• Configurations par type de session - Chaque type de session (learning, merging, issue, answering, evaluator, judge) possède sa propre page de configuration dédiée où vous pouvez rattacher un contexte, sélectionner des skills, commands et scripts, et définir d’autres valeurs par défaut au niveau de la session
• Variables d’environnement - Des paires clé-valeur injectées dans les environnements de sandbox, avec la possibilité de marquer les valeurs sensibles comme secrets
• Configuration Git - Nom et e-mail d’auteur de commit personnalisés pour les commits générés par l’agent
• Paramètres de learning et de merging - Configurez quel modèle IA et quel template utiliser pour l’extraction de learnings et le merge de branches

Rôles d’équipe

Les projets prennent en charge trois rôles :

• Owner - Accès complet, y compris la suppression du projet et la gestion des membres
• Admin - Peut gérer les paramètres, les membres et toutes les ressources du projet
• Member - Peut créer et gérer ses propres ressources (sandboxes, runs, workflows) au sein du projet

Les membres sont invités par e-mail et doivent accepter l’invitation avant d’obtenir l’accès. Chaque membre peut configurer ses propres clés API, utilisées pour le provisionnement des sandboxes.

Sandboxes

Une sandbox est une machine virtuelle Linux isolée provisionnée via E2B. Les sandboxes sont l’environnement d’exécution où tournent les agents de codage IA. Chaque sandbox est un système Linux complet avec son propre système de fichiers, sa pile réseau et son espace de processus.

Configuration de sandbox

Chaque sandbox est créée avec un objet de configuration qui définit :

• Template ID - Détermine l’image de base et les outils préinstallés. Différents templates prennent en charge différents outils CLI (Claude Code, OpenCode, Codex, Pi, etc.)
• Timeout - Combien de temps la sandbox peut tourner avant son arrêt automatique, de 1 minute à 4 heures
• Mémoire- RAM allouée de 256 Mo à 8 Go
• Nombre de CPU - Nombre de cœurs CPU de 1 à 8
• Overrides de modèle - Spécifiez différents modèles IA pour les étapes de designer et de checker
• Thinking effort- Niveaux de thinking effort par modèle (p. ex., high, medium, low) qui contrôlent la quantité de raisonnement que le modèle effectue avant de répondre

Cycle de vie de la sandbox

Les sandboxes progressent à travers ces états :

• Creating - L’API E2B provisionne la VM
• Running - La sandbox est active et l’agent s’exécute
• Paused - La sandbox a été suspendue mais peut être reprise
• Killed - La sandbox a été terminée (par timeout, par action utilisateur ou à la fin)
• Error - La sandbox a rencontré une erreur fatale lors du provisionnement ou de l’exécution

Workflows

Un workflow est un blueprint réutilisable qui définit comment les agents IA doivent traiter une tâche. Les workflows spécifient le type de pipeline, la configuration de sandbox par défaut et les instructions au niveau des étapes.

Types de workflow

Single Designer

Le type le plus simple. Un seul agent reçoit le prompt et l’exécute en une passe. Idéal pour les tâches directes où aucune revue n’est nécessaire.

Designer & Checker

Le type le plus courant. Un designer agent écrit du code à partir du prompt, puis un checker agent relit la sortie au regard d’instructions configurables. Si le checker rejette (son verdict a pass: false), le designer reçoit le feedback et itère. Cette boucle se poursuit jusqu’à ce que le checker approuve ou que le nombre maximal d’itérations soit atteint.

Custom Pipeline

Définissez une séquence arbitraire de types d’étapes : designer, checker, optimizer, prompter, investigator, deep-dive, evaluator ou judge. Chaque étape peut, en option, spécifier son propre outil CLI, modèle, thinking effort et ses instructions. Les étapes peuvent être regroupées en boucles avec un nombre maximal d’itérations configurable.

Persona Pipeline

Chaînez des personas nommées en un pipeline séquentiel. Chaque étape référence une persona par son ID et hérite de la configuration complète de cette persona. C’est le type le plus flexible, qui vous permet de composer des workflows multi-agents complexes à partir de définitions de personas réutilisables.

Runs

Un run est une exécution unique d’un workflow (ou une session de sandbox autonome). Les runs stockent le prompt, la configuration, le statut, les informations de branche GitHub, les détails de la PR, le suivi des coûts, le score de qualité, le statut des checks CI et les références au workflow et au projet auxquels ils appartiennent.

Chaque run contient une ou plusieurs run steps. Une run step représente une invocation d’agent unique - une passe de designer, une revue de checker, une évaluation d’evaluator, etc. Les étapes suivent leur rôle (designer, checker, optimizer, prompter, investigator, deep-dive, evaluator, judge ou merge_agent), leur statut, leur durée, la sandbox utilisée, les verdicts du checker et les scores de qualité individuels.

Personas

Une persona est une configuration d’agent IA réutilisable limitée à un projet. Les personas vous permettent de définir des comportements d’agent standardisés qui peuvent être référencés à travers les workflows et les étapes de pipeline.

Chaque persona inclut :

• Type - Le rôle que remplit la persona. L’ensemble complet des types de persona est :
  • designer - Implémente les fonctionnalités et les correctifs
  • checker - Relit et valide la sortie
  • optimizer - Refactorise et améliore le code existant
  • prompter - Génère ou affine les prompts pour les agents en aval
  • investigator - Explore les codebases et fait des recherches avant de modifier
  • planner - Produit des plans structurés et des listes d’issues
  • deep-dive - Effectue une analyse approfondie avec un raisonnement étendu
  • reviewer - Se concentre sur la revue de code, la lisibilité et la maintenabilité
  • custom - Type sans contrainte pour des cas d’usage spécialisés
• Outil CLI - Quel client CLI utiliser dans la sandbox (identifié par une chaîne d’ID d’outil)
• Modèle - Quel modèle IA utiliser (p. ex., claude-opus-4-6, claude-sonnet-4-6)
• Thinking effort - Combien de raisonnement le modèle doit appliquer
• Instructions - Des instructions personnalisées au niveau système qui façonnent le comportement de l’agent
• Skills, commands et scripts - Les sets d’assets activés pour cette persona dans la sandbox
• Learnings - Faut-il inclure les learnings compilés du projet dans le contexte de l’agent

Les personas sont activées ou désactivées au niveau du projet. Les personas désactivées n’apparaissent pas dans la configuration de workflow ni dans les sélecteurs d’étape de persona pipeline.

Contextes

Les contextes sont des documents réutilisables et versionnés qui définissent le system prompt et le contenu CLAUDE.md injectés dans les sessions d’agent. Contrairement au system prompt de sandbox global (qui s’applique à chaque sandbox du projet), les contextes sont limités à des types de session spécifiques - ce qui vous donne un contrôle précis sur les instructions que reçoit chaque classe d’agent.

Limitation par type de session

Chaque document de contexte est rattaché à l’un des types de session suivants :

• learning - Sessions qui extraient et relisent les learnings des runs terminés
• merging - Sessions où un merge agent intègre des branches
• issue - Sessions de découverte et de scan d’issues
• answering - Answering sessions qui résolvent les questions produites par les sessions d’issues avant l’implémentation
• evaluating - Sessions d’evaluator agent qui notent la qualité de la sortie du run
• judging - Sessions de judge agent qui comparent les sorties entre des branches parallèles

Versionnement des contextes

Chaque document de contexte est versionné. Lorsque vous mettez à jour un contexte, la version précédente est préservée, de sorte que vous pouvez suivre l’évolution de vos instructions et revenir en arrière si un changement dégrade la performance de l’agent. La version active d’un contexte est celle injectée dans les nouvelles sessions de ce type. Les documents de contexte sont accessibles à /p/[id]/context au sein de votre projet.

Assets : Skills, Commands et Scripts

Les assets sont des packages versionnés et publiables de façon indépendante, qui étendent les capacités de l’agent au sein de la sandbox. Les assets sont créés et gérés au niveau du projet et peuvent être rattachés sélectivement à des personas individuelles ou à des types de session spécifiques via les Session Configurations.

Skills

Les skills sont des packages de savoir spécialisés. Contrairement à un unique fichier d’instructions, un skill est composé de plusieurs fichiers - par exemple, un skill Convex pourrait inclure un document de référence de patterns, un fichier de snippets de code et un fichier de lignes directrices d’architecture. Tous les fichiers d’un skill sont écrits sur le système de fichiers de la sandbox au démarrage de la session, de sorte que l’agent peut les lire, les référencer et s’appuyer dessus.

Les skills sont versionnés indépendamment. Publier une nouvelle version de skill n’affecte pas les sessions en cours d’exécution - seules les nouvelles sessions récupèrent les fichiers mis à jour.

Commands

Les commands sont des alias de commandes shell disponibles pour les agents à l’intérieur de la sandbox. Une command possède un nom, une expression shell et une description optionnelle. Par exemple, une command run-tests pourrait se déployer en npx vitest run --reporter=verbose, donnant aux agents un alias stable et spécifique au projet quelle que soit la configuration de votre test runner. Les commands sont injectées dans l’environnement de la sandbox au démarrage de la session.

Scripts

Les scripts sont des scripts shell ou Python exécutables qui peuvent être lancés à des points de cycle de vie spécifiques d’un workflow - avant que l’agent ne démarre, après que l’agent a terminé, ou à la demande. Les scripts sont utiles pour pré-alimenter la sandbox avec des données dynamiques, valider la sortie après la fin, ou exécuter des étapes de post-traitement trop procédurales pour un agent.

Sélection d’assets par persona et par type de session

Les skills, commands et scripts peuvent être rattachés à deux niveaux :

• Par persona - Lorsqu’une persona est utilisée dans une étape de pipeline, ses assets configurés sont injectés dans la sandbox pour cette étape uniquement
• Par type de session - La page Session Configuration de chaque type de session (issue, learning, merging, answering, evaluating, judging) vous laisse sélectionner quels assets sont disponibles pour toutes les sessions de ce type

Issues et Answering Sessions

Les sessions d’issues vous permettent de scanner une codebase à la recherche de problèmes et d’opportunités d’amélioration. Une session d’issues crée une sandbox qui analyse le repository et génère une liste structurée d’issues, chacune avec un titre, une description, une priorité (low, medium, high, critical) et un prompt suggéré pour la résolution.

Answering Sessions

Lorsqu’une session d’issues produit des questions ou des hypothèses non résolues - par exemple, “Faut-il utiliser la couche de cache existante ou la contourner ?” - une answering session peut être lancée pour laisser l’agent IA (ou un collaborateur humain) résoudre ces questions avant que l’implémentation ne commence. L’answering session reçoit la liste des questions ouvertes et produit des réponses structurées, qui sont ensuite transmises au run d’implémentation. Cela évite que les agents fassent des hypothèses incorrectes sur des exigences ambiguës.

Les issues individuelles peuvent être exécutées en créant un run avec le prompt suggéré, ou regroupées en work chains qui traitent plusieurs issues en séquence sur la même branche.

Sprint Chains

Les sprint chains sont un mécanisme d’orchestration en batch pour exécuter plusieurs runs de workflow à travers une série de sprints planifiés. Elles se distinguent des work chains (qui chaînent des correctifs d’issues sur une seule branche) en ce que chaque sprint d’une sprint chain est une unité de travail indépendante avec sa propre branche et sa propre pull request.

Structure d’une sprint chain

Une sprint chain suit :

• Plage de sprints- Le nombre total de sprints définis dans la chain (p. ex., “sprints 1 à 8”)
• Index de sprint courant - Quel sprint est en cours d’exécution ou vient de se terminer
• Suivi de PR par sprint - Chaque sprint enregistre sa propre URL de pull request, son nom de branche et son statut de PR de façon indépendante
• Prompts de sprint - Chaque sprint de la chain peut avoir son propre prompt ou hériter de celui par défaut de la chain

Les sprint chains sont bien adaptées à l’exécution d’une roadmap de fonctionnalités où chaque fonctionnalité nécessite une revue et un merge indépendants. La chain avance à travers les sprints automatiquement ou sur approbation manuelle, selon votre configuration.

Tâches récurrentes

Les tâches récurrentes vous permettent de planifier n’importe quel workflow CodeCourier pour qu’il s’exécute automatiquement à une cadence répétée. C’est utile pour les builds nocturnes, les audits hebdomadaires de qualité de code, les vérifications quotidiennes de dépendances, ou tout workflow que votre équipe souhaite automatiser sans déclenchement manuel.

Options de fréquence

Les valeurs de fréquence prises en charge sont :

• daily - S’exécute chaque jour à l’heure et à la minute configurées
• every_other_day - S’exécute un jour sur deux
• weekly - S’exécute une fois par semaine le jour configuré
• biweekly - S’exécute une fois toutes les deux semaines
• monthly - S’exécute une fois par mois le jour configuré

Fuseau horaire et planification

Les tâches récurrentes stockent un fuseau horaire, une heure et une minute d’exécution. La plateforme les utilise pour calculer la prochaine heure de run (nextRunAt) et déclenche le run automatiquement lorsque l’heure planifiée arrive. Toutes les heures planifiées sont stockées en UTC en interne mais peuvent être configurées et affichées dans n’importe quel fuseau horaire IANA.

Rôles Evaluator et Judge

CodeCourier inclut deux rôles d’agent spécialisés pour l’évaluation de la qualité, qui vont au-delà du pattern de checker standard :

Evaluator

Un evaluator agent note la qualité de la sortie d’un run ou d’une run step à travers les six dimensions de qualité (voir Scoring de qualité ci-dessous). Les evaluators sont utiles dans les longs pipelines où vous voulez une passe d’évaluation de qualité dédiée après l’implémentation et avant la revue finale. La sortie de l’evaluator est structurée - elle produit des scores numériques et un résumé, pas un verdict binaire réussite/échec.

Judge

Un judge agent compare les sorties de branches parallèles ou de plusieurs tentatives de run et sélectionne la meilleure. Les judges sont utiles lorsque vous exécutez le même prompt sur plusieurs configurations simultanément (différents modèles, différentes personas, différents sets de skills) et que vous voulez un arbitre objectif pour décider quel résultat faire avancer. Le judge reçoit toutes les sorties candidates et produit une comparaison structurée avec un gagnant et une justification.

Scoring de qualité

CodeCourier suit la qualité de la sortie au niveau de la run step via un objet de score de qualité structuré. Cela donne aux équipes un signal objectif et cohérent de la performance de chaque invocation d’agent - au-delà du simple “a-t-il terminé ?”.

Dimensions du score

Chaque score de qualité de run step inclut six dimensions, chacune notée sur une échelle de 0 à 100 :

• Correction - La sortie implémente-t-elle correctement les exigences ?
• Sûreté de typage - Les types TypeScript sont-ils corrects, sans any implicite ni erreurs de type ?
• Style de code - Le code suit-il les conventions et lignes directrices de style du projet ?
• Couverture de tests - Les tests sont-ils présents, pertinents et couvrent-ils le code modifié ?
• Complétude - L’agent a-t-il traité toutes les parties du prompt ?
• Composite - Un agrégat pondéré des cinq dimensions ci-dessus

Les scores de run step individuels sont agrégés en un qualityScore global sur l’enregistrement du run. Cela permet de filtrer et de trier les runs par qualité dans les vues d’analytics, et vous laisse identifier quelles configurations de workflow produisent systématiquement une sortie de meilleure qualité.

Checks CI

Les runs suivent le statut des checks CI via un objet ciChecks qui est mis à jour à mesure que votre pipeline CI traite le code généré par l’agent. L’objet contient :

• status - Statut CI global : pending, running, passing, failing ou skipped
• checks - Un tableau de résultats de checks individuels, chacun avec un nom, un statut et une URL de détails optionnelle
• checkedAt - Horodatage de la plus récente interrogation du statut CI

Les données de check CI apparaissent sur la page de détail du run, de sorte que vous pouvez évaluer la qualité du code sans passer à l’interface de votre provider CI.

Learnings

Les learnings sont le système de gestion des connaissances dans CodeCourier. Chaque fois qu’un agent IA commet une erreur, découvre un pattern ou rencontre une exigence spécifique au projet, ce savoir peut être capturé sous forme d’enregistrement de learning structuré.

Structure d’un learning

Chaque learning contient :

• Description - Ce qui a été appris
• Trigger - Quelle situation déclenche ce learning
• Comportement correct - Ce que l’agent devrait faire lorsque le trigger se produit
• Sévérité - Critical, important ou minor
• Catégorie - Preference, pattern, gotcha, tool ou architecture
• Confiance - Un score numérique indiquant la fiabilité de ce learning
• Source - S’il a été créé par un agent pendant un run ou extrait d’une session après coup

Cycle de vie d’un learning

Les learnings passent par un processus de revue en trois étapes :

1. Pending - Nouvellement créé, en attente de revue humaine
2. Approved - Vérifié par un membre de l’équipe et inclus dans les sessions futures
3. Rejected - Écarté comme incorrect ou non utile

Versions de learning

Les learnings approuvés sont compilés en documents markdown versionnés appelés learning versions. Chaque version est limitée à un projet et à un type de rôle, contient le markdown compilé et référence quels enregistrements de learning individuels sont inclus. Lorsqu’une nouvelle sandbox est provisionnée, la learning version active est injectée automatiquement dans le contexte de l’agent.

Le modèle de données en temps réel

CodeCourier utilise Convex comme base de données et runtime backend. Cela signifie que chaque query est une subscription réactive : lorsque les données changent sur le serveur, chaque client connecté qui lit ces données se met à jour instantanément, sans polling ni rafraîchissement manuel requis.

Cette architecture a des implications importantes pour l’expérience CodeCourier :

• Les mises à jour du statut de run (pending à running à completed) apparaissent immédiatement dans les navigateurs de tous les membres de l’équipe
• Les messages de sandbox s’affichent en temps réel à mesure que l’agent les produit
• Les scores de qualité et le statut des checks CI se mettent à jour en direct à mesure que les evaluators terminent leurs évaluations et que les pipelines CI rendent compte
• Les nouveaux learnings, les changements de workflow et les ajouts de membres d’équipe se propagent instantanément
• Les compteurs du dashboard et les analytics se mettent à jour en direct sans rafraîchissement de page

Toute la logique métier - authentification, autorisation, validation et mutations de données - s’exécute dans les Convex server functions. Le frontend ne parle jamais directement à la base de données ; il appelle des queries Convex (qui s’abonnent de façon réactive) et des mutations (qui modifient les données via des functions côté serveur validées).

Comment les concepts se connectent

Voici comment les grands concepts se relient les uns aux autres :

• Un projet contient des workflows, personas, contextes, assets, plans, issues, learnings, tâches récurrentes, sprint chains et membres d’équipe
• Un workflow référence un projet et définit un blueprint pour les runs
• Une persona appartient à un projet et porte son propre set d’assets (skills, commands, scripts) et son rattachement de contexte ; elle peut être référencée par les étapes de workflow persona pipeline
• Un contexte appartient à un projet, est limité à un type de session et est injecté automatiquement dans les sandboxes de ce type
• Les assets (skills, commands, scripts) appartiennent à un projet et sont sélectionnés par persona et par type de session
• Un run appartient à un projet, référence éventuellement un workflow, crée une ou plusieurs sandboxes et suit les scores de qualité et le statut des checks CI
• Une sandbox appartient à un run (ou existe de façon autonome) et contient des messages
• Une session d’issues appartient à un projet et produit des issues qui peuvent déclencher des runs, des work chains ou des answering sessions
• Une sprint chain appartient à un projet et orchestre une série de runs à travers des sprints planifiés, chacun avec sa propre branche et sa propre PR
• Une tâche récurrente appartient à un projet et déclenche des runs selon un calendrier configurable
• Les learnings sont extraits des sandboxes, relus par les membres de l’équipe, compilés en versions et injectés dans les sandboxes futures

Prochaines étapes