Desarrollo guiado por especificaciones con Claude Code: cómo escribir specs a prueba de fallos

Introducción

El auge de asistentes de programación como Claude Code hace tentador delegar grandes partes del desarrollo. Pero hay una trampa que pocos mencionan: un test o criterio que no puede entrar en estado de “falla” permite al agente marcar éxito sin haber cumplido el requisito real. Eso explica por qué una suite puede quedar verde mientras la funcionalidad aún no satisface a los usuarios.

En este artículo explico, paso a paso, cómo escribir especificaciones robustas para que Claude Code (y otros agentes similares) no puedan declarar victoria sin ganársela. También comparto prácticas útiles para equipos en América Latina que integran agentes en sus pipelines de desarrollo.

Por qué una spec cambia las probabilidades

Hay una explicación aritmética simple detrás del valor de una spec. Según el equipo de RL Engineering de Anthropic, Claude Code tiene alrededor de un intento exitoso inicial en tres para pull requests pequeños y medianos sin guía detallada: en dos de cada tres casos no alcanza el requisito, interpreta mal el alcance o toma un camino de implementación distinto al que usted habría elegido.

Piense en decisiones: si en cada decisión Claude toma la misma que usted el 80% de las veces, y una característica razonable implica unas veinte decisiones, entonces la probabilidad de acertar las veinte es 0.8^20 —aproximadamente 1%. La spec elimina esas decisiones del agente: usted ya las tomó. Ese es el mecanismo que mejora sustancialmente la tasa de éxito.

Las cuatro fases — y la regla que muchos rompen

El desarrollo guiado por especificaciones funciona en cuatro fases claras:

• Requisitos: qué debe hacer la función desde la perspectiva del usuario. Historias, criterios de aceptación y casos límite. No es el cómo.
• Diseño: modelos de datos, contratos de API, qué archivos se modifican y qué queda fuera de alcance.
• Tareas: pasos de implementación ordenados con dependencias explícitas (la tarea 3 no puede empezar antes que la 2).
• Ejecución: el agente escribe código siguiendo la lista de tareas, una a la vez, en una sesión nueva.

La regla que muchos rompen es sencilla pero crítica: ejecutar en una sesión nueva. Mantener la misma sesión de planificación para la implementación parece eficiente, pero es contraproducente: la sesión de planificación contiene ideas rechazadas, preguntas y contextos exploratorios que no deberían influir en la ejecución. Cuando la ejecución ocurre en una sesión fresca, el agente solo “ve” los artefactos finales: SPEC.md y PLAN.md. Eso convierte a la especificación en la interfaz real entre diseño y ejecución.

Fase 1: deje que Claude le entreviste

Escribir una buena spec desde cero toma tiempo. Una alternativa eficaz es pedirle a Claude que extraiga la spec a partir de una entrevista dirigida. Un prompt de planificación en modo “plan” puede hacer preguntas específicas sobre implementación, casos límite, modos de falla y decisiones de trade-off. El flujo típico:

1. Indique la característica en una línea (por ejemplo, “login passwordless por magic link”).
2. Pida al agente que le entreviste en detalle usando la herramienta AskUserQuestion: que haga preguntas no obvias y siga hasta cubrir todos los casos.
3. Cuando la spec aparece, edítela directamente (por ejemplo, en SPEC.md) para convertirla en su documento.

Responder honestamente a las preguntas, incluyendo las que aún no tienen respuesta, es trabajo de diseño barato ahora y caro más adelante. Ese proceso hace visibles vacíos y decisiones pendientes que deben resolverse antes de implementar.

Escriba criterios que un comando pueda juzgar

Esta es la sección más importante y la que suele faltar en otros guías. Cada criterio de aceptación cae en dos categorías:

• Interpretable por un comando: existe un estado observable que define claramente el “fallo”.
• Autocalificado por el agente: el agente decide si pasó o no, lo que permite sesgos y validaciones inválidas.

Ejemplos de criterios interpretables (que un comando o test pueden comprobar):

