Proposition : Système Modulaire CLAUDE.md

Date : 21/01/2026 18:18 Status : EN ATTENTE VALIDATION

Problème

Le fichier CLAUDE.md est devenu trop volumineux :

• 1355 lignes actuellement
• 24 sections principales
• Tout est chargé en mémoire même si pas nécessaire
• Pas de possibilité d'ajouter des sections à la demande

Solution : Système Modulaire à 3 Niveaux

Concept : Granularité intelligente

~/.claude/
├── CLAUDE.md              # NIVEAU 1 - Core (~200 lignes) - TOUJOURS chargé
│                          # Règles, workflow, chemins critiques
│
├── index/                 # NIVEAU 2 - Index transverses (~50-80 lignes chacun)
│   │                      # Vue d'ensemble, évite les doublons
│   ├── services.md        # TOUS les services existants (nom, rôle, port, état)
│   ├── machines.md        # TOUTES les machines (IP, rôle, accès)
│   ├── urls.md            # TOUTES les URLs actives
│   └── credentials-index.md  # Liste des credentials (sans valeurs)
│
└── memory/                # NIVEAU 3 - Détails complets - chargés à la demande
    ├── o2switch.md        # Détails O2switch (structure, crons, scripts)
    ├── notifications.md   # Détails stack notifications (endpoints, payloads)
    ├── stockage.md        # Détails ZFS, NFS, rsync
    ├── docker.md          # Détails stacks, conventions
    ├── cicd.md            # Détails GitLab, Smart-Deploy
    ├── logging.md         # Détails Loki, Promtail, requêtes
    ├── ai-tools.md        # Détails outils IA win11
    ├── credentials.md     # Valeurs complètes (sensible)
    └── ...                # Extensible

Les 3 niveaux

Exemple concret : "ajoute des notifications"

1. Je lis CLAUDE.md (toujours chargé) → Règles OK

2. Sujet "notifications" détecté → Je consulte AUTOMATIQUEMENT :
   - index/services.md → Je vois qu'il existe déjà :
     • ntfy (push notifications) - port 8080
     • apprise (gateway multi-canal) - port 8000
     • notif-logger (API dispatch) - port 5300

3. Je te réponds : "Il existe déjà une stack notifications.
   Tu veux utiliser l'existant ou autre chose ?"

4. Si besoin de détails → Je charge memory/notifications.md
   (endpoints, payloads, exemples curl)

Chargement proactif intelligent

Règle ajoutée dans CLAUDE.md core :

## Chargement proactif mémoire

