Files
Support-Agent/docs/agents/agent-diagnostic.md
T

14 KiB
Raw Blame History

Agent de diagnostic (pilote dans Claude Code)

  • Date : 2026-10-14.
  • Statut : construit le 2026-10-14 (outils, instructions, point d'entrée) ; test à l'aveugle : §7. Décision liée : D-046 (docs/decisions.md).
  • Place : version pilote, la plus légère, de l'enquête à la demande (D-042) et du cadre d'agents (D-027). Mêmes idées (outils en lecture, réfutation obligatoire, preuves tracées), mais exécutée par Claude Code au lieu du harnais par API : pas de clé API, pas de harnais à écrire.

1. Objet

Le besoin (utilisateur). Un agent d'analyse qu'on appelle à tout moment et qui fait un diagnostic sur les données qu'on lui fournit. On profite de la souplesse d'un agent pour se dispenser, au départ, de méthodes analytiques complexes. Simple pour l'instant. Un dossier propre à l'agent : sa doc, ses scripts, ses outils.

Choix de l'utilisateur, sur proposition :

Question Choix
Mode d'appel Les deux : une question facultative ; sans question, l'agent fait le scan de la période
Sortie Un rapport écrit dans le dépôt par diagnostic, et un résumé dans la conversation
Données de la première version Les déplacements et les images ; les métriques système plus tard
Forme Un sous-agent Claude Code avec son dossier agents/diagnostic/
Graphiques matplotlib, ajouté à .venv et au dev container (poste de dev seulement)

Critère de réussite. On lui donne data/PS_DES_COUDRES/, sans autre explication ; il rend un diagnostic traçable des deux épisodes nocturnes sur REF_G et REF_D (§6).

Ce que ça change. La chaîne analytique de D-044 (détecter puis corriger, embarquable) passe au second plan : l'agent explore et diagnostique ; on reviendra au code embarquable si un même motif se répète. La couche déterministe reste sans LLM (D-027).

2. Architecture

.claude/agents/diagnostic.md     point d'entrée pour Claude Code : nom, outils, modèle
agents/diagnostic/
  README.md                      doc humaine : à quoi il sert, comment l'appeler
  instructions.md                sa méthode : règles, déroulé, format du rapport
  outils/                        ses scripts Python
  rapports/                      un rapport par diagnostic
  • Appel : @agent-diagnostic data/PS_DES_COUDRES/ suivi, au choix, d'une question ; ou en langage naturel (« lance l'agent diagnostic sur … ») ; ou une session entière dans un terminal : claude --agent diagnostic, mais elle charge CLAUDE.md (omitClaudeMd ne vaut que pour un sous-agent) : elle n'est pas à l'aveugle.
  • Contexte isolé : le sous-agent démarre sans la conversation qui l'appelle, donc sans ses hypothèses.
  • Emplacement : agents/ est celui que prévoyait D-027. La méthode et les outils sont portables vers le futur harnais par API.

3. Point d'entrée

.claude/agents/diagnostic.md :

---
name: diagnostic
description: Diagnostic des données d'une station AIMsight (déplacements optiques, images).
  À appeler avec un dossier de data/ et, si on veut, une question. Rend un rapport
  traçable dans agents/diagnostic/rapports/.
tools: Read, Bash, Write
model: opus
effort: high
omitClaudeMd: true
---
Tu es l'agent de diagnostic du projet. Commence par lire agents/diagnostic/instructions.md
et suis-le à la lettre.
  • Outils : Read (CSV, docs, images), Bash (ses scripts, ls, grep), Write (son rapport). Ni Edit, ni accès au web, ni sous-agents.
  • Modèle : Opus 5.5, effort high, fixé explicitement (D-042). À baisser si le coût ou la lenteur gênent.
  • omitClaudeMd: true : CLAUDE.md et D-045 citent déjà la buée probable et les deux épisodes ; l'agent les recopierait au lieu de les trouver. Ses règles sont reprises dans instructions.md, avec la liste des seules docs qu'il lit.
  • Limites, acceptées pour un outil de travail interne : Claude Code ne restreint ni Bash à outils/, ni Write à rapports/, ni Read à une liste de fichiers. Ces limites sont tenues par les instructions, pas par le code ; le rapport liste ce que l'agent a lu.

4. Méthode (instructions.md)

Entrée : un dossier de data/ et une question facultative. Sans question : scan de toute la période. Avec une question : enquête sur la fenêtre et les capteurs concernés, la période entière servant de référence.

Sources autorisées :

  • les données du dossier (CSV, images) ;
  • docs/domaine/colonnes-des-deplacements.md (formats des exports) et docs/domaine/pieges-des-donnees.md ;
  • les docs AIMsight, par section : chaîne de dépendance (§4), familles d'hypothèses (§12) et workflow (§13) de AIMsight_agentic_support_project_context.md ; classifications (§4.3) de AIMsight_reference_quality_event_explainer_roadmap.md ; la FAQ pour error (pdftotext).

