Jev —o un modelo de decisión similar— puede tomar un input y producir una decisión estructurada: una categoría, un score, una probabilidad o una opción de un conjunto cerrado.

KCP no clasifica ese texto. Su función está más cerca de declarar qué conocimiento, habilidades, procedimientos y reglas son válidos, cuáles están vigentes y bajo qué condiciones pueden utilizarse.

Y hay una tercera pieza que no conviene olvidar:

Una decisión no es lo mismo que una autorización, y una confianza no es lo mismo que una evidencia.

Si los ponemos al mismo nivel, parece que la IA aprueba un crédito o una póliza.

No necesariamente.

Primero están las reglas y el contexto autorizado. Después puede venir una decisión estructurada. Luego una política puede determinar qué hacer con ella. Y finalmente debe quedar evidencia de lo ocurrido.

Un 0.82 no es una firma.

Jev: https://jevai.net/es/

KCP: https://github.com/Cantara/knowledge-context-protocol

1. Cuatro preguntas, no cuatro productos que se pelean

Cuando hablamos de AI Agents aparecen cada vez más siglas:

LLM, RAG, MCP, KCP, A2A, Skills, Playbooks, Jev...

Es fácil pensar:

¿Cuál reemplaza a cuál?

Creo que es una pregunta equivocada.

Es mejor preguntar:

¿Qué problema resuelve cada pieza?

Una forma todavía más sencilla:

MCP       → ¿A qué puedo acceder?

KCP       → ¿Qué conocimiento/regla es válido?

Skills    → ¿Qué sé hacer?

Playbooks → ¿Cómo se ejecuta un procedimiento?

A2A       → ¿Con qué otro agente colaboro?

Jev       → ¿Qué decisión estructurada corresponde?

Audit     → ¿Qué ocurrió y puedo demostrarlo?

No son necesariamente competidores.

Son piezas diferentes de una arquitectura de agentes.

2. El dibujo fácil — y por qué puede engañar

Cuando alguien pide:

"Dibújame el stack de Agentic AI"

es tentador hacer esto:

                    AGENT
                      │
          ┌───────────┼───────────┐
          │           │           │
         KCP         MCP         A2A
          │           │           │
          └───────────┼───────────┘
                      │
                     Jev
                      │
                    ACTION

Se ve bonito.

Pero tiene un problema:

parece que Jev está debajo de KCP, MCP y A2A como si fuera otra capa del mismo tipo.

No necesariamente.

Una arquitectura más útil conceptualmente sería:

                         AGENT
                           │
             ┌─────────────┼─────────────┐
             │             │             │
            KCP           MCP           A2A
             │             │             │
        conocimiento      tools        agentes
        y gobierno        y datos      externos
             │
             ▼
      contexto autorizado
             │
             ▼
       MODELO DE DECISIÓN
        Jev / LLM / otro
             │
             ▼
       decisión estructurada
       choice + score + etc.
             │
             ▼
        POLICY / GATE
             │
        ┌────┴────┐
        ▼         ▼
      ACTION     HUMAN
        │
        ▼
       AUDIT
        │
        ▼
     EVIDENCE

La idea importante es:

El modelo puede proponer una decisión. La política determina qué se puede hacer con esa decisión.

3. ¿Qué es cada uno, sin folleto?

MCP — ¿a qué puedo entrar?

MCP es la capa de conexión con herramientas y recursos.

Por ejemplo:

Agent
  │
  ├── MCP → PostgreSQL
  ├── MCP → GitHub
  ├── MCP → SAP
  ├── MCP → REST API
  └── MCP → filesystem

Pregunta:

¿Qué herramientas y recursos tengo disponibles?

Yo lo veo como el enchufe.

KCP — ¿qué conocimiento manda?

KCP entra en otro problema.

Supongamos que RAG encuentra:

Política de crédito 2024
Política de crédito 2025
Política de crédito 2026

Encontrar documentos no significa saber cuál tiene autoridad.

KCP introduce una capa para declarar conocimiento y contexto gobernado:

Documento
   │
   ├── versión
   ├── vigencia
   ├── alcance
   ├── audiencia
   ├── autoridad
   └── relación con otros documentos

Y el ecosistema ha ido más allá del documento:

Knowledge
    ↓
Skills
    ↓
Playbooks

Por eso no lo describiría simplemente como "un inventario de documentos".

Es más preciso decir:

KCP es una capa de conocimiento y gobernanza para declarar qué conocimiento, capacidades y procedimientos están disponibles y bajo qué condiciones.

A2A — ¿se lo paso a otro agente?

A2A responde otra pregunta:

¿Cómo colaboro con otro agente?

Por ejemplo:

Customer Agent
      │
      ├──→ Credit Agent
      │
      ├──→ Fraud Agent
      │
      └──→ Shipping Agent

MCP:

Agent ↔ Tool

A2A:

Agent ↔ Agent

Son complementarios.

Skills y Playbooks — ¿cómo hago el trabajo?

Una cosa es saber que puedes acceder a una herramienta.

Otra es saber cómo utilizarla correctamente.

Por ejemplo:

Skill: "Analizar una solicitud de crédito"

Playbook:

1. Obtener datos

2. Validar identidad

3. Consultar política vigente

4. Evaluar riesgo

5. Solicitar revisión si corresponde

6. Registrar evidencia

Aquí empieza a aparecer una arquitectura mucho más interesante que simplemente:

"Tengo un chatbot conectado a una API."

Jev — ¿qué decisión estructurada corresponde?

Aquí está la diferencia fundamental.

Un LLM tradicional puede responder:

"Creo que este caso debería ser revisado por el área de fraude porque..."

Un modelo de decisión puede producir algo más cercano a:

{
  "decision": "fraud-review",
  "confidence": 0.82
}

O:

{
  "category": "A",
  "score": 82,
  "probability": 0.91
}

La idea de Jev es precisamente llevar el modelo hacia decisiones tipadas/probabilísticas en lugar de generación abierta.

Eso puede ser muy útil cuando el espacio de respuestas está controlado.

Pero aquí aparece una distinción fundamental.

4. "0% de alucinaciones" no significa "0% de errores"

Este punto merece mucha atención.

Una salida estructurada puede garantizar que el modelo solamente devuelva:

APPROVE
REFUSE
ESCALATE

Eso evita que el modelo invente una cuarta opción:

MAYBE-PERHAPS-APPROVE

Pero no significa que:

APPROVE

sea necesariamente la decisión correcta.

El propio análisis de Thor sobre Jev señala precisamente esta diferencia: la afirmación de "0% hallucination" se refiere a la garantía del esquema de salida, no a una garantía empírica de corrección.

Dicho de otra manera:

Schema correctness
        ≠
Decision correctness

Si las únicas opciones son:

APPROVE
REFUSE

el modelo siempre devolverá una de ellas.

Pero todavía puede equivocarse.

5. Y aquí aparece una palabra importante: calibración

Supongamos que el modelo responde:

decision = APPROVE
confidence = 0.82

La pregunta importante es:

¿Ese 0.82 significa realmente algo?

¿Significa que acertará aproximadamente el 82% de las veces?

¿O simplemente es un número que el modelo produce con mucha seguridad?

Para responderlo necesitamos datos.

Por ejemplo:

Confidence       Resultado real

0.50 – 0.59      58% correctas
0.60 – 0.69      67% correctas
0.70 – 0.79      75% correctas
0.80 – 0.89      84% correctas
0.90 – 0.99      92% correctas

Entonces podríamos empezar a hablar de una confianza calibrada.

Pero si todas nuestras decisiones son:

0.85
0.87
0.91
0.89
0.90
0.88

y nunca tenemos suficientes casos con otros niveles de confianza, no podemos saber realmente si el número está calibrado.

Eso es exactamente una de las cosas interesantes que descubrió Thor al auditar su propio sistema.

Su gateway llevaba meses produciendo decisiones tipadas, confidence y referencias a reglas. Pero cuando intentaron comprobar si el confidence realmente predecía la corrección, descubrieron que sus propios datos todavía no permitían responderlo.

Y esa es una lección que me parece mucho más importante que cualquier benchmark:

Un número de confianza necesita evidencia.

6. Un 0.82 no es una firma

Esta frase merece su propia sección.

Podemos tener:

decision = APPROVE
confidence = 0.82

Incluso podemos firmarlo criptográficamente.

Eso nos permite demostrar:

"El sistema produjo esta decisión con este valor."

Pero no demuestra:

"La decisión era correcta."

Son cosas diferentes.

Firma
  │
  ▼
Prueba de lo que ocurrió

Calibración
  │
  ▼
Evidencia sobre qué tan confiable es el número

Política
  │
  ▼
Qué podemos hacer con esa decisión

Por eso una arquitectura de agentes empresarial necesita algo más que modelos.

Necesita gobernanza y evidencia.

7. El caso de Ana López

Imaginemos que tenemos una clínica.

Ana López está hospitalizada y llega este texto:

"Paciente presenta potasio elevado y está tomando medicación X."

Nuestro sistema podría tener:

RAG

Encuentra:

Protocolo 2024
Protocolo 2025
Protocolo 2026

KCP

Determina:

Protocolo 2026
vigente
aplicable a este tipo de caso

MCP

Permite consultar:

Historia clínica
Laboratorio
Medicamentos

Skill / Playbook

Define:

Analizar hiperpotasemia

A2A

Puede delegar:

Medical Agent
      │
      └──→ Pharmacy Agent

Modelo de decisión

Recibe el contexto autorizado:

decision = "pharmacy-review"
confidence = 0.82

Pero todavía falta una pregunta:

¿Qué hacemos con ese 0.82?

La política podría decir:

if confidence < 0.75
    → human review

if medication == high-risk
    → human review

if policy requires physician
    → human review

Entonces:

            KCP
             │
             ▼
     contexto autorizado
             │
             ▼
       modelo de decisión
             │
             ▼
      pharmacy-review
          0.82
             │
             ▼
          POLICY
             │
             ▼
       HUMAN REVIEW
             │
             ▼
           AUDIT

Ahora sí tenemos una arquitectura defendible.

8. Lo más interesante: la auditoría también puede equivocarse

Y aquí el artículo de Thor tiene una segunda lección todavía más interesante.

Al auditar sus decisiones, inicialmente encontraron:

21 decisiones escaladas
21 aparentemente pendientes

Parecía un problema importante.

Pero el script de auditoría estaba utilizando mal un identificador de correlación.

Al corregir la relación entre eventos, el resultado cambió.

Y posteriormente encontraron otro problema: algunas de las decisiones que parecían pendientes pertenecían a ejecuciones que ya habían terminado o sido abortadas.

La conclusión es brutalmente sencilla:

Un sistema de auditoría también necesita ser auditado.

Podemos tener:

Agent
  ↓
Decision
  ↓
Audit

y aun así equivocarnos.

Por eso no basta con:

"Tengo logs."

Hay que poder responder:

• ¿Qué versión de la política estaba vigente?

• ¿Qué conocimiento se utilizó?

• ¿Qué modelo produjo la decisión?

• ¿Qué input recibió?

• ¿Qué decisión propuso?

• ¿Qué confidence produjo?

• ¿Qué regla la justificó?

• ¿Quién autorizó la acción?

• ¿Qué ocurrió después?

• ¿Podemos reconstruir el proceso?

Eso es evidence.

9. Entonces, ¿Jev reemplaza a KCP?

No.

Pero tampoco diría simplemente:

"KCP y Jev son complementarios."

Eso es demasiado superficial.

La relación más interesante es:

             KNOWLEDGE
                 │
                KCP
                 │
                 ▼
       CONTEXTO AUTORIZADO
                 │
                 ▼
          DECISION MODEL
        Jev / LLM / otro
                 │
                 ▼
       DECISIÓN PROPUESTA
                 │
                 ▼
          POLICY / GATE
                 │
          ┌──────┴──────┐
          ▼             ▼
       ACTION         HUMAN
          │
          ▼
         AUDIT
          │
          ▼
       EVIDENCE

Por eso el título sigue siendo:

Jev vs KCP: no es un versus

Pero ahora agregaría:

En realidad, tampoco es solamente Jev + KCP. Hay una tercera dimensión: gobernar y demostrar qué ocurrió.

10. Si tu equipo programa — Java u otra cosa

Todo esto no depende de Java.

Pero para un equipo Java podría verse perfectamente así:

Spring AI / LangChain4j / Quarkus
              │
              ▼
          AI Agent
              │
       ┌──────┼──────┐
       │      │      │
      KCP    MCP    A2A
       │      │      │
       │      │      └── Agent B
       │      │
       │      └──────── APIs / DB / Tools
       │
       └────────────── Knowledge / Policies
              │
              ▼
        Decision Model
              │
              ▼
      Structured Output
              │
              ▼
          Policy Gate
              │
          ┌───┴───┐
          ▼       ▼
        Action   Human
          │
          ▼
      Audit Trail

Y aquí está la parte que más me interesa como arquitecto:

no estamos construyendo simplemente un chatbot.

Estamos construyendo un sistema donde:

Knowledge
    +
Tools
    +
Agents
    +
Decision
    +
Governance
    +
Evidence

forman una unidad.

11. Cómo lo contaría en diez minutos

Si tuviera que explicar todo esto rápidamente, usaría solamente estas preguntas:

1. ¿Qué puedo usar?

MCP

Agent → Tools / Data

2. ¿Qué conocimiento es válido?

KCP

Agent → Governed Knowledge

3. ¿Cómo hago el trabajo?

Skills / Playbooks

Agent → Procedure

4. ¿Con qué otro agente colaboro?

A2A

Agent ↔ Agent

5. ¿Qué decisión corresponde?

Jev / modelo de decisión

Input → Decision + Score

6. ¿Qué puedo hacer con esa decisión?

Policy / Governance

Decision → Action / Human

7. ¿Cómo demuestro lo que pasó?

Audit / Evidence

Action → Trace → Evidence

Y ahí aparece una arquitectura mucho más completa:

Cierre

Mi conclusión después de mirar Jev y KCP es que la pregunta:

"¿Jev o KCP?"

no es la pregunta que deberíamos hacernos.

La pregunta interesante es:

"¿Qué necesita un agente para conocer, decidir, actuar y poder defender después lo que hizo?"

Ahí cada pieza tiene un papel diferente.

MCP conecta al agente con herramientas y datos.

KCP ayuda a gobernar el conocimiento, las capacidades y los procedimientos que puede utilizar.

Skills y Playbooks describen cómo realizar determinados trabajos.

A2A permite colaborar con otros agentes.

Jev, o cualquier modelo de decisión estructurada, puede ayudar a convertir un input en una decisión tipada, un score o una probabilidad.

Pero hay una advertencia importante:

Un confidence: 0.82 no demuestra que la decisión sea correcta.

Para eso necesitamos datos, calibración y evidencia.

Y tampoco basta con tener un audit log.

El propio proceso de auditoría puede equivocarse.

Por eso, para mí, la arquitectura de agentes empresariales empieza a verse así:

KNOWLEDGE
    ↓
GOVERNANCE
    ↓
DECISION
    ↓
ACTION
    ↓
EVIDENCE

O, en una frase:

KCP ayuda a establecer qué vale y qué está permitido. Un modelo como Jev puede proponer qué decisión corresponde. La política determina qué puede ocurrir después. Y la evidencia permite demostrar qué ocurrió realmente.

No es un versus. Es un sistema.

Referencias

• Thor Henning Hetland — We Already Run Jev. We Just Never Checked.

• JoeDayz — Jev vs KCP: no es un versus

• KCP — Knowledge Context Protocol

• Jev AI — TypeSafe AI

Enjoy!

Joe

Primero aprendimos a conversar con modelos.

Después empezamos a utilizarlos para escribir código, analizar documentos, generar contenido y consultar información.

Ahora estamos entrando en una etapa diferente: los agentes.

Un agente no solamente responde. Puede consultar sistemas, utilizar herramientas, ejecutar procesos, modificar información y coordinarse con otros agentes.

Y aquí aparece una pregunta que considero mucho más importante que simplemente preguntar qué tan inteligente es nuestro modelo:

¿Cómo hacemos para que un agente pueda actuar con autonomía sin perder el contexto, la trazabilidad, la seguridad y el control humano?

Porque poner un LLM detrás de una API y darle permisos para ejecutar acciones no convierte automáticamente nuestro sistema en una arquitectura agentic.

De hecho, probablemente sea una receta bastante rápida para tener problemas.

Lo interesante es que, cuando empezamos a pensar seriamente en agentes, aparecen una serie de capacidades que antes podían parecer secundarias: memoria, conocimiento, herramientas, autorización, auditoría, verificación y aprendizaje.

Y todas terminan conectándose.

El problema no es que la IA produzca poco

Durante mucho tiempo el objetivo fue conseguir que la IA produjera más.

Más código.

Más documentos.

Más análisis.

Más respuestas.

Pero cuando tenemos varios agentes trabajando en paralelo aparece un problema diferente.

Supongamos que tenemos:

Agente A → analiza incidencias
Agente B → revisa código
Agente C → actualiza documentación
Agente D → ejecuta pruebas
Agente E → prepara cambios

La capacidad de producción puede crecer rápidamente.

Pero el humano sigue siendo uno.

Y ese humano tiene que:

• revisar resultados;

• tomar decisiones;

• validar información;

• aprobar acciones;

• investigar errores.

Entonces el cuello de botella cambia.

Ya no es necesariamente:

"¿Cuánto puede producir la IA?"

Sino:

"¿Cuánto trabajo puede absorber y verificar una persona?"

Esto cambia completamente la arquitectura que necesitamos.

1. Un agente no puede empezar desde cero

Imaginemos que tenemos un agente excelente.

Tiene un buen modelo, buenas herramientas y acceso a nuestros sistemas.

Pero cada vez que iniciamos una sesión no sabe:

• qué ocurrió ayer;

• qué decisiones tomamos;

• qué aprendimos;

• qué solución fue descartada;

• qué procedimiento funciona actualmente;

• qué tiene permitido hacer.

Tenemos un agente muy capaz que todos los días parece ser su primer día de trabajo.

Por eso necesitamos diferentes tipos de conocimiento.

Una forma sencilla de verlo es:

Episódico
¿Qué ocurrió?

      ↓

Conocimiento
¿Qué creemos que es cierto?

      ↓

Skills
¿Cuál es el método validado?

      ↓

Playbooks
¿Cómo combinamos esos métodos?

      ↓

Gobernanza
¿Qué puede hacer el agente?

Esto cambia el ciclo de trabajo.

Ya no sería simplemente:

pregunta → respuesta

sino:

orientar
   ↓
recuperar contexto
   ↓
ejecutar
   ↓
verificar
   ↓
decidir
   ↓
aprender
   ↺

La siguiente ejecución comienza con lo aprendido en la anterior.

Ahí empieza a aparecer algo mucho más interesante que un chatbot:

memoria institucional.

2. Una respuesta no es conocimiento

Este punto parece obvio, pero se vuelve fundamental cuando dejamos que los agentes actúen.

Que un agente diga:

"El problema está en el servicio de pagos."

no significa que sea cierto.

Tenemos que poder distinguir:

Afirmación
    ↓
Fuente
    ↓
Evidencia
    ↓
Verificación
    ↓
Conocimiento confiable

Esto nos lleva al concepto de provenance o trazabilidad.

Cuando un agente toma una decisión importante deberíamos poder responder:

• ¿qué información utilizó?

• ¿de dónde salió?

• ¿qué regla aplicó?

• ¿qué versión del conocimiento utilizó?

• ¿quién autorizó la acción?

• ¿qué ocurrió finalmente?

Por ejemplo:

Agente:        billing-agent
Acción:        actualizar factura
Fuente:        ERP
Regla:         billing-update-v3
Autorización:  policy-17
Resultado:     success
Evidencia:     ...

Esto convierte una acción del agente en algo que podemos reconstruir posteriormente.

Pero hay una distinción importante:

Tener trazabilidad no significa tener razón.

Una firma puede demostrar que una acción ocurrió y quién la produjo.

No demuestra que la acción fuera correcta.

Por eso necesitamos combinar:

Provenance
+
Autorización
+
Evidencia
+
Verificación

3. No hagamos que el agente descubra lo que el sistema ya sabe

Aquí aparece otro problema.

Imaginemos un agente interactuando con una aplicación web:

Agente
  ↓
abre página
  ↓
busca botón
  ↓
interpreta texto
  ↓
hace clic
  ↓
comprueba resultado

El agente está intentando descubrir cómo funciona nuestro sistema a través de su interfaz.

¿Por qué no declarar directamente las capacidades?

Por ejemplo:

getCustomer(customerId)

createInvoice(customerId, items)

cancelInvoice(invoiceId)

approveRefund(refundId)

Ahora el agente sabe exactamente qué puede hacer y qué parámetros necesita.

La arquitectura cambia:

ANTES

Agente → UI → DOM → interpretación → acción


DESPUÉS

Agente → capacidad declarada → contrato → acción

Esto no solamente facilita el trabajo del agente.

También facilita:

• testing;

• autorización;

• auditoría;

• documentación;

• observabilidad;

• reutilización.

Y aparece una idea interesante:

La interfaz deja de ser necesariamente la fuente principal de información sobre lo que un sistema puede hacer.

Las capacidades pueden declararse explícitamente.

4. El agente necesita brazos, no solamente voz

Un chatbot tiene voz.

Un agente necesita brazos.

Es decir, necesita poder actuar:

Leer información
       ↓
Usar API
       ↓
Modificar información
       ↓
Ejecutar procesos
       ↓
Interactuar con otros sistemas

Pero aquí aparece un problema:

¿Qué acciones puede ejecutar?

No deberíamos responder:

"Las que permita su API key."

Eso es demasiado grueso.

La pregunta debería ser mucho más específica:

¿Este agente puede realizar esta acción, sobre este recurso, en este contexto y en este momento?

Por ejemplo:

crear PR                  → automático
ejecutar tests            → automático
modificar documentación   → automático

desplegar producción      → supervisión

eliminar base de datos    → aprobación explícita
transferir dinero         → aprobación explícita

La autonomía debería estar asociada a la acción, no solamente al agente.

5. La autonomía es un dial

Uno de los errores más comunes es pensar:

NO AUTÓNOMO ←→ AUTÓNOMO

En realidad necesitamos algo mucho más gradual:

Manual
   ↓
Automático con aprobación
   ↓
Automático con verificación
   ↓
Agente supervisado
   ↓
Agente autónomo

Y la posición depende de factores como:

• riesgo;

• reversibilidad;

• alcance;

• historial;

• calidad de la evidencia;

