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 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
El SDD.pdf de Scrum Manager identifica tres antipatrones frecuentes:
- Documentación zombi: el proyecto acumula specs que nadie consulta, actualiza ni elimina. Las specs están desactualizadas y cualquiera que las consulte obtendrá información incorrecta.
- El teatro de la especificación: el equipo escribe specs y ejecuta las puertas de aprobación, pero la revisión es superficial. Nadie lee realmente la spec en profundidad; las puertas se convierten en un trámite.
- SDD como herramienta de control: las specs se usan para microgestionar al equipo. Cada decisión debe estar en una spec aprobada. La autonomía del product builder desaparece.
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.