- CLAUDE.md becomes a short map: status and next step, analyses index, documentation map, working rules. - docs/decisions.md: ADR-style project decision log (D-001..D-014). - docs/analyses/: living sheet per analysis (analyse_01) and template. - docs/domaine/: domain knowledge, one note per question. - .claude/rules/analyses.md: path-scoped rule loaded on src/ and docs/analyses/; .claude/skills/nouvelle-analyse: new-analysis workflow. - README.md: human entry point. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
10 KiB
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), 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 : l'analyse 01 est en place sur VERMONT et produit un graphique HTML. C'est un prototype expérimental, sans tests automatisés.
- Point ouvert de l'analyse 01 : l'accoutumance. Après plus de 30 jours de déficit, l'anomalie peut disparaître (voir sa fiche).
- Prochaine étape : choisir l'analyse 02 parmi les pistes de la fiche 01 (classement des trous, taux de jours à charge complète, perte secteur rapide, autonomie), puis combiner les analyses.
Analyses
| N° | Nom | Question | Statut | Fiche |
|---|---|---|---|---|
| 01 | MA7D_DROP |
La tension moyenne sur 7 jours décroche-t-elle de son propre passé récent (> 0,2 V) ? | prototype en place | docs/analyses/analyse_01.md |
Pour créer une analyse : skill nouvelle-analyse (.claude/skills/nouvelle-analyse/).
Commandes
python3 src/analyse_01.py: point d'entrée de l'analyse 01. Il analysedata/, écritout/<STATION>_energy.htmlet l'ouvre dans le navigateur (viaexplorer.exesous WSL). Il bascule seul sur.venvsi plotly manque.python3 src/energy_check.py data/: résumé texte +out/<STATION>_energy.json(out/est ignoré par git)..venv/bin/python src/energy_plot.py data/: graphique seul (plotly.js est chargé depuis le CDN).
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/analyses/analyse_NN.md: fiche vivante de chaque analyse (principe, constantes et sources, résultats, limites, options écartées, historique). Modèle :docs/analyses/_modele.md.docs/domaine/: le savoir métier, une note par question.ce-que-mesure-la-station.md: format CSV, métriques et unités, consommation mesurée mais pas l'apport.comment-se-comporte-la-batterie.md: LiFePO4, plateau et coude, table OCV, redémarrage à 12,6 V, capacité.pieges-des-donnees.md: trou ≠ coupure, signatures d'une coupure, seuils absolus, cycle jour/nuit.cas-annotes-par-l-expert.md: diagnostics experts des 5 stations.colonnes-des-deplacements.md: colonnes des déplacements (cas d'usage suivant).
- 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/; - un changement de cap met à jour « État et prochaine étape » ci-dessus.
- une décision projet prise en conversation donne une entrée dans
.claude/rules/analyses.mdse charge seul quand Claude touchesrc/oudocs/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 fichedocs/analyses/analyse_NN.md; le plan peut rester dansdocs/superpowers/plans/.
Fichiers
README.md: point d'entrée pour un humain (lancer l'analyse, où trouver quoi). Tout le projet est versionné, saufout/,.venv/et__pycache__/(D-014).doc/: documentation AIMsight, à lire avant de concevoir. Ne pas re-demander à l'utilisateur ce qui y figure.AIMsight_reference_quality_event_explainer_roadmap (2).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). Le doc de contexte la cite sans le suffixe « (2) ».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 : ne pas suivre ce point, le projet est 100 % analytique.
AIMsight FAQ.pdfetAIMsight 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 "doc/<fichier>.pdf" -.
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/:BusVoltageseule des autres stations (incomplètes), mises de côté le 2026-10-09. Non analysées ; ne pas les réintroduire sans demande.src/analyse_NN.py: point d'entrée de chaque analyse. Code partagé :src/energy_check.py(bibliothèque standard uniquement, embarquable) etsrc/energy_plot.py(plotly, poste de dev).src/__main__ (3).py: copie de référence du collecteursystem_infoembarqué (INA219, table OCV LiFePO4, compensation IR 0,34 Ω). Source des unités. Ne pas modifier.architecture.drawio: schéma d'architecture tenu par l'utilisateur. Ne pas le modifier sans 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, 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 = Nonesignifie UNKNOWN. - Une analyse seule conclut au plus
consistent with.
- Contrat commun :
- Livrable : un graphique HTML par station. En haut, l'analyse (courbes superposées) ; 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).
- Ouvert : architecture (à définir plus tard, ne pas la figer ici), destinataire du diagnostic (client final ou ingénieur support).
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é.
- 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
inlierbinaire : RANSAC sera remplacé par un estimateur pondéré. Utiliser poids continus,N_eff, résidus, influence. sigma0seul 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
pandasn'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/analyse_01.pysur VERMONT.
Conventions
- Échanges et documents projet en français ; la documentation AIMsight est en anglais (garder ses termes techniques).