Calidad desde la especificación
La calidad empieza antes de escribir código. El objetivo de la especificación es acercarnos a un proceso más determinista: menos interpretación, menos trabajo especulativo y menos iteraciones de IA.
La spec no es burocracia. Es el contrato que permite que los agentes trabajen sobre una fuente de verdad y que la revisión pueda comprobar si el resultado cumple lo acordado.
Entrada típica
Sección titulada «Entrada típica»Una spec parte de una necesidad o requisito y se completa con el contexto imprescindible:
- Objetivo funcional.
- Criterios de aceptación.
- Restricciones de producto o negocio.
- Riesgos e impacto entre apps o sistemas.
- Diseño visual si aplica.
- Reglas de arquitectura.
- Validaciones esperadas.
- Supuestos que deben aprobarse.
Papel del Spec Author
Sección titulada «Papel del Spec Author»El agente Spec Author transforma una petición inicial en documentación revisable.
Debe producir:
spec.md: qué se pide, criterios, alcance y supuestos.design.md: cómo se resuelve, decisiones técnicas, riesgos y alternativas.tasks.md: tareas ejecutables, orden recomendado y estado.
La persona aprueba, corrige o bloquea la spec antes de delegar implementación.
Qué debe contener una buena spec
Sección titulada «Qué debe contener una buena spec»Requirements
Sección titulada «Requirements»Explica la necesidad con lenguaje claro, sin saltar directamente a la solución.
Criterios de aceptación
Sección titulada «Criterios de aceptación»Define cómo sabremos que el trabajo está completo.
Riesgos e impacto
Sección titulada «Riesgos e impacto»Identifica dependencias, cambios colaterales, impacto entre apps y decisiones que requieren criterio humano.
Diseño técnico
Sección titulada «Diseño técnico»Describe la solución propuesta y cómo encaja con la arquitectura del proyecto.
Plan ejecutable
Sección titulada «Plan ejecutable»Divide el trabajo en tareas pequeñas que puedan implementarse y validarse.
Beneficios
Sección titulada «Beneficios»- Menos requisitos mal interpretados.
- Menos iteraciones de IA.
- Menos consumo de tokens.
- Menos retrabajo.
- Menos contexto contaminado.
- Mejor revisión humana.
Errores habituales
Sección titulada «Errores habituales»- Usar la spec como resumen del ticket, sin decisiones ni supuestos.
- No pedir aprobación humana cuando hay ambigüedad.
- Crear tareas demasiado grandes.
- No definir validaciones antes de implementar.
- No reconciliar cambios de spec cuando aparece información nueva.
Default recomendado
Sección titulada «Default recomendado»Si la petición no se puede explicar como spec validable, todavía no está lista para implementación asistida por IA.