Spec writing
El spec writing (escritura de especificaciones) es la práctica de redactar documentos estructurados que describen con precisión qué debe construir un agente de IA, cómo debe comportarse y con qué restricciones debe operar. En el marco del Spec-Driven Development (SDD), la spec es el artefacto primario del desarrollo: el contrato entre el equipo humano y el agente que va a ejecutar el trabajo.
El spec writing es una competencia central del product builder y una de las formas más eficaces de reducir las alucinaciones y los outputs inconsistentes de los agentes de IA.
La spec como artefacto co-creado
La spec «nace dentro del equipo que construye» (Yeret): es un paso adelante cuando la escribe quien va a construir y un paso atrás cuando alguien la entrega desde fuera.
No es un documento que el humano entrega al agente, sino uno que se construye en colaboración. El humano aporta el qué y el por qué —la dirección estratégica, los requisitos de negocio, las restricciones— y el agente propone el cómo con nivel de detalle. El humano valida, corrige y aprueba.
Esta colaboración aprovecha las fortalezas de cada parte: los modelos de lenguaje son excelentes elaborando detalles cuando tienen una directiva de alto nivel clara, pero se pierden cuando no tienen una misión definida. El humano aporta la dirección; el agente aporta la exhaustividad.
Las seis áreas de una spec efectiva
GitHub analizó más de 2.500 ficheros de configuración de agentes en repositorios públicos y encontró un patrón claro: las specs más efectivas cubren seis áreas (publicado en el GitHub Blog en 2025):
- Comandos: no solo nombres de herramientas sino comandos completos con parámetros. No "usar npm" sino "npm run build para compilar, npm test para ejecutar tests, npm run lint --fix para corregir estilo".
- Testing: cómo ejecutar los tests, qué framework se usa, dónde viven los ficheros de test, qué cobertura se espera.
- Estructura del proyecto: dónde vive el código fuente, los tests, la documentación. Ser explícito: "src/ para código de aplicación, tests/ para tests unitarios".
- Estilo de código: un fragmento real de código que muestre el estilo del proyecto vale más que tres párrafos describiéndolo. Convenciones de naming, reglas de formato, ejemplos de output esperado.
- Flujo git: nomenclatura de ramas, formato de mensajes de commit, requisitos de pull request.
- Boundaries: qué no debe tocar el agente nunca. Secretos, directorios de dependencias, configuraciones de producción. El sistema Always / Ask First / Never formaliza estas restricciones.
Specs vivas frente a specs estáticas
Una decisión relevante en el spec writing es si la spec se mantiene viva después de la implementación (spec-anchored) o si se usa como guía de construcción y luego se descarta (spec-first):
- Las specs spec-anchored se mantienen sincronizadas con el código y sirven como documentación viva del sistema. Requieren un proceso de mantenimiento activo.
- Las specs spec-first orientan la construcción y luego se archivan o descartan. Más ligeras, pero sin el beneficio de la documentación persistente.
No todas las specs merecen mantenerse. La regla práctica es: si la spec responde a preguntas que el equipo seguirá teniendo en el futuro, mantenerla. Si solo responde a preguntas de la construcción inicial, descartarla.
Antipatrones del spec writing
La guía Spec Driven Development en equipos ágiles de Scrum Manager (edición de septiembre de 2026) cataloga cuatro modos de fallo del método mal aplicado:
- Sobreespecificación: el equipo invierte más tiempo en perfeccionar la spec que en producir software que funciona; su forma extrema es aplicar la misma intensidad a un defecto trivial y a una funcionalidad compleja.
- Puertas como cuellos de botella: una aprobación se bloquea porque quien debe aprobar no está disponible o no da abasto. La respuesta es delegar, admitir la aprobación asíncrona y acortar las specs, no eliminar la puerta.
- Teatro de la especificación: se escriben specs que nadie revisa de verdad y el proceso se ejecuta de forma mecánica. Una puerta que nunca rechaza nada, o una spec que nunca cambia tras su revisión, no indica que todo esté bien: indica que nadie está mirando.
- Documentación zombi: specs que nadie consulta ni actualiza. Decidir qué specs mantener vivas y cuáles dejar morir forma parte de la gestión.
Los cuatro comparten remedio: el principio de proporcionalidad, y alguien (el agile enabler) que mire el proceso además de a quienes lo ejecutan.
Error frecuente
Escribir specs como prosa libre en lugar de como documentos estructurados. Los agentes procesan mejor la información estructurada que la prosa libre. Una spec con secciones claras, encabezados consistentes y formato predecible permite al agente localizar rápidamente la información relevante para cada tarea. Una spec redactada como un documento de texto narrativo produce outputs más variables e inconsistentes que una spec estructurada con el mismo contenido.
Recursos
📊 Guía didáctica SDDRecursos · Scrum Manager
🏦 SDD en equipos ágilesSkill Arena · Scrum Manager
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.