← Volver al listado de tecnologías ← Índice de Everything Claude Code

Capítulo 9: Aprendizaje Continuo e Instincts

Por: Artiko
claude-codeaprendizajeinstinctscontinuous-learning

1. El Problema del Conocimiento Efímero

Cada sesión de Claude Code empieza desde cero. No importa cuántas veces le hayas explicado que en tu proyecto usás pnpm en lugar de npm, o que el equipo prefiere async/await sobre .then(), o que las migraciones de base de datos siempre van acompañadas de un test de rollback. La próxima sesión, empieza de cero.

Esto no es un bug. Es una característica del modelo de lenguaje: sin estado externo, no hay memoria persistente. Pero para un desarrollador que trabaja todos los días en el mismo proyecto, es una fricción enorme.

El costo real de repetir contexto

Imagina este escenario. Estás trabajando en una aplicación React Native. Has aprendido, después de varios intentos, que cuando hay un error de metro bundler, el primer paso es siempre limpiar la caché con npx react-native start --reset-cache. Pero cada sesión nueva, Claude Code intenta primero reiniciar el servidor, luego verificar la configuración de babel, luego revisar el archivo package.json. Tres o cuatro pasos antes de llegar a la solución que ya sabés que funciona.

Multiplicá eso por cada patrón aprendido: convenciones de naming, estructura de carpetas, dependencias problemáticas, comandos de deploy, patrones de testing, estilos de código. Cada uno de esos patrones requiere ser re-explicado, o re-descubierto, en cada sesión.

El costo no es solo tokens. Es tiempo de tu atención. Es la interrupción de un flujo de trabajo. Es la frustración de tener que repetirte.

Tres capas del problema

Capa 1: Contexto del proyecto. Las convenciones específicas de tu codebase que no están documentadas en ningún lado porque “todo el equipo ya las sabe”. El tipo de cosas que le explicarías a un developer nuevo en sus primeros dos días.

Capa 2: Patrones de trabajo. Tu forma específica de atacar ciertos tipos de problemas. No es que haya una sola forma correcta, es que vos tenés una preferencia establecida que produce buenos resultados en tu contexto.

Capa 3: Conocimiento errático. Problemas que encontraste una vez, investigaste durante una hora, y resolviste. Si no lo documentaste en el momento, ese conocimiento desaparece. La próxima vez que Claude Code encuentre el mismo error, va a repetir el mismo proceso de hora de investigación.

Cómo ECC resuelve esto

Everything Claude Code (ECC) introduce el sistema de Continuous Learning: un mecanismo que observa tus sesiones, detecta patrones, y persiste ese conocimiento en una forma reutilizable.

La solución opera en tres niveles:

  1. Observación pasiva: hooks que capturan lo que pasa durante la sesión sin interrumpir el trabajo
  2. Análisis en background: un agente separado (ligero, Haiku) procesa las observaciones sin consumir tokens del contexto principal
  3. Persistencia estructurada: el conocimiento se guarda como “instincts” atómicos, con metadatos de confianza y evidencia

El resultado: después de algunas semanas de uso, Claude Code en tu proyecto opera con el contexto implícito de meses de trabajo colaborativo.

2. Continuous Learning v1: La Primera Versión

Antes de entrar en la arquitectura actual, vale entender de dónde vino. La v1 del sistema de aprendizaje continuo fue un primer intento sólido que estableció los conceptos base.

El hook Stop

La v1 usaba el hook Stop de Claude Code: un gancho que se ejecuta una sola vez, al final de la sesión, cuando el usuario cierra la conversación.

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/skills/continuous-learning/on-stop.sh"
          }
        ]
      }
    ]
  }
}

Por qué Stop y no UserPromptSubmit: La alternativa obvia hubiera sido correr el análisis en cada mensaje. Pero eso agrega latencia perceptible a cada interacción. El hook Stop corre una sola vez al final de la sesión, invisible al usuario.

El comando /learn

La v1 exponía un comando manual:

/learn    # Analizar la sesión actual y extraer patrones

Cuando ejecutabas /learn, el skill tomaba el historial de la sesión y ejecutaba un análisis buscando:

Formato del output de /learn

La v1 generaba skills completos. Un skill es un archivo .md con instrucciones detalladas sobre cómo manejar una situación específica:

---
name: fix-metro-bundler
description: Resolución estándar para errores de Metro bundler en React Native
---

# Fix Metro Bundler

Cuando aparece un error de Metro bundler, el orden de pasos es:

1. Primero: `npx react-native start --reset-cache`
2. Si persiste: `watchman watch-del-all`
3. Si persiste: eliminar `node_modules/.cache`

## Cuándo aplicar
- Error: "Unable to resolve module"
- Error: "Metro has encountered an error"
- Bundler que no responde

Limitaciones de la v1

La v1 tenía problemas fundamentales que la segunda versión resuelve:

Granularidad excesiva. Un skill completo es una unidad de conocimiento demasiado grande. La mayoría del conocimiento que vale la pena capturar es más pequeño: una preferencia, una convención, un paso de un proceso. Convertirlo todo en skills completos creaba archivos extensos con mucho ruido.

Confianza binaria. O algo era un skill o no lo era. No había forma de representar “vi esto dos veces, probablemente sea un patrón” vs “vi esto veinte veces, estoy seguro”.

Sin scope de proyecto. Un patrón aprendido en tu proyecto React Native se mezclaba con patrones de tu proyecto Rust. El conocimiento era global por defecto.

Hook Stop no confiable. Si Claude Code crasheaba o la sesión terminaba abruptamente, el hook Stop no se ejecutaba. Perdías el análisis de toda esa sesión.

3. De Skills a Instincts: La Evolución Conceptual

La segunda versión introduce un concepto nuevo: el instinct.

Por qué skills completos son granularidad excesiva

Pensemos cómo aprende un developer humano. Cuando sos nuevo en un proyecto, no aprendés en unidades de “documentos de cinco páginas”. Aprendés en fragmentos pequeños:

Estos son instincts. Pequeñas piezas de conocimiento contextual que, acumuladas, te convierten en un contributor efectivo del proyecto.

La metáfora del aprendizaje humano

Un desarrollador senior en su propio proyecto tiene miles de estos instincts internalizados. No los puede listar todos. No los tiene documentados. Pero los aplica automáticamente, sin pensar, porque los observó y los reforzó a lo largo del tiempo.

Cuando le explicás a un developer nuevo cómo funciona el proyecto, lo que hacés es transferir los instincts más importantes. No les das un documento de 50 páginas. Les das los 20 instincts que más impactan en el día a día.

El sistema de Continuous Learning v2 hace exactamente eso: observa tu sesión con Claude Code y extrae los instincts implícitos que se manifiestan en cómo trabajás.

Qué es un instinct atómico

Un instinct es una unidad de conocimiento con estas propiedades:

4. Continuous Learning v2: Arquitectura de Instincts

La versión 2 es una reescritura completa del sistema. Las mejoras son fundamentales, no incrementales.

Las 6 mejoras vs v1

graph LR
    A[v1] --> B[v2]

    subgraph v1
        A1[Stop hook]
        A2[Análisis en contexto]
        A3[Skills completos]
        A4[Sin confianza]
        A5[Evolución directa]
        A6[Sin sharing]
    end

    subgraph v2
        B1[PreToolUse/PostToolUse]
        B2[Background agent Haiku]
        B3[Instincts atómicos]
        B4[Confianza 0.3-0.9]
        B5[Instincts → cluster → skill]
        B6[Export/import JSON]
    end

Mejora 1: Observación durante la sesión (no al final)

En v2, los hooks PreToolUse y PostToolUse capturan cada tool call durante la sesión. Esto es 100% confiable: si Claude Code usa una herramienta, la observación se registra. No importa si la sesión termina abruptamente.

Mejora 2: Análisis en background con Haiku

El análisis no corre en el contexto principal. Corre en un agente separado que usa claude-haiku, el modelo más rápido y económico. Esto significa cero impacto en los tokens del contexto principal y cero latencia perceptible.

Mejora 3: Granularidad atómica

En vez de generar un skill completo, el sistema genera instincts individuales. Un skill de v1 sobre “cómo debuggear el proyecto” se convierte en v2 en 8-12 instincts específicos, cada uno con su propio score de confianza.

Mejora 4: Sistema de confianza

Cada instinct tiene un score numérico. Un instinct observado por primera vez empieza en 0.3. Con más evidencia, sube. Con contradicciones, baja. Solo los instincts con confianza suficiente evolucionan a skills.

Mejora 5: Pipeline de evolución

El camino de instinct a skill no es directo. Los instincts relacionados se agrupan en clusters. Un cluster con suficiente confianza puede evolucionar a un skill, un comando personalizado, o incluso un agente especializado.

Mejora 6: Sharing estructurado

Los instincts se pueden exportar a JSON y compartir. Un developer senior puede exportar sus instincts de proyecto, un nuevo member los importa, y empieza con semanas de contexto pre-cargado.

Por qué PreToolUse/PostToolUse en vez de Stop

El hook Stop tiene un problema de confiabilidad: solo corre si la sesión termina limpiamente. Un crash, una desconexión de red, cerrar la terminal accidentalmente — cualquiera de estos eventos hace que el hook Stop no se ejecute.

