Tag: Spec Driven Development

  • Cómo explicar IA a tu jefe: 6 frases que acaban en tu sprint

    Cómo explicar IA a tu jefe: 6 frases que acaban en tu sprint

    La reunión duró cuarenta minutos. Al final, el director de producto lo cerró con una frase: "entonces montamos un agente que conteste con nuestra documentación y que no se invente nada, para el sprint que viene".

    Todo el mundo asintió. Yo también asentí, y ese fue mi error.

    En esa frase había tres proyectos distintos, un criterio de aceptación imposible de cumplir y una fecha. Lo que aprendí ese trimestre es que explicar IA a negocio no es un favor que le haces a tu jefe: es una tarea técnica que, si no haces, la pagas tú.

    Resumen rápido

    Explicar IA a negocio no consiste en corregir términos: consiste en convertir cada frase de la reunión en una decisión escrita antes de que llegue al sprint como alcance. Seis frases hacen casi todo el daño: "es solo un prompt", "necesitamos un agente", "entrénalo con nuestros datos", "que no alucine", "con IA iremos mucho más rápido" y "¿esto ya está en producción?". El método son cuatro pasos: traduce a decisión y no a definición, pon el tradeoff con números aunque sean aproximados, deja la decisión escrita y pelea el alcance en lugar de la palabra.

    El malentendido no se queda en la reunión: acaba en el alcance de tu sprint

    Cuando alguien de negocio usa mal un término técnico, tú y yo hacemos lo mismo: dejarlo pasar. No es el momento, se entiende por el contexto.

    El problema es que en proyectos de IA los términos no son adorno. Son alcance.

    "Agente" no describe una feature: describe un sistema con permisos y modos de fallo propios. "Que no alucine" no es un requisito: es una promesa que nadie puede firmar. Y las dos acaban redactadas como criterios de aceptación por alguien que no tenía por qué saber lo que esas dos palabras arrastran.

    Heredas el malentendido convertido en alcance. Y el alcance, a diferencia de la palabra, tiene fecha.

    Las definiciones limpias están en el diccionario de términos de IA y puedes mandar ahí a quien pregunte. Aquí van las seis frases y la factura que te llega cuando nadie las traduce.

    Traducir IA a negocio: las seis frases y lo que cuestan

    Estas son las seis frases que más veces he oído en reuniones de proyecto de IA, lo que cree quien las dice y la factura concreta que llega al sprint:

    Lo que dice Lo que cree que significa Lo que te llega al sprint
    "Es solo un prompt" Una frase bien escrita, medio día La estimación dividida entre tres
    "Necesitamos un agente" Un chat con botones Un sistema con permisos sobre datos reales
    "Entrénalo con nuestros datos" Que el modelo aprenda de sus PDF Semanas en el proyecto equivocado
    "Que no alucine" Un bug que se arregla Un criterio de aceptación que no cierra nunca
    "Con IA iremos mucho más rápido" El mismo trabajo en menos tiempo Fechas puestas sobre una cifra que nadie midió
    "¿Esto ya está en producción?" Si responde, está terminado Tú eres el sistema de evaluación, en tu tiempo

    "Es solo un prompt" — por qué la estimación se te va al triple

    Cree que el trabajo es redactar bien una instrucción. Medio día, uno si hay que probar variantes.

    El prompt es la pieza pequeña. Alrededor va el contexto que le pasas, las herramientas que puede llamar, qué ocurre cuando devuelve basura y cómo compruebas que la semana que viene sigue funcionando igual. Todo eso junto es lo que conté en por qué un LLM por sí solo no es un producto.

    El coste llega en la estimación: dijiste dos días pensando en la instrucción, y el ticket incluía en silencio todo lo demás. Cuando pides más tiempo, la conversación ya no es "el problema era más grande", es "¿por qué tardas el triple en escribir una frase?".

    "Necesitamos un agente" — qué te están pidiendo en realidad

    Cree que es un chat con botones que contesta en lenguaje natural.

    De verdad es un bucle que decide por su cuenta, llama herramientas y tiene permisos sobre sistemas reales. La distancia entre las dos cosas la desarrollé en IA generativa vs IA agéntica, y es la distancia entre dos presupuestos.

    El coste es que diste una estimación para un envoltorio de chat y te han pedido un sistema que actúa solo. Y "actúa" arrastra preguntas que no estaban en el ticket: sobre qué puede escribir, quién lo autoriza, cómo se detiene a mitad de ejecución, qué queda auditado.

    Ninguna cabe en el sprint que ya tenía fecha antes de que existieran.

    "Entrénalo con nuestros datos" — semanas en el proyecto equivocado

    Cree que toca fine-tuning: echarle los PDF de la empresa al modelo y que aprenda.

    Casi siempre lo que quiere es que el sistema busque en sus documentos antes de responder. Cuál toca en cada caso lo conté en RAG vs fine-tuning vs contexto.

    El coste son semanas en el proyecto equivocado. Y lo peor no es el tiempo: después nadie lo lee como un malentendido de alcance, se lee como que "la IA no funcionó" y que el que la montó fuiste tú.

    La versión hermana es "ponle memoria", que para quien lo dice significa acordarse de todo para siempre. Debajo hay ventana de contexto y coste por token. Si no sale antes, eliges arquitectura para sostener una expectativa que nadie revisó.

    "Que no alucine" — el criterio de aceptación que no cierra nunca

    Cree que es un bug: se abre ticket, se arregla, se cierra.

    Es consecuencia de cómo funciona el modelo. Se acota con límites de dominio, verificación y citas, y se reduce mucho. No se elimina. El porqué está en por qué la IA se inventa cosas.

    Este es el más caro de la lista por una razón concreta: se escribe. "El sistema no debe dar información incorrecta" aterriza tal cual como criterio de aceptación, y es una casilla que no vas a marcar nunca. No porque sea difícil: porque no se puede demostrar sobre entradas que no controlas. En la demo funciona y en la retro siguiente alguien trae un caso.

    Te quedas como responsable indefinido de algo que, por diseño, no tiene línea de meta.

    "Con IA iremos mucho más rápido" — la cifra que nadie midió

    Cree que es el mismo trabajo en menos tiempo.

    La IA mueve el cuello de botella: escribir código deja de ser lo caro, y especificar y revisar código que no escribiste pasan a serlo. Es lo que más ha cambiado en 15 años programando, y revisar es trabajo aunque no aparezca en ningún tablero.

    El coste son fechas puestas sobre una cifra que nadie midió. Nadie dice en voz alta "asumamos que iremos un 40% más rápido": se asume en silencio y aparece en el roadmap.

    Y cuando alguien lo mide en serio, el resultado incomoda. En el ensayo controlado de METR, 16 developers open-source experimentados resolvieron 246 tareas con y sin IA: creyeron que habían ido un 20 % más rápidos y en realidad tardaron un 19 % más. Cuidado con usar ese dato como arma, porque el propio METR lo da hoy por histórico —las herramientas eran de principios de 2025— y sirve justo para lo contrario de lo que parece: si los únicos que lo midieron con rigor ya no dan su número por vigente, nadie debería estar poniendo fechas sobre uno inventado.

    Sin medición no hay defensa: si el trimestre se cumple, la IA funcionó; si no, el equipo no la supo aprovechar. Lo único que rompe el bucle es llegar con números propios, y de eso va cómo medir la productividad en equipos que usan IA.

    "¿Esto ya está en producción?" — sin evals, el sistema de evaluación eres tú

    Cree que si responde bien en la demo, está terminado.

    Sin evals automáticos, que son los unit tests de un sistema con LLM, ni observabilidad, no sabes si funciona. Sabes que no ha explotado delante de ti todavía.

    El coste es el más silencioso de todos: tú eres el sistema de evaluación. Cada ajuste de prompt, cada versión nueva del modelo, cada caso raro que reporta un cliente pasa por tu criterio, a mano. Ese trabajo no está en ninguna planificación y crece con el uso: cuanto mejor le va al producto, más de tu tiempo se come mantenerlo respirando.

    Cómo explicar IA a tu jefe sin quedar de listo

    Tener razón no sirve de nada si la forma de decirlo te deja fuera de la conversación. Quien pide esto tiene su propia fecha encima. Cuatro cosas que funcionan.

    1. Traduce a decisión, no a definición. No expliques qué es un agente. Pregunta: "cuando dices agente, ¿quieres que actúe solo o que responda cuando le preguntan?". La definición no cambia nada; esa respuesta cambia el proyecto. Y la contesta él, así que la decisión sigue siendo suya.

    2. Pon el tradeoff con números, aunque sean aproximados. "Dos semanas si solo responde, seis si actúa solo" convierte un debate de palabras en una elección con precio. Da siempre rango y nunca una fecha suelta: la fecha se te queda pegada. Y si puedes, remata con la versión pequeña: "el día 12 tienes la que responde y cita fuentes; la que actúa sola es otra conversación". No estás negociando el alcance desde arriba, estás poniendo algo antes sobre la mesa. Con eso discute muchísima menos gente.

    3. Deja la decisión escrita. No hace falta un documento formal: dos líneas en el ticket o un correo con copia a los que estaban en la reunión. No es para tener razón después, sino para que el malentendido salga antes de escribir código. Si ahí pone "el sistema responde consultas, no ejecuta acciones sobre datos de cliente", quien lo lee contesta "espera, yo quería que ejecutara". Y te lo dice el martes, no en la demo del mes que viene. Ese es el argumento real para trabajar con especificaciones y la base del libro de Spec-Driven Development.

    4. No pelees la palabra, pelea el alcance. Da igual cómo lo llame. Lo que tiene que quedar fijado por escrito es qué hace, con qué permisos y qué pasa cuando falla. Esas tres cosas son el contrato; el término es decoración.

    Y si te toca opinar antes de que se apruebe el proyecto, ahí van cinco preguntas antes de aprobar un proyecto de IA.

    Explicar IA a negocio es parte de tu trabajo técnico

    Lo que cambió con la IA es el margen entre lo que negocio cree que pide y lo que hay que construir. Ese margen lo pagas tú en horas.

    Mañana, en la próxima reunión donde suelten una de estas seis frases, no la corrijas. Haz una pregunta que fuerce una decisión y escribe la respuesta en el ticket con las palabras de quien la dijo.

    Con eso dejas de heredar el malentendido. Y en un proyecto de IA, eso es la mitad del trabajo.

    Estas conversaciones, sobre proyectos reales, pasan cada semana en Dominicode Labs.

    Preguntas frecuentes

    ¿Cómo explico un proyecto de IA a mi jefe?

    No lo expliques: conviértelo en una decisión suya. Pregunta si el sistema tiene que actuar por su cuenta o solo responder cuando le preguntan, pon precio a cada opción en la misma frase ("dos semanas si solo responde, seis si actúa solo") y escribe la respuesta en el ticket con sus palabras. La definición no cambia nada; esa decisión cambia el proyecto entero.

    ¿No es el trabajo de mi jefe entender lo que pide?

    Entenderlo es su trabajo, sí, pero el coste de que no lo entienda cae en tu calendario, no en el suyo. Traducir hacia arriba no es un favor: es proteger tu propia estimación, y es una habilidad senior tan real como diseñar el sistema.

    ¿Cómo explico que "que no alucine" no es un requisito válido sin sonar a excusa?

    No discutas el requisito: propón otro que sí se pueda verificar. Cambia "no debe dar información incorrecta" por "toda respuesta cita el fragmento del que sale, y si la búsqueda no devuelve nada, el sistema responde que no lo sabe".

    Que eso último lo decida la búsqueda y no el modelo es lo que lo hace comprobable. Y añade la segunda mitad antes de que te la traigan ellos: sobre una lista fija de preguntas, alguien revisa que el fragmento citado sostenga la respuesta. Citar el documento correcto y tergiversarlo también es fallar.

    ¿Qué pregunto exactamente cuando alguien dice "necesitamos un agente"?

    Pregunta una sola cosa: "¿quieres que actúe por su cuenta o que responda cuando le preguntan?". Si contesta que actúe, encadena tres más: sobre qué sistemas puede escribir, quién lo autoriza y qué pasa cuando se equivoca. Esas cuatro respuestas son el alcance real.

    ¿Cómo sé si me están pidiendo fine-tuning o búsqueda sobre documentos?

    Pregunta qué pasa cuando el documento cambia. Si la respuesta es "tiene que responder con la versión nueva ya", están describiendo búsqueda sobre documentos, no entrenamiento. El fine-tuning ajusta cómo responde el modelo; si metes ahí información que cambia cada semana, te toca reentrenar cada semana.

    ¿Cómo estimo si negocio aún no ha decidido si el sistema actúa o solo responde?

    No estimes el proyecto: estima las dos versiones. Un rango para la que solo responde y otro para la que actúa sobre datos reales, con la diferencia en una línea. Así la fecha queda atada a esa decisión y no a tu velocidad.

    ¿Y si mi jefe se molesta cuando le matizo un término?

    No corrijas la palabra y ese roce casi nunca aparece. Lleva la conversación a qué hace el sistema, con qué permisos y qué ocurre cuando falla, y deja que él lo llame como quiera.

    Y si ya se ha molestado, no lo resuelvas en la reunión. Escríbele después el comportamiento que entendiste, con sus palabras, y pregúntale si es eso. Cuesta mucho ofenderse con alguien que te está confirmando lo que pediste.


    Por Bezael Pérez — Developer senior con más de 15 años de experiencia y fundador de Dominicode.

  • Cómo formar a tu equipo de desarrollo en IA en 6 semanas

    Cómo formar a tu equipo de desarrollo en IA en 6 semanas

    Cada vez que entro a dar una formación de IA a un equipo de desarrollo, hago la misma pregunta antes de encender el proyector: ¿qué no le dejáis hacer a la IA?

    Y casi siempre pasa lo mismo. Silencio. No un silencio incómodo: un silencio de gente que nunca se lo había planteado porque nadie se lo había preguntado.

    Formar a tu equipo de desarrollo en IA no consiste en repartir licencias ni en enseñar a escribir prompts: consiste en acordar por escrito qué se delega a la IA, cómo se revisa lo que genera y quién responde cuando falla. Eso es justo lo que ese silencio deja al descubierto.

    Al rato alguien contesta: "lo crítico lo revisamos bien". Pregunto qué es crítico. Salen tres definiciones distintas en la misma sala, y las tres personas llevan dos años trabajando en el mismo repositorio.

    Ahí está el problema entero. No es que el equipo no sepa usar la herramienta. Es que cada uno decide por su cuenta dónde termina la máquina y dónde empieza él.

    Comprar licencias no es formar a tu equipo de desarrollo en IA

    El patrón se repite en casi todas las empresas que me llaman. Dirección aprueba las licencias, se manda un email de anuncio, se hace una demo de una hora, y a partir de ahí "el equipo ya usa IA".

    Seis meses después sube la actividad. Más commits, más PRs, más líneas. Y nadie en esa organización sabe decir si el equipo va mejor o solo va más rápido cuesta abajo.

    Los datos del sector cuentan esa misma historia. El informe DORA 2025 sobre desarrollo asistido por IA, con casi 5.000 profesionales encuestados, encontró que el 90% ya usa IA en su trabajo y más del 80% cree que le hace más productivo.

    Pero un 30% reconoce tener poca o ninguna confianza en el código que esa IA genera. Trabajamos a diario con algo en lo que no confiamos.

    La encuesta a desarrolladores de Stack Overflow 2025 afina el diagnóstico: la frustración número uno, citada por el 66%, son las soluciones "casi correctas, pero no del todo". Y hay más gente que desconfía de la precisión de estas herramientas (45,7%) que gente que confía (32,7%).

    Lee eso otra vez con gorra de manager. El trabajo de tu equipo se ha desplazado a detectar lo casi-correcto. Eso no es una habilidad de herramienta. Es criterio.

    La conclusión más incómoda del informe DORA cabe en una frase suya: "AI doesn't fix a team; it amplifies what's already there". La IA no arregla un equipo, magnifica lo que ya había. Un equipo con estándares claros se vuelve más rápido y más consistente. Un equipo sin criterio compartido genera incoherencia a mayor velocidad y con mejor presentación.

    Por eso la adopción no es la competencia. El porcentaje de gente con la extensión instalada es una métrica de compras, no de ingeniería.

    Qué es exactamente "la parte de criterio" (en operativa, no en filosofía)

    Cuando digo criterio no hablo de sabiduría abstracta. Hablo de cuatro decisiones que alguien de tu equipo toma cada día, casi siempre sin acuerdo.

    Uno: qué se delega y qué no. Las tareas con dependencias de estado y decisiones encadenadas necesitan supervisión constante; las independientes y verificables se pueden lanzar en paralelo sin drama. Desarrollé esa separación en cómo clasificar tareas con IA en desarrollo de software, y es el primer acuerdo que debería tener un equipo por escrito.

    Dos: cómo se revisa código que no escribió un humano. Revisar el código de un compañero es revisar una intención que puedes preguntar. Revisar un diff generado es revisar una salida sin intención detrás. Menos estilo y naming, más "¿esto resuelve nuestro problema o uno parecido?".

    Tres: quién firma lo que sale a producción. Autoría y responsabilidad se han separado, y muchos equipos no lo han asumido. El modelo no está de guardia a las tres de la mañana. Si no hay un nombre humano pegado a ese despliegue, no hay dueño.

    Cuatro: qué haces cuando la propuesta funciona pero está mal. Este es el caso difícil. Pasa los tests, hace lo que pedía el ticket, y mete un patrón que dentro de cuatro meses te obliga a reescribir un módulo. Un dev con criterio lo rechaza aunque esté verde. Uno sin criterio lo mergea porque está verde.

    Decisión de criterio Síntoma cuando falta
    Qué se delega Cada dev tiene su umbral y la base de código parece escrita por cinco equipos
    Cómo se revisa Aprobaciones rápidas en diffs de 400 líneas que nadie ha leído entero
    Quién firma Cuando algo rompe, la primera frase es "eso lo generó la IA"
    Funciona pero está mal Deuda técnica nueva cada sprint, sin ninguna decisión que la haya causado

    Lo que la IA se ha llevado es la parte mecánica; escribí sobre ese desplazamiento en lo que cambió de verdad en el desarrollo con IA. Lo que queda es esta lista. Y esta lista es justo la que nadie está formando.

    El problema de los juniors: le has quitado su gimnasio

    Delegar a la IA el trabajo de bajo valor elimina justo las tareas con las que un junior se hacía senior. Es la parte de la que menos se habla y la que más me preocupa.

    El CRUD repetitivo, el test aburrido, el refactor pequeño, el bug tonto de dos horas: trabajo de bajo valor para la empresa y de altísimo valor para el que empezaba. Ahí aprendía un junior a leer un stack trace, a oler dónde rompe algo y a intuir por qué una decisión de ayer duele hoy.

    Si delegas ese bloque entero, el junior no se convierte en senior. Se convierte en revisor de algo que no sabe evaluar. Y un revisor sin criterio aprueba con una seguridad que asusta.

    No te digo que prohíbas la IA a los juniors: eso los deja fuera del mercado. Te digo que rediseñes por dónde entra el aprendizaje, con tres reglas que puedes implantar esta semana:

    • Primero a mano, después con IA. Elige dos o tres categorías de tarea (tests de lógica de negocio, consultas a base de datos) donde el junior hace la primera implementación sin asistente. A partir de la segunda, con lo que quiera. El objetivo no es sufrir: es tener un modelo mental propio contra el que comparar. Esto va por confianza, y la que lo hace cumplir de verdad es la regla siguiente.
    • Prohibido "no sé por qué funciona". Si no puede explicar el diff línea a línea en la revisión, no se mergea. Acótalo para que sobreviva al tercer mes: en los PRs que tocan lógica de negocio, y durante los primeros meses de cada junior. Un senior sentado en todos los PRs de todos los juniors no escala más allá de dos.
    • PR saboteado semanal. Un senior coge un PR generado con IA, le planta un fallo real (una condición invertida, un await que falta, un índice que se cae en la query nueva) y se lo pasa al junior. Tres condiciones para que esto no acabe siendo una novatada: el junior sabe que es un ejercicio y que hay un fallo, la rama vive fuera del flujo de merge para que nadie la apruebe por error, y al terminar se enseña el fallo aunque no lo haya encontrado. No se puntúa. Treinta minutos. Y una vez al mes se invierte: el junior sabotea y busca el senior. Es el ejercicio más barato y más eficaz que conozco para entrenar la mirada.

    Las tres cuestan tiempo de las personas más caras del equipo — cuenta unas 2 horas de senior por junior y semana. Es el precio real de que dentro de dos años tengas seniors.

    Y un cuarto movimiento que cambia el rol: que el junior escriba la especificación y la IA implemente. Deja de aprender tecleando y empieza a aprender decidiendo, que es donde está el valor ahora. Es la base de por qué el spec define hoy tu ventaja competitiva, y el método completo está en el libro de Spec-Driven Development.

    Si buscas algo que darle a un junior para que recorra ese camino por su cuenta, el curso Construye con IA va justo de eso: de la idea al producto decidiendo, no tecleando.

    Criterio compartido: el acuerdo que tu equipo debería tener escrito

    Un equipo donde cada dev tiene su propio umbral de delegación no tiene un problema de talento. Tiene un problema de varianza.

    Cinco personas razonables tomando cinco decisiones razonables distintas producen una base de código incoherente. Y eso no se detecta en el PR: se detecta seis meses después, cuando hay tres formas de hacer lo mismo y nadie sabe cuál es la buena.

    La solución no es un curso. Es un documento de una página que el equipo redacta y firma. Un acuerdo de uso de IA es ese documento: fija, por categoría de tarea, qué se delega al modelo, con qué nivel de revisión y quién tiene que dar el visto bueno. Cabe en esto:

    Categoría Regla Quién aprueba
    Qué se le pega al modelo Nunca secretos, credenciales ni datos reales de cliente: sintéticos o anonimizados. Solo herramientas aprobadas por la empresa Autor del PR
    Scaffolding, boilerplate, migraciones sin cambio de esquema Se delega completo Autor del PR
    Tests de lógica existente Se delega, revisión normal. El test tiene que fallar al menos una vez antes de aprobarse Autor del PR
    Refactor que cruza módulos o toca una API pública Se delega la implementación, el plan lo escribe un humano Autor + un revisor
    Auth, permisos, pagos, datos personales Se puede generar, revisión obligatoria de dos personas Owner del módulo
    Cambios de esquema en producción No se delega la decisión Tech lead
    Infra, pipelines de CI/CD y secretos No se delega la decisión Tech lead
    Dependencias nuevas La IA propone, un humano aprueba antes de que entre en el package.json Tech lead

    La fila de los tests es la que más gente se salta y la que más caro sale: un test generado certifica el comportamiento actual, bug incluido. Si rompes a mano lo que prueba y sigue en verde, ese test no vale nada.

    Tres reglas al pie del documento que valen más que la tabla:

    1. Toda excepción se justifica en una línea dentro del PR. Una línea, no un ensayo.
    2. Quien abre el PR responde del código, lo haya escrito él o no. La tabla dice quién aprueba; la responsabilidad no se reparte.
    3. El acuerdo se revisa cada trimestre. Si crece a ocho páginas, nadie lo lee y deja de existir.

    Métetelo en el repositorio, no en Confluence. En el CONTRIBUTING.md, en el CLAUDE.md o en el AGENTS.md, donde lo lean el equipo y los agentes. Y protege con CODEOWNERS las rutas críticas, pero acuérdate de activar en la rama principal la regla "Require review from Code Owners": sin esa casilla, CODEOWNERS sugiere revisores y no bloquea nada. Con la casilla puesta, el acuerdo deja de depender de la memoria de nadie un viernes a las siete.

    Y si quieres el punto de partida, este es el bloque que pego yo en el repo:

    # Acuerdo de uso de IA — v1
    Revisión: cada trimestre. Si crece a 8 páginas, deja de existir.
    
    | Categoría | Regla | Quién aprueba |
    |---|---|---|
    | Qué se le pega al modelo | Nunca secretos ni datos reales de cliente | Autor del PR |
    | Scaffolding, boilerplate, migraciones sin cambio de esquema | Se delega completo | Autor del PR |
    | Tests de lógica existente | Se delega. Debe fallar una vez antes de aprobarse | Autor del PR |
    | Refactor que cruza módulos o toca API pública | El plan lo escribe un humano | Autor + revisor |
    | Auth, permisos, pagos, datos personales | Revisión de dos personas | Owner del módulo |
    | Cambios de esquema en producción | No se delega la decisión | Tech lead |
    | Infra, CI/CD y secretos | No se delega la decisión | Tech lead |
    | Dependencias nuevas | La IA propone, un humano aprueba | Tech lead |
    
    1. Toda excepción se justifica en una línea dentro del PR.
    2. Quien abre el PR responde del código, lo haya escrito él o no.
    3. Nada se mergea si el autor no lo puede explicar línea a línea.
    

    Facilitar esa redacción con el equipo delante —y que salga en una sesión, no en tres meses de hilo de Slack— es la mitad del trabajo de una formación en IA para equipos de desarrollo. El documento no vale por lo que dice: vale porque lo escribieron ellos.

    Cómo medir si la formación en IA de tu equipo sirvió de algo

    La formación funcionó si el equipo converge: si ante el mismo ticket da menos respuestas distintas que antes de empezar. Lo que no sirve es medir líneas de código o PRs mergeados — con IA esas dos suben aunque el equipo esté empeorando. Ya conté qué medir en un equipo que usa IA en lugar de eso.

    Para evaluar la formación en concreto uso una medida que no vas a encontrar en ningún dashboard, porque me la inventé yo: la dispersión de criterio, es decir, cuántas respuestas distintas da tu equipo cuando le preguntas qué delegaría de un mismo ticket. Se mide así.

    Coges cinco tickets reales del backlog y preguntas a cada dev, por escrito y en anónimo, si los delegaría enteros, en parte o nada. Anotas el reparto antes de empezar. Seis semanas después repites el ejercicio con cinco tickets distintos pero del mismo perfil: si repites los mismos, lo que mides es si se acuerdan del acuerdo que firmaron, no si tienen criterio.

    Mira cuánta gente coincide en la opción mayoritaria de cada ticket. Si en la primera ronda el equipo se reparte entre las tres opciones y en la segunda ocho de cada diez coinciden, la formación funcionó. Si sigue repartido, has pagado una charla.

    Un detalle que evita el autoengaño: mete entre los cinco un ticket que ya salió mal en producción por haberlo delegado. Ese te dice si el equipo converge hacia el criterio bueno o simplemente converge hacia el que habla más alto en las reuniones.

    Añade tres indicadores de salud que ya deberías estar mirando: ciclos de revisión por PR, defectos que llegan a producción y tiempo de recuperación cuando algo rompe. El último es el más revelador, porque un equipo que no entiende el código que desplegó tarda muchísimo en arreglarlo.

    Y una métrica que no debes usar jamás: porcentaje de código generado por IA. Es vanidad pura y encima incentiva justo lo contrario de lo que quieres.

    Plan de 6 semanas para formar a tu equipo de desarrollo en IA

    Nada de trimestres ni de planes estratégicos: esto empieza el lunes. Seis semanas, una o dos sesiones por semana, y cada semana cierra con un entregable — diagnóstico, borrador del acuerdo, acuerdo firmado en el repo y segunda medición de dispersión.

    Semana Qué haces Entregable
    1 Diagnóstico, sin formación. Cada dev trae el PR más grande del último mes que se aprobó en menos de diez minutos, y se lee en voz alta en una sesión de 60 min. Se anotan de paso los términos donde el equipo no coincide Foto real del punto de partida, glosario común y medición inicial de dispersión
    2-4 Criterio en vivo. Dos sesiones semanales revisando PRs reales del repo, no ejemplos de juguete. Cada sesión añade una línea al acuerdo Borrador del acuerdo de uso de IA
    3 Arranca en paralelo la pista de juniors (primero a mano, PR saboteado) y sigue corriendo hasta el final Rutina semanal instalada
    5 Se cierra y se firma el acuerdo v1. Se mete en el repo y se cablea lo automatizable: bloquear PRs que tocan package.json sin aprobación del tech lead, límite de tamaño de diff, y el check de que la línea de justificación está en la descripción del PR Acuerdo v1 en producción
    6 Segunda medición de dispersión y retro Comparativa antes/después

    Coste total: entre 8 y 10 sesiones en seis semanas, alrededor de hora y media por persona y semana. Ese es el número que necesitas para venderlo hacia arriba.

    Las semanas 2, 3 y 4 deciden el resultado. Es donde el equipo discute casos concretos con el código delante y donde salen los desacuerdos que llevaban meses enterrados. Si te saltas esa parte y das teoría, acabas con gente que recita buenas prácticas y sigue mergeando lo que no entiende.

    Fíjate en que no hay ninguna semana de vocabulario. Si el 90% del equipo ya usa IA a diario, dedicar cinco días a explicar qué es una ventana de contexto es formación para un equipo que no tienes: los términos salen solos en la sesión de diagnóstico, y ahí se anotan.

    Si prefieres no llevar esto tú solo, es exactamente el trabajo que hago con equipos internos: seis semanas, adaptadas al stack real y con el acuerdo saliendo de los PRs del propio repo. Así funciona una formación para tu equipo.

    Por dónde empiezas el lunes

    Reúne al equipo cuarenta y cinco minutos, pon tres tickets reales encima de la mesa y que cada uno diga qué delegaría de cada uno. No pidas opiniones generales: vas a ver la dispersión en directo, y ese reparto es tu punto de partida.

    La herramienta se compra en una tarde. El criterio se acuerda, se escribe y se revisa. Esa diferencia es todo lo que separa a un equipo que usa IA de un equipo que la aprovecha.

    Preguntas frecuentes

    ¿Cuánto tiempo necesita un equipo para formarse en IA de verdad?

    Seis semanas para tener criterio compartido y un acuerdo escrito funcionando. La parte técnica pura son entre 8 y 24 horas según el nivel, pero sin las sesiones de revisión sobre código real el conocimiento no se convierte en práctica de equipo.

    ¿Sirve este plan para un equipo de 3 personas? ¿Y para 40?

    Para 3 sí, comprimido: las semanas 2, 3 y 4 se hacen en dos. Por debajo de 3 el acuerdo no aporta gran cosa, porque no hay varianza que reducir.

    Por encima de 15 no funciona en una sola sala: se hace por squad, cada uno redacta su acuerdo y luego se consolidan las reglas comunes en el repositorio raíz.

    ¿Debo prohibir la IA a los juniors hasta que tengan más nivel?

    No, eso los deja fuera del mercado y además la usarán igual sin que te enteres. Lo que sí funciona es acotar dónde la usan: que hagan la primera implementación de ciertas categorías de tarea sin asistente, y que no mergeen nada que no sepan explicar línea a línea.

    ¿Quién es responsable si el código generado por IA rompe producción?

    Quien abrió el pull request. La autoría del código y la responsabilidad sobre él se separaron, y la única forma de que un sistema siga funcionando es que la responsabilidad se quede pegada a un nombre humano. Escríbelo en el acuerdo del equipo antes de que ocurra el primer incidente.

    ¿Cómo justifico ante dirección invertir en formación si ya pagamos las licencias?

    Con la diferencia entre adopción y resultado. La licencia demuestra que la gente usa la herramienta; no dice nada sobre defectos en producción, ciclos de revisión ni tiempo de recuperación. Lleva esos tres números a la reunión junto con la medición de dispersión de criterio y la conversación cambia de tono.

    ¿Qué hago si un dev senior se niega a usar IA?

    Escúchale primero, porque su objeción suele ser de calidad y suele tener parte de razón. Después conviértelo en el dueño de la parte de revisión del acuerdo: la gente que desconfía escribe las mejores reglas de control, y así deja de ser un bloqueo para ser una garantía.


    Por Bezael Pérez — Developer senior con más de 15 años de experiencia y fundador de Dominicode.

  • Llevo 15 años programando: esto es lo que cambió con la IA

    Llevo 15 años programando: esto es lo que cambió con la IA

    Hace quince años, construir una funcionalidad significaba abrir un archivo en blanco y teclear cada línea hasta que compilaba. Cuando me atascaba, Stack Overflow. Cuando Stack Overflow fallaba, la documentación. Cuando la documentación mentía, prueba y error durante horas. Así aprendí el oficio y así trabajé la primera mitad de mi carrera.

    Esta mañana he construido un módulo completo sin teclear una sola línea de implementación a mano.

    Llevo quince años en esto y he visto pasar muchas modas. El desarrollo de software con IA no es una más. Es lo único que ha cambiado de raíz cómo hago mi trabajo. Pero no por la razón que casi todo el mundo repite en LinkedIn.

    Lo que ha cambiado no son las herramientas. Es el rol.

    Ya no me pagan por escribir código. Me pagan por decidir qué código debe existir, especificarlo bien y verificar que lo que se ha escrito es correcto. El tecleo —la parte que durante quince años fue la mayor parte del oficio— se ha vuelto la parte barata.

    Y si quieres la definición limpia, esta es la mía: el desarrollo de software con IA es la práctica de construir software delegando la escritura del código a modelos y agentes, mientras el developer se reserva las tres decisiones que siguen siendo suyas —qué construir, cómo debe encajar y si lo generado es correcto—.


    De escribir código a orquestarlo: así se programa con IA hoy

    Antes, un día productivo se medía en líneas. Hoy se mide en decisiones acertadas.

    La sesión de esta mañana fue así: abrí un documento, describí qué quería —el comportamiento, los límites, los casos que no debía tocar—, se lo pasé a un agente y me fui a por café. Cuando volví, había un diff de trescientas líneas esperándome.

    Mi trabajo empezó ahí. Leerlo entero. Cuestionar tres decisiones. Rechazar una. Aprobar el resto.

    No escribí la implementación. La orquesté.

    Si tuviera que resumir el cambio en una tabla, sería esta:

    Antes Ahora
    Unidad de medida Líneas escritas Decisiones acertadas
    Cuello de botella Teclear rápido y conocer la API Especificar con precisión
    Habilidad clave Saber escribir código Saber leer y revisar código
    Riesgo principal Bugs por descuido Deuda por código que nadie entendió
    Tu rol Autor Director y revisor

    Y ese cambio no fue de un día para otro. Fue una escalera. Primero el autocompletado —GitHub Copilot en 2021—, que adivinaba el final de la línea. Después el chat, ChatGPT y compañía, al que le pegabas un error y te devolvía una respuesta plausible. Y ahora el agente autónomo, del estilo de Claude Code o Cursor, que lee tu repo, ejecuta comandos, mira la salida y decide el siguiente paso sin ti. Si todavía andas en el primer escalón, la guía de Agentes de IA es el mejor sitio para entender qué hace distinto al último.

    Esa forma de trabajar en bucle —delegar, observar, corregir, repetir— tiene su propia disciplina, y la desarrollé entera en Loop Engineering: la evolución del desarrollo con IA. Porque diseñar bien ese bucle es hoy más determinante que elegir el modelo de moda.


    El cuello de botella del desarrollo de software con IA se movió: ahora está en especificar

    Durante años, el cuello de botella era teclear rápido y conocer la API de memoria. El que escribía más limpio y más rápido ganaba.

    Hoy el cuello de botella es otro: describir con precisión lo que quieres.

    Un agente hace lo que le pides al pie de la letra, no lo que querías decir. Todo lo que no especificas, lo inventa. Y lo inventa con una seguridad que asusta.

    Por eso el trabajo de más valor ya no es escribir la función. Es escribir la especificación de la función: el resultado esperado, los límites, los casos borde, lo que queda explícitamente fuera del alcance.

    Esto no es teoría. Es la metodología que uso a diario y la que documenté entera en el libro de Spec-Driven Development: especificar primero, delegar después. Si quieres el porqué antes que el cómo, lo cuento en Spec-Driven Development: la forma de evitar el caos con la IA.

    El developer que sabe redactar una buena especificación multiplica su trabajo. El que sigue tratando al agente como un buscador —"hazme esto"— se pasa el día corrigiendo basura.


    Lo que NO ha cambiado (y por qué el senior vale más que nunca)

    Aquí está la parte incómoda para los que venden que la IA ya programa sola.

    Nada de esto elimina al developer con criterio. Lo hace imprescindible.

    Un agente escribe trescientas líneas en dos minutos. Pero no sabe si esas trescientas líneas encajan en tu arquitectura. No sabe si van a ser un infierno de mantener dentro de un año. No sabe si acaba de duplicar una lógica que ya existía en otro módulo. El agente optimiza para que el criterio de parada se cumpla, no para que el sistema siga vivo dentro de dos años.

    Ese juicio sigue siendo tuyo.

    Y no es una manía mía de señor mayor. El informe DORA 2025 de Google Cloud, hecho con cerca de 5.000 profesionales de todo el mundo, encontró que el 90% ya usa IA en su trabajo y más del 80% dice que le ha subido la productividad. Pero un 30% reconoce tener poca o ninguna confianza en el código que esa IA genera.

    Ahí tienes la foto exacta del oficio hoy: casi todos delegamos, casi nadie firma a ciegas. Esa distancia entre "lo uso todos los días" y "no me fío" es, literalmente, la descripción de tu nuevo puesto de trabajo.

    Y ojo con confundir velocidad con progreso. Generar código rápido no es lo mismo que avanzar rápido. Un diff de trescientas líneas que nadie entiende no es velocidad, es deuda con intereses. Por eso "más rápido" y "mejor" no son la misma métrica, y desarrollé cómo distinguirlas en Cómo medir la productividad de un equipo con IA.

    Hay tres cosas que la IA no ha tocado, y son exactamente las que definen a un buen ingeniero:

    • El criterio. Saber qué construir y, sobre todo, qué no construir.
    • La arquitectura. Decidir cómo encajan las piezas para que el sistema aguante el paso del tiempo.
    • Saber leer código. Porque revisar es la nueva forma de escribir. Un diff que no entiendes es un diff que no puedes aprobar.

    Lo diré claro: hoy saber leer código importa más que saber escribirlo. Escribir lo hace la máquina. Leerlo, entenderlo y detectar dónde se ha equivocado sigue siendo humano.


    Al que no se adapta no lo sustituye la IA

    El miedo que oigo en cada charla es siempre el mismo: "¿La IA me va a quitar el trabajo?".

    No. Pero un developer que orquesta, especifica y revisa bien va a hacer el trabajo de tres que siguen tecleando línea a línea. Y las empresas lo van a notar en la nómina antes de lo que crees.

    No te sustituye la IA. Te sustituye el compañero que sabe usarla.

    La brecha ya no está entre el que programa y el que no. Está entre el que ha movido su trabajo hacia arriba en la cadena —del tecleo a la decisión— y el que sigue midiendo su día en líneas escritas a mano, orgulloso de un esfuerzo que la máquina hace gratis.

    Esa segunda persona no está en peligro por la IA. Está en peligro por negarse a cambiar de rol.


    Qué puedes hacer hoy

    Si llevas años programando y sientes que el suelo se mueve, tienes razón. Se mueve. Pero a tu favor, si haces el cambio a tiempo.

    Deja de medir tu jornada en líneas escritas. Empieza a medirla en decisiones acertadas, especificaciones claras y diffs bien revisados.

    Coge mañana una tarea aburrida y acotada —migrar un módulo, añadir tests a un servicio— y en vez de teclearla, especifícala y delégala. Luego siéntate a revisar el resultado como revisarías el pull request de un junior brillante pero despistado. Ahí, en esa revisión, es donde vas a hacer tu trabajo de senior a partir de ahora.

    Ese es el músculo nuevo. Y como todo músculo, se entrena.

    Si quieres ver este flujo completo montado de principio a fin —de la idea a un producto funcionando, especificando y delegando de verdad— es exactamente lo que construimos en el curso Construye con IA. Y si prefieres hacer el cambio acompañado, con proyectos reales y gente que ya está en esto, te espero en Dominicode Labs.

    El código dejó de ser el trabajo. El criterio para dirigirlo es el trabajo. Muévete hacia ahí.


    Preguntas frecuentes

    ¿La IA va a reemplazar a los programadores?

    No a los programadores con criterio. La IA reemplaza el tecleo, que era la parte mecánica del oficio, no el juicio. Un agente escribe código muy rápido, pero no decide qué construir, no diseña una arquitectura que aguante el tiempo ni sabe si su propia solución es mantenible. Lo que sí ocurre es que un developer que sabe orquestar, especificar y revisar hace el trabajo de varios que siguen escribiendo cada línea a mano. El riesgo no es la IA: es no adaptarse a usarla.

    ¿Necesito seguir aprendiendo a programar si la IA escribe el código?

    Sí, y hoy más que nunca. La IA escribe código, pero alguien tiene que leerlo, entenderlo y decidir si es correcto. No puedes aprobar un diff que no comprendes ni detectar un fallo de arquitectura si no sabes cómo debería estar construido. Saber programar deja de ser una habilidad de producción y pasa a ser una habilidad de criterio y revisión. Sin esa base, delegar en un agente es apostar a ciegas.

    ¿Por dónde empiezo a programar con IA?

    Por una tarea real, aburrida y acotada, no por un proyecto ambicioso. Coge algo que sepas hacer a mano en media hora —migrar un módulo, añadir tests, actualizar una dependencia—, escríbele una especificación clara al agente en lugar de un "hazme esto" y luego revisa el resultado línea a línea. Cuando eso te salga limpio, sube el listón. Trabajar primero la especificación y después delegar es la base de la metodología Spec-Driven Development, y es el orden que evita el caos.

    ¿Qué habilidades necesita hoy un developer?

    Tres que la IA no cubre. Criterio para decidir qué construir y qué no. Arquitectura para que las piezas encajen y el sistema sobreviva al paso del tiempo. Y capacidad de leer código ajeno —ahora, código generado— para revisarlo y aprobarlo con confianza. A eso se suma una habilidad nueva: saber especificar con precisión lo que quieres, porque todo lo que no le dices al agente, se lo inventa. El tecleo rápido ya no está en la lista.

    ¿Sigue haciendo falta un developer senior si la IA programa sola?

    Más que antes. La IA baja el coste de escribir código, lo que multiplica la cantidad de código que se genera y, con él, la superficie donde algo puede salir mal. Alguien tiene que poner criterio arquitectónico, revisar lo que produce el agente y frenar las decisiones que optimizan por cerrar la tarea a costa de la mantenibilidad. Ese trabajo es exactamente el de un senior. La IA no elimina ese rol: lo hace el más valioso del equipo.


    Por Bezael Pérez — Developer senior con más de 15 años de experiencia y fundador de Dominicode.

  • Spec-Driven Development (SDD): Evita el caos de la IA

    Spec-Driven Development (SDD): Evita el caos de la IA

    Hace unos meses un cliente me llamó desesperado. Habían decidido usar Cursor y Claude Code para acelerar el desarrollo de su nueva aplicación. El primer día escribieron 5.000 líneas de código y estaban maravillados con la velocidad.

    El segundo día, nada compilaba.

    El tercer día, la IA empezó a sobreescribir funciones previas, a alucinar APIs inexistentes y a meter bugs en bucle. Habían creado un monstruo de código spaghetti en tiempo récord.

    El problema no era la IA. El problema era que nadie le había dicho exactamente qué construir.

    Hoy te quiero explicar qué es Spec-Driven Development (SDD), la metodología de diseño que utilizo a diario para dar directrices claras a las IAs y evitar el caos en el código.


    El peligro de programar por "vibe coding"

    Cuando te sientas ante un editor como Cursor y le tiras prompts rápidos tipo "añade autenticación" o "agrega este formulario", estás haciendo vibe coding. La IA asume la arquitectura por su cuenta, inventa nombres de variables y adivina el modelo de datos.

    Esto funciona para landing pages sencillas, pero en proyectos reales produce tres efectos desastrosos:

    1. Código redundante: La IA vuelve a escribir funciones que ya existían porque no sabe dónde encontrarlas.
    2. APIs rotas: Se inventa endpoints que no coinciden con tu backend.
    3. Pérdida de control: El desarrollador deja de entender cómo funciona el sistema, convirtiéndose en un espectador pasivo.

    La solución no es dar mejores prompts conversacionales. La solución es dar especificaciones estructuradas.


    La regla de oro de SDD: Diseña antes de codificar

    La metodología Spec-Driven Development (SDD) establece que nunca debes dejar que un agente de IA escriba código hasta que haya aprobado un documento de diseño claro.

    Antes de tocar el teclado, debes estructurar tres archivos en la carpeta de especificaciones de tu proyecto:

    1. spec.md (La Especificación)

    Define la visión del producto, las reglas de negocio, los casos de uso y la arquitectura de datos. Responde al QUÉ se va a construir.

    2. plan.md (El Plan Técnico)

    Detalla la estrategia técnica paso a paso. Divide el desarrollo en fases incrementales y lógicas (por ejemplo, definir primero el esquema de base de datos antes de hacer la UI). Responde al CÓMO se va a construir.

    3. tasks.md (La Lista de Tareas)

    Una lista TODO detallada con tareas unitarias y autocontenidas. Cada tarea debe ser tan pequeña que la IA pueda completarla en una sola iteración y validarla con un test.


    El Flujo de Trabajo con tu Copiloto

    Una vez que tienes estos archivos, tu rol cambia de programador interactivo a director técnico:

    1. Le entregas el spec.md y el plan.md al agente de IA (ej: Claude Code).
    2. Le pides que lea las especificaciones y empiece a resolver la primera tarea del tasks.md.
    3. El agente implementa la tarea, corre los tests correspondientes y te avisa cuando está lista.
    4. Marcas la tarea como completada y pasas a la siguiente.

    Con este flujo, la IA no tiene que adivinar nada. Trabaja con un contrato de éxito claro y documentado.

    Este enfoque de ingeniería de software es el que trato en profundidad en mi libro de SDD: Spec-Driven Development, indispensable para cualquier desarrollador que quiera escalar sus desarrollos con IA en bucles agénticos u organizados. Además, es la metodología de base que aplicamos en todas las lecciones del curso de Construye con IA.


    Conclusión: La IA es el ejecutor, tú eres el arquitecto

    Delegar la escritura de código es seguro, pero delegar la arquitectura es un suicidio técnico. Al adoptar Spec-Driven Development, mantienes el control absoluto del diseño de tu software, reduces las alucinaciones de la IA a cero y multiplicas tu velocidad de desarrollo real.

    Si quieres aprender a estructurar tus specs y debatir sobre metodologías de ingeniería agéntica con otros desarrolladores senior, te espero en Dominicode Labs.


    Preguntas Frecuentes (FAQ)

    ¿Qué diferencia hay entre SDD y TDD?

    TDD (Test-Driven Development) se enfoca en escribir los tests unitarios antes que el código para guiar la implementación. SDD (Spec-Driven Development) va un paso más allá y exige redactar la especificación funcional y el plan técnico arquitectónico antes de escribir los tests o el código. Ambas metodologías se complementan perfectamente.

    ¿Por qué las especificaciones reducen las alucinaciones de la IA?

    Los LLMs tienden a alucinar cuando no tienen suficiente contexto o cuando las instrucciones son ambiguas. Un documento spec.md acota el espacio de decisiones que la IA debe tomar, forzándola a ceñirse a las reglas de negocio y arquitecturas declaradas en el archivo.

    ¿Cuánto tiempo toma escribir las especificaciones?

    Escribir un spec.md básico para una nueva feature suele tomar entre 15 y 30 minutos. Aunque parece un paso extra, te ahorra horas de depuración de código spaghetti mal estructurado por la IA en fases posteriores.

    ¿Se puede aplicar SDD a proyectos legacy o ya existentes?

    Sí. Al trabajar con código legacy, el primer paso es documentar el estado actual del componente afectado en un archivo de contexto (context.md) y redactar el spec.md detallando únicamente los cambios y adiciones a realizar, guiando a la IA sobre la base ya existente.


    Por Bezael Pérez — Developer senior con más de 15 años de experiencia y fundador de Dominicode.

  • SDD 2026: por qué el spec define tu ventaja competitiva

    SDD 2026: por qué el spec define tu ventaja competitiva

    Un cliente me mandó su proyecto hace tres semanas. Llevaba dos meses usando Claude Code todos los días. El repositorio tenía 340 archivos. Tenía features. Tenía tests. El código compilaba.

    Y no tenía ni idea de qué hacía el sistema.

    Me preguntó: “¿Por qué cada vez que añado algo nuevo, rompo tres cosas que ya funcionaban?” La respuesta era visible desde el primer git log: llevaba dos meses pidiéndole a la IA que generara código sin decirle nunca qué estaba construyendo realmente. Cada prompt era una instrucción táctica. Nunca había una visión. Nunca un mapa.

    Eso es Spec-Driven Development (SDD) al revés. Y en 2026, con agentes que pueden escribir mil líneas en minutos, la diferencia entre los dos modos es la diferencia entre un producto y un desastre con tests.


    La IA no necesita que seas más rápido. Necesita que seas más claro.

    La narrativa que se vende sobre el desarrollo con IA es esta: “ahora puedes construir el doble de rápido”. Es verdad. El problema es que construir el doble de rápido sin dirección no te lleva antes a destino — te lleva el doble de lejos en la dirección equivocada.

    Los agentes de IA son ejecutores extraordinariamente potentes con cero criterio arquitectónico propio. Claude Code, GitHub Copilot, Cursor, cualquiera — siguen instrucciones. Si las instrucciones son vagas, el output es coherente localmente e incoherente globalmente. Cada archivo tiene sentido en sí mismo. El sistema entero no tiene sentido como conjunto.

    El spec no es documentación. No es burocracia. Es la única forma de darle a un agente de IA el contexto suficiente para que sus decisiones locales sean coherentes con la visión global.

    Sin spec, el agente está adivinando constantemente. Y adivina bien, frase a frase. Pero adivinar bien frase a frase no produce un párrafo con sentido — produce contenido que parece correcto y no lleva a ningún lado.


    Qué es SDD y por qué no es lo que crees

    Spec-Driven Development no es escribir documentación antes de programar. Eso es lo que la mayoría imagina y por lo que lo descartan: “ya tengo suficiente trabajo sin añadir Word docs al proceso”.

    SDD es una metodología de tres artefactos que define qué construyes, cómo lo construyes y en qué orden lo construyes — antes de que un solo agente escriba una sola línea de código.

    Los tres artefactos son:

    spec.md — el qué. La especificación estructurada del sistema. Tiene seis secciones fijas: Visión, Usuarios, Funcionalidades, Flujos, Arquitectura, NFRs. En total, tres o cuatro páginas que responden a la pregunta que ningún agente puede responder por ti: qué problema resuelves exactamente, para quién, y qué significa “hecho” en este proyecto.

    plan.md — el cómo. El plan técnico por fases. No divide el trabajo en tareas sueltas — divide el trabajo en capas que tienen sentido en secuencia. Primero el dominio, después la infraestructura, después la UI. No al revés. El plan.md es el documento que evita que empieces por la pantalla de login cuando el sistema de autenticación aún no existe.

    tasks.md — el orden. La lista de tareas ordenada para TDD. Cada tarea define qué test escribes primero y qué código lo hace pasar. El tasks.md convierte el plan en commits atómicos verificables. Cuando un agente ejecuta una tarea del tasks.md, el resultado es predecible: un test verde y un incremento de funcionalidad real.

    Estos tres documentos no tardan tres días en escribirse. Con el skill /dominicode-sdd-spec-creator en Claude Code (disponible para miembros de Dominicode Labs), la estructura completa se genera en minutos a partir de una descripción del proyecto. Lo que tarda tiempo es pensar — y ese tiempo es exactamente el que te ahorra deuda técnica después.


    Antes vs después: el mismo proyecto, dos formas de empezar

    Hace unos meses construí un sistema de gestión de contenido para automatizar la publicación en múltiples canales. El proyecto tenía integraciones con tres APIs externas, lógica de colas, transformaciones de formato y un dashboard de seguimiento.

    Sin SDD (como lo hubiera hecho en 2022): Habría abierto el editor, creado una carpeta src/, y empezado por la parte que más me apetecía — probablemente el dashboard. A las dos semanas tendría un dashboard bonito conectado a datos hardcodeados, una integración con una API que funcionaba en happy path, y ninguna certeza de cómo conectar las piezas. Cada decisión técnica habría sido local, sin visión del sistema completo.

    Con SDD: Antes de escribir código, escribí el spec.md. La sección de Flujos me forzó a pensar en qué pasa cuando una API falla en mitad de una publicación — algo que no habría considerado hasta toparme con el bug en producción. La sección de NFRs me hizo definir qué latencia máxima era aceptable para el sistema de colas. La sección de Arquitectura me hizo elegir entre evento-driven y polling antes de escribir nada — no a mitad del proyecto cuando cambiar de dirección cuesta semanas.

    El spec.md tardó dos horas. El plan.md, una hora más. El tasks.md, otra hora.

    Cuatro horas de especificación que eliminaron tres semanas de refactoring posterior.

    Cuando empecé a usar Claude Code en el proyecto, el agente tenía el spec.md en el contexto. Cada decisión técnica que tomaba era coherente con la arquitectura definida. No porque el LLM sea mágicamente más inteligente con un documento — sino porque el documento le daba información que de otra forma no tenía.


    El spec como brújula del agente

    Este es el cambio de mentalidad que más cuesta hacer: el spec no es para ti. Es para el agente.

    Cuando llevas quince años programando, tu cabeza tiene el contexto del proyecto. Sabes por qué elegiste ese patrón. Sabes qué módulo toca qué. Sabes los trade-offs que hiciste en la semana dos. Ese contexto vive en tu cabeza y lo das por supuesto.

    El agente no tiene nada de eso. Sin contexto explícito, cada sesión empieza desde cero. Cada prompt es una petición descontextualizada si no le das el marco. Sin spec, el agente responde a lo que le preguntas — no a lo que necesitas construir.

    Con el spec.md en contexto, el agente puede hacer preguntas que de otra forma no haría: “esta funcionalidad que me pides entra en conflicto con el flujo de usuario número tres que está en el spec — ¿quieres cambiar el flujo o ajustar la funcionalidad?”. Esa pregunta vale más que mil líneas de código generado sin contexto.

    Esta es exactamente la lógica detrás del libro Spec-Driven Development — no es un manual de documentación, es una metodología diseñada para que el agente tenga suficiente contexto para tomar decisiones correctas sin que tú estés micromanageando cada prompt.


    Por qué el spec te protege del vibe coding

    El vibe coding no es programar con IA. Es programar con IA sin criterio. Hay developers que publican proyectos enteros generados en un fin de semana. Impresionante en superficie. Inutilizable en producción.

    El problema del vibe coding no es la velocidad — es la ausencia de coherencia acumulada. Cada prompt genera código coherente con el prompt anterior, pero nadie garantiza que el sistema resultante sea coherente con la intención original. A las cuatro horas de vibe coding, el proyecto tiene forma de algo pero no tiene diseño. Tiene features pero no tiene arquitectura.

    Lo que se acumula en silencio no es código malo — es deuda técnica agéntica. El tipo de deuda que no se ve en los tests porque los tests también los generó el agente sin un contrato claro de qué probar. El tipo de deuda que explota cuando intentas añadir la feature número veinte sobre una base que asumió implícitamente cosas que nunca se definieron.

    Para entender por qué la arquitectura de tus agentes necesita un spec detrás, te recomiendo el post sobre agentic harness: por qué la spec y la arquitectura no bastan.

    SDD es el antídoto no porque ralentice el desarrollo. Lo acelera — pero acelera el desarrollo en la dirección correcta. La spec es el contrato que el agente respeta en cada iteración. El plan es la secuencia que evita que construyas la décima planta antes de los cimientos. El tasks.md son los commits que puedes revisar, aprobar y revertir si algo no cuadra.

    Con SDD, el vibe coding se convierte en agile coding con contexto — velocidad de agente, criterio de arquitecto.


    Cómo empezar con SDD en Claude Code hoy

    Si tienes Claude Code y quieres aplicar SDD en tu próximo proyecto, el proceso es directo:

    1. Describe tu proyecto en lenguaje natural — qué construyes, para quién, qué problema resuelve.
    2. Ejecuta el skill /dominicode-sdd-creator — genera spec.md, plan.md y tasks.md en pocos minutos (disponible en Dominicode Labs).
    3. Revisa el spec antes de tocar código — es el momento de pensar, no después.
    4. Añade el spec.md al contexto de Claude Code con @spec.md al inicio de cada sesión de desarrollo — la documentación oficial de Claude Code explica cómo gestionar el contexto entre sesiones.
    5. Trabaja el tasks.md en secuencia — un task, un test, un commit.

    El skill no reemplaza tu pensamiento. Te obliga a pensar antes de que sea costoso cambiar de dirección.

    El post sobre SDD Creator, la herramienta CLI muestra exactamente cómo se genera la estructura automáticamente.

    Si quieres ver cómo se aplica esto en un proyecto real de principio a fin — desde la spec inicial hasta el deploy — es exactamente lo que trabajamos en el curso Construye con IA: no tutoriales sueltos de herramientas, sino el proceso completo de construir un producto con IA de forma que funcione en producción.


    El spec como ventaja competitiva real

    Hay algo que nadie dice sobre SDD en 2026 y que merece decirse.

    En un mundo donde cualquier developer puede generar código a gran velocidad con IA, la diferencia competitiva no está en quién genera más rápido. Está en quién sabe exactamente qué construir y por qué.

    El spec es donde vive esa ventaja. No en el prompt. No en la elección del modelo. En la claridad con la que defines el problema antes de que empiece la ejecución.

    Los developers que entienden esto ya no compiten con los que “usan IA para programar más rápido”. Son una categoría diferente: developers que combinan criterio técnico con capacidad de ejecución agéntica. El spec es la expresión concreta de ese criterio.

    Dentro de doce meses, los equipos que hayan integrado SDD en su workflow tendrán bases de código mantenibles, documentación generada como efecto colateral del proceso, y la capacidad de incorporar nuevos agentes o nuevos developers sin que el proyecto colapse. Los que sigan con vibe coding habrán reescrito el proyecto tres veces.


    FAQ

    ¿SDD no es simplemente documentación con otro nombre?

    No. La documentación describe lo que existe. El spec define lo que va a existir — antes de que exista. La diferencia no es semántica: la documentación se escribe después y siempre está desactualizada. El spec se escribe antes y guía la implementación. Si el spec y el código divergen durante el desarrollo, es señal de que hay una decisión técnica que tomar conscientemente — no de que el documento esté equivocado.

    ¿Cuánto tiempo tarda escribir el spec de un proyecto real?

    Depende del proyecto. Para un MVP de funcionalidad acotada, entre dos y cuatro horas. Para un sistema con múltiples integraciones y flujos complejos, un día. El punto de referencia útil: si el spec tarda más de un día en escribirse, es señal de que el proyecto no está suficientemente definido para empezar a construirlo — y ese es el momento exacto en que el spec te está salvando, no ralentizando.

    ¿Se puede aplicar SDD a proyectos que ya existen?

    Sí, pero el proceso es diferente. En proyectos existentes, el spec se usa para nuevas features o para refactorizaciones significativas. El ejercicio de escribir el spec de un módulo existente es también un audit implícito: si no puedes escribir el spec del módulo, es porque el módulo no tiene diseño coherente. El spec revela la deuda técnica que el código oculta.

    ¿SDD funciona con cualquier agente de IA o solo con Claude Code?

    La metodología es agnóstica al agente. Spec.md, plan.md y tasks.md son documentos markdown que cualquier LLM puede usar como contexto. El skill /dominicode-sdd-spec-creator está diseñado para Claude Code y disponible en Dominicode Labs, pero los artefactos que genera son compatibles con cualquier entorno. Lo importante no es la herramienta — es el hábito de definir antes de ejecutar.

    ¿Qué pasa cuando el spec cambia durante el desarrollo? ¿No es todo ese trabajo en vano?

    El spec cambia. Siempre cambia. Y eso es una funcionalidad, no un fallo. Cuando el spec cambia, tienes un documento que actualizar — y esa actualización fuerza una decisión consciente sobre el impacto del cambio en la arquitectura, los flujos y las tareas pendientes. Sin spec, el cambio ocurre de forma invisible: alguien pide algo diferente, el agente lo implementa, y nadie sabe qué asunciones antiguas quedan rotas. Con spec, el cambio es visible y gestionable.

    ¿Es SDD compatible con metodologías ágiles?

    Completamente. SDD no impone un ciclo de desarrollo — impone un hábito de especificación antes de ejecución. Dentro de un sprint de dos semanas, el spec de las features del sprint se escribe al inicio. El plan.md define el orden de implementación dentro del sprint. El tasks.md genera los tickets concretos. SDD convierte el backlog en artefactos ejecutables para agentes, no en listas de deseos sin criterio técnico.


    Por Bezael Pérez — Developer senior con más de 15 años de experiencia y fundador de Dominicode.

  • El Harness: por qué la spec y la arquitectura no son suficientes

    El Harness: por qué la spec y la arquitectura no son suficientes

    Mi workflow completo: de idea a producto en producción con IA

    Hace un año tardaba 2-3 semanas en tener algo desplegado desde una idea nueva.

    Hoy tardo 2-3 días.

    No porque use mejores modelos. Porque cambié el workflow.

    Acá está el proceso completo, sin omitir nada.


    Fase 1 — Captura (30 minutos)

    Antes de abrir el editor, abro un documento en blanco y respondo tres preguntas:

    1. ¿Qué problema concreto resuelve esto?
    2. ¿Quién lo va a usar y en qué contexto exacto?
    3. ¿Qué tiene que funcionar sí o sí para que sea útil desde el día uno?

    Solo eso. Sin pensar en tech stack. Sin pensar en arquitectura.

    Si no puedo responder las tres en 30 minutos, la idea no está lista para construirse.


    Fase 2 — Spec (1-2 horas)

    Con las respuestas anteriores, genero la spec técnica.

    La spec tiene 6 secciones: Visión, Usuarios, Funcionalidades, Flujos, Arquitectura y NFRs.

    No la escribo yo desde cero. La genero con un agente que toma mis respuestas de la Fase 1 como input.

    Luego la reviso y ajusto lo que el agente asumió mal.

    El output: un documento de 2-3 páginas que define qué se construye, para quién, y cómo debe comportarse.


    Fase 3 — Plan técnico (30 minutos)

    Con la spec lista, otro agente genera el plan de implementación.

    No “empieza a codear”. Define:

    • Las fases del proyecto en orden
    • Qué necesita estar listo antes de cada fase
    • Los riesgos técnicos por módulo

    Reviso el plan. Lo ajusto si algo no tiene sentido. Firma.


    Fase 4 — Implementación (el grueso)

    Aquí entra Claude Code.

    No le doy el prompt “hazme la app”. Le doy la spec + el plan + el task específico a implementar en esa sesión.

    Un task. Una sesión. Un output verificable.

    Si el task es “implementar autenticación con GitHub OAuth”, eso es todo lo que hace esa sesión.

    Al final de cada sesión, verifico que lo que se construyó cumple el criterio de aceptación de la spec.

    Si no lo cumple, corrijo antes de avanzar. No acumulo deuda de contexto.


    Fase 5 — Deploy y validación (1-2 horas)

    Deploy con el stack que use el proyecto (Railway, Vercel, Supabase).

    Luego muestro el producto a 2-3 personas del perfil objetivo y les hago una sola pregunta:

    “¿Qué haría que esto fuera indispensable para ti?”

    No “¿te gusta?” ni “¿qué mejorarías?”.

    Esa pregunta específica te da el siguiente ciclo de iteración o te dice que pivotes.


    Lo que hace que este workflow funcione no es la IA.

    Es que la IA nunca opera sin contexto estructurado.

    Cada agente recibe exactamente lo que necesita para hacer su parte. Nada más. Nada menos.

    Sin eso, la IA improvisa. Y cuando improvisa, construye lo que interpreta, no lo que necesitas.


    Si quieres ver este workflow ejecutado en vivo sobre un proyecto real — Stripe webhook receiver + Supabase, desde la spec hasta el deploy — eso es exactamente lo que hacemos el 9 de julio.

    workshop.dominicode.com

  • sdd-creator: genera spec, plan y tasks con cualquier agente IA

    sdd-creator: genera spec, plan y tasks con cualquier agente IA

    Llevaba tres horas implementando un sistema de autenticación con JWT cuando me di cuenta de que no había especificado nada.

    ¿El token debía expirar en la sesión o persistir entre reinicios? ¿Qué pasaba cuando el refresh token vencía estando el usuario activo? ¿El endpoint de logout invalidaba en servidor o solo limpiaba el cliente?

    Yo respondí esas preguntas sobre la marcha. Sin coherencia, sin registro de decisiones. El código resultó funcional pero arquitectónicamente un desastre.

    Eso no es un problema del agente. Es un problema de proceso. Para eso existe sdd-creator.


    El problema de codear sin especificar

    Los agentes de IA son extremadamente buenos ejecutando instrucciones. También son extremadamente buenos ejecutando instrucciones mal definidas — y el resultado es lo que imaginas.

    Cuando le das a Claude Code o a Cursor un prompt del tipo “implementa login con JWT”, el agente toma decisiones. Muchas. Las toma rápido, sin preguntarte, porque así trabajan. El output es código funcional que responde a una interpretación del problema, no necesariamente a tu interpretación.

    El fallo no está en la IA. Está en que nunca estableciste qué querías exactamente.

    Spec-Driven Development (SDD) resuelve esto con una premisa simple: antes de generar código, genera el spec. Un documento que responde qué hace la feature, por qué existe, quién la usa, qué flujos cubre y bajo qué criterios está terminada.

    El problema es que hacer bien un spec lleva disciplina. Y cuando tienes el agente abierto y las ganas de construir, la tentación de saltártelo es enorme.


    Qué es sdd-creator y cómo funciona

    sdd-creator es un skill para agentes de IA que impone el proceso de especificación antes de ejecutar cualquier implementación. No es un generador de documentos — es un interrogador. El agente no escribe código hasta que el spec esté completo y confirmado.

    A diferencia de pedirle directamente al agente que “genere un spec libre”, sdd-creator impone siempre las mismas 6 secciones y bloquea la implementación hasta recibir confirmación explícita. Sin esa estructura, los specs se convierten en párrafos de texto libre que el agente interpreta como quiere.

    El flujo tiene siete pasos:

    1. Describes el feature o proyecto que quieres construir
    2. sdd-creator detecta la complejidad (LOW / MEDIUM / HIGH)
    3. Te hace una entrevista interactiva — te pregunta lo que no especificaste
    4. Genera spec.md con 6 secciones estructuradas
    5. Espera tu confirmación antes de continuar
    6. Genera plan.md con las decisiones técnicas y la planificación por fases
    7. Genera tasks.md con las tareas ordenadas para TDD — y solo entonces empieza la implementación

    El repositorio está en GitHub: bezael/sdd-creator — MIT, v1.2.0.

    Si quieres entender la metodología detrás con más profundidad, el libro SDD cubre los principios completos, con patrones reales de proyectos en producción.


    Instalación

    Una sola línea:

    npx skills@latest add bezael/sdd-creator

    El CLI detecta tu herramienta y copia el skill al directorio correcto automáticamente. Como referencia, los directorios destino son:

    • Claude Code: ~/.claude/skills/
    • Cursor: .cursor/rules/ del proyecto

    No hay configuración adicional. No hay API keys. No hay dependencias de runtime. El skill vive como un archivo de instrucciones que el agente carga en contexto cuando lo invocas.

    Para instalación manual o integración con otros agentes, consulta la documentación oficial de Claude Code o los docs de tu herramienta.


    Tutorial paso a paso — feature de login con JWT

    Vamos con un ejemplo concreto. Tienes una app NestJS y quieres implementar autenticación con JWT. Sin sdd-creator, abres el agente y escribes: “implementa autenticación con JWT”. Con sdd-creator, el proceso es diferente.

    Paso 1 — Invoca el skill

    En Claude Code o en Cursor, activa sdd-creator. Luego describe tu feature:

    Quiero implementar un sistema de autenticación con JWT para una API NestJS.
    Incluye registro, login, refresh de token y logout.

    Paso 2 — La entrevista interactiva

    sdd-creator detecta complejidad media y empieza a preguntarte:

    • ¿El token de acceso expira en cuánto tiempo?
    • ¿El refresh token se invalida en servidor o solo en cliente?
    • ¿El endpoint de logout invalida todos los dispositivos activos o solo el actual?
    • ¿La app requiere rate limiting en los endpoints de auth?
    • ¿Los usuarios pueden tener múltiples sesiones simultáneas?

    Preguntas incómodas. Preguntas que el agente habría respondido solo — con su mejor criterio — si no le hubieras forzado a preguntarte.

    Paso 3 — Confirmas el spec.md

    El agente genera el spec.md completo. Lo revisas, corriges lo que no cuadra, y confirmas. Solo entonces avanza.

    Paso 4 — plan.md y tasks.md

    sdd-creator genera el plan técnico (decisiones de arquitectura, librerías, estructura de módulos) y la lista de tareas ordenadas para TDD. Primero los tests de los casos de error — token expirado, credenciales inválidas, refresh token revocado. Luego el código que los hace pasar.

    Resultado: el agente implementa exactamente lo que especificaste. Sin sorpresas. Sin decisiones implícitas. Sin “lo hice así porque parecía razonable”.


    Los 3 archivos que genera

    spec.md — La especificación en 6 secciones

    La estructura es fija e invariable:

    1. Visión — qué problema resuelve y por qué existe esta feature
    2. Usuarios — quién la usa y cuáles son sus necesidades reales
    3. Funcionalidades — qué puede hacer el sistema (listado concreto)
    4. Flujos — cómo se comporta el sistema en los escenarios principales
    5. Arquitectura — cómo está organizado técnicamente
    6. NFRs — requisitos no funcionales: performance, seguridad, disponibilidad

    La estructura fija es deliberada. Cuando el spec siempre tiene las mismas 6 secciones, puedes revisarlo en segundos y saber exactamente qué falta. Un spec libre en prosa no tiene esa propiedad.

    Si quieres ver cómo aplicar estas 6 secciones en un proyecto greenfield completo, este post sobre SDD con slices verticales lo cubre en detalle.

    plan.md — Las decisiones técnicas

    El plan responde: ¿cómo vamos a construir esto? Librerías seleccionadas y por qué. Estructura de módulos. Fases de implementación. Dependencias entre componentes. Riesgos identificados.

    No es un documento académico — es el registro de las decisiones que tomarías antes de empezar, aunque fueran en tu cabeza. Externalizar ese razonamiento tiene valor: el agente lo usa como referencia durante la implementación, y tú lo usas para hacer review.

    tasks.md — La lista ordenada para TDD

    Las tareas están ordenadas para Test-Driven Development. Los tests de los contratos del sistema van primero. El código que los satisface, después. Cada tarea es atómica — una sola responsabilidad, verificable por sí sola.

    Cuando tienes esta lista, puedes darle una tarea al agente y pedirle que haga solo esa. Sin divagar. Sin añadir “mejoras” que no pediste. La tarea acotada, con su test, con su criterio de aceptación.

    Esta es exactamente la forma de trabajar que desarrollamos en el curso Construye con IA — de la idea al producto real, con agentes IA y sin perder el control del código.


    Cuándo NO usar sdd-creator

    sdd-creator añade valor cuando el problema tiene suficiente complejidad para merecer una especificación. Hay casos donde el overhead no compensa:

    • Scripts de un solo uso: automatizaciones de 20-30 líneas que se ejecutan una vez y se descartan
    • Prototipos desechables: experimentos para validar si algo es técnicamente posible, sin intención de iterar sobre el código
    • Hotfixes triviales: corregir un typo, cambiar un color, ajustar un literal de texto

    La regla práctica: si el feature va a producción y va a ser mantenido, usa sdd-creator. Si es exploración o descarte, ve directo al código.


    Compatible con cualquier agente de IA

    sdd-creator no está atado a un agente específico. Funciona con todos los entornos de desarrollo con IA más usados:

    Agente Tipo de integración Directorio
    Claude Code Skills nativo ~/.claude/skills/
    Cursor Rules .cursor/rules/ del proyecto
    Codex CLI (OpenAI) AGENTS.md / system prompt Configuración de proyecto
    Gemini CLI System prompt Configuración de proyecto
    Aider Contexto personalizado .aider.conf.yml
    Continue config.json .continue/

    El formato MIT también significa que puedes adaptarlo a tu equipo. Si tienes convenciones de nomenclatura propias, o secciones adicionales en tus specs, puedes forkear el repositorio y ajustarlo.


    FAQ

    ¿Qué es sdd-creator?

    sdd-creator es un skill para agentes de IA que implementa el flujo de Spec-Driven Development. Cuando lo activas, el agente no escribe código directamente — primero te hace una entrevista para entender el problema, luego genera tres documentos estructurados (spec.md, plan.md, tasks.md), y solo después implementa. Es la diferencia entre darle instrucciones a un agente y darle una especificación.

    ¿Con qué agentes de IA funciona sdd-creator?

    Con Claude Code, Cursor, Codex CLI (OpenAI), Gemini CLI, Aider y Continue. El skill es un archivo de instrucciones, no una integración específica — cualquier agente que soporte archivos de contexto puede usarlo. La instalación varía: en Claude Code se copia a ~/.claude/skills/, en Cursor va a .cursor/rules/.

    ¿Cuánto tiempo lleva generar la spec con sdd-creator?

    Entre 5 y 20 minutos, dependiendo de la complejidad del feature. Una feature simple puede especificarse en 5 minutos. Una feature con múltiples flujos, integraciones externas y requisitos de seguridad puede tomar 20. Ese tiempo es siempre menor que el que cuesta refactorizar código que el agente implementó sin especificación.

    ¿Es sdd-creator compatible con proyectos legacy?

    Sí. SDD no requiere empezar desde cero — puedes aplicarlo feature a feature sobre una base de código existente. El spec refleja las restricciones reales del sistema existente: qué puedes cambiar, qué no, y qué deuda técnica tienes que tener en cuenta durante la implementación.

    ¿Puedo usar sdd-creator en equipos?

    Sí, y es donde más valor aporta. El spec.md generado es el contrato de la feature — cualquier miembro del equipo puede revisarlo, cuestionarlo y aprobarlo antes de que empiece la implementación. Elimina el “yo entendí que…” de las reuniones de review.


    Ahora, cuando tengo el agente abierto y las ganas de construir, lo primero que activo es sdd-creator. Los 15 minutos de spec se pagan solos. Esas tres horas de JWT no se van a repetir.

    Si quieres ver cómo SDD encaja en el ciclo completo de desarrollo con IA — desde la idea hasta el producto desplegado — en Dominicode Labs tienes acceso a proyectos reales donde aplicamos este flujo de principio a fin.

    Por Bezael Pérez — Fundador de Dominicode.

  • Vibe coding sin sistema: por qué tu proyecto con IA se rompe

    Vibe coding sin sistema: por qué tu proyecto con IA se rompe

    La primera semana fue increíble.

    Abriste Claude Code, describiste la idea a grandes rasgos, y el proyecto arrancó. En dos horas tenías rutas funcionando. En cuatro tenías la autenticación. En un día, un prototipo que podías enseñar. Sentiste que habías desbloqueado algo — que la IA era la ventaja que llevabas buscando.

    La segunda semana empezaron las grietas. Añadiste una feature nueva y rompiste una que ya funcionaba. Pediste al modelo que corrigiera el bug y generó código con una convención de nombres distinta a la del resto del proyecto. Abriste el archivo equivocado porque en una sesión le pusiste un nombre y en otra, otro.

    La tercera semana dejaste de entender tu propio proyecto.

    Esto no es un problema de la IA. Es el resultado predecible del vibe coding sin sistema — y hay una salida que no implica empezar desde cero.


    El ciclo que reconocerás si llevas más de dos semanas con IA

    El vibe coding tiene un patrón muy concreto. Arranca con energía, avanza rápido, y luego se convierte en deuda que nadie quiere pagar.

    Semana 1 — La euforia del prototipo. El modelo genera código que funciona. Tú describes lo que quieres, él lo construye. Cada sesión termina con algo nuevo encima de la mesa. Sientes que puedes construir cualquier cosa.

    Semana 2 — Los primeros síntomas. Añadir una feature empieza a costar más de lo esperado. El modelo genera código que no encaja del todo con lo que ya existe — naming diferente, estructura diferente, patrones distintos. Cada sesión nueva es ciega respecto a las decisiones de la anterior.

    Semana 3 — El colapso. El proyecto tiene capas que se contradicen entre sí. No puedes explicarle a nadie la arquitectura — ni siquiera a la IA que lo construyó. Cada sesión nueva te exige re-explicar el contexto desde cero. Y cuando lo haces, el modelo entiende una versión diferente de lo que tienes.

    Aquí hay dos salidas que la mayoría elige: abandonar el proyecto o empezar desde cero con la promesa de “esta vez lo haré mejor”. Ninguna funciona porque el problema no es el punto de partida. Es la ausencia de sistema.


    Por qué el vibe coding escala mal

    Por defecto, la IA no carga el estado de sesiones anteriores. Aunque herramientas como Claude Projects permiten persistir algo de contexto entre conversaciones, ese contexto no es estructurado — no sabe que decidiste usar repositorios en lugar de servicios directos, ni recuerda que el módulo de usuarios tiene una estructura específica, ni que descartaste la opción B el martes porque tenía un problema de concurrencia.

    Lo que el modelo construye en cada sesión es una respuesta razonable al contexto que le das en ese momento. Sin especificación, sin arquitectura documentada, sin contexto persistente, ese contexto siempre es incompleto. Y el modelo completa los huecos con sus propias suposiciones — razonables para un proyecto genérico, incorrectas para el tuyo.

    El resultado es código construido sobre arena. Cada sesión añade una capa nueva que puede o no ser compatible con lo que ya existe. Con el tiempo, la incoherencia se acumula hasta que el proyecto es incomprensible — no porque sea complejo, sino porque nadie tomó decisiones explícitas.

    Esto no es un defecto del modelo. Es una consecuencia directa de cómo usamos el modelo.


    Los 3 síntomas de que tu proyecto está en modo vibe

    Antes de hablar de la solución, vale la pena identificar dónde estás. Estos tres síntomas aparecen en orden: si tienes los tres, el proyecto ya necesita intervención.

    Naming inconsistente entre archivos. Un archivo se llama user-service.ts, otro usersService.ts, otro UserManager.ts. Las variables que representan el mismo concepto tienen nombres distintos según la sesión en que se crearon. El proyecto habla idiomas distintos en cada carpeta.

    Tests que no prueban lo que dicen. Los tests existen — el modelo siempre los genera cuando se los pides — pero prueban el código tal como fue escrito en ese momento, no el comportamiento que el sistema debería tener. Cuando el código cambia, los tests se rompen de formas que no esperabas. O peor: siguen en verde porque prueban implementación, no contrato.

    No puedes explicar la arquitectura de tu propio proyecto. Este es el síntoma definitivo. Si le preguntas al modelo “¿cuál es la arquitectura de este proyecto?” y la respuesta que genera no coincide con lo que tienes, tienes un problema de contexto. Si tú mismo no puedes describir en dos párrafos cómo fluyen los datos de principio a fin, el proyecto ya está en modo vibe terminal.

    Si reconoces los tres, no significa que tengas que tirar el código. Significa que tienes que añadir lo que falta: sistema.


    El sistema que reemplaza al vibe

    Pasar del vibe coding al desarrollo con sistema no es abandonar la IA. Es usarla de forma diferente — con estructura que la hace más efectiva, no más lenta.

    El sistema tiene cuatro piezas. No son opcionales entre sí.

    1. Spec antes de código (SDD)

    La especificación no es un documento burocrático. Es la respuesta a: ¿qué estoy construyendo exactamente, para quién, y cómo fluye la información?

    Con Spec-Driven Development, la spec se escribe antes de abrir el editor. No porque sea una regla, sino porque un modelo que recibe una spec bien escrita genera código diez veces más coherente que uno al que le describes la idea de viva voz. La spec define los contratos. El modelo los implementa. El espacio de decisión se reduce y el output es predecible.

    2. Contexto persistente (CLAUDE.md)

    El CLAUDE.md en la raíz del proyecto es el system prompt que Claude Code lee al inicio de cada sesión. Contiene el stack, las convenciones de naming, las restricciones explícitas y el estado actual del proyecto. No es documentación — es la memoria estructurada que el modelo necesita para ser consistente. En otros entornos como Cursor o Windsurf, el concepto equivalente existe con distintos nombres (.cursor/rules/, AGENTS.md).

    Sin este archivo, cada sesión es ciega. Con él, cada sesión arranca desde el mismo punto de partida. Las decisiones tomadas en día 1 siguen vigentes en día 30. Aquí tienes cómo estructurar este archivo paso a paso si quieres implementarlo hoy.

    3. Tareas pequeñas (chunking)

    “Implementa el sistema de autenticación completo” es el tipo de prompt que genera código plausible pero incoherente con tu proyecto. El modelo toma demasiadas decisiones implícitas porque el scope es demasiado amplio.

    La regla es: una tarea por sesión, un contrato por tarea. En lugar de pedir la autenticación completa, pides el esquema de usuario, luego el endpoint de login, luego el middleware de validación. Cuatro sesiones. Cuatro piezas que encajan porque cada una tiene un contexto explícito y un alcance controlado.

    4. Validación continua

    Al final de cada sesión, pides al modelo un resumen: qué se implementó, qué decisiones se tomaron, qué queda pendiente. Ese resumen va a un session-log.md con fecha. La sesión siguiente empieza con ese log como contexto. No empiezas desde cero — empiezas desde donde lo dejaste.

    El context engineering es la disciplina que une estas cuatro piezas. No es un concepto teórico — es la práctica concreta de gestionar qué información recibe el modelo en cada momento.


    Cómo hacer la transición sin empezar desde cero

    Este es el punto donde la mayoría para: “mi proyecto ya es un caos, tendría que reescribirlo todo”. No.

    La transición tiene cinco pasos y los puedes empezar hoy con el código que tienes.

    Paso 1 — Audita lo que existe. Antes de añadir nada, entiende el estado real del proyecto. Pídele al modelo que lea tu estructura de carpetas y te describa la arquitectura que ve. Compara esa descripción con lo que creías que habías construido. La brecha entre las dos es tu deuda de contexto.

    Paso 2 — Genera la spec retroactiva. No necesitas escribir la spec desde cero — puedes generarla a partir del código existente. Dale al modelo el contexto actual y pídele que genere una spec de lo que existe: entidades, contratos, flujos. Esa spec se convierte en la verdad oficial del proyecto, no el código.

    Paso 3 — Crea el CLAUDE.md. Con la spec en mano, crea el archivo de contexto persistente. Incluye el stack real (no el ideal), las convenciones que ya están en el código aunque no estuvieran documentadas, y las restricciones que te habría gustado tener desde el principio. Esto es lo que normaliza el naming y la estructura en todas las sesiones futuras.

    Paso 4 — Divide lo que queda en tareas pequeñas. El backlog de features pendientes deja de ser una lista de ideas y pasa a ser una lista de contratos. Cada tarea tiene una descripción concreta: qué recibe, qué devuelve, cómo interactúa con lo existente. El modelo implementa contratos, no ideas.

    Paso 5 — Valida antes de seguir. Antes de añadir la siguiente feature, escribe o genera los tests del contrato de la feature actual. No para cubrir el código — para verificar el comportamiento. Si el test falla cuando cambias algo que no debería afectarlo, el test te está diciendo que el contrato no estaba claro.

    Son cinco pasos que se pueden hacer en una tarde si el proyecto no es demasiado grande. El resultado no es un proyecto perfecto — es un proyecto con el que puedes volver a trabajar con confianza.


    La diferencia que importa en producción

    El vibe coding no es malo. Es la herramienta correcta para el momento incorrecto.

    Para validar una idea en 48 horas, el vibe coding es insuperable. Para construir algo que tendrás que mantener en semanas 4, 8 y 16, es un problema en espera de ocurrir.

    La diferencia entre un developer que usa IA con efectividad y uno que acaba atascado no es el modelo que usan, ni el IDE, ni los prompts. Es si tienen sistema o no. Si cada sesión nueva añade coherencia al proyecto o añade caos.

    El sistema no frena la velocidad de la IA. La mantiene en el tiempo.

    Si quieres ver esto aplicado en proyectos reales — desde la spec inicial hasta el producto funcionando, con CLAUDE.md, SDD y Claude Code — el curso Construye con IA: de la idea al producto cubre exactamente ese flujo. Y si quieres trabajar la transición con proyectos concretos y feedback en comunidad, en Dominicode Labs hacemos exactamente eso.


    FAQ

    ¿El vibe coding sirve para algo?

    Sí, y mucho. El vibe coding es la herramienta perfecta para prototipar ideas rápido — para validar si algo es técnicamente posible, para hacer demos, para explorar una API que no conoces. El problema no es el vibe coding en sí, sino usarlo para construir algo que vas a mantener durante semanas o meses. En ese contexto, la ausencia de sistema convierte la velocidad inicial en deuda que pagas después con intereses.

    ¿Cuándo está bien improvisar?

    Siempre que el objetivo sea explorar, no construir. Si abres una sesión nueva para entender cómo funciona un nuevo framework, para probar una librería, o para validar si tu idea de arquitectura tiene sentido — improvisa sin culpa. El momento en que decides que algo va a producción o que tendrás que volver a ello en una semana, el sistema tiene que entrar.

    ¿Tengo que empezar desde cero si mi proyecto ya es un caos?

    No. La spec retroactiva y el CLAUDE.md te permiten añadir estructura al código existente sin reescribirlo. El código puede quedarse como está mientras añades el sistema que le da coherencia hacia adelante. Lo que sí tendrás que hacer es tomar las decisiones que no tomaste al principio — naming, arquitectura, convenciones — y documentarlas. Eso es trabajo que tarda horas, no semanas.

    ¿El sistema con IA hace el desarrollo más lento?

    La percepción de velocidad que da el vibe coding es real — pero es velocidad a corto plazo. El sistema hace que la semana 3 sea igual de rápida que la semana 1, porque el contexto no se degrada. Sin sistema, la velocidad cae semana a semana conforme la deuda de contexto se acumula. Quien usa sistema tiene el mismo ritmo en el sprint 8 que en el sprint 1. Quien usa vibe coding puro, no.

    ¿Qué es lo primero que debo hacer si reconozco los síntomas?

    Crea el CLAUDE.md. Puedes tenerlo en quince minutos: descripción del proyecto, stack real con versiones, convenciones de naming que ya existen en el código (aunque estén implícitas), y las tres o cuatro restricciones que te habría gustado tener desde el principio. Ese archivo solo ya reduce la inconsistencia en las sesiones futuras. El resto del sistema puedes añadirlo gradualmente.

    ¿En qué se diferencia el vibe coding del agentic engineering?

    El vibe coding es un flujo de trabajo donde el developer describe ideas y el modelo decide cómo implementarlas. El agentic engineering es una disciplina donde el developer diseña el sistema — la spec, el contexto, los contratos, los límites — y delega la implementación de forma controlada. La diferencia no es la IA que usas sino quién toma las decisiones de diseño: tú o el modelo.


    *Por Bezael Pérez — Developer senior con más de 15 años de experiencia y fundador de Dominicode.*

  • Las 4 habilidades que definen al programador en la era de la IA

    Las 4 habilidades que definen al programador en la era de la IA

    Un cliente me llamó a las 11 de la noche. Me dijo que su equipo llevaba tres semanas con Claude Code y que la productividad se había disparado. Más código por sprint. Menos bugs. Entregas más rápidas.

    Pero había un problema.

    "Bezael, el equipo construye muy rápido. El problema es que construye muy rápido la cosa equivocada."

    Tres semanas generando código con IA. Código correcto, bien estructurado, con tests. Y un producto que no resolvía lo que el cliente necesitaba.

    Ese es el nuevo riesgo para el programador en la era de la IA. No que la IA te reemplace escribiendo código. Sino que la velocidad de producción amplifique el coste de tomar decisiones equivocadas. Antes tardabas un mes en construir algo mal. Ahora tardas tres días.

    Lo que separa a los developers que avanzan de los que se atascan no son sus habilidades técnicas. Son cuatro habilidades del programador en la era de la IA que ningún LLM puede suplir.


    Las habilidades del programador en la era de la IA que este post desarrolla son cuatro: entender el problema real antes de escribir una línea, comunicar la solución a stakeholders no técnicos, especificar con precisión lo que el agente debe construir, y negociar trade-offs cuando los requisitos chocan. Son las habilidades que la IA no puede ejecutar por ti — y las que determinan si su velocidad se convierte en ventaja o en ruido.


    Por qué el código ya no es el cuello de botella del programador en la era IA

    Durante veinte años el cuello de botella en el desarrollo de software fue escribir el código. Encontrar developers. Escalar equipos. Mantener la velocidad.

    Eso ha cambiado.

    Hoy un developer con Claude Code puede producir en un día lo que antes llevaba una semana. Los agentes no se cansan, no tienen bloqueos creativos, y no discuten sobre si usar tabs o spaces. El Stack Overflow Developer Survey 2025 documenta que más del 75% de developers ya usa o planea usar herramientas de IA en su flujo de trabajo — el cambio está aquí.

    Pero los agentes hacen exactamente lo que les pides. Ni más, ni menos. Y si lo que les pides es impreciso, ambiguo, o directamente equivocado, producen código impecable que resuelve el problema equivocado.

    El cuello de botella se ha desplazado. Ya no está en escribir. Está en pensar.


    Habilidad 1: Entender el problema real antes de abrir el editor

    Esta es la más subestimada y la que más dinero cuesta cuando falla.

    Un cliente te dice: "Necesitamos un dashboard con métricas en tiempo real." Un developer técnico abre el editor y empieza a pensar en WebSockets, en qué charting library usar, en cómo estructurar el backend.

    Un developer con criterio hace una pregunta primero: "¿Para qué vas a usar ese dashboard? ¿Quién lo mira y qué decisión toma a partir de lo que ve?"

    Esa pregunta cambia todo.

    A veces el dashboard en tiempo real que pedían era en realidad un email diario con tres métricas. A veces era un CSV que se cargaba en Excel. A veces ni siquiera era un problema de visualización — era un problema de que nadie en la empresa sabía qué datos tenía disponibles.

    Con IA esto se vuelve crítico. Porque ahora la velocidad de producción es tan alta que el coste de empezar en la dirección equivocada es enorme. Construyes tres features completas en el tiempo que antes tardabas en escribir media. Si las tres están mal orientadas, has quemado tres veces más tiempo que antes.

    La habilidad de entender el problema real — no el síntoma que te describen, sino la causa raíz que lo genera — es la que protege todo lo demás.

    No se aprende con más cursos de programación. Se aprende haciendo preguntas incómodas antes de escribir una línea.


    Habilidad 2: Comunicar la solución a quien no es técnico

    El código más elegante del mundo no vale nada si nadie en la empresa entiende qué resuelve ni por qué importa.

    Esto ha sido siempre un problema para los developers. Pero con IA se vuelve más urgente, porque ahora eres capaz de construir cosas más complejas, más rápido, con más capas de abstracción. Y cuanto más complejo es lo que construyes, más difícil es explicarlo a quien toma las decisiones de negocio.

    La comunicación técnica a stakeholders no técnicos no es "simplificar para que lo entienda un niño". Es traducir impacto.

    Un stakeholder no necesita entender cómo funciona una cola de mensajes asíncrona. Necesita entender que gracias a esa cola, el sistema puede procesar diez mil pedidos en paralelo sin que ningún usuario espere más de dos segundos. Eso sí lo entiende. Y eso sí cambia cómo percibe el valor de lo que has construido.

    Esta habilidad también protege tu trabajo. Si tu contribución es invisible para quien decide los presupuestos, eres vulnerable. Si puedes hacer visible el impacto técnico en términos de negocio, eres indispensable.

    Practica esto: después de cada feature que entregues, escribe en dos frases qué problema de negocio resuelve y qué habría pasado sin ella. Si no puedes hacerlo, tienes un problema antes de que alguien externo lo detecte.

    Hay un ejercicio que funciona muy bien para esto: antes de la próxima reunión de sprint, prepara una explicación de lo que estás construyendo en menos de 60 segundos, sin usar términos técnicos. Si necesitas más tiempo o tienes que recurrir al jargon, la feature aún no está suficientemente clara en tu cabeza. Esa claridad — la que te permite explicarla en voz alta — es exactamente la que también necesitas para especificarla bien para un agente.

    Esta habilidad se conecta directamente con la siguiente. Un developer que no puede explicar lo que construye a un humano tampoco puede especificarlo con precisión para una máquina.


    Habilidad 3: Especificar con precisión lo que el agente debe construir

    Esta es la habilidad nueva. La que no existía como tal hace tres años y que ahora es central.

    Los agentes de IA son ejecutores extraordinarios de instrucciones precisas. Son ejecutores pésimos de instrucciones vagas.

    "Construye un sistema de autenticación" puede producir cualquier cosa desde un JWT básico hasta un sistema OAuth completo con múltiples proveedores y gestión de sesiones. El agente hará algo. Y lo que haga puede ser técnicamente correcto y completamente inadecuado para tu contexto.

    Especificar bien significa definir:

    1. Qué hace el sistema — comportamiento concreto, no intención abstracta
    2. Qué NO hace — los límites son tan importantes como las funcionalidades
    3. Bajo qué restricciones — tecnología, rendimiento, compatibilidad, seguridad
    4. Cómo se valida que está correcto — criterios de aceptación verificables

    Si quieres entender mejor el perfil completo del developer que trabaja con agentes en producción, el post sobre qué es un Agentic Engineer cubre ese rol con detalle. La especificación es su primer requisito.

    Llevo varios años aplicando una metodología para esto que llamo Spec-Driven Development. La idea es que antes de que el agente escriba una línea, tienes un documento que responde esas cuatro preguntas. No un documento largo ni burocrático — uno preciso. El Libro SDD documenta este proceso completo, desde cómo estructurar la especificación hasta cómo convertirla en tareas que un agente puede ejecutar sin desviarse.

    La diferencia entre un developer que especifica bien y uno que no lo hace no se mide en velocidad. Se mide en cuánto código hay que tirar a la basura al final de cada sprint.


    Habilidad 4: Negociar trade-offs cuando los requisitos chocan

    Los requisitos siempre chocan. Siempre.

    "Quiero que sea seguro, rápido, barato, flexible y que esté listo para el martes." No puedes tener las cinco cosas. Nunca has podido. Pero antes la conversación sobre qué sacrificar era más lenta porque construir era más lento. Ahora, con la velocidad que da la IA, la presión para tomarlo todo aumenta.

    Un developer que sabe negociar trade-offs no es el que cede ante la presión del cliente. Es el que hace explícito el coste de cada decisión y ayuda a quien decide a entender qué están eligiendo realmente.

    "Si priorizamos velocidad de lanzamiento, el sistema no va a escalar bien por encima de diez mil usuarios. Podemos lanzar en dos semanas con esa limitación asumida, o lanzar en seis semanas con una arquitectura que aguante cien mil. ¿Qué es más importante ahora mismo para el negocio?"

    Esa conversación requiere que el developer entienda el negocio suficientemente bien como para hacer la pregunta correcta. Requiere que sepa comunicar la implicación técnica en términos de impacto. Y requiere que tenga la seguridad de plantear la conversación antes de que los problemas aparezcan en producción.

    Con agentes de IA esto se vuelve más delicado porque la velocidad de implementación hace que sea tentador no tener esa conversación. "Lo construimos rápido, si no funciona lo cambiamos." Pero cambiar una decisión arquitectural después de que cuatro features dependen de ella no es barato, aunque la IA escriba el código.

    En el curso Construye con IA dedicamos una parte específica a cómo estructurar estas conversaciones antes de empezar a generar código — porque los errores más costosos no son de sintaxis, son de dirección.


    Las habilidades del programador que la IA no puede reemplazar

    La IA escribe código. Lo depura. Lo refactoriza. Lo documenta. Lo testea.

    No puede entrar a una reunión y detectar que lo que el cliente pide en realidad responde a un miedo que no ha verbalizado. No puede leer el contexto político de una organización para entender por qué un requisito existe. No puede mirar los ojos de un stakeholder y saber que cuando dice "necesitamos esto para el viernes" en realidad está diciendo "si esto no sale el viernes, me cuesta el trabajo".

    Esas lecturas son humanas. Y en un entorno donde el código se genera en segundos, son el verdadero diferencial.

    Los developers que van a crecer en los próximos años no son los que más saben de LLMs. Son los que combinan criterio técnico con las habilidades de comunicación, especificación y negociación que hacen que ese criterio tenga impacto.


    El developer que va a sobrevivir a la IA

    No es el que sabe más frameworks.

    No es el que tiene mejores prompts para Claude.

    Es el que puede entrar en una sala con personas técnicas y no técnicas, entender lo que realmente está en juego, definir con precisión lo que hay que construir, y explicar con claridad por qué ciertas cosas no se pueden tener al mismo tiempo.

    Este cambio de rol — de ejecutar tareas a tomar decisiones con criterio — es lo que ya analizamos en profundidad en el post sobre el programador que se convierte en product builder. Las cuatro habilidades de este post son el motor que hace posible ese salto.

    La IA amplifica la velocidad de ejecución. Las cuatro habilidades de las que hablamos hoy amplifican la calidad de las decisiones. Y en software, las decisiones siempre cuestan más que el código.

    En Dominicode Labs trabajamos estos temas con developers que están construyendo con IA en proyectos reales — no ejercicios de academia, sino productos con usuarios, deadlines, y stakeholders que necesitan respuestas los lunes por la mañana.

    Si quieres empezar hoy, elige la habilidad que sabes que tienes más floja de las cuatro y pasa esta semana ejerciéndola deliberadamente. Una conversación con un stakeholder. Un documento de especificación antes de abrir el editor. Una pregunta incómoda que no has hecho todavía.

    El código lo escribe la IA. El criterio lo pones tú.


    Preguntas frecuentes

    ¿Estas habilidades sustituyen al conocimiento técnico profundo?
    No, lo complementan. Sin base técnica sólida no puedes especificar bien ni negociar trade-offs con conocimiento de causa. Lo que cambia es que el conocimiento técnico ya no es suficiente por sí solo — necesitas combinarlo con estas capacidades para que tenga impacto real. Un developer que solo sabe programar pero no puede comunicar ni especificar ni negociar tiene cada vez menos diferencial frente a un agente de IA.

    ¿Cómo se aprende a especificar para agentes de IA si nunca lo he hecho?
    Empieza por escribir, antes de cualquier tarea, un documento de dos párrafos: uno con lo que el sistema debe hacer y uno con lo que no debe hacer. Con ese ejercicio simple ya estás especificando. A medida que lo practiques, irás añadiendo restricciones, criterios de aceptación y contexto. La metodología Spec-Driven Development es un marco más completo para esto, documentado en el Libro SDD.

    ¿Estas habilidades son más importantes para freelancers que para developers en empresa?
    Son importantes en los dos contextos, pero de formas distintas. El freelance que no sabe comunicar ni negociar pierde clientes. El developer en empresa que no sabe hacer estas cosas se queda estancado en roles de ejecución y ve cómo los que ascienden son los que saben tener las conversaciones difíciles. En ambos casos, la consecuencia de no desarrollarlas es la misma: invisibilidad.

    ¿La velocidad que da la IA no hace que estos trade-offs sean menos importantes porque "se puede cambiar todo fácilmente"?
    Es una trampa común. Sí, la IA acelera la implementación. Pero hay decisiones — de arquitectura, de modelo de datos, de contratos de API — que una vez tomadas son costosas de cambiar aunque el código lo escriba un agente.

    Si tu base de datos está mal modelada, reescribir las queries con IA no resuelve el problema. El coste de las malas decisiones estructurales no ha bajado con la IA.

    Lo que ha bajado es el coste de implementar la decisión, buena o mala. Eso amplifica el impacto de decidir bien tanto como el de decidir mal.

    ¿Existe algún perfil técnico donde estas habilidades no importan?
    Si trabajas en investigación pura, en open source sin usuarios directos, o en roles muy especializados de bajo nivel donde el contacto con stakeholders es mínimo, el peso relativo de estas habilidades es menor. Pero para la mayoría de developers que trabajan en productos, servicios o consultoría — que es la mayoría — estas cuatro capacidades son cada vez más determinantes para el crecimiento profesional.


    Por Bezael Pérez — Developer senior con más de 15 años de experiencia y fundador de Dominicode.

  • Proyecto greenfield con SDD: spec global + slices verticales

    Proyecto greenfield con SDD: spec global + slices verticales

    Hace unas semanas un developer del canal me contó lo que había pasado en su último proyecto.

    Seis horas. Eso tardó en planificar un proyecto greenfield con SDD usando slices verticales. Tenía un spec global, features bien definidas, tareas granulares. Parecía perfecto.

    Ejecutó el primer slice con su agente IA. La app funcionaba. Autenticación, flujo de datos, navegación — todo correcto.

    Y era completamente gris. Sin estilos. Sin diseño. Una interfaz que parecía sacada de 1998.

    No había especificado nada sobre la UI en su spec. Ni colores, ni componentes, ni sistema de diseño. El agente hizo exactamente lo que se le pidió: implementar la lógica. Y lo hizo bien.

    El problema no era el agente. Era el spec.

    El error que nadie te dice sobre SDD en proyectos nuevos

    Spec-Driven Development (SDD) es una metodología en la que cada feature comienza con un documento de especificación estructurado — el spec — antes de escribir código. El spec define qué hace la feature, cómo se ve, y qué criterios debe cumplir para considerarse completa.

    Cuando descubres SDD, la primera intuición es clara: especifica todo antes de escribir una línea de código. Visión, usuarios, funcionalidades, arquitectura, flujos.

    Y esa intuición es correcta… pero incompleta.

    Hay dos errores que se cometen casi siempre en un proyecto greenfield con SDD:

    El primero es intentar especificar el proyecto completo antes de tocar el teclado. Un spec monolítico de 40 páginas que detalla hasta la última feature antes de que exista una sola línea de código. Es atractivo. Se siente seguro. Y casi siempre es un error.

    El segundo es lo que le pasó a ese developer: especificar las features en términos de lógica y flujos, pero olvidar que las features tienen una cara visible. Que los usuarios las ven. Que el diseño no es una capa que se añade al final — es parte de la feature.

    Ambos errores llevan al mismo resultado: rediseño tardío, deuda técnica, y la sensación de que SDD no funciona cuando el problema real es la estrategia, no la metodología.


    La estructura que sí funciona: spec global ligero + slices con UI

    La solución tiene dos capas. Una sesión corta de spec global que define las reglas del juego, y luego un ciclo de feature-por-feature donde cada spec incluye explícitamente la UI.

    Capa 1: El spec global ligero

    Este documento no especifica features. Especifica el contexto en el que todas las features van a vivir. Se hace una sola vez, en una sola sesión, y no debería tomar más de 45 minutos.

    # Spec Global — [Nombre del proyecto]
    _Versión: 1.0 | Fecha: YYYY-MM-DD_
    
    ## Visión
    [Una sola frase que describe qué es el producto y para quién.]
    
    ## Stack técnico
    - Frontend: Angular 22 con Signals
    - Backend: NestJS + Supabase
    - Estilos: Tailwind CSS v4
    - Testing: Jest + Testing Library
    
    ## Sistema de diseño
    - Librería de componentes: Angular Material / PrimeNG / custom
    - Paleta de colores: primario #1A73E8, fondo #F8FAFC, texto #0F172A
    - Tipografía: Inter, base 16px
    - Espaciado: escala de 4px (4, 8, 12, 16, 24, 32, 48...)
    - Breakpoints: sm 640px / md 768px / lg 1024px / xl 1280px
    
    ## Convenciones de arquitectura
    - Estructura: feature-based (cada feature es un módulo independiente)
    - Estado global: NgRx Signal Store
    - Llamadas HTTP: Resource API (Angular 22)
    - Validación: Zod en schemas compartidos
    
    ## Decisiones técnicas ya tomadas
    - Autenticación: Supabase Auth (no reinventar)
    - Despliegue: Vercel (frontend) + Railway (backend)
    - No usar: Redux clásico, Class Components, módulos NgModule legacy
    
    ## Features planificadas (sin detallar)
    1. Autenticación
    2. Dashboard principal
    3. Gestión de proyectos
    4. Reportes
    

    Eso es todo. No más. El spec global no detalla cómo funciona cada feature — solo establece las reglas que todas van a respetar.

    Lo más importante de ese documento son las secciones de sistema de diseño y convenciones de arquitectura. Son el contrato que el agente va a respetar en cada feature. Si no las defines aquí, las decide él — y probablemente no va a coincidir con lo que tienes en la cabeza.

    Capa 2: El spec de cada feature — con sección UI obligatoria

    Aquí está el cambio que lo transforma todo. Cuando vas a implementar una feature, escribes su spec detallado en ese momento, no antes. Y ese spec siempre incluye una sección de UI/UX.

    # Feature 1: Autenticación
    _Contexto: spec global v1.0 | Estado: en implementación_
    
    ## Qué hace
    Permite al usuario crear cuenta, iniciar sesión y recuperar contraseña.
    Usa Supabase Auth. No hay lógica de autenticación propia.
    
    ## Flujos principales
    1. Registro: email + contraseña → verificación por email → redirect a dashboard
    2. Login: email + contraseña → redirect a dashboard (o a la ruta que intentaba visitar)
    3. Recuperación: email → link con token → nueva contraseña → login
    
    ## UI/UX (obligatorio)
    - Layout: columna centrada, max-width 400px, padding 24px
    - Componentes a usar: InputField, Button, Alert — todos del sistema de diseño global
    - Estados visuales a implementar:
      - Loading: botón con spinner, campos desactivados
      - Error: Alert rojo con mensaje específico (no "algo salió mal")
      - Éxito: redirect inmediato, sin pantalla intermedia
    - Mobile first: el form debe funcionar bien en 320px
    - No inventar componentes nuevos — usar los del spec global
    
    ## Criterios de aceptación
    - [ ] El usuario puede registrarse con email válido
    - [ ] El usuario recibe email de verificación
    - [ ] El usuario puede iniciar sesión y llega al dashboard
    - [ ] Los estados de loading y error son visibles
    - [ ] El form es usable en móvil
    
    ## Lo que NO hace esta feature
    - No maneja OAuth (Twitter, Google) — queda para v2
    - No maneja roles de usuario — eso es responsabilidad del dashboard
    

    La sección UI/UX no es opcional. Es donde especificas exactamente qué tiene que ver el usuario cuando interactúa con esta feature. Si la omites, el agente tomará esa decisión por ti, y probablemente tomará la decisión más rápida, no la más correcta.


    Spec total upfront vs spec incremental — la comparativa real

    La tentación de escribir el spec completo del proyecto antes de arrancar tiene sentido desde afuera. La realidad es diferente.

    Spec total upfront Spec incremental (global ligero + features)
    Tiempo inicial 2-3 días o más 45 min (spec global) — hasta 20× más rápido para arrancar
    Riesgo Alto — cambias de opinión cuando ves el código real Bajo — ajustas cada feature antes de implementarla
    UI/UX Probablemente omitida o abstracta Concreta en cada feature, con contexto real
    Consistencia Dependes de que el spec inicial fuera perfecto El spec global garantiza coherencia entre features
    Deuda de redesign Alta — aparece cuando el 80% del código ya existe Baja — se elimina en cada ciclo de validación visual
    Útil con agentes IA Solo si el agente tiene memoria perfecta (no la tiene) Sí — cada prompt incluye contexto concreto y actualizado

    El spec incremental no significa improvisación. Significa que el contexto que tienes cuando implementas la feature 4 es mejor que el que tenías antes de escribir una sola línea de código. Y ese contexto — los componentes que ya existen, las decisiones que ya se tomaron, los problemas que ya aparecieron — enriquece el spec de la siguiente feature.

    Este enfoque es una variación de la Vertical Slice Architecture documentada por Jimmy Bogard, aplicada al contexto de specs con agentes IA.

    El rediseño tardío no ocurre porque el spec sea incremental. Ocurre porque no hay spec en absoluto.


    El ciclo de trabajo en un proyecto greenfield SDD

    El flujo que funciona es simple, y se repite para cada feature:

    1. Escribe el spec de esa feature (con sección UI incluida)
    2. Dáselo al agente como contexto completo
    3. Implementa
    4. Valida visualmente antes de marcar como hecho
    5. Usa lo aprendido para enriquecer el spec de la siguiente feature

    El paso 4 es crítico y muchos lo saltan. Validar visualmente significa abrir el navegador, probar el flujo como lo haría un usuario real, y confirmar que los estados de loading, error y éxito se ven como los especificaste. No basta con que los tests pasen.

    Si en el paso 4 descubres que algo no se ve bien, arréglalo antes de avanzar. El coste de arreglar un componente mal implementado en la feature 1 es mínimo. El coste de arreglar el mismo patrón cuando ya está repetido en las features 1, 3, 5 y 7 es considerable.


    Lo que cambia cuando tienes el spec global

    El spec global tiene un efecto que no es obvio hasta que lo usas en producción.

    Cuando llegas a la feature 4, el agente tiene contexto. Sabe que los inputs van con Tailwind, que el estado global es NgRx Signal Store, que los errores se muestran con el componente Alert del sistema de diseño. Si estás usando Angular 22, también puedes aprovechar la Resource API para centralizar las llamadas HTTP en el spec desde el principio — sin que el agente invente su propio patrón. No lo tienes que repetir en cada prompt.

    Y cuando llega alguien nuevo al proyecto — o cuando tú mismo vuelves al código tres meses después — entiende en 10 minutos las decisiones que se tomaron y por qué.

    Eso no lo da el código. Lo da el spec.

    Si quieres profundizar en la metodología completa, en el libro de Spec-Driven Development tienes el framework completo: cómo estructurar specs, cómo trabajar con agentes IA de forma efectiva, y los patrones que se usan en proyectos reales de producción.


    La UI no es una capa. Es un contrato.

    El error del developer que me escribió no fue usar SDD. Fue asumir que SDD significa especificar todo el proyecto antes de arrancar.

    SDD significa especificar lo suficiente, en el momento correcto, con el nivel de detalle correcto. El spec global define el campo de juego. El spec de cada feature define las reglas de ese momento.

    Y la UI no es una capa que se añade al final. Es parte del contrato de cada feature.

    Si quieres ver este flujo en acción — desde el spec hasta el commit — en el curso Construye con IA: De la Idea al Producto aplicamos exactamente esta metodología: spec global, slices verticales, validación visual antes de avanzar. Con agentes IA reales, en proyectos que no son de juguete.

    Y si prefieres el formato comunidad, en Dominicode Labs compartimos los specs reales de los proyectos que construimos juntos — con las decisiones que se tomaron y las que se descartaron.

    El spec no te quita velocidad. Te quita el coste de arreglar lo que nadie especificó.


    FAQ

    ¿Cuánto tiempo debería tardar el spec global de un proyecto real?

    Entre 30 y 60 minutos. Si tardas más, estás especificando features en el spec global, y eso no es su función. El spec global define el contexto y las reglas. Las features se detallan una a una cuando llega su turno.

    ¿Es obligatoria la sección UI/UX en el spec de cada feature?

    En proyectos con interfaz visible, sí. Si estás construyendo una API sin frontend, la sección UI/UX no aplica, pero deberías incluir una sección de contratos de API: endpoints, tipos de respuesta, códigos de error. El principio es el mismo: especifica todo lo que el agente necesita para no tomar decisiones que tú deberías tomar.

    ¿Cómo manejo las features que dependen de otras que aún no están implementadas?

    En el spec de la feature con dependencia, añades una sección “Asunciones” que documenta qué esperas de las features previas. Si la feature A aún no existe, especificas el contrato que A debería cumplir — y cuando implementes A, ese contrato ya está documentado. Es una forma de diseño by contract que funciona muy bien con agentes.


    Por Bezael Pérez — Developer senior con más de 15 años de experiencia y fundador de Dominicode.