Files
Support-Agent/CLAUDE.md
T
maximeandClaude Opus 5.5 df9ab5cdae Add the exploratory report on a diagnostic agent framework
Record decision D-027: a server-side LLM agent layer next to the
unchanged deterministic rules, aimed at unknown anomalies and rule
edge cases. The agent annotates and never rewrites the day color.
Home-made harness (Messages API + Tool Runner), staged start with a
manual Energy pilot on VERMONT history. D-003 is partly replaced.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-12 17:41:42 +02:00

16 KiB
Raw Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Ce fichier est une carte, chargée à chaque session : il doit rester court (< 200 lignes). Le détail est dans docs/ et se lit quand on en a besoin.

Projet

Agent de diagnostic proactif pour AIMsight, un système de surveillance optique de déplacements : une caméra suit des cibles (prismes, réflecteurs) sur un ouvrage, et le mouvement de la caméra est compensé grâce à des cibles de référence. L'agent analyse les séries temporelles avec des méthodes analytiques (pas de LLM), complétées à l'étude par une couche d'agents LLM côté serveur (D-027), détecte les anomalies et explique chacune d'elles (preuves calculées + ce qui reste non établi) avant que le client ne pose la question. Cible d'exécution idéale : le système embarqué de la station. Langage : Python.

État et prochaine étape

  • 2026-10-09 : MOVING_AVERAGE_7_DAYS_DROP est en place sur VERMONT et produit un graphique HTML. C'est un prototype expérimental, sans tests automatisés.
  • Point ouvert de MOVING_AVERAGE_7_DAYS_DROP : l'accoutumance. Après plus de 30 jours de déficit, l'anomalie peut disparaître (voir sa fiche).
  • 2026-10-12 : MOVING_AVERAGE_7_DAYS_MIDNIGHT_UTC_DROP (suggestion d'un collègue) en place, en panneau sous la précédente pour comparer. Elle est bien moins bruitée (pire cas sain −0,04 V contre −0,16 V), mais plus tardive sur VERMONT : 1 h avant la première coupure, contre ~2,7 jours.
  • 2026-10-12, changement d'échelle (D-018) : les analyses suivantes donnent l'état de la batterie jour par jour, avec des seuils physiques du matériel, pour être utilisables dès l'installation. Phase C (état seul), puis phase B (niveaux gradués).
  • 2026-10-12 : DAILY_BATTERY_STATE en place (phase C, état seul).
  • 2026-10-12 : DAILY_BATTERY_TREND en place (tendance markovienne : chaque jour face à la veille, mieux / stable / pire).
  • 2026-10-12, recentrage (D-020) : le diagnostic énergétique livré ne retient que DAILY_BATTERY_STATE et DAILY_BATTERY_TREND, combinées par la matrice état × tendance de docs/energy/matrice-etat-tendance.drawio en une couleur par jour (vert / orange / rouge). Le manuel docs/energy/guide/diagnostic-energetique.md (brouillon) l'explique au client et au support.
  • 2026-10-12 (D-021) : graphique pour le site de monitoring (Plotly) : une seule figure, l'état en haut et la tendance dessous, écrite en page de démo et en JSON. La matrice est codée (src/energy/day_color.py, jours inconnus en gris), mais pas tracée (la bande de couleurs a été écartée).
  • 2026-10-12 (D-022, D-023) : maquettes du site en HTML sur données réelles (maquettes/user/ pour le client, maquettes/support/ pour le support ; Figma seulement sur demande). Maquette client « Energy » en place : section Diagnostic de la page System Summary. Tout ce qui va au site est en anglais, figure état × tendance comprise.
  • 2026-10-12 (D-024) : focus sur un jour, J et la veille seulement : src/energy/focus_jour.py (résumé des faits + graphique de 48 h), sélection des données dans day_color.focus().
  • 2026-10-12 (D-025) : maquette support « Home » en place : page d'accueil (toutes les stations) avec une section Status, une notification par station Orange ou Red, et un lien vers la vue client.
  • 2026-10-12 (D-026) : projet rangé par domaine (src/energy/, docs/energy/, code commun dans src/common/, documentation AIMsight dans docs/aimsight/). Les analyses ne sont plus numérotées : chacune est désignée par sa règle. Deux scripts Energy : daily.py (analyses livrées) et all_analyses.py (comparaison).
  • 2026-10-12 (D-027) : piste exploratoire d'une couche d'agents LLM côté serveur, en complément des règles (anomalies inconnues, cas limites des règles) : docs/agents/rapport-exploratoire.md. Rien n'est construit.
  • Prochaine étape : étape 1 du rapport d'agents (pilote manuel Energy sur l'historique de VERMONT, il faut une clé API Anthropic) ; mise en forme du manuel avec le plugin Interactive Docs (dans une autre conversation) ; choisir avec l'équipe du site le format d'intégration du graphique ; maquettes : poursuivre « Energy » côté client pas à pas, puis le côté support pas à pas (points ouverts dans D-022).

