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

Qué hay de Nuevo en v2 (vs v1)

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

Puntuación de Confianza

La confianza evoluciona con el tiempo:

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