Comando Clarify: Casos borde, ambigüedades y supuestos

El comando Clarify de Spec Kit toma tu especificación terminada y la somete a un interrogatorio riguroso para encontrar vacíos y ambigüedades antes de escribir una sola línea de código. Si desarrollas con inteligencia artificial y quieres evitar que la IA decida por ti, aquí aprendes cómo funciona.

Apenas terminas tu especificación con historias de usuario, requisitos funcionales y criterios de aceptación, sientes la tentación de programar. Pero por muy bien definida que esté, casi siempre quedan lagunas o falta información. Y aquí viene lo interesante: si dejas esos huecos abiertos, la IA los rellena por su cuenta y tu aplicación termina con divergencias.

¿Qué hace el comando Clarify en Spec Kit?

Clarify revisa tu archivo spec.md, identifica las ambigüedades y genera preguntas concretas que tú debes responder. Con cada respuesta, edita el archivo directamente: elimina lo que sobra y agrega la información nueva que le proporcionas.

¿Para qué sirve el comando Clarify? Sirve para detectar vacíos y ambigüedades en tu especificación. Genera preguntas puntuales, y con tus respuestas actualiza automáticamente el archivo spec.md para que la IA no tome decisiones por ti.

Lo importante es esto: no reemplaza tu criterio, lo activa. La IA te recomienda una opción, pero tú decides si la sigues o eliges otra.

¿Cómo se ejecuta Clarify paso a paso?

Cada comando se trabaja en un rama de git independiente. El flujo que se muestra en la clase es directo:

1. Abre la terminal y ubícate en la raíz del proyecto, en este caso my project [00:41].
2. Verifica en qué rama estás; aquí veníamos de la rama spec [00:57].
3. Crea una rama nueva con git checkout -b clarify [01:07].
4. Abre Cloud con el comando cloud y ejecuta speckit-clarify [01:20].

No necesitas escribir ningún prompt. Al presionar Enter, Cloud Code empieza a analizar el spec.md y tarda cerca de uno o dos minutos en generar las preguntas [02:00].

¿Qué tipo de preguntas genera Clarify?

El comando arranca preparando hasta cinco preguntas, cada una ligada a un requisito funcional específico. En la práctica de la clase se respondieron cuatro, porque el resto se consideró de bajo impacto.

¿Clarify siempre hace cinco preguntas? No. Genera hasta cinco, pero solo mantiene las relevantes. En este ejercicio hizo cuatro y descartó áreas como accesibilidad o límites de tasa por ser de bajo impacto.

Cada pregunta llega con una recomendación y varias opciones. Estas fueron las cuatro que aparecieron:

• Duración de sesión activa [02:25]: afecta al requisito funcional 4. La opción recomendada era 24 horas, un tiempo de vida moderado y razonable para una app de reservas deportivas sin datos sensibles críticos. Se aceptó la recomendada.
• Qué ve un visitante sin sesión [03:30]: la IA recomendaba mostrar el catálogo de cinco campos solo con nombres. Aquí se eligió la opción A, nada visible: el visitante solo ve login y registro.
• Reservas canceladas en el historial [04:35]: se optó por la opción A, que la reserva aparezca marcada como cancelada por temas de rastreo de lo que hace el usuario.
• Longitud mínima de contraseña [05:12]: la IA sugería cuatro caracteres como mínimo comúnmente aceptado, pero se le indicó que ocho estaba bien.

Cuando ninguna opción te convence, puedes escribir la tuya propia, como pasó con la segunda pregunta [03:55]. Y cada vez que respondes, ves en pantalla esos signos de más y menos: Cloud Code está editando spec.md en vivo, quitando y agregando información.

¿Qué entrega Clarify al terminar?

Una vez cerrada la ronda, el comando avisa que no detectó más aclaraciones necesarias [06:05]. Las áreas restantes (accesibilidad, límites de tasa, múltiples sesiones por dispositivo y volumen de datos) se marcaron como de bajo impacto.

El reporte final incluye varios elementos útiles:

• Un resumen de las preguntas y las respuestas que diste.
• El archivo actualizado, en este caso spec.md.
• Las historias de usuario y requisitos funcionales modificados.
• Un cuadro de cobertura por categoría y estado [06:40].

Ese cuadro te dice qué quedó resuelto: alcance funcional y comportamiento, modelo y dominio de datos, entre otros. Y lo que no se resolvió, como integraciones externas, aparece marcado explícitamente como fuera de alcance.

¿Cómo verificas los cambios en el archivo spec.md?

Abres tu carpeta, abres el spec.md y revisas lo que cambió. En el ejemplo se agregó un nuevo requisito funcional, el 4A [07:10], que indica que un visitante sin sesión activa no debe ver el catálogo de campos. Ese fue justo el resultado de la segunda pregunta del Clarify.

La analogía que se usa lo deja claro: ya tienes las leyes de la ciudad, que son la constitución de tu proyecto, y ya tienes los planos, que son tus especificaciones. Pero si le entregas eso a un albañil, empieza a apilar ladrillos y al final los caños no encajan ni las paredes alinean. Falta un plan de trabajo, un plan de ingeniería, y eso se construye en la siguiente clase.

¿Qué cambios te sugirió Clarify que tú no habías considerado? Cuéntanos en los comentarios cuáles fueron esas preguntas que te destaparon vacíos en tu especificación.