Artigos

Gestão de especificações: guardar, versionar e revisar especificações como código

A gestão de especificações é o modo como uma equipe guarda uma especificação de software, registra cada mudança, revisa essa mudança e mantém a especificação atual. A gestão da especificação é o mesmo trabalho: uma especificação é o documento que diz o que o software deve fazer, e gerenciá-la é o que mantém o documento encontrável e confiável. Gerenciar especificações como código significa que esses documentos são arquivos no sistema de controle de versões, de modo que uma mudança numa especificação é um commit que um revisor pode comparar num diff. O versionamento de especificações é o histórico desses commits, junto com o status escrito em cada documento. Manter as especificações sincronizadas com o código significa que uma mudança proposta que quebra a estrutura da especificação falha na mesma verificação automática pela qual passa a mudança de código. O desenvolvimento baseado em especificações (SDD, spec-driven development) é a prática de escrever a especificação antes do código e tratá-la como a fonte da verdade. A integração contínua (CI, continuous integration) é uma verificação automática em cada mudança proposta. Um documento de requisitos de produto (PRD, product requirements document) é a prosa que enuncia o problema e o escopo; o modelo de PRD em Markdown é um arquivo de funcionalidade do SpecScore com essa forma. Easy Approach to Requirements Syntax (EARS) é um padrão de frase para um requisito. No SpecScore, um requisito (REQ) é uma regra nomeada dentro de uma funcionalidade, e um critério de aceitação (AC, acceptance criterion) é uma condição abstrata opcional que aponta para uma ou mais dessas regras. A verificação é um comando da interface de linha de comando (CLI, command-line interface), specscore spec lint, documentado em Lintar especificações na CI com um linter de especificações. O formato vive no repositório público specscore/specscore (CC BY 4.0). A CLI vive em specscore/specscore-cli (Apache-2.0).

Última atualização: 9 de novembro de 2026

Onde a especificação fica armazenada

A gestão de especificações começa por um lugar onde os arquivos possam viver. Neste repositório a especificação é Markdown sob spec/. O README de spec lista os diretórios: features, plans, ideas, decisions e lessons. Uma funcionalidade é um diretório com um README.md. A especificação de funcionalidade é o contrato desse arquivo, e o modelo de PRD é um exemplo preenchido que um linter aceitou.

specscore spec lint não adivinha qual árvore ler. internal/cli/spec.go na tag v0.55.1, e a mesma função na tag v0.39.1, sobe a partir do diretório de trabalho até encontrar specscore.yaml. O comentário dessa função diz que o comando exige o arquivo, retorna o código de saída 3 quando ele falta e manda executar specscore init. O fluxo dogfood deste repositório instala a CLI v0.39.1 e depois executa specscore spec lint, então o checkout que ele linta tem esse arquivo de configuração.

Um índice fica ao lado dos arquivos de funcionalidade. A regra feature-index-row-sync é um erro no catálogo de lint em v0.39.1 e em v0.55.1. A linha do catálogo diz que ela exige que cada linha do índice de funcionalidades coincida com o seu arquivo de funcionalidade. Isso é o índice alinhado com o documento para o qual aponta. Não é uma comparação da redação do requisito com um arquivo-fonte.

Versionamento de especificações

O versionamento de especificações, para arquivos commitados no git, é o histórico de commits desses arquivos. O SpecScore não acrescenta um segundo número de versão a uma funcionalidade. A revisão que um revisor olha é o commit no branch. A linha de status no documento diz em que ponto do ciclo de vida essa funcionalidade está, e isso é um fato diferente do hash do git.

A especificação de funcionalidade no repositório tem ela mesma **Status:** Stable. Ela exige uma linha **Status:** imediatamente depois do título, e o valor tem de ser um de Draft, In Review, Approved, Implementing, Stable, Amending, Rejected ou Deprecated. A regra status-mirror, nos dois catálogos nomeados acima, exige que o status: do frontmatter de um artefato que tem status coincida com essa linha do corpo, e proíbe status: num tipo que não tem status. Fazer as duas cópias coincidirem não é o mesmo que rejeitar uma palavra fora dos oito valores. Nenhuma das duas linhas do catálogo descreve uma regra que rejeite um status de funcionalidade fora desse conjunto, então esta página não afirma que ela exista.

Os planos usam outro conjunto. A regra P-006, em ambos os catálogos, exige que o **Status:** do corpo de um plano de um único arquivo seja um de Draft, In Review, Approved, Executing, Blocked, Implemented, Failed, Rejected, Withdrawn, Superseded ou Deprecated. A regra idea-status-values rejeita um status de ideia fora do conjunto que essa regra permite. O catálogo é a lista. Esta página não repete as palavras da ideia.

A especificação de plano também descreve uma tabela opcional ## Snapshots com as colunas Date, Git Hash, Action e Comment. Diz que cada instantâneo referencia um hash de commit do git do estado do plano naquele momento. Os dois catálogos de lint verificados para esta página não nomeiam uma regra que resolva esse hash, então esta página não afirma que o linter verifica se o commit existe. O hash é um ponteiro que uma pessoa pode seguir no git. A especificação de plano publicada é a página de formato desse documento.

Revisar uma especificação

A revisão de uma especificação em Markdown é o pull request que a muda. dogfood.yml executa em pull_request e num push para main. O job faz checkout do repositório, instala a CLI com SPECSCORE_VERSION em v0.39.1 e executa specscore spec lint sem flags extras. O GitHub Actions marca o passo como falho quando esse processo sai com código diferente de zero. As permissões do fluxo são contents: read.