PreToolUse y PostToolUse corren sincronizados con cada tool call durante la sesión. Si Claude Code ejecuta un bash command, los hooks se activan. Si Claude Code lee un archivo, los hooks se activan. El 100% de las tool calls queda registrado.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": ".*",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/skills/continuous-learning-v2/pre-tool.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": ".*",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/skills/continuous-learning-v2/post-tool.sh"
          }
        ]
      }
    ]
  }
}

5. Anatomía Completa de un Instinct

Un instinct es un archivo YAML con una estructura definida. Entender cada campo es fundamental para saber cómo funciona el sistema.

Estructura completa

---
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"
created_at: "2025-01-15T14:32:00Z"
updated_at: "2025-01-22T09:15:00Z"
observation_count: 5
evidence:
  - date: "2025-01-15"
    event: "User rewrote class component to functional component"
    weight: 0.2
  - date: "2025-01-17"
    event: "User corrected class-based approach in code review"
    weight: 0.15
  - date: "2025-01-19"
    event: "User applied functional pattern 3 times without prompting"
    weight: 0.25
  - date: "2025-01-22"
    event: "User explicitly said 'use functional' in prompt"
    weight: 0.1
tags:
  - react
  - patterns
  - code-style
---
# Prefer Functional Style

## Action
Use functional patterns over classes when appropriate.

## Context
In this project, functional components and functional programming patterns
are strongly preferred over class-based approaches.

## Evidence
Observed 5 instances of preference across 4 sessions.
Last confirmation: User corrected class-based approach on 2025-01-22.

## Exceptions
- Legacy code that already uses classes (avoid unnecessary refactoring)
- Third-party library requirements that mandate class syntax

Campo por campo

id: Identificador único y semántico. Debe describir el comportamiento, no ser un UUID. Ejemplos buenos: prefer-async-await, test-before-implement, always-validate-input. Ejemplos malos: instinct-001, learned-pattern-xyz.

trigger: La condición en la que aplica el instinct. Debe ser lo suficientemente específico para no aplicar en todos lados, pero lo suficientemente general para ser útil. Empieza con “when” o “before” o “after”.

confidence: El score numérico de 0.3 a 0.9. Ver la sección 6 para el significado de cada nivel.

domain: La categoría del instinct. Los dominios disponibles son: code-style, testing, git, debugging, workflow, architecture, security. Ver la sección 7.

source: Cómo se creó el instinct. Valores posibles:

scope: project o global. Un instinct de proyecto solo se carga cuando Claude Code está trabajando en ese proyecto específico.

project_id: Hash del proyecto, derivado del git remote URL. Esto garantiza que dos proyectos con el mismo nombre no se confundan.

project_name: Nombre legible del proyecto, extraído del git remote o del directorio.

observation_count: Cuántas veces se observó el patrón que sustenta este instinct.

evidence: Array de observaciones específicas con fecha, descripción y peso. El weight de cada observación contribuye al confidence total. Observaciones explícitas del usuario tienen más peso que inferencias.

tags: Tags libres para búsqueda y filtrado.

Ejemplos de instincts reales

Instinct de git workflow:

---
id: squash-before-pr
trigger: "before creating a pull request"
confidence: 0.85
domain: "git"
source: "session-observation"
scope: project
project_id: "b2c3d4e5f6a1"
project_name: "backend-api"
observation_count: 8
evidence:
  - date: "2025-01-10"
    event: "User squashed 4 commits before opening PR"
    weight: 0.2
  - date: "2025-01-14"
    event: "User explicitly said 'squash first' in prompt"
    weight: 0.3
---
# Squash Before PR

## Action
Always squash WIP commits before creating a pull request.

## Context
This project follows a clean commit history policy. PRs should have
meaningful, atomic commits — not a trail of "fix", "fix again", "wip".

Instinct de testing:

---
id: test-error-paths
trigger: "when writing tests for a function"
confidence: 0.72
domain: "testing"
source: "session-observation"
scope: global
observation_count: 12
evidence:
  - date: "2025-01-08"
    event: "User added error case tests after reviewing PR"
    weight: 0.15
  - date: "2025-01-12"
    event: "User corrected test suite missing error path"
    weight: 0.2
---
# Test Error Paths

## Action
Always include at least one test for the error/failure path,
not just the happy path.

Instinct de debugging:

---
id: check-env-vars-first
trigger: "when investigating a configuration error"
confidence: 0.65
domain: "debugging"
source: "session-observation"
scope: global
observation_count: 6
evidence:
  - date: "2025-01-05"
    event: "3 debugging sessions resolved by missing env var"
    weight: 0.4
---
# Check Env Vars First

## Action
Before diving into code debugging of configuration errors,
first verify all required environment variables are set and have correct values.

6. El Sistema de Confianza (0.3-0.9)

El sistema de confianza es uno de los elementos más importantes del diseño. Permite representar el conocimiento con incertidumbre, en lugar de forzar una decisión binaria de “sé esto” o “no sé esto”.

Qué significa cada nivel

graph LR
    A["0.3 — Tentativo\nPrimera observación"] --> B["0.5 — Probable\n2-3 confirmaciones"]
    B --> C["0.65 — Confirmado\n4+ observaciones"]
    C --> D["0.8 — Establecido\nMúltiples sesiones"]
    D --> E["0.9 — Certero\nExplícito del usuario"]

0.3 — Tentativo: El sistema detectó un posible patrón por primera vez. Podría ser coincidencia. No se usa para guiar comportamiento todavía, pero se registra para observación futura. El Observer agent crea el instinct pero lo marca como bajo-confianza.

0.5 — Probable: Se observó el patrón en 2 o 3 ocasiones sin contradicción. El instinct empieza a influir suavemente en el comportamiento. Si Claude Code tiene dos opciones igualmente válidas, prefiere la que coincide con el instinct.

0.65 — Confirmado: 4 o más observaciones consistentes. El instinct activamente guía las decisiones. Claude Code lo aplica sin necesitar confirmación explícita para casos claros.

0.8 — Establecido: El patrón fue observado en múltiples sesiones distintas, con evidencia fuerte. Claude Code lo trata como convención del proyecto/workflow.

0.9 — Certero: El usuario lo confirmó explícitamente (verbalmente en la sesión o con /instinct-add). Máxima prioridad. Solo los instincts de máxima confianza se marcan así.

Cómo sube la confianza

Cada nueva observación que confirma el instinct aumenta el score. El incremento depende del tipo de observación:

Tipo de observaciónIncremento típico
Usuario aplica el patrón sin prompting+0.05 a +0.10
Usuario corrige comportamiento contrario+0.10 a +0.15
Usuario lo dice explícitamente en prompt+0.15 a +0.20
Usuario lo agrega manualmente con /instinct-addSalto a 0.85+

Cómo baja la confianza

Las contradicciones reducen el score. Si un instinct dice “preferir async/await” y el usuario escribe código con .then() varias veces sin que Claude Code lo sugiriera, el sistema interpreta eso como evidencia en contra.

Tipo de contradicciónDecremento típico
Usuario aplica patrón contrario-0.05
Usuario deshace cambio que siguió el instinct-0.10
Usuario dice explícitamente lo contrario-0.20

Thresholds para evolución

Los instincts no evolucionan arbitrariamente. El sistema usa thresholds:

Cuándo descartar un instinct

Un instinct se descarta cuando:

  1. Score cae bajo 0.3 después de haber estado más alto: el patrón que lo creó era ruido.
  2. Sin observaciones en 60 días: el patrón ya no es relevante en el trabajo actual.
  3. El usuario lo elimina explícitamente con /instinct-delete <id>.
  4. Entra en conflicto directo con un instinct de mayor confianza sobre el mismo trigger.

7. Dominios de Instincts

Los dominios son categorías que organizan los instincts. No son solo etiquetas: determinan cómo se agrupan para evolución y qué tipo de skill/comando generan.

code-style

Convenciones de cómo se escribe el código en este proyecto/equipo.

Ejemplos de lo que captura:

---
id: named-exports-only
trigger: "when writing a new module"
confidence: 0.75
domain: "code-style"
---
# Named Exports Only

## Action
Use named exports instead of default exports.

testing

Patrones de cómo se escriben y organizan los tests.

Ejemplos:

---
id: describe-per-function
trigger: "when writing tests"
confidence: 0.7
domain: "testing"
---
# Describe Per Function

## Action
Create one describe block per function/method being tested,
not one describe block per file.

git

Flujo de trabajo con git: commits, branches, PRs.

Ejemplos:

---
id: conventional-commits
trigger: "when creating a git commit"
confidence: 0.9
domain: "git"
---
# Conventional Commits

## Action
Always use conventional commit format: feat/fix/chore/docs/refactor/test
followed by colon and description.

## Format
feat: add user authentication
fix: resolve null pointer in payment service

debugging

Estrategias y primeros pasos para distintos tipos de errores.

Ejemplos:

---
id: check-docker-logs
trigger: "when a service is not responding"
confidence: 0.68
domain: "debugging"
---
# Check Docker Logs

## Action
Before investigating code, run `docker-compose logs --tail=50 <service>`
to see recent error messages.

workflow

Procesos y flujos de trabajo que no encajan en otras categorías.

Ejemplos:

---
id: run-lint-before-commit
trigger: "before committing code"
confidence: 0.8
domain: "workflow"
---
# Run Lint Before Commit

## Action
Always run `npm run lint` and `npm run type-check` before committing.
Fix all errors; do not commit with lint errors.

