Changer l'agent et le modèle

Ce tutoriel explique comment choisir et configurer les types d'agents et les modèles dans les steps du framework.

Qu'est-ce qu'un type d'agent ?

Un type d'agent est le mécanisme d'exécution — comment l'agent aborde sa tâche. C'est différent du persona (le rôle) et du profile (les connaissances techniques).

Analogie : le type d'agent est le métier, le profil est la personnalité, le profile est la spécialisation.

Types d'agents disponibles

Implémentation

Type	Usage	Modèle recommandé
executor	Implémentation de code, refactoring, feature work	sonnet
deep-executor	Tâches autonomes complexes, longue durée	opus
build-fixer	Erreurs de build, type errors, toolchain	sonnet
designer	Architecture UX/UI, design de composants	sonnet

Review et vérification

Type	Usage	Modèle recommandé
code-reviewer	Review complète — API, contrats, compatibilité	opus
quality-reviewer	Qualité, maintenabilité, performance, lint	sonnet
security-reviewer	Vulnérabilités, authentification, autorisation	sonnet
verifier	Validation des preuves de complétion	sonnet
test-engineer	Stratégie de tests, couverture, tests instables	sonnet

Analyse et planification

Type	Usage	Modèle recommandé
explore	Découverte de codebase, mapping de symboles	haiku
analyst	Clarification des besoins, critères d'acceptance	opus
architect	Design système, interfaces, décisions long terme	opus
planner	Séquençage de tâches, plans d'exécution	opus
debugger	Analyse de cause racine, isolation de régression	sonnet
writer	Documentation, notes de migration, guides	haiku

Les tiers de modèles

Shingan utilise 3 tiers abstraits indépendants du provider :

Tier	Capacité	Usage idéal
haiku	Rapide, coût faible	Lookups, scans, recherches ciblées
sonnet	Équilibré	Implémentation, review, debug
opus	Raisonnement profond	Architecture, analyse profonde, décisions complexes

• Claude Code : les tiers sont résolus automatiquement vers les modèles Claude correspondants. Aucune configuration nécessaire.
• OpenCode : les modèles sont configurés via le CLI npx opencode-shingan setup --models ou à l'installation via install.sh. Ils sont écrits directement dans framework/models.md et dans le frontmatter des agents.

Configurer les modèles (OpenCode)

La configuration se fait via le CLI npm :

npx opencode-shingan setup --models

Ou via le script d'installation :

bash install.sh

Les deux proposent 3 modes :

1. Un seul modèle pour tous les rôles (ex: Kimi K2 uniquement)
2. Un modèle par tier — rapide, standard, avancé (3 modèles)
3. Configuration avancée — un modèle différent par agent (50+ modèles possibles)

Les modèles sont écrits dans framework/models.md et dans le frontmatter de chaque agent.

Changer un modèle après l'installation

Demandez à l'IA :

"Change le modèle de security-reviewer en anthropic/claude-opus-4"

L'IA modifiera :

1. La table dans framework/models.md
2. Le champ model: dans framework/agents/security-reviewer.md

Vous pouvez aussi relancer la configuration : npx opencode-shingan setup --models.

Fichier de référence

Tous les modèles configurés sont visibles dans framework/models.md, section "Modèles configurés". C'est la source de vérité unique.

Comment changer dans un step

Dans un fichier de step, modifiez les champs type: et model: de l'agent :

### Step 05 — Examine

<agent>
  type: security-reviewer
  model: opus
</agent>

