OpenSpec

Primeiros Passos ​

Este guia explica como o OpenSpec funciona após você ter instalado e inicializado-o. Para instruções de instalação, consulte o README principal ou o guia de instalação. Novo em todo o conjunto de documentação? A página inicial da documentação mapeia tudo.

Onde digito esses comandos? Em dois lugares, e confundir os dois é o erro mais comum no início.

  • Comandos openspec ... (como openspec init) são executados no seu terminal.
  • Comandos /opsx:... (como /opsx:propose) são executados no chat do seu assistente de IA, a mesma caixa onde você pediria para escrever código.

Não existe um "modo interativo" separado para iniciar. Você simplesmente digita o comando com barra no chat e seu assistente assume a partir daí. Explicação completa: Como os Comandos Funcionam.

Seus Primeiros Cinco Minutos ​

O ciclo completo, com cada etapa rotulada por onde ela acontece:

text
TERMINAL   $ npm install -g @fission-ai/openspec@latest
TERMINAL   $ cd your-project && openspec init
AI CHAT      /opsx:explore                    (opcional: pense antes)
AI CHAT      /opsx:propose add-dark-mode      (a IA elabora o plano; você revisa)
AI CHAT      /opsx:apply                      (a IA implementa)
AI CHAT      /opsx:archive                    (specs atualizadas, mudança arquivada)

Duas etapas no terminal para configurar, e depois você vive no chat. O restante deste guia detalha o que cada etapa faz e o que você verá.

Não quer fazer a parte do terminal sozinho? Cole o prompt de configuração no seu assistente e ele cuida das duas linhas, depois relata o que criou.

Ainda não sabe o que construir? Comece com /opsx:explore. É um parceiro de reflexão sem compromisso que lê sua base de código, pondera opções e transforma uma ideia vaga em um plano concreto, tudo antes de qualquer artefato ou código existir. Quando a visão fica clara, ele passa a vez para /opsx:propose. Este é o melhor hábito para trabalhar com uma IA que, caso contrário, construiria confiantemente a coisa errada. Veja o guia de Explore.

Como Funciona ​

O OpenSpec ajuda você e seu assistente de código de IA a concordarem sobre o que construir antes de qualquer código ser escrito.

Caminho rápido padrão (perfil core):

text
/opsx:explore ──► /opsx:propose ──► /opsx:apply ──► /opsx:sync ──► /opsx:archive
   (opcional)

Comece com /opsx:explore quando estiver descobrindo o que fazer, ou vá direto para /opsx:propose quando já sabe. Explore está no perfil padrão, então sempre estará disponível quando você quiser.

Caminho expandido (seleção de fluxo de trabalho personalizado):

text
/opsx:new ──► /opsx:ff or /opsx:continue ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive

O perfil global padrão é core, que inclui propose, explore, apply, update, sync e archive. Você pode habilitar os comandos de fluxo de trabalho expandido com openspec config profile e depois openspec update.

O Que o OpenSpec Cria ​

Após executar openspec init, seu projeto terá esta estrutura:

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

Dois diretórios-chave:

  • specs/ - A fonte da verdade. Essas specs descrevem como seu sistema se comporta atualmente. Organizadas por domínio (ex.: specs/auth/, specs/payments/).

  • changes/ - Modificações propostas. Cada mudança recebe sua própria pasta com todos os artefatos relacionados. Quando uma mudança é concluída, suas specs são mescladas no diretório principal specs/.

Entendendo os Artefatos ​

Cada pasta de mudança contém artefatos que orientam o trabalho:

ArtefatoPropósito
proposal.mdO "porquê" e o "o quê" - captura intenção, escopo e abordagem
specs/Specs delta mostrando requisitos ADICIONADOS/MODIFICADOS/REMOVIDOS
design.mdO "como" - abordagem técnica e decisões de arquitetura
tasks.mdChecklist de implementação com caixas de seleção

Os artefatos se constroem uns sobre os outros:

proposal ──► specs ──► design ──► tasks ──► implement
   ▲           ▲          ▲                    │
   └───────────┴──────────┴────────────────────┘
            atualize conforme aprende

Você sempre pode voltar e refinar artefatos anteriores conforme aprende mais durante a implementação.

Como Funcionam as Specs Delta ​

As specs delta são o conceito-chave no OpenSpec. Elas mostram o que está mudando em relação às suas specs atuais.

