Continuous Learning v2.1 - Arquitectura basada en Instintos

¿Qué hace Continuous Learning v2.1 - Arquitectura basada en Instintos?

Un sistema de aprendizaje avanzado que convierte tus sesiones de Claude Code en conocimiento reutilizable a través de 'instintos' atómicos: pequeños comportamientos aprendidos con puntuación de confianza.

v2.1 añade instintos con alcance de proyecto — los patrones de React se quedan en tu proyecto React, las convenciones de Python se quedan en tu proyecto Python, y los patrones universales (como 'siempre validar entrada') se comparten globalmente.

Cuándo activarlo

• Configurar aprendizaje automático desde sesiones de Claude Code
• Configurar extracción de comportamiento basada en instintos mediante hooks
• Ajustar umbrales de confianza para comportamientos aprendidos
• Revisar, exportar o importar bibliotecas de instintos
• Evolucionar instintos en skills, comandos o agentes completos
• Gestionar instintos de alcance de proyecto vs globales
• Promover instintos de alcance de proyecto a global

Novedades en v2.1

Característica	v2.0	v2.1
Almacenamiento	Global (~/.claude/homunculus/)	Por proyecto (${XDG_DATA_HOME:-~/.local/share}/ecc-homunculus/projects/<hash>/)
Alcance	Todos los instintos aplican en todas partes	Por proyecto + global
Detección	Ninguna	URL remota git / ruta del repositorio
Promoción	N/A	Proyecto → global cuando se ve en 2+ proyectos
Comandos	4 (status/evolve/export/import)	6 (+promote/projects)
Contaminación cruzada	Riesgo de contaminación	Aislado por defecto

Novedades en v2 (vs v1)

Característica	v1	v2
Observación	Hook de fin (fin de sesión)	PreToolUse/PostToolUse (100% fiable)
Análisis	Contexto principal	Agente en segundo plano (Haiku)
Granularidad	Skills completos	Instintos atómicos
Confianza	Ninguna	0.3-0.9 ponderada
Evolución	Directo a skill	Instintos -> clúster -> skill/comando/agente
Compartición	Ninguna	Exportar/importar instintos

El Modelo de Instinto

Un instinto es un pequeño comportamiento aprendido:

---
id: prefer-functional-style
trigger: "al escribir nuevas funciones"
confidence: 0.7
domain: "code-style"
source: "session-observation"
scope: project
project_id: "a1b2c3d4e5f6"
project_name: "my-react-app"
---

# Preferir Estilo Funcional

## Acción
Usar patrones funcionales en lugar de clases cuando sea apropiado.

## Evidencia
- Observadas 5 instancias de preferencia por patrones funcionales
- El usuario corrigió un enfoque basado en clases por uno funcional el 2025-01-15

Propiedades:

• Atómico — un disparador, una acción
• Ponderado por confianza — 0.3 = tentativo, 0.9 = casi seguro
• Etiquetado por dominio — code-style, testing, git, debugging, workflow, etc.
• Respaldado por evidencia — registra qué observaciones lo crearon
• Consciente del alcance — project (por defecto) o global

Cómo funciona

Actividad de la sesión (en un repositorio git)
      |
      | Los hooks capturan prompts + uso de herramientas (100% fiable)
      | + detectan contexto del proyecto (git remote / ruta del repositorio)
      v
+---------------------------------------------+
|  projects/<hash-proyecto>/observations.jsonl  |
|   (prompts, llamadas a herramientas, resultados, proyecto) |
+---------------------------------------------+
      |
      | Agente observador lee (en segundo plano, Haiku)
      v
+---------------------------------------------+
|          DETECCIÓN DE PATRONES               |
|   * Correcciones del usuario -> instinto     |
|   * Resoluciones de errores -> instinto      |
|   * Flujos de trabajo repetidos -> instinto  |
|   * Decisión de alcance: proyecto o global?  |
+---------------------------------------------+
      |
      | Crea/actualiza
      v
+---------------------------------------------+
|  projects/<hash-proyecto>/instincts/personal/ |
|   * prefer-functional.yaml (0.7) [proyecto]  |
|   * use-react-hooks.yaml (0.9) [proyecto]    |
+---------------------------------------------+
|  instincts/personal/  (GLOBAL)               |
|   * always-validate-input.yaml (0.85) [global]|
|   * grep-before-edit.yaml (0.6) [global]     |
+---------------------------------------------+
      |
      | /evolve agrupa + /promote
      v
+---------------------------------------------+
|  projects/<hash>/evolved/ (alcance proyecto)  |
|  evolved/ (global)                           |
|   * commands/new-feature.md                  |
|   * skills/testing-workflow.md               |
|   * agents/refactor-specialist.md            |
+---------------------------------------------+