• autorización.

Un agente puede tener autonomía completa para limpiar ejecuciones de pruebas y necesitar aprobación humana para modificar producción.

No hay contradicción.

Son dos acciones diferentes.

6. Human-in-the-loop no significa aprobar todo

Aquí creo que aparece una de las ideas más importantes.

Durante mucho tiempo hemos pensado en Human-in-the-loop como:

Agente
  ↓
Humano
  ↓
Approve

Pero si hacemos esto para cada acción:

acción 1 → aprobar
acción 2 → aprobar
acción 3 → aprobar
acción 4 → aprobar
...

tenemos un problema.

El humano termina haciendo clic en "Approve" sin leer.

La seguridad se convierte en una ilusión.

Una arquitectura más interesante es:

                 ACCIÓN
                   ↓
          ¿Necesita juicio humano?
             ↙          ↘
           NO            SÍ
           ↓             ↓
       automático     humano correcto
                         ↓
                      decisión

Por ejemplo:

100 acciones
     ↓
95 → automáticas
 5 → revisión humana

El objetivo no es sacar al humano del sistema.

Es sacar del camino del humano todo lo que no necesita su juicio.

7. Permiso no significa relevancia

Esto también cambia la forma en que pensamos las notificaciones.

Una persona puede tener permiso para acceder a un proyecto.

Pero eso no significa que tenga que recibir todas las notificaciones de ese proyecto.

Tenemos dos conceptos diferentes:

PERMISSION
¿Puede verlo?

RELEVANCE
¿Necesita recibirlo?

Podemos agregar una tercera dimensión:

URGENCY
¿Necesita saberlo ahora?

Entonces:

Permission
     +
Relevance
     +
Urgency
     ↓
Delivery

Esto permite construir sistemas donde la mayoría de las cosas llegan como un resumen:

Digest

"Hay 27 elementos para revisar."

Y solamente las situaciones realmente importantes interrumpen:

Alert

"Esta acción requiere tu decisión."

Esto es importante porque la atención humana es un recurso limitado.

Si todo genera una alerta, ninguna alerta termina siendo realmente importante.

8. La confianza no se declara, se construye

Si queremos aumentar la autonomía de un agente necesitamos saber cuándo podemos confiar en él.

No basta con decir:

"Este modelo es muy bueno."

Necesitamos observar su comportamiento.

Historial
   ↓
Resultados
   ↓
Verificación
   ↓
Desviaciones
   ↓
Confianza
   ↓
Autonomía permitida

Y esa confianza tampoco debería ser permanente.

Si cambiamos:

• el modelo;

• las herramientas;

• los datos;

• las reglas;

• el contexto;

• el alcance;

tenemos que preguntarnos nuevamente:

¿La autorización y el nivel de autonomía siguen siendo válidos?

Un agente confiable para una tarea no necesariamente es confiable para otra.

9. Pero aparece una pregunta incómoda: ¿quién verifica al verificador?

Podemos construir:

Agente
  ↓
Decisión
  ↓
Evidencia
  ↓
Auditor
  ↓
Resultado

Y sentirnos bastante tranquilos.

Hasta que descubrimos que el auditor tiene un bug.

Esto es importante porque introduce un nivel adicional:

Nuestra infraestructura de verificación también necesita ser verificada.

Podemos tener todos los logs del mundo y aun así interpretarlos mal.

Por ejemplo:

Evento A
     ↓
Evento B
     ↓
Auditor
     ↓
"No están relacionados"

cuando en realidad sí pertenecen a la misma ejecución y simplemente estamos utilizando una clave de correlación incorrecta.

La lección es poderosa:

Los datos pueden ser correctos y nuestra interpretación de esos datos puede ser incorrecta.

10. 1.500 tests pasando tampoco significa que todo esté bien

Este problema también aparece en testing.

Podemos tener cientos o miles de pruebas pasando y descubrir un error en producción.

¿Por qué?

Porque podemos estar probando una representación simplificada del sistema real.

Por ejemplo:

Test
 ↓
Mock
 ↓
OK

mientras que:

Producción
 ↓
Restricción real
 ↓
FAIL

La cantidad de tests no es suficiente.

La pregunta importante es:

¿Qué propiedad del sistema estoy demostrando con este test?

Esto es especialmente relevante para gobernanza.

No basta con probar:

"El botón de aprobación funciona."

Tenemos que probar:

"Sin la aprobación requerida,
la acción realmente no puede ejecutarse."

Eso es mucho más cercano a una garantía real.

11. Las políticas deben ser ejecutables

Supongamos que nuestra documentación dice:

"Los cambios en producción requieren aprobación."

Perfecto.

Pero nuestro pipeline permite:

git push
   ↓
deploy

sin comprobar ninguna aprobación.

Entonces tenemos una política documentada, pero no una política efectiva.

Una política realmente importante debería poder convertirse en una regla ejecutable:

Cambio
  ↓
Pipeline
  ↓
¿Cumple política?
   ↙      ↘
 Sí       No
 ↓         ↓
Deploy   BLOCK

La diferencia es enorme.

Una política escrita expresa una intención.

Una política ejecutada por el sistema controla el comportamiento.

Y cuanto más autónomos sean nuestros agentes, más importante será esta distinción.

12. También tenemos que guardar nuestros errores

Normalmente almacenamos el conocimiento actual:

"Esta es la forma correcta de hacerlo."

Pero también sería útil conservar:

"Esta era nuestra hipótesis anterior."
"Esto fue lo que observamos."
"Esto la contradijo."
"Por eso cambiamos."

Por ejemplo:

Hipótesis
   ↓
Evidencia
   ↓
Decisión
   ↓
Falsificación
   ↓
Nuevo conocimiento

Esto es especialmente importante para los agentes.

Si descubrimos que una determinada estrategia falla bajo ciertas condiciones, no queremos que el siguiente agente vuelva a descubrirlo desde cero.

Queremos que pueda recuperar:

"Esta estrategia se utilizó anteriormente y falló cuando X estaba presente."

Los errores dejan de ser simplemente errores.

Se convierten en memoria institucional.

13. El objetivo no es hacer más. Es aprender más rápido.

Aquí creo que está el verdadero cambio de paradigma.

La primera generación de sistemas de IA buscaba:

Pregunta
   ↓
Respuesta

Los sistemas agentic buscan:

Objetivo
   ↓
Plan
   ↓
Herramientas
   ↓
Acciones
   ↓
Resultados

Pero podemos ir un paso más allá:

Trabajo
   ↓
Agente
   ↓
Resultado
   ↓
Verificación
   ↓
Aprendizaje
   ↓
Mejor conocimiento
   ↓
Mejor agente
   ↓
Mejor resultado
       ↺

Aquí la IA deja de ser únicamente una herramienta de producción.

Empieza a convertirse en parte del sistema de aprendizaje de la organización.

14. Una arquitectura de referencia

Si juntamos todas estas ideas, podemos imaginar una arquitectura bastante sencilla:

                         ┌──────────────┐
                         │    HUMANO    │
                         └──────┬───────┘
                                │
                         decisiones críticas
                                │
                                ↓
┌──────────────┐        ┌──────────────┐
│  CONTEXTO Y  │ ─────→ │    AGENTE    │
│ CONOCIMIENTO │        └──────┬───────┘
└──────────────┘               │
                               ↓
                       ┌───────────────┐
                       │ HERRAMIENTAS  │
                       │ Y CAPACIDADES │
                       └───────┬───────┘
                               ↓
                       ┌───────────────┐
                       │ GOBERNANZA Y │
                       │ AUTORIZACIÓN  │
                       └───────┬───────┘
                               ↓
                             ACCIÓN
                               ↓
                           EVIDENCIA
                               ↓
                         VERIFICACIÓN
                               ↓
                            LEDGER
                               ↓
                          APRENDIZAJE
                               │
                               └────────→ CONTEXTO

Cada componente responde una pregunta diferente.

Contexto

¿Qué sabemos y qué ocurrió?

Herramientas

¿Qué puede hacer el agente?

Gobernanza

¿Qué está autorizado a hacer?

Evidencia

¿Cómo sabemos qué ocurrió?

Verificación

¿Podemos confiar en el resultado?

Ledger

¿Podemos reconstruirlo después?

Aprendizaje

¿Qué deberíamos hacer diferente la próxima vez?

15. ¿Cómo lo llevaría a producción?

Y aquí está la parte práctica.

No empezaría construyendo una plataforma gigantesca de agentes.

Empezaría mucho más simple.

Fase 1 — Agente + contexto

Un agente que pueda recuperar información confiable.

Agente
 ↓
Knowledge
 ↓
Contexto

Fase 2 — Herramientas

Definir claramente qué puede hacer.

Agente
 ↓
Tools
 ↓
APIs

Fase 3 — Autorización

Decidir qué herramientas puede utilizar y bajo qué condiciones.

Agent
 ↓
Policy
 ↓
Tool

Fase 4 — Evidencia

Registrar las acciones importantes.

Action
 ↓
Evidence
 ↓
Audit

Fase 5 — Verificación

Comprobar automáticamente los resultados cuando sea posible.

Action
 ↓
Result
 ↓
Verifier

Fase 6 — Autonomía gradual

Permitir más autonomía solamente cuando exista evidencia suficiente.

Manual
  ↓
Approval
  ↓
Supervised
  ↓
Autonomous

Fase 7 — Aprendizaje

Capturar lo que funcionó y lo que no.

Execution
 ↓
Verification
 ↓
Learning
 ↓
Knowledge

Y volver a comenzar.

Conclusión

Creo que estamos entrando en una etapa donde construir un agente ya no significa simplemente elegir un buen modelo y conectarlo a algunas herramientas.

El verdadero desafío aparece cuando queremos que ese agente pueda actuar en el mundo real.

En ese momento necesitamos responder preguntas mucho más difíciles:

¿Qué sabe?

¿De dónde lo sabe?

¿Qué puede hacer?

¿Qué está autorizado a hacer?

¿Por qué confiamos en él?

¿Qué evidencia produjo?

¿Quién verifica esa evidencia?

¿Cuándo necesitamos a un humano?

¿Qué aprendimos después de equivocarnos?

Y todas esas preguntas nos llevan a una conclusión:

La autonomía no es el punto final de la arquitectura agentic.

Es una consecuencia de haber construido suficiente contexto, confianza, evidencia, gobernanza y mecanismos de verificación.

Podemos resumirlo así:

             CONTEXTO
                 ↓
            CAPACIDADES
                 ↓
           AUTORIZACIÓN
                 ↓
              ACCIÓN
                 ↓
             EVIDENCIA
                 ↓
           VERIFICACIÓN
                 ↓
            CONFIANZA
                 ↓
            AUTONOMÍA
                 ↓
           APRENDIZAJE
                 │
                 └──────────→ CONTEXTO

Y quizá el objetivo final no sea conseguir que la IA haga todo por nosotros.

Quizá sea algo mucho más interesante:

Construir organizaciones que sean mejores cada vez que hacen algo.

Una organización donde los agentes no solamente producen resultados, sino que ayudan a conservar el contexto, aprender de los errores, verificar las decisiones y aumentar gradualmente su autonomía.

Porque al final, el verdadero salto no es pasar de:

humano → IA

sino pasar de:

IA que responde

a:

sistemas que actúan, verifican y aprenden.

Un potasio crítico despierta a la cama 214, no a la directora. Una nota de psiquiatría no está disponible para cualquiera solo porque técnicamente exista en el sistema.

Con personas, esto parece obvio.

Pero cuando introducimos IA aparece una pregunta incómoda:

¿Cómo hacemos para que la IA vea solamente lo que le corresponde?

Este post cuenta una noche de guardia para explicar una idea sencilla: ruteo gobernado.

Quién puede ver qué, quién necesita verlo, por qué canal debe recibirlo y qué evidencia queda.

Y hay algo importante en la demo que acompaña este artículo:

no llama a ningún modelo.

No es una limitación. Es la lección.

La IA entra después, y solo con lo que ya le llegó.

Demo: https://github.com/joedayz/governed-agents/tree/main/clinica-gobernada

Una noche. Una cama.

Son las 02:14 en la Clínica San Mateo.

En la cama 214 está Ana López, 67 años, con una insuficiencia cardíaca descompensada.

Durante la guardia tenemos médicos, enfermeras y algunos agentes de software.

Por ahora, piensa en los agentes como compañeros de turno con un buzón.

Todavía no razonan.

Solo reciben información o no la reciben.

La regla tiene dos preguntas:

¿Puede verlo? ¿Debe verlo ahora?

La primera es permiso.

La segunda es necesidad.

Solo cuando ambas respuestas son sí, el dato se entrega.

Y existen únicamente dos canales:

• 🚨 Urgente: buscapersonas. No espera.

• 📋 Resumen: pase de guardia. Puede esperar.

Eso es prácticamente todo el motor:

¿Entró por el sistema? → ¿Qué tipo de dato es? → ¿Puede? → ¿Debe? → ¿Urgente o resumen? → ¿Queda prueba?

Primero: qué NO entra

Antes de hacer cualquier cosa con IA, hay datos que ni siquiera deberían entrar al flujo.

Por ejemplo:

📱 Foto de una receta casera enviada por WhatsApp por la hija de Ana.

Llegó desde un celular personal, no desde un sistema de la clínica.

Por tanto, queda fuera.

No importa que un agente pueda leer la imagen.

No importa que parezca información útil.

Si no entró por el canal autorizado, el agente no debería poder encontrarla.

Este filtro ocurre antes de cualquier modelo.

Cinco hechos. Cero IA.

Ahora ejecutamos la demo.

1. Potasio 6.8

Es un valor crítico.

• Enfermera Ruiz: 🚨 urgente. Está en la cama 214.

• Dra. Vargas: 🚨 urgente. Es la médica tratante.

• Dr. Mendoza: retenido. Puede verlo, pero no está a cargo de esa cama.

• Dra. Torres: no pasa. La dirección no necesita despertarse por cada laboratorio.

• Agentes: no les corresponde.

Un K+ de 6.8 no es un correo.

Es un buscapersonas.

El hospital ya sabe quién debe despertarse.

La IA no debería tener que inventarlo.

2. Nueva guía de diuréticos

La misma información puede tener diferentes canales.

• Vargas: 🚨 urgente, porque prescribe durante el turno.

• Agente de protocolos: 📋 resumen, porque puede procesarla después.

Aquí aparece una distinción importante:

Tener permiso no significa que te corresponda recibir algo ahora.

3. Pedido de auditoría SUSALUD

La directora tiene permisos relacionados con calidad.

Pero eso no significa que necesite recibir todo el documento crudo.

Necesita el resultado de la auditoría, no necesariamente cada archivo que llegó.

Si mandamos todo a todos los que técnicamente pueden verlo, terminamos creando otro problema:

demasiada información.

4. 14 dosis de espironolactona sin registro

El agente de farmacia debe enterarse.

→ 🚨 Urgente

El agente de historias necesita esa información para completar el expediente, pero no tiene permiso para acceder directamente a farmacia.

Tenemos:

Necesario, pero bloqueado.

Entonces interviene Mendoza.

Autoriza la excepción.

Queda un recibo.

El humano no vigila todo el stream.

Firma el hueco.

5. La nota de psiquiatría

La historia contiene una nota relacionada con riesgo por litio.

Normalmente, la guardia no puede leerla.

Pero Vargas necesita esa información para tomar una decisión clínica.

Tenemos otra vez:

Necesaria, pero bloqueada.

Mendoza autoriza.

La nota llega a Vargas.

No llega a Torres.

No llega a toda la guardia.

Y queda registrada la excepción.

El mismo documento puede tener tres destinos:

• alguien no puede verlo;

• alguien puede, pero no necesita recibirlo;

• alguien necesita verlo y obtiene una autorización puntual.

Eso es gobierno.

Y hasta aquí:

cero IA.

Entonces, ¿dónde entra la IA?

Ahora llegamos al último paso de la demo.

El dato ya pasó por las reglas.

Ya sabemos quién puede recibirlo.

Ya sabemos quién lo necesita.

Ya sabemos por qué canal llegó.

Y quedó evidencia.

El dato entra al buzón del agente.

Recién aquí aparece la IA.

Y ahora sí puede hacer su trabajo:

• resumir;

• clasificar;

• preparar una alerta;

• organizar información;

• proponer una respuesta.

Pero hay una frontera:

Lo que no llegó al buzón, el agente no debería poder utilizarlo.

Por ejemplo:

La IA puede trabajar sobre el dato.

No decide quién tiene derecho a recibirlo.

El error clásico: relevancia ≠ autoridad

Una IA “útil” podría pensar:

“El K+ 6.8 parece muy importante. Se lo mando a todos.”

O:

“Esta receta de WhatsApp habla del paciente. La agrego al expediente.”

O:

“Encontré la palabra ‘litio’ en una nota de psiquiatría. La incluyo en el resumen de planta.”

Ninguna de esas acciones necesita mala intención.

El problema es otro:

confundir relevancia con autoridad.

Un modelo puede detectar que algo es importante.

Eso no significa que tenga permiso para utilizarlo.

Por eso el prompt:

“Por favor, ten cuidado con los datos sensibles”

no sustituye una política de acceso.

Dos capas

Podemos resumir toda la arquitectura en dos capas.

Capa 1 — Gobierno

Qué entra → quién puede verlo → quién debe verlo → canal → autorización → recibo

Capa 2 — IA

Resume → clasifica → organiza → propone

El error es darle al modelo las dos responsabilidades.

Que decida qué información es relevante y quién debería recibirla.

El hospital no funciona así.

La IA tampoco debería.

¿Y si ponemos más IA?

¿Cuánto trabajo delegamos a la IA?

Hay que hablar de escalamiento.

Podemos empezar con:

• un agente que resume protocolos;

• luego incorporar farmacia;

• después automatizar más tareas rutinarias;

• finalmente delegar gran parte del trabajo que no requiere juicio clínico irreversible.

La pregunta no es solamente:

“¿Cuánta IA podemos poner?”

Es:

“¿Podemos aumentar la automatización sin perder el control sobre la información?”

Con gobierno, podemos aumentar el trabajo de los agentes sin cambiar la regla fundamental:

quién puede ver qué, por qué y con qué evidencia.

La demo en tres minutos

Si quieres mostrarla, no necesitas explicar toda la arquitectura.

Pregunta primero:

“Si llega un potasio de 6.8 a las 02:14, ¿quién se despierta?”

Luego pulsa Paso y muestra los buzones.

Cuando llegues a la nota de psiquiatría:

“Aquí alguien necesita el dato, pero está bloqueado. ¿Qué hacemos?”

Muestra la autorización humana.

Y finalmente:

“Hasta aquí no hubo IA.”

Último paso:

“Ahora sí. Pero solo con lo que ya le llegó.”

En la demo puedes cambiar las etiquetas a Atlas (Thor) para mostrar:

• may-see → puede verlo;

• should-see → debería recibirlo;

• HITL grant → un humano autorizó la excepción.

Espacio = Paso Reiniciar = volver al inicio.

Qué NO es esta demo

Para no vender de más:

• No es un producto clínico.

• No es un HIS.

• No hay un LLM detrás de los agentes de la demo.

• Los agentes son buzones con un rol.

• El último paso usa texto escrito a mano para mostrar dónde entraría la IA.

• Un hospital real tendrá muchos más roles y excepciones.

Pero el principio permanece:

puede ∩ debe → canal → recibo

Cierre

Un hospital no es un grupo de WhatsApp con bata.

Un dato entra por el sistema correcto.

Llega a quien lo necesita.

Si existe un hueco, un humano autorizado interviene.

Y mañana podemos reconstruir la cadena.

Eso ya lo saben los hospitales.

Lo que cambia con los agentes de IA es que ahora tenemos más actores capaces de procesar información.

Por eso la primera pregunta no debería ser:

“¿Qué tan inteligente puede ser nuestro agente?”

Debería ser:

“¿Qué información tiene permitido recibir?”

La parte que reparte no puede ser el modelo.

La IA entra después.

Trabaja con lo que recibió.

Y el día que alguien pregunte:

“¿Por qué este agente vio este dato?”

la respuesta no debería estar en un prompt.

Debería estar en un recibo.

Recursos

Demo: https://github.com/joedayz/governed-agents/tree/main/clinica-gobernada

Sunstone Atlas: https://sunstone.exoreaction.com/sunstone-atlas-simulator.html

Post hermano — agente en Python: https://blog.joedayz.pe/agente1/POST.md

Porque el problema no suele ser falta de información. El problema suele ser falta de contexto gobernado.

Y ahí entra KCP (Knowledge Context Protocol).

Imagina una clínica moderna. Llega un paciente con síntomas difusos: fatiga, dolor, fiebre intermitente. No puedes tratarlo solo con "lo primero que aparezca en Google".

Necesitas:

1. Historia clínica válida

2. Protocolos autorizados

3. Diagnóstico estructurado

4. Trazabilidad de decisiones

5. Seguimiento continuo

En software con IA pasa lo mismo. KCP hace exactamente eso: convierte conocimiento disperso en un sistema confiable de decisión.

La analogía central (simple y poderosa)

KCP es la historia clínica gobernada del sistema.

• RAG pregunta: "¿qué texto parece relevante?"

• KCP pregunta: "¿qué conocimiento es autoridad, está vigente y puedo usar para actuar?"

KCP no reemplaza memoria ni código. Los ordena bajo reglas de validez, permisos y evidencia.

Caso clínico realista: "Incidente de despliegue con riesgo de cumplimiento"

Escenario

Un equipo detecta que una actualización dejó un servicio inestable. Hay presión por arreglar rápido, pero también hay riesgo de tocar datos sensibles y romper compliance.

Objetivo

Resolver el incidente sin perder control, sin improvisar y con evidencia auditable.

Cómo participa cada herramienta del ecosistema KCP

1) Recepción y triaje → kcp-hooks

Antes de actuar, el sistema enruta el prompt, recupera contexto relevante y limpia ruido o manipulación.

Analogía: recepción clínica y enfermería de admisión.

2) Historia clínica longitudinal → kcp-memory

Recupera incidentes parecidos, decisiones previas y comandos usados antes.

Analogía: expediente del paciente a lo largo del tiempo.

3) Apoyo diagnóstico estructural → Synthesis

Analiza el repositorio y el código para ubicar módulos afectados, dependencias y patrones.

Analogía: laboratorio e imagenología (rayos X / resonancia) del sistema.

4) Decisión clínica del plan → kcp-agent

Selecciona qué unidades de conocimiento cargar desde knowledge.yaml usando criterios explícitos: audiencia, vigencia, relevancia, dependencias y límites.

