Tag: Programación

  • Implementación de formularios y validación en Angular 22

    Implementación de formularios y validación en Angular 22

    El stack completo del dev Angular en 2026: formularios, validación y tests

    Tiempo estimado de lectura: 3 min

    • Angular 22: reactividad con Signals y formularios con tipado estricto para detectar incompatibilidades en compilación.
    • Zod: esquema único TypeScript-first que centraliza reglas de negocio y evita duplicidad entre frontend y backend.
    • Jest + Testing Library: tests centrados en la experiencia del usuario, rápidos y resistentes a refactors.
    • Arquitectura en capas (presentador + servicios + esquemas) reduce bugs y facilita refactors.

    El stack completo del dev Angular en 2026: formularios, validación y tests es una realidad técnica: Angular 22 aporta reactividad y tipado estricto; Zod centraliza las reglas de negocio como esquemas TypeScript-first; y Jest + Testing Library aseguran pruebas resilientes desde la perspectiva del usuario. Si quieres construir formularios que no se rompan con el primer refactor, este es el flujo que realmente funciona en producción.

    Resumen rápido (lectores con prisa)

    Qué es: Un stack que combina Angular 22, Zod y Jest + Testing Library para formularios tipados, validación centralizada y tests orientados a usuario.

    Cuándo usarlo: Formularios complejos que requieren reglas de negocio compartidas entre cliente y servidor y tests resistentes a refactors.

    Por qué importa: Reduce duplicidad de reglas, mantiene tipos sincronizados y mejora la estabilidad de tests y CI.

    Cómo funciona: Angular gestiona la UI y tipos, Zod define esquemas TypeScript-first, y Jest + Testing Library validan comportamiento visible.

    Angular 22: Signals, Standalone y formularios tipados

    Angular 22 cambia el contrato de diseño.

    • Standalone Components reduce acoplamiento: cada componente declara exactamente lo que necesita.
    • Signals ofrece reactividad fina sin Zone.js, lo que hace la detección de cambios predecible.
    • Reactive Forms con tipado estricto (FormControl<string>, FormGroup<{ email: FormControl<string> }>), detectan incompatibilidades en compilación.

    Patrón recomendado

    El componente actúa como presentador; la lógica y las transformaciones residen en servicios inyectados con inject(). Evita colocar reglas de negocio dentro del template o del componente.

    Ejemplo de estructura mínima

    • registration.component.ts (Standalone, Signals para estado local)
    • registration.service.ts (transformaciones, llamadas API)
    • schema/registration.schema.ts (esquema Zod, ver sección siguiente)

    Si quieres dominar esta arquitectura de base y aprender patrones aplicados con Angular 22, apúntate al curso Angular Moderno: El curso definitivo.

    Zod: la fuente de la verdad para validación y tipos

    La duplicidad de reglas (validators en frontend, validadores en backend, DTOs sueltos) es la causa número uno de bugs en formularios complejos. Zod soluciona esto al declarar esquemas que sirven como contrato único.

    Flujo práctico

    1. Declara el esquema en un archivo compartido (si usas monorepo o paquete npm interno).
    2. Infieres tipos con z.infer<> para usar en servicios y repositorios.
    3. Conecta un validador que mapea schema.safeParse(form.value) a errores del FormGroup.

    Ejemplo (schema)

    // registration.schema.ts
    import { z } from "zod";
    
    export const RegistrationSchema = z.object({
      email: z.string().email("Email inválido"),
      password: z.string().min(8, "Mínimo 8 caracteres"),
      acceptTerms: z.literal(true, { errorMap: () => ({ message: "Debes aceptar los términos" }) })
    });
    
    export type Registration = z.infer<typeof RegistrationSchema>;
    

    Mapeo simple de errores a controles

    – Ejecuta const result = RegistrationSchema.safeParse(formGroup.value).

    – Si !result.success, itera result.error.formErrors.fieldErrors y asigna control.setErrors({ zod: mensaje }).

    Ventaja: el mismo esquema puede usarse en backend Node.js, evitando divergencias. Además TipScript siempre estará sincronizado con la validación.

    Aprende integraciones, refinements y transformaciones avanzadas con Zod en el curso Zod: Validación y Transformación de datos con TypeScript.

    Tests que importan: Jest + Angular Testing Library

    Los tests deben medir la experiencia del usuario, no detalles internos. Eso implica dos decisiones técnicas:

    1. Migrar a Jest por velocidad y fiabilidad en CI (usa jest-preset-angular).
    2. Usar Angular Testing Library para consultas semánticas y eventos reales (userEvent).

    Ejemplo de test resiliente

    it("muestra error cuando el email es inválido", async () => {
      render(RegistrationFormComponent);
      await userEvent.type(screen.getByLabelText("Email"), "no-es-email");
      await userEvent.tab();
      expect(screen.getByText("Email inválido")).toBeInTheDocument();
    });
    

    Razón: este test no depende de component.isSubmitted ni de variables privadas. Si cambias la implementación interna, mientras el comportamiento visible sea el mismo, el test sigue válido.

    Configuración mínima

    • Instala: npm i -D jest @types/jest jest-preset-angular @testing-library/angular @testing-library/user-event.
    • Ajusta jest.config.ts y prepara setup-jest.ts para Angular.
    • Mantén tests rápidos, aislados y con pocos mocks; mockea solo dependencias externas (APIs, storage).

    Si quieres configurar Jest, migrar desde Karma y escribir tests que sobrevivan a refactors, revisa Testing en Angular con Jest y Testing Library.

    Arquitectura y criterio: por qué esto funciona

    Las tres capas forman un sistema coherente:

    • Angular 22 define la superficie y el flujo de datos con tipos seguros.
    • Zod centraliza reglas de negocio y mantiene tipos sincronizados entre cliente y servidor.
    • Jest + Testing Library validan el comportamiento visible del usuario, no la implementación.

    Beneficios reales: menos bugs por desincronía, tests más estables, tiempo en CI reducido y una base de código que soporta refactors sin miedo. No es moda; es ingeniería.

    Si quieres implementar este stack de forma práctica y con ejemplos reales, empieza por los tres cursos enlazados arriba: aprendizaje dirigido, ejercicios aplicados y casos reales que aceleran pasar de teoría a producción.

    FAQ

    ¿Por qué usar Zod en lugar de validadores sueltos?

    Porque Zod permite declarar esquemas TypeScript-first que sirven como contrato único entre cliente y servidor, evitando duplicidad de reglas y divergencias que generan bugs en formularios complejos.

    ¿Qué aporta Signals frente a la reactividad clásica de Angular?

    Signals ofrece reactividad fina sin Zone.js, lo que hace la detección de cambios más predecible y permite optimizar renders sin depender del sistema de zones tradicional.

    ¿Por qué migrar a Jest desde Karma?

    Jest es más rápido y fiable en CI; combinado con jest-preset-angular reduce tiempos y fragilidad en pipelines de integración continua.

    ¿Cómo mapear errores de Zod a un FormGroup?

    Ejecuta RegistrationSchema.safeParse(formGroup.value). Si el parse falla, itera result.error.formErrors.fieldErrors y asigna errores a cada control con control.setErrors({ zod: mensaje }).

    ¿Qué pruebas debe cubrir Testing Library?

    Pruebas que midan la experiencia del usuario: consultas semánticas, interacción real con userEvent y aserciones sobre el comportamiento visible, no sobre variables internas.

    ¿Dónde colocar la lógica de negocio en esta arquitectura?

    La lógica y transformaciones deben residir en servicios inyectados (por ejemplo en registration.service.ts), mientras el componente actúa como presentador y coordina el estado local.

  • Cómo acelerar las entregas de los desarrolladores sénior sin comprometer calidad

    Cómo acelerar las entregas de los desarrolladores sénior sin comprometer calidad

    ¿Por qué los desarrolladores sénior siguen con las entregas lentas (y cómo evitarlo)?

    Tiempo estimado de lectura: 4 min

    • La experiencia introduce sesgos de anticipación: sénior suelen prever fallos y eso añade tiempo (sobreingeniería, refactorización y parálisis por análisis).
    • La solución son procesos y límites: ADRs, timebox, DoD estricta, backlogs separados y automatización reducen la fricción.
    • Automatización y métricas hacen que la rapidez sea sostenible: linters, CI, IA en la primera revisión, PR size y SLAs concretos aceleran sin sacrificar calidad.
    • Cultura y liderazgo determinan la efectividad: valorar decisiones rápidas y reversibles y responsabilizar al equipo sobre la deuda técnica convierte criterio en velocidad.

    ¿Por qué los desarrolladores sénior siguen con las entregas lentas (y cómo evitarlo)? La pregunta duele en equipos que necesitan velocidad sin sacrificar calidad. La respuesta no es moralizante: no es pereza ni incompetencia. Es la suma de experiencia, riesgo y estructuras de trabajo que no alinean incentivos. Si quieres acelerar sin quemar a tu gente ni a tu producto, esto es lo que realmente pasa —y qué hacer al respecto.

    Resumen rápido (lectores con prisa)

    ADRs (Architecture Decision Records): documento para registrar decisiones de arquitectura con fecha y contexto. Útil cuando la decisión puede revertirse o necesitar revisión.

    YAGNI: principio que evita construir soluciones para escenarios hipotéticos; aplicar en MVPs y experimentos.

    Timebox: límite temporal corto (48–72 horas) para decidir; si no hay consenso, define un decisor y registra la decisión en un ADR.

    Automatización + métricas: linters, CI, IA en revisiones iniciales, PR size y SLAs para convertir criterio en velocidad mantenible.

    Patrones que explican la lentitud

    1) Sobreingeniería: el futuro que nadie pidió

    Problema: un sénior tiende a diseñar soluciones que cubran escenarios hipotéticos —microservicios, abstracciones genéricas, event sourcing— para necesidades que hoy son triviales. Violación clásica de YAGNI (Martin Fowler).

    Qué hacer:

    • Define guardrails de arquitectura por contexto (MVP vs core). Un diagrama simple que diga “MVP = soluciones directas” evita debates infinitos.
    • Usa ADRs (Architecture Decision Records) para decisiones importantes y ponles plazo. Recurso.
    • Prioriza experimentos pequeños y medibles antes de diseñar grandes infraestructuras.

    Resultado esperado: menos tiempo invertido en abstracciones sin validación y más entregas que generan aprendizaje real.

    2) Refactorización expansiva: el “ya que estoy aquí”

    Problema: entrar a cambiar una línea y salir con cinco módulos reescritos. La intención es buena, pero el coste de oportunidad es alto.

    Qué hacer:

    • Separa deuda técnica del desarrollo funcional. Crea un backlog de deuda con criterios claros de prioridad y presupuestos de tiempo.
    • Impon una DoD (Definition of Done) estricta por ticket: lo que no está en la DoD no se toca.
    • Introduce reglas de “pequeñas mejoras” (máx. X archivos o Y líneas por PR) o tickets explícitos para refactors grandes.

    Resultado esperado: PRs más pequeñas, revisiones más rápidas y menos regresiones por cambios colaterales.

    3) Parálisis por análisis: debatir hasta el infinito

    Problema: múltiples opciones válidas y ninguna decisión. El coste: semanas de indecisión.

    Qué hacer:

    • Timebox: 48–72 horas para llegar a una decisión técnica informada. Si no hay consenso, define un decisor (Tech Lead o rota).
    • Documenta la decisión en un ADR y planifica re-evaluación tras N sprints.
    • Fomenta prototipos rápidos (spikes) con criterios claros de éxito para reducir la ambigüedad.

    Resultado esperado: decisiones más rápidas, mejores retrospectivas y menos “design by committee”.

    Tácticas operativas que sí funcionan

    Estas prácticas convierten criterio técnico en velocidad real sin sacrificar calidad.

    • Automatiza la fricción: linters, formatos automáticos y análisis estático en CI. Que la máquina rechace fallos triviales.
    • Primer revisión automatizada con IA: un agente (bien entrenado y con límites) puede hacer la primera pasada de code review para detectar complejidad innecesaria. Orquestación de flujos con herramientas como n8n facilita integrarlo en pipelines.
    • Métricas visibles: PR size, lead time, cycle time y tasa de rework (DORA metrics). Google DevOps tiene material útil.
    • Límites de PR y SLA de revisión: por ejemplo, PRs < 400 líneas y revisión en 24–48 horas. Esto fuerza pequeños incrementos.
    • Feature flags y despliegues canary: permiten entregar rápido sin riesgos mayores.
    • Pares en diseño crítico: pairing para decisiones de alto impacto reduce la necesidad de amplias revisiones posteriores.

    Cultura y liderazgo: la palanca que manda

    La técnica sola no basta. Cambiar la forma en que los sénior usan su criterio exige liderazgo que:

    • Valore decisiones rápidas y reversibles.
    • Recompense reducir el tiempo hasta el feedback real del cliente.
    • Promueva responsabilidad compartida sobre la deuda técnica (no que un solo “ángel” la arregle).

    Un buen indicador es si el equipo prioriza entregar aprendizaje al usuario sobre pulir arquitectura invisible.

    Conclusión práctica

    Los desarrolladores sénior no son el problema; son una solución mal encuadrada. Convertir su criterio en velocidad exige:

    • Reglas claras (DoD, backlogs separados).
    • Procesos que forcen decisiones (ADRs + timebox).
    • Automatización para reducir trabajo manual (linters, IA en CI, n8n).
    • Métricas y límites operativos (PR size, SLAs).

    No pidas a los sénior que “vayan más rápido”. Diseña el contexto donde su experiencia se traduce en decisiones efectivas y entregas constantes. Eso sí acelera —y a la larga, es lo que mantiene el código vivo sin quemar al equipo.

    FAQ

     

    ¿Qué es un ADR y para qué sirve?

    Un ADR (Architecture Decision Record) es un documento que registra una decisión arquitectónica, su contexto y sus consecuencias. Sirve para dejar rastro, facilitar re-evaluaciones y evitar repetir debates históricos.

    ¿Cómo evitar la sobreingeniería en un equipo sénior?

    Define guardrails claros (MVP vs core), aplica YAGNI en el contexto del producto y usa ADRs con fecha límite. Prioriza experimentos pequeños y medibles antes de invertir en infraestructuras grandes.

    ¿Qué límites prácticos poner en los PRs?

    Ejemplos prácticos: PRs < 400 líneas, límite de X archivos o Y funciones para pequeñas mejoras, y tickets dedicados para refactors mayores. Acompáñalo con SLA de revisión (24–48 horas).

    ¿Cuándo usar timebox para decisiones técnicas?

    Usa timebox (48–72 horas) cuando hay múltiples opciones válidas y la decisión bloquea progreso. Si no hay consenso, designa un decisor y registra la decisión en un ADR para re-evaluación posterior.

    ¿Qué métricas son útiles para medir velocidad sin sacrificar calidad?

    Métricas útiles incluyen PR size, lead time, cycle time y tasa de rework. Estas, combinadas con controles automáticos en CI, permiten actuar sobre cuellos de botella sin comprometer calidad.

    ¿Cómo integrar IA en la revisión de código sin depender exclusivamente de ella?

    Usa IA para la primera pasada: detectar complejidad innecesaria, problemas de estilo y patrones riesgosos. Mantén revisión humana para decisiones arquitectónicas y contextuales, y establece límites claros al alcance del agente.

  • Cómo Spec-First Optimiza el Desarrollo de Software con IA

    Cómo Spec-First Optimiza el Desarrollo de Software con IA

    Por qué Spec-First cambió mi forma de programar con IA (y por qué debería cambiar la tuya)

    Tiempo estimado de lectura: 4 min

    • Spec-First reduce suposiciones del modelo al definir contratos antes de pedir implementación.
    • Escribir tipos y casos de error toma minutos; arreglar código generado con suposiciones incorrectas puede costar días.
    • Combinar Spec-First con TDD convierte especificaciones en tests ejecutables y acelera desarrollo mantenible.
    • Aplica Spec-First en sistemas críticos, APIs públicas y módulos que deben escalar; evita para prototipos one-off.

    Por qué Spec-First cambió mi forma de programar con IA (y por qué debería cambiar la tuya). Poca gente habla de esto después del entusiasmo inicial. Descubrí algo curioso: no era la IA la que fallaba, era el orden de mis decisiones.

    La primera vez que pides código a un asistente te sientes en una peli de ciencia ficción. La décima vez estás peleando con alucinaciones, nombres mal elegidos y lógica que solo funciona en el mundo ideal del modelo. Spec-First rompió esa dinámica.

    Resumen rápido (lectores con prisa)

    Spec-First: escribe el contrato (tipos, entradas/salidas, casos límite) antes de pedir implementación. Reduce suposiciones del modelo y convierte especificaciones en tests ejecutables. Útil para código mantenible y APIs, menos para prototipos one-off.

    El coste real del Prompt-Driven Development

    El flujo habitual es: pides, pegas, arreglas. Repetir. Para prototipos funciona. Para software que vive y crece, no.

    • El modelo no conoce tu arquitectura.
    • No sabe tus convenciones ni decisiones pasadas.
    • No respeta tus límites de efectos secundarios ni tus políticas de error.

    Resultado: módulos que compilan pero no encajan. Bugs lógicos distribuidos. Revisiones interminables.

    Spec-First no te da respuesta mágica. Te devuelve tiempo y predictibilidad.

    Qué debe contener una spec si vas a usar IA

    No necesitas un documento de 30 páginas. Necesitas lo mínimo imprescindible para quitarle decisiones al modelo:

    Tipos e interfaces

    define entradas y salidas antes de pedir lógica.

    interface CreateUser { email: string; name?: string }
    type Result<T> = { ok: true; value: T } | { ok: false; error: string }

    Casos límite

    nulos, dominios bloqueados, fallos de red, retries, timeouts.

    Comportamiento determinista

    funciones puras, sin efectos laterales, o explícitamente con side effects autorizados.

    Restricciones de integración

    versiones de librería, patrones prohibidos, dónde puede tocar la base de datos.

    Escribir esto toma minutos. Arreglar un desastre generado por IA puede costarte días.

    Spec-First + TDD = velocidad real

    Si ya definiste tipos y casos de error, pedirle al modelo que genere tests primero es natural. Los tests pasan a ser la especificación ejecutable.

    Flujo práctico:

    • 1) Escribe tipos y contratos.
    • 2) Genera tests unitarios con la IA.
    • 3) Pide la implementación hasta que los tests pasen.

    La diferencia: pasas menos tiempo adivinando por qué algo falla y más en ajustar diseño.

    Ejemplo rápido (mental, no código largo)

    En vez de: “Crea función que valide emails”, di:

    “Función pura que recibe string, valida email corporativo (rechaza gmail.com, hotmail.com), retorna Result<Email, ValidationError>, cero excepciones, sin llamadas externas.”

    Esa frase evita que el modelo haga lo que le da la gana y te devuelve algo integrable.

    Cuándo aplicar Spec-First (y cuándo no)

    No es una religión. Úsalo cuando importe la mantenibilidad y la integración:

    • Sistemas críticos, core domain, APIs públicas.
    • Equipos distribuidos con contratos firmes.
    • Proyectos que deben escalar o durar.

    No lo emplees para scripts one-off o prototipos exploratorios donde la velocidad de concepto importa más que la calidad.

    Cambia tu rol profesional: de mecanógrafo a director de orquesta

    La IA está comoditizando la escritura de código. El valor real se desplaza hacia quien define qué construir y por qué. Spec-First es el instrumento para ejercer ese criterio sin perder velocidad.

    Tú no vas a competir con la IA en velocidad de tecleo. Vas a competir en claridad de intención, disciplina arquitectónica y capacidad de traducir requisitos imprecisos en contratos firmes.

    Cómo empezar hoy (3 pasos prácticos)

    1. Antes de pedir código, escribe los tipos. Solo eso.
    2. Genera tests unitarios desde esa spec.
    3. Pide la implementación, haz que los tests pasen.

    Hazlo en el siguiente ticket que abras. No hace falta cambiar todo tu flujo; prueba en un módulo nuevo y compara el resultado.

    Haz esto ahora: la próxima vez que pidas una función al asistente, detente 30 segundos y define solo los tipos. Luego vuelve y genera los tests. Verás la diferencia.

    Esto no acaba aquí: si quieres, puedo convertir tu próxima descripción vaga en una spec lista para usar con cualquier LLM.

    Este artículo trata sobre IA aplicada y flujos de trabajo con modelos, por lo que puede interesarte explorar recursos prácticos y experimentos en Dominicode Labs. Es un complemento natural para probar especificaciones y pipelines de tests en prototipos controlados.

    FAQ

     

     

    ¿Qué es Spec-First?

    Es una práctica que prioriza escribir contratos (tipos, entradas/salidas, casos límite) antes de solicitar la implementación a un asistente IA o a un desarrollador.

     

    ¿Cuándo debo usar Spec-First?

    Cuando la mantenibilidad, integraciones o el dominio crítico importen: APIs públicas, core domain y equipos distribuidos. No es necesario para scripts one-off o experimentos rápidos.

     

    ¿Spec-First reemplaza al TDD?

    No lo reemplaza; se complementan. Spec-First define contratos y TDD convierte esos contratos en tests ejecutables que guían la implementación.

     

    ¿Cuánto tiempo toma crear una spec básica?

    En muchos casos, minutos. Definir tipos y casos límite mínimos suele ser suficiente para reducir suposiciones del modelo y evitar reescrituras costosas.

     

    ¿Es útil para prototipos rápidos?

    No siempre. Para prototipos donde la velocidad de concepto importa más que la calidad, puedes omitirlo. Para piezas que deban mantenerse o integrarse, sí.

     

    ¿Qué incluye una spec mínima?

    Los tipos e interfaces de entradas/salidas, casos límite (nulos, dominios bloqueados, fallos de red), comportamiento determinista (funciones puras o efectos explícitos) y restricciones de integración (versiones, patrones prohibidos).

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

    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 actúa como contrato para agentes IA: reduce ambigüedad y alucinaciones.
    • Proveer tipos reales al modelo mejora la integración: interfaces y uniones limitan las soluciones válidas.
    • Prácticas recomendadas: evita any, usa uniones discriminadas, y documenta intenciones clave con JSDoc.
    • Aplica en sistemas críticos: APIs públicas, lógica financiera, workflows y automations en producción.

    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:

    • Tipos explícitos delimitan estados válidos ('pending' | 'completed' | 'failed').
    • Relaciones entre interfaces exponen dependencias y claves foráneas.
    • Uniones discriminadas fuerzan el manejo correcto de errores y casos límite.

    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

    ¿Por qué usar tipos en lugar de solo lenguaje natural?

    Porque los tipos actúan como restricciones matemáticas que reducen el espacio de soluciones válidas. Forzan al agente a no inventar propiedades o estados que no existen.

    ¿Qué tipos debo compartir primero?

    Empieza por los tipos que definen estados y contratos públicos: DTOs, modelos de entidad y tipos de retorno de API. Luego añade relaciones y uniones discriminadas.

    ¿Cómo evito que el agente ignore los tipos?

    Entrega los tipos en el contexto del prompt y pide explícitamente que la implementación cumpla las firmas. Usa ejemplos de tests o resultados (Result/Either) para que el agente devuelva formas esperadas.

    ¿Qué herramientas facilitan este flujo?

    Editores y orquestadores que soportan contexto tipado: Cursor, GitHub Copilot y plataformas de orquestación como n8n.

    ¿Es útil en prototipos rápidos?

    En prototipos muy tempranos donde los modelos de datos cambian constantemente, puede ser una carga. Para prototipos más avanzados o cuando la estructura es estable, sí acelera la integración.

    ¿Cómo manejar cambios de tipos en producción?

    Versiona tus tipos y mantén contratos retrocompatibles siempre que sea posible. Añade migraciones y tests que verifiquen transiciones permitidas entre versiones.

    ¿Debo incluir ejemplos de datos junto a los tipos?

    Sí. Ejemplos concretos ayudan al agente a mapear tipos a estructuras reales y generan pruebas útiles para validar implementaciones.

  • Claude Opus 4.8: novedades para desarrolladores (Claude Code, Effort Control y más)

    Claude Opus 4.8: novedades para desarrolladores (Claude Code, Effort Control y más)

    Anthropic acaba de lanzar Claude Opus 4.8, y ellos mismos lo describen como una mejora “modesta” sobre Opus 4.7. Es una descripción honesta, pero engañosa: las mejoras de calidad de vida son justo las que más se notan cuando trabajas con esto todos los días.

    En este artículo voy directo a lo que importa si programas: qué cambia de verdad, qué es marketing, y cómo encaja en un flujo de trabajo serio.

    Qué es Opus 4.8 en una frase

    Opus 4.8 reemplaza a 4.7 dentro de la misma familia de modelos. Mismo precio, pero más fiable y con mejor criterio cuando trabaja en modo agente. El identificador del modelo en la API es claude-opus-4-8.

    La jugada interesante de este lanzamiento no es el modelo en solitario, sino lo que Anthropic construyó alrededor de él. Vamos por partes.

    1. Dynamic Workflows en Claude Code

    Esta es la novedad grande, y de momento está en research preview.

    Claude Code ahora puede planificar una tarea de gran tamaño, lanzar cientos de subagentes en paralelo dentro de una misma sesión, verificar sus propios resultados y recién entonces reportarte. El ejemplo que pone Anthropic es ambicioso: migraciones de código a escala de cientos de miles de líneas, desde el arranque hasta el merge, usando tu propia suite de tests como criterio de aceptación.

    El detalle a tener en cuenta: esta capacidad está disponible en los planes Enterprise, Team y Max. Si estás en otro plan, no la tendrás todavía.

    Para quien delega tareas largas, este es el cambio con más potencial a medio plazo.

    2. Effort Control: tú decides cuánto piensa

    Ahora puedes elegir el nivel de “esfuerzo” del modelo desde un control junto al selector de modelo.

    • Más esfuerzo: razona más profundo y entrega mejores respuestas.
    • Menos esfuerzo: responde más rápido y consume menos de tus límites de uso.

    Por defecto viene en high. Por encima tienes la opción “extra” —que en Claude Code corresponde a xhigh— y “max”. La recomendación oficial es usar “extra” para tareas difíciles y flujos asíncronos largos. A diferencia de Dynamic Workflows, Effort Control está disponible en todos los planes.

    3. Un modelo más honesto (menos bugs silenciosos)

    Esta es, para mí, la mejora que más se nota en el día a día del código.

    Anthropic entrenó el modelo para que no cante victoria sin evidencia. El dato concreto: Opus 4.8 tiene aproximadamente cuatro veces menos probabilidad que su predecesor de dejar pasar un fallo —en código que él mismo escribió— sin señalártelo.

    Traducido: menos “ya está listo” cuando en realidad no lo está. Si delegas tramos grandes de trabajo, esa honestidad te ahorra horas de revisión y depuración.

    Novedad para quien construye sobre la API

    Si desarrollas agentes sobre la API, hay un cambio silencioso pero práctico: la Messages API ahora acepta entradas de tipo system dentro del array de mensajes. Esto te permite actualizar las instrucciones de Claude a mitad de una tarea —permisos, presupuesto de tokens, contexto del entorno— sin romper el prompt cache ni tener que colarlo como un turno de usuario. Para harnesses de agentes que corren de forma autónoma, limpia bastante la arquitectura.

    Precios y velocidad

    Opus 4.8 mantiene el precio de 4.7:

    • Modo regular: 5 USD por millón de tokens de entrada, 25 USD por millón de salida.
    • Modo fast: 10 USD por millón de entrada, 50 USD por millón de salida, a 2,5× la velocidad. Anthropic indica que este modo fast es alrededor de tres veces más barato que en modelos anteriores.

    En resumen: mejor modelo, mismo costo. Difícil quejarse de eso.

    Mi opinión: no es un salto generacional, y está bien

    Seamos claros: Opus 4.8 no te va a volar la cabeza. Es una mejora de calidad de vida, no un cambio de generación. Pero precisamente por eso se siente: el mejor criterio agéntico y la honestidad encajan a la perfección con un flujo de Spec-Driven Development (SDD).

    Si el modelo respeta mejor el spec, se atreve a frenar cuando el plan no cuadra y no te miente con un “terminé” falso, entonces puedes delegar tramos más grandes con menos revisión manual. Esa es la dirección que importa: el desarrollador como director de la IA, no como su competidor.

    Conclusión

    Claude Opus 4.8 no es un titular espectacular, pero es una actualización sólida para quien vive dentro de Claude Code. Dynamic Workflows y la honestidad extra del modelo son lo que de verdad vale la pena, y el Effort Control le da un control fino que se agradece.

    Si trabajas con SDD y Claude Code, este lanzamiento te toca de lleno. En las próximas semanas haré un experimento práctico combinando Dynamic Workflows con specs bien definidas; lo compartiré por aquí.

    ¿Ya probaste Opus 4.8? ¿Qué tarea grande le tirarías primero a los Dynamic Workflows? Cuéntame en los comentarios.

  • Construyendo Agentes Rápidos con TypeScript y Vercel AI SDK

    Construyendo Agentes Rápidos con TypeScript y Vercel AI SDK

    TypeScript + Vercel AI SDK: la combinación que uso para construir agentes rápido

    Tiempo estimado de lectura: 4 min

    • Tipado + validación: TypeScript en la superficie y Zod en runtime reducen errores silenciosos y permiten refactors seguros.
    • API unificada: Vercel AI SDK conecta proveedores y ofrece streaming y herramientas tipadas.
    • Extracción y control: generateObject y esquemas evitan ingeniería de prompt frágil y JSON truncado.
    • UX y operaciones: streamText mejora la percepción de latencia; métricas y circuit breakers mantienen robustez en producción.

    TypeScript + Vercel AI SDK: la combinación que uso para construir agentes rápido. Si vas a poner agentes en producción, necesitas que la capa que conecta al LLM con tus herramientas sea predecible, tipada y validada desde el primer día. Esa combinación reduce errores silenciosos, acelera refactors y convierte promesas estocásticas en contratos verificables.

    Resumen rápido (lectores con prisa)

    TypeScript para tipado estático, Zod para validación en runtime y Vercel AI SDK como API unificada. Juntos: herramientas tipadas, extracción estructurada (generateObject), y streaming (streamText) para agentes más seguros y previsibles.

    TypeScript + Vercel AI SDK: por qué funciona para agentes rápidos

    Tres problemas recurrentes al construir agentes:

    1. El LLM alucina parámetros para las herramientas (tool calls)

    Los modelos pueden generar parámetros inválidos o inventados para llamadas a herramientas, lo que puede llevar a ejecuciones peligrosas si no se validan antes.

    2. Las respuestas JSON vienen envueltas en markdown o truncadas

    Solemos ver JSON con backticks, texto adicional o respuestas incompletas que complican el parsing confiable.

    3. Cambios en la API del proveedor rompen integraciones silenciosamente

    Actualizar modelos o proveedores puede introducir cambios incompatibles si no hay contratos y pruebas robustas.

    La solución práctica es simple: tipos en la superficie (TypeScript), contratos ejecutables (Zod) y una API que integra ambas cosas (Vercel AI SDK). Beneficios concretos:

    • Autocompletado que evita buscar docs.
    • Tool calls que no se ejecutan si los datos no validan.
    • Extracción de objetos estructurados (generateObject) sin ingeniería de prompt frágil.
    • Streaming nativo (streamText) para UX reactiva.

    Tool calls tipados: la barrera que evita ejecuciones peligrosas

    Definir herramientas con esquemas evita que el agente ejecute acciones con parámetros inventados. Ejemplo:

    import { tool } from 'ai';
    import { z } from 'zod';
    
    const searchOrders = tool({
      description: 'Busca pedidos por ID de cliente',
      parameters: z.object({
        customerId: z.string().uuid(),
        status: z.enum(['pending','shipped','delivered']).optional(),
      }),
      execute: async ({ customerId, status }) => {
        return queryOrdersDatabase({ customerId, status });
      },
    });
    

    Si el LLM devuelve un customerId inválido, Zod lo rechazará antes de llamar a execute. Resultado: menos excepciones en la base de datos y trazabilidad clara del fallo (prompt → validación → rechazo).

    generateObject: extracción fiable de datos estructurados

    generateObject obliga al modelo a respetar un esquema y te devuelve un objeto tipado sin hacer JSON.parse() manual. Ejemplo práctico:

    import { generateObject } from 'ai';
    import { openai } from '@ai-sdk/openai';
    import { z } from 'zod';
    
    const schema = z.object({
      sentiment: z.enum(['positive','neutral','negative']),
      confidence: z.number().min(0).max(1),
      topics: z.array(z.string()).max(5)
    });
    
    const { object } = await generateObject({
      model: openai('gpt-4o'),
      schema,
      prompt: 'Analiza la reseña y devuelve sentiment, confidence y topics.'
    });
    
    // object ya está tipado según schema
    

    Esto reduce la ingeniería de prompts (“Devuelve SOLO JSON”) y aumenta la tasa de respuestas utilizables desde el primer intento.

    streamText: UX que comunica progreso y permite pasos intermedios

    Los agentes suelen ejecutar varias herramientas en cadena. streamText permite emitir texto progresivo y reflejar estados intermedios (p. ej. “consultando base de datos…”) en la UI sin arquitectura adicional:

    • Emite tokens progresivamente al frontend.
    • Reporta eventos de invocation/execute de herramientas.
    • Funciona tanto en Server (Next.js) como en cliente con hooks (useChat).

    Esto mejora la percepción de latencia y permite interacciones más naturales con agentes multi‑paso.

    Integración práctica y operaciones en producción

    Patrón recomendado

    1. Diseña esquemas Zod como fuente única de verdad.
    2. Expón el esquema (o ejemplo) en el prompt para guiar al LLM.
    3. Usa safeParse() para reintentos y autocorrección de prompts; usa parse() para endpoints que deben fallar rápido.
    4. Loguea prompt, raw response y error de Zod (flatten) para trazabilidad.

    Medidas operativas

    • Métricas: tasa de validación fallida, latencia media por herramienta, reintentos por prompt.
    • Retries limitados con backoff y contador de intentos (p. ej. 2 reintentos de autocorrección antes de degradar a humano).
    • Circuit breaker para evitar invocar herramientas costosas si la validación falla en cascada.

    Limitaciones y decisions trade‑offs

    • No eliminas la estocasticidad del LLM; la controlas. Algunos casos requerirán supervisión humana.
    • generateObject y Structured Outputs reducen errores de formato, pero no sustituyen la validación semántica (p. ej. números positivos). Zod sigue siendo necesaria.
    • Tipar desde el día 0 impone disciplina, pero acelera onboarding y refactors.

    Conclusión

    TypeScript + Vercel AI SDK: la combinación que uso para construir agentes rápido no es un truco de marketing. Es una estrategia concreta: tipos para detectar cambios, Zod para validar en runtime, y un SDK que une proveedores, streaming y herramientas tipadas. Si tu objetivo es desplegar agentes que actúen sobre sistemas reales—bases de datos, pedidos, o infraestructuras—esta pila reduce fallos silenciosos y convierte iteración rápida en ingeniería sostenible.

    Para equipos que exploran automatización y agentes como flujo de trabajo productivo, una guía práctica y recursos adicionales están disponibles en Dominicode Labs. Es una continuación lógica para quienes quieren aterrizar estas prácticas en sistemas reales.

    FAQ

    ¿Por qué combinar TypeScript con Zod y un SDK como Vercel AI SDK?

    TypeScript aporta seguridad estática y autocompletado; Zod proporciona validación en runtime; y Vercel AI SDK unifica la interacción con proveedores, streaming y herramientas tipadas. La combinación reduce errores silenciosos y facilita refactors.

    ¿Cómo evitan las herramientas tipadas ejecuciones peligrosas?

    Al definir parámetros con esquemas Zod, cualquier dato que no valide se rechaza antes de ejecutar la función execute, evitando operaciones con parámetros inventados o inválidos.

    ¿Qué ventaja ofrece generateObject frente a parsear JSON manualmente?

    generateObject obliga al modelo a respetar un esquema y devuelve un objeto ya tipado, evitando la ingeniería de prompt para forzar JSON y reduciendo errores por markdown, texto adicional o truncado.

    ¿Cuándo debo usar streamText?

    Cuando quieras mejorar la UX en interacciones multi‑paso: emitir tokens progresivamente, mostrar estados intermedios y reportar eventos de invocation/execute sin añadir complejidad arquitectónica.

    ¿Qué métricas operativas son críticas?

    Métricas como tasa de validación fallida, latencia media por herramienta y reintentos por prompt son esenciales para monitorear la salud y eficacia del agente.

    ¿Cuáles son las limitaciones principales de esta pila?

    No elimina la estocasticidad del LLM; solo la controla. También requiere validación semántica adicional (p. ej. asegurar números positivos). Tipar desde el día 0 impone disciplina, aunque acelera onboarding y refactors.

  • Adopta TDD para implementar pruebas efectivas con agentes de IA

    Adopta TDD para implementar pruebas efectivas con agentes de IA

    Testing en la era de los agentes — TDD + agents, qué tests escribir tú vs cuáles el agente, snapshot testing inteligente

    Tiempo estimado de lectura: 5 min

    Ideas clave:

    • Usa tests como especificación (Test-Driven Prompting) y pide al agente implementar hasta que el test pase.
    • Los humanos deben definir contratos y tests críticos; los agentes pueden generar unit tests, edge cases y boilerplate bajo supervisión.
    • Cambia snapshots textuales por evaluaciones semánticas (LLM-judge) para reducir fragilidad.
    • Implementa un pipeline two-speed con sandboxes efímeros y telemetría sobre prompts y evaluaciones.

    Tabla de contenidos

    Introducción

    Testing en la era de los agentes — TDD + agents, qué tests escribir tú vs cuáles el agente, snapshot testing inteligente debe aparecer en tu playbook desde hoy. Si vas a dejar que un agente (Claude Code, Aider, Cursor u otros) escriba código en tu repo, tienes que reordenar qué pruebas son autoritativas, cuáles automatizas y cómo evitas cobertura falsa.

    Aquí está la estrategia práctica y accionable: cómo usar TDD como especificación, qué pruebas deben ser humanas, cuáles delegar a la IA, y cómo evolucionar los snapshots desde diffs frágiles a evaluaciones semánticas.

    Resumen rápido (lectores con prisa)

    Test-Driven Prompting aplica TDD a agentes: escribe el test como especificación y pide al agente implementar hasta que pase. Usa humanos para contratos, integración crítica y regresiones reales; delega unit tests deterministas y generación de edge cases al agente. Reemplaza snapshots textuales por una evaluación semántica (LLM-judge) que decide si un cambio es cosmético o funcional.

    Test-Driven Prompting: TDD + agents, qué tests escribir tú vs cuáles el agente

    Test-Driven Prompting es TDD adaptado a agentes. Escribes el test primero —no como un ejercicio de documentación, sino como la especificación no ambigua— y pides al agente que implemente hasta que el test pase. El test se convierte en el prompt más estricto que existe.

    Beneficios inmediatos:

    • El agente no improvisa requisitos; el test define el contrato.
    • Evitas cambios colaterales porque la suite actúa como guardrail.
    • La revisión humana se traslada de “¿funciona?” a “¿es esto sostenible y seguro?”.

    Pero atención: si el agente escribe la implementación y el test, obtendrás tautologías. Por eso la división de responsabilidades es crítica.

    División práctica: qué escribe el humano y qué el agente

    Lo que debe escribir el humano (no delegues)

    • Tests de integración críticos: pagos, auth, sincronización entre servicios. Requieren contexto de negocio y pruebas contra fallos reales.
    • Flujos E2E y guiones de usuario (Playwright, Cypress): definen la experiencia que no puede ser inferida por el agente. Playwright / Cypress
    • Tests de regresión con historial real: errores de producción documentados como tests que no pueden ser reinterpretados.
    • Setup de entornos y fixtures confiables: seeds de DB, contratos de mock globales.

    Lo que el agente puede generar (con supervisión)

    • Tests unitarios para funciones puras: transformaciones deterministas, utilidades, algoritmos puros.
    • Generación de edge cases y fuzzing estructurado: inputs nulos, límites, arrays extremos.
    • Boilerplate de mocks simples y factories (bajo reglas estrictas definidas por humanos).

    Pauta de revisión

    Cualquier test con mocking complejo (p. ej. jest.mock con comportamiento dinámico) debe pasar revisión manual antes de merge. Los LLMs tienden a “alucinar” APIs de mocking o a asumir comportamiento de librerías.

    Snapshot testing inteligente: de fragilidad a semántica

    Cómo funciona

    Los snapshots textuales mueren rápidos en repos de ritmo alto. La alternativa es snapshot testing inteligente: comparar semánticamente en lugar de por texto.

    Cómo funciona:

    • Generas snapshot tradicional (DOM/JSON).
    • Si cambia, un módulo de evaluación semántica (LLM-as-a-Judge) recibe: snapshot antiguo, snapshot nuevo y una rúbrica.
    • El modelo decide si el cambio es cosmético (aprobable) o funcional (falla y requiere revisión).

    Aplicaciones

    • UI: detectar si un botón cambió de estilo (aprobable) vs desapareció el control de envío (fallo).
    • APIs: admitir la adición de campos no utilizados por clientes y bloquear cambios en campos requeridos.

    Herramientas/ideas

    Construir un servicio interno que use un modelo de evaluación (ej. GPT-4o / Claude avanzado) y registre justificaciones estructuradas para auditoría.

    Pipeline recomendado y consideraciones operativas

    1. Golden Dataset de tests

    Golden Dataset de tests: 20–50 casos representativos versionados en Git. Sirve como baseline para evaluar cambios de spec.

    2. Two-speed CI

    • Cada PR: ejecución determinista rápida (linters, unit tests generados por agente, AST checks).
    • Merge/main: evaluación semántica completa (LLM-judge, snapshots semánticos).

    3. Sandbox seguro para deterministas

    Sandbox seguro para deterministas: ejecuta tests en contenedores efímeros sin red ni credenciales. Usa Firecracker o gVisor para aislamiento si ejecutas código generado automáticamente.

    4. Métricas y guardrails

    • Pass rate determinista por PR.
    • Delta semántico medio por cambio de spec.
    • Flakiness score (casos inestables entre ejecuciones).
    • Cost per eval (tokens, tiempo).

    Integración de herramientas de observabilidad: Promptfoo para orquestación local de evals, LangSmith para tracing, Braintrust para gestión de datasets.

    Checklist mínimo antes de confiar en un agente

    • Tests críticos escritos por humanos y en el repo.
    • Golden Dataset versionado y ejecutable en CI.
    • Sandbox efímero con timeouts y sin acceso a prod.
    • Reglas claras de qué puede commitear el agente automáticamente.
    • LLM-judge configurado para snapshots y revisiones semánticas.
    • Telemetría: registro de prompts, respuestas, tokens y justificación del juez.

    Conclusión: el rol del Tech Lead

    Testing en la era de los agentes no elimina la responsabilidad humana; la traslada a la definición de contratos, gobernanza y métricas. El Tech Lead debe decidir qué pruebas son la fuente de verdad, cómo se auditan las decisiones del agente y cuándo intervenir manualmente. Si tratas los tests como especificaciones inmutables y habilitas snapshots semánticos, los agentes dejan de ser generadores de ruido y pasan a ser máquinas de productividad que se pueden gobernar.

    Dominicode Labs

    Para equipos que exploran evaluaciones semánticas y pipelines con agentes, Dominicode Labs ofrece recursos y patrones reproducibles para integrar LLM-judges y sandboxes en CI. Considera esta referencia como una continuación práctica de las ideas descritas arriba.

    FAQ

    Respuesta: Test-Driven Prompting aplica la práctica de escribir tests como especificaciones antes de implementar. El test actúa como el prompt más estricto para el agente y define el contrato que debe cumplirse.

    Respuesta: No delegues tests de integración críticos (pagos, auth), flujos E2E, tests de regresión con historial real y el setup de entornos/fixtures. Estos requieren contexto de negocio y control humano.

    Respuesta: Los snapshots semánticos usan un módulo de evaluación (LLM-judge) que recibe el snapshot antiguo, el nuevo y una rúbrica, y decide si el cambio es cosmético o funcional, registrando justificación para auditoría.

    Respuesta: Un Golden Dataset incluye 20–50 casos representativos, versionados en Git y ejecutables en CI. Sirve como baseline para validar cambios de especificación.

    Respuesta: Ejecuta código en contenedores efímeros sin red ni credenciales, aplica timeouts y usa tecnologías como Firecracker o gVisor para aislamiento.

    Respuesta: Sigue métricas como pass rate determinista por PR, delta semántico medio por cambio de spec, flakiness score y cost per eval (tokens, tiempo). Complementa con telemetría de prompts y decisiones del juez.

  • Recursos prácticos para aprender Spec-Driven Development

    Recursos prácticos para aprender Spec-Driven Development

    Listado de recursos para aprender SDD en castellano

    Tiempo estimado de lectura: 4 min

    • Ideas clave:
    • Spec-Driven Development (SDD) propone escribir especificaciones deterministas antes de codificar.
    • Un buen spec es el contrato entre el equipo humano y los agentes de IA; cuando es claro, reduce fragilidad en el código generado.
    • Lee la teoría primero, aplica en un proyecto pequeño y luego usa agentes (por ejemplo Claude Code) para cerrar el ciclo.
    • Versiona specs junto al código, declara contratos formales (OpenAPI/JSON Schema) y valida en runtime.

     

    Introducción

    El Spec-Driven Development (SDD) ya no es una moda: es la forma práctica de obtener código fiable cuando trabajas con agentes de IA. Si buscas un listado de recursos para aprender SDD en castellano, este artículo reúne lo esencial —teoría, práctica y pasos accionables— y muestra cómo convertir especificaciones en artefactos ejecutables por agentes como Claude Code.

    En las primeras líneas: el Spec-Driven Development consiste en escribir especificaciones deterministas antes de codificar. Esa especificación es el contrato que el equipo humano y el agente de IA van a cumplir. Si no está clara, el código generado será frágil; si está bien definida, el agente actúa como un ejecutor reproducible.

    Resumen rápido (lectores con prisa)

    SDD = escribir especificaciones deterministas y ejecutables antes de codificar. Úsalo cuando delegues trabajo repetible a agentes de IA o necesites contratos claros entre equipos. Importa porque reduce errores de generación y facilita trazabilidad. Funciona definiendo contratos formales (OpenAPI/JSON Schema), validándolos en runtime y versionándolos junto al código.

    Listado de recursos para aprender SDD en castellano

    SDD — Spec-Driven Development (libro)

    SDD — Spec-Driven Development

    Por qué leerlo: es la base conceptual sobre cómo diseñar especificaciones que funcionen tanto para personas como para modelos. Explica estructura de especificaciones, convenciones de contratos, ejemplos de modelos de datos y patrones para casos límite. Ideal para tech leads y arquitectos que deben estandarizar cómo se escribe el “qué” antes de generar el “cómo”.

    Construye con IA: de la idea al producto con Claude Code (curso Udemy)

    Construye con IA: de la idea al producto con Claude Code (curso Udemy)

    Por qué hacerlo: Claude Code es un agente que opera en tu entorno de desarrollo. El curso enseña a estructurar especificaciones que el agente pueda ingerir, supervisar la ejecución y corregir desviaciones. Es la práctica necesaria para ver cómo una especificación bien escrita reduce iteraciones y errores de generación.

    Cómo usar estos recursos de forma práctica (secuencia recomendada)

    1. Lee el libro primero. Construye el marco mental: ¿qué debe contener una especificación? ¿cómo documentar invariantes, límites y errores esperados?

    2. Aplica lo leído a un pequeño proyecto: escribe una especificación completa (archivo Markdown) para una funcionalidad simple: endpoint, modelo de datos y flujos de error.

    3. Realiza el curso y usa Claude Code para ejecutar la especificación. Observa dónde el agente alucina o omite pasos; corrige la especificación y repite.

    Esta secuencia cierra el ciclo: teoría → especificación real → ejecución con agente → ajuste de especificación.

    Paso 1

    Lee el libro y define la estructura mínima de tu spec: título, objetivo, invariantes y errores esperados.

    Paso 2

    Escribe la especificación en Markdown dentro del repo y convierte contratos en OpenAPI/JSON Schema.

    Paso 3

    Usa Claude Code para ejecutar; recopila fallos, ajusta la spec y repite hasta estabilidad.

    Plantilla mínima de una especificación SDD (práctica)

    Incluye estos apartados en un archivo Markdown dentro del repo (Docs-as-code):

    • Título y objetivo (1–2 frases).
    • Requisitos no funcionales (latencia, SLAs, seguridad).
    • Modelos de datos (ej. JSON Schema / OpenAPI snippets).
    • Casos de uso y flujos (máquina de estados simplificada).
    • Invariantes y restricciones (qué no debe pasar).
    • API contract (endpoint, métodos, parámetros, errores).
    • Tests de aceptación (inputs esperados y resultados).
    • Checklist de despliegue y rollback.

    Guardar la especificación cerca del código facilita que los agentes la lean como contexto y que el equipo la mantenga sincronizada.

    Buenas prácticas técnicas para equipos que adoptan SDD

    • Versiona las especificaciones en el mismo repo que el código. Nada de Confluence aislado.
    • Declara contratos formales (OpenAPI, JSON Schema). Convierte esos esquemas en herramientas ejecutables por agentes.
    • Usa prompts y archivos de contexto estándar (por ejemplo .cursorrules o system prompts) para que los agentes carguen las convenciones del proyecto.
    • Implementa validación: transforma tus schemas en validadores runtime (Zod o Ajv) y aplícalos a cada tool_use.
    • Instrumenta trazabilidad: cada ejecución automatizada debe dejar un rastro del prompt, la versión del spec y el resultado del agente.

    Limitaciones y siguientes pasos

    El ecosistema en castellano está creciendo; estos dos recursos son el núcleo. Para necesidades avanzadas —memoria a largo plazo, flujos que duran días, trazabilidad distribuida— añade prácticas e infraestructuras: persistencia (PostgreSQL/pgvector), orquestadores (n8n, LangGraph) y observabilidad (OpenTelemetry). Pero no conviertas la arquitectura en excusa: domina la especificación primero.

    Conclusión

    Si vas a trabajar con agentes de IA, aprender SDD es priorizar el acto más rentable: especificar bien. Empieza por leer el libro en Leanpub y practica con Claude Code en Udemy. Transforma la especificación en contrato vivo, versionado y ejecutable. Con eso, reduces iteraciones, controlas costos por token y, sobre todo, dejas de depender de la suerte cuando delegas en agentes.

    Para equipos interesados en implementar prácticas de SDD y automatización con agentes, una continuación lógica es revisar recursos y experimentos en Dominicode Labs.

     

    FAQ

    Respuesta: SDD consiste en escribir especificaciones deterministas antes de codificar; estas actúan como contrato entre equipos humanos y agentes de IA.

    Respuesta: Versionar las especificaciones en el mismo repo garantiza sincronía con el código, facilita revisiones y evita documentación aislada que se queda obsoleta.

    Respuesta: Se recomiendan contratos formales como OpenAPI y JSON Schema porque son legibles por herramientas y agentes, y permiten generar validadores y mocks.

    Respuesta: Transforma tus schemas en validadores runtime (por ejemplo Zod o Ajv) y ejecútalos en cada tool_use o etapa donde el agente entregue artefactos.

    Respuesta: Agentes como Claude Code ejecutan especificaciones en tu entorno; su papel es reproducir flujos definidos por la spec y permitir iteración rápida sobre fallos.

    Respuesta: Tras la teoría, aplica en un proyecto pequeño: escribe una spec, ejecútala con un agente, corrige las desviaciones y automatiza validaciones y trazabilidad.

  • Aprende a escribir especificaciones efectivas para LLMs

    Aprende a escribir especificaciones efectivas para LLMs

    Por qué dejé de escribir código desde cero y empecé a hacer specs primero

    Tiempo estimado de lectura: 3 min

    • Menos correcciones manuales: las specs reducen el tiempo invertido en ajustar código generado por LLMs.
    • Contratos ejecutables: una spec bien definida evita ambigüedades y deuda técnica.
    • Escalabilidad y previsibilidad: la spec es la fuente de verdad para cambios y nuevos colaboradores.

    ¿Sabes qué consume más tiempo que escribir código? Corregir el código que generó la IA porque nadie le dejó claro qué hacer.

    Hace un par de años disfrutaba abrir un editor en blanco. Era adrenalina pura: estructura, imports, resolver problemas “sobre la marcha”. Parecía productividad. Era ilusión.

    La transición a escribir specs primero cambió eso por completo. No porque sea más elegante, sino porque es más efectivo. Aquí te cuento por qué dejé de escribir código desde cero y empecé a hacer specs primero, qué contiene una spec útil y cómo eso transforma la relación entre humanos, agentes y código.

    Resumen rápido (lectores con prisa)

    Spec‑Driven Development: definir specs precisas antes de implementar reduce ambigüedades, minimiza correcciones manuales y convierte la spec en la fuente de verdad. Útil cuando el producto se mantiene, la lógica es compleja o hay múltiples integradores. Implementación: especifica stack, datos, contratos de API, reglas de negocio y casos de aceptación.

    Por qué dejé de escribir código desde cero y empecé a hacer specs primero

    El catalizador fue simple: gastaba horas ajustando código generado por LLMs. No es culpa de la IA. Es culpa de la ambigüedad. Un modelo no conoce tus convenciones, tus límites ni las decisiones que tomaste el martes. Para un LLM, lo que no está escrito no existe.

    Cuando trabajas sin spec, cada prompt es un microcontrato mal redactado. Resultado: fragmentos que funcionan aisladamente y rompen la coherencia global. El coste no es solo tiempo; es deuda técnica que aparece en sprint 3 y se siente en el cuello del repo.

    Escribir specs primero no es volver a la documentación de los 90. Es escribir contratos ejecutables: lo suficiente para que un agente implemente sin inventar nada. Eso cambió mi productividad: menos correcciones, menos parches, más iteraciones reales.

    ¿Qué lleva una spec que funcione con IA?

    No basta con una descripción bonita. Una spec útil es precisa, limitada y accionable. Esto es lo que siempre incluyo:

    • Stack exacto con versiones. No “React moderno”. React 18.3, Next.js 14, etc.
    • Modelo de datos. Tablas, campos, tipos y restricciones. Si usas UUID, dilo.
    • Contratos de API. Endpoints, payloads de ejemplo, códigos de error y formatos.
    • Reglas de negocio explícitas. Qué hacer y, más importante, qué no hacer.
    • Casos de aceptación. Escenarios claros que definen el comportamiento visible.
    • Límites del MVP. Qué se queda fuera en esta iteración y por qué.

    El documento vive en el repo (spec.md), versionado. Si algo cambia, la spec cambia primero. No al revés.

    Si quieres una guía práctica para redactar specs que funcionen con LLMs, uso y recomiendo el libro Spec‑Driven Development.

    Cómo cambiaron mis sesiones con agentes

    Antes: abría un chat, pedía componentes, pegaba código. Después de dos horas, el sistema era Frankenstein.

    Ahora: escribo la spec, lanzo al agente en terminal con la instrucción clara—lee spec.md e implementa la Fase X—y reviso diffs. El agente crea archivos, instala dependencias y propone un conjunto coherente desde la raíz. Mi rol pasa de “peón que teclea” a “arquitecto que aprueba”.

    Regla de oro

    Nunca corrijo el código directamente para resolver una ambigüedad. Actualizo la spec y mando al agente a refactorizar. Si corriges el código sin tocar la spec, el día siguiente volverás a ver el mismo fallo cuando el agente regenera algo incompatible.

    Beneficios reales (sin poesía)

    • Menos tiempo en ajustes menudos. Más tiempo en decisiones estratégicas.
    • Menos deuda técnica porque las reglas de diseño se establecen antes.
    • Cambios más predecibles: si una feature cambia, la spec es la fuente de verdad.
    • Escalabilidad del equipo: nuevos desarrolladores o agentes arrancan en horas, no en días.

    Cuando esto no aplica

    No todos los proyectos necesitan SDD. Si estás escribiendo un script de 50 líneas o prototipando algo desechable para validar una idea, un prompt rápido tiene sentido. SDD brilla cuando el producto crece, hay datos críticos o múltiples integradores.

    Regla práctica: si la base de código será mantenida más de un mes o la lógica de negocio es compleja, escribe la spec.

    El cambio de rol del developer

    Adoptar specs no elimina el trabajo humano; lo eleva. Ahora se pide que tomes decisiones tempranas y explícitas: límites, trade-offs, casos borde. La ejecución se delega, la responsabilidad de diseño sigue siendo humana.

    Ese es el valor real: profesionales que saben diseñar sistemas se vuelven más valiosos porque delegan la repetición y retienen la toma de decisiones estratégicas.

    El libro Spec‑Driven Development recoge las plantillas, patrones y ejemplos que uso todos los días para que un LLM implemente sin inventos. Si estás cansado de arreglar lo que la IA rompe, empieza por escribir la spec. Es incómodo al principio, pero harás más en menos tiempo y sin excusas.

    La próxima iteración de tu proyecto debería empezar con un archivo spec.md, no con un editor en blanco. Hazlo y verás que tu trabajo deja de parecer frenético: se vuelve deliberado.

    Para equipos que adoptan automatización y agentes como parte del flujo de desarrollo, una práctica centralizada de especificaciones acelera la coordinación entre humanos y máquinas. Si estás explorando flujos donde agentes y workflows son críticos, mira iniciativas y recursos prácticos en Dominicode Labs para ejemplos aplicables y plantillas.

    FAQ

    Respuesta: Spec‑Driven Development es la práctica de definir especificaciones precisas y accionables antes de implementar. Las specs actúan como contratos ejecutables para equipos humanos y agentes.

    Respuesta: Escribe una spec cuando la base de código será mantenida más de un mes, la lógica de negocio es compleja o hay múltiples integradores. Para scripts pequeños o prototipos muy tempranos, un prompt rápido puede bastar.

    Respuesta: Una spec mínima incluye: stack y versiones, modelo de datos, contratos de API con ejemplos, reglas de negocio claras y casos de aceptación. También define los límites del MVP.

    Respuesta: Mantén la spec en el repo, lanza al agente con instrucciones que apunten al archivo (por ejemplo, “lee spec.md e implementa la Fase X”) y revisa diffs en lugar de editar código directamente.

    Respuesta: Si alguien modifica código sin actualizar la spec, la siguiente regeneración por parte del agente puede reintroducir el fallo. La regla de oro es: actualiza la spec y vuelve a ejecutar al agente.

    Respuesta: Guarda las specs en el repositorio como archivos versionados (ej.: spec.md). Cualquier cambio debe pasar por control de versiones para que la spec sea la fuente de verdad.

  • Cómo elegir entre Hono, NestJS y Express en 2026

    Cómo elegir entre Hono, NestJS y Express en 2026

    Hono vs Express vs NestJS: cuál usar en 2026

    Tiempo estimado de lectura: 4 min

    Ideas clave

    • Decide por ejecución y mantenimiento: Edge/Serverless → Hono; contenedores y equipos grandes → NestJS; Express solo para legacy.
    • Hono sigue estándares Web (Fetch API) → despliegue directo en Cloudflare Workers, Deno y Bun; bundles mínimos y cold starts bajos.
    • NestJS aporta estructura, DI y patterns enterprise que facilitan gobernanza en equipos grandes.
    • Patrón recomendado: combinar Hono en el perímetro y NestJS en el core para optimizar latencia y mantenibilidad.

    Tabla de contenidos

    Resumen rápido (lectores con prisa)

    Hono es un microframework basado en la Fetch API ideal para despliegues Edge/Serverless con cold starts mínimos. NestJS es un framework estructurado con DI pensado para equipos grandes y aplicaciones empresariales. Express queda como opción legacy; para nuevo desarrollo en Node considera Fastify. Usa Hono en el perímetro y NestJS en el core cuando necesitas ambas propiedades.

    Introducción

    Hono vs Express vs NestJS: cuál usar en 2026 es la pregunta que debes resolver antes del primer commit. No es trivia: elegir mal condiciona latencia, coste, pruebas y, sobre todo, la capacidad del equipo para mantener código sano durante años.

    Si vas a desplegar en Cloudflare Workers, Deno o Bun, Hono cambia las reglas. Si tu sistema vive en Kubernetes y lo mantienen varios equipos, NestJS también cambia las reglas. Express… debería quedarse en mantenimiento.

    Hono vs Express vs NestJS: criterio de elección en 2026

    Primera regla: responde a dos preguntas concretas antes de elegir.

    • ¿Dónde se ejecutará el código? (Edge / Serverless vs contenedor)
    • ¿Quién lo mantendrá? (1–3 devs vs equipos >5)

    Hono está diseñado sobre estándares Web (Fetch API). Eso le da dos ventajas técnicas inmediatas: ejecuta sin cambios en Cloudflare Workers y Deno, y los bundles son mínimos → cold starts casi nulos. Ideal para servicios perimetrales: autenticación perimetral, proxies, transformaciones ligeras y APIs públicas de alta concurrencia.

    NestJS es lo opuesto deliberado: peso inicial mayor, pero estructura y DI que escalan en equipos grandes. Si necesitas módulos, interceptores, pipes, testing con mocks y un modelo mental homogéneo entre 10–50 ingenieros, NestJS reduce la deuda humana.

    Express sigue vivo por legacy. Técnicamente tiene problemas: acoplamiento a primitivas de Node (IncomingMessage/ServerResponse), soporte TypeScript no nativo y mala compatibilidad con runtimes Edge sin polyfills. Para proyectos nuevos, Fastify es una alternativa Node que merece consideración por rendimiento y plugins modernos.

    Performance y cold starts: cuándo importa realmente

    Si tu SLA pide latencia global baja y tus endpoints reciben picos distribuidos geográficamente, los cold starts importan. Hono arranca en milisegundos; NestJS arranca en cientos. Esa diferencia se traduce en UX y factura cuando se escala en funciones serverless.

    Ejemplo práctico:

    • API pública de alta concurrencia (CDN + Edge): Hono en Workers.
    • Sistema de facturación con colas, auditoría y scheduling: NestJS en contenedores.

    No mezcles requisitos. Si necesitas ambos, separa responsabilidades: Hono en el perímetro, NestJS en el núcleo.

    Escalabilidad de equipo y mantenibilidad

    NestJS gana por goleada en proyectos donde:

    • Múltiples equipos aportan features.
    • Necesitas contratos claros (interfaces, DTOs, guards).
    • Quieres testing coherente con DI y mocks.

    Hono exige disciplina. Sin una capa organizativa —convenios de carpeta, inyección manual, testing— terminas con endpoints inconexos. Aún así, para equipos pequeños o equipos senior que aceptan convenciones internas, Hono es una opción mantenible.

    Seguridad, observabilidad y ecosistema

    NestJS integra patterns enterprise: interceptores para logging, guards para auth, módulos para integración de colas (BullMQ), microservicios gRPC, etc. Si necesitas trazabilidad distribuida y middlewares estandarizados, te lo pone más fácil.

    Hono no te impide instrumentar trazas, pero requiere que diseñes la integración desde cero. Para infra ligera y métricas puntuales está bien; para auditoría y cumplimiento, NestJS acelera la adopción.

    Reglas prácticas para decidir (lista accionable)

    1. Despliegue Edge (Cloudflare Workers, Deno, Bun) → Hono. Docs: https://hono.dev, Cloudflare Workers: https://developers.cloudflare.com/workers
    2. Núcleo empresarial en Kubernetes → NestJS. Docs: https://docs.nestjs.com
    3. Proyecto nuevo pequeño, necesitas rendimiento en Node → Fastify sobre Express. Fastify: https://www.fastify.io
    4. Mantener app legacy en Express → parche, migración gradual a Fastify/NestJS o mantener si coste de migración es mayor.
    5. Necesitas tipado extremo end-to-end con frontend TS → Hono RPC o compartir DTOs desde NestJS.
    6. Requisito de cold starts <20ms → Hono (Edge); NestJS requiere contenedores siempre calientes.

    Patrón recomendado: combinar, no elegir a ciegas

    La arquitectura más práctica en 2026 no es monolítica en framework. Usa NestJS para la lógica de negocio, colas, trabajos en background y microservicios críticos; usa Hono para la capa perimetral, autenticación global, webhooks y endpoints que deben estar cerca del usuario.

    Ventaja: reduces coste y latencia donde importa, y mantienes previsibilidad y pruebas allí donde importa más: en el core.

    Conclusión

    Hono vs Express vs NestJS: cuál usar en 2026 no es una competición de popularidad. Es una cuestión de contexto. Si necesitas extremar latencia y desplegar en Edge, Hono gana. Si necesitas gobernanza de código, DI y un stack mantenible por equipos grandes, NestJS gana. Express sigue siendo válido solo para mantener legacy; para nuevo desarrollo, elige Fastify si trabajas exclusivamente en Node.

    Decide según ejecución y mantenimiento, no por hype. La mejor arquitectura combina herramientas: perímetro ligero (Hono) + corazón estructurado (NestJS). Eso te dará velocidad hoy y coherencia mañana.

    FAQ

    Respuesta: ¿Cuándo debo usar Hono en lugar de NestJS?

    Usa Hono cuando despliegues en runtimes Edge/Serverless (Cloudflare Workers, Deno, Bun) y necesites cold starts mínimos y alta concurrencia en endpoints públicos. Usa NestJS cuando necesites estructura, DI y gobernanza para equipos grandes.

    Respuesta: ¿Express todavía tiene sentido para proyectos nuevos?

    No para la mayoría de proyectos nuevos. Express se mantiene por legacy. Para nuevo desarrollo en Node, considera Fastify por rendimiento y plugins modernos.

    Respuesta: ¿Cómo afecta el entorno de ejecución a la elección del framework?

    El entorno define compatibilidad y cold starts. Hono está diseñado para la Fetch API y funciona en Workers/Deno/Bun sin polyfills. NestJS está pensado para contenedores y necesita procesos calientes para minimizar latencia.

    Respuesta: ¿Qué alternativas a Express recomiendan para Node moderno?

    Fastify es la alternativa recomendada por rendimiento y ecosistema de plugins. Evalúa Fastify sobre Express para proyectos nuevos en Node.

    Respuesta: ¿Puedo mezclar Hono y NestJS en la misma plataforma?

    Sí. Patrón recomendado: Hono en el perímetro (autenticación global, webhooks, endpoints edge) y NestJS en el núcleo (lógica de negocio, colas, trabajos). Separar responsabilidades reduce coste y mejora latencia.

    Respuesta: ¿Qué considerar sobre cold starts en serverless?

    Si tu SLA requiere latencias muy bajas y tienes picos geográficos, los cold starts importan. Hono puede arrancar en milisegundos en Edge; NestJS suele requerir contenedores calientes y arranques en cientos de ms.