Detección de Proyecto

El sistema detecta automáticamente tu proyecto actual:

1. Variable de entorno CLAUDE_PROJECT_DIR (máxima prioridad) — respetada como anulación explícita incluso si el directorio no es un repositorio git (haseado por su ruta absoluta)
2. git remote get-url origin — haseado para crear un ID de proyecto portable (el mismo repositorio en diferentes máquinas obtiene el mismo ID)
3. git rev-parse --show-toplevel — fallback usando la ruta del repositorio (específico de la máquina)
4. Fallback global — si no se detecta ningún proyecto, los instintos van al alcance global

Cada proyecto recibe un ID hash de 12 caracteres (ej. a1b2c3d4e5f6). Un archivo de registro en ${XDG_DATA_HOME:-~/.local/share}/ecc-homunculus/projects.json mapea los IDs a nombres legibles.

Directorio de Datos

Continuous-learning-v2 almacena los datos del observador fuera de ~/.claude para que la protección de rutas sensibles de Claude Code no bloquee las escrituras del instinto en segundo plano:

1. CLV2_HOMUNCULUS_DIR cuando se establece a una ruta absoluta
2. $XDG_DATA_HOME/ecc-homunculus
3. $HOME/.local/share/ecc-homunculus

Los usuarios existentes con datos en ~/.claude/homunculus pueden migrar una vez:

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

Inicio Rápido

1. Habilitar Hooks de Observación

Si está instalado como plugin (recomendado):

No se requiere un bloque adicional de settings.json para hooks. Claude Code v2.1+ carga automáticamente el plugin hooks/hooks.json, y observe.sh ya está registrado allí.

Si anteriormente copiaste observe.sh en ~/.claude/settings.json, elimina ese bloque duplicado de PreToolUse / PostToolUse. Duplicar el hook del plugin causa doble ejecución y errores de resolución de ${CLAUDE_PLUGIN_ROOT} porque esa variable solo está disponible dentro de las entradas hooks/hooks.json gestionadas por el plugin.

Si está instalado manualmente en ~/.claude/skills, añade esto a tu ~/.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. Inicializar la Estructura de Directorios

El sistema crea los directorios automáticamente en el primer uso, pero también puedes crearlos manualmente:

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

# Los directorios de proyecto se crean automáticamente cuando el hook se ejecuta por primera vez en un repositorio git

3. Usar los Comandos de Instinto

/instinct-status     # Muestra los instintos aprendidos (proyecto + global)
/evolve              # Agrupa instintos relacionados en skills/comandos
/instinct-export     # Exporta instintos a un archivo
/instinct-import     # Importa instintos de otros
/promote             # Promueve instintos de proyecto a alcance global
/projects            # Lista todos los proyectos conocidos y sus recuentos de instintos

Comandos

Comando	Descripción
/instinct-status	Muestra todos los instintos (alcance proyecto + global) con confianza
/evolve	Agrupa instintos relacionados en skills/comandos, sugiere promociones
/instinct-export	Exporta instintos (filtrable por alcance/dominio)
/instinct-import <archivo>	Importa instintos con control de alcance
/promote [id]	Promueve instintos de proyecto a alcance global
/projects	Lista todos los proyectos conocidos y sus recuentos de instintos

Configuración

Edita config.json para controlar el observador en segundo plano:

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

Clave	Valor por defecto	Descripción
observer.enabled	false	Habilita el agente observador en segundo plano
observer.run_interval_minutes	5	Cada cuánto analiza el observador las observaciones
observer.min_observations_to_analyze	20	Mínimo de observaciones antes de ejecutar el análisis

Otros comportamientos (captura de observaciones, umbrales de instinto, alcance de proyecto, criterios de promoción) se configuran mediante valores por defecto en el código en instinct-cli.py y observe.sh.

Soporte de plataforma para el observador

