D-028: CLAUDE.md names every folder and document with its size in lines, says how to read without filling the context (outline of a long file then one section, index of the decision log, CSV by script, folders not to read), and gives the current state instead of a dated history. It and D-026 now name final.py for the delivered script. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
15 KiB
CLAUDE.md
Ce fichier est une carte du projet, chargée à chaque session : il dit ce qui existe et où, pas le détail. Il reste court (< 200 lignes, D-012). Le reste se lit à la demande, et seulement la partie utile (voir « Lire sans saturer le contexte »).
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 (au 2026-10-12)
L'état courant seulement ; l'historique est dans git log et docs/decisions.md.
- Energy, livré (prototype, D-020) :
DAILY_BATTERY_STATEetDAILY_BATTERY_TREND, combinées par la matrice état × tendance en une couleur par jour (vert / orange / rouge, gris si inconnu). Une figure Plotly pour le site (D-021 ; la matrice est codée mais pas tracée), un focus sur un jour et sa veille (D-024), un manuel en brouillon. - Energy, comparaison seulement : les deux moyennes glissantes sur 7 jours. Point ouvert : l'accoutumance après ~30 jours de déficit (fiche
moving_average_7_days_drop). - Maquettes du site (D-022) : client « Energy » (section Diagnostic de la page System Summary) ; support « Home » (section Status, une notification par station Orange ou Red, lien vers la vue client, D-025).
- Agents LLM côté serveur (D-027) : rapport exploratoire seulement, 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)
Code dans src/energy/, fiche dans docs/energy/analyses/<règle en minuscules>.md.
| Règle | Question | Statut | Code |
|---|---|---|---|
DAILY_BATTERY_STATE |
Chaque jour : pleine charge, charge partielle (incertain), sous le plateau ou aucune charge ? | livrée (prototype, D-020) | battery_state.py |
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) | battery_trend.py |
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 : ~2,7 jours d'avance sur la première coupure de VERMONT, mais bruitée (pire cas sain −0,16 V) | moving_average.py |
MOVING_AVERAGE_7_DAYS_MIDNIGHT_UTC_DROP |
Même question, sur la seule mesure de 00:00 UTC de chaque jour | comparaison : peu bruitée (−0,04 V), mais 1 h d'avance seulement | moving_average.py |
- Couleur du jour :
src/energy/day_color.py(MATRIX,focus()pour J−1 / J), transcription dedocs/energy/matrice-etat-tendance.drawio. - Travailler sur une analyse :
.claude/rules/analyses.md(contratrun(series), calcul causal, constantes sourcées, graphiques, fiche à jour) se charge seul dès qu'on touchesrc/oudocs/*/analyses/. - Créer une analyse : skill
nouvelle-analyse.
Commandes
python3 src/energy/final.py [données] # livré : out/<STATION>_daily.html + .json (figure du site, D-021)
python3 src/energy/all_analyses.py [données] # les 4 analyses comparées (D-016) : out/<STATION>_energy.html
python3 src/energy/focus_jour.py JJ.MM[.AAAA] [données] # un jour et sa veille (D-024) : faits + out/<STATION>_focus_<AAAA-MM-JJ>.html + .json
python3 maquettes/user/energy.py [début] [fin] # maquette client : out/maquette_user_energy.html
python3 maquettes/support/home.py [début] [fin] # maquette support : out/maquette_support_home.html
pdftotext -layout "docs/aimsight/<fichier>.pdf" - # lire un PDF AIMsight
python3 -m venv .venv && .venv/bin/pip install plotly # recréer .venv
[données]: CSV ou dossiers, défautdata/. Dates des maquettes enAAAA-MM-JJ, défaut 2026-09-18 à 2026-09-28 ; la maquette support mène à la maquette client : les lancer avec les mêmes dates.- Chaque script bascule seul sur
.venvsi plotly manque, puis ouvre sa page (navigateur Windows viaexplorer.exesous WSL). - Vérifier un changement : pas de tests automatisés (D-008). Lancer
all_analyses.py, etfinal.pypour le livré, sur VERMONT.
Carte du dépôt
Lire sans saturer le contexte
- Fichier long (tailles en lignes ci-dessous) : lire son plan (
grep -n '^#' <fichier>), puis la seule section utile (Read avecoffsetetlimit). docs/decisions.md: l'index estgrep -n '^## D-' docs/decisions.md; lire ensuite l'entrée citée seulement. Son Statut dit si elle est remplacée.- CSV de
data/: les explorer par script (common.stations.load_stations), jamais en les affichant. - Ne pas lire :
docs/superpowers/(historique),out/(sorties générées),.venv/.
Fichiers
README.md(40 l) : point d'entrée pour un humain.docs/decisions.md(300 l, D-001 à D-027) : décisions projet, au format ADR allégé (statut, décision, pourquoi, options écartées, conséquence). À consulter avant de changer d'orientation ou de reproposer une option : elle a peut-être déjà été écartée.docs/domaine/: savoir métier commun, une note courte (< 50 l) 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/: le domaine Energy.analyses/<règle>.md(80-120 l) : fiche vivante de chaque analyse (principe, constantes et sources, résultats, limites, options écartées, pistes, historique). Modèle :.claude/skills/nouvelle-analyse/modele-fiche.md.domaine/(< 80 l) :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) ;cas-annotes-par-l-expert.md(diagnostics experts des 5 stations, vérité de référence).guide/diagnostic-energetique.md(180 l, brouillon) : manuel, partie 1 pour le client (§1-4), partie 2 pour le support (§5-9). À tenir à jour avec la matrice et les fiches des deux analyses livrées.matrice-etat-tendance.drawio: matrice état × tendance, tenue par l'utilisateur.
docs/agents/rapport-exploratoire.md(290 l) : cadre d'agents LLM (D-027) : choix retenus, architecture, démarrage par étapes (§6) ; annexe A : pistes à revoir étape par étape. Le code d'agent vivra à part (agents/, proposé, pas créé).docs/aimsight/: documentation AIMsight d'origine, en anglais, non modifiée. À lire avant de concevoir, par section ; ne pas re-demander à l'utilisateur ce qui y figure.AIMsight_reference_quality_event_explainer_roadmap.md(1 180 l) : référence qui fait autorité : couche diagnostique commune, explainer d'événements, classifications (§4.3), API indépendante de l'estimateur (§10).AIMsight_agentic_support_project_context.md(2 090 l) : extension support : chaîne de dépendance (§4), domaines dont la santé système (§5.1, le cas d'usage actuel), 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,AIMsight Test Manual.pdf(en réalité le manuel de la station) : définitions des signaux et des colonnes CSV, alimentation, schedules.collecteur_system_info.py: copie de référence du collecteursystem_infoembarqué (INA219, table OCV LiFePO4, compensation IR 0,34 Ω). Source des unités. Ne pas modifier.
docs/superpowers/: specs et plans superpowers (170-850 l chacun). Historique non maintenu, pas une référence. La spec d'une nouvelle analyse s'écrit dans sa fiche ; le plan peut aller dansdocs/superpowers/plans/.data/: jeu de travail = VERMONT seule (D-009), le seul dataset complet : 7 CSV, un par métrique système (~5 000 l chacun). Les analyses tournent uniquement sur ce jeu.metadata.md(220 l) etd.md: notes brutes de l'expert, résumées danscas-annotes-par-l-expert.md.metadata.mdcontient aussi des identifiants techniques de station (SIM, IP) : le dépôt doit rester privé (D-014).archive/:BusVoltageseule de 4 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).common/:stations.py(chargement des CSV, trous de mesure ; bibliothèque standard) etpage.py(poste de dev : bascule.venv, ouverture dans le navigateur,AUTOSCALE_Y_JS).energy/: calcul embarquable, en bibliothèque standard et sans import decommon/:battery_state.py,battery_trend.py,moving_average.py,day_color.py. Scripts plotly du poste de dev, à laisser hors de la station :final.py,all_analyses.py,focus_jour.py.
maquettes/: maquettes du site en HTML sur données réelles (D-022), Figma seulement sur demande. Un script remplit son gabarit HTML :user/energy.py+energy_template.html(client),support/home.py+home_template.html(support)..claude/:rules/analyses.md(se charge seule, voir « Analyses »),skills/nouvelle-analyse/(procédure et modèle de fiche),settings.json(lecture de.envinterdite).architecture.drawio: schéma d'architecture tenu par l'utilisateur. Ne pas le modifier sans demande.out/: pages et JSON générés. Tout le projet est versionné, saufout/,.venv/et__pycache__/(D-014).
Règles 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) oudocs/<domaine>/domaine/. - Un changement de cap met à jour « État et prochaine étape » ci-dessus : l'état courant, pas un historique.
- Langue : échanges et documents projet en français ; documentation AIMsight en anglais (garder ses termes techniques) ; tout ce qui va au site en anglais, figure état × tendance comprise (D-023).
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 (pour Energy, la matrice état × tendance, D-020). Une analyse seule conclut au plus
consistent with. Préférer des fenêtres larges (plusieurs jours, multiples de 24 h). - Livrables : pour le site, une figure Plotly par station (état en haut, tendance dessous, D-021) et la couleur du jour ; pour comparer, une page HTML par station, un panneau par analyse puis un graphique par série (D-016). Zoom dans le temps seulement, ordonnée recalée sur la plage visible (D-013).
- Destinataires 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.
- 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.
- Pour les déplacements (cas d'usage suivant) :
- 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.
- ne rien construire sur
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.