CLAUDE.md : 6 couches pour Claude Code sans pertes

# Config Système Claude.md : 6 Couches pour un Contexte Impeccable en Claude Code

Claude Code démarre chaque session à zéro : pas de connaissance du projet, pas de détails sur le serveur, pas de correctifs passés. Cela entraîne des explications répétées et des risques — de la suppression de données de production à la publication de secrets dans le dépôt. La configuration CLAUDE.md de 582 lignes résout cela avec 6 couches : des règles aux hooks automatisés. Chaque couche est issue d'incidents réels.

Incidents qui ont Façonné l'Architecture

Trois déconvenues ont défini l'approche :

• SNI-proxy via localhost. L'agent a remplacé 127.0.0.1 par une IP réelle, cassant les uploads. Cause : aucune compréhension de l'importance de cette valeur spécifique.
• Verrouillage Fail2ban. Plusieurs connexions SSH en une minute ont été signalées comme une attaque par force brute, stoppant l'entraînement du modèle.
• Suppression de dataset. Une commande "filtre" a effacé des fichiers au lieu de les déplacer.

Leçons apprises : les règles doivent analyser les valeurs actuelles avant modification, imposer un seul tunnel SSH, et exiger une confirmation explicite pour les suppressions.

La Structure en 6 Couches

Couche 1 : Règles (9 fichiers)

Chargées contextuellement : les règles SSH n'encombrent pas les tâches textuelles, les règles de debug ignorent les guides de style.

Couche 2 : Mémoire (78 fichiers)

Graphe de connaissances avec 178 renvois croisés via [[nomfichier]]. Fichiers centraux toujours en contexte ; spécifiques au sujet chargés à la demande. Couvre infrastructure, correctifs et pièges.

Couche 3 : Passations

Résumés de sessions : objectif, réalisations, échecs, étapes suivantes. Exemple :

## Objectif de Session
Vérificateur de couleurs : balayage CNN + diffusion.

## Réalisé
- Baseline CNN : médiane 1,99 deg (11M params)
- Balayage : crop128(3,17), bs16(2,04)
- Diffusion : époque 5/50, perte 0,827

## Échecs
- EfficientNet-B0 : hash incohérent
- lr=3e-4 : NaN sans clipping

## Prochaines Étapes
Inférence pour diffusion + fiches visuelles.

27 passations sur 4 jours évitent de reprendre les impasses. Fonctionne entre abonnements.

Couche 4 : Chroniques

Chronologie des décisions : 3-7 lignes par jalon. Complète les passations avec l'historique complet.

Couche 5 : Hooks

Scripts Python automatisés déclenchés par événements (SessionStart, Stop, PreToolUse). Indépendants de la mémoire du modèle.

Exemple de hook de passation :

# remind_handoff.py (hook Stop)
age = session_age_minutes()
if age < 15 or fresh_handoff_exists():
    return
print(json.dumps({
    "decision": "block",
    "reason": f"Session {int(age)} min, pas de passation enregistrée."
}))

Couche 6 : Compétences (16 kits)

Guides déclenchés par événements : "utilisez ceci pour GPUs bloqués" au lieu d'instructions vagues.

Hooks vs Règles : Exécution Garantie

Les règles de prompt sont oubliées dans les longues sessions. Les hooks s'exécutent mécaniquement. Le hook de démarrage valide les liens CLAUDE.md ; celui de fin incite aux passations.

Défense de la Chaîne d'Approvisionnement : Config en Une Ligne

Dans .npmrc :

min-release-age=7

Bloque les paquets de moins de 7 jours. Nous a sauvés de l'attaque axios 1.14.1 (Sapphire Sleet, 31 mars 2026, fenêtre de 3h). Équivalent Python dans uv.toml :

exclude-newer = "7 days"

Principes Issus de 37 Articles de Recherche

Distillés en règles :

• Boucle de Preuve. Pas d'auto-confirmation : exigez des preuves externes (tests d'une session fraîche).
• Raisonnement Structuré. Format : faits → trace → conclusions → hypothèses vérifiées. Précision des patchs : 78 % → 93 %.
• Orchestration Déterministe. Tâches fixes (tests, linting) via scripts shell.
• Lignes Rouges. Interdictions strictes : "pas de suppressions sans confirmation", liées à des incidents spécifiques.

Autres : générateur-évaluateur, décomposition multi-agents, sécurité des agents.

Métriques et Auto-Mise à Jour

• 78 fichiers mémoire, 178 liens.
• 27 passations en 4 jours.
• 96,9 % de taux de hit KV-cache (83 sessions).

La config s'auto-valide : hook SessionStart vérifie les liens après édition.

Points Clés :

• Passations et Mémoire préviennent la perte de contexte entre sessions.
• Hooks garantissent les actions critiques.
• Boucliers chaîne d'approvisionnement : min-release-age=7 dans .npmrc / uv.toml.
• Raisonnement Structuré booste la précision debug à 93 %.
• Lignes Rouges réduisent les risques production.

Stack minimal : Orchestration Déterministe + Raisonnement Structuré + Défense Chaîne d'Approvisionnement + Passations.

Repo : github.com/AnastasiyaW/claude-code-config (MIT).

— Editorial Team