architecture

Decisiones arquitectónicas del proyecto: patrones, estructura, dependencias.

Ejemplos:

---
id: no-business-logic-in-controllers
trigger: "when writing controller code"
confidence: 0.82
domain: "architecture"
---
# No Business Logic in Controllers

## Action
Controllers should only handle HTTP concerns (request parsing, response formatting).
All business logic belongs in service classes.

security

Prácticas de seguridad observadas en el proyecto.

Ejemplos:

---
id: never-log-sensitive-data
trigger: "when adding logging"
confidence: 0.9
domain: "security"
---
# Never Log Sensitive Data

## Action
Never log passwords, tokens, API keys, or PII (emails, phone numbers,
national IDs). Log IDs and operation names only.

8. Project-Scoped vs Global Instincts (v2.1)

La versión 2.1 introduce uno de los cambios más importantes: el scope de proyecto.

El problema de cross-project contamination

Sin scope de proyecto, un instinct aprendido en un proyecto React contamina el trabajo en un proyecto Python. Un patrón de testing de Jest se aplica en un proyecto que usa pytest. Una convención de commits de un proyecto personal se intenta aplicar en un proyecto corporativo con sus propias reglas.

Esto hace que los instincts sean contraproducentes. En vez de ayudar, interrumpen con sugerencias incorrectas para el contexto actual.

Cómo funciona la detección de proyecto

El sistema usa una jerarquía de cuatro niveles para identificar el proyecto actual:

flowchart TD
    A[Session starts] --> B{CLAUDE_PROJECT_DIR set?}
    B -->|Yes| C[Use env var]
    B -->|No| D{In a git repo?}
    D -->|Yes| E[git remote get-url origin]
    E --> F[Hash remote URL → project_id]
    D -->|No| G[git rev-parse --show-toplevel]
    G --> H[Hash path → project_id]
    H --> I[Global fallback]
    F --> J[Project-scoped instincts loaded]
    C --> J
    I --> K[Global instincts only]

Nivel 1: Variable de entorno. Si CLAUDE_PROJECT_DIR está seteada, se usa eso. Útil para workspaces no-git o proyectos con estructura de monorepo.

Nivel 2: Git remote URL. El método más confiable. Hace hash del remote URL (git remote get-url origin). Dos clones del mismo repo en diferentes máquinas producen el mismo project_id. Esto permite compartir instincts entre máquinas del mismo developer.

Nivel 3: Git root path. Si no hay remote, usa el path del directorio raíz del repo. Funciona para repos locales, pero no se puede compartir entre máquinas (el path puede diferir).

Nivel 4: Global fallback. Si no hay ningún contexto de proyecto, el instinct se guarda como global y aplica en todos los proyectos.

Estructura de directorios

~/.claude/
├── instincts/
│   ├── personal/          ← instincts globales (aplican en todos los proyectos)
│   │   ├── test-error-paths.md
│   │   ├── conventional-commits.md
│   │   └── never-log-sensitive-data.md
│   └── evolved/           ← skills generados por evolución de instincts
│       ├── git-workflow.md
│       └── testing-standards.md
└── projects/
    ├── a1b2c3d4e5f6/      ← hash del proyecto "my-react-app"
    │   ├── observations.jsonl
    │   └── instincts/
    │       └── personal/
    │           ├── prefer-functional-style.md
    │           └── squash-before-pr.md
    └── b2c3d4e5f6a1/      ← hash del proyecto "backend-api"
        ├── observations.jsonl
        └── instincts/
            └── personal/
                ├── no-business-logic-in-controllers.md
                └── check-docker-logs.md

Cuándo un instinct escala a global

Un instinct de proyecto puede promover a global cuando:

  1. Se observa el mismo patrón en 2+ proyectos distintos. El sistema detecta instincts con el mismo id o semántica similar en diferentes proyectos y sugiere unificarlos.

  2. El usuario lo promueve explícitamente con /promote <instinct-id>.

  3. El instinct tiene un score de confianza global muy alto (>0.85) y el pattern es claramente independiente del proyecto (ej: “siempre validar input de usuario”).

La promoción no elimina el instinct de proyecto. Lo replica en el scope global, y si los dos divergen con el tiempo, el de proyecto tiene precedencia.

9. El Flujo de Observación

El flujo completo, desde la actividad en la sesión hasta el instinct guardado, involucra varios componentes que trabajan juntos.

Paso 1: Hooks capturan la actividad

sequenceDiagram
    participant U as Usuario
    participant CC as Claude Code
    participant H as Hook PreToolUse
    participant O as observations.jsonl

    U->>CC: "refactoriza esta función a async/await"
    CC->>H: tool_call: bash
    H->>O: append observation
    CC->>U: executes bash, edits file
    CC->>H: tool_call: edit
    H->>O: append observation

El hook PreToolUse se ejecuta antes de cada tool call. Registra:

El hook PostToolUse se ejecuta después y registra:

Paso 2: observations.jsonl acumula datos

Cada sesión acumula sus observaciones en un archivo JSONL (JSON Lines) en el directorio del proyecto:

~/.claude/projects/<project-hash>/observations.jsonl

Paso 3: Observer agent procesa (background, Haiku)

Al final de la sesión, un agente Haiku en background lee las observaciones del día y busca patrones. El agente Haiku es deliberadamente el modelo más liviano: no necesita razonamiento complejo para detectar patrones simples, y el costo de tokens debe ser mínimo.

El Observer agent hace tres análisis:

Análisis de correcciones: ¿El usuario tuvo que corregir algo que hizo Claude Code? Esas correcciones son evidencia fuerte de que la primera aproximación no coincidía con las preferencias del usuario.

Análisis de repetición: ¿Se aplicó el mismo patrón múltiples veces en la sesión? La repetición es evidencia de una convención.

Análisis de explicitaciones: ¿El usuario dijo algo sobre cómo quería que se hicieran las cosas? Las instrucciones explícitas generan instincts de alta confianza directamente.

Paso 4: Decisión de scope

Para cada posible instinct detectado, el Observer agent decide el scope:

Paso 5: Creación o actualización del instinct

Si el instinct ya existe (mismo id), se actualiza: se agrega evidencia al array y se recalcula el confidence score.

Si es nuevo, se crea con confidence 0.3 y la evidencia de la sesión actual.

10. El observations.jsonl

El archivo observations.jsonl es el registro crudo de todo lo que sucede durante las sesiones. Es el dato primario del que se extraen los instincts.

Formato del archivo

Cada línea es un objeto JSON independiente. El archivo nunca se sobreescribe; solo se hace append. Esto lo hace robusto ante crashes.

{"ts":"2025-01-22T14:32:15Z","session":"abc123","hook":"PreToolUse","tool":"bash","input":{"command":"npm run test"},"prompt_context":"run the full test suite"}
{"ts":"2025-01-22T14:32:18Z","session":"abc123","hook":"PostToolUse","tool":"bash","output":{"exit_code":0,"stdout":"Tests: 42 passed"},"duration_ms":2843}
{"ts":"2025-01-22T14:33:05Z","session":"abc123","hook":"PreToolUse","tool":"edit","input":{"file":"src/auth/service.ts","changes":"replaced class AuthService with function-based approach"},"prompt_context":"user said: use functions not classes"}
{"ts":"2025-01-22T14:33:06Z","session":"abc123","hook":"PostToolUse","tool":"edit","output":{"success":true},"duration_ms":45}
{"ts":"2025-01-22T14:35:22Z","session":"abc123","hook":"PreToolUse","tool":"bash","input":{"command":"git add -p"},"prompt_context":"stage only the relevant changes"}

Qué registra

Prompts del usuario: El contexto del prompt que originó la tool call. Esto es crucial para el análisis semántico: permite al Observer agent entender la intención detrás de cada acción.

Tool calls: Cada tool call con su tipo, input completo y output. El input de edits incluye una descripción de los cambios (no el diff completo, que sería demasiado).

Outcomes: Si la tool call fue exitosa o fallida, y el tiempo que tomó. Los failures son evidencia importante para instincts de debugging.

Session ID: Permite agrupar todas las observaciones de una sesión y analizar la narrativa completa.

Cómo consultarlo

El archivo es texto plano, consultable con herramientas estándar:

# Ver observaciones de hoy
cat ~/.claude/projects/<hash>/observations.jsonl | grep "2025-01-22"

# Ver solo los edits (cambios de código)
cat ~/.claude/projects/<hash>/observations.jsonl | jq 'select(.tool == "edit")'

# Ver las correcciones (PostToolUse con error, seguido de nuevo intento)
cat ~/.claude/projects/<hash>/observations.jsonl | jq 'select(.output.exit_code != 0)'

Rotación y limpieza

Para evitar que el archivo crezca indefinidamente:

11. /instinct-status

El comando /instinct-status muestra el estado actual del sistema de aprendizaje: qué instincts existen, cuáles tienen más confianza, cuáles están evolucionando.

Ejemplo de output

╔════════════════════════════════════════════════════════════════╗
║  INSTINCT STATUS — backend-api                                 ║
║  Project: b2c3d4e5f6a1 | 2025-01-22 14:45                     ║
╚════════════════════════════════════════════════════════════════╝

PROJECT INSTINCTS (8 total)
─────────────────────────────────────────────────────────────────
 id                              domain        confidence   obs
