Quickstart

Sua primeira alteração, da ideia ao arquivamento, em um projeto novo ou existente.

Antes de começar, você precisa do CLI na sua máquina (Instalação) e do OpenSpec inicializado no seu projeto (Configure seu projeto).

Começar do zero

Você pode começar sem uma stack escolhida ou uma arquitetura completa. Inicialize o OpenSpec na pasta do seu projeto e, em seguida, peça ao seu agente para explorar as opções com você. No seu chat de IA:

Ajude-me a explorar um rastreador de tarefas do zero. Ainda não escolhi uma stack. Compare as opções e me ajude a escolher o primeiro comportamento a ser implementado.

Decida o que a primeira alteração precisa e deixe as escolhas de arquitetura posteriores em aberto. Peça ao seu agente para propor essa única alteração e, em seguida, siga os passos abaixo. Você pode revisitar a arquitetura conforme o projeto cresce.

O ciclo em visão geral

Toda alteração passa pelos mesmos cinco passos: você reflete sobre a ideia com o seu agente, ele elabora um plano, você corrige o plano antes que qualquer código exista, o agente implementa a partir dele, e o arquivamento atualiza suas specs com o que foi entregue.

flowchart LR
    explore["1 · Explore<br/>think it through together"] --> propose["2 · Propose<br/>agent drafts the plan"]
    propose --> review["3 · Review<br/>you correct the plan"]
    review --> apply["4 · Apply<br/>agent builds, task by task"]
    apply --> archive["5 · Archive<br/>specs absorb the change"]
    archive -. "next change" .-> explore

Todos os prompts abaixo vão no seu chat de IA, o mesmo lugar onde você pede código. Os exemplos usam linguagem simples para funcionar em diferentes ferramentas. Você também pode invocar uma skill diretamente; a sintaxe varia conforme a ferramenta (ferramentas suportadas).

Passo 1: Explore

Reflita sobre a ideia com seu agente antes de pedir um plano. No seu chat de IA:

Ajude-me a explorar como a limitação de taxa deve funcionar neste app.

Explore é um modo de reflexão. O agente investiga sua base de código, faz as perguntas que importam, esboça opções e desafia premissas. Ele nunca escreve código. Ele não escreve mais nada, a menos que você peça para registrar o que decidiu ou diga sim quando ele oferecer. O resultado é uma ideia mais afiada.

Fique aqui o tempo que o problema precisar. Quando a forma parecer certa, passe a tarefa:

Proponha a alteração que acabamos de discutir.

Essa linha inicia o propose para você, carregando tudo o que foi definido. Pule o primeiro prompt do passo 2.

Passo 2: Propose

Propose transforma a ideia em um plano revisável. Vindo do explore, ele já está em execução. Começando do zero, quando a alteração está clara na sua cabeça, peça diretamente. No seu chat de IA:

Proponha uma alteração para adicionar limitação de taxa.

O agente faz as perguntas necessárias e, em seguida, escreve uma pasta de alteração:

openspec/changes/add-rate-limiting/
├── proposal.md    why, and what changes
├── specs/         what "done" means, as testable requirements
├── design.md      technical decisions (only when the change needs one)
└── tasks.md       the implementation checklist

Nenhum código ainda. Propose para no plano.

Passo 3: Revise e corrija o plano

Corrija o plano enquanto ainda é só texto e nada foi construído. Leia nesta ordem:

• proposal.md: este é o problema certo, no tamanho certo?
• specs/: a leitura de maior valor. Você aceitaria esses requisitos como prontos?
• tasks.md: as tarefas cobrem as specs, e nada mais?

Para corrigir algo, ambas as abordagens funcionam:

• Edite o arquivo você mesmo. Os artefatos são markdown simples, e os arquivos são o plano.
• Diga ao seu agente o que está errado ("a spec está faltando o caso não autenticado"). Ele revisa os artefatos.

Passo 4: Apply

Apply transforma o plano em código. Inicie uma nova sessão de chat, já que a implementação flui melhor em uma janela de contexto limpa. No seu chat de IA:

Aplique a alteração add-rate-limiting.

O agente lê a pasta de alteração e, em seguida, trabalha no tasks.md, marcando cada tarefa conforme é concluída.