Déroulé (d'après le §13 du contexte support) :

  1. Inventaire : ce qui est disponible, ce qui manque, ce que ce manque empêche de conclure.
  2. Repérage : par capteur, ce qui sort de l'ordinaire de ce capteur (son propre passé, pas un seuil absolu).
  3. Faits, par événement : début, fin, durée ; capteurs touchés (cibles ou références, combien, lesquels) ; amplitude, retour à la normale ; déplacement associé ou non ; images autour de l'instant.
  4. Hypothèses, dans les familles du §12 : événement externe (occlusion, eau ou buée, turbulence, éclairage), mouvement de l'ouvrage, mouvement de la caméra ou compensation, cible dégradée, problème système.
  5. Réfutation obligatoire de l'hypothèse principale : chercher le fait qui la contredirait, dire ce qu'on a trouvé.
  6. Rapport (§5).

Règles (reprises de CLAUDE.md) :

  • vocabulaire : confirmed / strongly supported / consistent with / possible / insufficient evidence / not observed ;
  • fait observé, fait dérivé, contexte donné par l'utilisateur, hypothèse et inconnu restent séparés ;
  • aucun seuil inventé : un seuil de repérage est annoncé comme choix d'exploration, jamais comme critère de conclusion ;
  • rien sur inlier ; sigma0 jamais suffisant seul ; un mouvement commun à toutes les cibles n'est pas un mouvement de l'ouvrage ; un trou n'est pas forcément une coupure ;
  • toute heure en UTC ; chaque preuve cite la commande qui l'a produite ;
  • « rien d'anormal » est une conclusion valable ;
  • lecture seule : n'écrire que son rapport ;
  • rapport en français, termes AIMsight en anglais.

5. Le rapport

agents/diagnostic/rapports/<AAAA-MM-JJ>_<STATION>[_<sujet>].md :

  1. En-tête : station, données fournies (dossier, période), question ou « scan », date, modèle.
  2. Sources lues : docs et fichiers ouverts.
  3. Inventaire : disponible, manquant, ce que le manque limite.
  4. Un bloc par événement :
    • classification, liste fermée : monitored-object motion, camera/reference compensation event, weak/unstable reference solution, model mismatch/parallax, target-local degradation (§4.3 de la roadmap), problème système, rien d'anormal, indéterminé ;
    • cause probable, à part : famille d'événement externe (buée ou eau, occlusion, turbulence, éclairage) ou inconnue ;
    • couche de la chaîne de dépendance, niveau de preuve ;
    • preuves, chacune avec sa commande ;
    • réfutation, alternatives, inconnus, prochaine vérification.
  5. Constats permanents : ce qui dure toute la période.
  6. Validation, laissée vide pour l'utilisateur : accepté tel quel ou corrigé (en quoi), diagnostic final. Un rapport validé deviendra un cas.

6. Outils (agents/diagnostic/outils/)

Scripts en ligne de commande. Ils renvoient des valeurs, jamais des verdicts. Bibliothèque standard, sauf le graphique.

Script Sortie
inventaire.py <dossier> Fichiers par type (« advanced », horaire, images), période, cadence, capteurs (cible ou référence, seuil d'erreur), trous de mesure, points rejetés par capteur, heures couvertes par les images
resume.py <dossier> [--colonne C] [--stat median|min|max] [--pas 1h] [--capteurs] [--debut] [--fin] Pour une colonne : le niveau habituel de chaque capteur sur la période (médiane, MAD, min, max), puis un tableau, une ligne par pas de temps et une colonne par capteur, avec la statistique choisie ; « rej » quand toutes les mesures du pas sont rejetées
graphique.py <dossier> [--capteurs] [--colonnes] [--debut] [--fin] Un PNG des séries dans out/diagnostic/, que l'agent regarde (matplotlib, .venv)
  • Un module de lecture de l'export « advanced », partagé par les trois scripts.
  • Images de la caméra : pas de script. L'agent trouve l'image d'une heure par son nom (images/AAAAMMJJTHH00Z_*.jpg) et la lit directement. Le recadrage viendra plus tard.

7. Vérification

Les outils, à la main (pas de tests automatisés, D-008) : sur data/PS_DES_COUDRES/, inventaire.py doit retrouver les chiffres établis à la main le 2026-10-14 : 525 mesures du 08/10 22:00Z au 14/10 09:45Z, 15 capteurs dont 3 références, cadence de 15 min, 3 mesures manquantes (09/10 12:00Z, 10/10 10:45Z, 14/10 09:30Z), PM_G rejetée aux 525 mesures, 24 images du 13/10 12:00Z au 14/10 11:00Z.

L'agent, à l'aveugle, sur PS des Coudres, en deux passages : un scan sans question ni contexte ; puis la question « que s'est-il passé dans la nuit du 13 au 14/10 ? ». Attendus, écrits avant le premier passage :

  1. les deux épisodes nocturnes de l'erreur de REF_G et REF_D : le 13/10 de ~01:00 à ~03:45Z, puis du 13/10 ~23:45Z au 14/10 ~04:45Z ;
  2. REF_CT et les 12 cibles non touchées ;
  3. aucune conclusion de mouvement de l'ouvrage, avec une réfutation explicite ;
  4. PM_G rejetée sur toute la période (seuil d'erreur de 0,3), en constat permanent ;
  5. les inconnus : pas de métriques système, images pour le second épisode seulement, pas de météo ;
  6. un niveau de preuve mesuré : une cause externe (buée ou autre) au plus strongly supported, pas confirmed sans la voir sur une image ;
  7. les 3 mesures manquantes non présentées comme des coupures.

Un attendu manqué ou une conclusion au-delà des preuves se corrige dans instructions.md, puis on relance.

Résultats du 2026-10-14. Lancement retenu : l'outil Agent (sous-agent diagnostic, prompt réduit au dossier et à la question). Un premier essai en mode non interactif (claude -p --agent diagnostic) n'était pas à l'aveugle : en session principale, omitClaudeMd n'est pas appliqué et l'agent a reçu CLAUDE.md (« buée probable le matin ») ; la règle Write(agents/diagnostic/rapports/**) n'a pas non plus reconnu le chemin. Rapports : agents/diagnostic/rapports/2026-10-14_PS_DES_COUDRES.md (scan) et …_nuit-13-14-10.md (question).

Attendu Scan Question
1. Deux épisodes REF_G / REF_D atteint : 13/10 01:15 → 02:45Z et 13/10 23:45Z → 14/10 03:30Z, bornes calées sur REF_G ; REF_D citée atteint : 13/10 23:45Z → 14/10 05:30Z ; la nuit précédente citée (« déjà vu »)
2. REF_CT et cibles non touchées atteint pour l'erreur. L'agent va plus loin : la compensation transmet l'épisode aux corr_x des cibles, sans mouvement de leurs positions brutes (BJ_G ≈ −0,4 à 03:45Z, vérifié). L'attendu était incomplet idem : marches synchrones des cibles à 00:00Z, 03:45Z et 05:30Z
3. Pas de mouvement de l'ouvrage, réfutation atteint (positions brutes des cibles sans marche) atteint
4. PM_G rejetée (constat permanent) atteint atteint (« seuil mal réglé ? », réflecteur visible sur l'image)
5. Inconnus atteint : pas de métriques système, pas d'image pour le premier épisode, pas de météo atteint
6. Niveau de preuve mesuré atteint : camera/reference compensation event strongly supported ; cause inconnue atteint : dégradation confirmed, compensation strongly supported, buée ou rosée possible
7. Mesures manquantes non présentées comme des coupures atteint (couche non établie sans métriques système) sans objet (hors fenêtre)
  • Coût et durée : scan 39 appels d'outils, 238 s, ~91 k tokens ; question 36 appels, 184 s, ~91 k tokens (l'outil Agent ne rend pas de coût en dollars). Essai non interactif : 41 tours, 235 s, 1,69 $.
  • Sources lues : conformes ; CLAUDE.md non lu ; seul le contexte git (branche, derniers commits) est fourni d'office, signalé, sans conclusion utile.
  • Corrections des instructions : une : signaler un contexte reçu sans l'avoir ouvert ; une commande Bash simple par appel (une boucle for avait été refusée).
  • À valider par l'utilisateur : la classification camera/reference compensation event (plutôt que target-local degradation), l'effet sur les cibles, et le cycle journalier de corr_y (mouvement thermique ou parallaxe, non tranché).

8. Documentation

  • D-046 dans docs/decisions.md : l'agent pilote, son lien avec D-027, D-042 et D-044, ses limites (§3).
  • CLAUDE.md : l'état, la carte du dépôt, la commande d'appel, matplotlib dans .venv. Rester sous 200 lignes en resserrant des lignes existantes.
  • .devcontainer/devcontainer.json : matplotlib à côté de plotly.
  • agents/diagnostic/README.md : court ; renvoie à ce document.

9. Laissé de côté pour l'instant

À ajouter quand le besoin apparaît, pas avant.

  • Métriques système (couleurs du jour livrées) : dès qu'une station a les deux types de données.
  • Recadrage autour d'un capteur (positions x, y de l'export) : pour voir un réflecteur à pleine résolution.
  • Base de cas : les rapports validés, chargés dans les instructions tant qu'ils y tiennent.
  • Plafond de tours ou de coût (maxTurns) : après la mesure d'un premier passage.
  • Commande /diagnostic (skill avec context: fork) par-dessus le sous-agent, si l'appel par @ gêne.
  • Brouillon de réponse au client (D-042) : quand le support s'en servira.
  • Passage au harnais par API (D-027, D-042) : quand l'agent devra tourner hors de Claude Code ou notifier.

10. Options écartées

  • Skill dans la conversation courante : il hériterait des hypothèses de la conversation et chargerait son contexte ; un diagnostic qu'on veut juger doit partir sans a priori.
  • Skill seul avec context: fork : tout vivrait caché sous .claude/, à l'écart de la doc du projet ; résultat en tâche de fond par défaut. Reste un ajout possible (§9).
  • Graphiques par plotly : un PNG demande kaleido, qui embarque un navigateur.
  • Pas de graphique : l'agent verrait mal les formes des séries (cycle jour/nuit, marche).