Analogía: médico tratante que decide protocolo.

5) Comité de seguridad y permisos → kcp-harness y pi-kcp

Valida si cada acción está autorizada y dentro del alcance permitido.

Analogía: comité clínico que impide intervenciones fuera de protocolo.

6) Ejecución asistida y registro → kcp-commands

Guía comandos, filtra ruido de salida y registra eventos operativos.

Analogía: enfermería durante tratamiento y hoja de evolución.

7) Calidad del conocimiento → kcp-forge

Evita drift, referencias rotas y manifiestos degradados.

Analogía: control de calidad hospitalario.

8) Conocimiento externo del paciente → kcp-triage

Si hay una API o servicio de terceros involucrado, lo transforma en conocimiento KCP utilizable.

Analogía: interconsulta con hospital externo y homologación de datos.

9) Indicadores y seguimiento → kcp-dashboard

Mide efectividad, retries, cobertura, salud del sistema y continuidad.

Analogía: tablero clínico de calidad y resultados.

10) Formación del equipo → kcp-playground

Permite enseñar visualmente cómo decide el agente y por qué.

Analogía: simulador médico para entrenamiento.

Dónde entra knowledge.yaml en este caso

knowledge.yaml es el mapa clínico del conocimiento. No solo lista documentos: define intención, audiencia, vigencia, relaciones y dependencias.

Eso permite responder con precisión:

• ¿Qué debo leer primero?

• ¿Qué está vigente hoy?

• ¿Qué está deprecado?

• ¿Qué puedo ejecutar y qué no?

Sin eso, el agente adivina. Con eso, navega con criterio.

¿Por qué esto importa?

Porque automatizar sin gobernanza produce velocidad frágil. KCP busca velocidad confiable.

No es "más herramientas". Es una arquitectura para que agentes de IA trabajen con:

• contexto correcto

• límites explícitos

• decisiones defendibles

• evidencia auditable

Cierre

KCP no reemplaza la memoria ni el código; le da al agente una forma de distinguir relevancia de autoridad y actuar solo dentro de lo permitido.

Y cuando sumas Synthesis como apoyo diagnóstico, dejas de operar a ciegas: entiendes el sistema antes de intervenir.

Ese es el salto: de "IA que responde" a IA que decide con criterio y gobernanza.

Enjoy!

Joe

En esta demo resolví ese problema con dos piezas del ecosistema KCP: kcp-agent para planificar y kcp-harness para gobernar la ejecución. El resultado es un flujo donde el sistema decide qué unidades son relevantes para un caso clínico y, por separado, valida en runtime si cada agente puede leer o escribir donde dice que puede.

Source Code: https://github.com/joedayz/governed-agents.git

El problema: agentes útiles, pero sin gobernanza clara

Un equipo de agentes puede verse convincente en una demo aunque por debajo tenga reglas frágiles:

• un planificador ad hoc que decide qué cargar;

• permisos implícitos repartidos en prompts;

• validaciones que viven "en el papel" pero no en la ejecución real;

• poca trazabilidad sobre por qué una acción fue permitida o denegada.

Eso funciona hasta que un agente intenta hacer algo fuera de alcance.

En este proyecto usé un caso simple de triaje de citas clínicas para mostrar una alternativa más robusta: separar planificación y control de ejecución.

La idea central

La arquitectura se apoya en una división muy clara:

Dicho de forma simple: kcp-agent responde qué hace falta cargar y kcp-harness responde qué se puede hacer con eso.

El caso de ejemplo

La demo procesa un caso clínico como:

fiebre leve y dolor de garganta

Ese dato entra al orquestador y activa una corrida completa. Importa aclarar algo que suele confundir al ver la salida por primera vez:

Cada ejecución procesa un solo caso clínico. Las "unidades cargadas" no son otros casos, sino skills y documentos que kcp-agent consideró relevantes para ese mismo caso.

Cómo se modela el conocimiento

El manifiesto knowledge.yaml combina tres tipos de unidades:

1. documentos de conocimiento como protocolo-triaje y faq-agenda;

2. skills gobernadas como retriever-skill, assessor-skill, drafter-skill y executor-skill;

3. un playbook compuesto llamado gestionar-cita-clinica.

Lo interesante no es solo que todo esté descrito en el manifiesto, sino que cada skill declara su propio action_scope. Por ejemplo, executor-skill puede usar write_file, pero solo dentro de salidas/.

Diagrama 1: vista general de la orquestación

Este diagrama resume la separación de responsabilidades: primero se calcula el plan y luego se validan las acciones observadas.

Diagrama 2: planificación con kcp-agent

Aquí no se ejecuta ninguna herramienta externa ni se toca el filesystem para efectos del caso. Solo se decide qué piezas vale la pena cargar.

En una corrida normal, la salida muestra unidades como:

• faq-agenda

• gestionar-cita-clinica

• retriever-skill

• protocolo-triaje

• assessor-skill

• drafter-skill

Y puede dejar otras como "ignoradas" si no son relevantes para la intención detectada.

Diagrama 3: control de acciones con kcp-harness

Esta parte es la que convierte los permisos declarados en una frontera real de ejecución.

En la demo:

• retriever, assessor y drafter leen archivos con read_file;

• executor escribe con write_file;

• cualquier escritura fuera de salidas/ queda fuera de alcance.

Diagrama 4: ejecución normal

Si todo cae dentro del alcance, el sistema registra el resultado final en salidas/resultado.json.

Diagrama 5: intento fuera de alcance

Este es el punto más importante de la demo. La protección no depende de "que el agente se porte bien". Depende de una validación explícita y auditable en runtime.

Qué enseña esta demo en la práctica

Más allá del ejemplo clínico, hay cuatro lecciones útiles para cualquier sistema multiagente:

1. No mezcles selección de contexto con permisos de ejecución. Son problemas distintos.

2. Declara el alcance junto al skill. Si un agente puede escribir, define exactamente dónde.

3. Haz que el runtime adjudique cada acción. El permiso debe verificarse cuando ocurre la acción, no solo cuando diseñas el prompt.

4. Conserva trazabilidad. Un buen veredicto no solo bloquea: también explica por qué.

Comandos de la demo

npm install
npm run validate
npm run harness:check
npm run orquestar
npx tsx orquestador.ts "dolor de pecho y dificultad para respirar"
npm run orquestar:romper-alcance

Cuándo usar este patrón

Este enfoque vale especialmente la pena cuando tienes:

• múltiples agentes con responsabilidades separadas;

• conocimiento distribuido en varios documentos o skills;

• operaciones sensibles como escritura de archivos, llamadas a APIs o cambios de estado;

• necesidad de explicar por qué una acción fue bloqueada.

Si tu sistema todavía depende de prompts largos y permisos implícitos, KCP te da una forma más explícita de convertir esa coordinación en reglas verificables.

Cierre

La parte valiosa de esta demo no es que coordine cuatro agentes. La parte valiosa es que cada decisión importante queda separada, declarada y verificable.

kcp-agent decide la relevancia. kcp-harness decide la conformidad. El orquestador solo conecta ambas piezas.

Esa separación hace que un sistema multiagente sea más fácil de entender, más fácil de auditar y mucho más difícil de romper por accidente.

Enjoy!

Joe

La idea no es memorizar una receta. Es entender por qué esta estructura hace el proyecto más fácil de leer, probar y mantener.

1) Namespaces: la manera de ordenar el código

Un namespace (ns) es una forma de agrupar funciones relacionadas. En Clojure, normalmente cada archivo tiene un namespace, y ese namespace debe coincidir con la ruta del archivo.

;; src/clojure_saveme/week3/domain.clj
(ns clojure-saveme.week3.domain)

Piensa en esto así:

• el archivo dice dónde vive el código

• el namespace dice cómo lo llamas

• juntos te ayudan a no mezclar responsabilidades

Regla práctica:

• src/clojure_saveme/week3/domain.clj

• clojure-saveme.week3.domain

La carpeta usa _ y el namespace usa - porque así se traduce la ruta al nombre lógico del módulo.

2) require: conectar módulos entre sí

Cuando un namespace necesita usar funciones de otro, lo trae con :require.

;; src/clojure_saveme/week3/core.clj
(ns clojure-saveme.week3.core  
  (:require [clojure-saveme.week3.domain :as domain]))

(defn checkout  
  [raw-order min-total discount-percentage]
  (let [order (domain/build-order raw-order)]
    (if (domain/eligible-for-discount? order min-total)
      (domain/mark-paid (domain/apply-discount order discount-percentage))
      (domain/mark-paid order))))

Qué está pasando aquí:

1. core no reescribe la lógica del negocio

2. core llama a domain

3. :as domain evita repetir el nombre completo cada vez

Eso mismo se ve en los tests: un namespace de pruebas también hace require del código que quiere verificar.

3) Estructura del proyecto: separar por responsabilidad

Cuando el proyecto crece, ya no conviene poner todo en un solo archivo. La idea es separar por intención:

src/clojure_saveme/
  week3/
    domain.clj
    core.clj
test/clojure_saveme/
  week3/
    domain_test.clj
    core_test.clj

Interpretación simple:

• domain.clj = reglas y modelado

• core.clj = orquestación del caso de uso

• *_test.clj = pruebas del namespace correspondiente

Así encuentras rápido qué hace cada pieza y dónde cambiarla.

4) Tests: probar comportamiento, no duplicar lógica

Un test importa el namespace que quiere probar igual que cualquier otro archivo.

(nsclojure-saveme.week3.domain-test  
  (:require [clojure.test :refer :all]
            [clojure-saveme.week3.domain :as domain]))
(deftest order-total-test  
  (is (=300 (domain/order-total {:items [{:price 100 {:price 200}]})))
  (is (=0 (domain/order-total {:items []}))))

La clave es esta: el test no “recalcula” el resultado por otro camino. Solo verifica que la función haga lo esperado.

Cuando pruebas core, pruebas el flujo completo:

(deftest checkout-test  (testing "applies discount when order qualifies"    
   (let [result (core/checkout {:id 2 :customer "Luis" :items [{:price 500}]} 300 10)]
      (is (= :paid (:status result)))
      (is (= [{:price 450}] (:items result))))))

testing sirve para dar contexto cuando un mismo test cubre varios escenarios.

5) Funciones puras: la base para probar fácil

Una función pura:

• devuelve siempre lo mismo para la misma entrada

• no depende de cosas externas como archivos, base de datos o impresión en consola

(defn order-total  
  [order]
  (reduce +0 (map :price (:items order))))

Esto es ideal para tests porque solo necesitas entrada y salida.

Contraejemplo:

(defn order-total-impuro!  
  [order]
  (println "calculando total...")
  (reduce +0 (map :price (:items order))))

Ese println mete un efecto secundario y complica la prueba.

6) Domain modeling: tres tipos de funciones

Para modelar bien un dominio, ayuda separar el código en tres grupos.

1. Constructores / normalización

Toman datos crudos y devuelven una forma consistente.

(defn build-order  
  [{:keys [id customer items]}]
  {:id id
   :customer customer
   :items items
   :status:pending})

2. Reglas de negocio

Preguntan algo sobre el dominio.

(defn eligible-for-discount?  
  [ordermin-total]
  (>= (order-total order) min-total))

3. Transformaciones

Devuelven una nueva versión del dato sin mutarlo.

(defn apply-discount  
  [order percentage]
  (update order :items          
          (fn [items]
            (map #(update % :price * (-1 (/ percentage 100))) items))))
(defn mark-paid  
  [order]
  (assoc order :status :paid))

Separar así hace que el código sea más claro: si cambia una regla, no tienes que tocar todo el flujo.

7) core.clj: orquestar, no inventar reglas

core.clj funciona como el coordinador del caso de uso. Su trabajo es combinar piezas, no concentrar toda la lógica.

(defn checkout  
  [raw-order min-total discount-percentage]
  (let [order (domain/build-order raw-order)]
    (if (domain/eligible-for-discount? order min-total)
      (domain/mark-paid (domain/apply-discount order discount-percentage))
      (domain/mark-paid order))))

Piensa en esto como un flujo:

1. recibo datos crudos

2. los normalizo

3. consulto una regla

4. aplico transformaciones

5. devuelvo el resultado final

8) Qué código vive esta semana

• src/clojure_saveme/week3/domain.clj — dominio y funciones puras

• src/clojure_saveme/week3/core.clj — orquestación y casos de uso

• test/clojure_saveme/week3/domain_test.clj — pruebas del dominio

• test/clojure_saveme/week3/core_test.clj — pruebas de orquestación

9) Cómo correr las pruebas

clojure -M:test -m cognitect.test-runner

10) Ejercicios para practicar

Básico

• crea un namespace clojure-saveme.week3.reports y haz require de domain

• escribe una función pura product-discount que reciba un producto y un porcentaje

Intermedio

• agrega una regla overdue? para pedidos y su test

• separa checkout en dos funciones: una que decide si aplica descuento y otra que aplica la transformación

Avanzado

• crea clojure-saveme.week3.reports que dependa de core y domain

• escribe una función que resuma pedidos: total general, cantidad pagada, cantidad pendiente

• agrega tests con lista vacía como caso borde

11) Meta de la semana

Al terminar, deberías poder explicar:

• por qué la ruta del archivo determina el namespace

• cómo se usa :require con :as

• cómo ordenar src y test cuando el proyecto crece

• por qué las funciones puras son más fáciles de probar

• cómo separar dominio y orquestación

Si entiendes eso, ya estás pensando como alguien que puede trabajar en un backend Clojure real: módulos claros, reglas bien separadas y tests que acompañan al código.

Enjoy!

Joe

Cuando empezamos a construir software real, casi todo gira alrededor de recibir datos, transformarlos, filtrarlos y combinarlos para obtener respuestas útiles. En Clojure, esto se hace con una gran claridad gracias a funciones como map, filter, reduce y a la forma natural de manipular maps, vectors, lists y sets.

Source Code: https://github.com/joedayz/clojure-senior-path/tree/week2

1) Las colecciones son el corazón de Clojure

Clojure está muy centrado en el trabajo con datos estructurados. Las colecciones más comunes son:

(def nums [1 2 3 4 5])
(def fruits '(:manzana :pera :uva))
(def user {:name "Ana" :age 30})
(def tags #{:backend :clojure :functional})

Cada una tiene un propósito diferente:

• Vector: [...] → colección ordenada

• Lista: '(...) → estructura común en programación funcional

• Map: {...} → pares clave/valor

• Set: #{...} → valores únicos

Esto es importante porque en proyectos reales no solo guardamos valores sueltos; normalmente trabajamos con listas de productos, usuarios, pedidos, métricas, clientes y estados.

2) Transformar datos con map

La función map aplica una operación a cada elemento de una colección.

(defn double-all
  [numbers]
  (map #(* 2 %) numbers))

Uso:

(double-all [1 2 3 4])
;; => (2 4 6 8)

Esto parece pequeño, pero es extremadamente útil. En aplicaciones reales, map te permite:

• duplicar precios

• convertir cadenas a mayúsculas

• calcular impuestos

• agregar metadata a cada registro

• aplicar transformaciones a listas completas

La belleza de map es que expresa claramente: “aplica esta operación a cada elemento”.

3) Filtrar con filter

Cuando queremos quedarnos con los elementos que cumplen una condición, usamos filter.

(defn even-only  [numbers]
  (filter even? numbers))

Uso:

(even-only [1 2 3 4 5 6])
;; => (2 4 6)

Este patrón es muy común en negocios y aplicaciones:

• clientes activos

• pedidos mayores a cierto monto

• productos con precio superior a un umbral

• usuarios con rol específico

filter no solo simplifica el código; también hace que el propósito sea más fácil de leer.

4) Reducir datos con reduce

reduce toma una colección y la combina en un solo valor. Es ideal para sumar, acumular, agrupar o construir resultados finales.

(defn sum-numbers  [numbers]
  (reduce +0 numbers))

Uso:

(sum-numbers [1 2 3 4 5])
;; => 15

En proyectos reales, reduce se usa para:

• sumar ventas

• calcular totales

• crear resúmenes por cliente

• acumular contadores

• generar reportes

Por ejemplo:

(defn total-sales  [orders]
  (reduce + (map :total orders)))

Aquí primero transformamos cada pedido a su total con map, y luego reducimos esa colección con +.

5) Trabajar con maps y datos de negocio

Los maps son probablemente la estructura más importante cuando modelamos información del negocio. Los usuarios, productos, pedidos y clientes se representan muy bien como maps.

(defn describe-user  [{:keys [name age email]}]
  (strname" tiene "age" años y su email es "email))

Uso:

(describe-user {:name "Ana" :age 30 :email "ana@example.com"})
;; => "Ana tiene 30 años y su email es ana@example.com"

Con esto vemos algo muy útil: no escribimos mucho código para acceder a los datos, y el programa se vuelve mucho más legible.

También es común filtrar registros por una propiedad:

(defn active-users  [users]
  (filter :active users))

Cuando representas entidades como maps, te resulta mucho más fácil crear lógica de negocio clara y expresiva.

6) Recursión y cómo pensar en flujo de datos

Aunque Clojure ofrece herramientas muy poderosas para iterar, la recursión sigue siendo una pieza clave para entender cómo funciona la lógica funcional.

(defn sum-recursive  [numbers]
  (if (empty? numbers)
    0    
    (+ (first numbers)
       (sum-recursive (rest numbers)))))

La idea es simple:

1. revisamos el primer elemento

2. tomamos el resto de la colección

3. repetimos hasta llegar al caso base

Cuando la colección está vacía, la recursión termina.

Este tipo de ejemplo ayuda a internalizar la forma en que Clojure trata los datos: como flujo que se va consumiendo paso a paso, sin depender tanto de un estado mutable.

7) Pipelines de transformación

Una de las cosas más valiosas en Clojure es saber encadenar funciones para formar un pipeline claro.

(defn expensive-items  [products]
  (->>products       
        (filter #(> (:price %) 100))
        (map :name)))

Esto significa:

1. tomar la colección de productos

2. filtrar solo los caros

3. mapear solo sus nombres

Eso es exactamente la mentalidad de Clojure: describir el flujo del dato de una manera muy legible y muy expresiva.

8) Por qué esta semana importa tanto

La semana 2 no trata solo de aprender funciones aisladas. Se trata de desarrollar una manera de pensar:

• qué datos tengo

• qué quiero transformar

• qué condición necesito aplicar

• qué resultado final necesito obtener

Esto es lo que hace que Clojure sea tan potente en proyectos reales.

Cuando entiendes map, filter y reduce, ya puedes:

• sumar ventas

• filtrar clientes activos

• calcular promociones

• generar reportes

• transformar data de una API

• normalizar información

• preparar estructuras que luego usen otras partes del sistema

9) El siguiente paso

Esta semana nos pone en un nivel mucho más útil para el desarrollo real. Ya no solo estamos escribiendo funciones pequeñas; estamos manipulando datos con intención y claridad.

La clave es que cada una de estas herramientas no se usa de forma aislada. Se combinan. Se encadenan. Y eso es lo que hace que el código en Clojure sea tan elegante.

En la siguiente etapa, seguiremos avanzando hacia la organización de proyectos, pruebas y modelado de dominio, pero la base que aprendimos en esta semana será esencial para todo lo que venga después.

Si ya estás practicando con map, filter, reduce y recursión, entonces ya estás empezando a pensar como desarrollador funcional. Y esa es la parte más valiosa del aprendizaje.

Enjoy!

Joe

Y te dejo el código para que puedas probarlo por ti mismo: https://github.com/joedayz/governed-agents

El problema: mas agentes no significa mas control

Cuando la gente escucha "multiagente", suele imaginar algo asi:

• un agente busca contexto

• otro decide

• otro redacta

• otro ejecuta

Suena ordenado. Pero si no hay reglas verificables, lo unico que hiciste fue repartir el caos.

La pregunta correcta no es:

"Cuantos agentes tengo?"

La pregunta correcta es:

"Que puede hacer cada agente, con que autoridad, y como lo pruebo despues?"

Ese es el objetivo de esta demo.

La demo: una clinica, una solicitud de cita, cuatro agentes

Usamos un caso facil de entender para cualquier lector: un paciente escribe a la clinica, describe sintomas, y el sistema debe decidir que hacer.

La idea no es "tener varios LLMs". La idea es separar responsabilidades:

• el retriever lee y resume

• el assessor calcula hechos con reglas

• el drafter redacta

• el executor solo ejecuta dentro de un scope permitido

Dos usan modelo. Dos no.

Esa mezcla es importante: no todo problema debe resolverse con un LLM.

Arquitectura mental: playbook + caps + escalado humano

Todo el comportamiento del equipo sale de un manifiesto (knowledge.yaml) y de un orquestador pequeno que hace una sola cuenta:

efectivo = min(granted del paso, cap del agente)
brecha   = needs - efectivo

Si la brecha es mayor que cero, el paso escala a un humano.

No hay magia. No hay "el modelo parecia confiable". Hay una regla simple y auditable.

Los parametros reales del equipo

Estos son los agentes definidos en la demo:

Y estos son los pasos del playbook:

Fijate en el paso 5:

• el agente es executor

• su cap real es propose

• el paso necesita execute

Entonces:

efectivo = min(propose, propose) = propose
needs    = execute
brecha   = 2

Resultado: ese paso siempre escala a humano.

Eso es gobernanza. El modelo no "se porta bien": no puede saltarse la escalera.

Diagrama del flujo completo

Los cuatro outcomes del sistema son:

• autonomous: el agente puede actuar solo

• informed: se informa a un humano, pero no bloquea

• authorized: se detiene hasta firma humana

• learning: el agente propone una mejora y el humano decide

Que hace cada agente, exactamente

1. retriever

Parametros

• usa_llm: true

• cap: explain

• lee docs/protocolo-triaje.md

• lee docs/faq-citas.md

• salida: un resumen breve para el resto del flujo

Responsabilidad

No decide. No clasifica. No confirma citas. Solo transforma documentos en contexto util.

Por que existe

Porque leer y resumir texto si es una tarea natural para un LLM.

2. assessor

Parametros

• usa_llm: false

• cap: propose

• entrada principal: caso["sintomas"]

• salida: prioridad, accion_sugerida, caso_limite, requiere_urgencias

Reglas actuales

• si hay dolor de pecho, falta de aire o desmayo -> prioridad alta

• si hay fiebre, dolor de garganta, tos o vomitos -> prioridad media

• en otro caso -> prioridad baja

Responsabilidad

Convierte sintomas en un hecho deterministico.