• Interrompido ou sem contexto? Abra uma nova sessão e peça para aplicar novamente. Ele retoma na primeira tarefa desmarcada.
• O plano se revelou errado? Corrija os artefatos (de qualquer forma do passo 3) e continue aplicando.
• O progresso fica nas caixas de seleção do tasks.md. Não há estado oculto.

Passo 5: Archive

O arquivamento faz duas coisas: atualiza suas specs principais com os requisitos da alteração e move a pasta de alteração para a pasta de arquivo (em /openspec/changes/archive/*).

Quando todas as caixas do tasks.md estiverem marcadas, no seu chat de IA:

Archive a alteração add-rate-limiting.

Acompanhe o que o arquivamento faz:

## A alteração finalizada
> A implementação está pronta. A spec delta (o que esta alteração adiciona) ainda está dentro da pasta de alteração; specs/ ainda não sabe sobre limitação de taxa.
  openspec/
  ├── specs/                                   (no rate-limiting spec yet)
  └── changes/
      └── add-rate-limiting/
          ├── proposal.md
          ├── tasks.md                         every box checked
          └── specs/
              └── rate-limiting/
                  └── spec.md                  the delta: ADDED requirements

## Requisitos chegam a specs/
> Cada requisito no delta chega à spec principal: os adicionados são anexados, os modificados substituem sua versão anterior. Uma nova capacidade ganha um novo arquivo de spec.
  openspec/
  ├── specs/
+ │   └── rate-limiting/
+ │       └── spec.md                          gains "Requirement: Rate limiting"
  └── changes/
      └── add-rate-limiting/
          └── specs/
              └── rate-limiting/
                  └── spec.md                  the delta, source of the merge

## A pasta se move para archive/
> A pasta de alteração inteira, delta incluído, se move para o arquivo sob um prefixo de data. Nada é excluído.
  openspec/
  ├── specs/
  │   └── rate-limiting/
  │       └── spec.md
  └── changes/
-     └── add-rate-limiting/
+     └── archive/
+         └── 2026-08-08-add-rate-limiting/
+             ├── proposal.md
+             ├── tasks.md
+             └── specs/rate-limiting/spec.md

## Specs descrevem o sistema como construído
> changes/ está livre para a próxima alteração. specs/ é a fonte de verdade para o que o sistema faz; archive/ é o histórico de como ele chegou lá.
  openspec/
  ├── specs/
  │   └── rate-limiting/
  │       └── spec.md                          the spec as built
  └── changes/
      └── archive/
          └── 2026-08-08-add-rate-limiting/

Git é uma preocupação separada. Faça o commit da pasta de alteração junto com o código, e nada mais no seu fluxo de trabalho muda.

Manter ou remover alterações arquivadas

openspec/changes/archive/ mantém a proposta, o design, as tarefas e o delta de cada alteração finalizada. No fluxo de arquivamento acima, o delta já atualizou openspec/specs/.

• Mantenha a pasta de alteração inteira quando quiser um registro autocontido no checkout atual.
• Remova a pasta specs/ de uma alteração arquivada quando o Git for o seu histórico de specs. Faça o commit do arquivo primeiro e, em seguida, exclua openspec/changes/archive/<change>/specs/. A proposta, o design e as tarefas permanecem no checkout. openspec validate --archived ainda funciona porque verifica a conclusão das tarefas, não os deltas aplicados.
• Remova a pasta de alteração inteira apenas quando não precisar mais da proposta, do design ou do histórico de tarefas no checkout. As specs atuais não mudam, mas openspec validate --archived e as buscas no checkout não incluem mais essa alteração.

WARNING

Mantenha o commit de arquivo no histórico do seu repositório se quiser que o Git preserve os arquivos excluídos. Compactar os commits de arquivo e de limpeza remove esse snapshot intermediário.

O OpenSpec não remove automaticamente alterações arquivadas nem oferece uma configuração de retenção.

Indo além

• Specs delta: como escrever as alterações de comportamento em uma spec delta.
• Perfis: fluxos de trabalho opcionais além do conjunto principal (verificar antes de arquivar, planejamento incremental).

Guias avançados

Ainda não escrito; guias que planejamos adicionar:

• Prototipe primeiro: faça um spike do código antes de qualquer spec e, em seguida, preencha a proposta com o que o protótipo ensinou.
• Construindo iterativamente: uma sequência de pequenas alterações em vez de uma grande proposta.
• Revisando uma alteração implementada: o plano precisa mudar novamente após o apply, mas a alteração ainda não foi mesclada ou arquivada.