SpecScore vs Plain Markdown
La mayoría de los equipos ya tienen "especificaciones" — como Markdown ad-hoc en una carpeta de docs, páginas de Notion o tickets de Jira. Es gratis, ya está ahí y funciona. SpecScore es el mismo Markdown, más la estructura que un agente de IA puede lintear, consultar y trazar de vuelta al código.
Lo que tienen en común.
Lo que lo predeterminado hace bien.
Plain Markdown, Notion y Jira son el verdadero predeterminado. Se lo han ganado.
Curva de aprendizaje cero
No hay esquema, ni campos obligatorios, ni CLI en el flujo. Abre un archivo, empieza a escribir. Para una nota puntual o un proyecto diminuto, eso es exactamente lo correcto — la estructura que no necesitas es solo fricción.
Ya está instalado
Tu equipo ya está en Notion, Confluence o una carpeta docs/. Nada que adoptar, nada que migrar. La opción de menor fricción es la que ya estás usando.
Universalmente portable
Plain Markdown se abre en cualquier lugar y sobrevive a cualquier herramienta. SpecScore está construido sobre exactamente esta propiedad — es por eso que SpecScore también es Markdown, no una base de datos.
Comparación de funcionalidades.
La diferencia no es el archivo — es lo que un agente puede hacer con él.
| Capacidad | Plain Markdown / Notion | SpecScore |
|---|---|---|
| Formato | Markdown libre / docs | Markdown + YAML frontmatter (estructurado) |
| Dónde viven los requisitos | Jira, Notion, Slack, la cabeza de alguien | En el repositorio, junto al código |
| "¿Esta especificación está completa?" | Un humano la lee y decide | specscore lint — automático |
| Detección de ambigüedad | Ninguna — los verbos vagos pasan en silencio | Verbos vagos, ACs faltantes, referencias colgantes señalados |
| IDs de requisitos / ACs | Ninguno | IDs direccionables por máquina (REQ: slug) |
| Estado del ciclo de vida | Implícito, si se rastrea siquiera | Aplicado — Draft → Approved → Implementing → Stable |
| Trazabilidad código-a-especificación | Ninguna | specscore: anotaciones + Verifies: trailers |
| Navegación de agentes | Leer cada archivo para encontrar algo | Consultar el grafo de especificaciones desde el CLI |
| Puerta de calidad en CI | Ninguna | specscore lint sale con código no-cero, como un linter |
| Curva de aprendizaje | Ninguna | Un formato que aprender (incremental) |
| Costo / licencia | Gratis | Gratis, open source |
Donde SpecScore va más allá.
La ambigüedad se detecta, no se interpreta
Con especificaciones libres, cada interacción con un agente comienza con interpretación — "el login debería funcionar" es una moneda al aire entre correcto y plausible-pero-incorrecto. El lint de SpecScore señala el verbo vago y el criterio de aceptación faltante antes de que un agente actúe sobre ello.
$ specscore lint auth/login.md ✗ R1 "should work" — no medible ✗ R1 no acceptance criteria
La mala interpretación deja de acumularse
Un agente malinterpreta un requisito, un segundo construye sobre él, un tercero depende de ambos — y te das cuenta tres agentes después. Los criterios de aceptación estructurados dan a cada agente las mismas condiciones de aprobado/fallido, así la interpretación no deriva entre ellos.
El código se traza de vuelta a la especificación
Los docs simples no tienen vínculo con el código que los implementa. SpecScore agrega anotaciones de fuente specscore: y trailers de commit Verifies:— specscore code refs responde "¿qué código implementa este requisito?" de forma determinista.
Una especificación en lugar de cuarenta tickets
Un nuevo compañero de equipo (o un agente fresco) lee una especificación de feature con todo el contexto, en lugar de reconstruir la intención a partir de cuarenta tickets de Jira y un hilo de Slack.
Los agentes consultan, en lugar de releer
En una carpeta de docs, encontrar "¿qué está en progreso?" significa abrir archivos. En SpecScore, es specscore feature list — el grafo de especificaciones responde desde el CLI, así los agentes no queman contexto releyendo el repositorio.
La calidad se aplica en CI
Las especificaciones libres no tienen puerta — una escrita a medias se mergea tan fácil como una completa. specscore lint sale con código no-cero ante problemas, igual que ESLint o go vet protegen el código.
Cuándo usar cada uno.
Plain Markdown está bien cuando…
- Es una nota puntual, un spike o un proyecto demasiado pequeño para necesitar estructura.
- Ningún agente de IA construirá a partir del doc — un humano lo lee y simplemente lo entiende.
- Estás capturando una idea aproximada, no un requisito que alguien implementará.
Recurre a SpecScore cuando…
- Un agente de IA construye a partir de la especificación — la ambigüedad se convierte en código incorrecto.
- Múltiples agentes o personas dependen de los mismos requisitos.
- Necesitas saber qué código implementa qué requisito.
- "¿Está terminada esta especificación?" debería responderlo una herramienta, no una reunión.
- El proyecto es lo bastante grande como para que releer todo no escale.
Haz evolucionar las especificaciones que ya tienes.
No conviertes tu backlog ni cambias tus herramientas. Elige tu próxima feature, escribe una especificación de SpecScore para ella y ejecuta specscore lint — mira si detecta algo que tu ticket pasó por alto. Agrega anotaciones specscore:cuando la implementes. Expande al siguiente sprint solo si ayudó.
Plain Markdown es la rampa de entrada. SpecScore es a lo que evoluciona.
Comentarios
Esta comparación se basa en documentación y código fuente públicamente disponibles. ¿Algo incorrecto o desactualizado? abre un issue de corrección. ¿Quieres que comparemos SpecScore con otra herramienta? solicita una.