─────────────────────────────────────────────────────────────────
 no-business-logic-controllers   architecture  ████████░░  0.82  12
 conventional-commits            git           █████████░  0.88   9
 check-docker-logs               debugging     ██████░░░░  0.65   6
 squash-before-pr                git           ████████░░  0.80   8
 validate-request-body           security      ██████░░░░  0.60   5
 service-layer-returns-result    architecture  █████░░░░░  0.55   4
 test-all-http-methods           testing       ████░░░░░░  0.45   3
 use-zod-schemas                 code-style    ███░░░░░░░  0.35   2

GLOBAL INSTINCTS (4 total)
─────────────────────────────────────────────────────────────────
 test-error-paths                testing       ███████░░░  0.72  12
 never-log-sensitive-data        security      █████████░  0.90  18
 check-env-vars-first            debugging     ██████░░░░  0.65   6
 conventional-commits            git           █████████░  0.88  22

EVOLUTION CANDIDATES
─────────────────────────────────────────────────────────────────
 ▸ no-business-logic-controllers + service-layer-returns-result
   → can evolve to: skill "clean-architecture-patterns" (confidence: 0.80)
   → run: /evolve no-business-logic-controllers service-layer-returns-result

PENDING EVOLUTION
─────────────────────────────────────────────────────────────────
 conventional-commits (project) → already exists globally, can /promote

Cómo interpretar el output

Las barras de confianza: Representan el score en escala visual. ████████░░ = 0.82/1.0. Una barra llena indicaría 0.9 (máximo práctico).

La columna obs: Cantidad de observaciones que sustentaron el instinct. Un instinct con confianza 0.80 pero solo 3 observaciones es más frágil que uno con confianza 0.75 y 15 observaciones.

Evolution Candidates: El sistema agrupa instincts relacionados y sugiere evoluciones. Cuando ve dos instincts del mismo dominio con alta confianza, propone convertirlos en un skill.

Pending Evolution: Instincts de proyecto que ya existen globalmente o que son candidatos a promote.

Filtros disponibles

/instinct-status --domain=git           # Solo instincts de git
/instinct-status --scope=global         # Solo globales
/instinct-status --min-confidence=0.7   # Solo los de alta confianza
/instinct-status --evolve-ready         # Solo los que son candidatos a evolución

12. /learn y /learn-eval

El sistema tiene dos comandos manuales que complementan el aprendizaje automático.

/learn: Análisis inmediato de sesión

/learn

Fuerza inmediatamente el análisis de la sesión actual, sin esperar al final. Útil cuando:

El output de /learn es conversacional:

Analizando sesión actual...

Sesión: 1h 23min | 47 tool calls | 3 correcciones

Nuevos instincts detectados:
  + use-zod-schemas (code-style, 0.35) — primera observación
  + check-docker-logs (debugging, 0.65) — 3ra observación, confianza aumentada

Instincts existentes actualizados:
  ↑ no-business-logic-controllers: 0.75 → 0.82 (2 nuevas observaciones)
  ↑ conventional-commits: 0.82 → 0.88 (1 observación explícita)

Nada descartado.

Para ver estado completo: /instinct-status

/learn-eval: Análisis profundo con evaluación

/learn-eval

/learn-eval hace lo mismo que /learn pero agrega una capa de evaluación crítica. En lugar de solo registrar lo observado, el agente evalúa la calidad de los instincts existentes:

¿Qué analiza /learn-eval extra?

  1. Coherencia interna: ¿Hay instincts que se contradicen? Por ejemplo, un instinct que dice “usar functional style” y otro que dice “usar classes para servicios” en el mismo dominio.

  2. Obsolescencia: ¿Hay instincts que no se han visto en mucho tiempo? Puede ser que el proyecto cambió de convenciones.

  3. Especificidad vs generalidad: ¿Hay instincts demasiado vagos para ser útiles? ¿Hay instincts demasiado específicos que solo aplican a un archivo?

  4. Threshold de descarte: ¿Hay instincts bajo 0.3 que deberían eliminarse?

El output de /learn-eval incluye recomendaciones de acción:

EVALUACIÓN CRÍTICA DE INSTINCTS

Coherencia:
  ⚠️  CONFLICTO: prefer-functional-style vs use-classes-for-services
      Ambos en domain code-style con triggers similares.
      Recomendación: revisar y unificar. Acción: /instinct-edit

Obsolescencia:
  ⚠️  use-redux-for-state: último observation 2024-11-10 (73 días)
      El proyecto posiblemente migró a otro state manager.
      Recomendación: /instinct-delete use-redux-for-state

Especificidad:
  ⚠️  always-do-good: confidence 0.45, trigger demasiado vago
      No hay evidencia concreta de qué significa "do good" en código.
      Recomendación: /instinct-refine always-do-good

Descarte sugerido:
  ✗  use-deprecated-api (confidence: 0.28, sin observaciones en 45 días)
     /instinct-delete use-deprecated-api

Cuándo usar cada uno

SituaciónComando
Final de sesión productiva, quiero capturar aprendizajes/learn
Quiero asegurarme de que el instinct específico que acabo de demostrar quedó registrado/learn
Limpieza mensual del sistema de aprendizaje/learn-eval
Los instincts parecen estar dando sugerencias incorrectas/learn-eval
Onboarding: quiero evaluar qué instincts transferir a un nuevo proyecto/learn-eval

13. /evolve: De Instincts a Skills

El endpoint final del pipeline de aprendizaje es /evolve. Cuando los instincts maduran lo suficiente, se pueden convertir en artifacts de mayor nivel.

Cómo funciona el clustering

El sistema de evolución empieza por clustering: agrupar instincts relacionados que juntos cuentan una historia más completa.

Los criterios de clustering son:

  1. Mismo dominio: Instincts de architecture tienden a agruparse.
  2. Triggers complementarios: Un instinct con trigger “when writing controllers” y otro con “when writing services” del mismo proyecto son complementarios.
  3. Confianza suficiente: El cluster solo se propone si la suma ponderada de confianza de los miembros supera 0.7.
  4. Semántica: El Observer agent identifica instincts que hablan del mismo concepto con distintos ángulos.

Qué puede generar /evolve

Skills (~/.claude/skills/): Un skill completo con instrucciones detalladas. Apropiado cuando el cluster representa un proceso o conjunto de reglas que requiere contexto extenso.

/evolve no-business-logic-controllers service-layer-returns-result
→ Genera: ~/.claude/skills/clean-architecture-nodejs.md

Commands (~/.claude/commands/): Un comando personalizado ejecutable. Apropiado cuando el cluster representa un proceso repetible que tiene un punto de inicio y fin claro.

/evolve squash-before-pr conventional-commits
→ Genera: ~/.claude/commands/prepare-pr.md

Agents: Un agente especializado con un conjunto de habilidades específico. Solo cuando el cluster es suficientemente grande y cubre un dominio completo de trabajo.

/evolve --all --domain=testing
→ Genera: agente especializado en testing para este proyecto

El proceso interactivo

/evolve no es un proceso automático silencioso. Es interactivo:

/evolve no-business-logic-controllers service-layer-returns-result

Analizando cluster...

Instincts incluidos:
  - no-business-logic-controllers (0.82, 12 obs)
  - service-layer-returns-result (0.55, 4 obs)

Tema detectado: Clean Architecture en Node.js — separación Controller/Service

Tipo de artifact sugerido: skill
Nombre sugerido: clean-architecture-nodejs
Razón: proceso con múltiples reglas que requiere explicación

¿Proceder con generación? [Y/n]: Y

Generando skill...

Creado: ~/.claude/skills/clean-architecture-nodejs.md
Los instincts originales se mantienen y apuntan al skill generado.

¿Quieres revisar el skill antes de activarlo? [Y/n]: Y

El skill generado incluye las instrucciones consolidadas de todos los instincts del cluster, ejemplos derivados de las observaciones, y casos de excepción detectados de las contradicciones menores.

14. /promote: De Proyecto a Global

La mayoría de los instincts empiezan con scope project. Con el tiempo, algunos demuestran ser universales.

Cuándo promover

El criterio principal es: ¿aplica este patrón sin importar en qué proyecto estés trabajando?

Ejemplos de instincts que deben ser globales:

Ejemplos de instincts que deben quedarse en proyecto:

El criterio “visto en 2+ proyectos”

El sistema detecta automáticamente cuando el mismo instinct (mismo id o misma semántica detectada por el Observer agent) aparece en dos proyectos distintos. En ese caso, sugiere la promoción:

[Continuous Learning] Instinct "test-error-paths" detectado en 2 proyectos:
  - backend-api (confianza: 0.72)
  - mobile-app (confianza: 0.68)

Recomendación: promover a global
Ejecutar: /promote test-error-paths

Cómo funciona la promoción

/promote squash-before-pr

Instinct: squash-before-pr (git, 0.80, proyecto: backend-api)

Análisis de universalidad:
  ✓ El patrón no referencia archivos específicos del proyecto
  ✓ Es una práctica de git independiente del stack
  ✓ La confianza es 0.80 — umbral de promoción: 0.7

¿Promover squash-before-pr a scope global? [Y/n]: Y

Promovido. El instinct de proyecto permanece como referencia.

La promoción crea una copia del instinct en ~/.claude/instincts/personal/. El instinct de proyecto sigue existiendo. Si los dos divergen en el futuro (el global tiene evidence diferente al de proyecto), el de proyecto tiene precedencia cuando se trabaja en ese proyecto.