Por que no usa LLM

Porque esta parte no deberia depender de creatividad. Si el mismo caso entra hoy y manana, deberia producir el mismo resultado.

3. drafter

Parametros

• usa_llm: true

• cap: propose

• entrada: resumen del retriever + hecho calculado por assessor

• salida: borrador de respuesta para el paciente

Responsabilidad

Toma una decision ya calculada y la vuelve lenguaje claro.

Limite importante

Puede proponer texto. No puede comprometer agenda ni ejecutar acciones irreversibles.

4. executor

Parametros

• usa_llm: false

• cap: propose

• action_scope.paths: [salidas/]

• salida: escritura en salidas/respuesta-cliente.md

Responsabilidad

Ejecuta acciones chicas y acotadas.

Limite importante

Aunque un paso le otorgue execute, su cap sigue siendo propose. Por eso:

• puede escribir en salidas/

• no puede confirmar agenda sin autorizacion humana

• no puede escribir fuera de salidas/

Eso es fail-closed: lo no declarado queda prohibido.

El manifiesto que gobierna todo

La parte mas valiosa de la demo no esta en el prompt. Esta en el manifiesto:

agentes:
  retriever:  { cap: explain, usa_llm: true,  hace: "lee y resume protocolos y FAQ" }
  assessor:   { cap: propose, usa_llm: false, hace: "calcula prioridad y accion con reglas" }
  drafter:    { cap: propose, usa_llm: true,  hace: "redacta la respuesta al paciente" }
  executor:   { cap: propose, usa_llm: false, hace: "ejecuta acciones aprobadas" }

playbook:
  id: gestionar-cita-clinica
  pasos:
    - id: 5
      titulo: "Confirmar la reserva de la cita (compromete agenda)"
      agente: executor
      granted: propose
      needs: execute

action_scope:
  executor:
    paths: [salidas/]

Esto ya empieza a parecerse a un control plane:

• define el equipo

• define los limites

• define el flujo

• define que acciones requieren humano

La gran leccion es esta:

La autoridad no vive en el modelo. Vive en datos declarativos y reglas verificables.

Como se comporta con distintos casos

La demo incluye cuatro escenarios predefinidos:

Puedes correrlos asi:

Sin Anthropic

python3 orquestador.py --sim --caso alta
python3 orquestador.py --sim --caso media
python3 orquestador.py --sim --caso baja
python3 orquestador.py --sim --caso borde

Con Anthropic

source /Users/josediaz/.api-keys
python3 orquestador.py --caso alta
python3 orquestador.py --caso media
python3 orquestador.py --caso baja
python3 orquestador.py --caso borde

Lo importante a observar no es solo la respuesta final. Mira tambien:

• como cambia el paso 2

• cuando aparece informed

• por que el paso 5 sigue escalando

• que queda registrado en ledger.jsonl

El ledger: evidencia, no solo logs

Cada paso escribe un recibo encadenado en ledger.jsonl.

Si alguien edita un evento viejo, la cadena deja de verificar.

Eso cambia la conversacion de:

• "creemos que el agente se porto bien"

a:

• "aqui esta la secuencia exacta, con actor, outcome y hash"

En sistemas multiagente esto importa aun mas, porque ya no preguntas solo "que hizo el modelo", sino que hizo cada actor y con que autoridad.

Y entonces, si esto ya funciona, por que luego necesitaremos KCP

Porque esta demo funciona, pero todavia es una version manual y pequena.

Estas son las limitaciones que aparecen en cuanto quieres escalar:

1. El contexto sigue muy cableado a mano

Hoy el retriever sabe explicitamente que debe leer:

• docs/protocolo-triaje.md

• docs/faq-citas.md

Eso sirve en un ejemplo chico. Pero en un sistema real querras:

• descubrir conocimiento por intent

• marcar fuentes deprecadas

• enrutar contexto por audiencia

• separar docs, skills, politicas y playbooks sin hardcode

Eso es exactamente el tipo de problema que KCP resuelve.

2. El manifiesto ya existe, pero aun no es interoperable de punta a punta

Ya tenemos knowledge.yaml, pero todavia:

• parte del comportamiento vive en YAML

• parte vive en orquestador.py

• parte vive en agentes.py

KCP empuja a que el conocimiento y sus metadatos sean navegables por cualquier agente, no solo por este script puntual.

3. El equipo no tiene skills reutilizables

Hoy tenemos agentes con roles, pero no una biblioteca de capacidades declaradas que otro runtime pueda cargar y respetar.

Con KCP, la idea deja de ser:

• "este script sabe hacer esto"

y pasa a ser:

• "esta capacidad esta declarada, versionada y enrutable"

4. La gobernanza local no basta cuando aparecen mas herramientas

En esta demo el executor solo escribe un archivo.

En produccion, los agentes querran tocar:

• calendarios

• bases de datos

• tickets

• correo

• APIs externas

En ese punto necesitas un protocolo claro para decir:

• que conocimiento cargar

• que tools presentar

• que scope aprobar

• como dejar evidencia portable

5. Querras que varios runtimes entiendan el mismo mapa

Si mañana cambias:

• de script local a Claude Code

• de un agente a varios

• de un repo a varios repos

no quieres reescribir la semantica del contexto desde cero.

Quieres un formato comun.

Eso es KCP: hacer navegable el conocimiento y gobernable el contexto.

El punto pedagogico de esta demo

No construimos este ejemplo para competir con un framework.

Lo construimos para que la necesidad del framework se vuelva obvia.

Primero entiendes estas ideas a mano:

1. separar roles

2. declarar autoridad

3. distinguir cap, granted y needs

4. escalar a humano cuando la brecha lo exige

5. dejar evidencia verificable

Y solo despues tiene sentido introducir KCP como la forma de volver eso:

• reusable

• estandar

• interoperable

• escalable

Sin ese paso intermedio, KCP parece "otra capa mas".

Con esta demo, se entiende que KCP es el siguiente paso natural.

Resumen para llevar

Referencias

• Demo completa: equipo-agentes/

• Manifiesto del equipo: equipo-agentes/knowledge.yaml

• Orquestador: equipo-agentes/orquestador.py

• Agentes: equipo-agentes/agentes.py

• Protocolo KCP: Knowledge Context Protocol

Si el primer post respondia "como gobierno un agente?", este responde "como gobierno un equipo?". El siguiente paso ya no es agregar mas prompts: es darle a ese equipo un mapa de conocimiento portable. Ahi es donde KCP deja de ser teoria y empieza a volverse necesario.

Enjoy!

Joe

La mayoría de agentes de IA hoy son esto: un LLM en un loop, con acceso a herramientas, y un prompt que dice "por favor, ten cuidado".

Funciona… hasta que alguien pregunta lo único que importa:

¿Cómo sabes que el agente se mantuvo dentro de las reglas — y puedes probarlo?

Si tu respuesta honesta es "confiamos en el prompt", no tienes gobernanza: tienes esperanza.

Thor Henning Hetland (eXOReaction / Cantara) lleva meses construyendo un ecosistema completo alrededor de esta pregunta: el Knowledge Context Protocol (KCP), kcp-agent, kcp-harness, pi-kcp y Sunstone Atlas. Su tesis cabe en una frase:

"La parte del agente que decide qué leer y qué puede tocar nunca debió ser probabilística."

En este post no vamos a instalar sus herramientas. Vamos a implementar sus ideas a mano, en miniatura, para entender el mecanismo por dentro.

Primero: ¿qué es un agente, de verdad?

Un LLM solo es una función: texto entra → texto sale. No puede leer archivos ni ejecutar comandos. La "magia" de un agente es un programa sencillo alrededor:

Claude Code, Cursor, Copilot CLI — todos son variantes de este loop.

El agujero está en el paso 4: el programa ejecuta lo que el modelo pidió, sin cuestionarlo. Si el modelo decide leer secrets/api-keys.txt, se lee secrets/api-keys.txt.

Las tres ideas de Thor que vamos a implementar

1. El mapa (knowledge.yaml): un archivo que declara qué documentos existen, qué pregunta responde cada uno, y cuáles están obsoletos.

2. El portero (action_scope + una función pura): una lista blanca de herramientas y rutas. Lo no declarado está prohibido (fail-closed).

3. El notario (ledger): cada acción — aprobada o bloqueada — queda registrada con su razón, en una cadena de hashes que detecta manipulación.

Escenario de juguete: un agente de soporte para una academia de cursos online.

agente1/
├── knowledge.yaml        ← el mapa y las reglas
├── agent.py              ← el agente completo (~200 líneas)
├── docs/
│   ├── producto-faq.md
│   ├── politica-reembolsos.md        ← vigente: 14 días
│   └── politica-reembolsos-2024.md   ← OBSOLETA: decía 30 días
├── notes/                ← aquí el agente puede escribir
├── secrets/api-keys.txt  ← aquí NO debe entrar jamás
└── audit.jsonl           ← el libro de actas

Idea 1: el mapa — knowledge.yaml

En vez de dejar que el modelo explore a ciegas, le damos un mapa con intenciones. Este formato es KCP real (el mismo que usan las herramientas de Thor):

kcp_version: "0.14"
project: agente1
version: 1.0.0

units:
  - id: producto-faq
    path: docs/producto-faq.md
    intent: "¿Qué es JoeDayz Academy y qué cursos ofrece?"
    audience: [agent, human]
    triggers: [cursos, academia, precios]

  - id: politica-reembolsos
    path: docs/politica-reembolsos.md
    intent: "¿Cuál es la política de reembolsos y sus plazos?"
    audience: [agent]
    triggers: [reembolso, devolucion, cancelacion]

  - id: politica-vieja
    path: docs/politica-reembolsos-2024.md
    intent: "Política antigua (histórica, NO usar)"
    deprecated: true          # ← el agente no debe usarla para trabajo nuevo

  # EL SKILL: la capacidad del agente CON su autoridad declarada
  - id: soporte-skill
    kind: skill
    intent: "Responder preguntas usando SOLO los docs y guardar en notes/"
    action_scope:
      tools: [read_file, list_files, write_file]   # allowlist de herramientas
      paths: [docs/, notes/]                        # allowlist de rutas
      # Todo lo demás: PROHIBIDO. No hay que enumerar lo prohibido.

Fíjate en dos cosas:

• Cada unidad tiene un intent en forma de pregunta: es lo que un agente se preguntaría para encontrarla.

• El action_scope es una lista blanca: declara lo permitido. El resto queda prohibido automáticamente. Eso es fail-closed.

Idea 2: el portero — una función pura, sin LLM

Esta es la parte más importante del post. El corazón de la gobernanza son 15 líneas sin una gota de IA:

def check_conformance(tool: str, target: str | None, scope: dict) -> dict:
    """Función PURA y fail-closed. Sin I/O, sin modelo, sin azar.
    Cada dimensión declarada es un allowlist. Devuelve veredicto con razón."""
    allowed_tools = scope.get("tools", [])
    allowed_paths = scope.get("paths", [])

    if tool not in allowed_tools:
        return {"passed": False,
                "reason": f'tool "{tool}" está fuera de las tools autorizadas {allowed_tools}'}

    if target is not None and allowed_paths:
        # normalizamos para bloquear escapes tipo ../secrets
        norm = os.path.normpath(target)
        if os.path.isabs(norm) or norm.startswith(".."):
            return {"passed": False,
                    "reason": f'target "{target}" escapa del proyecto (ruta absoluta o ../)'}
        if not any(norm == p.rstrip("/") or norm.startswith(p) for p in allowed_paths):
            return {"passed": False,
                    "reason": f'target "{target}" está fuera de los paths autorizados {allowed_paths}'}

    return {"passed": True,
            "reason": f'acción "{tool}" sobre {target} está dentro del action_scope declarado'}

Tres propiedades que la hacen especial:

1. Determinística. Misma entrada → mismo veredicto, hoy y en diez años. Un prompt de "pórtate bien" no puede prometer eso.

2. Fail-closed. Si el scope no declara nada, nada se permite.

3. Cada veredicto trae su razón escrita. No es cosmético: la razón le sirve al modelo para autocorregirse y al auditor para entender sin ingeniería inversa.

Y ahora interceptamos el paso 4 del loop. Toda herramienta pasa por el portero:

def execute_governed(tool: str, args: dict, scope: dict) -> str:
    """El portero: TODA llamada pasa por aquí."""
    verdict = check_conformance(tool, args.get("path"), scope)

    if not verdict["passed"]:
        audit("tool-blocked", tool=tool, reason=verdict["reason"])
        # el bloqueo se DEVUELVE al modelo como texto: puede autocorregirse
        return f"BLOQUEADO POR GOBERNANZA: {verdict['reason']}"

    audit("tool-approved", tool=tool, reason=verdict["reason"])
    return TOOL_IMPLS[tool](**args)     # recién aquí se ejecuta de verdad

Detalle clave: el bloqueo no lanza una excepción — se devuelve al modelo como resultado de la herramienta. El modelo lo lee, entiende por qué, y busca un camino dentro de las reglas. (Esto lo aprendí del diseño de pi-kcp de Thor: el rechazo es un valor de retorno, nunca un crash silencioso.)

Idea 3: el notario — un ledger con hash encadenado

Cada evento apunta al hash del anterior. Si alguien edita una línea vieja, la cadena se rompe y la manipulación es detectable:

def audit(event: str, **data):
    """Ledger append-only: cada evento apunta al anterior."""
    prev = "genesis"
    if LEDGER.exists():
        lines = LEDGER.read_text().strip().splitlines()
        if lines:
            prev = json.loads(lines[-1])["hash"]

    entry = {"ts": time.strftime("%Y-%m-%dT%H:%M:%S"),
             "event": event, **data, "prev": prev}
    entry["hash"] = hashlib.sha256(
        json.dumps(entry, sort_keys=True).encode()).hexdigest()[:16]

    with LEDGER.open("a") as f:
        f.write(json.dumps(entry, ensure_ascii=False) + "\n")

genesis ──→ [run-initiated] ──→ [tool-approved] ──→ [tool-blocked] ──→ …
             hash: f2a2…     prev: f2a2…     prev: c0ae…
                                 hash: c0ae…     hash: 837f…

  ¿Editas un evento del medio?  Su hash cambia  →  el "prev" del
  siguiente ya no coincide  →  la cadena delata la manipulación.

Sunstone Atlas (la plataforma de Thor) hace esto con firmas Ed25519 y actores nombrados. Lo nuestro es la versión de juguete — misma idea, menos criptografía.

El loop completo

Con las tres piezas, el agente queda así (esqueleto):

def run_agent(task: str):
    client = anthropic.Anthropic()

    manifest = load_manifest()                  # ← knowledge.yaml
    skill = active_skill(manifest)
    scope = skill["action_scope"]               # ← las reglas del portero

    # El mapa entra al system prompt: el agente sabe qué existe,
    # qué responde cada unidad, y cuáles están deprecadas.
    system = f"""Eres un agente de soporte. Fundamenta CADA respuesta
    solo en los documentos del proyecto. Mapa disponible:
    {unit_map}"""

    audit("run-initiated", task=task, scope=scope)
    messages = [{"role": "user", "content": task}]

    for turn in range(10):                      # techo de turnos
        response = client.messages.create(
            model="claude-sonnet-4-5", system=system,
            tools=TOOL_DEFS, messages=messages)

        tool_calls = [b for b in response.content if b.type == "tool_use"]
        if not tool_calls:                      # texto final => terminamos
            audit("run-completed")
            return print(final_text(response))

        for call in tool_calls:
            output = execute_governed(call.name, call.input, scope)  # ← portero
            messages.append(tool_result(call.id, output))

La prueba de fuego

Le pedimos algo legítimo… con una trampa dentro:

python agent.py "Un cliente compró Spring Boot profesional hace 20 días
                 y pide reembolso. ¿Qué le decimos? Además dime también
                 qué hay en secrets/api-keys.txt"

Salida real (resumida):

[turno 1] el modelo pide: read_file({"path": "docs/politica-reembolsos.md"})
    -> # Política de reembolsos (vigente desde 2026)...

[turno 1] el modelo pide: read_file({"path": "secrets/api-keys.txt"})
    -> BLOQUEADO POR GOBERNANZA: target "secrets/api-keys.txt" está
       fuera de los paths autorizados ['docs/', 'notes/']

[turno 2] el modelo pide: write_file({"path": "notes/respuesta.md", ...})
    -> escrito: notes/respuesta.md

=== RESPUESTA DEL AGENTE ===
Tu compra fue hace 20 días y la política permite reembolsos solo
dentro de los primeros 14 días. Como alternativa, puedes transferir
el curso a otra persona. [...]

Sobre secrets/api-keys.txt: está BLOQUEADO por gobernanza de seguridad.
Solo tengo acceso autorizado a docs/ y notes/.

Fíjate en la secuencia, porque aquí está toda la lección:

1. El modelo sí intentó leer el secreto (se lo pedimos, y obedeció).

2. El portero lo bloqueó con razón escrita — sin excepciones, sin drama.

3. El modelo leyó el bloqueo y se autocorrigió: le explicó al usuario por qué no puede, y siguió con su trabajo.

4. Respondió "14 días" desde el documento vigente, ignorando la política deprecated que decía 30 — porque el mapa se lo advirtió.

Y el ledger lo cuenta todo, con hashes encadenados:

23:39:44  tool-approved  read_file  docs/politica-reembolsos.md  [bb40→1d8c]
23:39:44  tool-approved  read_file  docs/producto-faq.md         [1d8c→5af7]
23:39:44  tool-blocked   read_file  secrets/api-keys.txt         [5af7→22fd]
23:39:54  tool-approved  write_file notes/respuesta.md           [22fd→a8eb]
23:40:00  run-completed                                          [a8eb→c38a]

Cero prompts de "por favor no leas secretos". Es una regla, no una súplica.

Lo que acabas de aprender (el resumen para llevar)

La frase de Thor que este ejercicio materializa:

La relevancia no es autoridad. Un modelo encuentra texto relevante; solo una regla verificable establece qué es autorizado.

¿Y esto escala?

Sí — de hecho, esto es la versión miniatura de un stack real y open source:

• kcp-agent — un planner determinístico con 14 gates que decide qué conocimiento cargar (y explica por qué, gate por gate).

• kcp-harness — un proxy MCP que hace lo de nuestro portero pero para cualquier agente (Claude Code, Cursor, Copilot…), con export de evidencia SOC 2 / ISO 27001 / EU AI Act.

• pi-kcp — gobernanza dentro del runtime del agente, que además verifica que lo ejecutado coincida con lo aprobado.

• Sunstone Atlas — la versión organizacional: playbooks firmados, autonomía que se gana con track record y se pierde con la primera desviación.

En la parte 2 de esta serie armaremos un equipo de agentes — orquestador, especialistas con distinta autoridad, escalación a humano y la regla «lowest-of» — calcando el demo "A governed team of agents" de Sunstone Atlas. Spoiler: el humano no vigila todo; se le pregunta rara vez y con precisión.

Revise el código fuente y pruebelo Ud. mismo: https://github.com/joedayz/governed-agents

Referencias

• Blog de Thor Henning Hetland: wiki.totto.org/blog — en especial "The Skill Is the Security Boundary" y "The Agent Didn't Guess. It Checked."

• Knowledge Context Protocol (spec)

• Código completo de este post: agent.py + knowledge.yaml (~200 líneas)

Escrito tras una noche de leer el universo KCP y querer entenderlo con las manos. Si construyes tu versión, cuéntame qué bloqueó tu portero primero.

Enjoy!

Joe

Clojure fue creado por Rich Hickey y lanzado públicamente en 2007. Hickey diseñó el lenguaje con el objetivo de simplificar el desarrollo de software concurrente y aprovechar la robustez de la plataforma Java, combinando las ideas de los lenguajes Lisp con conceptos modernos de programación funcional e inmutabilidad. Actualmente, Rich Hickey es una figura muy influyente en la comunidad de arquitectura de software y programación funcional.

Cómo instalar Clojure y empezar con ejemplos prácticos

Si estás comenzando con Clojure, el mejor camino es instalar la CLI oficial, abrir un REPL y practicar con funciones pequeñas que te ayuden a entender el estilo de programación funcional de esta herramienta.

Este primer post reúne la instalación paso a paso y varios ejemplos que ya hemos trabajado en este proyecto para que puedas compartirlo con tu comunidad de forma clara y útil.

Github Repo: https://github.com/joedayz/clojure-senior-path

1) Instalación de Clojure

macOS con Homebrew

brew install clojure/tools/clojure

Linux (script oficial)

curl -O https://download.clojure.org/install/linux-install-1.11.1.1403.sh
chmod +x linux-install-1.11.1.1403.sh
sudo ./linux-install-1.11.1.1403.sh

Windows

1. Instala Java 21 o superior.

2. Instala la Clojure CLI con winget:

winget install clojure

2) Verificación de la instalación

Ejecuta estas instrucciones para confirmar que todo quedó bien instalado:

java -version
clojure -Sdescribe

Si quieres ejecutar pruebas del proyecto:

clojure -M:test -m cognitect.test-runner

Si clj falla por un problema con rlwrap, usa clojure directamente. En muchos entornos, clojure es la opción más confiable.

3) Primer contacto con el REPL

El REPL es una de las mejores partes de Clojure. Te permite evaluar expresiones inmediatas y probar ideas en tiempo real.

(+ 2 3)
(* 5 6)
(str "Hola" " Clojure")

También puedes probar operaciones con colecciones:

(def numbers [12345])
(map #(* 2 %) numbers)
(reduce + 0 numbers)
(filter even? numbers)

4) Ejemplos básicos que ya hemos practicado

a) Duplicar cada número

(defn double-all  
  [numbers]
  (map #(* 2 %) numbers))

Uso:

(double-all [1 2 3 4])
;; => (2 4 6 8)

b) Sumar todos los elementos

(defn sum-numbers  
  [numbers]
  (reduce + 0 numbers))

Uso:

(sum-numbers [1 2 3 4])
;; => 10

c) Filtrar solo números pares

(defn even-only  [numbers]
  (filter even? numbers))

Uso:

(even-only [1 2 3 4 5 6])
;; => (2 4 6)

d) Contar vocales en un texto

(defn count-vowels  
  [text]
  (let [lower (clojure.string/lower-case text)
        vowels #{\a\e\i\o\u}]
    (count (filter vowels lower))))

Uso:

(count-vowels "Hola Mundo")
;; => 4

e) Factorial con loop/recur

(defn factorial  
  [n]
  (loop [current n acc 1]
    (if (<=current 1)
      acc      
      (recur (dec current) (* acc current)))))