1. Analyser les surfaces d'attaque introduites
2. Vérifier la validation des entrées
3. Contrôler la gestion des erreurs (pas de leak d'infos sensibles)
4. Vérifier l'authentification et les autorisations

Guide de choix

Quelle tâche -> quel type ?

Scan de fichiers, recherche de patterns    -> explore (haiku)
Clarification des besoins, spec            -> analyst (opus)
Design architecture, décisions système     -> architect (opus)
Séquençage, plan d'exécution               -> planner (opus)
Implémentation, refactoring                -> executor (sonnet)
Tâche autonome complexe (>1h)              -> deep-executor (opus)
Bug, erreur de build, type error           -> build-fixer / debugger (sonnet)
Review qualité, lint, maintenabilité       -> quality-reviewer (sonnet)
Review sécurité                            -> security-reviewer (sonnet)
Review complète (API, contrats)            -> code-reviewer (opus)
Tests, couverture                          -> test-engineer (sonnet)
Documentation                              -> writer (haiku)
Validation de complétion                   -> verifier (sonnet)

Quel modèle ?

haiku   : scan, lookup, recherche rapide, tâches < 30s
sonnet  : implémentation standard, review, debug (80% des cas)
opus    : architecture, analyse profonde, décisions irréversibles

Commencez par sonnet

En cas de doute, sonnet est le bon choix. Passez à opus uniquement quand la tâche nécessite un raisonnement architectural profond ou des décisions à fort impact. Passez à haiku uniquement pour des lookups très ciblés.

Exemple : upgrader une review pour une feature critique

Scenario : vous implémentez un système de paiement. Le step d'examine standard utilise sonnet. Vous voulez une review de sécurité plus approfondie.

Avant (step standard) :

### Step 05 — Examine

<agent>
  type: quality-reviewer
  model: sonnet
</agent>

1. Vérifier la qualité du code produit
2. Identifier les edge cases manquants
3. Contrôler la cohérence avec les patterns existants

Après (upgrade pour feature critique) :

### Step 05 — Examine

<agent>
  type: security-reviewer
  model: opus
</agent>

1. Analyser toutes les surfaces d'attaque du flow de paiement
2. Vérifier la validation des montants (overflow, negative values)
3. Contrôler que les données de carte ne transitent jamais en clair
4. Vérifier idempotence des transactions
5. Contrôler la gestion des timeouts et des états intermédiaires

Deux changements : type passe de quality-reviewer à security-reviewer, et model passe de sonnet à opus. Les instructions deviennent aussi plus spécifiques au domaine paiement.

Le flag -e (economy)

Le flag -e d'/kensho désactive entièrement les subagents. Utile sur les plans avec tokens limités.

/kensho -e -s implement user registration

Avec -e :

• Pas de subagents spécialisés — tout est exécuté en séquentiel par le même agent
• Moins de contexte consommé
• Moins de qualité sur les steps de review et de planification
• Adapté pour les tâches simples ou quand le budget est serré

-e désactive les avantages de spécialisation

Les types d'agents et les modèles spécifiques n'ont plus d'effet en mode economy. Tous les steps sont traités de la même façon. Utilisez -e uniquement quand la contrainte de tokens est réelle.

Combiner type et profile

Les trois champs sont indépendants et se combinent :

<agent>
  type: executor          ← mécanisme : comment l'agent travaille
  profile: [rust, tauri]  ← connaissances : ce qu'il sait sur la stack
  model: sonnet           ← capacité : profondeur du raisonnement
</agent>

Chaque champ est optionnel — le framework applique des valeurs par défaut raisonnables si un champ est absent.

Bonnes pratiques

Modèle par défaut dans l'agent

Le fichier agent définit un modèle par défaut (model: opus pour architect). Le champ model: dans le step le surcharge. Utilisez la surcharge uniquement quand vous avez une raison spécifique de dévier du défaut.

Opus pour l'architecture, pas pour tout

Utiliser opus sur tous les steps ne donne pas de meilleurs résultats — ça consomme plus de tokens et ralentit le pipeline. Réservez opus aux steps qui impliquent des décisions structurelles ou de sécurité.

Ne changez pas le type d'agent pour corriger un prompt

Si un agent ne produit pas le bon output, vérifiez d'abord les instructions du step avant de changer son type. Un executor avec de mauvaises instructions reste mauvais avec n'importe quel type. Changez le type uniquement quand le rôle de l'agent doit changer.