15. /instinct-export e /instinct-import

Una de las características más poderosas del sistema es la capacidad de compartir instincts entre developers.

/instinct-export: Exportar instincts

/instinct-export                           # Exporta todos los instincts del proyecto actual
/instinct-export --global                  # Exporta instincts globales
/instinct-export --min-confidence=0.65     # Solo los de alta confianza
/instinct-export --domain=architecture     # Solo un dominio
/instinct-export > team-instincts.json     # Guardar a archivo

Formato JSON completo

{
  "export_version": "2.1",
  "exported_at": "2025-01-22T15:30:00Z",
  "source_project": {
    "id": "b2c3d4e5f6a1",
    "name": "backend-api"
  },
  "exported_by": "senior-dev",
  "instincts": [
    {
      "id": "no-business-logic-controllers",
      "trigger": "when writing controller code",
      "confidence": 0.82,
      "domain": "architecture",
      "scope": "project",
      "observation_count": 12,
      "evidence_summary": "Observed 12 times across 8 sessions. User corrected twice.",
      "body": "Controllers should only handle HTTP concerns. Business logic belongs in services.",
      "tags": ["architecture", "clean-code", "mvc"]
    },
    {
      "id": "conventional-commits",
      "trigger": "when creating a git commit",
      "confidence": 0.88,
      "domain": "git",
      "scope": "global",
      "observation_count": 9,
      "evidence_summary": "Strong user preference. Confirmed explicitly twice.",
      "body": "Always use conventional commit format: feat/fix/chore/docs/refactor/test.",
      "tags": ["git", "commits", "conventions"]
    }
  ],
  "metadata": {
    "total_instincts": 2,
    "avg_confidence": 0.85,
    "domains": ["architecture", "git"]
  }
}

/instinct-import: Importar instincts

/instinct-import team-instincts.json

El proceso de import es interactivo y muestra las decisiones:

Importando team-instincts.json...

Source: backend-api | 2 instincts | avg confidence: 0.85

Resolución de conflictos:
─────────────────────────────────────────────────────────────────
  conventional-commits (git, 0.88)
    Estado: YA EXISTE localmente (confidence: 0.72)
    Opciones:
      [1] Mantener local (0.72)
      [2] Reemplazar con importado (0.88)
      [3] Merge — promedio de confianza (0.80), unir evidencias
    Selección: 3 — Merge

  no-business-logic-controllers (architecture, 0.82)
    Estado: NO EXISTE localmente
    Acción: Importar con scope=project, confidence=0.82 * 0.9 = 0.74
    (confidence reducida 10% al importar — requiere validación local)

─────────────────────────────────────────────────────────────────
Resumen:
  1 instinct mergeado
  1 instinct importado (confianza reducida)

¿Confirmar? [Y/n]: Y

Importación completada.

Proceso de merge

Cuando hay conflicto (el mismo id ya existe localmente), hay tres opciones:

  1. Mantener local: El instinct importado se ignora. Útil si tu versión refleja cómo trabajás específicamente.
  2. Reemplazar: El importado sobreescribe. Útil si el importado viene de alguien con más experiencia en ese patrón.
  3. Merge: Se promedian las confianzas y se unen los arrays de evidencia. Útil cuando ambas versiones son válidas y se complementan.

Reducción de confianza en imports

Cuando importás un instinct nuevo (no existente localmente), su confianza se reduce un 10%. Un instinct con 0.82 de quien lo exportó se importa como 0.74.

Esto es intencional: los instincts de otro developer reflejan los patrones de otro developer. Deben ganar confianza en tu contexto a través de tus propias observaciones.

16. Caso de Uso: Onboarding de Equipo

El caso de uso más impactante del sistema de instincts es el onboarding acelerado de nuevos developers.

El problema del onboarding sin instincts

Un developer nuevo en un proyecto tarda semanas en absorber el contexto implícito: las convenciones no escritas, los patrones preferidos, las trampas conocidas. Durante ese tiempo, comete errores que el equipo ya sabe evitar, hace preguntas que ya fueron respondidas, y produce código que los reviewers tienen que corregir.

Cuando trabaja con Claude Code, el problema se multiplica: Claude Code tampoco sabe nada del proyecto.

Walkthrough completo: Senior exporta → New member importa

Paso 1: El dev senior exporta sus instincts maduros

El dev senior tiene 3 meses trabajando en el proyecto con ECC activo. Sus instincts tienen confianza alta:

/learn-eval
→ Resultado: 14 instincts de proyecto, 8 globales, promedio confianza: 0.76

/instinct-export --min-confidence=0.65 > onboarding-instincts.json
→ Exportados 11 instincts (3 descartados por baja confianza)

El archivo resultante tiene instincts sobre:

Paso 2: El senior revisa antes de compartir

No todo lo que el sistema aprendió es para compartir. El senior hace una revisión rápida:

{
  "id": "pedro-review-style",
  "trigger": "when Pedro reviews PRs",
  ...
}

Este instinct captura el estilo de review de un reviewer específico — es conocimiento útil pero muy personal. El senior lo elimina del export con un editor de texto.

También ajusta algunos confidence scores: un instinct que el sistema marcó como 0.75 pero que el senior sabe que es 0.9 por experiencia directa.

Paso 3: El nuevo member importa

El nuevo developer clona el repo y, en su primera sesión con Claude Code:

/instinct-import onboarding-instincts.json

El proceso de import le muestra los instincts que está a punto de recibir, con opción de revisar cada uno. Puede aceptar todos con Y o revisar individualmente.

Paso 4: El nuevo developer trabaja con contexto pre-cargado

Desde la primera sesión, Claude Code en este proyecto opera con el contexto de meses de trabajo del senior:

La primera semana del nuevo developer es dramáticamente más productiva.

Paso 5: Los instincts del nuevo developer ganan confianza

Los instincts importados empezaron con confianza reducida (0.9 del original). Con cada sesión, cuando el Observer agent los ve aplicados, la confianza sube. Después de 2-3 semanas, el nuevo developer ha “validado” los instincts del senior en su propio contexto.

También empieza a generar instincts propios: patrones que observa en su trabajo diario que el senior quizás no tenía.

El resultado a los 30 días

ANTES (sin instincts compartidos):
  - Semana 1-2: mucho contexto re-explicado, errores de convención
  - Semana 3-4: empieza a funcionar bien
  - Mes 2: developer efectivo en el proyecto

CON instincts compartidos:
  - Día 1: trabaja con contexto del mes 2
  - Semana 2: sus propios instincts empiezan a madurar
  - Mes 1: developer efectivo desde la semana 1

17. El Skill Creator

Además de aprender de las sesiones, ECC tiene un skill específico para crear conocimiento a partir del historial de git.

/skill-create: Aprender del pasado

/skill-create

El Skill Creator analiza el historial de git del proyecto para detectar patrones en cómo se ha evolucionado el código:

Qué analiza del git history

git log --pretty=format:"%H %s" --diff-filter=M -500

El Skill Creator analiza los últimos 500 commits modificando archivos. Busca:

  1. Clusters de cambios relacionados: Commits que tocan los mismos archivos tienden a representar áreas de trabajo frecuente.
  2. Patrones en los mensajes: Si el 80% de los commits usan feat: y fix:, ese es el estándar del proyecto.
  3. Tipos de archivos más editados: Si hay muchos cambios en *.test.ts, el proyecto tiene cultura de testing. Si los cambios son siempre en *.controller.ts y *.service.ts, hay una arquitectura clara.
  4. Diffs repetidos: Si el mismo tipo de cambio aparece múltiples veces (por ejemplo, agregar validación a controllers), es un patrón.

El SKILL.md que genera

---
name: project-conventions-backend-api
description: Convenciones detectadas en el historial de git de backend-api
source: skill-creator
generated_at: 2025-01-22
confidence: 0.75
---

# Convenciones del Proyecto — backend-api

## Detectadas automáticamente del historial git (últimos 500 commits)

## Commit Message Format
El 87% de los commits usa conventional commits.
Formato: `type(scope): description`
Types observados: feat, fix, refactor, test, docs, chore

## Arquitectura detectada
- Directorio `src/controllers/` — 145 modificaciones
- Directorio `src/services/` — 132 modificaciones
- Directorio `src/__tests__/` — 98 modificaciones
Patrón: arquitectura controller/service con tests co-localizados

## Patrones de desarrollo
- Tests se agregan en el mismo commit que el feature (87% de veces)
- Los refactors son commits separados, nunca mezclados con features
- Los fixes siempre incluyen un test que reproduce el bug

## Archivos de alta modificación
1. `src/auth/service.ts` — 34 modificaciones
2. `src/database/connection.ts` — 28 modificaciones
3. `src/middleware/validation.ts` — 22 modificaciones

Cómo refinarlo manualmente

El skill generado es un punto de partida. El developer puede editarlo directamente para:

18. GitHub App para Repos Grandes

Para proyectos con historial extenso (10K+ commits), el análisis local es lento. ECC tiene integración con una GitHub App que procesa el análisis en la nube.

El problema a escala

Un repo con 50K commits y 5 años de historia tiene demasiado historial para analizar localmente. El skill-creator local limita a los últimos 500 commits por razones de performance.

La GitHub App no tiene ese límite. Puede analizar el historial completo, incluyendo PRs, code reviews, y comentarios.