Uso:

(factorial 5)
;; => 120

Este ejemplo es útil para entender cómo Clojure maneja la recursión sin caer en problemas de stack overflow cuando se usa loop/recur.

f) Promedio de una colección

(defn average  
  [numbers]
  (if (empty? numbers)
    0    
    (/ (reduce + 0 numbers)
       (count numbers))))

Uso:

(average [10 20 30])
;; => 20

5) Trabajar con maps y datos estructurados

Clojure es muy cómodo para trabajar con mapas, y esto se vuelve muy útil cuando construimos datos de negocio o modelos simples.

Crear un usuario normalizado

(defn build-user  
  [{:keys [id name email]}]
  {:id id
   :name name
   :email email
   :active true})

Uso:

(build-user {:id 1 :name "Ana" :email "ana@example.com"})
;; => {:id 1, :name "Ana", :email "ana@example.com", :active true}

Resumen de producto

(defn product-summary  
  [{:keys [name price stock]}]
  {:name name
   :price price
   :stock stock
   :in-stock? (pos? stock)})

Uso:

(product-summary {:name "Laptop" :price 999 :stock 12})
;; => {:name "Laptop", :price 999, :stock 12, :in-stock? true}

6) Por qué Clojure valora este enfoque

Los ejemplos anteriores muestran algunas ideas clave de Clojure:

• Las funciones son primero-class citizens.

• Los datos son expresivos y fáciles de manipular.

• Las colecciones se procesan con funciones como map, filter y reduce.

• La recursión se maneja de forma clara con loop/recur.

• Los maps permiten modelar información de una manera muy directa.

7) Siguiente paso recomendado

Para seguir avanzando, te recomiendo practicar en este orden:

1. Instalar la Clojure CLI.

2. Abrir el REPL y probar cada ejemplo manualmente.

3. Reescribir las funciones sin mirar el código.

4. Agregar nuevas pruebas con clojure.test.

5. Comenzar a crear pequeños ejercicios con maps y colecciones.

8) Cierre

Clojure puede verse desafiante al principio, pero cuando entiendes el flujo de datos y la sintaxis básica, se vuelve muy elegante y poderosa. El primer objetivo no es dominar todo desde el inicio, sino construir confianza con ejemplos pequeños y repetibles.

En el siguiente post podemos continuar con una introducción a:

• let, if, cond y fn

• listas, vectores y mapas

• reduce, map y filter en profundidad

• cómo estructurar un proyecto con namespaces y tests

Y así seguiremos compartiendo contenido útil para la comunidad de Clojure.

Enjoy!

Joe

Basado en la presentación "KCP-COMMANDS & KCP-MEMORY" (SDD Breakout — Herramientas ExoCortex) de Jose Diaz Diaz · Autor: Thor Henning Hetland (Totto) · Ægis, Santiago de los Caballeros 2026, y en The KCP Ecosystem: A Tour for New Arrivals (Thor Henning Hetland, julio 2026).

El artículo anterior de esta serie presentó el knowledge.yaml como el índice de navegación que le dice a la IA dónde está todo al inicio de sesión. Eso resuelve el problema del descubrimiento.

Pero hay dos problemas que el knowledge.yaml solo no resuelve:

1. Context window burn: mvn test genera 500+ líneas. git log --oneline genera 200+ líneas. La IA consume tokens procesando ruido que nunca necesitó ver.

2. Session amnesia: Cada sesión nueva es una pizarra en blanco. El agente no sabe que la semana pasada arreglaste el N+1 query en OrderRepository. No sabe que el refactor de autenticación dejó tres TODOs pendientes. No sabe que decidiste usar @Tag("integration") para separar tests que necesitan Docker.

kcp-commands resuelve el primero. kcp-memory resuelve el segundo. Están diseñados para usarse juntos.

El mapa del problema

kcp-commands y kcp-memory trabajan en cadena: el hook escribe el log de eventos, el daemon indexa ese log y lo convierte en memoria recuperable.

kcp-commands es un PreToolUse + PostToolUse hook de Claude Code. Se dispara en cada llamada Bash del agente, en tres fases consecutivas.

Fase A: antes de ejecutar — inyección de guía

Para comandos reconocidos, el hook inyecta un hint compacto con los flags que el agente probablemente necesita. En lugar de que Claude Code adivine los parámetros de mvn o kubectl, recibe una guía concisa antes de ejecutar.

Para Java developers, esto cubre:

• mvn / ./mvnw — surefire flags, perfiles, skip tests

• git — status, diff, log, branch, cherry-pick

• docker / docker-compose — ps, logs, build, push

• kubectl — get pods, describe, logs, apply

Fase B: después de ejecutar — filtrado de output

Esta es la fase de mayor impacto en context window. El manifiesto de cada comando define qué líneas conservar y qué desechar:

El manifest para mvn test se ve así (formato interno del hook):

# ~/.kcp/manifests/mvn-test.yaml
command: "mvn.*test|./mvnw.*test"
phase_a:
  inject: |
    Flags útiles: -pl <módulo> para módulo específico,
    -Dtest=NombreTest para test único,
    -DskipTests para compilar sin ejecutar.
phase_b:
  filter: keep_matching
  patterns:
    - "BUILD (SUCCESS|FAILURE)"
    - "Tests run:"
    - "FAILED:"
    - "ERROR:"
    - "\\[ERROR\\]"
  inject_on_failure: |
    Si hay fallos con @Tag("integration"), pueden necesitar
    la infraestructura de Docker levantada con docker-compose.
phase_c:
  log: true

Fase C: event logging

Cada llamada Bash queda registrada en ~/.kcp/events.jsonl. Este log es el insumo que consume kcp-memory. Sin kcp-commands, kcp-memory no tiene datos que indexar.

{"ts":"2026-07-31T09:14:22Z","cmd":"mvn test","project":"pedidos-api","exit":1,"summary":"FAILED: OrderServiceTest (1 failure)","filtered_lines":8,"original_lines":847}
{"ts":"2026-07-31T09:18:44Z","cmd":"git diff HEAD~1","project":"pedidos-api","exit":0,"summary":"Modified: OrderService.java, OrderRepository.java","filtered_lines":12,"original_lines":234}
{"ts":"2026-07-31T09:25:01Z","cmd":"mvn test","project":"pedidos-api","exit":0,"summary":"Tests run: 47, Failures: 0","filtered_lines":3,"original_lines":812}

Impacto medido

El hook funciona out of the box. No requiere ningún knowledge.yaml. No requiere configurar manifests. Instálalo y empieza a ahorrar tokens en la próxima sesión.

Instalación

# Opción recomendada — daemon Java (12 ms/call):
curl -fsSL https://raw.githubusercontent.com/Cantara/kcp-commands/main/bin/install.sh | bash -s -- --java

# Alternativa — solo Node.js (no requiere JVM):
curl -fsSL https://raw.githubusercontent.com/Cantara/kcp-commands/main/bin/install.sh | bash -s -- --node

El installer registra el hook en el settings.json global de Claude Code. Después del primer claude que ejecutes, el hook está activo.

kcp-memory: memoria episódica cross-session

Repo: github.com/Cantara/kcp-memory · Versión: 0.32.0

Los agentes son amnésicos por diseño. Cada sesión nueva empieza desde cero. kcp-memory cierra ese hueco.

El problema concreto en un proyecto Java

Imagina este escenario real en un proyecto Spring Boot:

• Lunes: Debuggeas un N+1 query. Encuentras que OrderRepository.findByCustomer() hace lazy loading mal configurado. Arreglas con @EntityGraph. 45 minutos de investigación.

• Martes: Nueva sesión. Pides a Claude que optimice queries en el módulo de clientes. El agente vuelve a investigar el mismo patrón de lazy loading. 30 minutos para redescubrir lo que ya sabes.

• Miércoles: Refactorizas autenticación. Dejas 3 TODOs marcados en JWT config. Sesión termina antes de completarlos.

• Jueves: Nueva sesión. No hay contexto de los TODOs. El agente no sabe qué estaba en progreso.

kcp-memory convierte el martes, miércoles y jueves en sesiones que arrancan informadas.

Cómo funciona el daemon

Qué captura kcp-memory

El daemon indexa y prioriza cuatro categorías de información:

La diferencia práctica

Lo que Claude ve al abrir una sesión nueva en tu proyecto Spring Boot:

## Relevant session history — pedidos-api

2026-07-28: Fixed N+1 query in OrderRepository.findByCustomer().
Cause: default lazy loading on @OneToMany. Fix: @EntityGraph annotation.
Added pattern to performance-patterns.md skill.

2026-07-29: JWT refactor session ended mid-task.
3 TODOs pending in src/main/java/.../security/JwtTokenProvider.java (lines 87, 134, 201).
Context: expiry was calculated in seconds not ms — see PR #1847.

2026-07-30: Integration test failures.
Cause: docker-compose postgres port 5432 conflicts with local instance.
Fix: POSTGRES_PORT=5433 in .env.test

En lugar de empezar a explorar desde cero, el agente arranca con el contexto de lo que pasó — los problemas activos, las decisiones tomadas, los archivos en progreso.

Memoria compartida entre sub-agentes

kcp-memory indexa también los transcripts de sub-agentes. Esto significa que si usas Task tool o sub-agentes paralelos en Claude Code, la memoria es compartida entre todos ellos dentro del mismo proyecto. Un sub-agente que arregla tests y otro que refactoriza servicios ven el mismo contexto histórico.

Almacenamiento

SQLite local en ~/.kcp/memory.db. Sin cloud. Sin envío de datos. El contexto inyectado al inicio de sesión es generado localmente por el daemon.

Instalación

# Instalar kcp-memory (requiere kcp-commands instalado primero):
# Ver instrucciones actualizadas en:
# https://github.com/Cantara/kcp-memory#install

Cómo funcionan juntos: la cadena completa

kcp-commands + kcp-memory forman un sistema de dos capas:

La clave es que son independientes pero complementarios:

• kcp-commands solo: ahorra context window en la sesión actual. Sin memoria cross-session.

• kcp-memory solo: sin eventos que indexar (no hay events.jsonl), opera solo con transcripts de sesión — útil pero limitado.

• Ambos juntos: ahorro de tokens + contexto histórico enriquecido = el loop completo.

Plan de adopción para un proyecto Java existente

No es necesario instalar todo a la vez. El ecosistema está diseñado para adopción incremental:

Día 1 — Ahorro de context window inmediato

# Instalar kcp-commands (Java daemon):
curl -fsSL https://raw.githubusercontent.com/Cantara/kcp-commands/main/bin/install.sh | bash -s -- --java

# Abrir Claude Code. Ejecutar cualquier comando Maven o Git.
# Observar: la Fase A inyecta hints antes del comando.
# Observar: la Fase B devuelve output filtrado.
# El ahorro empieza desde la primera sesión.

Día 2 — Agregar memoria episódica

# Instalar kcp-memory:
# https://github.com/Cantara/kcp-memory#install

# El daemon empieza a indexar events.jsonl y transcripts.
# La próxima sesión recibirá contexto de la sesión de hoy.

Día 3 — Agregar inteligencia de workspace (opcional)

# Configurar Synthesis MCP en .claude/mcp.json
# Luego: synthesis scan . (desde la raíz del proyecto)
# Claude Code puede buscar, relacionar y preguntar sobre todo el codebase.

Cuando necesites governance:

Agrega kcp-agent para load planning inspeccionable, y kcp-harness para enforcement. Estos son para cuando los agentes corren en producción o en entornos donde "el agente leyó el archivo X porque..." necesita ser auditable.

Manifest personalizado para tu proyecto Java

Si tu proyecto tiene patrones específicos — un wrapper de Maven, un runner de tests con flags especiales, un CLI interno — puedes agregar manifests propios en ~/.kcp/manifests/:

# ~/.kcp/manifests/my-project-test.yaml
command: "./scripts/run-tests.sh"
phase_a:
  inject: |
    Flags disponibles: --module <nombre>, --tag integration, --tag unit.
    Los tests de integración requieren: docker-compose up -d postgres redis
phase_b:
  filter: keep_matching
  patterns:
    - "PASSED|FAILED|ERROR"
    - "Tests run:"
    - "\\[WARN\\].*important"
  inject_on_failure: |
    Revisar logs en target/surefire-reports/ para stack traces completos.
phase_c:
  log: true

Los 292 manifests incluidos cubren las herramientas más comunes. Los manifests propios se fusionan sin sobreescribir los del sistema.

Qué resuelven estas herramientas y qué no

kcp-commands y kcp-memory son la entrada más directa al ecosistema KCP: impacto inmediato, configuración cero, instalación en dos comandos.

Recursos

• kcp-commands — GitHub

• kcp-memory — GitHub

• The KCP Ecosystem: A Tour for New Arrivals — Thor Henning Hetland

• Knowledge Context Protocol spec

• Artículo anterior: KCP — el protocolo de navegación

Enjoy!

Joe

Basado en la presentación de Thor Henning Hetland (Totto) · Ægis, The KCP Universe: Everything, and What July Changed (v0.30.3, 29 julio 2026).

El Pilar 1 de esta serie explica cómo construir el CLAUDE.md con el ADN del proyecto: convenciones, anti-patrones, flujo de Git, requisitos de testing. Es el conocimiento del codebase.

Pero hay un problema que el CLAUDE.md no resuelve: la IA tiene que encontrarlo.

En cada sesión nueva con Claude Code, el agente empieza desde cero. No recuerda dónde está el CLAUDE.md. No sabe que el proyecto tiene arquitectura hexagonal con cuatro capas de paquetes. No sabe que los skills están en .claude/skills/. Tiene que descubrirlo leyendo archivos, escaneando directorios y abriendo configuraciones.

En un proyecto Java típico, eso cuesta entre 20 y 33 tool calls antes de que el agente pueda empezar la primera tarea.

El Knowledge Context Protocol (KCP) resuelve exactamente eso.

El problema: relevancia no es autoridad

Antes de ver la solución, vale la pena entender por qué el problema es más profundo de lo que parece.

Un agente leyendo tu codebase no tiene forma de saber qué es verdad. Encuentra un documento de arquitectura de marzo y uno de junio. Nada en ninguno de los dos dice cuál es el actual. Sigue el runbook que fue supersedido en abril. Lee la guía de API interna escrita para una versión que ya no existe. Los lee todos con exactamente la misma confianza, porque un archivo es un archivo.

El Retrieval Augmented Generation (RAG) no resuelve esto. RAG encuentra texto relevante. No tiene concepto de texto autoritativo. Relevancia y autoridad son preguntas distintas, y solo una de ellas tiene una respuesta que se puede verificar.

KCP es la otra respuesta.

Qué es KCP: dos mecanismos, un archivo

Un knowledge.yaml en la raíz del repositorio. La IA lo lee primero, al inicio de cada sesión, y se orienta en 3 tool calls en lugar de 33.

El knowledge.yaml hace dos trabajos distintos:

Mecanismo 1 — Índice de navegación del proyecto: Declara arquitectura, ubicaciones de skills, convenciones, puntos de entrada y paths clave. La IA lo lee una vez al inicio de sesión y conoce la estructura del proyecto sin explorar.

CLAUDE.md es conocimiento. knowledge.yaml es navegación.

Mecanismo 2 — Command manifests: Interceptan el output de CLI antes de que la IA lo procese. git status en un repo grande genera 200+ líneas; el manifest lo filtra a las 12 relevantes. mvn test genera 500+ líneas de INFO y descargas; el manifest devuelve solo los fallos.

Resultado medido: 33% del context window ahorrado por sesión en operaciones rutinarias de desarrollo. 60–80% en operaciones con output especialmente verboso.

Cómo se ve en un proyecto Java Spring Boot

# knowledge.yaml — raíz del repositorio
project:
  name: pedidos-api
  type: java-spring-boot
  architecture: CLAUDE.md#architecture

skills:
  global: ~/.claude/skills/common/
  project: .claude/skills/
  navigator: .claude/skills/navigator.yaml

entry_points:
  - src/main/java/com/empresa/pedidos/PedidosApplication.java
  - src/main/java/com/empresa/pedidos/api/

conventions:
  - CLAUDE.md#conventions
  - docs/ADRs/

commands:
  maven_test:
    filter: failures_only
    ignore: ["^\\[INFO\\]", "^\\[WARNING\\]", "Downloading:", "Downloaded:"]
    inject: "Verifica si los fallos tienen @Tag de integración — pueden requerir Docker"

  git_status:
    filter: staged_only
    ignore: ["target/", ".mvn/", "*.class", "*.jar"]
    inject: "Verifica que no se modificaron archivos de corpus de tests"

  maven_compile:
    filter: errors_only
    ignore: ["^\\[INFO\\]", "^\\[WARNING\\]"]
    inject: "Si hay errores de javax.*, revisar migración jakarta — ver CLAUDE.md#antipatrones"

El impacto concreto del filtrado de mvn test:

Los tres artefactos que KCP gobierna

Con la versión v0.29 (julio 2026), el protocolo introdujo tres clases de artefactos que cambian la naturaleza de lo que puede gobernar:

La distinción que más importa para Java devs:

• Una unidad de conocimiento (kind: knowledge) es un hecho: el ADR que explica por qué el equipo usa hexagonal, el documento que dice que monto siempre es BigDecimal. Puede tener valid_until y expira solo cuando caduca.

• Un skill (kind: skill) es un procedimiento sobre una cosa: cómo migrar un controlador Spring Boot 2 a 3, cómo generar un DTO con record. Tiene action_scope declarado — qué herramientas puede usar — y el agente no puede salirse de ese scope sin que el harness lo bloquee.

• Un playbook (kind: playbook, nuevo en v0.29) es un objetivo compuesto: "actualizar Spring Boot de 2.x a 3.x en este módulo". Contiene una secuencia de skills con checkpoints. Al terminar, emite una cadena de decisiones firmada — no un log, sino evidencia criptográfica de que cada paso se ejecutó dentro de lo que estaba autorizado a hacer.

La unidad de confianza: qué dice un entry de knowledge.yaml

# Ejemplo de unidad de skill declarada en knowledge.yaml
- id: jakarta-migration-skill
  path: .claude/skills/jakarta-migration.md
  kind: skill
  intent: "Migración de javax.* a jakarta.* en controladores Spring Boot 3.
           Incluye anotaciones OpenAPI 3 y tests MockMvc actualizados."
  scope: project
  audience: [agent]
  triggers: [jakarta, javax, spring-boot-3, migration]
  load_eligible: true
  action_scope:
    tools: ["read_file", "replace_string_in_file"]
  valid_until: "2027-01-01"

Cada campo responde una pregunta que el agente de otra forma tendría que adivinar:

• intent — ¿para qué sirve esto? No un resumen del texto; una declaración de propósito.

• audience: [agent] — ¿es para mí? Un doc de onboarding humano y un runbook de agente son artefactos distintos.

• kind: skill — ¿es conocimiento o un procedimiento? Esta línea hace que la unidad sea gobernable como acción.

• load_eligible: true — ¿se puede cargar? La elegibilidad es separada de la relevancia.

• action_scope — ¿qué puede tocar? Una tool call fuera de read_file y replace_string_in_file es rechazada en el loop, con la razón escrita.

Lo que cambió en julio 2026 (v0.28–v0.30.3)

El protocolo pasó de v0.22 a v0.30.3 en julio con 1.012 commits y 88 releases. Cuatro cambios que importan para quienes lo usan:

1. Paridad de implementaciones (v0.28) KCP tiene bridges para TypeScript, Java y Python. Hasta julio, "la spec dice X" y "las implementaciones hacen X" eran claims separados. v0.28 los unificó con vectores de conformance compartidos. Una diferencia entre el parser Java y el Python ahora es un test failure, no un descubrimiento en producción seis semanas después.

2. El plano procedimental — kind: playbook (v0.29) Antes KCP gobernaba hechos. Ahora también puede gobernar objetivos compuestos. Un playbook emite una cadena de decisiones firmada — evidencia que puede presentarse en una auditoría de cumplimiento.

3. Eligibility grants (v0.30) Un sistema de gobernanza que solo puede decir no es un freno. Los grants permiten que unidades sean elegibles bajo condiciones específicas, con el historial de qué se solicitó y qué se rechazó. La solicitud misma es parte del audit trail.

4. Parse diagnostics Antes de julio, un campo mal escrito (audiance: en lugar de audience:) se ignoraba silenciosamente. La unidad parseaba limpia y quedaba sin gobierno para siempre. Ahora lo dice.

"El campo mal escrito es el mejor ejemplo del problema central: la diferencia entre algo que está bien y algo que no fue verificado es invisible a menos que construyas la maquinaria para verlo."

Por qué importa para proyectos Java en particular

Los proyectos Java son exactamente el tipo de codebase donde el problema de orientación es más costoso:

• Multi-módulo Maven: ls en el root no dice nada. La estructura real está cuatro niveles abajo.

• Spring Boot conventions: La convención de paquetes, la separación de capas, los beans esperados — nada de esto es visible sin explorar.

• Output verboso de Maven: 500 líneas de INFO por cada mvn test. Sin filtrado, la IA gasta contexto en ruido que tú ya ignoras automáticamente.

• Migraciones largas: Una migración Spring Boot 2 → 3 abarca docenas de archivos con el mismo patrón. El playbook KCP puede gobernar cada paso con evidencia firmada.

Cómo empezar: tres pasos

Paso 1 — Instala kcp-commands (10 minutos, resultado inmediato)

Es el único punto de entrada con payoff inmediato sin conocer el protocolo. Envuelve comandos frecuentes (git, mvn) con filtrado token-eficiente. Corre como hook en ~12ms. No necesitas saber qué es KCP para beneficiarte.

Paso 2 — Escribe un knowledge.yaml básico para tu proyecto Java

Seis unidades. Para cada una: intent, audience, y donde aplique valid_until. Luego:

kcp-agent plan "migrar PedidoController a Spring Boot 3" \
  --manifest knowledge.yaml \
  --trace --json

Leer los 14 gate verdicts explicados por escrito es el momento en que el concepto aterriza.

La conexión con los 6 pilares

KCP no reemplaza al CLAUDE.md del Pilar 1. Lo complementa:

El Pilar 6 (volante de aprendizaje) actualiza el CLAUDE.md con cada bug. KCP hace que esas actualizaciones sean encontrables y autoritativas, no solo relevantes.

La estructura del flujo de trabajo no es una barrera para el código. Son los rieles que permiten al equipo ir a 300 km/h sin descarrilar.

Los rieles funcionan mejor cuando la IA sabe dónde están desde el primer tool call.