Quand un sujet est abordé, AVANT de proposer une solution :
1. Consulter l'index correspondant (index/*.md)
2. Vérifier si un service/outil existe déjà
3. Si oui → proposer d'utiliser l'existant
4. Si besoin de détails → charger le module memory/*.md

Mapping sujet → index :
- notifications, alertes, mail, push → index/services.md + memory/notifications.md
- déploiement, CI/CD, pipeline → index/services.md + memory/cicd.md
- stockage, backup, ZFS, NFS → index/machines.md + memory/stockage.md
- docker, container, stack → index/services.md + memory/docker.md
- O2switch, backup externe → memory/o2switch.md
- IA, Ollama, ComfyUI → index/services.md + memory/ai-tools.md

Fichiers Index (Niveau 2)

index/services.md (~80 lignes) :

# Services Infrastructure 33800

## Stack Notifications
| Service | Port | Rôle | Machine |
|---------|------|------|---------|
| ntfy | 8080 | Push notifications | prod-portainer |
| apprise | 8000 | Gateway multi-canal | prod-portainer |
| notif-logger | 5300 | API logging + dispatch | prod-portainer |

## Stack Monitoring
| Service | Port | Rôle | Machine |
| grafana | 3000 | Dashboards | prod-portainer |
| loki | 3100 | Logs aggregation | prod-portainer |
| prometheus | 9090 | Metrics | prod-portainer |

## Stack IA
| Service | Port | Rôle | Machine |
| ai-orchestrator | 5501 | Queue jobs IA | prod-portainer |
| open-webui | 3001 | Interface Ollama | prod-portainer |
| ollama | 11434 | LLM inference | win11 |
...etc

index/machines.md (~50 lignes) :

# Machines Infrastructure 33800

| Machine | IP | Rôle | Accès |
|---------|-----|------|-------|
| PVE | 192.168.1.4 | Hyperviseur principal + Claude | ssh gouroubleu@pve.local |
| prod-portainer | 192.168.1.12 | Docker PROD | ssh gouroubleu@prod-portainer.local |
| nginx | 192.168.1.104 | Reverse proxy | ssh gouroubleu@nginx.local |
| win11 | 192.168.1.30 | GPU RTX 3090 | ssh gouro@win11.local |
...etc

Usage

Automatique (je fais moi-même) :

• Sujet détecté → Je consulte l'index correspondant
• Besoin de détails → Je charge le module memory/

Manuel (tu demandes) :

• "charge notifications" → Je lis memory/notifications.md
• "montre les services" → Je lis index/services.md
• "détails o2switch" → Je lis memory/o2switch.md

Analyse des doublons

Fichiers docs existants (1456 lignes total)

Doublons identifiés dans CLAUDE.md

Total doublons estimé : ~595 lignes (44%)

Proposition de restructuration

Nouveau CLAUDE.md (~500 lignes)

Garder UNIQUEMENT ce qui doit être en mémoire permanente :

CLAUDE.md (allégé)
├── Règles Obligatoires / Interdictions     (~50 lignes) - CRITIQUE
├── Credentials                              (~85 lignes) - CRITIQUE
├── Workflow Claude (procédures session)     (~50 lignes) - CRITIQUE
├── Symlinks et chemins                      (~20 lignes) - CRITIQUE
├── Convention nommage                       (~15 lignes)
├── Actions Disponibles (résumé)             (~30 lignes)
├── Quick Reference (IPs, URLs clés)         (~50 lignes) - NOUVEAU
├── O2switch Quick Reference                 (~40 lignes) - NOUVEAU
├── Références vers docs/                    (~30 lignes) - NOUVEAU
└── Notifications (endpoints)                (~30 lignes)

TOTAL ESTIMÉ : ~400-500 lignes

Nouveaux fichiers docs/

Mise à jour fichiers existants

Section O2switch complète (à ajouter)

Infos collectées

O2SWITCH - RÉSUMÉ COMPLET

Hébergement : yellow.o2switch.net
Domaine     : nowhere84.com
User SSH    : deas8499
cPanel      : https://yellow.o2switch.net:2083

Credentials :
- Username  : deas8499
- Password  : d9fx-RNEz-xfK(
- API Token : 3HW5KTGKHFAL889K9M2K9XJ4MU3D5SWV

SSH Config (~/.ssh/config) :
  Host o2switch
    HostName yellow.o2switch.net
    User deas8499
    IdentityFile ~/.ssh/o2switch_rsa

URLs publiques :
- https://dashboard.nowhere84.com    (Dashboard monitoring)
- https://status.nowhere84.com       (Page status)
- https://claude.nowhere84.com       (Viewer tasks/propositions)
- https://cdn.nowhere84.com          (Assets statiques)

Structure sur O2switch :
~/backup/
├── configs/        (rsync depuis PVE)
│   ├── claude/
│   ├── secrets/
│   ├── stacks/
│   └── scripts/
├── postgresql/     (pg_dump)
├── gitlab/         (tar backups)
└── claude/         (git)

~/public_html/
├── dashboard/      (git auto-deploy)
├── status/         (PHP)
├── claude/         (PHP viewer)
└── webhooks/       (PHP proxy)

~/repositories/
├── dashboard.git   (bare repo)
└── claude-docs.git (bare repo)

Crons synchronisation (sur PVE) :
- 0 */2 * * *   sync-configs-o2switch.sh  → ~/backup/configs/
- 0 */6 * * *   pg-to-o2switch.sh         → ~/backup/postgresql/
- 30 */6 * * *  gitlab-to-o2switch.sh     → ~/backup/gitlab/
- 0 * * * *     generate.sh (git push)    → ~/public_html/dashboard/

Cron sur O2switch :
- */5 * * * *   healthcheck.sh            → Alerte ntfy si services DOWN

Plan d'exécution

Phase 1 : Créer structure

mkdir -p ~/.claude/index/
mkdir -p ~/.claude/memory/

