Fluxo de Trabalho com Especificações Primeiro
Defina requisitos antes de escrever código.
OpenSpecDesenvolvimento Orientado por Especificações para Assistentes de IA
Uma especificação leve para construir e gerenciar projetos de assistentes de IA.
Bem-vindo. Este é o lugar central de tudo sobre o OpenSpec.
O OpenSpec ajuda você e seu assistente de codificação de IA a concordarem sobre o que construir antes de qualquer código ser escrito. Você descreve a mudança, a IA redige uma especificação curta e uma lista de tarefas, vocês dois olham para o mesmo plano, e então o trabalho acontece. Não há mais descoberta no meio do caminho de que a IA construiu a coisa errada.
Se você não ler mais nada, leia estas duas páginas:
/opsx:propose (dica: no seu chat com a IA, não no terminal). Isso confunde quase todo mundo uma vez.Essa segunda é mais importante do que parece. O OpenSpec tem duas partes: uma ferramenta de linha de comando que você executa no terminal e comandos de barra que você dá ao seu assistente de IA. Saber qual é qual evita o momento mais comum de confusão.
O melhor hábito a construir primeiro: quando você não tiver certeza do que construir, comece com
/opsx:explore. É um parceiro de pensamento sem riscos que lê seu código, pondera opções e transforma uma ideia vaga em um plano concreto antes que qualquer artefato ou código exista. O guia Explorar Primeiro apresenta o caso.
Sou novo. Comece com Começar, depois folheie Conceitos Básicos em Resumo. Quando algo parecer misterioso, o FAQ e o Glossário estão por perto.
Tenho um problema, mas não um plano. Este é o caso comum, e tem uma resposta dedicada: Explorar Primeiro. Use /opsx:explore para pensar com a IA antes de se comprometer com qualquer coisa.
Tenho uma base de código grande existente. Você não documenta tudo. Usando OpenSpec em um Projeto Existente mostra como começar em código legado real sem tentar fazer demais.
Quero apenas fazer funcionar. Instale, execute openspec init, depois leia Como os Comandos Funcionam para que seu primeiro comando de barra vá para o lugar certo. Ou entregue a configuração ao seu assistente com o prompt de instalação assistida por IA.
Aprendo por exemplos. A página Exemplos e Receitas percorre mudanças reais do início ao fim: um pequeno recurso, uma correção de bug, uma refatoração, uma exploração.
A IA acabou de redigir um plano — e agora? Leia. Revisando uma Mudança mostra a passagem de dois minutos que detecta um desvio enquanto ainda é barato, e Escrevendo Boas Especificações cobre do que é feito um plano digno de aprovação.
Trabalho em equipe. OpenSpec em Equipe mostra como uma mudança se mapeia para um branch e um pull request, e como os colegas revisam um plano antes do código.
Venho do fluxo de trabalho antigo. O Guia de Migração explica o que mudou e por que, e garante que seu trabalho existente está seguro.
Quero adaptá-lo ao processo da minha equipe. Customização cobre configuração de projeto, esquemas personalizados e contexto compartilhado.
Algo está quebrado. Solução de Problemas reúne as falhas que as pessoas realmente enfrentam, com correções.
| Documento | O que ele oferece |
|---|---|
| Começar | Instalar, inicializar e executar sua primeira mudança do início ao fim |
| Explorar Primeiro | Use /opsx:explore para pensar em uma ideia antes de se comprometer |
| Como os Comandos Funcionam | Onde os comandos de barra são executados, o que "modo interativo" significa, terminal vs. chat |
| Conceitos Básicos em Resumo | Todo o modelo mental em uma página: especificações, mudanças, deltas, arquivo |
| Instalação | npm, pnpm, yarn, bun, Nix, um prompt que entrega a configuração ao seu assistente de IA, e como verificar se funcionou |
| Documento | O que ele oferece |
|---|---|
| Fluxos de Trabalho | Padrões comuns e quando usar cada comando |
| Exemplos e Receitas | Tutoriais completos de mudanças reais, copiáveis |
| Escrevendo Boas Especificações | Como são um requisito e um cenário fortes, e como dimensionar corretamente uma mudança |
| Revisando uma Mudança | A passagem de dois minutos em um plano rascunhado antes de qualquer código ser escrito |
| OpenSpec em Equipe | Como mudanças se encaixam em branches, pull requests e revisão |
| Usando OpenSpec em um Projeto Existente | Adotando OpenSpec em uma base de código legada grande |
| Editando e Iterando em uma Mudança | Atualizar artefatos, voltar atrás, reconciliar edições manuais |
| Comandos | Referência para cada comando de barra /opsx:* |
| CLI | Referência para cada comando de terminal openspec |
| Documento | O que ele oferece |
|---|---|
| Conceitos | A explicação longa de especificações, mudanças, artefatos, esquemas e arquivo |
| Fluxo de Trabalho OPSX | Por que o fluxo de trabalho é fluido em vez de fases fixas, além de um mergulho profundo na arquitetura |
| Glossário | Cada termo definido em um só lugar |
| Documento | O que ele oferece |
|---|---|
| Customização | Configuração de projeto, esquemas personalizados, contexto compartilhado |
| Multilíngue | Gerar artefatos em idiomas além do inglês |
| Ferramentas Suportadas | As mais de 30 ferramentas de IA com as quais o OpenSpec se integra, e onde os arquivos são salvos |
| Vitrine da Comunidade | Projetos e recursos construídos com e para o OpenSpec |
| Documento | O que ele oferece |
|---|---|
| FAQ | Respostas rápidas para as perguntas mais frequentes |
| Solução de Problemas | Correções concretas para falhas concretas |
| Guia de Migração | Migrando do fluxo de trabalho legado para o OPSX |
| Documento | O que ele oferece |
|---|---|
| Stores: Guia do Usuário | Planeje em seu próprio repositório quando seu trabalho abrange repositórios ou equipes |
| Contrato de Agente | As superfícies CLI legíveis por máquina que os agentes dirigem |
1. Install npm install -g @fission-ai/openspec@latest
2. Initialize cd your-project && openspec init
3. Explore (in your AI chat) /opsx:explore ← optional, but a great habit
4. Propose (in your AI chat) /opsx:propose add-dark-mode
5. Build (in your AI chat) /opsx:apply
6. Archive (in your AI chat) /opsx:archiveOs passos 1 e 2 acontecem no seu terminal. O restante acontece no chat do seu assistente de IA. Essa divisão é a única coisa que vale a pena memorizar, e Como os Comandos Funcionam explica exatamente por quê. O passo 3 é opcional, mas começar com /opsx:explore quando você está inseguro é o hábito que mais vale a pena formar.
openspec feedback "sua mensagem" envia feedback diretamente do seu terminal (abre uma issue no GitHub).Encontrou algo nestes documentos que está errado, desatualizado ou confuso? Isso é um bug. Abra uma issue ou um PR. Melhorias na documentação são algumas das contribuições mais valiosas que você pode fazer.