El observador en segundo plano requiere WSL2, Linux o macOS. En Windows nativo (Git Bash / MSYS2) se inicia y reporta éxito, pero el proceso se elimina cuando el hook que lo creó termina y su Job Object se cierra, por lo que nunca se ejecuta ningún análisis — establecer observer.enabled: true allí es efectivamente una operación nula (ver issue #2489).

observe.sh detecta esto en la siguiente invocación del hook y escribe un mensaje de advertencia explicativo en observer-start.log una vez que el observador ha fallado en sobrevivir varias veces consecutivas.

Variable de entorno	Valor por defecto	Descripción
ECC_OBSERVER_NOSURVIVE_WARN_AFTER	3	Fallos consecutivos no supervivencia antes de registrar la advertencia

Estructura de Archivos

${XDG_DATA_HOME:-~/.local/share}/ecc-homunculus/
+-- identity.json           # Tu perfil, nivel técnico
+-- projects.json           # Registro: hash proyecto -> nombre/ruta/remoto
+-- observations.jsonl      # Observaciones globales (fallback)
+-- instincts/
|   +-- personal/           # Instintos globales auto-aprendidos
|   +-- inherited/          # Instintos globales importados
+-- evolved/
|   +-- agents/             # Agentes globales generados
|   +-- skills/             # Skills globales generados
|   +-- commands/           # Comandos globales generados
+-- projects/
    +-- a1b2c3d4e5f6/       # Hash del proyecto (de URL remota git)
    |   +-- project.json    # Espejo de metadatos por proyecto (id/nombre/root/remoto)
    |   +-- observations.jsonl
    |   +-- observations.archive/
    |   +-- instincts/
    |   |   +-- personal/   # Auto-aprendidos específicos del proyecto
    |   |   +-- inherited/  # Importados específicos del proyecto
    |   +-- evolved/
    |       +-- skills/
    |       +-- commands/
    |       +-- agents/
    +-- f6e5d4c3b2a1/       # Otro proyecto
        +-- ...

Guía de Decisión de Alcance

Tipo de Patrón	Alcance	Ejemplos
Convenciones de lenguaje/framework	proyecto	"Usar hooks de React", "Seguir patrones Django REST"
Preferencias de estructura de archivos	proyecto	"Tests en __tests__/", "Componentes en src/components/"
Estilo de código	proyecto	"Usar estilo funcional", "Preferir dataclasses"
Estrategias de manejo de errores	proyecto	"Usar tipo Result para errores"
Prácticas de seguridad	global	"Validar entrada de usuario", "Sanitizar SQL"
Mejores prácticas generales	global	"Escribir tests primero", "Siempre manejar errores"
Preferencias de flujo de trabajo con herramientas	global	"Hacer grep antes de editar", "Leer antes de escribir"
Prácticas de git	global	"Commits convencionales", "Commits pequeños y enfocados"

Promoción de Instintos (Proyecto -> Global)

Cuando el mismo instinto aparece en múltiples proyectos con alta confianza, es candidato para promoción a alcance global.

Criterios de auto-promoción:

• Mismo ID de instinto en 2+ proyectos
• Confianza promedio >= 0.8

Cómo promover:

# Promover un instinto específico
python3 instinct-cli.py promote prefer-explicit-errors

# Auto-promover todos los instintos que califiquen
python3 instinct-cli.py promote

# Vista previa sin cambios
python3 instinct-cli.py promote --dry-run

El comando /evolve también sugiere candidatos a promoción.

Puntuación de Confianza

La confianza evoluciona con el tiempo:

Puntuación	Significado	Comportamiento
0.3	Tentativo	Sugerido pero no aplicado
0.5	Moderado	Aplicado cuando es relevante
0.7	Fuerte	Auto-aprobado para aplicación
0.9	Casi seguro	Comportamiento central

La confianza aumenta cuando:

• El patrón se observa repetidamente
• El usuario no corrige el comportamiento sugerido
• Instintos similares de otras fuentes concuerdan

La confianza disminuye cuando:

• El usuario corrige explícitamente el comportamiento
• El patrón no se observa durante períodos prolongados
• Aparece evidencia contradictoria

¿Por qué Hooks vs Skills para Observación?

"v1 se basaba en skills para observar. Los skills son probabilísticos — se activan ~50-80% de las veces según el juicio de Claude."

Los hooks se activan el 100% de las veces, de manera determinista. Esto significa:

• Cada llamada a herramienta es observada
• No se pierden patrones
• El aprendizaje es completo

Compatibilidad hacia atrás

v2.1 es totalmente compatible con v2.0 y v1:

• Los instintos globales existentes pueden migrarse desde ~/.claude/homunculus/instincts/ con scripts/migrate-homunculus.sh
• Los skills existentes de v1 en ~/.claude/skills/learned/ siguen funcionando
• El hook de fin sigue ejecutándose (pero ahora también alimenta v2)
• Migración gradual: ejecuta ambos en paralelo

Privacidad

• Las observaciones se quedan locales en tu máquina
• Los instintos con alcance de proyecto están aislados por proyecto
• Solo se pueden exportar instintos (patrones) — no las observaciones brutas
• No se comparte ningún código ni contenido de conversación real
• Tú controlas qué se exporta y se promueve

Relacionados

• ECC-Tools GitHub App - Generar instintos desde el historial del repositorio
• Homunculus - Proyecto comunitario que inspiró la arquitectura basada en instintos v2 (observaciones atómicas, puntuación de confianza, canal de evolución de instintos)
• The Longform Guide - Sección de aprendizaje continuo

---

Aprendizaje basado en instintos: enseñando a Claude tus patrones, un proyecto a la vez.