Personnaliser un agent

Ce tutoriel explique comment utiliser, configurer et créer des agents pour adapter le comportement du framework.

Qu'est-ce qu'un agent ?

Un agent est un rôle spécialisé que l'IA adopte pendant un step. Il définit :

• Qui elle est (identité, expertise, niveau d'expérience)
• Ce qu'elle fait (responsabilités du rôle)
• Ce qu'elle ne fait pas (contraintes explicites)
• Comment interagir (menu d'actions avec des codes courts)
• Quels outils elle utilise
• Quel modèle elle utilise (tier ou ID concret)

L'agent est différent du profile : le profile injecte des connaissances techniques (conventions, toolchain), l'agent définit le rôle et le comportement.

Agents disponibles

Agent	Rôle	Tier par défaut	Fichier
analyst	Clarifie les besoins, produit des specs	opus	framework/agents/analyst.md
architect	Conçoit l'architecture, read-only	opus	framework/agents/architect.md
executor	Implémente le code	sonnet	framework/agents/executor.md
code-reviewer	Review complète 3 passes	opus	framework/agents/code-reviewer.md
security-reviewer	Audit sécurité OWASP	opus	framework/agents/security-reviewer.md
quality-reviewer	Qualité, SOLID, maintenabilité	sonnet	framework/agents/quality-reviewer.md
test-engineer	Tests, couverture, edge cases	sonnet	framework/agents/test-engineer.md
debugger	Root cause, isolation	sonnet	framework/agents/debugger.md
explore	Exploration rapide codebase	haiku	framework/agents/explore.md

Utiliser un agent dans un step

Dans un fichier de step, la balise <agent> indique quel agent adopter :

### Step 02 — Plan

<agent>architect</agent>

1. Concevoir l'architecture des modules
2. Identifier les interfaces entre composants
3. Produire le plan fichier par fichier

Changer l'agent change le comportement pour ce step. Un executor implémente du code, un code-reviewer cherche des problèmes.

Quand créer un nouvel agent ?

Créez un nouvel agent quand :

• Le rôle n'existe pas parmi les 9 agents de base
• Vous avez besoin d'un expert domaine récurrent (DBA, DevOps, UX designer, data engineer...)
• Le rôle a des contraintes spécifiques importantes (ex: read-only, pas de modifications de schéma, etc.)

Préférez les profiles

Avant de créer un nouvel agent, demandez-vous si un profile ne suffit pas. Si vous voulez un "executor Rust", c'est <agent>executor</agent> + profile: rust — pas un nouvel agent. Créez un agent uniquement quand le rôle lui-même est différent.

Créer un nouvel agent

Etape 1 : Créer le fichier

touch framework/agents/dba.md

Etape 2 : Écrire le frontmatter

---
name: dba
role: Database Administrator
model: opus
description: |
  Expert en bases de données, optimisation de requêtes, et modélisation.
  Utiliser quand : design de schéma, migrations, performance SQL, indexation.
disallowedTools: Write, Edit
---

Les champs obligatoires :

• name : identifiant utilisé dans les step files
• role : titre affiché
• model : tier de modèle par défaut (haiku, sonnet, opus) ou ID concret — configuré dans framework/models.md (voir changer le modèle)
• description : quand utiliser cet agent (aide l'IA à le choisir automatiquement)
• disallowedTools : outils interdits (pour les agents read-only)

Etape 3 : Section Identité

## Identité

Tu es un DBA senior spécialisé en PostgreSQL. Tu conçois des schémas
performants, optimises les requêtes lentes, et guides les migrations
de données sans downtime.

### Principes
- **Performance first** : chaque requête doit être indexée
- **Data integrity** : contraintes FK, NOT NULL, CHECK partout
- **Migration safe** : zéro downtime, rollback possible

Etape 4 : Menu d'actions

Le menu d'actions permet d'invoquer des actions spécifiques avec des codes courts.

## Menu d'actions

| Code | Action | Description |
|------|--------|-------------|
| `S` | Schema | Designer un schéma de tables |
| `O` | Optimize | Analyser et optimiser une requête lente |
| `M` | Migrate | Planifier une migration de schéma |
| `I` | Index | Recommander des index |
| `R` | Review | Revoir un schéma ou une migration existante |

Une fois l'agent actif, taper S déclenche le mode "Schema design" sans avoir à réécrire l'instruction complète.

Etape 5 : Section Agent_Prompt

Le bloc <Agent_Prompt> contient les instructions d'exécution en anglais :

<Agent_Prompt>
  <Role>
    You are a senior PostgreSQL DBA. You design normalized schemas,
    optimize queries with EXPLAIN ANALYZE, and plan zero-downtime migrations.
  </Role>

  <Responsibilities>
    - Design normalized database schemas (3NF minimum)
    - Analyze and optimize slow queries
    - Plan zero-downtime migrations
    - Recommend indexing strategies
  </Responsibilities>

  <Constraints>
    - Read-only: never modify code directly — propose changes
    - Always justify with EXPLAIN ANALYZE
    - Consider impact on existing queries
    - SQL-first thinking, not ORM-first
  </Constraints>

  <Output_Format>
    ## Schema: {title}

    ### Tables
    | Table | Columns | Index | Constraints |

    ### Migrations
    1. ALTER TABLE ... (safe, no lock)
    2. CREATE INDEX CONCURRENTLY ... (no downtime)
  </Output_Format>
</Agent_Prompt>

Etape 6 : Utiliser dans un step

### Step 02 — Design du schéma

<agent>dba</agent>

1. Analyser les entités identifiées au step 01
2. Concevoir le schéma normalisé (3NF minimum)
3. Définir les index nécessaires
4. Planifier la migration zero-downtime

<gate>Schéma validé → type `next`</gate>

Bonnes pratiques

Un agent = un rôle clair

Ne créez pas un agent "full-stack" qui fait tout. Chaque agent doit avoir un périmètre net avec des contraintes explicites. La valeur vient de ce qu'il refuse de faire autant que de ce qu'il fait.

Read-only par défaut pour les agents non-executor

Si l'agent n'a pas besoin de modifier du code (architect, dba, analyst...), ajoutez disallowedTools: Write, Edit dans le frontmatter. Ça force la séparation des responsabilités et évite les modifications accidentelles.

Ne dupliquez pas les agents existants

Avant de créer un nouvel agent, vérifiez qu'un des 9 existants ne couvre pas déjà le besoin avec un profile adapté. Un executor + profile: python-fastapi est presque toujours suffisant — inutile de créer un agent python-developer.