No desenvolvimento de software moderno, a colaboração com assistentes de código baseados em Inteligência Artificial (como Claude Code, Gemini CLI, Copilot, etc.) tornou-se comum. No entanto, o maior desafio mudou: o problema raramente é a escrita do código em si, mas sim garantir que você e a IA concordem com o que deve ser construído antes que a primeira linha de código seja gerada.

O OpenSpec foi criado exatamente para resolver essa lacuna. Ele atua como uma especificação de código aberto para gerenciar o comportamento do sistema e as propostas de mudança de forma estruturada.

1. Como o OpenSpec Funciona

O princípio fundamental do OpenSpec é estabelecer uma “fonte da verdade” (source of truth) compartilhada entre o desenvolvedor humano e o agente de IA.

Fluxos de Trabalho (Workflows)

O OpenSpec opera através de perfis de comandos. O perfil padrão e recomendado é o Core Profile, que utiliza comandos abreviados iniciados por barras (/).

Caminho Rápido Padrão (Core Profile):

/opsx:propose ──► /opsx:apply ──► /opsx:sync ──► /opsx:archive

Caminho Expandido (Customizado):

Para fluxos que exigem maior controle, seleção de workflows customizados ou iterações incrementais, o OpenSpec oferece uma abordagem expandida:

/opsx:new ──► /opsx:ff ou /opsx:continue ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive

Nota: O perfil global padrão é o core (que inclui os comandos propose, explore, apply, sync e archive). É possível habilitar o perfil expandido usando o comando de configuração openspec config profile seguido por openspec update.

2. A Estrutura de Diretórios do OpenSpec

Ao executar o comando de inicialização openspec init no seu projeto, a seguinte estrutura de arquivos é criada na raiz do repositório:

openspec/
├── specs/                  # Fonte da verdade (comportamento atual do sistema)
│   └── <domain>/
│       └── spec.md
├── changes/                # Atualizações propostas (uma pasta por alteração)
│   └── <change-name>/
│       ├── proposal.md
│       ├── design.md
│       ├── tasks.md
│       └── specs/          # Especificações Delta (o que está mudando)
│           └── <domain>/
│               └── spec.md
└── config.yaml             # Configuração opcional do projeto

Os Dois Diretórios Chave:

1. specs/ (A Fonte da Verdade): Este diretório descreve como o seu sistema se comporta atualmente. Ele é rigidamente organizado por domínios ou contextos delimitados (ex: specs/auth/, specs/payments/).

2. changes/ (Modificações Propostas): Cada nova funcionalidade, refatoração ou correção ganha uma pasta isolada contendo todos os artefatos relacionados àquela mudança. Quando o ciclo de desenvolvimento termina, essas especificações locais são integradas à fonte da verdade principal.

3. Compreendendo os Artefatos

Dentro de cada pasta de alteração em changes/, existem artefatos específicos que guiam o ciclo de desenvolvimento:

Os artefatos são construídos de forma iterativa e incremental, alimentando o próximo passo do fluxo:

proposal ──► specs ──► design ──► tasks ──► implement
    ▲          ▲         ▲         ▲            │
    └──────────┴─────────┴─────────┴────────────┘
               (Atualize conforme aprende)

Durante a implementação, se você ou a IA descobrirem restrições técnicas imprevistas, o fluxo permite retornar e refinar os artefatos anteriores, mantendo a documentação viva e precisa.

4. O Conceito de Especificações Delta (Delta Specs)

As Especificações Delta representam o coração da mecânica do OpenSpec. Em vez de reescrever uma especificação inteira do sistema a cada alteração, descreve-se apenas o diferencial (delta) usando três seções principais em Markdown: ## ADDED Requirements, ## MODIFIED Requirements e ## REMOVED Requirements.

Exemplo de Formatação de uma Delta Spec (spec.md):

# Delta for Auth

## ADDED Requirements
### Requirement: Two-Factor Authentication
O sistema DEVE exigir um segundo fator de autenticação durante o login.

