Apprentissage continu v2.1 - Architecture basée sur les instinc…

Apprentissage continu v2.1 - Architecture basée sur les instincts

Un système d'apprentissage avancé qui transforme vos sessions Claude Code en connaissances réutilisables via des « instincts » atomiques – de petits comportements appris avec un score de confiance.

v2.1 ajoute les instincts limités au projet – les motifs React restent dans votre projet React, les conventions Python restent dans votre projet Python, et les motifs universels (comme « toujours valider les entrées ») sont partagés globalement.

Quand activer

• Mise en place de l'apprentissage automatique à partir des sessions Claude Code
• Configuration de l'extraction de comportements basée sur les instincts via des hooks
• Réglage des seuils de confiance pour les comportements appris
• Révision, exportation ou importation de bibliothèques d'instincts
• Transformation d'instincts en compétences, commandes ou agents complets
• Gestion des instincts limités au projet vs instincts globaux
• Promotion d'instincts du projet vers la portée globale

Nouveautés de la v2.1

Fonctionnalité	v2.0	v2.1
Stockage	Global (~/.claude/homunculus/)	Limité au projet (${XDG_DATA_HOME:-~/.local/share}/ecc-homunculus/projects/<hash>/)
Portée	Tous les instincts s'appliquent partout	Limité au projet + global
Détection	Aucune	URL git distante / chemin du dépôt
Promotion	N/A	Projet → global lorsqu'observé dans 2+ projets
Commandes	4 (status/evolve/export/import)	6 (+promote/projects)
Contamination inter-projets	Risque	Isolé par défaut

Nouveautés de la v2 (vs v1)

Fonctionnalité	v1	v2
Observation	Hook de fin (fin de session)	PreToolUse/PostToolUse (100% fiable)
Analyse	Contexte principal	Agent d'arrière-plan (Haiku)
Granularité	Compétences complètes	Instincts atomiques
Confiance	Aucune	Pondérée 0,3-0,9
Évolution	Directe vers compétence	Instincts -> cluster -> compétence/commande/agent
Partage	Aucun	Export/import d'instincts

Le modèle Instinct

Un instinct est un petit comportement appris :

---
id: prefer-functional-style
déclencheur: "lors de l'écriture de nouvelles fonctions"
confiance: 0.7
domaine: "code-style"
source: "session-observation"
portée: projet
project_id: "a1b2c3d4e5f6"
nom_projet: "my-react-app"
---

# Préférer le style fonctionnel

## Action
Utiliser des motifs fonctionnels plutôt que des classes lorsque c'est approprié.

## Preuves
- 5 instances d'une préférence pour les motifs fonctionnels observées
- L'utilisateur a corrigé une approche basée sur les classes pour une approche fonctionnelle le 2025-01-15

Propriétés :

• Atomique – un déclencheur, une action
• Pondéré par confiance – 0,3 = provisoire, 0,9 = presque certain
• Étiqueté par domaine – code-style, test, git, débogage, flux de travail, etc.
• Basé sur des preuves – suit les observations qui l'ont créé
• Conscient de la portée – projet (par défaut) ou global

Comment ça fonctionne

Activité de session (dans un dépôt git)
      |
      | Les hooks capturent les invites + utilisation d'outils (100% fiable)
      | + détectent le contexte du projet (git remote / chemin du dépôt)
      v