Analyses (domaine Energy)

Règle Question Statut Fiche
DAILY_BATTERY_STATE Chaque jour : pleine charge, charge partielle (incertain), sous le plateau ou aucune charge ? livrée (prototype, D-020) docs/energy/analyses/daily_battery_state.md
DAILY_BATTERY_TREND Chaque jour, face à la veille : mieux, stable ou pire (changement d'état, sinon écart de fin de nuit) ? livrée (prototype, D-020) docs/energy/analyses/daily_battery_trend.md
MOVING_AVERAGE_7_DAYS_DROP La tension moyenne sur 7 jours décroche-t-elle de son propre passé récent (> 0,2 V) ? comparaison seulement docs/energy/analyses/moving_average_7_days_drop.md
MOVING_AVERAGE_7_DAYS_MIDNIGHT_UTC_DROP Même question, sur la seule mesure de 00:00 UTC de chaque jour comparaison seulement docs/energy/analyses/moving_average_7_days_midnight_utc_drop.md

Pour créer une analyse : skill nouvelle-analyse (.claude/skills/nouvelle-analyse/).

Commandes

  • python3 src/energy/daily.py [données] : analyses livrées (DAILY_BATTERY_STATE, DAILY_BATTERY_TREND). Il écrit out/<STATION>_daily.html + .json (figure pour le site, D-021) et les ouvre dans le navigateur (via explorer.exe sous WSL). Défaut : data/. Il bascule seul sur .venv si plotly manque, comme tous les scripts plotly.
  • python3 src/energy/all_analyses.py [données] : les quatre analyses ensemble pour comparer (D-016), un panneau chacune, puis un graphique par série. Il écrit out/<STATION>_energy.html et l'ouvre.
  • python3 src/energy/focus_jour.py 27.09 : focus sur un jour et sa veille (D-024). Il affiche les faits de la couleur et écrit out/<STATION>_focus_<AAAA-MM-JJ>.html + .json, puis l'ouvre.
  • python3 maquettes/user/energy.py [début] [fin] : maquette client « Energy » (page System Summary, section Diagnostic, D-022), écrite dans out/maquette_user_energy.html et ouverte.
  • python3 maquettes/support/home.py [début] [fin] : maquette support « Home » (toutes les stations, section Status, D-025), écrite dans out/maquette_support_home.html et ouverte.

Documentation (à lire à la demande)

  • docs/decisions.md : journal des décisions projet, au format ADR allégé (statut, décision, pourquoi, options écartées, conséquence). Le lire avant de changer d'orientation ou de reproposer une option : elle a peut-être déjà été écartée.
  • docs/<domaine>/analyses/<règle>.md : fiche vivante de chaque analyse (principe, constantes et sources, résultats, limites, options écartées, historique). Modèle : .claude/skills/nouvelle-analyse/modele-fiche.md.
  • docs/domaine/ : le savoir métier commun, une note par question.
    • ce-que-mesure-la-station.md : format CSV, métriques et unités, consommation mesurée mais pas l'apport.
    • pieges-des-donnees.md : trou ≠ coupure, signatures d'une coupure, seuils absolus, cycle jour/nuit.
    • colonnes-des-deplacements.md : colonnes des déplacements (cas d'usage suivant).
  • docs/energy/domaine/ : le savoir métier Energy.
    • comment-se-comporte-la-batterie.md : LiFePO4, plateau et coude, table OCV, redémarrage à 12,6 V, capacité.
    • tensions-selon-l-etat-de-la-batterie.md : tensions et pentes en charge, pleine charge et décharge (VERMONT, collecteur, chimie).
    • cas-annotes-par-l-expert.md : diagnostics experts des 5 stations.
  • docs/agents/rapport-exploratoire.md : cadre d'agents de diagnostic LLM (D-027). Choix retenus, architecture, démarrage par étapes ; annexe A : pistes détaillées à revoir étape par étape.
  • docs/energy/guide/diagnostic-energetique.md : manuel du diagnostic énergétique, pour le client (partie 1) et le support (partie 2). À tenir à jour avec la matrice (docs/energy/matrice-etat-tendance.drawio) et les fiches DAILY_BATTERY_STATE et DAILY_BATTERY_TREND.
  • Règle de travail :
    • une décision projet prise en conversation donne une entrée dans docs/decisions.md ;
    • toute modification d'une analyse met à jour sa fiche dans le même changement ;
    • un savoir métier nouveau va dans docs/domaine/ (commun) ou docs/<domaine>/domaine/ ;
    • un changement de cap met à jour « État et prochaine étape » ci-dessus.
  • .claude/rules/analyses.md se charge seul quand Claude touche src/ ou docs/*/analyses/.
  • docs/superpowers/ : documents de travail superpowers (specs, plans). C'est un historique, non maintenu après coup, et ce n'est pas une référence. La spec d'une nouvelle analyse s'écrit directement dans sa fiche docs/<domaine>/analyses/<règle>.md ; le plan peut rester dans docs/superpowers/plans/.

Fichiers

  • README.md : point d'entrée pour un humain (lancer l'analyse, où trouver quoi). Tout le projet est versionné, sauf out/, .venv/ et __pycache__/ (D-014).
  • docs/aimsight/ : documentation AIMsight d'origine, à lire avant de concevoir. Ne pas re-demander à l'utilisateur ce qui y figure. Contenus non modifiés.
    • AIMsight_reference_quality_event_explainer_roadmap.md : référence qui fait autorité. Elle couvre la couche diagnostique commune, l'explainer d'événements, les classifications (§4.3) et l'API indépendante de l'estimateur (§10).
    • AIMsight_agentic_support_project_context.md : extension support. Contenu : chaîne de dépendance (§4), domaines dont la santé système (§5.1), règles épistémiques (§10), familles d'hypothèses (§12), format de sortie (§14-15), cas de régression (§16-17), cas d'usage (§23).
    • Les deux docs prévoient un LLM/agent pour la synthèse : la couche déterministe reste 100 % analytique ; la couche d'agents côté serveur (D-027) reprend cette idée, en exploration.
    • AIMsight FAQ.pdf et AIMsight Test Manual.pdf (ce dernier est en réalité le manuel de la station) : définitions des signaux et des colonnes CSV, alimentation, schedules. Pour les lire : pdftotext -layout "docs/aimsight/<fichier>.pdf" -.
    • collecteur_system_info.py : copie de référence du collecteur system_info embarqué (INA219, table OCV LiFePO4, compensation IR 0,34 Ω). Source des unités. Ne pas modifier.
  • data/ : jeu de travail = VERMONT seule, le seul dataset complet (les 7 métriques système, telles qu'extraites de la plateforme) + diagnostics experts (metadata.md, d.md). Les analyses tournent uniquement sur ce jeu.
  • data/archive/ : BusVoltage seule des autres stations (incomplètes), mises de côté le 2026-10-09. Non analysées ; ne pas les réintroduire sans demande.
  • src/ : un sous-dossier par domaine, plus le code commun (D-026).
    • src/common/ : stations.py (chargement des CSV, trous de mesure ; bibliothèque standard) et page.py (poste de dev : bascule .venv, ouverture dans le navigateur, AUTOSCALE_Y_JS).
    • src/energy/ : calcul embarquable, en bibliothèque standard et sans import de common/ : moving_average.py, battery_state.py, battery_trend.py et day_color.py (matrice, couleur du jour, focus J−1 / J). Scripts plotly du poste de dev : daily.py, all_analyses.py et focus_jour.py.
  • architecture.drawio : schéma d'architecture tenu par l'utilisateur. Ne pas le modifier sans demande.
  • maquettes/ : maquettes de page en HTML, sur données réelles (D-022), en deux blocs : user/ (client) et support/. Un script par design, ou directement le HTML. Figma seulement sur demande.

Principes (raisons, statuts et options écartées : docs/decisions.md)

  • Point d'entrée du POC : scan proactif d'un export. L'agent détecte les événements, les classe et explique chacun. Le mode « question de support » viendra ensuite, sur le même socle.
  • Premier cas d'usage : santé énergétique des stations. Ici, le trou de données est l'anomalie. L'interprétation des déplacements viendra ensuite.
  • Pas de LLM dans la couche déterministe (agents LLM côté serveur en exploration, D-027), pas de données synthétiques (ni CSV simulés, ni générateur de scénarios : refus explicite de l'utilisateur). Le code d'analyse est embarquable : bibliothèque standard, calcul léger.
  • Anomalie énergétique = régime non soutenable (l'apport ne couvre pas la consommation), pas une batterie basse. Une station débranchée avec une batterie pleine est déjà en anomalie.
  • Analyses combinées : chaque analyse est une preuve imparfaite, juste « dans la majorité des cas » ; la combinaison fait le diagnostic. Préférer des fenêtres larges (plusieurs jours, multiples de 24 h).
    • Contrat commun : run(series) -> {analysis, rule, points: [{t, value, anomaly, facts}]}. Calcul causal (le point t n'utilise que les données ≤ t). anomaly = None signifie UNKNOWN (exception : DAILY_BATTERY_STATE en phase C et DAILY_BATTERY_TREND, où None = pas de verdict ; l'UNKNOWN est dans facts.state ou facts.trend).
    • Une analyse seule conclut au plus consistent with.
  • Livrable : un graphique HTML par station. En haut, les analyses, un panneau chacune (courbes superposées, D-016) ; dessous, un graphique par série temporelle. Zoom dans le temps seulement, avec l'ordonnée recalée sur la plage visible (D-011, D-013).
  • Destinataire du diagnostic : le client final et l'ingénieur support, en couches (D-020).
  • Ouvert : architecture (à définir plus tard, ne pas la figer ici).

L'essentiel du domaine (détail : docs/domaine/)

  • Données : un CSV par station et par métrique, <STATION>_<Metric>_<début> to <fin>.csv, colonnes ,time_utc,metric, moyennes horaires en UTC. Une valeur vide signifie qu'il n'y a pas de mesure.
  • Unités : BusVoltage [V], BusCurrent [mA], Power [mW], ShuntVoltage [mV]. Ces trois dernières sont une seule mesure : la consommation. L'apport (panneau ou secteur) n'est pas mesuré.
  • Batterie LiFePO4 de 12,8 V :
    • entre 30 et 90 % de charge, la tension de nuit reste plate ; elle ne chute qu'au coude (~12,8 V, puis ~12,5 V) ;
    • sous 12 V, la station s'éteint et ne redémarre que vers ~12,6 V ;
    • ≥ 14,0 V dans la journée signale une charge complète.
  • Les seuils de tension absolus ne se transposent pas d'une station à l'autre : comparer la station à son propre passé. Exception : les seuils du matériel (fin de charge ~14,0 V, coude 12,8 V), admis pour les analyses d'état (D-018).
  • Un trou n'est pas forcément une coupure : retard de synchronisation en fin de fichier, début d'historique, cause commune si plusieurs stations ont un trou en même temps.

Règles non négociables

  • Chaque conclusion est traçable. Elle cite les faits calculés et la règle qui l'a produite. Aucun chiffre ni seuil sans source.
  • Ne pas confondre « pas de donnée visible » et « station arrêtée » : acquisition, transmission, ingestion et affichage sont des couches distinctes.
  • Ne rien construire sur inlier binaire : RANSAC sera remplacé par un estimateur pondéré. Utiliser poids continus, N_eff, résidus, influence.
  • sigma0 seul et le nombre de références ne sont jamais des critères suffisants.
  • Ne pas confondre qualité image d'une cible et qualité du réseau de références, ni petit résidu et transformation bien contrainte.
  • Ne pas confondre mouvement en mode commun et mouvement structurel, ni références cohérentes et références physiquement fixes.
  • Séparer fait observé, fait dérivé, contexte opérateur, hypothèse et inconnu. Pas de pseudo-probabilités ; vocabulaire : confirmed / strongly supported / consistent with / possible / insufficient evidence / not observed.
  • Pas de règle spécifique à un site : les cas résolus deviennent des cas de régression.
  • Lecture seule : aucune action sur les stations, la configuration ou le retraitement.

Environnement

  • pandas n'est pas installé ; la bibliothèque standard suffit pour explorer les CSV (csv, datetime.fromisoformat).
  • .venv/ (Python 3.14) ne contient que plotly, pour le poste de dev. Le code d'analyse reste en bibliothèque standard.
  • Prototype expérimental : pas de tests automatisés (D-008). Vérifier les changements à la main en lançant python3 src/energy/all_analyses.py (et daily.py pour le livré) sur VERMONT.

Conventions

  • Échanges et documents projet en français ; la documentation AIMsight est en anglais (garder ses termes techniques).