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 añade instintos con ámbito 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 Activar
- Configurar aprendizaje automático desde sesiones de Claude Code
- Configurar extracción de comportamientos basados en instintos a través de hooks
- Ajustar umbrales de confianza para comportamientos aprendidos
- Revisar, exportar o importar bibliotecas de instintos
- Evolucionar instintos en habilidades, comandos o agentes completos
- Gestionar instintos de ámbito de proyecto vs globales
- Promover instintos de ámbito de proyecto a global
Novedades en v2.1
| Característica | v2.0 | v2.1 |
|---|---|---|
| Almacenamiento | Global (~/.claude/homunculus/) | Ámbito de proyecto (${XDG_DATA_HOME:-~/.local/share}/ecc-homunculus/projects/<hash>/) |
| Ámbito | Todos los instintos aplican en todas partes | Ámbito de proyecto + global |
| Detección | Ninguna | URL remota git / ruta de repositorio |
| Promoción | N/A | Proyecto → global cuando se ve en 2+ proyectos |
| Comandos | 4 (status/evolve/export/import) | 6 (+promote/projects) |
| Proyectos cruzados | Riesgo de contaminación | Aislado por defecto |
Novedades en v2 (vs v1)
| Característica | v1 | v2 |
|---|---|---|
| Observación | Hook de parada (fin de sesión) | PreToolUse/PostToolUse (100% fiable) |
| Análisis | Contexto principal | Agente en segundo plano (Haiku) |
| Granularidad | Habilidades completas | Instintos atómicos |
| Confianza | Ninguna | 0.3-0.9 ponderado |
| Evolución | Directo a habilidad | Instintos -> clúster -> habilidad/comando/agente |
| Compartición | Ninguna | Exportar/importar instintos |
El Modelo de Instinto
Un instinto es un pequeño comportamiento aprendido:
---
id: preferir-estilo-funcional
disparador: "al escribir nuevas funciones"
confianza: 0.7
dominio: "estilo-codigo"
fuente: "observacion-sesion"
alcance: proyecto
id_proyecto: "a1b2c3d4e5f6"
nombre_proyecto: "mi-app-react"
---
# Preferir Estilo Funcional
## Acción
Usar patrones funcionales en lugar de clases cuando sea apropiado.
## Evidencia
- Observadas 5 instancias de preferencia por patrón funcional
- El usuario corrigió un enfoque basado en clases a 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 — estilo-codigo, testing, git, depuracion, flujo-trabajo, etc.
- Respaldado por evidencia — rastrea qué observaciones lo crearon
- Consciente del ámbito —
proyecto(por defecto) oglobal
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 repo)
v
+---------------------------------------------+
| projects/<hash-proyecto>/observations.jsonl |
| (prompts, llamadas a herramientas, resultados, proyecto) |
+---------------------------------------------+
|
| El agente observador lee (segundo plano, Haiku)
v
+---------------------------------------------+
| DETECCIÓN DE PATRONES |
| * Correcciones del usuario -> instinto |
| * Resoluciones de errores -> instinto |
| * Flujos de trabajo repetidos -> instinto |
| * Decisión de ámbito: ¿proyecto o global? |
+---------------------------------------------+
|
| Crea/actualiza
v
+---------------------------------------------+
| projects/<hash-proyecto>/instincts/personal/ |
| * preferir-estilo-funcional.yaml (0.7) [proyecto] |
| * usar-hooks-react.yaml (0.9) [proyecto] |
+---------------------------------------------+
| instincts/personal/ (GLOBAL) |
| * siempre-validar-entrada.yaml (0.85) [global]|
| * grep-antes-de-editar.yaml (0.6) [global] |
+---------------------------------------------+
|
| /evolve agrupa + /promote promociona
v
+---------------------------------------------+
| projects/<hash>/evolved/ (ámbito proyecto) |
| evolved/ (global) |
| * commands/nueva-funcionalidad.md |
| * skills/flujo-testing.md |
| * agents/especialista-refactorizacion.md |
+---------------------------------------------+
Detección de Proyecto
El sistema detecta automáticamente tu proyecto actual:
- Variable de entorno
CLAUDE_PROJECT_DIR(máxima prioridad) — se respeta como anulación explícita incluso si el directorio no es un repositorio git (se hashea por su ruta absoluta) git remote get-url origin— se hashea para crear un ID de proyecto portable (el mismo repositorio en diferentes máquinas obtiene el mismo ID)git rev-parse --show-toplevel— alternativa usando la ruta del repositorio (específica de la máquina)- Alternativa global — si no se detecta ningún proyecto, los instintos van al ámbito 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 asigna 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 de instintos en segundo plano:
CLV2_HOMUNCULUS_DIRcuando se establece a una ruta absoluta$XDG_DATA_HOME/ecc-homunculus$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 se instaló como plugin (recomendado):
No se requiere ningún bloque adicional de settings.json hook. Claude Code v2.1+ carga automáticamente el plugin hooks/hooks.json, y observe.sh ya está registrado allí.
Si previamente copiaste observe.sh en ~/.claude/settings.json, elimina ese bloque duplicado de PreToolUse / PostToolUse. Duplicar el hook del plugin causa ejecución doble 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 se instaló 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 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 # Mostrar instintos aprendidos (proyecto + global)
/evolve # Agrupar instintos relacionados en habilidades/comandos
/instinct-export # Exportar instintos a un archivo
/instinct-import # Importar instintos de otros
/promote # Promover instintos de proyecto a ámbito global
/projects # Listar todos los proyectos conocidos y sus conteos de instintos
Comandos
| Comando | Descripción |
|---|---|
/instinct-status | Mostrar todos los instintos (ámbito proyecto + global) con confianza |
/evolve | Agrupar instintos relacionados en habilidades/comandos, sugerir promociones |
/instinct-export | Exportar instintos (filtrable por ámbito/dominio) |
/instinct-import <archivo> | Importar instintos con control de ámbito |
/promote [id] | Promover instintos de proyecto a ámbito global |
/projects | Listar todos los proyectos conocidos y sus conteos 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 | Habilitar el agente observador en segundo plano |
observer.run_interval_minutes | 5 | Cada cuánto el observador analiza 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, ámbito de proyecto, criterios de promoción) se configuran mediante valores predeterminados en el código de 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 e informa éxito, pero el proceso se elimina
cuando el hook que lo creó sale y su Objeto de Trabajo 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
una advertencia explicativa en observer-start.log una vez que el observador ha fallado al
sobrevivir varias veces seguidas.
| Variable de entorno | Valor por defecto | Descripción |
|---|---|---|
ECC_OBSERVER_NOSURVIVE_WARN_AFTER | 3 | Fallos consecutivos sin sobrevivir 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 de proyecto -> nombre/ruta/remoto
+-- observations.jsonl # Observaciones globales (alternativa)
+-- instincts/
| +-- personal/ # Instintos globales auto-aprendidos
| +-- inherited/ # Instintos globales importados
+-- evolved/
| +-- agents/ # Agentes globales generados
| +-- skills/ # Habilidades globales generadas
| +-- commands/ # Comandos globales generados
+-- projects/
+-- a1b2c3d4e5f6/ # Hash de proyecto (de URL remota git)
| +-- project.json # Espejo de metadatos por proyecto (id/nombre/raíz/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 Ámbito
| Tipo de Patrón | Ámbito | Ejemplos |
|---|---|---|
| Convenciones de lenguaje/framework | proyecto | "Usar hooks React", "Seguir patrones Django REST" |
| Preferencias de estructura de archivos | proyecto | "Pruebas 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 pruebas primero", "Siempre manejar errores" |
| Preferencias de flujo de trabajo de herramientas | global | "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 ámbito global.
Criterios de autopromoció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 preferir-errores-explicitos
# Autopromover 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 | Autoaprobado 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 durante períodos prolongados
- Aparece evidencia contradictoria
Por Qué Hooks vs Habilidades para la Observación
"v1 dependía de habilidades para observar. Las habilidades son probabilísticas: se activan ~50-80% de las veces según el juicio de Claude."
Los hooks se activan el 100% de las veces, de forma 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 se pueden migrar desde
~/.claude/homunculus/instincts/conscripts/migrate-homunculus.sh - Las habilidades existentes de v1 en
~/.claude/skills/learned/todavía funcionan - El hook de parada sigue ejecutándose (pero ahora también alimenta a v2)
- Migración gradual: ejecuta ambos en paralelo
Privacidad
- Las observaciones permanecen locales en tu máquina
- Los instintos con ámbito de proyecto están aislados por proyecto
- Solo se pueden exportar instintos (patrones), no observaciones en bruto
- No se comparte ningún código o contenido de conversación real
- Tú controlas qué se exporta y promociona
Relacionados
- Aplicación GitHub ECC-Tools - Generar instintos desde el historial del repositorio
- Homunculus - Proyecto comunitario que inspiró la arquitectura basada en instintos de v2 (observaciones atómicas, puntuación de confianza, pipeline de evolución de instintos)
- La Guía Extensa - Sección de aprendizaje continuo
Aprendizaje basado en instintos: enseñando a Claude tus patrones, un proyecto a la vez.