SpecScore vs Plain Markdown
A maioria dos times já tem "especificações" — como Markdown ad-hoc numa pasta de docs, páginas do Notion ou tickets do Jira. É gratuito, já está lá e funciona. O SpecScore é o mesmo Markdown, mais a estrutura que um agente de IA pode fazer lint, consultar e rastrear de volta ao código.
O que têm em comum.
O que o padrão faz bem.
Plain Markdown, Notion e Jira são o verdadeiro padrão. Eles merecem.
Curva de aprendizado zero
Não há schema, nem campos obrigatórios, nem CLI no loop. Abra um arquivo, comece a digitar. Para uma nota pontual ou um projeto minúsculo, isso é exatamente certo — estrutura de que você não precisa é só fricção.
Já instalado
Seu time já está no Notion, Confluence ou numa pasta docs/. Nada para adotar, nada para migrar. A opção de menor fricção é aquela que você já está usando.
Universalmente portável
Plain Markdown abre em qualquer lugar e sobrevive a qualquer ferramenta. O SpecScore é construído sobre exatamente essa propriedade — é por isso que o SpecScore também é Markdown, não um banco de dados.
Comparação de funcionalidades.
A diferença não é o arquivo — é o que um agente consegue fazer com ele.
| Capacidade | Plain Markdown / Notion | SpecScore |
|---|---|---|
| Formato | Markdown / docs em formato livre | Markdown + YAML frontmatter (estruturado) |
| Onde os requisitos vivem | Jira, Notion, Slack, na cabeça de alguém | No repositório, junto ao código |
| "Esta especificação está completa?" | Um humano lê e decide | specscore lint — automático |
| Detecção de ambiguidade | Nenhuma — verbos vagos passam silenciosamente | Verbos vagos, ACs ausentes, referências soltas sinalizados |
| IDs de requisitos / ACs | Nenhum | IDs endereçáveis por máquina (REQ: slug) |
| Status do ciclo de vida | Implícito, se rastreado de alguma forma | Imposto — Draft → Approved → Implementing → Stable |
| Rastreabilidade código-para-especificação | Nenhuma | specscore: anotações + Verifies: trailers |
| Navegação de agentes | Ler cada arquivo para achar qualquer coisa | Consultar o grafo de especificações pelo CLI |
| Quality gate em CI | Nenhum | specscore lint retorna código diferente de zero, como um linter |
| Curva de aprendizado | Nenhuma | Um formato para aprender (incremental) |
| Custo / licença | Gratuito | Gratuito, open source |
Onde o SpecScore vai além.
A ambiguidade é detectada, não interpretada
Com especificações em formato livre, toda interação com o agente começa com interpretação — "o login deveria funcionar" é um cara ou coroa entre o certo e o plausível-mas-errado. O lint do SpecScore sinaliza o verbo vago e o critério de aceitação ausente antes que um agente aja sobre ele.
$ specscore lint auth/login.md ✗ R1 "should work" — unmeasurable ✗ R1 no acceptance criteria
A má interpretação para de se acumular
Um agente lê errado um requisito, um segundo constrói em cima disso, um terceiro depende de ambos — e você só percebe três agentes depois. Critérios de aceitação estruturados dão a todo agente as mesmas condições de aprovação/falha, então a interpretação não deriva entre eles.
O código rastreia de volta à especificação
Documentos simples não têm vínculo com o código que os implementa. O SpecScore adiciona anotações de origem specscore: e trailers de commit Verifies: — o specscore code refs responde "qual código implementa este requisito?" de forma determinística.
Uma especificação em vez de quarenta tickets
Um novo colega de time (ou um agente novo) lê uma especificação de feature com todo o contexto, em vez de reconstruir a intenção a partir de quarenta tickets do Jira e uma thread do Slack.
Agentes consultam, em vez de reler
Numa pasta de docs, achar "o que está em andamento?" significa abrir arquivos. No SpecScore, é specscore feature list — o grafo de especificações responde pelo CLI, então agentes não queimam contexto relendo o repositório.
A qualidade é imposta no CI
Especificações em formato livre não têm gate — uma pela metade faz merge tão fácil quanto uma completa. O specscore lint retorna código diferente de zero em problemas, do mesmo jeito que o ESLint ou go vet protegem o código.
Quando usar cada um.
Plain Markdown está bom quando…
- É uma nota pontual, um spike ou um projeto pequeno demais para precisar de estrutura.
- Nenhum agente de IA vai construir a partir do documento — um humano lê e simplesmente entende.
- Você está capturando uma ideia bruta, não um requisito que alguém vai implementar.
Use o SpecScore quando…
- Um agente de IA constrói a partir da especificação — ambiguidade vira código errado.
- Múltiplos agentes ou pessoas dependem dos mesmos requisitos.
- Você precisa saber qual código implementa qual requisito.
- "Esta especificação está pronta?" deveria ser respondido por uma ferramenta, não por uma reunião.
- O projeto é grande o suficiente para que reler tudo não escale.
Promova as especificações que você já tem.
Você não converte o seu backlog nem muda as suas ferramentas. Escolha a sua próxima feature, escreva uma especificação SpecScore para ela e rode specscore lint — veja se ela pega algo que o seu ticket deixou passar. Adicione anotações specscore:quando implementá-la. Expanda para o próximo sprint só se ajudou.
Plain Markdown é a rampa de entrada. O SpecScore é para onde ele cresce.
Feedback
Esta comparação é baseada em documentação e código-fonte publicamente disponíveis. Algo incorreto ou desatualizado? abra uma issue de correção. Quer que comparemos o SpecScore com outra ferramenta? solicite uma.