#### Scenario: OTP required
- GIVEN um usuário com 2FA ativado
- WHEN o usuário submete credenciais válidas
- THEN um desafio de OTP deve ser apresentado

## MODIFIED Requirements
### Requirement: Session Timeout
O sistema DEVE expirar as sessões após 30 minutos de inatividade. (Anteriormente: 60 minutos)

#### Scenario: Idle timeout
- GIVEN uma sessão autenticada
- WHEN se passarem 30 minutos sem atividade
- THEN a sessão é invalidada

## REMOVED Requirements
### Requirement: Remember Me (Descontinuado em favor do 2FA)

O que acontece no Arquivamento (/opsx:archive)?

Quando o comando de arquivamento é disparado com sucesso:

• Os requisitos marcados como ADDED são anexados ao arquivo de especificação principal daquele domínio.

• Os requisitos marcados como MODIFIED substituem as versões antigas correspondentes na fonte da verdade.

• Os requisitos marcados como REMOVED são excluídos da especificação principal.

• A pasta temporária da mudança é movida para openspec/changes/archive/ para fins de histórico e auditoria.

5. Exemplo Prático: Implementando a Funcionalidade “Dark Mode”

Para entender o ciclo de ponta a ponta, veja o passo a passo para adicionar o modo escuro a uma aplicação:

Passo 1: Iniciar a Mudança

Você digita o comando para propor a nova feature:

/opsx:propose add-dark-mode

A IA analisa o repositório e cria automaticamente a estrutura em openspec/changes/add-dark-mode/:

• ✓ proposal.md — Intenção e escopo definidos.

• ✓ specs/ — Requisitos e cenários Gherkin/BDD mapeados.

• ✓ design.md — Abordagem técnica (ex: CSS Custom Properties + React Context).

• ✓ tasks.md — Lista de tarefas gerada.

Passo 2: Validar os Artefatos Gerados

O desenvolvedor revisa os arquivos criados pela IA. O arquivo tasks.md, por exemplo, conterá etapas claras:

# Tasks
## 1. Infraestrutura de Tema
- [ ] 1.1 Criar ThemeContext com estado light/dark
- [ ] 1.2 Adicionar propriedades personalizadas de CSS para cores
- [ ] 1.3 Implementar persistência no localStorage
## 2. Componentes de Interface
- [ ] 2.1 Criar o componente ThemeToggle

Passo 3: Implementar o Código

Com o planejamento aprovado, você executa:

/opsx:apply

A IA começa a processar a lista de tarefas sequencialmente, escrevendo o código correspondente e marcando as tarefas concluídas no arquivo tasks.md.

Passo 4: Arquivar a Mudança

Após validar que tudo funciona e os testes passaram, você encerra o ciclo:

/opsx:archive

O OpenSpec consolida o delta de UI em openspec/specs/ui/spec.md, limpa o diretório de alterações ativas e o move para o histórico de auditoria. A documentação do sistema está atualizada e sincronizada com o código produzido.

6. Comandos Úteis de Verificação (CLI)

Você pode gerenciar e auditar o estado das suas especificações diretamente do terminal usando a CLI do OpenSpec:

• Listar alterações ativas:

  openspec list

• Exibir detalhes de uma alteração específica:

  openspec show add-dark-mode
  

• Validar a formatação e consistência da especificação:

  openspec validate add-dark-mode
  

• Abrir o painel visual interativo:

  openspec view
  

Conclusão

O OpenSpec estabelece uma abordagem rigorosa, porém ágil, para o desenvolvimento auxiliado por IA. Ao forçar uma etapa de design e especificação via Delta Specs antes da escrita do código, eliminam-se alucinações e desvios de escopo, garantindo uma arquitetura limpa, documentada e alinhada com as necessidades do negócio.

Ao aplicar essas boas práticas, desenvolvedores conseguem não apenas aumentar produtividade, mas também melhorar a qualidade e consistência das soluções entregues.