O status da funcionalidade In Review significa que a funcionalidade é apresentada para revisão. Escrever essa palavra é uma edição do arquivo Markdown. O pull request é onde uma pessoa lê o diff. status-mirror verifica que o frontmatter e o corpo nomeiam o mesmo status. Não registra que um revisor tenha concordado com a prosa. A página de validadores separa essa verificação estrutural de uma leitura que uma pessoa ainda tem de fazer. O relato regra por regra do que specscore spec lint informa está em Lintar especificações na CI com um linter de especificações.

Manter as especificações sincronizadas com o código

Manter as especificações sincronizadas com o código, neste site, significa que a especificação está no repositório com o projeto, e que a CI faz o pull request falhar quando a árvore da especificação viola o formato. Um pull request pode mudar um arquivo de funcionalidade e o código no mesmo diff. A regra feature-index-row-sync mantém uma linha do índice alinhada com o arquivo de funcionalidade que ela nomeia. Não lê um arquivo-fonte para decidir se o código implementa o requisito.

O trecho abaixo são os passos de instalação e de lint de dogfood.yml. O arquivo do fluxo também define permissões, um grupo de concorrência e um comentário sobre por que o pin não é latest. Essas linhas ficam de fora aqui. Os comandos são os que esse arquivo executa.

Passos de instalação e lint de dogfood.yml
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

O comentário nesse arquivo diz que um pin flutuante latest muda o portão sob o repositório: um pull request e a branch main à qual ele aponta podem ver regras diferentes. O pin é v0.39.1. O job não passa --fix. Uma execução limpa e uma execução que falha, incluindo a linha file:line [severity] rule: message, são mostradas em Lintar especificações na CI com um linter de especificações.

Uma frase da especificação que já não descreve o código não é um desses achados. specscore spec lint valida a estrutura: arquivos e seções obrigatórios, linhas de índice, a forma dos cabeçalhos e as referências que as regras nomeiam. Não avalia se a implementação corresponde ao requisito. Esse limite é o sentido da página de validadores. Manter a prosa verdadeira continua sendo uma revisão do diff.

Como outras ferramentas de desenvolvimento baseado em especificações verificam uma especificação

Os parágrafos abaixo usam as páginas obtidas em 9 de novembro de 2026. Descrevem as verificações próprias dessas ferramentas. Não dizem quantos produtos existem e não ordenam um mercado. Ferramentas de desenvolvimento baseado em especificações é a comparação mais longa.

A referência de SDD agêntico do GitHub Spec Kit descreve /speckit.analyze como uma verificação somente leitura sobre spec.md, plan.md e tasks.md. Informa conflitos, lacunas e ambiguidades, nunca edita arquivos, e se executa no agente antes da implementação. A lista de comandos dessa mesma página não descreve um job de CI que execute specscore spec lint contra uma árvore SpecScore.

OpenSpec guarda uma mudança como um diretório diretamente sob openspec/changes/. openspec validate verifica mudanças e especificações em busca de problemas de estrutura. A referência diz que o código de saída 0 significa que cada item validado passou, e que o código de saída 1 significa que um item falhou, que a solicitação de relatório é inválida, que a configuração não pode ser lida ou que a execução falhou. Essa verificação é a forma do OpenSpec, incluindo os blocos de requisito e de cenário, não um cabeçalho ### AC: do SpecScore. Num comando diferente, openspec status, a mesma referência diz que um lote que não consegue carregar uma mudança ainda sai com 1, “so CI doesn’t accept an incomplete report as successful.” Essa frase é sobre openspec status, não sobre openspec validate.

Perguntas frequentes

O que é gestão de especificações?

Gestão de especificações é guardar uma especificação de software, registrar cada mudança, revisar essa mudança e manter a especificação atual. No SpecScore os arquivos são Markdown no repositório git, e specscore spec lint é a verificação estrutural que um job de CI pode fazer falhar.

O que é gestão da especificação?

Gestão da especificação é a mesma prática. A especificação é o documento que diz o que o software deve fazer. Gerenciá-la significa que o documento tem um lugar conhecido, um histórico, uma revisão e uma verificação de que a sua estrutura ainda corresponde ao formato.

Como funciona gerenciar especificações como código?

A especificação é uma árvore de arquivos Markdown sob spec/, mais specscore.yaml na raiz do repositório. Uma mudança é um commit. Um pull request revisa o diff. dogfood.yml executa specscore spec lint nesse pull request.

Como funciona o versionamento de especificações?

O histórico do git é o histórico de versões dos arquivos. Uma funcionalidade também traz **Status:** com um dos oito valores que a especificação de funcionalidade exige. Um plano pode registrar uma linha ## Snapshots cujo Git Hash é um commit do estado do plano. Os catálogos do linter citados aqui não descrevem uma regra que resolva esse hash.

Como manter as especificações sincronizadas com o código?

Coloque a especificação no repositório e faça o pull request falhar quando specscore spec lint informar uma violação estrutural, inclusive uma linha de índice que não coincide com o seu arquivo de funcionalidade. O comando não decide se o código implementa o requisito. Uma frase que se afastou do código ainda precisa que uma pessoa leia o diff.

Mantenha a especificação no repositório.

Encontrou um erro na tradução ou tem uma ideia para melhorar esta página?