Aprendizaje Continuo 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 agrega 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 la entrada") se comparten globalmente.

Cuándo Activar

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

Qué hay de Nuevo en v2.1

Característica	v2.0	v2.1
Almacenamiento	Global (~/.claude/homunculus/)	Con alcance de proyecto (${XDG_DATA_HOME:-~/.local/share}/ecc-homunculus/projects/<hash>/)
Alcance	Todos los instintos aplican en todas partes	Con alcance de proyecto + global
Detección	Ninguna	URL remota de 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)
Entre proyectos	Riesgo de contaminación	Aislado por defecto

Qué hay de Nuevo en v2 (vs v1)

Característica	v1	v2
Observación	Hook Stop (fin de sesión)	PreToolUse/PostToolUse (100% confiable)
Análisis	Contexto principal	Agente en segundo plano (Haiku)
Granularidad	Skills completos	"Instintos" atómicos
Confianza	Ninguna	Ponderada 0.3-0.9
Evolución	Directamente a skill	Instintos → cluster → skill/comando/agente
Compartir	Ninguno	Exportar/importar instintos

El Modelo de Instinto

Un instinto es un pequeño comportamiento aprendido:

---
id: prefer-functional-style
trigger: "when writing new functions"
confidence: 0.7
domain: "code-style"
source: "session-observation"
scope: project
project_id: "a1b2c3d4e5f6"
project_name: "my-react-app"
---

# Prefer Functional Style

## Action
Use functional patterns over classes when appropriate.

## Evidence
- Observed 5 instances of functional pattern preference
- User corrected class-based approach to functional on 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 — rastrea qué observaciones lo crearon
• Consciente del alcance — project (por defecto) o global

Cómo Funciona

Actividad de Sesión (en un repositorio git)
      |
      | Los hooks capturan prompts + uso de herramientas (100% confiable)
      | + detectan contexto del proyecto (git remote / ruta del repo)
      v
+---------------------------------------------+
|  projects/<project-hash>/observations.jsonl  |
|   (prompts, llamadas de herramientas, resultados, proyecto)   |
+---------------------------------------------+
      |
      | El agente observador lee (segundo plano, Haiku)
      v
+---------------------------------------------+
|          DETECCIÓN DE PATRONES               |
|   * Correcciones de usuario -> instinto      |
|   * Resoluciones de errores -> instinto      |
|   * Flujos de trabajo repetidos -> instinto  |
|   * Decisión de alcance: ¿proyecto o global? |
+---------------------------------------------+
      |
      | Crea/actualiza
      v
+---------------------------------------------+
|  projects/<project-hash>/instincts/personal/ |
|   * prefer-functional.yaml (0.7) [project]   |
|   * use-react-hooks.yaml (0.9) [project]     |
+---------------------------------------------+
|  instincts/personal/  (GLOBAL)               |
|   * always-validate-input.yaml (0.85) [global]|
|   * grep-before-edit.yaml (0.6) [global]     |
+---------------------------------------------+
      |
      | /evolve clusters + /promote
      v
+---------------------------------------------+
|  projects/<hash>/evolved/ (project-scoped)   |
|  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)
2. git remote get-url origin — hasheado para crear un ID de proyecto portable (el mismo repo en diferentes máquinas obtiene el mismo ID)
3. git rev-parse --show-toplevel — respaldo usando la ruta del repo (específica de la máquina)
4. Respaldo global — si no se detecta ningún proyecto, los instintos van al alcance global

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

Directorio de Datos

Continuous-learning-v2 almacena los datos del observador fuera de ~/.claude para que el guard de rutas sensibles de Claude Code no bloquee las escrituras de instintos 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 bloque extra de hooks en settings.json. Claude Code v2.1+ carga automáticamente el hooks/hooks.json del plugin, y observe.sh ya está registrado allí.

Si está instalado manualmente en ~/.claude/skills, agregar 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. Usar los Comandos de Instinto

/instinct-status     # Mostrar instintos aprendidos (proyecto + global)
/evolve              # Agrupar instintos relacionados en skills/comandos
/instinct-export     # Exportar instintos a archivo
/instinct-import     # Importar instintos de otros
/promote             # Promover instintos de proyecto a alcance global
/projects            # Listar todos los proyectos conocidos y sus conteos de instintos

Guía de Decisión de Alcance

Tipo de Patrón	Alcance	Ejemplos
Convenciones de lenguaje/framework	project	"Usar React hooks", "Seguir patrones Django REST"
Preferencias de estructura de archivos	project	"Pruebas en __tests__/", "Componentes en src/components/"
Estilo de código	project	"Usar estilo funcional", "Preferir dataclasses"
Estrategias de manejo de errores	project	"Usar tipo Result para errores"
Prácticas de seguridad	global	"Validar entrada de usuario", "Sanitizar SQL"
Buenas prácticas generales	global	"Escribir pruebas primero", "Siempre manejar errores"
Preferencias de flujo de trabajo de herramientas	global	"Grep antes de Edit", "Read antes de Write"
Prácticas de Git	global	"Conventional commits", "Commits pequeños y enfocados"

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 coinciden

La confianza disminuye cuando:

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

Privacidad

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