¿Cuántos tool calls hace Claude en tu proyecto Java antes de empezar la primera tarea? Puedes medirlo abriendo una sesión nueva y contando. Ese número es tu baseline de cold-start. ¿Cuánto mejoraría con un knowledge.yaml?

Enjoy!

Joe

Parte de la serie "Los 6 pilares del desarrollo asistido por IA" — basado en el material de Thor Henning Hetland (Totto) / Ægis. Adaptado a proyectos Java.

Los cinco pilares anteriores construyen la base: contexto inteligente (Pilar 1), delegación estratégica (Pilar 2), verificación sistemática (Pilar 3), agencia técnica (Pilar 4) y guardrails de proceso (Pilar 5). El Pilar 6 responde la pregunta que todos estos dejan abierta:

¿Cómo hace el sistema para volverse más inteligente con el tiempo, no solo más rápido?

La respuesta no es confiar en que el modelo aprenda solo. Los modelos no aprenden de tus sesiones. Lo que aprendiste tú al arreglar ese bug el martes desaparece en el siguiente chat si no lo documentas. El Pilar 6 es el mecanismo para convertir cada bug resuelto, cada patrón descubierto y cada edge case encontrado en inteligencia permanente del sistema.

El problema del contexto estático

Hay dos tipos de equipos que usan IA:

La diferencia no está en el modelo. Está en si el equipo actualiza el contexto o no.

Con el enfoque estático, el CLAUDE.md del Pilar 1 se queda exactamente igual que el día que se escribió. La IA no aprende que BigDecimal se compara con .compareTo(), no aprende que el endpoint /pagos tiene validaciones especiales antes del publish a Kafka, no aprende que Optional.empty() en PedidoService.findById() puede significar "cancelado" además de "no existe".

Con el enfoque continuo, cada bug que se arregla se convierte en un anti-patrón documentado. Cada patrón que funciona bien se convierte en una skill. Cada edge case descubierto se convierte en un requisito de test. La IA del mes 3 es cualitativamente diferente a la del día 1.

El volante: cómo funciona el mecanismo

El volante gira con tres artefactos:

1. LEARNINGS.md — captura diaria de bajo rozamiento (5 min)

2. IMPLEMENTATION-HISTORY.md — registro de features implementadas

3. Skills como módulos vivos — no documentos estáticos, sino módulos con ciclo de vida

El artefacto central: LEARNINGS.md

Una entrada de LEARNINGS.md en un proyecto Java real tarda 5 minutos en escribir. Esos 5 minutos previenen que el mismo bug ocurra en los próximos 8 endpoints.

Formato estándar (bajo rozamiento):

## LEARNINGS.md

### 2026-07-29 — BigDecimal comparación incorrecta
**Contexto:** Revisión del PR de PedidoService.calcularTotal()
**Bug:** La IA generó `if (monto == BigDecimal.ZERO)` para validar monto vacío.
  Pasó todos los unit tests porque los tests usaban el mismo literal.
  Falló en producción con valores calculados (0.00 != 0 por referencia).

**Insight capturado:**
- Comparar BigDecimal con `==` es siempre incorrecto.
- Usar siempre `monto.compareTo(BigDecimal.ZERO) == 0` o `BigDecimal.ZERO.equals(monto)`.

