OpenSpec – Apresentando os recursos básicos

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:

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

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

<strong># Delta for Auth</strong>

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

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

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

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

<strong>## REMOVED Requirements</strong>
<strong>### Requirement: Remember Me (Descontinuado em favor do 2FA)</strong>

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:

<strong>/opsx:propose add-dark-mode</strong>

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:

<strong>/opsx:apply</strong>

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:

<strong>/opsx:archive</strong>

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:

  <strong>openspec list</strong>

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

  <strong>openspec show add-dark-mode</strong>
  

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

  <strong>openspec validate add-dark-mode</strong>
  

• Abrir o painel visual interativo:

  <strong>openspec view</strong>
  

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.