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

Canonical: https://specscore.md/pt-br/articles/spec-management/

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

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](https://specscore.md/pt-br/spec-driven-development/) (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](https://specscore.md/pt-br/validators/) (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](https://specscore.md/pt-br/articles/feature-spec-template/) é um arquivo de funcionalidade do SpecScore com essa forma. [Easy Approach to Requirements Syntax](https://specscore.md/pt-br/articles/ears-requirements/) (EARS) é um padrão de frase para um requisito. No [SpecScore](https://specscore.md/), um requisito (REQ) é uma regra nomeada dentro de uma funcionalidade, e um [critério de aceitação](https://specscore.md/pt-br/articles/acceptance-criteria/) (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](https://specscore.md/pt-br/cli/) (CLI, command-line interface), `specscore spec lint`, documentado em [Lintar especificações na CI com um linter de especificações](https://specscore.md/pt-br/articles/lint-specs-in-ci/). O formato vive no repositório público [specscore/specscore](https://github.com/specscore/specscore) ([CC BY 4.0](https://github.com/specscore/specscore/blob/main/LICENSE)). A CLI vive em [specscore/specscore-cli](https://github.com/specscore/specscore-cli) ([Apache-2.0](https://github.com/specscore/specscore-cli/blob/main/LICENSE)).

## 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](https://github.com/specscore/specscore/blob/main/spec/README.md) lista os diretórios: features, plans, ideas, decisions e lessons. Uma funcionalidade é um diretório com um `README.md`. A [especificação de funcionalidade](https://specscore.md/feature-specification) é o contrato desse arquivo, e o [modelo de PRD](https://specscore.md/pt-br/articles/feature-spec-template/) é um exemplo preenchido que um linter aceitou.

`specscore spec lint` não adivinha qual árvore ler. [internal/cli/spec.go](https://github.com/specscore/specscore-cli/blob/v0.55.1/internal/cli/spec.go) na tag v0.55.1, e a mesma função na [tag v0.39.1](https://github.com/specscore/specscore-cli/blob/v0.39.1/internal/cli/spec.go), 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](https://github.com/specscore/specscore/blob/main/.github/workflows/dogfood.yml) 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](https://github.com/specscore/specscore-cli/blob/v0.39.1/docs/lint-rules.md) e em [v0.55.1](https://github.com/specscore/specscore-cli/blob/v0.55.1/docs/lint-rules.md). 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](https://github.com/specscore/specscore/blob/main/spec/features/feature/README.md) 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](https://github.com/specscore/specscore/blob/main/spec/features/plan/README.md) 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](https://specscore.md/plan-specification) 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](https://github.com/specscore/specscore/blob/main/.github/workflows/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](https://specscore.md/pt-br/validators/) 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](https://specscore.md/pt-br/articles/lint-specs-in-ci/).

## 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](https://github.com/specscore/specscore/blob/main/.github/workflows/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

```yaml
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](https://specscore.md/pt-br/articles/lint-specs-in-ci/).

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](https://specscore.md/pt-br/validators/). 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](https://specscore.md/pt-br/spec-driven-development/tools/) é a comparação mais longa.

A [referência de SDD agêntico do GitHub Spec Kit](https://github.github.io/spec-kit/reference/agentic-sdd.html) 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](https://github.com/Fission-AI/OpenSpec) guarda uma mudança como um diretório diretamente sob `openspec/changes/`. [openspec validate](https://openspec.dev/docs/cli) 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](https://github.com/specscore/specscore/blob/main/.github/workflows/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.

## Fontes

Arquivos da CLI e catálogos de lint lidos em 9 de novembro de 2026 nas tags v0.39.1 do specscore-cli (a versão que dogfood.yml instala) e v0.55.1. Os requisitos de funcionalidade e de plano são os arquivos ligados abaixo em specscore/specscore. As páginas de concorrentes foram obtidas no mesmo dia.

- [specscore/specscore — spec/README.md](https://github.com/specscore/specscore/blob/main/spec/README.md)
- [specscore/specscore — valores de status da funcionalidade](https://github.com/specscore/specscore/blob/main/spec/features/feature/README.md)
- [specscore/specscore — instantâneos do plano](https://github.com/specscore/specscore/blob/main/spec/features/plan/README.md)
- [specscore/specscore](https://github.com/specscore/specscore)
- [specscore/specscore — licença CC BY 4.0](https://github.com/specscore/specscore/blob/main/LICENSE)
- [specscore/specscore-cli](https://github.com/specscore/specscore-cli)
- [specscore-cli — licença Apache-2.0](https://github.com/specscore/specscore-cli/blob/main/LICENSE)
- [specscore-cli v0.39.1 — internal/cli/spec.go](https://github.com/specscore/specscore-cli/blob/v0.39.1/internal/cli/spec.go)
- [specscore-cli v0.55.1 — internal/cli/spec.go](https://github.com/specscore/specscore-cli/blob/v0.55.1/internal/cli/spec.go)
- [specscore-cli v0.39.1 — catálogo de regras de lint](https://github.com/specscore/specscore-cli/blob/v0.39.1/docs/lint-rules.md)
- [specscore-cli v0.55.1 — catálogo de regras de lint](https://github.com/specscore/specscore-cli/blob/v0.55.1/docs/lint-rules.md)
- [specscore/specscore — dogfood.yml (CLI v0.39.1)](https://github.com/specscore/specscore/blob/main/.github/workflows/dogfood.yml)
- [O que o SpecScore valida](https://specscore.md/pt-br/validators/)
- [Lintar especificações na CI com um linter de especificações](https://specscore.md/pt-br/articles/lint-specs-in-ci/)
- [Sintaxe de requisitos EARS explicada, com exemplos](https://specscore.md/pt-br/articles/ears-requirements/)
- [Como escrever critérios de aceitação que um agente de IA possa verificar](https://specscore.md/pt-br/articles/acceptance-criteria/)
- [Modelo de PRD em Markdown para programar com IA](https://specscore.md/pt-br/articles/feature-spec-template/)
- [Especificação de funcionalidade](https://specscore.md/feature-specification)
- [Especificação de plano](https://specscore.md/plan-specification)
- [GitHub Spec Kit — referência de SDD agêntico (/speckit.analyze)](https://github.github.io/spec-kit/reference/agentic-sdd.html)
- [Referência da CLI do OpenSpec — openspec validate e openspec status](https://openspec.dev/docs/cli)
- [Fission-AI/OpenSpec](https://github.com/Fission-AI/OpenSpec)
- [Ferramentas de desenvolvimento baseado em especificações](https://specscore.md/pt-br/spec-driven-development/tools/)

## Relacionados

- [Lintar especificações na CI com um linter de especificações](https://specscore.md/pt-br/articles/lint-specs-in-ci/)
- [Modelo de PRD em Markdown para programar com IA](https://specscore.md/pt-br/articles/feature-spec-template/)
- [Como escrever critérios de aceitação que um agente de IA possa verificar](https://specscore.md/pt-br/articles/acceptance-criteria/)
- [Sintaxe de requisitos EARS explicada, com exemplos](https://specscore.md/pt-br/articles/ears-requirements/)
- [Desenvolvimento baseado em especificações](https://specscore.md/pt-br/spec-driven-development/)
- [Ferramentas de desenvolvimento baseado em especificações](https://specscore.md/pt-br/spec-driven-development/tools/)
- [Especificação de funcionalidade](https://specscore.md/feature-specification)
- [Especificação de plano](https://specscore.md/plan-specification)
- [CLI](https://specscore.md/pt-br/cli/)
- [O que o SpecScore valida](https://specscore.md/pt-br/validators/)
