Conceitos
Este guia explica as principais ideias por trás do OpenSpec e como elas se encaixam. Para uso prático, consulte Primeiros Passos e Fluxos de Trabalho.
Filosofia
O OpenSpec é construído com base em quatro princípios:
fluid not rigid — no phase gates, work on what makes sense
iterative not waterfall — learn as you build, refine as you go
easy not complex — lightweight setup, minimal ceremony
brownfield-first — works with existing codebases, not just greenfieldPor que esses princípios importam
Fluido, não rígido. Sistemas de especificação tradicionais prendem você a fases: primeiro planeja, depois implementa, depois termina. O OpenSpec é mais flexível — você pode criar artefatos em qualquer ordem que faça sentido para o seu trabalho.
Iterativo, não cascata. Requisitos mudam. O entendimento se aprofunda. O que parecia uma boa abordagem no início pode não se sustentar depois que você vê a base de código. O OpenSpec abraça essa realidade.
Simples, não complexo. Alguns frameworks de especificação exigem configuração extensa, formatos rígidos ou processos pesados. O OpenSpec não atrapalha. Inicialize em segundos, comece a trabalhar imediatamente, personalize apenas se precisar.
Brownfield-first. A maior parte do trabalho de software não é construir do zero — é modificar sistemas existentes. A abordagem baseada em deltas do OpenSpec facilita a especificação de mudanças no comportamento existente, não apenas a descrição de novos sistemas.
Visão Geral
O OpenSpec organiza seu trabalho em duas áreas principais:
┌────────────────────────────────────────────────────────────────────┐
│ openspec/ │
│ │
│ ┌─────────────────────┐ ┌───────────────────────────────┐ │
│ │ specs/ │ │ changes/ │ │
│ │ │ │ │ │
│ │ Fonte da verdade │◄─────│ Modificações propostas │ │
│ │ Como seu sistema │ merge│ Cada change = uma pasta │ │
│ │ funciona atualmente│ │ Contém artefatos + deltas │ │
│ │ │ │ │ │
│ └─────────────────────┘ └───────────────────────────────┘ │
│ │
└────────────────────────────────────────────────────────────────────┘Specs são a fonte da verdade — elas descrevem como seu sistema se comporta atualmente.
Changes são modificações propostas — elas ficam em pastas separadas até que você esteja pronto para mesclá-las.
Essa separação é fundamental. Você pode trabalhar em múltiplos changes em paralelo sem conflitos. Você pode revisar um change antes que ele afete as specs principais. E quando você arquiva um change, seus deltas são mesclados de forma limpa na fonte da verdade.
Specs
Specs descrevem o comportamento do seu sistema usando requisitos e cenários estruturados.
Estrutura
openspec/specs/
├── auth/
│ └── spec.md # Comportamento de autenticação
├── payments/
│ └── spec.md # Processamento de pagamentos
├── notifications/
│ └── spec.md # Sistema de notificações
└── ui/
└── spec.md # Comportamento e temas da UIOrganize specs por domínio — agrupamentos lógicos que fazem sentido para o seu sistema. Padrões comuns:
- Por área de funcionalidade:
auth/,payments/,search/ - Por componente:
api/,frontend/,workers/ - Por contexto delimitado:
ordering/,fulfillment/,inventory/
Formato de Spec
Uma spec contém requisitos, e cada requisito tem cenários:
# Auth Specification
## Purpose
Authentication and session management for the application.
## Requirements
### Requirement: User Authentication
The system SHALL issue a JWT token upon successful login.
#### Scenario: Valid credentials
- GIVEN a user with valid credentials
- WHEN the user submits login form
- THEN a JWT token is returned
- AND the user is redirected to dashboard
#### Scenario: Invalid credentials
- GIVEN invalid credentials
- WHEN the user submits login form
- THEN an error message is displayed
- AND no token is issued
### Requirement: Session Expiration
The system MUST expire sessions after 30 minutes of inactivity.
#### Scenario: Idle timeout
- GIVEN an authenticated session
- WHEN 30 minutes pass without activity
- THEN the session is invalidated
- AND the user must re-authenticateElementos-chave:
| Elemento | Propósito |
|---|---|
## Purpose | Descrição de alto nível do domínio desta spec |
### Requirement: | Um comportamento específico que o sistema deve ter |
#### Scenario: | Um exemplo concreto do requisito em ação |
| SHALL/MUST/SHOULD | Palavras-chave da RFC 2119 indicando a força do requisito |
Por Que Estruturar Specs Dessa Forma
Requisitos são o "o quê" — eles declaram o que o sistema deve fazer sem especificar a implementação.
Cenários são o "quando" — eles fornecem exemplos concretos que podem ser verificados. Bons cenários:
- São testáveis (você poderia escrever um teste automatizado para eles)
- Cobrem tanto o caminho feliz quanto casos extremos
- Usam o formato estruturado Given/When/Then ou similar
Palavras-chave da RFC 2119 (SHALL, MUST, SHOULD, MAY) comunicam a intenção:
- MUST/SHALL — requisito absoluto
- SHOULD — recomendado, mas existem exceções
- MAY — opcional
O Que Uma Spec É (e Não É)
Uma spec é um contrato de comportamento, não um plano de implementação.
Conteúdo bom para specs:
- Comportamento observável no qual usuários ou sistemas downstream dependem
- Entradas, saídas e condições de erro
- Restrições externas (segurança, privacidade, confiabilidade, compatibilidade)
- Cenários que podem ser testados ou explicitamente validados
Evite em specs:
- Nomes internos de classes/funções
- Escolhas de bibliotecas ou frameworks
- Detalhes de implementação passo a passo
- Planos de execução detalhados (esses pertencem a
design.mdoutasks.md)
Teste rápido:
- Se a implementação pode mudar sem alterar o comportamento visível externamente, provavelmente não pertence à spec.
Mantenha Leve: Rigor Progressivo
O OpenSpec visa evitar burocracia. Use o nível mais leve que ainda torne a mudança verificável.
Spec lite (padrão):
- Requisitos curtos e focados em comportamento
- Escopo e não-objetivos claros
- Algumas verificações de aceitação concretas
Spec completa (para maior risco):
- Mudanças entre equipes ou entre repositórios
- Mudanças de API/contrato, migrações, preocupações de segurança/privacidade
- Mudanças em que a ambiguidade provavelmente causará retrabalho caro
A maioria das mudanças deve permanecer no modo Lite.
Colaboração Humano + Agente
Em muitas equipes, humanos exploram e agentes rascunham artefatos. O ciclo pretendido é:
- O humano fornece intenção, contexto e restrições.
- O agente converte isso em requisitos e cenários focados em comportamento.
- O agente mantém detalhes de implementação em
design.mdetasks.md, não emspec.md. - A validação confirma estrutura e clareza antes da implementação.
Isso mantém as specs legíveis para humanos e consistentes para agentes.
Changes
Um change é uma modificação proposta ao seu sistema, empacotada como uma pasta com tudo o que é necessário para entender e implementá-la.
Estrutura de Change
openspec/changes/add-dark-mode/
├── proposal.md # Por quê e o quê
├── design.md # Como (abordagem técnica)
├── tasks.md # Checklist de implementação
├── .openspec.yaml # Metadados do change (opcional): schema, created, skip_specs, retire_capabilities
└── specs/ # Delta specs
└── ui/
└── spec.md # O que está mudando em ui/spec.mdCada change é autocontido. Ele tem:
- Artefatos — documentos que capturam intenção, design e tarefas
- Delta specs — especificações do que está sendo adicionado, modificado ou removido
- Metadados — configuração opcional para este change específico
Por Que Changes São Pastas
Empacotar um change como pasta tem vários benefícios:
Tudo junto. Proposta, design, tarefas e specs ficam em um só lugar. Sem procurar em diferentes localizações.
Trabalho paralelo. Múltiplos changes podem existir simultaneamente sem conflitar. Trabalhe em
add-dark-modeenquantofix-auth-bugtambém está em andamento.Histórico limpo. Quando arquivados, changes se movem para
changes/archive/com todo o contexto preservado. Você pode olhar para trás e entender não apenas o que mudou, mas por quê.Fácil de revisar. Uma pasta de change é fácil de revisar — abra-a, leia a proposta, verifique o design, veja os deltas das specs.
Artefatos
Artefatos são os documentos dentro de um change que guiam o trabalho.
O Fluxo de Artefatos
proposal ──────► specs ──────► design ──────► tasks ──────► implement
│ │ │ │
por quê o quê como passos
+ escopo mudanças abordagem a seguirArtefatos se constroem uns sobre os outros. Cada artefato fornece contexto para o próximo.
Tipos de Artefato
Proposta (proposal.md)
A proposta captura intenção, escopo e abordagem em alto nível.
# Proposal: Add Dark Mode
## Intent
Users have requested a dark mode option to reduce eye strain
during nighttime usage and match system preferences.
## Scope
In scope:
- Theme toggle in settings
- System preference detection
- Persist preference in localStorage
Out of scope:
- Custom color themes (future work)
- Per-page theme overrides
## Approach
Use CSS custom properties for theming with a React context
for state management. Detect system preference on first load,
allow manual override.Quando atualizar a proposta:
- Mudanças de escopo (estreitando ou expandindo)
- A intenção se esclarece (melhor entendimento do problema)
- A abordagem muda fundamentalmente
Specs (delta specs em specs/)
Delta specs descrevem o que está mudando em relação às specs atuais. Veja Delta Specs abaixo.
Design (design.md)
O design captura a abordagem técnica e as decisões de arquitetura.
# Design: Add Dark Mode
## Technical Approach
Theme state managed via React Context to avoid prop drilling.
CSS custom properties enable runtime switching without class toggling.
## Architecture Decisions
### Decision: Context over Redux
Using React Context for theme state because:
- Simple binary state (light/dark)
- No complex state transitions
- Avoids adding Redux dependency
### Decision: CSS Custom Properties
Using CSS variables instead of CSS-in-JS because:
- Works with existing stylesheet
- No runtime overhead
- Browser-native solution
## Data Flow
```
ThemeProvider (context)
│
▼
ThemeToggle ◄──► localStorage
│
▼
CSS Variables (applied to :root)
```
## File Changes
- `src/contexts/ThemeContext.tsx` (new)
- `src/components/ThemeToggle.tsx` (new)
- `src/styles/globals.css` (modified)Quando atualizar o design:
- A implementação revela que a abordagem não funcionará
- Uma solução melhor é descoberta
- Dependências ou restrições mudam
Tarefas (tasks.md)
Tarefas são o checklist de implementação — passos concretos com caixas de seleção.
# 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
- [ ] 1.4 Add system preference detection
## 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.3 Test contrast ratios for accessibilityBoas práticas de tarefas:
- Agrupe tarefas relacionadas sob títulos
- Use numeração hierárquica (1.1, 1.2, etc.)
- Mantenha tarefas pequenas o suficiente para serem concluídas em uma sessão
- Marque as tarefas como concluídas conforme você as completa
Delta Specs
Delta specs são o conceito-chave que torna o OpenSpec funcional para desenvolvimento brownfield. Elas descrevem o que está mudando em vez de reafirmar a spec inteira.
O Formato
# Delta for Auth
## ADDED Requirements
### Requirement: Two-Factor Authentication
The system MUST support TOTP-based two-factor authentication.
#### Scenario: 2FA enrollment
- GIVEN a user without 2FA enabled
- WHEN the user enables 2FA in settings
- THEN a QR code is displayed for authenticator app setup
- AND the user must verify with a code before activation
#### Scenario: 2FA login
- GIVEN a user with 2FA enabled
- WHEN the user submits valid credentials
- THEN an OTP challenge is presented
- AND login completes only after valid OTP
## MODIFIED Requirements
### Requirement: Session Expiration
The system MUST expire sessions after 15 minutes of inactivity.
(Previously: 30 minutes)
#### Scenario: Idle timeout
- GIVEN an authenticated session
- WHEN 15 minutes pass without activity
- THEN the session is invalidated
## REMOVED Requirements
### Requirement: Remember Me
(Deprecated in favor of 2FA. Users should re-authenticate each session.)Seções de Delta
| Seção | Significado | O Que Acontece ao Arquivar |
|---|---|---|
## ADDED Requirements | Novo comportamento | Adicionado à spec principal |
## MODIFIED Requirements | Comportamento alterado | Substitui o requisito existente |
## REMOVED Requirements | Comportamento descontinuado | Removido da spec principal; remover o último requisito aposenta a capacidade e exclui seu arquivo de spec, quando a mudança declara retire_capabilities: true |
## Purpose | Para que serve uma capacidade totalmente nova | Semeia o Purpose da spec principal sendo criada; ignorado quando a spec já existe |
Por Que Deltas em Vez de Specs Completas
Clareza. Um delta mostra exatamente o que está mudando. Lendo uma spec completa, você teria que fazer o diff mentalmente em relação à versão atual.
Evitação de conflitos. Dois changes podem tocar o mesmo arquivo de spec sem conflitar, desde que modifiquem requisitos diferentes.
Eficiência de revisão. Os revisores veem a mudança, não o contexto inalterado. Foco no que importa.
Adequação brownfield. A maioria do trabalho modifica comportamento existente. Deltas tornam modificações de primeira classe, não uma preocupação posterior.
Esquemas
Esquemas definem os tipos de artefatos e suas dependências para um fluxo de trabalho.
Como os Esquemas Funcionam
# openspec/schemas/spec-driven/schema.yaml
name: spec-driven
artifacts:
- id: proposal
generates: proposal.md
requires: [] # No dependencies, can create first
- id: specs
generates: specs/**/*.md
requires: [proposal] # Needs proposal before creating
- id: design
generates: design.md
requires: [proposal] # Can create in parallel with specs
- id: tasks
generates: tasks.md
requires: [specs, design] # Needs both specs and design firstArtefatos formam um grafo de dependências:
proposal
(root node)
│
┌─────────────┴─────────────┐
│ │
▼ ▼
specs design
(requires: (requires:
proposal) proposal)
│ │
└─────────────┬─────────────┘
│
▼
tasks
(requires:
specs, design)Dependências são facilitadores, não portões. Elas mostram o que é possível criar, não o que você deve criar em seguida. Você pode pular o design se não precisar dele. Você pode criar specs antes ou depois do design — ambos dependem apenas da proposta.
Esquemas Integrados
spec-driven (padrão)
O fluxo de trabalho padrão para desenvolvimento orientado a especificações (spec-driven):
proposal → specs → design → tasks → implementMelhor para: A maioria dos trabalhos de funcionalidades onde você quer concordar com as especificações antes da implementação.
Esquemas Personalizados
Crie esquemas personalizados para o fluxo de trabalho da sua equipe:
# Create from scratch
openspec schema init research-first
# Or fork an existing one
openspec schema fork spec-driven research-firstExemplo de esquema personalizado:
# openspec/schemas/research-first/schema.yaml
name: research-first
artifacts:
- id: research
generates: research.md
requires: [] # Do research first
- id: proposal
generates: proposal.md
requires: [research] # Proposal informed by research
- id: tasks
generates: tasks.md
requires: [proposal] # Skip specs/design, go straight to tasksConsulte Personalização para obter detalhes completos sobre como criar e usar esquemas personalizados.
Arquivamento
Arquivar completa uma alteração mesclando seus delta specs nas specs principais e preservando a alteração para o histórico.
O Que Acontece Quando Você Arquiva
Before archive:
openspec/
├── specs/
│ └── auth/
│ └── spec.md ◄────────────────┐
└── changes/ │
└── add-2fa/ │
├── proposal.md │
├── design.md │ merge
├── tasks.md │
└── specs/ │
└── auth/ │
└── spec.md ─────────┘
After archive:
openspec/
├── specs/
│ └── auth/
│ └── spec.md # Now includes 2FA requirements
└── changes/
└── archive/
└── 2025-01-24-add-2fa/ # Preserved for history
├── proposal.md
├── design.md
├── tasks.md
└── specs/
└── auth/
└── spec.mdO Processo de Arquivamento
Mesclar deltas. Cada seção do delta spec (ADDED/MODIFIED/REMOVED) é aplicada à spec principal correspondente.
Mover para o arquivo. A pasta da alteração é movida para
changes/archive/com um prefixo de data para ordenação cronológica.Preservar contexto. Todos os artefatos permanecem intactos no arquivo. Você pode sempre olhar para trás para entender por que uma alteração foi feita.
Por Que o Arquivamento é Importante
Estado limpo. Alterações ativas (changes/) mostram apenas o trabalho em andamento. O trabalho concluído sai do caminho.
Trilha de auditoria. O arquivo preserva o contexto completo de cada alteração — não apenas o que mudou, mas a proposta explicando o porquê, o design explicando como, e as tarefas mostrando o trabalho realizado.
Evolução das specs. As specs crescem organicamente conforme as alterações são arquivadas. Cada arquivamento mescla seus deltas, construindo uma especificação abrangente ao longo do tempo.
Como Tudo se Conecta
┌──────────────────────────────────────────────────────────────────────────────┐
│ OPENSPEC FLOW │
│ │
│ ┌────────────────┐ │
│ │ 1. START │ /opsx:propose (core) or /opsx:new (expanded) │
│ │ CHANGE │ │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ 2. CREATE │ /opsx:ff or /opsx:continue (expanded workflow) │
│ │ ARTIFACTS │ Creates proposal → specs → design → tasks │
│ │ │ (based on schema dependencies) │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ 3. IMPLEMENT │ /opsx:apply │
│ │ TASKS │ Work through tasks, checking them off │
│ │ │◄──── Update artifacts as you learn │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ 4. VERIFY │ /opsx:verify (optional) │
│ │ WORK │ Check implementation matches specs │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ ┌──────────────────────────────────────────────┐ │
│ │ 5. ARCHIVE │────►│ Delta specs merge into main specs │ │
│ │ CHANGE │ │ Change folder moves to archive/ │ │
│ └────────────────┘ │ Specs are now the updated source of truth │ │
│ └──────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────────────┘O ciclo virtuoso:
- As specs descrevem o comportamento atual
- Alterações propõem modificações (como deltas)
- A implementação torna as alterações reais
- O arquivamento mescla deltas nas specs
- As specs agora descrevem o novo comportamento
- A próxima alteração se baseia nas specs atualizadas
Glossário
| Termo | Definição |
|---|---|
| Artefato | Um documento dentro de uma alteração (proposta, design, tarefas ou delta specs) |
| Arquivamento | O processo de concluir uma alteração e mesclar seus deltas nas specs principais |
| Alteração | Uma modificação proposta para o sistema, empacotada como uma pasta com artefatos |
| Delta spec | Uma spec que descreve mudanças (ADDED/MODIFIED/REMOVED) em relação às specs atuais |
| Domínio | Um agrupamento lógico para specs (ex.: auth/, payments/) |
| Requisito | Um comportamento específico que o sistema deve ter |
| Cenário | Um exemplo concreto de um requisito, normalmente no formato Dado/Quando/Então |
| Esquema | Uma definição dos tipos de artefatos e suas dependências |
| Spec | Uma especificação que descreve o comportamento do sistema, contendo requisitos e cenários |
| Fonte de verdade | O diretório openspec/specs/, contendo o comportamento atual acordado |
Próximos Passos
- Começando - Primeiros passos práticos
- Fluxos de trabalho - Padrões comuns e quando usar cada um
- Comandos - Referência completa de comandos
- Personalização - Crie esquemas personalizados e configure seu projeto