Phase 2 : Créer les INDEX (Niveau 2)

Total index : ~200 lignes

Phase 3 : Créer les MODULES détaillés (Niveau 3)

Total modules : ~1150 lignes (réparties)

Phase 4 : Réduire CLAUDE.md core (Niveau 1)

# CLAUDE.md Core

## Règles Obligatoires / Interdictions     (~50 lignes)
## Workflow Claude                          (~40 lignes)
## Symlinks et chemins                      (~20 lignes)
## Chargement proactif mémoire              (~30 lignes)  ← NOUVEAU
## Liste modules disponibles                (~20 lignes)
## Quick reference critique                 (~40 lignes)

TOTAL : ~200 lignes

Phase 5 : Backup et déploiement

# Backup
cp ~/.claude/CLAUDE.md ~/.claude/CLAUDE.md.backup-20260121

# Déployer nouveau CLAUDE.md
# Tester une session
# Rollback si nécessaire

Ordre de création recommandé

1. index/services.md - Le plus utile pour éviter doublons
2. index/machines.md - Référence IPs
3. memory/o2switch.md - Demandé initialement
4. memory/notifications.md - Exemple concret
5. Reste des modules progressivement

Corrélation Dashboard ↔ Index

Les fichiers index/ contiennent les mêmes données que le dashboard !

Source unique : config.json

/stock_8to/33800-stack/monitoring/config.json
              │
              ├──────────► generate.sh ──────────► Dashboard HTML
              │                                    (dashboard.nowhere84.com)
              │
              └──────────► generate-index.sh ────► Fichiers index/
                           (NOUVEAU)               (~/.claude/index/*.md)

Script generate-index.sh (à créer)

#!/bin/bash
# Génère les fichiers index/ depuis config.json

CONFIG="/stock_8to/33800-stack/monitoring/config.json"
INDEX_DIR="$HOME/.claude/index"

# Génère index/services.md depuis config.json.services
jq -r '.services | to_entries | .[] | "| \(.key) | \(.value.port) | \(.value.label) | \(.value.host) |"' $CONFIG > $INDEX_DIR/services.md

# Génère index/machines.md depuis config.json.hosts
jq -r '.hosts | to_entries | .[] | "| \(.key) | \(.value.ip) | \(.value.label) | \(.value.mdns // "-") |"' $CONFIG > $INDEX_DIR/machines.md

Avantages

1. Source unique : config.json = vérité
2. Toujours synchronisé : Dashboard et Index générés ensemble
3. Pas de désynchronisation : Une seule donnée à maintenir
4. Cron possible : generate.sh peut aussi régénérer les index/

Intégration dans generate.sh

# Dans /stock_8to/33800-stack/monitoring/generate.sh
# Ajouter à la fin :

echo "Generating Claude index files..."
./generate-index.sh

Ainsi, chaque fois que le dashboard est régénéré (toutes les heures), les fichiers index/ sont aussi mis à jour automatiquement.

Bénéfices attendus

Avantages du système modulaire

1. Chargement à la demande : Tu charges uniquement ce dont tu as besoin
2. Modules indépendants : Chaque sujet dans son fichier
3. Facile à étendre : Nouveau sujet = nouveau fichier dans memory/
4. Credentials isolés : Pas chargés par défaut, uniquement si besoin
5. Maintenance ciblée : Mise à jour d'un seul module sans toucher au reste

Commandes proposées

"charge o2switch"           → Lit ~/.claude/memory/o2switch.md
"charge machines docker"    → Lit les 2 modules
"charge credentials"        → Lit le module sensible
"liste modules"             → Affiche les modules disponibles
"décharge tout"             → Revient au core seulement

Risques

1. Oubli de charger un module : Je n'aurai pas l'info si pas chargé

   • Mitigation : Quick reference dans le core avec les infos essentielles
   • Mitigation : Je peux proposer de charger un module si pertinent

2. Désynchronisation : Les modules peuvent diverger de la réalité

   • Mitigation : Date de mise à jour dans chaque module

Validation requise

• [ ] Accord sur le concept de modules
• [ ] Accord sur la liste des modules proposés
• [ ] Accord pour commencer l'exécution

En attente de ta validation avant exécution.