Configuration des personas

Après avoir créé une persona, la page de détail propose sept onglets pour configurer chaque aspect du comportement de l’agent : Configuration, Instructions, Context, Skills, Activity, Analytics, et Related. Ce guide couvre chaque onglet en profondeur, avec les best practices et recommandations pour chaque paramètre.

Onglet Configuration

L’onglet Configuration contrôle le comportement runtime principal de la persona : quel outil elle utilise, quel modèle elle exécute, et à quelle profondeur elle raisonne sur les problèmes.

Sélection de l’outil CLI

L’outil CLI détermine quel agent de codage IA s’exécute à l’intérieur de la sandbox. CodeCourier prend en charge plusieurs outils, chacun avec ses propres forces :

• Claude Code (claude) - L’agent de codage d’Anthropic. Idéal pour la génération de code complexe, les changements multi-fichiers et les tâches de reasoning profond. Prend en charge un effort de réflexion jusqu’à “max”.
• OpenCode (opencode) - Alternative open source avec support de plusieurs fournisseurs de modèles. Bon pour les équipes qui ont besoin de flexibilité dans le choix du modèle.
• Codex (codex) - L’agent de codage d’OpenAI. Idéal pour les tâches qui bénéficient des modèles GPT.

Lorsque vous changez l’outil CLI, le menu déroulant du modèle se met automatiquement à jour pour n’afficher que les modèles disponibles pour cet outil. Si le modèle actuellement sélectionné n’est pas disponible sur le nouvel outil, il revient au modèle par défaut de l’outil.

Sélection du modèle

Le modèle détermine le LLM spécifique qui alimente l’agent. Les modèles disponibles dépendent de l’outil CLI sélectionné. Pour Claude Code, les options typiques incluent :

• claude-opus-4-6 - Capacité la plus élevée, idéal pour les tâches complexes. Coût et latence plus élevés.
• claude-sonnet-4-6 - Bon équilibre entre qualité et vitesse. Recommandé pour les rôles checker et prompter.

Choisissez le modèle en fonction du rôle de la persona. Les designers, les agents deep-dive et les optimizers bénéficient généralement du modèle le plus capable (Opus), tandis que les checkers, reviewers et prompters fonctionnent bien avec des modèles plus rapides (Sonnet) puisque leurs tâches sont plus contraintes.

Effort de réflexion

L’effort de réflexion contrôle la quantité de reasoning que le modèle applique avant de produire une sortie. Un effort plus élevé conduit à de meilleurs résultats sur les problèmes complexes mais augmente la latence et le coût.

Injection de learnings

Lorsqu’elle est activée, les sessions de la persona reçoivent automatiquement les learnings compilés actifs pour son type de rôle. Les learnings sont des connaissances capturées à partir des runs passés - patterns, pièges, préférences et best practices qui améliorent le comportement de l’agent au fil du temps.

Chaque version de learning est compilée par type de rôle (designer, checker, etc.), de sorte qu’une persona designer reçoit des learnings spécifiques au designer tandis qu’une persona checker reçoit des learnings spécifiques au checker. Ce toggle vous permet de désactiver l’injection pour les personas qui doivent démarrer à neuf sans contexte historique.

Bascule activer/désactiver

Le toggle isEnabled contrôle si la persona est active et sélectionnable dans les configurations de persona pipeline. Désactiver une persona la cache du sélecteur de personas dans les éditeurs de workflow sans la supprimer. C’est utile lorsqu’une persona est en cours de révision et ne doit pas être utilisée dans des workflows de production tant qu’elle n’est pas prête.

Onglet Instructions

L’onglet Instructions fournit une zone de texte libre pour définir le comportement au niveau système de la persona. Ces instructions sont injectées dans le contexte de l’agent au début de chaque session et façonnent la manière dont il aborde les tâches.

Écrire des instructions efficaces

Les bonnes instructions de persona sont spécifiques, actionnables et structurées. Voici des patterns qui fonctionnent bien :

## Role
You are a senior frontend engineer specializing in React 19
and Tailwind CSS v4.

## Standards
- Use functional components exclusively
- Extract reusable logic into custom hooks
- All components must have TypeScript interfaces for props
- Prefer server components where possible
- Use the project's existing design tokens from globals.css

## File Organization
- Components go in components/{feature}/
- Hooks go in hooks/
- Never create barrel (index.ts) files

## Testing
- Write unit tests for all utility functions
- Include at minimum one integration test per component
- Use Vitest and React Testing Library

Best practices pour les instructions

• Soyez explicite sur ce qu’il ne faut PAS faire - Les contraintes sont aussi importantes que les instructions. Dites à l’agent ce qu’il faut éviter.
• Utilisez des sections structurées - Les titres et les listes numérotées facilitent le suivi des instructions par le modèle.
• Référencez les conventions du projet - Mentionnez des chemins de fichiers spécifiques, des patterns de nommage et des outils utilisés dans votre codebase.
• Restez concentré - Une persona de vérification ne devrait pas inclure d’instructions d’implémentation. Chaque persona a un seul job.
• Testez et itérez - Exécutez la persona dans quelques workflows, examinez la sortie, et affinez les instructions en fonction de ce qui ne va pas.
• Complétez, ne dupliquez pas le contexte - Si vous avez un document Context lié couvrant l’architecture, ne répétez pas cette même information dans le champ Instructions. Laissez chacun servir son objectif.

Onglet Context

L’onglet Context vous permet de lier un document Context à cette persona. Les documents Context sont des ressources markdown au niveau du projet - résumés architecturaux, standards de code, guides de référence API, notes d’onboarding, ou tout matériel de référence auquel un agent IA doit avoir accès pendant sa session.