• “Una petición con token expirado devuelve HTTP 401.”
• “La cuarta solicitud desde un mismo correo en una hora devuelve HTTP 429.”
• “Cada respuesta 4xx contiene una clave ‘error’ con un string.”
• “Exportar 10,000 filas completa en menos de 3 segundos en local.”
• “pytest sale 0 y el diff no agrega marcadores de skip.”

Lo que diferencia a estas reglas no es el tono, sino la existencia de un estado objetivo que cuenta como falla. Evite criterios vagos como “la interfaz debe ser intuitiva” o “la exportación debe ser rápida” sin umbrales medibles.

Notación EARS: un template práctico

Si prefieren no inventar la redacción cada vez, la notación EARS (Easy Approach to Requirements Syntax) es útil. Algunas formas prácticas:

• WHEN <disparador> THE system SHALL <respuesta>
  • WHEN se envía un email válido THE system SHALL enviar un enlace válido por 15 minutos.
• IF <condición> THEN THE system SHALL <respuesta>
  • IF un enlace se usa dos veces THEN THE system SHALL devolver HTTP 410.
• WHILE <estado> THE system SHALL <respuesta>
  • WHILE un usuario está rate limited THE system SHALL devolver HTTP 429.

Estas formas fomentan criterios claros, accionables y comprobables.

Revisar en un contexto que no vio la planificación

La revisión debe simular al revisor humano que recibe SPEC.md y PLAN.md —no a quien participó en la planificación. Pida a otro revisor humano o abra una sesión de revisión fresca con el agente: si la especificación está completa, cualquier persona que no vio la discusión original debería ser capaz de entender los requisitos y la lista de tareas sin preguntar por decisiones previamente resueltas.

Esto también ayuda a equipos distribuidos en América Latina donde la asincronía y la rotación de tareas son comunes: la spec es el único contrato claro entre quien diseñó y quien implementa.

Escalando trabajo en paralelo

Para trabajos mayores o equipos que quieren paralelizar, divida la spec en submódulos con interfaces estrictas y contratos de API. Definan tareas independientes con criterios de aceptación propios y pruebas que puedan ejecutarse en aislamiento. La clave es expresar dependencias explícitas en la sección de tareas: si la tarea B depende de la A, que la spec lo diga.

En entornos con CI, aseguren que cada PR tenga sus pruebas y que la pipeline falle si un criterio medible no se cumple. Eviten permitir marcadores skip que oculten problemas reales.

¿Necesitan un framework?

Un framework no es obligatorio, pero ayuda. Plantillas para SPEC.md, PLAN.md, y un checklist de criterios comprobables estandarizan el proceso y reducen errores humanos. Lo esencial no es la herramienta, sino seguir la disciplina: planear, documentar, cerrar decisiones y ejecutar en una sesión nueva.

Qué cambio en mi forma de trabajar

Aplicar estas reglas transformó cómo trabajo con agentes: ahora siempre convierto la planificación en artefactos editables (SPEC.md, PLAN.md), obligo a una revisión fresca y escribo criterios medibles. Esto reduce fugas de responsabilidad, evita falsos verdes en CI y hace más predecible la entrega de features.

Preguntas frecuentes

• ¿Por qué no ejecutar en la misma sesión de planificación?
  Porque la sesión contiene contexto descartado y decisiones exploratorias que pueden sesgar la implementación. Una sesión nueva fuerza a que el agente se limite a la spec.

• ¿Qué hacer si un criterio no es verificable automáticamente?
  Redúzcalo a un observable o definan una prueba manual con pasos concretos. Si no puede definirse un estado de fallo, no es un buen criterio.

• ¿Esto aplica a equipos pequeños o a freelancers?
  Sí. Incluso en equipos pequeños, una spec clara evita retrabajo y malentendidos, especialmente en trabajo remoto o asíncrono.

Conclusión

La parte difícil de la spec-driven development no es escribir la spec: es escribirla de modo que el agente no pueda fingir cumplimiento. Formular criterios verificables, ejecutar en sesiones nuevas y usar plantillas como EARS para la redacción reducen drásticamente el riesgo de entregas que “pasan” tests pero no resuelven problemas reales. Para equipos en América Latina, donde la colaboración remota y la presión de tiempo son comunes, esta disciplina mejora la calidad y previsibilidad del software.