Usa el sistema de tipos de TypeScript como documentación para IA

El type system de TypeScript como documentación para tu agente de IA

Tiempo estimado de lectura: 4 min

El type system de TypeScript como documentación para tu agente de IA funciona mejor que mil parrafadas: le das al modelo un contrato, no una novela. Si quieres que Claude, GPT o cualquier agente genere código real y alineado con tu arquitectura, empieza por entregarle los tipos —no descripciones— y observa cómo las alucinaciones desaparecen.

¿Por qué? Porque un tipo es una restricción matemática. Un LLM con contexto tipado no puede inventar propiedades, estados o firmas que no existen.

Resumen rápido (lectores con prisa)

Qué: Usa el type system de TypeScript como contrato para agentes IA.

Cuándo: En APIs públicas, lógica crítica y workflows en producción.

Por qué importa: Reduce alucinaciones y errores de integración.

Cómo: Pega las interfaces, enums y tipos en el prompt y obliga al agente a cumplir firmas y uniones discriminadas.

Qué cambia en tu flujo de trabajo

Los modelos de lenguaje predicen tokens; no “entienden” tus necesidades de negocio. Cuando les ofreces solo lenguaje natural, abrazan convenciones comunes y rellenan huecos con suposiciones populares. Resultado: código que “parece” correcto pero falla en integrarse con tu stack.

Si en cambio inyectas las interfaces, enums y tipos de tu proyecto, reduces drásticamente el espacio de soluciones válidas. El agente no elige entre cien estructuras posibles: respeta la tuya.

No es teoría. Es práctica:

Fuentes prácticas: documentación oficial de TypeScript, guías de APIs y plataformas de agentes como OpenAI o Anthropic.

Ejemplo práctico: deja de explicar, pega el tipo

Imagina que quieres delegar la lógica de cambio de estado de pedidos.

Sin tipos: “Crea una función para actualizar el estado de un pedido”. El modelo inventa estados. Problema.

Con tipos reales:

type OrderStatus = 'pending' | 'confirmed' | 'dispatched' | 'delivered' | 'refunded';

interface Order {
  id: string;
  status: OrderStatus;
  customerId: string;
  updatedAt: string; // ISO UTC
}

type UpdateOrderStatusResult = 
  | { success: true; order: Order }
  | { success: false; error: 'ORDER_NOT_FOUND' | 'INVALID_TRANSITION' };

Pega esto en el prompt o en el contexto del agente (Cursor, GitHub Copilot, flujos custom via API) y pide: “Implementa updateOrderStatus que valide transiciones y devuelva UpdateOrderStatusResult”. Ahora el agente debe cumplir la firma. No habrá processing fantasmas ni retornos desordenados.

Reglas prácticas para construir el contexto tipado

1. Evita any como si fuera veneno

any es una puerta abierta a alucinaciones.

2. Prefiere uniones discriminadas sobre booleans dispersos

Las banderas (isLoading, isError) permiten estados imposibles; una unión no.

3. Añade JSDoc breve cuando la intención no sea obvia

Ejemplo: /** Fecha en UTC. No convertir a local. */

4. Expone las relaciones

Usa referencias: invoice.orderId: Order['id']. El agente lo interpreta como clave foránea.

5. Incluye los tipos de retorno claros (Result/Either)

Obliga a manejar errores, no a ignorarlos.

Herramientas que usan este enfoque

Herramientas que usan este enfoque: n8n para orquestación, GitHub Copilot y Cursor en editores. También puedes integrar directamente archivos .d.ts en el contexto de la llamada a la API.

¿Cuándo aplicar Type-Driven Development con agentes?

Úsalo cuando la consistencia importa: APIs públicas, lógica financiera, workflows críticos, transformaciones de datos y automations en producción. Evítalo solo en prototipos tempranos donde los modelos de datos cambian cada dos días.

No confundas disciplina con burocracia: diseñar tipos claros al principio acelera todo lo demás. Es una inversión que reduce revisiones manuales y bugs silenciosos.

Resultado esperado y próximos pasos

Si empiezas hoy, el cambio es tangible: menos iteraciones, menos PRs arreglando supuestos imposibles y, sobre todo, código que entra en tu base sin romper contratos. El tipo es el contrato. El agente es el implementador.

Haz esto ahora: copia el archivo de tipos relevante (o el fragmento clave) en el prompt de tu agente, pide una implementación concreta y compara el PR generado con lo que haría un desarrollador. Notarás dos cosas: consistencia y menos errores lógicos. Si trabajas con n8n, añade los tipos a los nodos o workflows para que los agentes que automatan tareas respeten tus contratos.

No acaba aquí: diseña un checklist de tipos antes de delegar, prueba un par de endpoints y verás cómo el modelo deja de “inventar”. ¿Quieres un checklist listo para usar? Haz esto primero: pega tu index.d.ts en el prompt y pide al agente “Genera tests unitarios que verifiquen las transiciones permitidas”. Verás la diferencia al instante.

Si quieres profundizar con proyectos y experimentos, revisa también los recursos y experimentos de Dominicode Labs. Es un buen complemento para validar patrones de Type-Driven Development aplicados a agentes y workflows antes de llevarlos a producción.

FAQ