Hay una brecha creciente entre los desarrolladores que obtienen resultados confiables de Claude Code y los que pasan la mitad del dia deshaciendo lo que el agente acaba de construir. La diferencia no es talento, experiencia ni algun truco secreto de prompt engineering. Es una cuestion de metodologia. Los desarrolladores que entregan software de produccion con agentes de IA han convergido en un patron, lo llamen asi o no: definir lo que quieres antes de que el agente empiece a escribir codigo.
Este articulo le da nombre a ese patron. El desarrollo spec-first es una metodologia para la ingenieria de software asistida por IA. No una vaga "buena practica." Un ciclo de vida estructurado y repetible con fases definidas, checkpoints claros y artefactos concretos en cada paso. Si has estado buscando una forma de hacer que la salida de Claude Code sea lo suficientemente predecible como para apostar tu calendario de releases, este es el framework.
El techo del Vibe Coding
"Vibe coding" entro al vocabulario a principios de 2025. La propuesta: describe lo que quieres en lenguaje natural, deja que la IA lo escriba, itera hasta que se vea bien. Para prototipos, proyectos de fin de semana y scripts puntuales, el vibe coding funciona. Obtienes algo funcional rapido, y si se rompe despues, no hay mucho en juego.
El software de produccion opera bajo restricciones diferentes. El codigo debe integrarse con una codebase existente, satisfacer requisitos especificos y sobrevivir al contacto con otras personas que lo mantendran. Cuando el vibe coding se encuentra con estas restricciones, los modos de fallo son predecibles.
El primer fallo es la deriva. Describes una funcionalidad vagamente, el agente implementa su interpretacion, ajustas, el agente reimplementa su interpretacion ajustada. Tres iteraciones despues, tienes codigo funcional que no satisface ninguno de tus requisitos originales porque cada iteracion desplazo el objetivo. Estas convergiendo en lo que el agente cree que quieres, no en lo que realmente necesitas.
El segundo fallo son las decisiones invisibles. Cada vacio en tu descripcion es una decision que el agente toma en silencio. Esquema de base de datos, estrategia de manejo de errores, forma de la API, reglas de validacion, eleccion de librerias. Descubres estas decisiones durante el code review, o peor, en produccion. El agente no tomo malas decisiones. Tomo decisiones no instruidas, y no tenias mecanismo para detectarlas antes de que quedaran incorporadas en la implementacion.
El tercer fallo es la paralisis de review. Un diff de 600 lineas donde el agente eligio la arquitectura, el modelo de datos, los codigos de error y el manejo de casos limite no es revisable en el sentido tradicional. No estas revisando codigo contra una spec. Estas reconstruyendo la spec a partir del codigo, y luego decidiendo si estas de acuerdo. Esto toma mas tiempo del que habria tomado escribir la spec.
El vibe coding toca techo porque mezcla dos actividades distintas: decidir que construir y construirlo. El desarrollo spec-first las separa.
Spec-First como metodologia
El desarrollo spec-first es un ciclo de vida de cuatro fases. Cada fase produce un artefacto concreto. Cada transicion tiene una condicion de puerta clara. La metodologia funciona con cualquier agente de IA para codificacion, pero los ejemplos en este articulo usan Claude Code porque es donde la comunidad esta iterando mas rapido.
Fase 1: Brainstorm
Tu y el agente (o solo tu) exploran el espacio del problema. ?Cuales son las restricciones? ?Que enfoques existen? ?Cuales son los compromisos? Esto es conversacional. No te estas comprometiendo con nada. Estas mapeando el terreno.
La condicion de puerta: tienes un enfoque preferido y puedes articular por que este enfoque sobre las alternativas.
Hacer brainstorm con Claude Code es valioso porque el agente tiene amplio conocimiento de patrones y librerias. El error es saltar del brainstorm directamente al codigo. El brainstorm muestra opciones. No elige entre ellas. Tu lo haces.
Fase 2: Spec
Escribes la decision. Este es el contrato contra el cual el agente implementara. Una spec no es una user story, no es un ticket de Jira, no es un parrafo en prosa. Es un documento estructurado con:
- Declaracion del problema: que esta roto o falta, en terminos concretos
- Enfoque propuesto: la solucion elegida de la fase de brainstorm
- Archivos afectados: que archivos debe tocar el agente (e implicitamente, cuales no)
- Criterios de aceptacion: condiciones testeables que definen "terminado"
- Fuera de alcance: lo que el agente debe evitar explicitamente
Los criterios de aceptacion son el elemento mas importante. Cada uno debe ser una accion concreta con un resultado observable. "La autenticacion deberia funcionar" no es un criterio. "Enviar credenciales validas devuelve un 200 con un token de sesion; enviar credenciales invalidas devuelve un 401 sin token" si lo es.
La seccion de fuera de alcance previene el gold-plating. Sin ella, los agentes "mejoraran" codigo adyacente, refactorizaran archivos que notaron desordenados o agregaran funcionalidades que parecen relacionadas. Cada minuto que el agente pasa en trabajo no solicitado es un minuto que tu pasas revisando trabajo no solicitado.
La condicion de puerta: alguien que no estuvo en el brainstorm podria leer esta spec y construir lo correcto.
Fase 3: Implementacion
El agente ejecuta contra la spec. No contra una conversacion. No contra un recuerdo de lo que discutieron. Contra un documento concreto con criterios testeables.
Antes de escribir codigo, el agente produce un plan: una lista numerada de cambios que pretende hacer, que archivos modificara y como verificara el resultado. Este plan es un checkpoint de dos minutos. Lo lees, confirmas que coincide con tu intencion y das luz verde a la implementacion. O detectas un malentendido y lo corriges. De cualquier forma, has invertido dos minutos en lugar de veinte.
El patron plan-antes-de-codigo no es burocracia. Es la intervencion individual de mayor apalancamiento en todo el workflow. La mayoria de los errores de implementacion no son errores de codigo. Son errores de comprension: el agente malinterpreto la spec. Detectar un error de comprension en un plan cuesta dos minutos. Detectarlo en un diff de 400 lineas cuesta veinte. Detectarlo en produccion cuesta un dia.
La condicion de puerta: el agente ha publicado un reporte de finalizacion con afirmaciones especificas sobre lo que se construyo y como se verifico.
Fase 4: Verificacion
Tu o un proceso de QA confirman la implementacion contra la spec. No "?se ve bien?" sino "?satisface cada criterio de aceptacion?"
La verificacion es mecanica. Tomas cada criterio de la spec, ejecutas la prueba (correr un comando, abrir un navegador, disparar un evento) y registras el resultado: aprobado o fallido. Los criterios que fallan regresan a la Fase 3. La verificacion se documenta junto a la implementacion para que cualquiera que lea la tarea en seis meses pueda ver exactamente que se probo.
La condicion de puerta: cada criterio de aceptacion tiene un resultado registrado de aprobado/fallido.
Ese es el ciclo de vida completo. Cuatro fases, cuatro artefactos (justificacion del enfoque, spec, plan de implementacion, registro de verificacion), cuatro condiciones de puerta. Las fases son secuenciales pero ligeras. Para una funcionalidad de tamano medio, las fases 1 y 2 toman 15-20 minutos. La fase 3 toma lo que tome la implementacion. La fase 4 toma 5-10 minutos.
Por que esto importa mas con agentes que con humanos
Cada argumento para escribir specs es anterior a la IA. "Escribe requisitos antes que codigo" ha sido consejo desde antes de que la mayoria de nosotros nacieramos. Entonces, ?por que enmarcar esto como algo especifico del desarrollo asistido por IA?
Porque los agentes cambian la funcion de costo.
Un desarrollador humano que recibe un requisito vago se detendra y hara preguntas. "?Te referias a auth por password o SSO?" "?Esto deberia funcionar en movil?" "?Que pasa cuando el token expira?" Cada pregunta es un mini-checkpoint que empuja la implementacion hacia el objetivo correcto. El costo de una spec vaga con un desarrollador humano son algunos hilos de Slack y quiza una tarde de retrabajo.
Un agente que recibe un requisito vago no se detendra. Tomara cada decision ambigua en silencio, se comprometera con un enfoque y te presentara una implementacion terminada. El costo de una spec vaga con un agente es una implementacion terminada que puede estar completamente equivocada, mas el tiempo que pasas descubriendo que esta equivocada, mas el tiempo que pasas rehaciendola.
La asimetria es marcada. Los agentes son mas rapidos en ejecucion y peores en juicio que los desarrolladores humanos. Cada ambiguedad en la spec es una llamada de juicio, y cada llamada de juicio que el agente hace sin orientacion es un lanzamiento de moneda sobre si el resultado coincide con tu intencion. Una spec elimina los lanzamientos de moneda.
Hay una segunda razon, mas sutil. Los agentes no objetan. Un ingeniero senior que recibe una spec mala dira "esto no tiene sentido por X." Un agente implementara una spec mala fielmente y producira output fielmente erroneo. El desarrollo spec-first te obliga a poner a prueba tu propio pensamiento antes de entregarlo a una entidad que lo ejecutara sin cuestionarlo. La spec no es solo para el agente. Es para ti.
El checkpoint plan-antes-de-codigo
Si tomas una sola practica de este articulo e ignoras el resto, toma esta.
Antes de que el agente escriba codigo, exige que publique un plan de implementacion. No codigo. No un diff. Un esquema estructurado de lo que pretende hacer.
Un plan se ve asi: pasos numerados en orden de ejecucion, archivos a modificar, cambios de logica en cada archivo y el enfoque de verificacion. El agente lo produce en unos treinta segundos. Tu lo lees en unos dos minutos. En esos dos minutos, puedes detectar:
- Violaciones de alcance: el agente planea modificar archivos no listados en la spec
- Desajustes arquitectonicos: el agente eligio un enfoque que entra en conflicto con patrones existentes
- Pasos faltantes: el plan no aborda un criterio de aceptacion
- Sobreingenieria: el agente planea construir abstracciones que no estan justificadas
La revision de plan de 2 minutos reemplaza la revision de diff de 20 minutos donde descubres estos problemas despues de que ya estan construidos. Es la puerta de calidad mas barata en ingenieria de software.
Escribi un recorrido detallado del patron plan-antes-de-codigo en Desarrollo spec-driven con Claude Code, incluyendo plantillas de spec y formatos de reportes de finalizacion. Este articulo se enfoca en por que funciona el patron; aquel se enfoca en como implementarlo.
Verificacion como paso de primera clase
La fase con menos inversion en el workflow de la mayoria de los desarrolladores es la verificacion. El agente dice "listo." El desarrollador echa un vistazo al diff. El merge ocurre. El bug aparece dos dias despues cuando un usuario encuentra el caso limite numero tres de los criterios de aceptacion.
El desarrollo spec-first trata la verificacion como un paso formal con sus propios artefactos. El reporte de finalizacion mapea cada criterio de aceptacion a una comprobacion concreta:
- Criterio: "Cambiar de workspace restaura el estado de filtros guardado."
- Comprobacion: Abrir la app, establecer filtros en workspace A, cambiar a workspace B, volver a workspace A, observar que los filtros estan restaurados.
- Resultado: Aprobado.
Esto no es overhead. Es el paso que determina si la implementacion realmente satisface la spec. Sin el, la spec es una lista de deseos y los criterios de aceptacion son aspiracionales.
El registro de verificacion tambien resuelve un problema posterior: el code review. Cuando un revisor abre el pull request, lee la spec, lee el registro de verificacion y revisa el diff con contexto completo. El tiempo de revision baja porque el revisor esta confirmando una afirmacion verificada, no conduciendo una investigacion.
Cuando corres multiples agentes en paralelo, cada uno implementando una spec diferente, la disciplina de verificacion es la diferencia entre un pipeline controlado y un monton de codigo que "probablemente funciona." Cada spec tiene criterios. Cada implementacion tiene un reporte de finalizacion. Cada reporte de finalizacion mapea criterios a comprobaciones. Nada se entrega sin verificacion registrada.
Objeciones y compromisos honestos
El desarrollo spec-first no es gratis. Las objeciones son reales y merecen abordarse de frente.
"Escribir specs me hace mas lento." Aisladamente, si. Escribir una spec para una funcionalidad toma 15-20 minutos. Pero recuperas ese tiempo (y mas) en las fases de implementacion y revision. Un agente con una spec clara produce una implementacion correcta con mas frecuencia que un agente con un prompt vago. Menos iteraciones, menos retrabajo, revisiones mas cortas. El efecto neto para funcionalidades de cualquier sustancia es entrega mas rapida, no mas lenta.
Para cambios triviales (renombrar una variable, corregir un typo, subir una version), las specs son overhead innecesario. Spec-first es para trabajo donde la implementacion requiere decisiones. Si el cambio es mecanico y no ambiguo, salta la spec.
"Mi agente es suficientemente bueno sin specs." Para algunas tareas, probablemente cierto. Claude Code es notablemente capaz de inferir intenciones a partir de descripciones breves. La pregunta no es si el agente puede producir buena salida a partir de instrucciones vagas. Es si lo hace confiablemente. Si te sientes comodo con retrabajo ocasional y tiempos de revision impredecibles, el vibe coding puede ser suficiente para tu caso de uso. Spec-first paga cuando la consistencia y la predecibilidad importan: cuando la funcionalidad es compleja, cuando el codigo va a produccion, cuando alguien mas lo mantendra.
"Las specs se vuelven obsoletas." Preocupacion valida. Una spec escrita durante el brainstorming podria no sobrevivir al contacto con la realidad. La solucion no es saltarse las specs. Es actualizar la spec cuando el plan revela nueva informacion. Si el plan del agente muestra que el enfoque en la spec no funcionara, revisa la spec antes de continuar. La spec es un documento vivo durante la implementacion. Se convierte en registro historico despues de la verificacion.
"Esto es solo waterfall." No. El fallo del waterfall fueron specs grandes para proyectos grandes con ciclos de feedback largos. El desarrollo spec-first opera a nivel de tarea: una spec por funcionalidad o fix, escrita en 15-20 minutos, implementada en horas, verificada el mismo dia. El ciclo de feedback es corto. La inversion por spec es pequena. Si la spec esta mal, te enteras durante la revision del plan, no seis meses despues.
Herramientas para el ciclo de vida Spec-First
La metodologia funciona con cualquier sistema de tareas: GitHub Issues, Linear, Notion, archivos de texto plano. Lo que importa es que la spec, el plan, las notas de implementacion y los resultados de verificacion vivan en un solo lugar, adjuntos a una tarea.
Si buscas un sistema disenado para este workflow, beads es un issue tracker open-source y Git-nativo que alberga el ciclo de vida completo. Cada "bead" lleva una descripcion (tu spec), un hilo de comentarios (planes y reportes de finalizacion), un estado (open, in_progress, ready_for_qa, done) y metadatos como dependencias y prioridades. El CLI bd opera desde la terminal, lo que significa que los agentes pueden leer specs, publicar planes y reportar finalizaciones sin salir de su entorno de trabajo.
bd create --title "Persist filter state across workspaces" \
--description "## Problem ..." --type feature --priority p2
bd update bb-a1b2 --claim --actor eng1
bd comments add bb-a1b2 --author eng1 "PLAN: ..."
# After implementation:
bd comments add bb-a1b2 --author eng1 "DONE: ... Commit: a1b2c3d"
bd update bb-a1b2 --status ready_for_qa
Todo el ciclo de vida ocurre en el CLI. Seis meses despues, bd show bb-a1b2 devuelve la historia completa de lo que fue especificado, planificado, construido y verificado.
Cuando corres un agente a traves de este ciclo de vida, el CLI es suficiente. Cuando corres cinco o diez en paralelo, cada uno en una etapa diferente del pipeline spec-implement-verify, necesitas ver el estado del pipeline de un vistazo. Beadbox es un dashboard en tiempo real que muestra que specs estan abiertas, cuales tienen planes esperando revision, cuales estan en progreso, cuales estan bloqueadas y cuales estan listas para verificacion. Monitorea la misma base de datos de beads en la que escriben los agentes, actualizandose en vivo conforme cambian los estados.
No necesitas Beadbox para practicar desarrollo spec-first. La metodologia es agniostica a herramientas. Pero cuando los flujos de trabajo paralelos convierten tu pipeline en una cola de tareas que no puedes rastrear solo de memoria, la capa visual cambia la velocidad con la que puedes revisar, desbloquear y entregar.
El cambio mas amplio
El desarrollo spec-first no es una reaccion a que los agentes de IA para codificacion sean malos. Es el reconocimiento de que son buenos en las cosas equivocadas sin orientacion. Los agentes son ejecutores extraordinariamente capaces. Escriben sintaxis correcta, siguen patrones, manejan boilerplate y producen un volumen que ningun humano puede igualar. Lo que les falta es el contexto para tomar buenas decisiones sobre que construir. Ese contexto viene de ti, y la spec es el vehiculo.
Los desarrolladores que prosperaran en la ingenieria asistida por IA no son los que escriben los mejores prompts. Son los que escriben las mejores specs. Los prompts son efimeros. Las specs son duraderas. Los prompts optimizan para una sola interaccion. Las specs optimizan para un ciclo de vida: brainstorm, definir, implementar, verificar.
Esto no es un parche temporal hasta que los agentes sean mas inteligentes. Incluso conforme los modelos mejoren, la asimetria fundamental permanece: el humano sabe lo que el negocio necesita; el agente sabe como escribir codigo. Una spec conecta ambos. Los modelos mejores ejecutaran specs mas rapido, pero la necesidad de la spec no desaparece. Se vuelve mas importante conforme escalas, porque mas agentes ejecutando contra instrucciones vagas producen output mas divergente.
Si has estado corriendo agentes de Claude Code y encontrando los resultados inconsistentes, o gastando demasiado tiempo en revision, o luchando para coordinar flujos de trabajo paralelos, intenta esto: antes de la proxima funcionalidad, toma 15 minutos para escribir una spec con criterios de aceptacion testeables, exige al agente que publique un plan antes de codificar, y verifica la salida criterio por criterio. Un ciclo te mostrara la diferencia.
Si estas construyendo workflows como este, dale una estrella a Beadbox en GitHub.