O Formato ​

As specs delta usam seções para indicar o tipo de mudança:

markdown
# Delta for Auth

## ADDED Requirements

### Requirement: Two-Factor Authentication
The system MUST require a second factor during login.

#### Scenario: OTP required
- GIVEN a user with 2FA enabled
- WHEN the user submits valid credentials
- THEN an OTP challenge is presented

## MODIFIED Requirements

### Requirement: Session Timeout
The system SHALL expire sessions after 30 minutes of inactivity.
(Previously: 60 minutes)

#### Scenario: Idle timeout
- GIVEN an authenticated session
- WHEN 30 minutes pass without activity
- THEN the session is invalidated

## REMOVED Requirements

### Requirement: Remember Me
(Deprecated in favor of 2FA)

O Que Acontece ao Arquivar ​

Quando você arquiva uma mudança:

  1. Requisitos ADICIONADOS são anexados à spec principal
  2. Requisitos MODIFICADOS substituem a versão existente
  3. Requisitos REMOVIDOS são excluídos da spec principal

A pasta da mudança é movida para openspec/changes/archive/ para histórico de auditoria.

Exemplo: Sua Primeira Mudança ​

Vamos percorrer a adição de modo escuro a uma aplicação.

1. Iniciar a Mudança (Padrão) ​

text
You: /opsx:propose add-dark-mode

AI:  Created openspec/changes/add-dark-mode/
     ✓ proposal.md — why we're doing this, what's changing
     ✓ specs/       — requirements and scenarios
     ✓ design.md    — technical approach
     ✓ tasks.md     — implementation checklist
     Ready for implementation!

Se você habilitou o perfil de fluxo de trabalho expandido, também pode fazer isso em duas etapas: /opsx:new e depois /opsx:ff (ou /opsx:continue incrementalmente).

2. O Que É Criado ​

proposal.md - Captura a intenção:

markdown
# Proposal: Add Dark Mode

## Intent
Users have requested a dark mode option to reduce eye strain
during nighttime usage.

## Scope
- Add theme toggle in settings
- Support system preference detection
- Persist preference in localStorage

## Approach
Use CSS custom properties for theming with a React context
for state management.

specs/ui/spec.md - Delta mostrando novos requisitos:

markdown
# Delta for UI

## ADDED Requirements

### Requirement: Theme Selection
The system SHALL allow users to choose between light and dark themes.

#### Scenario: Manual toggle
- GIVEN a user on any page
- WHEN the user clicks the theme toggle
- THEN the theme switches immediately
- AND the preference persists across sessions

#### Scenario: System preference
- GIVEN a user with no saved preference
- WHEN the application loads
- THEN the system's preferred color scheme is used

tasks.md - Checklist de implementação:

markdown
# Tasks

## 1. Theme Infrastructure
- [ ] 1.1 Create ThemeContext with light/dark state
- [ ] 1.2 Add CSS custom properties for colors
- [ ] 1.3 Implement localStorage persistence

## 2. UI Components
- [ ] 2.1 Create ThemeToggle component
- [ ] 2.2 Add toggle to settings page
- [ ] 2.3 Update Header to include quick toggle

## 3. Styling
- [ ] 3.1 Define dark theme color palette
- [ ] 3.2 Update components to use CSS variables

3. Implementar ​

You: /opsx:apply

AI:  Working through tasks...
     ✓ 1.1 Created ThemeContext with light/dark state
     ✓ 1.2 Added CSS custom properties to globals.css
     ✓ 1.3 Implemented localStorage persistence
     ✓ 2.1 Created ThemeToggle component
     ...
     All tasks complete!

Durante a implementação, se você descobrir que o design precisa de ajuste, basta atualizar o artefato e continuar.

4. Arquivar ​

You: /opsx:archive

AI:  Archiving add-dark-mode...
     ✓ Merged specs into openspec/specs/ui/spec.md
     ✓ Moved to openspec/changes/archive/2025-01-24-add-dark-mode/
     Done! Ready for the next feature.

Suas specs delta agora fazem parte das specs principais, documentando como seu sistema funciona.

Verificando e Revisando ​

Use a CLI para verificar suas mudanças:

bash
# List active changes
openspec list

# View change details
openspec show add-dark-mode

# Validate spec formatting
openspec validate add-dark-mode

# Interactive dashboard
openspec view

Próximos Passos ​