Comment fonctionne la liaison de contexte

Lorsqu’un document de contexte est lié à une persona, le markdown de la version active du contexte est automatiquement préfixé à la configuration de la sandbox au début de chaque session utilisant cette persona. L’agent reçoit le contenu du contexte avant de recevoir les propres instructions de la persona, de sorte que le contexte agit comme une connaissance de fond fondamentale.

Pour lier un contexte :

1. Naviguez vers l’onglet Context sur la page de détail de la persona.
2. Cliquez sur Select Context pour ouvrir le sélecteur de contexte.
3. Choisissez dans la liste des contextes de projet disponibles. Seuls les contextes avec une version active apparaissent dans la liste.
4. Enregistrez. La liaison est stockée en tant que contextId sur l’enregistrement de la persona.

Quand utiliser la liaison de contexte vs. les instructions

Onglet Skills

L’onglet Skills donne à cette persona accès à des connaissances de domaine packagées, des shell commands et des scripts exécutables. Il est organisé en trois sous-sections : Skills, Commands, et Scripts.

Skills

Les skills sont des ensembles curatés de fichiers de référence, de best practices et de documentation API pour des technologies spécifiques. La section Skills affiche tous les skills activés dans le projet sous forme de grille de cases à cocher. Chaque carte de skill affiche le nom du skill, sa description et le nombre de fichiers. Sélectionnez les skills pertinents pour le rôle de la persona :

• Un designer frontend pourrait avoir besoin de : frontend-design, vitest-testing
• Un designer backend pourrait avoir besoin de : convex-implementation, zod-validation
• Un checker pourrait avoir besoin de : app-security, superpower-codereview
• Un reviewer pourrait avoir besoin de : app-security, performance-optimization-addyosmani
• Un planner pourrait avoir besoin de : superpower-debugging, convex-implementation

Commands

Les commands sont des shell commands ou des alias qui sont injectés dans l’environnement sandbox au démarrage de la session. Ils donnent à l’agent accès à des opérations CLI spécifiques au projet, des scripts de build personnalisés, ou des commands utilitaires sans exiger que l’agent connaisse leur implémentation complète.

La section Commands affiche tous les commands définis dans le projet sous forme de liste à cases à cocher. Chaque entrée de command affiche son nom, son alias et une brève description de ce qu’il fait. Sélectionnez les commands auxquels la persona a besoin d’accéder pendant ses sessions. Les IDs de commands sélectionnés sont stockés dans selectedCommands sur l’enregistrement de la persona.

Exemples de cas d’usage pour l’injection de commands :

• Une persona designer qui a besoin de npm run typecheck et npm run lint
• Une persona checker qui a besoin d’un command validate-schema personnalisé

Scripts

Les scripts sont des fichiers de script exécutables qui sont injectés dans le système de fichiers de la sandbox au démarrage de la session. Contrairement aux commands (qui sont typiquement des alias ou des one-liners), les scripts sont des programmes multi-étapes que l’agent peut invoquer par nom.

La section Scripts affiche tous les scripts définis dans le projet. Chaque entrée affiche son nom, son langage (bash, python, node) et une description. Les IDs de scripts sélectionnés sont stockés dans selectedScripts sur l’enregistrement de la persona.

Onglet Activity

L’onglet Activity affiche un tableau paginé de tous les run steps exécutés par cette persona. Chaque ligne inclut le run lié, le statut de l’étape (completed/failed/running), le numéro d’itération et les horodatages. Cela vous donne un historique de la performance de la persona à travers les workflow runs.

Utilisez le flux d’activité pour identifier des patterns : si une persona échoue systématiquement sur un type de tâche particulier, examinez les messages d’échec pour affiner ses instructions. Si une persona nécessite régulièrement de nombreuses itérations avant de passer un checker, envisagez d’augmenter son effort de réflexion ou d’enrichir ses skills.

Onglet Analytics

L’onglet Analytics fournit des visualisations en séries temporelles de la performance de la persona. Vous pouvez filtrer par période (7 jours, 30 jours, 90 jours) et granularité (quotidienne, hebdomadaire, mensuelle). Les métriques suivantes sont suivies :

Le score de qualité est particulièrement précieux pour suivre si les changements d’instructions ont un effet positif. Après avoir affiné les instructions d’une persona, vérifiez la tendance du score de qualité sur la semaine suivante pour confirmer l’amélioration.

Les données de coût sont ventilées par catégorie de service en utilisant les enregistrements d’usage du projet, vous donnant une visibilité sur quel composant de chaque run (inférence de modèle, exécution sandbox, etc.) est le principal moteur de coût.

Onglet Related Entities

L’onglet Related affiche les entités connectées à cette persona : les workflows qui l’ont utilisée, les issues liées à ses runs, et les versions de learning compilées pour son type de rôle. Cela fournit un moyen rapide de naviguer d’une persona vers tout le travail auquel elle a été associée à travers le projet.

Versioning des personas

Chaque fois que vous enregistrez des changements aux instructions ou à la configuration d’une persona, CodeCourier crée un nouvel enregistrement de version plutôt que d’écraser l’existant. L’historique des versions est accessible depuis un panneau Version History sur la page de détail de la persona.

Comportements de versioning clés :

• Le champ version s’incrémente à chaque enregistrement (1, 2, 3, …).
• La version la plus récente devient automatiquement isLatest: true.
• Tous les nouveaux workflow runs utilisent la dernière version.
• Le champ parentPersonaId lie chaque version à son prédécesseur, formant une chaîne.
• Vous pouvez promouvoir n’importe quelle version antérieure au rang de dernière depuis le panneau d’historique des versions, créant un nouvel enregistrement de version qui reflète le contenu promu.

Étapes suivantes