+---------------------------------------------+
|  projects/<hash-projet>/observations.jsonl   |
|   (invites, appels d'outils, résultats, projet) |
+---------------------------------------------+
      |
      | L'agent observateur lit (arrière-plan, Haiku)
      v
+---------------------------------------------+
|          DÉTECTION DE MOTIFS                 |
|   * Corrections utilisateur -> instinct      |
|   * Résolutions d'erreurs -> instinct        |
|   * Flux de travail répétés -> instinct      |
|   * Décision de portée : projet ou global ?  |
+---------------------------------------------+
      |
      | Crée/met à jour
      v
+---------------------------------------------+
|  projects/<hash-projet>/instincts/personal/  |
|   * prefer-functional.yaml (0.7) [projet]    |
|   * use-react-hooks.yaml (0.9) [projet]      |
+---------------------------------------------+
|  instincts/personal/  (GLOBAL)               |
|   * always-validate-input.yaml (0.85) [global]|
|   * grep-before-edit.yaml (0.6) [global]     |
+---------------------------------------------+
      |
      | /evolve clustérise + /promote
      v
+---------------------------------------------+
|  projects/<hash>/evolved/ (limité au projet) |
|  evolved/ (global)                           |
|   * commands/new-feature.md                  |
|   * skills/testing-workflow.md               |
|   * agents/refactor-specialist.md            |
+---------------------------------------------+

Détection de projet

Le système détecte automatiquement votre projet actuel :

1. Variable d'environnement CLAUDE_PROJECT_DIR (priorité la plus élevée) – honorée comme une substitution explicite même lorsque le répertoire n'est pas un dépôt git (haché par son chemin absolu)
2. git remote get-url origin – haché pour créer un ID de projet portable (le même dépôt sur différentes machines obtient le même ID)
3. git rev-parse --show-toplevel – solution de repli utilisant le chemin du dépôt (spécifique à la machine)
4. Solution de repli globale – si aucun projet n'est détecté, les instincts vont à la portée globale

Chaque projet obtient un ID de hachage de 12 caractères (ex. a1b2c3d4e5f6). Un fichier de registre à ${XDG_DATA_HOME:-~/.local/share}/ecc-homunculus/projects.json mappe les ID aux noms lisibles par l'humain.

Répertoire de données

Continuous-learning-v2 stocke les données d'observation en dehors de ~/.claude afin que la protection des chemins sensibles de Claude Code ne bloque pas les écritures d'instincts en arrière-plan :

1. CLV2_HOMUNCULUS_DIR lorsqu'il est défini sur un chemin absolu
2. $XDG_DATA_HOME/ecc-homunculus
3. $HOME/.local/share/ecc-homunculus

Les utilisateurs existants avec des données dans ~/.claude/homunculus peuvent migrer une fois :

bash skills/continuous-learning-v2/scripts/migrate-homunculus.sh

Démarrage rapide

1. Activer les hooks d'observation

S'il est installé comme plugin (recommandé) :

Aucun bloc settings.json supplémentaire n'est nécessaire. Claude Code v2.1+ charge automatiquement le plugin hooks/hooks.json, et observe.sh y est déjà enregistré.

Si vous avez précédemment copié observe.sh dans ~/.claude/settings.json, supprimez ce bloc PreToolUse / PostToolUse dupliqué. La duplication du hook plugin provoque une double exécution et des erreurs de résolution de ${CLAUDE_PLUGIN_ROOT} car cette variable n'est disponible que dans les entrées hooks/hooks.json gérées par le plugin.

S'il est installé manuellement dans ~/.claude/skills, ajoutez ceci à votre ~/.claude/settings.json :

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "*",
      "hooks": [{
        "type": "command",
        "command": "~/.claude/skills/continuous-learning-v2/hooks/observe.sh"
      }]
    }],
    "PostToolUse": [{
      "matcher": "*",
      "hooks": [{
        "type": "command",
        "command": "~/.claude/skills/continuous-learning-v2/hooks/observe.sh"
      }]
    }]
  }
}

2. Initialiser la structure de répertoires

Le système crée les répertoires automatiquement lors de la première utilisation, mais vous pouvez aussi les créer manuellement :

# Répertoires globaux
mkdir -p "${XDG_DATA_HOME:-$HOME/.local/share}/ecc-homunculus"/{instincts/{personal,inherited},evolved/{agents,skills,commands},projects}

# Les répertoires de projet sont créés automatiquement lorsque le hook est exécuté pour la première fois dans un dépôt git

3. Utiliser les commandes Instinct

/instinct-status     # Afficher les instincts appris (projet + global)
/evolve              # Clusteriser les instincts liés en compétences/commandes
/instinct-export     # Exporter les instincts vers un fichier
/instinct-import     # Importer les instincts d'autres personnes
/promote             # Promouvoir les instincts du projet vers la portée globale
/projects            # Lister tous les projets connus et leurs comptes d'instincts

Commandes

Commande	Description
/instinct-status	Afficher tous les instincts (limités au projet + globaux) avec confiance
/evolve	Clusteriser les instincts liés en compétences/commandes, suggérer des promotions
/instinct-export	Exporter les instincts (filtrable par portée/domaine)
/instinct-import <fichier>	Importer des instincts avec contrôle de la portée
/promote [id]	Promouvoir les instincts du projet vers la portée globale
/projects	Lister tous les projets connus et leurs comptes d'instincts

Configuration

Modifiez config.json pour contrôler l'observateur d'arrière-plan :

{
  "version": "2.1",
  "observer": {
    "enabled": false,
    "run_interval_minutes": 5,
    "min_observations_to_analyze": 20
  }
}

Clé	Par défaut	Description
observer.enabled	false	Activer l'agent observateur d'arrière-plan
observer.run_interval_minutes	5	À quelle fréquence l'observateur analyse les observations
observer.min_observations_to_analyze	20	Nombre minimum d'observations avant exécution de l'analyse

Les autres comportements (capture d'observation, seuils d'instinct, portée du projet, critères de promotion) sont configurés via les valeurs par défaut du code dans instinct-cli.py et observe.sh.

Support de plateforme de l'observateur

L'observateur d'arrière-plan nécessite WSL2, Linux ou macOS. Sur Windows natif (Git Bash / MSYS2), il démarre et signale un succès, mais le processus est tué lorsque le hook déclencheur se termine et que son objet Job se ferme, donc aucune analyse n'est jamais exécutée – définir observer.enabled: true y est effectivement une opération vide (voir issue #2489).

observe.sh détecte cela lors de l'invocation de hook suivante et écrit un avertissement explicatif dans observer-start.log une fois que l'observateur a échoué à survivre plusieurs fois de suite.

Variable d'environnement	Par défaut	Description
ECC_OBSERVER_NOSURVIVE_WARN_AFTER	3	Non-survies consécutives avant que l'avertissement soit enregistré

