Clarity Gate
La Clarity Gate (puerta de claridad) es una prueba de calidad de una spec con una sola pregunta: ¿puede un agente distinto, o una sesión nueva del mismo agente, generar código funcionalmente equivalente leyendo solo la spec? Si no, la spec tiene supuestos implícitos, y esos supuestos son la causa principal de la deriva de especificaciones: cuando la spec dice una cosa y el código ha evolucionado hacia otra.
Escribir una buena spec es la mitad del desafío; la otra mitad es mantenerla alineada con el código a medida que el proyecto avanza. La deriva pasa deprisa: basta una decisión menor del agente que la spec no cubría, o un ajuste durante la implementación que nadie llevó al documento. Una spec derivada es un riesgo activo, porque quien la consulta decide sobre información incorrecta.
La Clarity Gate como prueba y como diagnóstico
Es una prueba que cualquier equipo puede aplicar: se da la spec a otro agente sin contexto y se compara el resultado. Lo que el segundo agente hace distinto es lo que la spec no decía —conocimiento que vivía en la conversación original y no quedó escrito—. Sirve, además, como diagnóstico más limpio que la depuración tradicional: si la spec es correcta y el código no la cumple, el problema es de implementación y se regenera la tarea; si la spec es incorrecta, se corrige la spec y se regenera.
Los tres niveles de vida de una spec
La taxonomía de Böckeler describe cómo distintos equipos gestionan el ciclo de vida:
- Spec primero (spec-first). Se escribe antes de codificar, guía la tarea actual y se descarta. La deriva no es problema, pero se pierde la documentación como activo.
- Spec anclada (spec-anchored). Se mantiene como documentación viva del sistema: cuando el código cambia, la spec se actualiza. La deriva es un riesgo real que exige disciplina. Es donde trabaja hoy la mayoría de los equipos.
- Spec como fuente (spec-as-source). La spec es el artefacto principal: solo se edita la spec y el código se regenera. La deriva desaparece por diseño, pero sigue siendo experimental.
Estrategias para mantener specs vivas
Para los equipos que trabajan con specs ancladas, cuatro prácticas se han asentado:
- Actualizar la spec en el mismo commit que el cambio, porque «luego» no existe.
- Versionarla, con un historial de qué cambió y por qué.
- Revisar el estado de las specs en la retrospectiva, para decidir cuáles siguen vivas.
- Para las specs críticas, crear pruebas de conformidad que verifiquen que el código cumple la spec.
El patrón de verdad vigente y propuestas de cambio
A ellas se añade un patrón sencillo, popularizado por OpenSpec, que separa lo que es verdad vigente de lo que solo es propuesta de cambio. Las specs del sistema viven en un directorio; las propuestas de cambio, en otro. Cuando un cambio se completa, su spec se funde con la vigente y la propuesta se archiva. El patrón no depende de la herramienta: cualquier equipo puede adoptarlo con dos carpetas y una regla, y resuelve la confusión más frecuente —no saber si lo que se lee describe lo que hay o lo que se quería—.
Error frecuente
«Lo actualizo luego». Luego no existe: la spec se actualiza en el mismo commit que el cambio, o deriva. Igual de dañino es asumir que una spec está clara sin probarlo —la Clarity Gate revela supuestos implícitos que no se ven desde dentro de la conversación original— y mezclar en el mismo sitio lo vigente y lo propuesto, porque quien lee no sabe si describe lo que hay o lo que se quería, y el agente tampoco.
Recursos
📊 Guía didáctica SDDRecursos · Scrum Manager
🏦 SDD en equipos ágilesSkill Arena · Scrum Manager
Referencias
- Böckeler, Birgitta. (2025). «Understanding Spec-Driven Development». Thoughtworks / martinfowler.com.
- OpenSpec (documentación del proyecto).
Véase también
¿Quieres avanzar en agilidad? Puedes buscar convocatorias de cursos y exámenes o ir a tu ritmo haciéndote miembro del Club Agile. Esta membresía incluye recursos exclusivos, aulas e-learning y acceso a Skill Arena: un espacio para practicar y medir tus habilidades ágiles a tu ritmo.