OpenSpec - Apresentando os recursos básicos

  Neste artigo vou apresentar os recursos básicos e a filosofia de funcionamento do OpenSpec para aplicar a abordagem do Spec-Driven Development.

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:

Artefato Propósito
proposal.md O "porquê" e o "quê". Captura a intenção original, o escopo e a abordagem macro.
specs/(Delta Specs) Especificações incrementais mostrando explicitamente os requisitos que serão adicionados, modificados ou removidos.
design.md O "como". Define a abordagem técnica, decisões arquiteturais e padrões de design adotados.
tasks.md O checklist de implementação detalhado com caixas de seleção (- [ ]).

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:

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/:

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:

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.

E estamos conversados...  

"Porque noutro tempo éreis trevas, mas agora sois luz no Senhor; andai como filhos da luz"
Efésios 5:8

Referências:

José Carlos Macoratti