Qué hace la GitHub App

  1. Análisis de historial completo: Los últimos 5 años de commits, no solo los últimos 500.
  2. Análisis de code reviews: Los comentarios de reviewers en PRs son una fuente rica de convenciones. “Siempre valida el input aquí”, “este patrón ya fue discutido, ver PR #234”, etc.
  3. Detección de anti-patrones: Errores que el equipo ha introducido y revertido múltiples veces.
  4. Auto-PRs de skills: Cuando detecta un nuevo patrón fuerte, abre un PR al repo para agregar el skill al CLAUDE.md del proyecto.

Auto-PRs de skills

La GitHub App puede abrir PRs automáticos:

[CL-Bot] feat: add detected skill for authentication patterns

Based on analysis of 234 related commits and 45 code review comments,
the following pattern has been consistently applied in this project:

- Authentication middleware always validates JWT before reaching controllers
- Failed auth attempts always log the IP address
- Token refresh logic is centralized in auth.service.ts

Added to: .claude/skills/authentication-patterns.md

El equipo puede revisar, aprobar, o rechazar el PR. Si lo aprueban, el skill queda en el repo y todos los developers lo cargan automáticamente.

Compartir con el equipo a través del repo

Cuando el skill se agrega al repo en .claude/skills/, todos los developers lo reciben al hacer git pull. No necesitan importar nada manualmente.

~/.claude/skills/         ← skills personales/globales
{project}/.claude/skills/ ← skills del equipo, en el repo

Claude Code busca skills tanto en ~/.claude/skills/ como en .claude/skills/ del proyecto actual.

19. Memory Persistence Hooks

El sistema de aprendizaje continuo incluye hooks específicos para persistir y restaurar contexto entre sesiones.

SessionStart: Cargar contexto

El hook SessionStart se ejecuta al inicio de cada sesión. Su responsabilidad es:

  1. Cargar los instincts del proyecto actual y presentarlos como contexto inicial
  2. Cargar el session file de la sesión anterior, si existe (ver sección 20)
  3. Verificar si hay actualizaciones de instincts pendientes de procesar
# ~/.claude/skills/continuous-learning-v2/session-start.sh
PROJECT_HASH=$(git -C "$CLAUDE_PROJECT_DIR" remote get-url origin 2>/dev/null | sha256sum | cut -c1-12)
INSTINCTS_DIR="$HOME/.claude/projects/$PROJECT_HASH/instincts/personal"

if [ -d "$INSTINCTS_DIR" ]; then
  echo "[CL] Loading $(ls $INSTINCTS_DIR | wc -l) project instincts"
fi

SessionEnd: Guardar aprendizajes

El hook Stop (sesión terminada limpiamente) dispara el análisis final:

  1. Cierre del observations.jsonl para esta sesión
  2. Trigger del Observer agent para análisis en background
  3. Actualización del session file con el estado final

PreCompact: Backup antes de compresión

Cuando Claude Code comprime el contexto (elimina mensajes viejos para hacer espacio), el hook PreCompact crea un snapshot:

# Antes de compactar, guardar estado actual
SESSION_FILE="$HOME/.claude/projects/$PROJECT_HASH/sessions/$(date +%Y%m%d-%H%M).md"
claude-code-snapshot > "$SESSION_FILE"

Esto garantiza que el conocimiento de la sesión no se pierda cuando el contexto se comprime.

20. Los Archivos de Sesión

Los archivos de sesión son una característica complementaria al sistema de instincts. Son especialmente útiles en sesiones largas o cuando se llega al límite de contexto.

Dónde se guardan

~/.claude/projects/<project-hash>/sessions/
├── 2025-01-22-1432.md   ← sesión del 22 de enero, 14:32
├── 2025-01-21-1015.md
└── 2025-01-20-0930.md

Formato del archivo de sesión

Un archivo de sesión tiene estructura específica para ser útil como context recovery:

# Session: backend-api | 2025-01-22 14:32

## Objetivo de la sesión
Implementar autenticación JWT con refresh tokens.

## Estado al cierre
- [x] Middleware JWT básico implementado
- [x] Login endpoint funcionando
- [ ] Refresh token endpoint — falta implementar
- [ ] Tests de auth — pendiente

## Qué funcionó
- Usar `jsonwebtoken` con la configuración: `{ algorithm: 'RS256', expiresIn: '15m' }`
- El middleware debe ir antes de los routers, no dentro
- Para testear JWT, usar `supertest` con `Authorization: Bearer <token>` header

## Qué no funcionó
- Intentamos usar `express-jwt` package — incompatible con nuestra versión de Express. No usar.
- Pasar el secret como string plano da problemas con RS256. Debe ser Buffer o KeyObject.

## Qué falta hacer
1. POST /auth/refresh — validar refresh token, generar nuevo access token
2. Invalidación de refresh tokens (tabla en DB)
3. Tests completos para todos los endpoints de auth
4. Rate limiting en los endpoints de auth

## Contexto importante para próxima sesión
- Los tokens RS256 necesitan las keys en `config/keys/` (no commitear)
- El usuario `[email protected]` existe en la DB de desarrollo con password `dev123`
- El middleware está en `src/middleware/auth.ts`

Qué contiene el archivo de sesión

El documento de longform guide original especifica exactamente lo que debe contener:

Lo que funcionó (con evidencia): No solo “funciona”, sino por qué funcionó. La configuración exacta, el enfoque específico, las dependencias necesarias.

Lo que no funcionó: Igual de importante. Evita que la próxima sesión repita el mismo camino fallido. Debe incluir el motivo del fallo, no solo el hecho.

Lo que queda pendiente: Lista priorizada de próximos pasos. Al empezar la próxima sesión, se puede retomar desde aquí.

Cómo usar el archivo de sesión

Al empezar una nueva sesión sobre el mismo tema:

lee el archivo de sesión de ayer y continuemos desde donde quedamos
→ Claude Code lee ~/.claude/projects/<hash>/sessions/2025-01-21-1015.md
→ Carga el contexto: qué se hizo, qué no funciona, qué queda
→ Empieza sugiriendo el primer paso pendiente

21. El Flujo Completo: Semanas 1-8

Cómo los instincts maduran a lo largo de semanas de uso real.

Semana 1: Observación pura

gantt
    title Madurez del Sistema por Semanas
    dateFormat  YYYY-MM-DD
    section Semana 1
    Observación y registro         :active, s1a, 2025-01-01, 7d
    section Semana 2-3
    Instincts tentaivos (0.3-0.5)  :s2a, 2025-01-08, 14d
    section Semana 4
    Primeros instincts confirmados  :s4a, 2025-01-22, 7d
    section Semana 5-6
    Candidatos a evolución          :s5a, 2025-01-29, 14d
    section Semana 7-8
    Primeros skills evolucionados   :s7a, 2025-02-12, 14d

La primera semana, el sistema observa sin generar instincts. El Observer agent registra observaciones pero aplica un threshold mínimo: un patrón visto solo una vez en la primera semana no genera instinct todavía.

Qué esperar: Después de la primera semana, tenés 20-40 observaciones registradas pero pocos o ningún instinct. Esto es normal.

Acción recomendada: Correr /learn al final de cada sesión para que el sistema no pierda las observaciones.

Semanas 2-3: Instincts tentativos

Las observaciones de la semana 1 empiezan a correlacionarse con las de la semana 2. El Observer agent empieza a ver patrones recurrentes y genera instincts con confianza 0.3-0.5.

Qué esperar: 5-15 instincts tentativos. Muchos serán ruido. La mayoría estarán en el rango 0.3-0.4.

Acción recomendada: Correr /instinct-status y revisar. Los que te parezcan incorrectos, eliminalos con /instinct-delete. Los que son correctos pero no los detectó, agregalos manualmente con /instinct-add.

Semana 4: Primeros instincts confirmados

Con 3-4 semanas de observaciones, los patrones reales empiezan a emerger claramente. Los instincts recurrentes suben de 0.3 a 0.5-0.7. Los que eran ruido se quedan en 0.3 o bajan.

Qué esperar: 5-10 instincts con confianza >0.6. Estos son los patrones más importantes de tu workflow.

Acción recomendada: Revisar con /learn-eval. Eliminar instincts conflictivos. Considerar si alguno debería ser global.

Semanas 5-6: Candidatos a evolución

Los instincts de alta confianza empiezan a agruparse. El sistema sugiere clusters.

Qué esperar: /instinct-status muestra “Evolution Candidates”. Los clusters relacionados tienen un prompt para convertirlos en skills.

Acción recomendada: Evaluar los evolution candidates. Los que representan un proceso claro, evolucionar a skill con /evolve.

Semanas 7-8: Primeros skills evolucionados

Qué esperar: 2-4 skills evolucionados, 10-20 instincts activos, sistema de aprendizaje funcionando de manera estable.

Qué cambia en el trabajo diario: Claude Code empieza la sesión con contexto. No necesitás re-explicar las convenciones del proyecto. Los errores conocidos tienen sus soluciones ya registradas. El flujo de trabajo es notablemente más fluido.

22. Integración con /rules-distill

El sistema de instincts se integra con otro skill de ECC: rules-distill.

Qué hace rules-distill

/rules-distill analiza patrones de trabajo y genera reglas para el CLAUDE.md del proyecto. En lugar de instincts (que son internos al sistema de aprendizaje), genera instrucciones que van en el contexto explícito.

