O que o SpecScore
valida.
O SpecScore é um formato aberto em Markdown para features, requisitos e critérios de aceitação — verificado por dois validadores: umlinter determinístico e umrevisor de IA. Veja o que cada um pega, e onde a verificação automática para.
Novo no SpecScore? Comece por aqui ·O CLI ·Skills de IA
$ specscore lint checkout/ ✓ 24 requirements — structure, references, IDs valid ✓ no index drift · no broken links · no slug collisions 0 problems exit 0
Três camadas, não uma.
O SpecScore valida em camadas, da mais barata e mais certa para a mais cara. O lint é determinístico — rápido, gratuito, roda em todo commit. A revisão de IA é probabilística — mais profunda, custa tokens, pega coisas que o lint não alcança. Ojulgamento humano é a terceira camada: as costuras que as duas primeiras não fecham ainda precisam de uma pessoa — nenhuma ferramenta consegue fechá-las de forma confiável hoje. As duas camadas automáticas são complementares, não redundantes: o lint pega o que a IA não consegue justificar; a IA pega o que o lint não alcança.
O que cada validador verifica.
Linter do CLI
determinísticoMesmo resultado a cada execução, sem LLM, sem custo. Se passa aqui, é um fato — não uma opinião.
$ specscore lint apply-discount.md ✓ R1 has acceptance criteria ✓ R2 has acceptance criteria ✗ R3 no acceptance criteria ✗ link "Related Feature: discount-tiers" not found ✗ section "Open Questions" missing 3 problems exit 1
- Integridade referencial — links resolvem, IDs são únicos
- Convenções estruturais — seções obrigatórias, formato do frontmatter
- Higiene de status e desvio de índice
- Colisões de slug
- Validade de prefixos em campos de metadados (ex.:
Related Ideas:)
Revisão e nota por IA
não determinísticoLê em busca de significado, como faria um revisor humano — e, como um humano, não é perfeitamente repetível.
> /score apply-discount.md Grade: B — ready with edits AC-2 vague trigger — name the actor and event AC-3 no error path for an expired code prose reads clean; criteria need tightening
- ACs formulados como Given/When/Then verificáveis
- Consistência interna dentro de um artefato
- Conteúdo vago ou de preenchimento
- Legibilidade para um revisor humano
- Feedback acionável pelo autor e marcado por severidade
- Uma nota de prontidão de A a F
O que eles não pegam.
Nenhum validador é mágica. Aqui é onde cada um para — para que você saiba exatamente onde o seu próprio julgamento ainda tem que fazer o trabalho.
Linter do CLI
- Contradições implícitas ao longo de hierarquias profundas
- Desvio entre especificação e código (melhorando com a chegada do
specstudio:recap) - Correção semântica dos critérios de aceitação
- Se um nome realmente faz sentido
- Se os requisitos resolvem o problema declarado
Revisão e nota por IA
pega de forma inconsistente- Reprodutibilidade total entre execuções — vereditos podem variar dentro da tolerância
- Contradições entre artefatos em uma árvore grande sem verificações cruzadas explícitas
- Se os requisitos realmente resolvem o problema — sinaliza lacunas óbvias, mas perde as específicas do domínio
- Vieses herdados da LLM subjacente
- Correção semântica com certeza absoluta
- Qualquer coisa que a rubrica não pondere
- 1
O lint alcança até aqui
Estrutura, referências, higiene. Barato e certo — mas cego ao significado.
- 2
A IA alcança até aqui
Significado, clareza, consistência dentro de um artefato. Mais profunda — mas probabilística, e fraca ao longo de uma árvore grande.
- 3
Ainda fica por sua conta
Julgamento transversal sobre o sistema inteiro — um trabalho que nenhuma ferramenta consegue fazer de forma confiável hoje, então ainda exige um revisor humano.
O caso do qual nenhuma ferramenta vai te salvar
Imagine uma árvore de especificações real e profunda. A feature A exigeX. A feature B exige Y. A feature C exigeZ. Então a feature D silenciosamente exige algo que contradiz B — mas só quando A também está ativa. O lint vê quatro documentos válidos e bem conectados e passa. O revisor de IA, lendo os artefatos um de cada vez, não tem motivo para carregar os quatro e notar a interação entre os três.
Nenhuma das camadas pega isso de forma confiável — e não vamos fingir o contrário. É exatamente essa classe de contradição que justifica a existência da terceira camada. O trabalho do SpecScore é deixar a árvore navegável o bastante para que um humano revisando as costuras consiga encontrar o conflito — questões em aberto sobem pela hierarquia, requisitos relacionados estão a uma consulta de distância — e não afirmar que uma ferramenta já o encontrou.