Fluxo de Trabalho Spec-First
Defina os requisitos antes de escrever o código.
OpenSpecDesenvolvimento Orientado por Especificação para Assistentes de IA
Uma especificação leve para construir e gerenciar projetos de assistentes de IA.
Bem-vindo. Este é o lar de tudo sobre OpenSpec.
OpenSpec ajuda você e seu assistente de codificação de IA a concordar no que construir antes que qualquer código seja escrito. Você descreve a mudança, a IA rascunha uma especificação curta e uma lista de tarefas, ambos olham para o mesmo plano, e então o trabalho acontece. Chega de descobrir no meio do caminho 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 de IA, não no terminal). Isso confunde quase todo mundo uma vez.A segunda é mais importante do que parece. OpenSpec tem duas metades: uma ferramenta de linha de comando que você executa no terminal e comandos slash que você dá ao seu assistente de IA. Saber qual é qual economiza o momento de confusão mais comum.
O melhor hábito para construir primeiro: quando você não tem certeza do que construir, comece com
/opsx:explore. É um parceiro de pensamento sem riscos que lê seu código, avalia opções e transforma uma ideia vaga em um plano concreto antes que qualquer artefato ou código exista. O guia Explore First apresenta o caso.
Sou totalmente novo. Comece com Getting Started, depois folheie Core Concepts at a Glance. Quando algo parecer misterioso, FAQ e Glossary estão por perto.
Tenho um problema, mas não tenho um plano. Este é o caso comum e tem uma resposta dedicada: Explore First. Use /opsx:explore para pensar sobre isso com a IA antes de se comprometer com qualquer coisa.
Tenho uma base de código existente e grande. Você não documenta tudo. Using OpenSpec in an Existing Project mostra como começar em um código real, "brownfield", sem tentar resolver o oceano inteiro.
Eu só quero fazer funcionar. Install, execute openspec init, depois leia How Commands Work para que seu primeiro comando slash caia no lugar certo.
Aprendo por exemplo. A página Examples & Recipes percorre mudanças reais do início ao fim: um pequeno recurso, uma correção de bug, um refactor, uma exploração.
Estou vindo do fluxo de trabalho antigo. O Migration Guide explica o que mudou e por quê, e promete que seu trabalho existente está seguro.
Quero adaptar ao processo da minha equipe. Customization cobre a configuração do projeto, esquemas personalizados e contexto compartilhado.
Algo está quebrado. Troubleshooting coleta as falhas reais que as pessoas encontram, com correções.
| Doc | O que ele oferece |
|---|---|
| Getting Started | Instalação, inicialização e execução da sua primeira mudança de ponta a ponta |
| Explore First | Use /opsx:explore para pensar sobre uma ideia antes de se comprometer |
| How Commands Work | Onde os comandos slash são executados, o que significa "modo interativo", terminal vs chat |
| Core Concepts at a Glance | Todo o modelo mental em uma página: especificações, mudanças, deltas, arquivo |
| Installation | npm, pnpm, yarn, bun, Nix e como verificar se funcionou |
| Doc | O que ele oferece |
|---|---|
| Workflows | Padrões comuns e quando recorrer a cada comando |
| Examples & Recipes | Guias completos de mudanças reais, prontos para copiar e colar |
| Using OpenSpec in an Existing Project | Adotando o OpenSpec em uma base de código "brownfield" grande |
| Editing & Iterating on a Change | Atualizar artefatos, voltar atrás, reconciliar edições manuais |
| Commands | Referência para cada comando slash /opsx:* |
| CLI | Referência para cada comando de terminal openspec |
| Doc | O que ele oferece |
|---|---|
| Concepts | A explicação detalhada de especificações, mudanças, artefatos, esquemas e arquivo |
| OPSX Workflow | Por que o fluxo de trabalho é fluido em vez de travado por fase, mais um mergulho na arquitetura |
| Glossary | Todo termo definido em um só lugar |
| Doc | O que ele oferece |
|---|---|
| Customization | Configuração do projeto, esquemas personalizados, contexto compartilhado |
| Multi-Language | Gerar artefatos em idiomas diferentes de inglês |
| Supported Tools | As 25+ ferramentas de IA com as quais o OpenSpec se integra e onde os arquivos são salvos |
| Doc | O que ele oferece |
|---|---|
| FAQ | Respostas rápidas às perguntas mais feitas |
| Troubleshooting | Correções concretas para falhas concretas |
| Migration Guide | Migrando do fluxo de trabalho legado para OPSX |
| Doc | O que ele oferece |
|---|---|
| Stores: User Guide | Planejar em seu próprio repo quando seu trabalho abrange vários repositórios ou equipes |
| Agent Contract | As superfícies CLI legíveis por máquina que os agentes impulsionam |
1. Install npm install -g @fission-ai/openspec@latest
2. Initialize cd your-project && openspec init
3. Explore (no seu chat de IA) /opsx:explore ← opcional, mas um ótimo hábito
4. Propose (no seu chat de IA) /opsx:propose add-dark-mode
5. Build (no seu chat de IA) /opsx:apply
6. Archive (no seu chat de IA) /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 How Commands Work explica exatamente por quê. O Passo 3 é opcional, mas começar com /opsx:explore quando você não tem certeza é o hábito mais valioso para formar.
openspec feedback "sua mensagem" envia feedback diretamente do seu terminal (ele abre um problema no GitHub).Encontrou algo nessas documentações que está errado, desatualizado ou confuso? Isso é um bug. Abra um problema ou um PR. Melhorias na documentação são algumas das contribuições mais valiosas que você pode fazer.