Apprentissage Continu v2.1

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 par 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

• Mettre en place l'apprentissage automatique à partir des sessions Claude Code
• Configurer l'extraction de comportements basée sur les instincts via des hooks
• Régler les seuils de confiance pour les comportements appris
• Examiner, exporter ou importer des bibliothèques d'instincts
• Faire évoluer les instincts en compétences, commandes ou agents complets
• Gérer les instincts par projet vs globaux
• Promouvoir les instincts du projet vers le périmètre global

Nouveautés de la v2.1

Fonctionnalité	v2.0	v2.1
Stockage	Global (~/.claude/homunculus/)	Par projet (${XDG_DATA_HOME:-~/.local/share}/ecc-homunculus/projects/<hash>/)
Périmètre	Tous les instincts s'appliquent partout	Par projet + global
Détection	Aucune	URL git remote / chemin du dépôt
Promotion	N/A	Projet → global lorsque vu dans 2+ projets
Commandes	4 (status/evolve/export/import)	6 (+promote/projects)
Inter-projets	Risque de contamination	Isolé par défaut

Nouveautés de la v2 (vs v1)

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

Le modèle d'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: "style-code"
source: "observation-session"
périmètre: projet
projet_id: "a1b2c3d4e5f6"
projet_nom: "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 de 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 la confiance — 0,3 = provisoire, 0,9 = quasi certain
• Étiqueté par domaine — style-code, test, git, débogage, workflow, etc.
• Basé sur des preuves — suit les observations qui l'ont créé
• Conscient du périmètre — projet (par défaut) ou global

Comment ça marche

Activité de session (dans un dépôt git)
      |
      | Les hooks capturent les invites + l'utilisation d'outils (fiable à 100 %)
      | + détection du contexte 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 de l'utilisateur -> instinct  |
|   * Résolutions d'erreurs -> instinct         |
|   * Workflows répétés -> instinct             |
|   * Décision de périmètre : 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 regroupe + /promote
      v
+---------------------------------------------+
|  projects/<hash>/evolved/ (par 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'env CLAUDE_PROJECT_DIR (priorité la plus élevée) — honoré comme remplacement explicite même si 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 dans le périmètre global

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

Répertoire de données

Apprentissage-Continu-v2 stocke les données d'observation en dehors de ~/.claude pour 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 avec 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

Si installé en tant que 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 déjà copié observe.sh dans ~/.claude/settings.json, supprimez ce bloc PreToolUse / PostToolUse en double. La duplication du hook du plugin provoque une double exécution et des erreurs de résolution ${CLAUDE_PLUGIN_ROOT} car cette variable n'est disponible que dans les entrées hooks/hooks.json gérées par le plugin.

Si 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 lors de la première exécution du hook dans un dépôt git

3. Utiliser les commandes d'instinct

/instinct-status     # Afficher les instincts appris (projet + global)
/evolve              # Regrouper les instincts associés en compétences/commandes
/instinct-export     # Exporter les instincts vers un fichier
/instinct-import     # Importer des instincts depuis d'autres sources
/promote             # Promouvoir les instincts du projet vers le périmètre global
/projects            # Lister tous les projets connus et leurs compteurs d'instincts

Commandes

Commande	Description
/instinct-status	Afficher tous les instincts (par projet + globaux) avec leur confiance
/evolve	Regrouper les instincts associés en compétences/commandes, suggérer des promotions
/instinct-export	Exporter les instincts (filtrable par périmètre/domaine)
/instinct-import <fichier>	Importer des instincts avec contrôle de périmètre
/promote [id]	Promouvoir les instincts du projet vers le périmètre global
/projects	Lister tous les projets connus et leurs compteurs 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	Fréquence d'analyse des observations par l'observateur
observer.min_observations_to_analyze	20	Nombre minimum d'observations avant le déclenchement de l'analyse

Les autres comportements (capture d'observations, seuils d'instincts, périmètres de 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 la plateforme pour l'observateur

L'observateur d'arrière-plan nécessite WSL2, Linux ou macOS. Sous Windows natif (Git Bash / MSYS2), il démarre et signale un succès, mais le processus est tué lorsque le hook qui l'a lancé se termine et que son objet Job se ferme, donc aucune analyse n'est jamais exécutée — activer observer.enabled: true dans ce cas est effectivement une opération nulle (voir le problème #2489).

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

Variable d'env	Par défaut	Description
ECC_OBSERVER_NOSURVIVE_WARN_AFTER	3	Nombre d'échecs de survie consécutifs avant que l'avertissement ne soit enregistré

Structure des fichiers

${XDG_DATA_HOME:-~/.local/share}/ecc-homunculus/
+-- identity.json           # Votre profil, niveau technique
+-- projects.json           # Registre : hash de projet -> nom/chemin/remote
+-- observations.jsonl      # Observations globales (solution de repli)
+-- instincts/
|   +-- personal/           # Instincts auto-appris globaux
|   +-- inherited/          # Instincts importés globaux
+-- evolved/
|   +-- agents/             # Agents générés globaux
|   +-- skills/             # Compétences générées globales
|   +-- commands/           # Commandes générées globales
+-- projects/
    +-- a1b2c3d4e5f6/       # Hash du projet (depuis l'URL git remote)
    |   +-- project.json    # Miroir des métadonnées par projet (id/nom/racine/remote)
    |   +-- 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 périmètre

Type de motif	Périmètre	Exemples
Conventions de langage/framework	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 », « Sanitiser le SQL »
Bonnes pratiques générales	global	« Écrire les tests d'abord », « Toujours gérer les erreurs »
Préférences de workflow d'outils	global	« Grep avant Éditer », « Lire avant Écrire »
Pratiques Git	global	« Commits conventionnels », « Petits commits ciblés »

Promotion d'instinct (Projet -> Global)

Lorsqu'un même instinct apparaît dans plusieurs projets avec une confiance élevée, il est candidat à la promotion vers le périmètre global.

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 qualifiés
python3 instinct-cli.py promote

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

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

Score de confiance

La confiance évolue au fil du temps :

Score	Signification	Comportement
0,3	Provisoire	Suggéré mais pas appliqué
0,5	Modéré	Appliqué lorsque pertinent
0,7	Fort	Approuvé automatiquement pour application
0,9	Quasi certain	Comportement fondamental

La confiance augmente lorsque :

• Le motif est observé à plusieurs reprises
• L'utilisateur ne corrige pas le comportement suggéré
• Des instincts similaires 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 ?

« La 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/ de v1 fonctionnent toujours
• Le hook stop continue de fonctionner (mais alimente désormais également v2)
• Migration progressive : exécutez les deux en parallèle

Confidentialité

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

Associé

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

---

Apprentissage par instincts : enseigner à Claude vos motifs, un projet à la fois.