Gestión de especificaciones: guardar, versionar y revisar especificaciones como código
La gestión de especificaciones es la forma en que un equipo guarda una especificación de software, registra cada cambio, revisa ese cambio y mantiene la especificación al día. La gestión de la especificación es el mismo trabajo: una especificación es el documento que dice qué debe hacer el software, y gestionarla es cómo el documento sigue siendo localizable y fiable. Gestionar las especificaciones como código significa que esos documentos son archivos en el sistema de control de versiones, de modo que un cambio en una especificación es un commit que un revisor puede comparar. El versionado de especificaciones es el historial de esos commits, junto con el estado escrito en cada documento. Mantener las especificaciones sincronizadas con el código significa que un cambio propuesto que rompe la estructura de la especificación falla la misma comprobación automática por la que pasa el cambio de código. El desarrollo basado en especificaciones (SDD, spec-driven development) es la práctica de escribir la especificación antes del código y tratarla como la fuente de verdad. La integración continua (CI, continuous integration) es una comprobación automática en cada cambio propuesto. Un documento de requisitos de producto (PRD, product requirements document) es la prosa que enuncia el problema y el alcance; la plantilla de PRD en Markdown es un archivo de funcionalidad de SpecScore con esa forma. Easy Approach to Requirements Syntax (EARS) es un patrón de frase para un requisito. En SpecScore, un requisito (REQ) es una regla con nombre dentro de una funcionalidad, y un criterio de aceptación (AC, acceptance criterion) es una condición abstracta y opcional que apunta a una o más de esas reglas. La comprobación es un comando de la interfaz de línea de comandos (CLI, command-line interface), specscore spec lint, documentado en lintear especificaciones en CI. El formato vive en el repositorio público specscore/specscore (CC BY 4.0). La CLI vive en specscore/specscore-cli (Apache-2.0).
Última actualización: 9 de noviembre de 2026
Dónde se guarda la especificación
La gestión de especificaciones empieza por un lugar donde puedan vivir los archivos. En este repositorio la especificación es Markdown bajo spec/. El README de spec enumera los directorios: funcionalidades, planes, ideas, decisiones y lecciones. Una funcionalidad es un directorio con un README.md. La especificación de funcionalidad es el contrato de ese archivo, y la plantilla de PRD es un ejemplo relleno que un linter ha aceptado.
specscore spec lint no adivina qué árbol leer. internal/cli/spec.go en la etiqueta v0.55.1, y la misma función en la etiqueta v0.39.1, sube desde el directorio de trabajo hasta encontrar specscore.yaml. El comentario de esa función dice que el comando exige el archivo, devuelve el código de salida 3 cuando falta y te indica que ejecutes specscore init. El workflow dogfood de este repositorio instala la CLI v0.39.1 y luego ejecuta specscore spec lint, así que el checkout que lintea tiene ese archivo de configuración.
Un índice acompaña a los archivos de funcionalidad. La regla feature-index-row-sync es un error en el catálogo de lint de v0.39.1 y de v0.55.1. La línea del catálogo dice que exige que cada fila del índice de funcionalidades coincida con su archivo de funcionalidad. Eso es el índice alineado con el documento al que apunta. No es una comparación de la redacción del requisito con un archivo de código fuente.
Versionado de especificaciones
El versionado de especificaciones, para archivos confirmados en git, es el historial de commits de esos archivos. SpecScore no añade un segundo número de versión a una funcionalidad. La revisión que mira un revisor es el commit de la rama. La línea de estado del documento dice en qué punto del ciclo de vida está esa funcionalidad, que es un hecho distinto del hash de git.
La especificación de funcionalidad en el repositorio tiene ella misma **Status:** Stable. Exige una línea **Status:** inmediatamente después del título, y el valor debe ser uno de Draft, In Review, Approved, Implementing, Stable, Amending, Rejected o Deprecated. La regla status-mirror, en los dos catálogos citados arriba, exige que el status: del frontmatter de un artefacto con estado coincida con esa línea del cuerpo, y prohíbe status: en un tipo que no tiene estado. Hacer coincidir las dos copias no es lo mismo que rechazar una palabra fuera de los ocho valores. Ninguna de las dos líneas del catálogo describe una regla que rechace un estado de funcionalidad fuera de ese conjunto, así que esta página no afirma que exista.
Los planes usan otro conjunto. La regla P-006, en ambos catálogos, exige que el **Status:** del cuerpo de un plan de un solo archivo sea uno de Draft, In Review, Approved, Executing, Blocked, Implemented, Failed, Rejected, Withdrawn, Superseded o Deprecated. La regla idea-status-values rechaza un estado de idea fuera del conjunto que esa regla permite. El catálogo es la lista. Esta página no repite las palabras de las ideas.
La especificación de plan también describe una tabla opcional ## Snapshots con las columnas Date, Git Hash, Action y Comment. Dice que cada instantánea referencia un hash de commit de git del estado del plan en ese momento. Los dos catálogos de lint revisados para esta página no nombran una regla que resuelva ese hash, así que esta página no afirma que el linter compruebe que el commit existe. El hash es un puntero que una persona puede seguir en git. La especificación de plan publicada es la página de formato de ese documento.
Revisar una especificación
La revisión de una especificación en Markdown es la pull request que la cambia. dogfood.yml se ejecuta en pull_request y en un push a main. El job hace checkout del repositorio, instala la CLI con SPECSCORE_VERSION en v0.39.1 y ejecuta specscore spec lint sin flags extra. GitHub Actions falla el paso cuando ese proceso termina con un código distinto de cero. Los permisos del workflow son contents: read.
El estado de funcionalidad In Review significa que la funcionalidad se presenta para revisión. Escribir esa palabra es una edición del archivo Markdown. La pull request es donde una persona lee el diff. status-mirror comprueba que el frontmatter y el cuerpo nombran el mismo estado. No registra que un revisor haya estado de acuerdo con la prosa. La página de validadores separa esa comprobación estructural de una lectura que una persona todavía tiene que hacer. El relato regla por regla de lo que informa specscore spec lint está en lintear especificaciones en CI.
Mantener las especificaciones sincronizadas con el código
Mantener las especificaciones sincronizadas con el código, en este sitio, significa que la especificación está en el repositorio con el proyecto, y que la CI falla la pull request cuando el árbol de la especificación viola el formato. Una pull request puede cambiar un archivo de funcionalidad y el código en el mismo diff. La regla feature-index-row-sync mantiene una fila del índice alineada con el archivo de funcionalidad que nombra. No lee un archivo fuente para decidir si el código implementa el requisito.
El extracto de abajo son los pasos de instalación y lint de dogfood.yml. El archivo del workflow también fija permisos, un grupo de concurrencia y un comentario sobre por qué el pin no es latest. Esas líneas se omiten aquí. Los comandos son los que ejecuta ese archivo.
name: Dogfood lint
on:
push:
branches: [main]
pull_request:
jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
- name: Install specscore CLI (pinned)
env:
SPECSCORE_VERSION: v0.39.1
run: |
curl -fsSL https://specscore.md/install/get-cli | \
SPECSCORE_INSTALL_DIR="$HOME/.local/bin" sh
echo "$HOME/.local/bin" >> "$GITHUB_PATH"
specscore --version
- name: Lint spec tree
run: specscore spec lint
El comentario de ese archivo dice que un pin flotante latest cambia la compuerta bajo el repositorio: una pull request y la rama main a la que apunta pueden ver reglas distintas. El pin es v0.39.1. El job no pasa --fix. Una ejecución limpia y una que falla, incluida la línea file:line [severity] rule: message, se muestran en lintear especificaciones en CI.
Una frase de la especificación que ya no describe el código no es uno de esos hallazgos. specscore spec lint valida la estructura: archivos y secciones obligatorios, filas de índice, forma de los encabezados y las referencias que nombran las reglas. No puntúa si la implementación coincide con el requisito. Ese límite es el sentido de la página de validadores. Mantener verdadera la prosa sigue siendo una revisión del diff.
Cómo comprueban una especificación otras herramientas de desarrollo basado en especificaciones
Los párrafos de abajo usan las páginas obtenidas el 9 de noviembre de 2026. Describen las comprobaciones propias de esas herramientas. No dicen cuántos productos existen ni ordenan un mercado. La comparativa de herramientas es la comparación más larga.
La referencia de SDD agéntico de GitHub Spec Kit describe /speckit.analyze como una comprobación de solo lectura sobre spec.md, plan.md y tasks.md. Informa de conflictos, huecos y ambigüedades, no edita archivos, y se ejecuta en el agente antes de la implementación. La lista de comandos de esa misma página no describe un job de CI que ejecute specscore spec lint contra un árbol de SpecScore.
OpenSpec guarda un cambio como un directorio directamente bajo openspec/changes/. openspec validate comprueba cambios y especificaciones en busca de problemas de estructura. La referencia dice que el código de salida 0 significa que cada elemento validado pasó, y que el código 1 significa que un elemento falló, que la petición de informe no es válida, que la configuración no se puede leer o que la ejecución falló. Esa comprobación es la forma de OpenSpec, incluidos sus bloques de requisito y de escenario, no un encabezado ### AC: de SpecScore. En otro comando, openspec status, la misma referencia dice que un lote que no puede cargar un cambio igual termina con 1, «so CI doesn’t accept an incomplete report as successful». Esa frase es sobre openspec status, no sobre openspec validate.
Preguntas frecuentes
¿Qué es la gestión de especificaciones?
La gestión de especificaciones es guardar una especificación de software, registrar cada cambio, revisar ese cambio y mantener la especificación al día. En SpecScore los archivos son Markdown en el repositorio git, y specscore spec lint es la comprobación estructural que un job de CI puede hacer fallar.
¿Qué es la gestión de la especificación?
La gestión de la especificación es la misma práctica. La especificación es el documento que dice qué debe hacer el software. Gestionarla significa que el documento tiene un lugar conocido, un historial, una revisión y una comprobación de que su estructura sigue coincidiendo con el formato.
¿Cómo funciona gestionar las especificaciones como código?
La especificación es un árbol de archivos Markdown bajo spec/, más specscore.yaml en la raíz del repositorio. Un cambio es un commit. Una pull request revisa el diff. dogfood.yml ejecuta specscore spec lint en esa pull request.
¿Cómo funciona el versionado de especificaciones?
El historial de git es el historial de versiones de los archivos. Una funcionalidad también lleva **Status:** con uno de los ocho valores que exige la especificación de funcionalidad. Un plan puede registrar una fila ## Snapshots cuyo Git Hash es un commit del estado del plan. Los catálogos del linter citados aquí no describen una regla que resuelva ese hash.
¿Cómo se mantienen las especificaciones sincronizadas con el código?
Pon la especificación en el repositorio y haz fallar la pull request cuando specscore spec lint informe de una violación estructural, incluida una fila de índice que no coincide con su archivo de funcionalidad. El comando no decide si el código implementa el requisito. Una frase que se ha desviado del código sigue necesitando que una persona lea el diff.
Fuentes
Archivos de la CLI y catálogos de lint leídos el 9 de noviembre de 2026 en las etiquetas v0.39.1 de specscore-cli (la versión que instala dogfood.yml) y v0.55.1. Los requisitos de funcionalidad y de plan son los archivos enlazados abajo en specscore/specscore. Las páginas de la competencia se obtuvieron el mismo día.
- specscore/specscore — spec/README.md
- specscore/specscore — valores de estado de la funcionalidad
- specscore/specscore — instantáneas del plan
- specscore/specscore
- specscore/specscore — licencia CC BY 4.0
- specscore/specscore-cli
- specscore-cli — licencia Apache-2.0
- specscore-cli v0.39.1 — internal/cli/spec.go
- specscore-cli v0.55.1 — internal/cli/spec.go
- specscore-cli v0.39.1 — catálogo de reglas de lint
- specscore-cli v0.55.1 — catálogo de reglas de lint
- specscore/specscore — dogfood.yml (CLI v0.39.1)
- Qué valida SpecScore
- Lintear especificaciones en CI con un linter de especificaciones
- Sintaxis de requisitos EARS explicada, con ejemplos
- Cómo escribir criterios de aceptación que un agente de IA pueda verificar
- Plantilla de PRD en Markdown para programar con IA
- Especificación de funcionalidad
- Especificación de plan
- GitHub Spec Kit — referencia de SDD agéntico (/speckit.analyze)
- Referencia de la CLI de OpenSpec — openspec validate y openspec status
- Fission-AI/OpenSpec
- Herramientas de desarrollo basado en especificaciones
Relacionado
- Lintear especificaciones en CI con un linter de especificaciones
- Plantilla de PRD en Markdown para programar con IA
- Cómo escribir criterios de aceptación que un agente de IA pueda verificar
- Sintaxis de requisitos EARS explicada, con ejemplos
- Desarrollo basado en especificaciones
- Herramientas de desarrollo basado en especificaciones
- Especificación de funcionalidad
- Especificación de plan
- CLI
- Qué valida SpecScore