La relación entre instincts y rules

Los instincts son conocimiento implícito del sistema. Las rules son instrucciones explícitas que Claude Code lee al inicio de cada sesión. Son complementarios, no equivalentes.

Un instinct de alta confianza puede ser un candidato a convertirse en rule:

/rules-distill --from-instincts --min-confidence=0.8

Analizando instincts de alta confianza...

Candidatos para rules:
  - conventional-commits (0.88): "Usar conventional commits format"
  - no-business-logic-controllers (0.82): "Controllers no tienen lógica de negocio"
  - never-log-sensitive-data (0.90): "No loggear datos sensibles"

Generar reglas? [Y/n]: Y

El resultado se agrega al CLAUDE.md del proyecto como reglas explícitas.

Cuándo usar rules vs instincts

AspectoRules (CLAUDE.md)Instincts
VisibilidadExplícitas, legibles por humanosInternas al sistema
AplicaciónSiempre, en cada sesiónContextual, con confianza
GestiónManual, editando CLAUDE.mdAutomática con observaciones
CompartirEn el repo (git)Export/import JSON
VelocidadInmediataSe construye con el tiempo

La estrategia óptima es usar ambos: los instincts capturan patrones emergentes automáticamente, y cuando maduran a alta confianza, se pueden distill a rules para que sean explícitas y compartidas por todo el equipo vía git.

23. Compartir Instincts en el Equipo

El flujo completo de compartir instincts en un equipo requiere una estrategia.

El flujo recomendado

sequenceDiagram
    participant S as Senior Dev
    participant R as Repo
    participant N as New Dev

    S->>S: /instinct-export --min-confidence=0.7
    S->>S: Revisar y limpiar manualmente
    S->>R: Subir onboarding-instincts.json al repo
    R->>N: git clone + git pull
    N->>N: /instinct-import .claude/onboarding-instincts.json
    N->>N: Trabaja con contexto pre-cargado
    N->>N: Instincts ganan confianza local
    N->>S: N exporta sus propios instincts después de 1 mes
    S->>S: /instinct-import N-instincts.json
    note over S,N: Merge bidireccional de conocimiento

Dónde guardar los instincts del equipo

El lugar recomendado es .claude/team-instincts.json en el repo del proyecto. Es un archivo que se versiona con git y está disponible para todos los members.

{project}/
├── .claude/
│   ├── team-instincts.json    ← instincts del equipo
│   ├── skills/                ← skills del equipo
│   └── CLAUDE.md              ← reglas del proyecto
├── src/
└── ...

Sincronización periódica

Una buena práctica es tener un proceso de sincronización mensual:

  1. El tech lead corre /learn-eval y /instinct-export --min-confidence=0.7
  2. Revisa el export, elimina lo muy personal o muy específico
  3. Hace merge con el team-instincts.json existente
  4. Abre un PR con el archivo actualizado
  5. El equipo revisa y aprueba

Esto mantiene el conocimiento del equipo actualizado y en control de versiones.

24. Debugging del Sistema de Aprendizaje

Qué hacer cuando las cosas no funcionan como esperás.

Síntoma: No se generan instincts

Diagnóstico 1: Los hooks no están configurados

# Verificar que los hooks están en settings.json
cat ~/.claude/settings.json | jq '.hooks'

Deben aparecer los hooks PreToolUse y PostToolUse apuntando al skill de continuous-learning.

Diagnóstico 2: El script del hook no tiene permisos