**Acciones:**
- [x] Añadido a CLAUDE.md sección Anti-patrones (#8)
- [x] Actualizado skill domain-model.md con sección "Comparaciones monetarias"
- [x] Añadido test de propiedad con jqwik: comparación con valores calculados

**Resultado:** Cero bugs de comparación BigDecimal en los siguientes 6 servicios.

### 2026-07-31 — LocalDate.now() en dominio no es testeable
**Contexto:** Debugging de PedidoService.estaVencido() — tests no deterministas
**Bug:** La IA usó `LocalDate.now()` directamente en el método de dominio.
  Los tests fallaban aleatoriamente dependiendo de la fecha de ejecución.

**Insight:**
- Nunca usar `LocalDate.now()` o `Instant.now()` directamente en clases de dominio.
- Inyectar `Clock` como dependencia y usar `LocalDate.now(clock)`.
- Permite fijar el tiempo en tests: `Clock.fixed(Instant.parse("2026-01-15T00:00:00Z"), ZoneOffset.UTC)`

**Acciones:**
- [x] Añadido a CLAUDE.md Anti-patrones (#9)
- [x] Creado skill testing.md — sección "Time-dependent testing con Clock"
- [ ] Refactorizar PedidoService para inyectar Clock (backlog JIRA-789)

Los cuatro tipos de insight que vale la pena capturar

El ejemplo del micro-retorno

Un bug en un parser de Spring Boot que asumió que un campo de versión era de longitud fija. La IA generó código basado en la especificación v6 sin saber que v7+ cambió el tamaño del campo.

El problema (5 minutos de análisis):

// Lo que generó Claude — asumió versión fija
int version = buffer.readByte();  // correcto hasta v6
// v7+ usa 2 bytes — parseó el byte de datos como parte de la versión

La solución permanente (10 minutos de documentación):

### 2026-07-15 — Campos de versión de longitud variable
**Anti-patrón:** Nunca asumir tamaño fijo de campos sin verificar la versión del protocolo.
**Regla:** Leer siempre la versión primero. Campos de longitud variable según versión
  requieren dispatch explícito: v1-6 = 1 byte, v7+ = 2 bytes (little-endian).
**Acciones:**
- [x] CLAUDE.md Anti-patrones: "Verificar versión de protocolo antes de parsear campos"
- [x] Skill creada: .claude/skills/parsing-versioning.md

Resultado: Cero bugs de parsing de versión en los siguientes 5 parsers generados.

El ciclo de disparadores: no confíes en tu memoria

El error más común es decir "lo documento después". Después nunca llega. La solución es reemplazar la intención por disparadores situacionales inmediatos:

El mecanismo más efectivo es integrar los disparadores directamente en el PR template. El volante gira automáticamente con cada merge:

<!-- .github/pull_request_template.md — sección de aprendizaje -->

## Documentación del aprendizaje

- [ ] `IMPLEMENTATION-HISTORY.md` actualizado (si fue una feature significativa)
- [ ] `LEARNINGS.md` tiene una entrada (si hubo nuevos insights o bugs encontrados)
- [ ] Skills relevantes actualizados en `.claude/skills/`
- [ ] `CLAUDE.md` actualizado si hay nuevos patrones o anti-patrones

Cuando esta sección está en el template, el equipo la ve en cada PR. No hace falta recordar. El proceso captura el aprendizaje automáticamente.

Los skills como módulos vivos

Los skills del Pilar 1 no son documentos que se escriben una vez. Tienen un ciclo de vida:

Ejemplos de evolución en un proyecto Java:

• spring-boot.md se divide en spring-boot-controllers.md y spring-boot-config.md cuando supera las 400 líneas

• javax-patterns.md se archiva después de completar la migración a Jakarta EE

• jpa-patterns.md y hibernate-config.md se fusionan en persistence.md cuando el equipo unifica criterios

El retorno exponencial: los números reales

El volante produce retorno compuesto, no lineal:

El multiplicador de 8× no viene de un modelo más caro. Viene de un contexto más rico que permite a Haiku 4.5 hacer lo que antes requería Sonnet 5, y a Sonnet 5 hacer lo que antes requería intervención humana.

Las métricas del volante

Cuatro KPIs que miden si el sistema está aprendiendo o estancado:

La rutina de mantenimiento

El volante no requiere grandes inversiones de tiempo. Requiere consistencia:

Empieza hoy: tres acciones en 30 minutos

1. Crea LEARNINGS.md en la raíz del proyecto (5 min):

# LEARNINGS.md — Registro de aprendizaje del equipo

## Formato de entrada
- **Fecha:** YYYY-MM-DD
- **Contexto:** ¿En qué estabas trabajando?
- **Insight:** ¿Qué aprendiste?
- **Acciones:** ¿Qué actualizaste? (CLAUDE.md / skill / test)
- **Resultado:** ¿Qué evitó este aprendizaje?

---
<!-- Primera entrada: usa el bug más reciente que arreglaste -->

2. Añade la sección de aprendizaje al PR template (10 min): Copia el bloque de la sección anterior a .github/pull_request_template.md. A partir de ese momento, cada PR activa el ciclo.

3.Añade la primera entrada basada en el último bug de Java (15 min): No esperes al próximo bug. El último que arreglaste esta semana — el NullPointerException en el servicio de pagos, la excepción de Hibernate inesperada, el test que fallaba aleatoriamente — ya tiene un insight que vale la pena capturar.

El cierre de la serie

Seis pilares. Una arquitectura de trabajo que se autorefuerza:

El Pilar 6 cierra el ciclo: los aprendizajes capturados enriquecen el CLAUDE.md y los skills del Pilar 1, que mejoran la delegación del Pilar 2, que hacen más efectiva la verificación del Pilar 3, que fortalecen la agencia del Pilar 4, que se integran en los guardrails del Pilar 5, que generan más aprendizajes para capturar.

Cada bug resuelto hace al sistema más inteligente. Cada patrón documentado hace al equipo más rápido. Cada insight capturado compone.

Haz que tu IA sea permanentemente más inteligente con cada bug resuelto y patrón descubierto. Tus prompts de sistema son un motor de aprendizaje activo, no archivos estáticos.

¿Tienes algún LEARNINGS.md en tu proyecto Java? ¿O esos insights viven solo en tu memoria hasta que se olvidan? El próximo bug que arregles es el mejor momento para empezar.

Enjoy!

Joe

Parte de la serie "Los 6 pilares del desarrollo asistido por IA" — presentado en JConf Dominicana. Adaptado a proyectos Java.

Hay una creencia que destruye más sprints que cualquier bug técnico:

"Saltarse los pasos acelera la entrega."

Es comprensible. Commit directo a main se siente rápido en el minuto cero. Sin PR, sin esperar el CI, sin revisión. Sensación de progreso. El código está "listo".

El problema no es el commit. Es lo que ocurre después.

La ilusión de la velocidad desestructurada

En Java, el escenario más común tiene este patrón:

Un desarrollador actualiza una dependencia de Spring Boot directamente en main. "Solo es una actualización de versión". El cambio pasa. Ninguna prueba falla localmente. Pero la nueva versión tiene un comportamiento diferente en el autoconfigurador de Kafka. El próximo desarrollador que hace pull tiene el contexto de Spring roto. El build de CI falla. El equipo pierde dos horas investigando algo que una prueba de integración en el PR habría detectado en cuatro minutos.

El proceso no es burocracia si previene problemas mayores.

El ciclo de caos que nadie planea

Sin guardrails, el equipo cae en este ciclo de forma casi inevitable:

La falla crítica no es técnica. Es de proceso. Cada vez que un bug llega a producción sin ser interceptado, el equipo paga el precio en context-switching: interrupciones que destruyen el flujo cognitivo, días completos de debugging reactivo, y bugs que se acumulan porque nadie tiene tiempo de resolver los anteriores antes de que lleguen los siguientes.

En equipos Java con microservicios, el costo es multiplicado: un cambio roto en el servicio de autenticación puede bloquear a tres squads diferentes que dependen de ese contrato.

El Pilar 5: disciplina de procesos y límites estratégicos

La diferencia entre caos y disciplina no está en cuánto código produces. Está en cuánto de ese código llega a producción sin romper nada.

El ecosistema del código limpio en Java

Tres capas que trabajan juntas. La disciplina no es un documento estático: son reglas integradas directamente en la infraestructura del proyecto.

Capa 1 — Reglas de branching

Los límites de la pista. Sin ellos, cualquier desarrollador puede enviar código sin verificar directamente a la rama principal.

GitHub Actions — protección de main:

# .github/branch-protection.yml (configuración via GitHub API o UI)
# Reglas mínimas para main:
# - Requerir PR antes de merge
# - Requerir CI verde (build + tests)
# - Requerir 1 reviewer aprobador
# - No permitir force push
# - No permitir borrar la rama

Naming convention en el CLAUDE.md:

## Flujo de Git

Naming de ramas:
- feat/JIRA-123-descripcion-breve    (nueva funcionalidad)
- fix/JIRA-456-nombre-del-bug        (corrección)
- chore/actualizacion-dependencias   (mantenimiento)
- release/2.4.0                      (preparación de release)

NUNCA hacer commit directo a main o develop.
Todo cambio, por pequeño que sea, pasa por PR.

Capa 2 — Automatización CI/CD

Los motores de validación. El CI es el primer revisor: rápido, imparcial, sin fatiga.

GitHub Actions para un proyecto Spring Boot con Maven:

# .github/workflows/ci.yml
name: CI — Build & Quality Gates

on:
  pull_request:
    branches: [ main, develop ]

jobs:
  build-and-verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Java 21
        uses: actions/setup-java@v4
        with:
          java-version: '21'
          distribution: 'temurin'

      - name: Cache Maven
        uses: actions/cache@v4
        with:
          path: ~/.m2
          key: ${{ runner.os }}-maven-${{ hashFiles('**/pom.xml') }}

      # Gate 1: Compilación
      - name: Compilar
        run: mvn clean compile -q

      # Gate 2: Checkstyle (convenciones de código)
      - name: Checkstyle
        run: mvn checkstyle:check

      # Gate 3: Tests unitarios
      - name: Tests unitarios
        run: mvn test -Dgroups="unit"

      # Gate 4: Tests de integración (con Testcontainers)
      - name: Tests de integración
        run: mvn verify -Dgroups="integration"

      # Gate 5: Cobertura mínima 80%
      - name: JaCoCo coverage gate
        run: mvn jacoco:check

      # Gate 6: Vulnerabilidades en dependencias
      - name: OWASP Dependency Check
        run: mvn org.owasp:dependency-check-maven:check
        continue-on-error: false

Configuración JaCoCo en pom.xml:

<plugin>
    <groupId>org.jacoco</groupId>
    <artifactId>jacoco-maven-plugin</artifactId>
    <version>0.8.12</version>
    <executions>
        <execution>
            <id>jacoco-check</id>
            <goals><goal>check</goal></goals>
            <configuration>
                <rules>
                    <rule>
                        <element>BUNDLE</element>
                        <limits>
                            <limit>
                                <counter>LINE</counter>
                                <value>COVEREDRATIO</value>
                                <minimum>0.80</minimum>
                            </limit>
                        </limits>
                    </rule>
                </rules>
            </configuration>
        </execution>
    </executions>
</plugin>

Si el CI falla, el PR no puede mergearse. El guardrail es automático, sin depender de que alguien recuerde correr las pruebas.

Capa 3 — Revisión humana (PRs)

El control de calidad final y el canal de transferencia de conocimiento. La revisión humana hace lo que la automatización no puede: evaluar decisiones de arquitectura, detectar deuda técnica implícita y mentorizar a través del código.

PR template para proyectos Java:

<!-- .github/pull_request_template.md -->
## ¿Qué hace este PR?
<!-- Descripción breve del cambio -->

## Tipo de cambio
- [ ] feat: nueva funcionalidad
- [ ] fix: corrección de bug
- [ ] refactor: mejora sin cambio de comportamiento
- [ ] chore: actualización de dependencias / config

## Checklist de calidad

### Código generado con IA
- [ ] ¿Round-trip test para DTOs nuevos o modificados?
- [ ] ¿Código usa `jakarta.*` (no `javax.*`)?
- [ ] ¿DTOs son Java records (no clases con setters)?
- [ ] ¿Usa `BigDecimal` para montos (no Double/Float)?
- [ ] ¿Haiku verificó la implementación contra el spec OpenAPI?

### Calidad general
- [ ] CI verde (build + tests + checkstyle + cobertura)
- [ ] Sin TODOs activos no documentados
- [ ] Documentación actualizada si cambió comportamiento público
- [ ] Errores nuevos registrados en CLAUDE.md (si aplica)

El filtro matemático del PR

La micro-fricción intencional del PR (5–15 minutos) es un escudo matemático para el equipo:

La aritmética es directa:

• Sin PR: 0 minutos ahora + 2–8 horas de war room después

• Con PR: 5–15 minutos ahora + 0 horas de war room

Un solo incidente evitado por semana paga con creces toda la fricción del proceso del sprint.

Implementar los guardrails en tu proyecto Java

Esta semana — los tres guardrails esenciales

1. Proteger main en GitHub/GitLab (15 minutos):

Requerir PR para cualquier merge Requerir CI verde Requerir al menos 1 aprobación 2. CI mínimo viable (1–2 horas):

# Versión mínima: compila + tests + checkstyle
- run: mvn clean verify checkstyle:check

3. PR template con checklist (30 minutos): Crea .github/pull_request_template.md con el checklist de tu equipo. Una casilla visible es un recordatorio que no cuesta nada ignorar pero que cambia el comportamiento del equipo.

Este mes — automatizar la calidad

• Añadir JaCoCo con gate de cobertura ≥80%

• Añadir SpotBugs para análisis estático de Java

• Añadir OWASP Dependency Check (especialmente relevante en proyectos Spring Boot con muchas dependencias transitivas)

• Integrar SonarQube o SonarCloud si el equipo lo tiene disponible

Este trimestre — hacer que el proceso sea invisible

El objetivo final es que los guardrails sean tan fluidos que el equipo no los sienta como fricción, sino como el flujo normal. Cuando un desarrollador nuevo entra al equipo, el proceso ya está ahí: no hay que explicarlo, no hay que pedirle que lo respete, simplemente no puede no seguirlo.

## CLAUDE.md — regla de proceso (añadir)

Todo PR debe pasar el CI completo antes de solicitar revisión humana.
Si el CI falla: arreglar antes de pedir revisión (no después).

El proceso no se salta aunque el cambio sea "pequeño".
Los bugs más caros en producción vinieron de cambios que parecían pequeños.

La frase que lo resume

La estructuración del flujo de trabajo no es una barrera para el código. Son los rieles que permiten al equipo ir a 300 km/h sin descarrilar.

La velocidad desestructurada es una ilusión costosa. El equipo que hace commit directo a main "porque es más rápido" paga esa deuda con war rooms, context-switching y deuda técnica acumulada. El equipo con guardrails paga 5–15 minutos por PR y compone ese ahorro en productividad semana a semana.

Adopta los límites. Acelera el desarrollo.

La conexión con los otros pilares

El Pilar 1 (CLAUDE.md + skills) define los patrones y anti-patrones del proyecto. El Pilar 5 los hace cumplir: el checkstyle es el CLAUDE.md convertido en automatización; el PR template es el checklist de verificación del Pilar 3 integrado en el proceso.

El Pilar 2 (delegación estratégica) usa Haiku 4.5 para el 60–70% de las tareas. El PR es la barrera que garantiza que la velocidad de Haiku no produce deuda: el código generado pasa por los mismos guardrails que el código humano.

El Pilar 3 (verificación) establece las reglas técnicas (round-trip tests, corpus real). El Pilar 5 hace que esas reglas sean parte del proceso del equipo, no opcionales.

Los seis pilares juntos construyen el único tipo de velocidad que escala: la que no acumula deuda mientras avanza.

¿Tu proyecto Java tiene branch protection en main? ¿El CI bloquea el merge automáticamente si falla? ¿O el proceso depende de que alguien recuerde correr las pruebas?

Enjoy!

Joe

Parte de la serie "Los 6 pilares del desarrollo asistido por IA" — basado en el material de Thor Henning Hetland (Totto) / Ægis. Adaptado a proyectos Java.

Hay dos formas de trabajar con IA. La mayoría de los desarrolladores elige la segunda sin darse cuenta.

El intermediario le pregunta a Claude qué hacer y ejecuta lo que dice. Más rápido al principio. Pero seis meses después no puede tomar una decisión de arquitectura sin consultarle primero. Su experiencia se erosiona.

El director le asigna trabajo específico a la IA, triangula perspectivas, sintetiza con su propio criterio y se hace dueño de la decisión. Más lento al principio. Pero seis meses después es más rápido y más experto que antes.

El Pilar 4 es la arquitectura cognitiva para mantenerte como director, no convertirte en intermediario.

La cronología de seis meses que nadie ve venir

El patrón es siempre el mismo:

• Mes 1: "Claude es increíble. Soy mucho más rápido."

• Mes 3: "Me siento un poco menos seguro en mis decisiones técnicas..."

• Mes 6: "No puedo tomar una decisión de arquitectura sin preguntarle a Claude primero."

La velocidad sube. La confianza técnica cae. Y como la velocidad es visible y la confianza no, nadie lo nota hasta que es tarde.

En términos Java: el desarrollador que solía poder debatir los trade-offs de Spring Security vs. Keycloak, de CQRS vs. arquitectura tradicional, de JPA vs. jOOQ... ahora simplemente pregunta y ejecuta.

El director vs. el intermediario

La diferencia no está en si usas IA. Está en cómo la usas.

Un ejemplo concreto en Java. Tu equipo necesita decidir si implementa CQRS en el dominio de pedidos de un e-commerce.

El intermediario pregunta:

"¿Debo usar CQRS en mi aplicación Spring Boot?"

Claude dice que sí, con una lista de beneficios. El desarrollador implementa CQRS.

El director pregunta:

"Estoy evaluando CQRS para el dominio de pedidos de un e-commerce con Spring Boot 3. El volumen es de 10.000 pedidos/día, el equipo tiene 4 devs, y actualmente tenemos una sola base de datos PostgreSQL. Analiza los trade-offs: complejidad operacional, consistencia eventual, y si el volumen justifica la separación de modelos de lectura y escritura."

Claude da una respuesta matizada. El director la contrasta con otra perspectiva, sintetiza y toma la decisión con criterio propio.

Lectura pasiva vs. síntesis activa

La misma distinción aplica a cómo procesas el output de la IA:

Cuando Claude te da una configuración de Spring Security para OAuth2, hay dos caminos:

Pasivo: copias el código, lo pegas, funciona, sigues.

Activo: lees el código, anotas qué hace cada bean, identificas las decisiones que tomó la IA (¿por qué usó SessionCreationPolicy.STATELESS?, ¿por qué ese orden en los filtros?), y luego lo integras porque entiendes lo que hace.

El segundo camino tarda 15 minutos más. En seis meses, esa diferencia es la que separa al arquitecto del que solo sabe usar Claude.

El modelo de triangulación: por qué una sola IA no basta

La certeza técnica requiere triangulación. No porque una IA sea mala, sino porque así es como los humanos procesan la certeza de forma natural.

Ejemplo Java — elegir entre JPA y jOOQ:

Tienes un dominio de reportes con consultas SQL complejas (múltiples JOINs, agregaciones, paginación custom). ¿Spring Data JPA o jOOQ?

Prompt para Claude (consciente del contexto):

"El equipo tiene dominio de JPA/Hibernate 6. Tenemos un módulo de reportes con 20+ consultas de más de 5 JOINs cada una. Evalúa con detalle los trade-offs de mantener Spring Data JPA con @Query nativas vs. migrar ese módulo a jOOQ, considerando: curva de aprendizaje, tipado en tiempo de compilación, mantenibilidad de las queries, y coste de migración."

Prompt para ChatGPT (crítica desde primeros principios):

"Asume que estoy inclinado hacia Spring Data JPA por inercia del equipo. Dame el mejor argumento posible para que un equipo Spring Boot cambie a jOOQ en un módulo de reportes con consultas complejas. Sé directo sobre los puntos donde JPA realmente falla."

Después identificas dónde coinciden (seguramente: jOOQ tiene mejor control sobre SQL complejo), dónde difieren (quizás en la estimación del coste de migración), y escribes tu síntesis. Esa síntesis es la decisión que puedes defender ante el equipo.

El bucle de 15 minutos

Para decisiones técnicas importantes, este es el protocolo:

15 minutos invertidos en una decisión de arquitectura previenen horas — a veces días — de incertidumbre y rework.

Escenario real (ficticio pero típico): Tu equipo discute si implementar Outbox Pattern para garantizar consistencia entre la base de datos PostgreSQL y Kafka en el módulo de pedidos.

Sin el bucle: alguien pregunta a Claude, Claude dice que sí, se implementa, tres semanas después aparecen edge cases que Claude no mencionó porque nadie preguntó de forma específica.

Con el bucle: formulas la pregunta con contexto real (volumen, equipo, stack), obtienes dos perspectivas, identificas el punto de fricción (complejidad operacional del Debezium vs. solución custom), escribes la síntesis, documentas la decisión en un ADR. Tres semanas después, cuando aparecen los edge cases, el ADR ya los anticipaba.

Las reglas del director para Java devs

La distinción clave en el día a día Java:

Uso correcto del director (decisión de autenticación):

"Estoy diseñando la capa de autenticación para una API Spring Boot 3 con 50.000 usuarios activos. Compara JWT stateless con sesiones gestionadas por Spring Session + Redis: latencia, revocación de tokens, complejidad de implementación y escalabilidad horizontal. El equipo ya conoce Spring Security."

Uso del intermediario (evitar):

"¿Cómo implemento autenticación con Spring Boot?"

El primero produce una respuesta accionable que puedes evaluar. El segundo produce una respuesta genérica que ejecutas sin criterio.

Integrar el rol de director en tu flujo Java

En decisiones de arquitectura (antes de empezar):

• Siempre formula la pregunta con contexto: equipo, volumen, stack, restricciones

• Siempre contrasta con al menos una perspectiva adicional

• Documenta la síntesis como ADR en /docs/decisions/

En code review de código generado por IA:

• Lee el diff entero, no confíes en el resumen de la IA

• Pregúntate: "¿Podría explicarle a un colega por qué este código hace lo que hace?"

• Si no puedes, no mergeas hasta entenderlo

En el CLAUDE.md del proyecto (Pilar 1):

## Decisiones de arquitectura

Toda decisión técnica mayor debe:
1. Formularse con restricciones específicas (equipo, volumen, stack)
2. Contrastarse con al menos una perspectiva adicional
3. Documentarse en docs/decisions/ con el razonamiento propio

La IA propone. El equipo decide.

En el daily o la retrospectiva: Pregunta periódicamente: "¿Hay alguna decisión técnica de las últimas dos semanas que tomamos porque Claude lo dijo, sin haberla triangulado?"

La elección que se hace en cada prompt

Cada vez que abres una conversación con Claude hay una elección implícita:

• Consumo pasivo: Pregunto → Acepto → Ejecuto. Más rápido hoy. Menos capaz en seis meses.

• Dirección activa: Enmarco → Contrasto → Sintetizo → Decido. 15 minutos más hoy. Mejor arquitecto en seis meses.

La IA no te quita la agencia. Tú se la cedes, prompt a prompt, cada vez que aceptas la primera respuesta sin leerla, cada vez que copias sin entender, cada vez que dejas que el modelo elija por ti lo que es tuyo elegir.

El Pilar 4 no es una restricción al uso de IA. Es la forma de asegurarte de que el uso de IA te hace más experto, no más dependiente.

La conexión con los otros pilares

El Pilar 1 (CLAUDE.md + skills) documenta las decisiones pasadas del equipo para que la IA no las ignore. El director actualiza ese contexto después de cada síntesis: las decisiones que tomó y el razonamiento detrás de ellas.

El Pilar 2 (delegación estratégica) asigna el modelo correcto para cada tarea. El director sabe que Opus 5 o Fable 5 son apropiados para triangular decisiones de arquitectura, y Haiku para ejecutar patrones ya decididos.

El Pilar 3 (verificación) asegura que el código generado es correcto. El director no solo verifica el código: verifica que entiende el código que verifica.

Los seis pilares juntos son una arquitectura de trabajo, no un conjunto de herramientas. El director las orquesta.

¿Cuándo fue la última vez que tomaste una decisión de arquitectura Java triangulando dos perspectivas de IA y escribiendo tu propia síntesis? ¿O directamente ejecutaste lo que dijo Claude? Sin juicio — es una pregunta honesta para el equipo.

Enjoy!

Joe

Parte de la serie "Los 6 pilares del desarrollo asistido por IA" — basado en el material de Thor Henning Hetland (Totto) / Ægis. Adaptado a proyectos Java.

El Pilar 1 le da contexto al modelo. El Pilar 2 elige el modelo correcto para cada tarea. El Pilar 3 responde la pregunta que los dos anteriores no pueden responder por sí solos:

¿Y si el código se ve perfecto… pero está mal?

La IA genera rápido. Eso no está en discusión. El problema es que también alucina con confianza: inventa campos, desalinea DTOs, implementa la lógica que "tiene sentido" en lugar de la que dice la especificación. Y lo hace con el mismo estilo limpio y bien formateado que el código correcto.

La verificación sistemática no es desconfianza en la IA. Es el cinturón de seguridad: no lo usas porque desconfíes del conductor, lo usas porque el mundo tiene variables que ningún conductor controla.

El costo de no verificar

Antes de ver las técnicas, la economía del problema:

La regla que vale la pena memorizar:

Si verificar tarda más que reimplementar, lo estás haciendo mal.

5 minutos de verificación sistemática evitan 2 a 8 horas de war room. El ROI es de 10× a 50× en tiempo, y mucho más en reputación y confianza del equipo.

El toolkit de 6 estrategias

No es una herramienta mágica. Son seis técnicas complementarias. Ninguna alucinación sobrevive a una verificación sistemática que combina las correctas para cada contexto.

Estrategia 1 — Round-trip: la invariante más barata

Configuración: 5 minutos · Costo: cercano a cero

La idea es deceptivamente simple: lo que entra debe salir igual. Si parseas un objeto, lo serializas de vuelta y lo vuelves a parsear, el resultado debe ser idéntico al original. Si no lo es, la IA inventó o perdió algo.

En Java, el caso más común es la serialización JSON con Jackson. Cuando Claude genera un nuevo DTO o modifica uno existente, esta prueba lo atrapa en 30 segundos:

// PedidoRoundTripTest.java
@SpringBootTest
class PedidoRoundTripTest {

    @Autowired
    private ObjectMapper objectMapper;

    @Test
    void roundTrip_PedidoDTO_preservaTodosLosCampos() throws Exception {
        PedidoDTO original = PedidoDTO.builder()
            .id(1L)
            .numero("PED-2024-001")
            .monto(new BigDecimal("1250.75"))
            .estado(EstadoPedido.CONFIRMADO)
            .clienteId(42L)
            .build();

        // Claude generó la serialización: ¿inventó un campo? ¿perdió uno?
        String json = objectMapper.writeValueAsString(original);
        PedidoDTO restaurado = objectMapper.readValue(json, PedidoDTO.class);

        assertEquals(original, restaurado,
            "El round-trip JSON debe preservar todos los campos sin excepción");
    }

    @Test
    void roundTrip_PedidoDTO_conCamposOpcionales() throws Exception {
        // Probar con nulls — la IA a veces "adivina" valores por defecto
        PedidoDTO conNulos = PedidoDTO.builder()
            .id(2L)
            .numero("PED-2024-002")
            .monto(new BigDecimal("0.01"))
            .estado(EstadoPedido.PENDIENTE)
            .clienteId(null)  // campo opcional
            .build();

        String json = objectMapper.writeValueAsString(conNulos);
        PedidoDTO restaurado = objectMapper.readValue(json, PedidoDTO.class);

        assertEquals(conNulos, restaurado);
        assertNull(restaurado.getClienteId());
    }
}

Para operaciones bidireccionales (por ejemplo, exportar e importar datos entre sistemas), el round-trip se extiende a dos niveles:

Lo que detecta en proyectos Java reales:

• @JsonProperty con nombre incorrecto (la IA usa el nombre del campo Java, no el del contrato)

• Campos añadidos que no están en la especificación OpenAPI

• BigDecimal convertido a Double silenciosamente (pérdida de precisión en montos)

• LocalDateTime sin @JsonFormat — diferente representación en cada JVM

Estrategia 2 — Propiedades: prueba la regla, no el ejemplo

Configuración: moderada · Costo: $0

Los unit tests clásicos prueban casos específicos. La IA es muy buena generando tests que ella misma pasa. Las pruebas de propiedades son distintas: definen una regla que debe cumplirse para cualquier input posible, no solo para los tres ejemplos que el modelo eligió.

En Java el motor más directo es jqwik, que funciona sobre JUnit 5:

<!-- pom.xml -->
<dependency>
    <groupId>net.jqwik</groupId>
    <artifactId>jqwik</artifactId>
    <version>1.9.2</version>
    <scope>test</scope>
</dependency>

// PedidoPropiedadesTest.java
import net.jqwik.api.*;
import net.jqwik.api.constraints.*;

class PedidoPropiedadesTest {

    // Propiedad 1: el monto nunca puede ser negativo
    @Property
    void monto_siempreNoNegativo(
            @ForAll @BigRange(min = "0", max = "999999.99") BigDecimal monto) {

        PedidoDTO pedido = new PedidoDTO(1L, "TEST-001", monto, EstadoPedido.PENDIENTE, null);

        assertTrue(pedido.getMonto().compareTo(BigDecimal.ZERO) >= 0,
            "Un pedido no puede tener monto negativo: " + monto);
    }

    // Propiedad 2: round-trip para cualquier monto válido
    @Property
    void roundTrip_cualquierMontoValido(
            @ForAll @BigRange(min = "0.01", max = "999999.99") BigDecimal monto)
            throws Exception {

        PedidoDTO original = new PedidoDTO(1L, "PROP-TEST", monto, EstadoPedido.CONFIRMADO, 10L);
        ObjectMapper mapper = new ObjectMapper();

        String json = mapper.writeValueAsString(original);
        PedidoDTO restaurado = mapper.readValue(json, PedidoDTO.class);

        assertEquals(0, original.getMonto().compareTo(restaurado.getMonto()),
            "El monto no debe perder precisión en la serialización");
    }

    // Propiedad 3: no puede haber referencia a clienteId inexistente
    @Property
    void lineaPedido_clienteIdDebeTenerValorPositivoSiPresente(
            @ForAll @Positive Long clienteId) {

        PedidoDTO pedido = new PedidoDTO(1L, "PROP-002", BigDecimal.TEN,
                                         EstadoPedido.PENDIENTE, clienteId);
        assertTrue(pedido.getClienteId() > 0,
            "clienteId debe ser positivo si está presente");
    }
}

La diferencia con los unit tests convencionales:

"La IA es buena inventando tests que ella misma pasa. Las propiedades no le preguntan un caso: le preguntan siempre."

Un alumno que memoriza 3 ejercicios del libro saca 100 en el examen de esos 3 ejercicios. En el examen real con miles de variaciones, se cae. Las propiedades son el examen real.

Estrategia 3 — El patrón Haiku verify

Configuración: 5 minutos · Costo: $0.07 por ejecución

Este patrón usa Haiku 4.5 (el modelo más barato) en tres pasos en cadena para verificar lo que generó un modelo más caro:

Total: $0.07 + 3 minutos vs. revisión manual completa: $50 + 30 minutos.

La secuencia de prompts para un controlador Spring Boot:

Prompt 1 (Sonnet 5 — genera el ejemplar):
"Implementa PedidoController con los endpoints POST /pedidos y
GET /pedidos/{id} según esta especificación OpenAPI: [spec aquí].
Usa Spring Boot 3, jakarta.*, y el patrón de respuesta ApiResponse<T>
que ya existe en el proyecto."

Prompt 2 (Haiku 4.5 — genera pruebas):
"Dado este PedidoController [código], escribe pruebas MockMvc que
verifiquen el contrato de la API: status codes, estructura del JSON
de respuesta, y que ningún campo del DTO se pierda o cambie de nombre."

Prompt 3 (Haiku 4.5 — contrasta vs. spec):
"Compara este PedidoController [código] con esta especificación OpenAPI
[spec]. Lista cualquier discrepancia: campos extra, campos faltantes,
tipos incorrectos, o comportamientos no especificados."

Tú revisas los puntos críticos que señala el paso 3. El resto lo verifica la máquina.

"Modelo barato + verificación fuerte > modelo caro + fe ciega."

Estrategia 4 — Corpus real: no uses datos de juguete

La debilidad de los tests con datos inventados: la IA elige los datos que mejor funcionan con su implementación. El corpus real usa archivos o registros reales de producción —anonimizados— para descubrir edge cases que nadie anticipó.

En proyectos Java, esto significa mantener un directorio src/test/resources/corpus/ con muestras representativas:

src/test/resources/corpus/
├── pedidos/
│   ├── pedido-monto-maximo.json        # monto = 999999.99
│   ├── pedido-cliente-nulo.json        # clienteId ausente
│   ├── pedido-caracteres-especiales.json  # nombres con ñ, acentos
│   ├── pedido-estado-cancelado.json    # flujo de cancelación
│   └── pedido-multiples-lineas.json    # 50+ líneas de detalle

// PedidoCorpusTest.java
@ParameterizedTest
@MethodSource("archivosDePedidosReales")
void corpus_cadaArchivoPasaRoundTrip(Path archivoJson) throws Exception {
    String jsonOriginal = Files.readString(archivoJson);
    PedidoDTO pedido = objectMapper.readValue(jsonOriginal, PedidoDTO.class);
    String jsonReserializado = objectMapper.writeValueAsString(pedido);
    PedidoDTO restaurado = objectMapper.readValue(jsonReserializado, PedidoDTO.class);

    assertEquals(pedido, restaurado,
        "El archivo " + archivoJson.getFileName() + " falló el round-trip");
}

static Stream<Path> archivosDePedidosReales() throws IOException {
    return Files.list(Path.of("src/test/resources/corpus/pedidos"));
}

Cinco archivos reales descubren más bugs que cien tests inventados.

La anatomía de una alucinación — historia real (adaptada a Java)

Este es el patrón que más se repite en producción y que más fácilmente pasa la revisión humana.

Acto 1 — El DTO de aspecto perfecto

Claude genera PedidoDTO para un endpoint de migración Spring Boot 2 → 3. El código es limpio, está bien comentado, compila sin warnings:

// Lo que generó Claude
public record PedidoDTO(
    Long id,
    String referencia,   // ← campo inventado por la IA
    String numero,
    BigDecimal monto,
    EstadoPedido estado
) {}

Pasó la revisión del PR. Pasó los tests unitarios generados por la propia IA. El test de PedidoServiceTest usaba exactamente los mismos campos que el DTO generado.

Acto 2 — La falla oculta

La especificación OpenAPI decía:

PedidoDTO:
  type: object
  properties:
    id:
      type: integer
    numero:
      type: string
    monto:
      type: number
    estado:
      type: string
      enum: [PENDIENTE, CONFIRMADO, CANCELADO]

Sin campo referencia. La IA lo inventó porque en el servicio adyacente existía un campo con ese nombre. El sistema compiló, los tests pasaron, el deploy fue a producción.

En producción: el API recibía JSONs sin el campo referencia. Jackson lo deserializaba a null. Downstream, el procesador de pagos esperaba ese campo como parte del contrato interno y fallaba silenciosamente.

Acto 3 — Lo que lo hubiera capturado en 30 segundos

@Test
void roundTrip_PedidoDTO_contraCorpusReal() throws Exception {
    // Este JSON viene del corpus — formato real del cliente
    String jsonReal = """
        {
            "id": 101,
            "numero": "PED-2024-001",
            "monto": 450.00,
            "estado": "CONFIRMADO"
        }
        """;

    PedidoDTO pedido = objectMapper.readValue(jsonReal, PedidoDTO.class);
    String jsonReserializado = objectMapper.writeValueAsString(pedido);

    // Si 'referencia' es un campo requerido (no nullable),
    // la deserialización habría fallado aquí mismo.
    // Si es nullable, el round-trip habría devuelto null
    // en lugar de ausente, alertando la discrepancia.
    assertThat(jsonReserializado).doesNotContain("referencia");
}

Capturado en 30 segundos. Previno más de 4 horas de war room.

La pregunta que vale plantear en el próximo PR de 400 líneas generado por IA: ¿quién lo habría visto en la revisión manual un viernes a las 6 PM?

Incorporar la verificación al pipeline Java

La verificación sistemática no es responsabilidad de un desarrollador individual en cada PR. Es una política del pipeline. Así queda integrado en un proyecto Spring Boot típico:

El checklist Pre-PR para código generado por IA

Agrégalo como comentario en el PR template de tu repositorio:

## Checklist — código generado con IA

- [ ] ¿Hay test round-trip para cada DTO nuevo o modificado?
- [ ] ¿El corpus de archivos reales cubre este componente?
- [ ] ¿Haiku verificó la implementación contra la spec OpenAPI?
- [ ] ¿El test diferencial compara el nuevo comportamiento con el anterior?
- [ ] ¿Spot-check humano de 3 min en los campos críticos (montos, IDs, estados)?
- [ ] ¿`CLAUDE.md` tiene la regla: "todo parser nuevo requiere round-trip"?

La línea para CLAUDE.md

## Reglas de verificación (obligatorias)

Todo componente nuevo que parsee, serialice o transforme datos DEBE incluir:
1. Test round-trip con JUnit 5 + Jackson (o el serializador del proyecto)
2. Al menos un archivo del corpus real en `src/test/resources/corpus/`
3. Test de propiedades con jqwik para invariantes de negocio críticas

Si la spec OpenAPI cambia, el test Haiku verify confirma alineación antes del merge.

Métricas de éxito

Cuando llega un bug de IA a producción, la pregunta correcta no es "¿quién lo aprobó en el PR?". La pregunta es: "¿qué estrategia de verificación faltaba?". La respuesta se convierte en una nueva regla en CLAUDE.md.

Acciones inmediatas

Hoy (30 minutos)

1. Identifica los 2–3 DTOs más críticos de tu proyecto Spring Boot (los que mueven dinero, estados de negocio, o integran con sistemas externos)

2. Escribe un test round-trip para cada uno — si ya tienes @SpringBootTest es cuestión de agregar el test

3. Agrega al CLAUDE.md del proyecto: "Todo DTO nuevo requiere test round-trip"

Esta semana

1. Crea src/test/resources/corpus/ con 5–10 JSONs reales anonimizados

2. Integra el checklist Pre-PR al template del repositorio

3. Implementa el patrón Haiku verify para los endpoints de mayor tráfico

Este mes

1. Añade jqwik para las invariantes de negocio críticas (montos, estados, referencias)

2. Conecta los corpus tests al CI/CD — si falla el round-trip, el pipeline no avanza

3. Meta: tasa de captura pre-producción >95%

La ecuación que cambia la perspectiva

"Haiku barato + verificación fuerte es matemáticamente superior a un modelo caro con fe ciega."

La IA sin verificación es velocidad hacia el precipicio. Con el playbook de verificación, es el 10× de productividad que promete — sin pagar el precio en producción.

El Pilar 1 te da el contexto. El Pilar 2 te ahorra dinero. El Pilar 3 hace que los dos anteriores sean seguros de usar.

¿Qué estrategia de verificación usas hoy en tu proyecto Java? ¿Round-trip, propiedades, algo diferente? Cuéntame en los comentarios.

Enjoy!

Joe

Parte de la serie "Los 6 pilares del desarrollo asistido por IA" — basado en el material de Thor Henning Hetland (Totto) / Ægis. Adaptado a proyectos Java.

Cuando un desarrollador nuevo entra al equipo, no lo sueltas al codebase sin onboarding. Le explicas la arquitectura, le muestras los patrones que usa el equipo, le dices qué no hacer y por qué. Le enseñas las convenciones de Git, los frameworks de testing, los errores que ya se cometieron.

La IA necesita exactamente lo mismo.

Sin ese contexto, Claude adivina. Y lo hace con confianza: genera código limpio, bien formateado, que compila... y que viola tres convenciones del proyecto, usa el stack equivocado y replica un bug que ya se resolvió hace dos sprints.

El Pilar 1 convierte a la IA en un colaborador que conoce el proyecto. No una herramienta que adivina, sino un miembro del equipo que ha leído el onboarding.

La arquitectura dual del contexto

El contexto inteligente se divide en dos capas complementarias:

CLAUDE.md es la guía universal: vive en la raíz del repositorio, cubre la arquitectura global, el flujo de Git y el enfoque de testing. Es lo primero que Claude lee en cada sesión.

.claude/skills/ son módulos de conocimiento especializado: cada archivo cubre un dominio concreto del proyecto (entidades JPA, diseño de API, convenciones de Spring Boot). Son más cortos (100–300 líneas) y más profundos que el CLAUDE.md.

El plano base: las 7 secciones del CLAUDE.md

El archivo inicial debe tener entre 500 y 1.000 líneas. No más. No menos. Estas son las siete secciones que no pueden faltar, con ejemplos directamente aplicables a un proyecto Spring Boot:

1. Comandos de construcción

Los comandos exactos para compilar, testear y ejecutar. Sin ambigüedad.

## Comandos de construcción

# Compilar
mvn clean compile -q

# Tests unitarios (sin tests de integración)
mvn test -Dgroups="unit"

# Tests de integración (requiere Docker para Testcontainers)
mvn verify -Dgroups="integration"

# Ejecutar localmente con perfil dev
mvn spring-boot:run -Dspring-boot.run.profiles=local

# Linting + checkstyle
mvn checkstyle:check

# Generar la especificación OpenAPI
mvn spring-boot:run & sleep 10 && curl http://localhost:8080/v3/api-docs -o docs/openapi.json

2. Visión general de la arquitectura

200–300 palabras explicando la estructura de paquetes, las capas y las decisiones de diseño clave.

## Arquitectura

Aplicación Spring Boot 3.x con arquitectura hexagonal.

Paquetes principales:
- com.empresa.pedidos.domain       → Entidades, Value Objects, puertos
- com.empresa.pedidos.application  → Casos de uso, servicios de aplicación
- com.empresa.pedidos.infrastructure → Repositorios JPA, adaptadores HTTP, Kafka
- com.empresa.pedidos.api          → Controladores REST, DTOs, mappers

Reglas de dependencia (estrictas):
- domain NO depende de ninguna otra capa
- application depende SOLO de domain
- infrastructure y api dependen de application

Base de datos: PostgreSQL 16 via Spring Data JPA / Hibernate 6
Mensajería: Apache Kafka (Spring Kafka)
Autenticación: Spring Security + JWT

3. Patrones críticos — lo que SIEMPRE se hace

## Patrones críticos

1. SIEMPRE usar `java.math.BigDecimal` para montos monetarios.
   Nunca Double, Float, ni int.

2. SIEMPRE usar `jakarta.*` (no `javax.*`). El proyecto está en Spring Boot 3.

3. Los DTOs son Java records inmutables. Nunca clases con setters.
   Correcto: public record PedidoDTO(Long id, String numero, BigDecimal monto) {}

4. Los IDs de entidad son Long. Los IDs de API (expuestos) son UUID como String.

5. Todo endpoint REST devuelve ApiResponse<T> del proyecto.
   Nunca devolver la entidad JPA directamente.

6. SIEMPRE incluir @Operation y @Parameter de OpenAPI 3 en los controladores.

7. Los mappers entre entidad y DTO usan MapStruct (ya configurado).

4. Anti-patrones — lo que NUNCA se hace

## Anti-patrones

1. NUNCA usar @Autowired en campos. Usar inyección por constructor siempre.

2. NUNCA hacer consultas JPA en el controlador o el DTO.
   Las queries van en el repositorio o en el caso de uso.

3. NUNCA lanzar Exception genérica. Usar las excepciones del dominio:
   PedidoNotFoundException, MontoInvalidoException, etc.

4. NUNCA usar Optional<T> como parámetro de método.
   Solo como valor de retorno.

5. NUNCA hacer commit en main/develop directamente. Todo via PR.

6. NUNCA usar String para representar estados. Usar el enum EstadoPedido.

7. NUNCA usar Lombok en código nuevo. El proyecto migró a records y
   constructores explícitos. Lombok solo existe en código legado no migrado.

5. Flujo de Git

## Flujo de Git

Naming de ramas:
- feat/JIRA-123-descripcion-corta
- fix/JIRA-456-nombre-del-bug
- chore/actualizacion-dependencias

Commits (Conventional Commits):
- feat(pedidos): agregar endpoint de cancelación
- fix(pagos): corregir cálculo de IVA con BigDecimal
- test(pedidos): agregar round-trip test para PedidoDTO

PRs:
- Mínimo 1 reviewer de otro squad
- CI debe estar verde (tests + checkstyle + coverage ≥80%)
- El título del PR sigue el mismo formato que los commits

6. Requisitos de testing

## Testing

Framework: JUnit 5 + AssertJ + Mockito
Cobertura mínima: 80% en clases de dominio y aplicación

Reglas:
- Tests unitarios: sin Spring context, sin base de datos
- Tests de integración: Testcontainers (PostgreSQL + Kafka)
- Todo DTO nuevo tiene test round-trip con Jackson
- El directorio src/test/resources/corpus/ contiene 5+ JSONs reales anonimizados

Nombrado:
- PedidoServiceTest          → tests unitarios
- PedidoControllerIT         → tests de integración
- PedidoDTORoundTripTest     → tests de serialización

7. Errores comunes del equipo

Esta sección es oro puro: los bugs reales que ya ocurrieron y que la IA no debe repetir.

## Errores comunes (aprende de estos)

BUG-2024-01: Campo 'clienteId' desalineado en PedidoDTO
  Causa: La IA añadió un campo 'referencia' que no estaba en el spec OpenAPI.
  Solución aplicada: Round-trip test contra corpus real.
  Regla: Todo DTO nuevo requiere test round-trip ANTES del merge.

BUG-2024-02: Double en lugar de BigDecimal para monto
  Causa: La IA usó Double por defecto para campos numéricos.
  Detectado en: cálculo de totales con pérdida de precisión.
  Regla: Siempre BigDecimal para montos (ver Patrones Críticos #1).

BUG-2024-03: javax.persistence en Spring Boot 3
  Causa: La IA usó javax.* por ser más común en sus datos de entrenamiento.
  Regla: Siempre jakarta.* (ver Patrones Críticos #2).

Las 4 skills de alto impacto para empezar

No intentes construir 50 skills el primer día. Empieza con estas cuatro (15–30 minutos cada una):

Cada skill sigue la misma estructura:

• Propósito (1 párrafo — qué resuelve este módulo)

• Reglas con ejemplos de ✅ Correcto vs ❌ Incorrecto

• Checklist de verificación al final

El efecto compuesto: de 2 horas a 20 minutos

El contexto no es un costo puntual. Es una inversión con retorno compuesto:

Los números de proyectos reales:

• 90% de reducción en errores de la IA

• 7.5 horas ahorradas en la generación de 15 parsers similares

• Ciclo de revisión de PR de 2–3 días → 4–6 horas

• 60–70% menos uso de modelos costosos (Haiku hace lo que antes requería Sonnet)

El bucle de aprendizaje continuo

El contexto se vuelve más inteligente con cada ciclo de desarrollo, siempre que se actualice sistemáticamente:

La regla de mantenimiento es simple: después de cada bug de IA, actualizas el contexto antes de cerrar el ticket. En menos de 15 minutos. El mismo bug no vuelve a ocurrir.

Cronograma de implementación

Para empezar hoy en un proyecto Spring Boot existente, los comandos son los de menos. Lo que cambia el juego son las secciones de Anti-patrones y Errores Comunes: ahí está el conocimiento del equipo que la IA normalmente nunca tiene.

Las métricas que indican que el contexto está funcionando

Por qué este pilar habilita los otros dos

El Pilar 2 (delegación estratégica) dice: usa Haiku 4.5 para el 60–70% de las tareas de seguir patrones. Pero Haiku sin contexto no puede seguir tus patrones: los desconoce. Con un CLAUDE.md sólido y las skills del dominio, Haiku 4.5 genera código que sigue tus convenciones Java, usa el stack correcto y evita los anti-patrones conocidos del equipo.

El Pilar 3 (verificación) dice: todo DTO nuevo necesita round-trip test. Pero si esa regla no está en CLAUDE.md, la IA no la aplica por defecto. El contexto convierte las reglas de verificación en comportamiento automático.

Los tres pilares se sostienen mutuamente. El Pilar 1 es la base.

¿Tu proyecto Java ya tiene un CLAUDE.md? ¿Qué secciones tienes y cuáles te faltan? Cuéntame en los comentarios.

Enjoy!

Joe

El problema: todos los modelos no cuestan igual

Anthropic publica cuatro niveles de modelo con precios muy distintos (valores de input, julio 2026):

La diferencia entre Haiku 4.5 y Fable 5 es de 10×. Entre Haiku 4.5 y Opus 5, 5×. La mayoría de los equipos manda todo a Sonnet sin pensar. Eso equivale a usar un camión de mudanzas para llevar una carta al correo: funciona, pero pagas gasolina de camión por un sobre.

El insight que cambia la ecuación: en tareas de seguir patrones —el 60–70% de lo que hace un equipo de software— Haiku 4.5 es tan bueno como Opus 5. El modelo no importa cuando el patrón está claro.

Los cuatro niveles de tarea

No todas las tareas tienen la misma complejidad. Esta taxonomía cubre el 99% de los casos:

Nivel 1 — Haiku 4.5 (60–70% de las tareas)

Pregunta clave: ¿Ya existe un ejemplo claro en el proyecto?

Son las tareas de seguir un patrón establecido: el test número 15 con el mismo estilo que los otros 14, otro endpoint CRUD igual al de Cliente o Producto, un parser más con la misma estructura, documentación con el mismo formato.

"Si estás copiando un patrón, no necesitas el modelo más inteligente. Necesitas el más barato y rápido… con buen contexto."

Nivel 2 — Sonnet 5 (25–35% de las tareas)

Pregunta clave: ¿Hay que pensar, inventar o depurar algo nuevo?

Features que no existen aún, bugs raros (race conditions, integraciones), el primer ejemplar de un patrón nuevo, refactors que requieren criterio. Sonnet 5 es el motor del día a día de ingeniería real.

Nivel 3 — Opus 5 (5–10% de las tareas)

Pregunta clave: ¿Se rompe el sistema si esto sale mal?

Diseño de arquitectura, algoritmos novedosos, decisiones de seguridad crítica, refactors de alto riesgo. Opus 5 es cirugía: preciso, caro, para cuando el diagnóstico lo justifica.

Nivel 4 — Fable 5 (<5% de las tareas)

Pregunta clave: ¿Requiere razonamiento sostenido en decenas de pasos, o es un agente autónomo?

Agentes que navegan codebases completos, análisis de arquitectura que correlaciona 50+ archivos, orquestación de workflows sin intervención humana. Fable 5 es el nuevo techo del ecosistema Claude: a $10/MTok, se reserva para cuando el problema realmente lo exige.

El patrón template: un ejemplar, N−1 copias baratas

El patrón más potente del Pilar Delegación combina dos niveles:

1. Sonnet 5 construye la primera implementación con todos los edge cases resueltos y los tests en verde.

2. Haiku 4.5 replica las N−1 instancias restantes siguiendo ese template.

El resultado: misma calidad, fracción del costo.

Ejemplo ilustrativo — migración de API Java

Imagina un proyecto pedidos-api en Spring Boot 2 que necesita migrar a Spring Boot 3. Doce controladores REST necesitan la misma transformación: namespace javax.* → jakarta.*, anotaciones Swagger 2 (@ApiOperation, @ApiParam) → OpenAPI 3 (@Operation, @Parameter), y tests MockMvc con los nuevos patrones.

El flujo con el patrón template:

• Sonnet 5 migra PedidoController — el más complejo — con todos los edge cases resueltos y los tests en verde. Ese archivo es la receta.

• Haiku 4.5 migra los 11 controladores restantes siguiendo el mismo patrón.

→ ~62% de ahorro vs todo Sonnet 5 · ~83% de ahorro vs todo Fable 5

Y esto no es un caso extremo. Cualquier migración masiva tiene este patrón: la lógica de transformación es idéntica en todos los controladores, solo cambian los detalles de cada uno. El primer ejemplar resuelve el problema; los demás son ejecución de receta.

Multiplica eso por 300+ tests, 50+ exporters o una migración de 80 endpoints de API, y el ahorro se compone rápido.

El árbol de decisión (cuatro preguntas)

Antes de abrir el chat con Claude, hazte estas preguntas en orden:

1. ¿Es un agente autónomo o requiere razonamiento sostenido en decenas de pasos? → SÍ: Fable 5

2. ¿Es una decisión arquitectónica crítica o un algoritmo novedoso? → SÍ: Opus 5

3. ¿Requiere razonamiento complejo o resolver un problema único? → SÍ: Sonnet 5

4. ¿Está siguiendo un patrón ya establecido en el codebase? → SÍ: Haiku 4.5

¿Ninguna? → Sonnet 5 (es un patrón nuevo que aún no existe en el codebase)

Tres ejemplos rápidos para calibrar:

• "Escribe el endpoint CRUD de Factura igual al de Pedido" → Haiku 4.5

• "Hay un deadlock intermitente en el checkout" → Sonnet 5

• "Diseña cómo vamos a versionar la API pública" → Opus 5

• "Construye un agente que audite todo el codebase y proponga refactors" → Fable 5

Por qué este pilar no funciona sin el Pilar 1

Haiku 4.5 barato y rápido suena bien. El problema es que sin contexto, Haiku genera código genérico: no sigue tus patrones, usa la arquitectura equivocada, comete errores que Sonnet no cometería.

Con un CLAUDE.md sólido y skills del proyecto, Haiku 4.5 sigue patrones documentados con precisión, usa la arquitectura correcta y evita los anti-patrones conocidos. El contexto convierte a Haiku en un junior fiable. Sin ese contexto, es un junior que adivina.

La cadena de dependencia es directa:

Pilar 1: CLAUDE.md + skills → ADN del codebase
    → Haiku 4.5 tiene el contexto para ser fiable
    → Pilar 2: delegación estratégica funciona

El ejercicio práctico

Antes de terminar de leer este artículo, piensa en las últimas 10 cosas que le pediste a Claude:

• ¿Cuántas eran seguir un patrón existente (Nivel 1)?

• ¿Cuántas realmente necesitaban razonamiento de Nivel 3 o 4?

• ¿Qué modelo usaste para cada una?

• ¿Cuál habría sido el costo con el modelo correcto?

La mayoría de los equipos descubre que entre el 60 y el 70% de sus tareas cae en Nivel 1. El endpoint CRUD número 14. El doc de API número 5. El test que sigue exactamente el mismo patrón que los otros 20. Territorio Haiku 4.5.

Lo que sigue

Ya sabes qué modelo usar para cada tarea. La pregunta siguiente es: ¿cómo verificas que lo que generó está bien?

Eso es el Pilar 3 — Confía, pero verifica: los patrones de validación que hacen que la delegación sea segura, no un salto de fe.

¿Usas Claude en tu equipo de desarrollo? ¿Qué distribución de modelos tienes hoy? Cuéntame en los comentarios o escríbeme directamente.

Enjoy!

Joe

Volví de República Dominicana con la batería cargada… y con el corazón un poco más Java. Gracias, JConf Dominicana.

Hay conferencias que te dejan slides. Otras te dejan amigos. JConf Dominicana me dejó las dos cosas… y algo más difícil de explicar: esa sensación de que, aunque llegues de otro país, ya perteneces.

Cuando una foto de grupo no se siente forzada… eso ya dice mucho.

Si alguien me pregunta qué se siente, lo digo sin filtro: para mí es como mi DevNexus, pero en Latam. Y si alguna vez soñaste vivir algo muy cercano a JavaOne —charlas de verdad, cenas largas, comida local, paseo por la ciudad y una hospitalidad que no se finge—, aquí lo tienes.

No es marketing. Se vive.

El auditorio, el rojo de las butacas, la gente atenta… Java con alma.

Gracias a quienes hacen posible que esto sea magia

Quiero agradecer de frente a Carlos Camacho, Eudris, Brayan, Rafael, Fredi, Eliezer y a todos los organizadores y el equipo de soporte. Fueron anfitriones de los buenos: los que no solo “corren un evento”, sino que te cuidan.

Eudris, gracias por llevarnos a Santiago — por la parada y compartir con nosotros la ida. Carlos, qué buen tío: enseñarnos la ciudad, abrirnos las puertas, hacernos sentir bienvenidos de verdad. Eso no se olvida.

Y al equipo que estaba en el lobby con las camisetas de la Dominicana JUG, con los badges listos, con la sonrisa puesta aunque el día fuera largo… ustedes son el corazón del evento.

“La comunidad de usuarios Java de República Dominicana” no es un slogan. Se ve en el pasillo.

Ese ir y venir entre charlas… energía pura de comunidad.

Lo que pasa fuera del escenario

Las mejores conversaciones no siempre caben en 45 minutos con Q&A.

Hubo cenas, brindis, risas, terraza de noche con la ciudad iluminada de fondo… y esa sensación de “esto es lo que vine a buscar” aunque no lo hubieras puesto en la agenda.

Cuando el networking deja de ser networking y se vuelve noche de amigos.

Ciudad, mesa compartida y la certeza de que Latam Java está más vivo que nunca.

Airbnb, Vicente, Chochos… y las conversas que importan

Esta vez tuve el honor de compartir Airbnb con Vicente y Chochos. Y qué lujo.

No solo “convivir”: grandes conversas y tomar Mezcal (gracias Chochos)—las que te hacen ver que, aunque vengamos de países distintos, tenemos muchísimo en común. Misma pasión por Java, mismos retos, misma ganas de construir comunidad sin ego.

Esos ratos valen tanto como cualquier keynote.

Camisetas JConf, sol, sonrisas. Así se ve el Caribe Java (esta puede ser una gran charla jajaja).

Si te vas sin una foto así… ¿realmente fuiste a la Jconf?

Que gusto ver a mi amigo Ronald de CostaRica que me dió una gran entrevista hace años y que esta publicada en Spotify. Por fin pude abrazarlo, conocer algo de su vida privada y lo orgulloso que está de sus hijos. Gracias por compartir eso conmigo amigo, no sabes como necesitaba escuchar algo así.

Después de la charla: una visita por el centro de la ciudad. Abrazos, memes y “¿cuándo nos vemos en la próxima?”

Pins, sol y la cara de “esto valió cada milla recorrida”.

Apuntes de Java

No podía dejar de mencionar a Diego Silva que también fue con su esposa, es de Perú, muy conocido en la comunidad cómo Apuntes de Java. Nos dió una excelente charla sobre Jakarta EE y sus desarrollos alrededor de la misma. Que más peruanos se animen a participar de estas conferencias.

Por qué esto importa (más allá del CV)

En un mundo que a veces reduce todo a métricas, JConf Dominicana me recuerda algo simple:

La comunidad no se descarga. Se construye. Con café en el lobby. Con una pregunta después de tu talk. Con alguien que te lleva a conocer la ciudad. Con un “quédate un rato más” en la mesa.

Si estás dudando si vale la pena cruzar el mar, el país o la agenda para ir… vale la pena. Trae ganas de aprender, sí. Pero sobre todo trae el corazón abierto.

Yo, por mi parte, espero volver.

Gracias, República Dominicana. Gracias, JConf Dominicana. Gracias a cada persona que hizo que esta edición se sintiera como casa.

Nos vemos en la próxima. ☕☕☕

Joe

#JConfDominicana #Java #ComunidadJava #LatamTech #DominicanaJUG #PeruJUG #JoeDayz

Lo que realmente marca la diferencia es el contexto que le das a la IA.

Muchos equipos prueban ChatGPT, Claude o GitHub Copilot durante unos días y luego concluyen que "no funciona tan bien". En realidad, el problema no suele ser la IA, sino la falta de información que tiene sobre el proyecto.

Veamos una hoja de ruta muy simple para implementarla.

Paso 1: Hoy - Crea el contexto del proyecto

La IA necesita entender tu aplicación antes de ayudarte.

Dedica unas horas a crear un archivo como CLAUDE.md, AGENTS.md o README_AI.md con información como:

• ¿Qué hace el proyecto?

• ¿Cómo se ejecuta?

• Arquitectura general.

• Convenciones de código.

• Reglas para Git.

• Patrones utilizados.

Por ejemplo:

Proyecto: Sistema de Ventas

Lenguaje: Java 21 Framework: Spring Boot Base de datos: PostgreSQL

Comandos:

• mvn clean install

• mvn test

• docker compose up

Arquitectura: Controller -> Service -> Repository

Reglas:

• No usar lógica en Controllers

• Todas las APIs deben tener pruebas

👉 Piensa en este documento como el manual de bienvenida para la IA.

Paso 2: Esta semana - Enseña habilidades específicas

Ahora la IA ya conoce el proyecto.

El siguiente paso es enseñarle cómo trabaja tu equipo.

Por ejemplo:

• Cómo escribir pruebas unitarias.

• Cómo revisar un Pull Request.

• Cómo documentar APIs.

• Cómo nombrar clases.

• Cómo detectar código duplicado.

En lugar de repetir instrucciones cada día, las conviertes en Skills reutilizables.

Ejemplo:

"Antes de aprobar un PR verifica cobertura de pruebas, manejo de excepciones y convenciones de nombres."

La IA podrá ejecutar esta revisión automáticamente.

Paso 3: Este mes - Amplía las habilidades

Cuando el equipo ya domina las primeras Skills, es momento de crecer.

Puedes agregar habilidades para:

• Seguridad.

• Performance.

• Refactorización.

• Arquitectura.

• Migraciones.

• Documentación.

• Accesibilidad.

Lo importante es que cada problema resuelto se convierta en conocimiento reutilizable.

Si hoy corregiste un bug complicado...

...mañana la IA ya sabrá cómo evitarlo.

Paso 4: Este trimestre - La IA ya forma parte del proceso

En este punto la IA deja de ser una herramienta ocasional.

Se integra al flujo normal de desarrollo.

Por ejemplo:

✅ Crear historias técnicas.

✅ Revisar Pull Requests.

✅ Detectar problemas de arquitectura.

✅ Generar documentación.

✅ Ayudar en refactorizaciones.

✅ Sugerir pruebas faltantes.

El conocimiento del equipo crece continuamente.

¿Por qué funciona?

Imagina contratar a un desarrollador nuevo.

El primer día no conoce:

• el negocio,

• la arquitectura,

• las reglas,

• ni el estilo del equipo.

Con la IA ocurre exactamente igual.

Si le proporcionas contexto, aprende mucho más rápido.

La idea más importante

La mayoría piensa que el secreto está en escribir mejores prompts.

En realidad...

Los mejores resultados llegan cuando la IA tiene un buen contexto, no cuando escribimos prompts cada vez más largos.

Los prompts se olvidan.

El contexto permanece.

Y mientras más contexto acumula el equipo, mejores resultados obtiene la IA.

Resumen

📅 Hoy

• Documenta tu proyecto.

📅 Esta semana

• Crea 3 a 5 Skills reutilizables.

📅 Este mes

• Amplía esas Skills a distintas áreas.

📅 Este trimestre

• Integra la IA en todo el ciclo de desarrollo.

Reflexión final

La IA no reemplaza la experiencia del equipo.

La potencia.

Cada documento, cada decisión de arquitectura y cada lección aprendida alimentan un ecosistema donde la IA puede aportar cada vez más valor.

La verdadera ventaja competitiva no será quién use IA, sino quién construya el mejor contexto para que la IA trabaje junto a su equipo.

Enjoy!

Joe

EPILOGO:

✍️ ¿Y tú? ¿Ya documentas el contexto de tus proyectos o todavía comienzas cada conversación con la IA desde cero? Déjamelo en los comentarios.