Agent coach d'usage IA — qualité de prompt et optimisation des tokens

Billet #224 : Mise en place d'un agent coach d'usage IA axé sur la qualité de prompt et l'optimisation des tokens
Type : Automatisation / Workflow / Gouvernance
Composants concernés : .github/agents/ai-coach.agent.md, .github/hooks/ai-coach-session-start.json, scripts/hooks/ai_coach_session_start.ps1, .github/prompts/ai-coach-report.prompt.md, logs/ai_coach_session_starts.jsonl

1. Contexte et objectif

Depuis plusieurs semaines, la préoccupation principale dans mon usage de l'IA sur ce projet avait évolué. Dans un premier temps, l'effort portait sur la qualité du prompt: formuler clairement les demandes pour éviter les pertes de temps, les allers-retours inutiles et les malentendus avec l'assistant IA. Cette discipline avait porté ses fruits en termes d'efficacité de développement.

Progressivement, une deuxième dimension s'est imposée: la consommation de tokens. Un projet de cette envergure génère des sessions de chat longues, des contextes chargés et des échanges itératifs. Prompter efficacement ne suffisait plus. L'objectif devenait d'optimiser chaque session pour produire le même résultat avec le moins de tokens possible.

Cette session avait donc pour but de créer un agent coach capable de:

observer la qualité des demandes formulées, le niveau de contexte fourni et les actions effectuées;
mesurer et signaler la pression token exercée sur chaque session;
produire un rapport orienté progression avec des recommandations concrètes sur la session, notamment pour réduire le gaspillage de tokens sans sacrifier la qualité du travail.

2. Solution implémentée

L'agent a été conçu autour de deux couches complémentaires, avec l'efficacité token comme fil conducteur prioritaire.

Couche 1 — Observation

L'agent analyse chaque session selon trois axes: - la qualité des demandes: clarté de l'objectif, niveau de contexte fourni, précision des contraintes; - le déroulement du travail: nombre d'itérations, présence de rework évitable, qualité de la séquence (brief → exécution → validation); - la pression token: signaux de gaspillage détectés activement — contexte réinjecté inutilement, demandes trop larges, briefs incomplets générant des corrections, reformulations répétées du même besoin.

Couche 2 — Coaching

Sur la base des observations, l'agent produit à la demande un rapport structuré comprenant: - un résumé exécutif orienté impact; - les bons coups et les moins bons coups de la session; - trois recommandations actionnables au maximum, priorisées selon leur potentiel de réduction de tokens; - un scorecard par dimension dont l'efficacité token est signalée comme dimension prioritaire; - une estimation qualitative de la tendance token si l'historique le permet.

Infrastructure d'activation

Pour que ce coach soit opérationnel sans action manuelle, quatre composants ont été configurés:

.github/ai-coach.config.json — configuration centrale du coach hybride: définit le mode de capture par défaut (events-only) et les paramètres de rétention des transcripts;
scripts/hooks/ai_coach_session_start.ps1 — hook de démarrage enrichi: génère un identifiant unique (session_id) à l'ouverture de chaque nouvelle session et crée les artefacts de session dédiés;
.github/agents/ai-coach.agent.md — agent configuré en mode «une session à la fois»: lit exclusivement le fichier de session active, sans accès aux sessions précédentes;
.github/prompts/ai-coach-report.prompt.md — prompt mis à jour pour cibler la session active uniquement et déclencher le rapport en une seule commande.

Fonctionnement concret

À chaque démarrage de session, le comportement est le suivant:

Un nouveau session_id unique est généré automatiquement.
Le coach crée un fichier d'événements dédié à cette session dans logs/ai_coach_sessions/.
La session active est pointée dans logs/ai_coach_active_session.json.
Lors d'une demande de rapport, le coach lit d'abord ce pointeur de session active — sans mélange avec les sessions précédentes.
Le mode audit complet (transcription intégrale) est prévu dans l'architecture, mais désactivé par défaut pour limiter les risques et les coûts.

3. Validation et résultat

L'infrastructure a été validée en trois étapes:

Exécution du hook: le script a été lancé avec succès — retour JSON conforme contenant le session_id unique généré.
Création des artefacts: une nouvelle session active a été créée dans logs/ai_coach_sessions/ et son pointeur enregistré dans logs/ai_coach_active_session.json.
Rapport généré en mode isolé: l'agent ai-coach a produit un rapport en se limitant exclusivement à la session active, sans accès aux sessions antérieures.

Ce qui est maintenant possible:

à chaque nouvelle session, un espace d'observation isolé est créé automatiquement — aucune intervention manuelle requise;
le coach analyse une session à la fois, sans contamination entre les sessions;
sur demande, un rapport est généré avec une analyse ciblée sur les comportements à fort impact token pour cette session spécifique;
les recommandations reçues sont directement actionnables: mieux définir le périmètre d'une demande, éviter le contexte superflu, cadrer les itérations dès le brief.

Ce dispositif constitue la première brique d'un suivi structuré de la progression en tant qu'utilisateur IA, avec une attention particulière à la maîtrise des coûts de session.

4. Limites et points d'attention

Mesure token indirecte: l'outillage actuel n'expose pas de compteur token en temps réel. Le coach travaille donc sur des signaux proxy — longueur des échanges, nombre d'itérations, complexité des demandes — et produit une estimation qualitative. Si des données explicites deviennent disponibles, elles seront automatiquement priorisées.
Périmètre de session: le hook SessionStart s'applique aux nouvelles sessions uniquement. Une session déjà ouverte au moment de la mise en place ne déclenchera pas l'initialisation automatique.
Analyse session par session: par conception, le coach évalue une seule session à la fois à partir de ses événements dédiés. Il ne fait pas de synthèse multi-sessions en mode automatique; une tendance sur plusieurs sessions nécessite une demande explicite avec un contexte fourni par l'utilisateur.
Deux modes disponibles: le mode par défaut (events-only) est léger, gouverné et session par session — il capture uniquement les événements utiles. Un mode audit renforcé (transcription complète) est prévu dans l'architecture et peut être activé via un flag dans .github/ai-coach.config.json, mais reste désactivé par défaut pour limiter les risques et les coûts. Il est conçu pour des périodes courtes et ciblées.
Richesse de l'analyse conditionnelle aux événements capturés: en mode events-only, la profondeur du coaching dépend des événements enregistrés dans le fichier de session. Des sessions avec peu d'événements produiront des recommandations moins précises.
Rapport à l'initiative de l'utilisateur: le coach observe en continu, mais ne produit de rapport que sur demande explicite. C'est un choix délibéré pour ne pas alourdir les sessions en cours.