ls -la ~/.claude/skills/continuous-learning-v2/
# pre-tool.sh y post-tool.sh deben tener permiso de ejecución (x)
chmod +x ~/.claude/skills/continuous-learning-v2/*.sh

Diagnóstico 3: El archivo observations.jsonl no se está escribiendo

# Verificar que el directorio del proyecto existe
ls ~/.claude/projects/

# Ver si se creó el directorio del proyecto actual
PROJECT_HASH=$(git remote get-url origin | sha256sum | cut -c1-12)
ls ~/.claude/projects/$PROJECT_HASH/

Si el directorio no existe, los hooks no están creando las observaciones. Revisar permisos del directorio padre.

Síntoma: Instincts con confianza que no sube

Generalmente indica que las observaciones no están referenciando el instinct existente. El Observer agent puede estar creando instincts con IDs diferentes para el mismo concepto.

/instinct-status --verbose

El modo verbose muestra los raw observations que contribuyeron a cada instinct. Si ves observaciones similares yendo a IDs diferentes, hay que consolidar manualmente:

/instinct-merge prefer-functional prefer-functions-over-classes
→ Consolida dos instincts en uno, suma evidencias

Síntoma: Instincts incorrectos o contradictorios

Correr /learn-eval que hace el análisis crítico específicamente para detectar conflictos.

Si hay un instinct claramente incorrecto:

/instinct-delete <id>              # Eliminar directamente
/instinct-edit <id>                # Editar el YAML manualmente
/instinct-set-confidence <id> 0.3  # Bajar confianza sin eliminar

Síntoma: Los instincts no se cargan en la sesión

Verificar que el hook SessionStart existe y está configurado. También verificar que el project_id detectado corresponde al directorio donde están los instincts:

# Ver qué project_id detecta el sistema
~/.claude/skills/continuous-learning-v2/detect-project.sh

Si el project_id es diferente al que usaste para crear los instincts (por ejemplo, porque cambiaste el git remote), hay que migrar:

/instinct-migrate --from=<old-hash> --to=<new-hash>

25. Privacy y Datos

El sistema de aprendizaje maneja datos sensibles con cuidado. Entender qué se guarda y dónde es importante.

Qué se guarda localmente

Todo el almacenamiento es local. Los instincts, las observaciones, los archivos de sesión — todo va a ~/.claude/ en tu máquina. Nada sale de tu máquina sin tu acción explícita.

Específicamente:

Qué contienen las observaciones

Las observaciones registran:

Las observaciones NO incluyen:

Si un prompt contiene datos sensibles (como una API key que pegaste directamente en el prompt), esa cadena puede quedar en observations.jsonl. Por eso es importante:

  1. No pegar secretos directamente en los prompts. Usar referencias (mira el .env).
  2. Si accidentalmente ocurrió, limpiar con /observations-redact <pattern>.

Qué no sale de tu máquina

Por defecto, absolutamente nada sale de tu máquina. El Observer agent (Haiku) corre localmente via la API de Anthropic con tu API key personal — los tokens se gastan en tu cuenta, el análisis queda en tu contexto.

La única forma en que los datos salen de tu máquina es:

Cómo limpiar instincts problemáticos

# Eliminar un instinct específico
/instinct-delete <id>

# Eliminar todos los instincts de un dominio
/instinct-delete --domain=<domain>

# Eliminar todas las observaciones de una fecha
/observations-clear --before=2025-01-01

# Limpieza total del proyecto
/observations-clear --all
/instinct-delete --all --project=current

# Limpieza total global (¡destructivo!)
rm -rf ~/.claude/instincts/personal/

26. Comparativa: Sin ECC vs Con ECC

Cómo cambia el trabajo a lo largo del tiempo

graph LR
    subgraph Semana 2
        A1["Sin ECC\nRe-explicar contexto\ncada sesión"]
        B1["Con ECC\nPrimeros instincts\ntentativos activos"]
    end

    subgraph Mes 1
        A2["Sin ECC\nMisma fricción\nconstante"]
        B2["Con ECC\nInstincts maduros\n+ primeros skills"]
    end

    subgraph Mes 3
        A3["Sin ECC\nNingún aprendizaje\nacumulado"]
        B3["Con ECC\nSistema completo\noperacional"]
    end

Tabla de comparativa detallada

SituaciónSin ECCCon ECC (2 semanas)Con ECC (1 mes)Con ECC (3 meses)
Inicio de sesiónContexto desde ceroInstincts tentativos cargadosInstincts confirmados activosSkills evolucionados + instincts
Re-explicar convencionesCada sesiónOcasionalmenteRara vezCasi nunca
Errores ya conocidosMismo tiempo de resoluciónMismaInstincts de debugging activosSoluciones pre-conocidas
Nuevo developer en equipo2-4 semanas de onboarding—Export de instincts disponibleOnboarding en días
Consistencia de códigoDepende de la sesiónMejoraConsistenteMuy consistente
Commits de formato incorrectoFrecuentesMenosRarosCasi inexistentes
Tiempo perdido en re-contexto10-20 min/sesión5-10 min2-5 min<2 min

27. Mejores Prácticas

Las 15 reglas para aprovechar el sistema de aprendizaje

1. Correr /learn al final de sesiones largas. No esperar al hook automático. Si la sesión fue productiva, capturar los aprendizajes manualmente asegura que se registren.

2. Hablar en el prompt cuando algo no te gusta. En vez de solo deshacer el cambio que Claude Code hizo, decir “eso no funciona así en este proyecto” activamente. La corrección explícita genera evidencia de alta confianza.

3. Ser explícito cuando algo está bien. Si Claude Code aplicó exactamente la convención correcta, decirlo: “bien, así es como se hace aquí”. Esta confirmación sube el confidence score.

4. Revisar /instinct-status semanalmente. 10 minutos por semana revisando el estado del sistema evita la acumulación de instincts incorrectos o contradictorios.

5. Hacer /learn-eval mensualmente. El análisis crítico mensual limpia el ruido y sugiere consolidaciones.

6. No pegar secretos en los prompts. Usar referencias (“mira el .env”) en vez de pegar valores directamente. Las observaciones guardan el prompt context.

7. Exportar instincts antes de cambiar de proyecto. Si vas a empezar en un proyecto nuevo pero con tecnologías similares, exportar los instincts globales del proyecto actual y revisar cuáles son transferibles.

8. Usar /instinct-add para patrones importantes nuevos. No esperar a que el sistema los detecte. Si encontraste una solución importante a un problema difícil, agregar el instinct manualmente.

9. Especificar el trigger correctamente. Un trigger vago ("always") crea un instinct que se aplica en demasiados contextos. Un trigger específico ("when writing controller methods that handle user input") lo hace más útil.

10. No editar el YAML de instincts directamente. Usar los comandos del sistema (/instinct-edit, /instinct-merge). El sistema mantiene metadatos que el YAML no muestra.

11. Compartir instincts en el equipo cuando maduren. Esperar a que los instincts tengan confianza >0.65 antes de compartir. Los de baja confianza pueden contaminar el onboarding.

12. Mantener instincts atómicos. Si un instinct empieza a describir múltiples cosas, dividirlo. Un instinct = un trigger = una acción.

13. Usar /evolve cuando hay 2+ instincts del mismo dominio con alta confianza. El clustering natural del sistema sugiere evoluciones, pero el usuario tiene que aprobarlas.

14. Promover a global solo lo universal. No todo instinct útil en el proyecto actual es útil en todos los proyectos.

15. Usar los archivos de sesión para proyectos complejos. Para proyectos con mucho estado (implementaciones en curso, decisiones de arquitectura pendientes), el archivo de sesión es esencial.

28. Anti-Patrones

Los 10 errores más comunes

Anti-patrón 1: Confiar ciegamente en todos los instincts desde el día 1. Los instincts de confianza <0.5 son tentativos. No son certezas. Tratar un instinct de 0.35 como una regla fija lleva a frustrarse cuando el sistema se contradice.

Anti-patrón 2: Nunca revisar /instinct-status. El sistema acumula ruido con el tiempo. Sin revisión periódica, los instincts incorrectos se acumulan y eventualmente empiezan a degradar la calidad del trabajo.

Anti-patrón 3: Importar instincts de un proyecto muy diferente. Importar instincts de un proyecto Rails en un proyecto FastAPI produce ruido. Los instincts tienen scope implícito en la tecnología. Filtrar por relevancia antes de importar.

Anti-patrón 4: Crear instincts demasiado específicos. Un instinct que dice "en src/auth/service.ts línea 45, usar esta sintaxis específica" no es útil más allá de esa función. Los instincts deben ser principios, no instrucciones de línea específica.

Anti-patrón 5: Crear instincts demasiado vagos. El extremo opuesto: "hacer buen código" no tiene trigger ni acción específica. No ayuda a nadie.

Anti-patrón 6: No usar el sistema durante semanas y esperar resultados inmediatos. El sistema necesita observaciones para funcionar. Si no se usa Claude Code con los hooks activos, no hay datos para aprender.

Anti-patrón 7: Guardar secretos en los prompts. Ver sección de Privacy. Un error que puede tener consecuencias reales si los instincts exportados contienen tokens o keys.

Anti-patrón 8: Evolucionar instincts demasiado pronto. Un instinct de confianza 0.45 no está listo para evolucionar a skill. El skill resultante sería de baja calidad y potencialmente incorrecto. Esperar a 0.75+.

Anti-patrón 9: Tener demasiados instincts. Más de 30-40 instincts activos por proyecto empieza a ser contraproducente. El sistema carga todos en el contexto. Si hay muchos, la señal se pierde en el ruido.

Anti-patrón 10: Ignorar los Evolution Candidates del sistema. Cuando /instinct-status muestra “Evolution Candidates”, hay una sugerencia concreta de mejora. Ignorarla sistemáticamente desperdicia el valor del sistema.

29. Ejercicios Prácticos

Ejercicio 1: Activar y verificar el sistema (30 minutos)

Objetivo: Confirmar que los hooks están funcionando y el sistema está registrando observaciones.

Pasos:

  1. Verificar que los hooks están en ~/.claude/settings.json
  2. Abrir una sesión de Claude Code en un proyecto
  3. Ejecutar 5-10 comandos normales de trabajo
  4. Verificar que observations.jsonl se está actualizando: 
    tail -f ~/.claude/projects/<hash>/observations.jsonl
  5. Correr /learn y revisar el output

Resultado esperado: Al menos algunas observaciones registradas y el comando /learn ejecutándose sin errores.

Ejercicio 2: Tu primer instinct manual (20 minutos)

Objetivo: Crear un instinct manualmente para capturar una convención importante del proyecto.

Pasos:

  1. Pensar en una convención del proyecto que siempre tenés que re-explicar
  2. Crear el instinct con /instinct-add: 
    /instinct-add
id: <nombre-descriptivo>
trigger: when <condición>
domain: <dominio>
scope: project
  3. Agregar la descripción de la acción cuando el sistema lo pida
  4. Verificar con /instinct-status que aparece

Resultado esperado: El instinct aparece en /instinct-status con confidence 0.85+ (los manuales tienen alta confianza inicial).

Ejercicio 3: Exportar e importar (45 minutos, requiere dos proyectos)

Objetivo: Practicar el flujo de sharing entre proyectos.

Pasos:

  1. En el proyecto A, correr /instinct-export --min-confidence=0.5 > /tmp/project-a-instincts.json
  2. Abrir el JSON y revisar el contenido
  3. Eliminar los instincts que son muy específicos del proyecto A
  4. Cambiar al proyecto B
  5. Correr /instinct-import /tmp/project-a-instincts.json
  6. Revisar los conflictos y resolverlos
  7. Verificar con /instinct-status que los importados están activos

Resultado esperado: Instincts relevantes del proyecto A activos en el proyecto B con confianza reducida.

Ejercicio 4: Tu primer /evolve (60 minutos, requiere instincts maduros)

Objetivo: Evolucionar instincts a un skill completo.

Pasos:

  1. Verificar con /instinct-status --evolve-ready si hay candidatos
  2. Si no hay, encontrar 2 instincts del mismo dominio con confianza >0.65
  3. Correr /evolve <id1> <id2>
  4. Revisar el skill generado en ~/.claude/skills/
  5. Editar el skill manualmente para agregar contexto que el sistema no pudo inferir
  6. Activar el skill agregándolo al CLAUDE.md

Resultado esperado: Un skill .md con instrucciones consolidadas de los instincts originales.

Ejercicio 5: Onboarding simulado (90 minutos, requiere un compañero)

Objetivo: Practicar el flujo completo de compartir contexto de proyecto.

Pasos:

  1. Dev A exporta sus instincts: /instinct-export --min-confidence=0.65 > onboarding.json
  2. Dev A revisa el JSON y lo limpia (elimina datos muy personales)
  3. Dev B importa: /instinct-import onboarding.json
  4. Dev B trabaja 30 minutos en el proyecto con los instincts importados
  5. Dev B nota qué instincts fueron útiles y cuáles no
  6. Dev B da feedback a Dev A sobre qué faltó y qué sobraba

Resultado esperado: Una conversación sobre qué conocimiento implícito es más valioso para transferir, y un onboarding.json refinado.

30. Checklist y Resumen

Checklist de configuración inicial

Checklist de uso semanal

Checklist mensual

Resumen del capítulo

El sistema de Continuous Learning e Instincts de ECC resuelve el problema fundamental del conocimiento efímero: cada sesión de Claude Code ya no empieza desde cero.

Los puntos clave del sistema:

Arquitectura v2.1: Los hooks PreToolUse/PostToolUse capturan el 100% de la actividad. Un Observer agent en background (Haiku) analiza sin afectar el contexto principal. Los instincts atómicos representan conocimiento granular con confianza ponderada.

Instincts: La unidad fundamental de aprendizaje. Atómicos, con score de confianza 0.3-0.9, con evidencia rastreable, con scope de proyecto o global. Se crean automáticamente por observación o manualmente con /instinct-add.

El pipeline de madurez: Observaciones → Instincts tentativos → Instincts confirmados → Clusters → Skills/Commands/Agents. Cada etapa tiene sus criterios de confianza.

Project-scoped instincts (v2.1): Cada proyecto tiene sus propios instincts. Los patrones universales pueden promoverse a global. No hay cross-project contamination.

Sharing de equipo: Export/import JSON con reducción de confianza al importar. Flujo natural para onboarding acelerado y transferencia de conocimiento entre developers.

La transformación: Después de 2-3 meses de uso activo, Claude Code en tu proyecto opera con el contexto implícito de meses de trabajo colaborativo. El tiempo de re-contexto por sesión baja de 10-20 minutos a menos de 2 minutos. Los errores conocidos tienen soluciones pre-registradas. Las convenciones del equipo se aplican consistentemente.

El sistema no es magia: requiere uso activo, revisión periódica, y retroalimentación explícita. Pero con esa inversión mínima, transforma fundamentalmente cómo Claude Code aprende y se adapta a tu forma de trabajar.

Siguiente capítulo: Capítulo 10: Multi-Agent Systems

← Volver al listado de tecnologías ← Índice de Everything Claude Code