Structure de fichiers

${XDG_DATA_HOME:-~/.local/share}/ecc-homunculus/
+-- identity.json           # Votre profil, niveau technique
+-- projects.json           # Registre : hachage projet -> nom/chemin/distant
+-- observations.jsonl      # Observations globales (solution de repli)
+-- instincts/
|   +-- personal/           # Instincts globaux auto-appris
|   +-- inherited/          # Instincts globaux importés
+-- evolved/
|   +-- agents/             # Agents globaux générés
|   +-- skills/             # Compétences globales générées
|   +-- commands/           # Commandes globales générées
+-- projects/
    +-- a1b2c3d4e5f6/       # Hachage du projet (depuis l'URL git distante)
    |   +-- project.json    # Miroir des métadonnées par projet (id/nom/racine/distant)
    |   +-- observations.jsonl
    |   +-- observations.archive/
    |   +-- instincts/
    |   |   +-- personal/   # Auto-appris spécifique au projet
    |   |   +-- inherited/  # Importé spécifique au projet
    |   +-- evolved/
    |       +-- skills/
    |       +-- commands/
    |       +-- agents/
    +-- f6e5d4c3b2a1/       # Un autre projet
        +-- ...

Guide de décision de portée

Type de motif	Portée	Exemples
Conventions de langage/cadre	projet	"Utiliser les hooks React", "Suivre les motifs Django REST"
Préférences de structure de fichiers	projet	"Tests dans __tests__/", "Composants dans src/components/"
Style de code	projet	"Utiliser le style fonctionnel", "Préférer les dataclasses"
Stratégies de gestion d'erreurs	projet	"Utiliser le type Result pour les erreurs"
Pratiques de sécurité	global	"Valider les entrées utilisateur", "Nettoyer le SQL"
Meilleures pratiques générales	global	"Écrire les tests d'abord", "Toujours gérer les erreurs"
Préférences de flux de travail d'outils	global	"Grep avant Édition", "Lire avant Écrire"
Pratiques Git	global	"Commits conventionnels", "Petits commits ciblés"

Promotion d'instinct (Projet -> Global)

Lorsque le même instinct apparaît dans plusieurs projets avec une confiance élevée, il est candidat à la promotion vers la portée globale.

Critères de promotion automatique :

• Même ID d'instinct dans 2+ projets
• Confiance moyenne >= 0,8

Comment promouvoir :

# Promouvoir un instinct spécifique
python3 instinct-cli.py promote prefer-explicit-errors

# Promouvoir automatiquement tous les instincts éligibles
python3 instinct-cli.py promote

# Prévisualiser sans modifier
python3 instinct-cli.py promote --dry-run

La commande /evolve suggère également des candidats à la promotion.

Score de confiance

La confiance évolue avec le temps :

Score	Signification	Comportement
0,3	Provisoire	Suggéré mais non imposé
0,5	Modéré	Appliqué lorsque pertinent
0,7	Fort	Auto-approuvé pour application
0,9	Presque certain	Comportement de base

La confiance augmente lorsque :

• Le motif est observé de manière répétée
• L'utilisateur ne corrige pas le comportement suggéré
• Des instincts similaires provenant d'autres sources sont en accord

La confiance diminue lorsque :

• L'utilisateur corrige explicitement le comportement
• Le motif n'est pas observé pendant des périodes prolongées
• Des preuves contradictoires apparaissent

Pourquoi les hooks plutôt que les compétences pour l'observation ?

« v1 reposait sur les compétences pour observer. Les compétences sont probabilistes – elles se déclenchent ~50-80% du temps selon le jugement de Claude. »

Les hooks se déclenchent 100% du temps, de manière déterministe. Cela signifie :

• Chaque appel d'outil est observé
• Aucun motif n'est manqué
• L'apprentissage est complet

Rétrocompatibilité

v2.1 est entièrement compatible avec v2.0 et v1 :

• Les instincts globaux existants peuvent être migrés depuis ~/.claude/homunculus/instincts/ avec scripts/migrate-homunculus.sh
• Les compétences ~/.claude/skills/learned/ existantes de v1 fonctionnent toujours
• Le hook de fin s'exécute toujours (mais alimente maintenant aussi v2)
• Migration progressive : exécutez les deux en parallèle

Confidentialité

• Les observations restent locales sur votre machine
• Les instincts limités au projet sont isolés par projet
• Seuls les instincts (motifs) peuvent être exportés – pas les observations brutes
• Aucun code réel ou contenu de conversation n'est partagé
• Vous contrôlez ce qui est exporté et promu

Liens associés

• Application GitHub ECC-Tools – Générer des instincts à partir de l'historique du dépôt
• Homunculus – Projet communautaire qui a inspiré l'architecture basée sur les instincts de v2 (observations atomiques, score de confiance, pipeline d'évolution des instincts)
• Le guide Longform – Section apprentissage continu

---

Apprentissage basé sur les instincts : enseigner vos motifs à Claude, un projet à la fois.