Spec Kit 0.8.13 · Maio 2026
Spec-Driven
Development
O guia completo de todos os comandos, fluxos e boas práticas para usar o Spec Kit do começo ao fim de um projeto real.
specify-cli · instalação via uv tool install
EXPLORAR
↓
Visão Geral
O Spec Kit funciona em
duas camadas distintas
Terminal
Camada de Setup
Instalação, inicialização do projeto, gestão de integrações com agentes de IA, extensões, presets e workflows. Tudo via linha de comando.
$ specify init meu-app --integration opencode
Agente IA
Camada de Desenvolvimento
O fluxo real de desenvolvimento Spec-Driven: da constituição até a implementação. Comandos usados no chat do agente após o specify init.
/speckit.specify → /speckit.plan → /speckit.implement
Comandos do Agente
O fluxo completo,
passo a passo
/speckit.constitution
O que você passa
- Regras de arquitetura (Clean Arch, SOLID, etc.)
- Padrões de qualidade e testes
- Regras de UX e segurança
- Padrões de código e nomenclatura
- Restrições de performance
O que é gerado
.specify/memory/constitution.md
As leis permanentes do projeto. Todo comando posterior vai respeitar essas regras.
exemplo.txt
/speckit.constitution # Leis do projeto — fullstack Nenhuma regra de negócio em controller, componente visual ou infraestrutura.
Backend expõe contratos claros, versionados e documentados.
Frontend consome APIs por services/hooks isolados.
Todo comportamento importante deve ter cobertura de testes.
Nenhuma feature cria conceito duplicado sem verificar existentes.
UX prioriza estados vazios, loading, erro e feedback claro.
Segurança: validar no backend, proteger rotas, tratar permissões.
Performance: evitar N+1, payloads gigantes e renders desnecessários.
GPT-5.5 thinking: high
Uso usual
- No início de qualquer projeto novo, antes de qualquer outro comando
- Ao retomar um projeto antigo sem constituição definida
Também use quando...
- A stack ou arquitetura mudar de forma significativa
- O time adotar um novo padrão de testes ou segurança
- Um novo membro entrar e precisar entender as regras do projeto
/speckit.specify
O que você passa
- O QUÊ o sistema deve fazer
- POR QUÊ — motivação de negócio
- Regras de negócio sem ambiguidade
- Critérios de sucesso mensuráveis
- Edge cases e restrições importantes
⚠ Sem React, Spring, PostgreSQL aqui. A stack vem no /plan.
O que é gerado
specs/001-nome-feature/spec.md branch criada pasta da feature
GPT-5.5 thinking: high
Uso usual
- Após a constituição, para descrever o primeiro módulo ou feature
- Início de cada novo ciclo de desenvolvimento
Também use quando...
- Surgir uma demanda fora do escopo atual — atualize a spec antes de implementar
- A regra de negócio mudar e precisar refletir na documentação
- Quiser dividir um módulo grande em specs menores e independentes
/speckit.clarify
O que você passa
- Pontos de regra de negócio não óbvios
- Casos de borda a detalhar
- Questões de segurança e permissão
- Telas/fluxos mínimos para MVP
- Comportamento em valores similares
O que é gerado
Atualização e refinamento do spec.md — força o agente a não assumir coisas implícitas.
GPT-5.5 thinking: high
Uso usual
- Após o /specify, antes de partir para o /plan
- Quando a spec tem pontos vagos que o agente poderia interpretar errado
Também use quando...
- O domínio for complexo e envolver regras financeiras, legais ou de segurança
- Existirem múltiplos comportamentos possíveis para um mesmo caso de uso
- Quiser garantir que edge cases estão cobertos antes do planejamento técnico
/speckit.checklist
O que você passa
- Pode ser vazio (usa critérios padrão)
- Foco em domínio: "valide requisitos de segurança"
- Validação de estados de erro/loading/vazio
- Checagem de critérios mensuráveis
O que é gerado
Checklist de qualidade dos requisitos. Aponta buracos antes de gastar tempo no planejamento técnico.
Uso usual
- Após o /clarify (ou direto após o /specify em fluxos enxutos)
- Como gate de qualidade antes de investir tempo no planejamento técnico
Também use quando...
- A spec foi escrita por outra pessoa e você quer validar a completude
- O escopo cresceu e você quer checar se os critérios de aceite ainda fazem sentido
- Quiser focar a validação em um domínio específico, como segurança ou UX
/speckit.plan
O que você passa
- Stack completa (framework, linguagem, banco)
- Arquitetura (monorepo, microservices, etc.)
- Autenticação e autorização
- Libs e dependências principais
- Padrões técnicos obrigatórios
- Estratégia de testes
O que é gerado
plan.md research.md data-model.md contracts/ quickstart.md
GPT-5.5 thinking: medium-high
Uso usual
- Após spec validada pelo /checklist, para definir como construir tecnicamente
- Uma vez por feature ou módulo, antes de gerar as tasks
Também use quando...
- A stack mudar e o plano anterior precisar ser refeito
- Uma nova integração ou serviço externo for adicionado ao escopo
- O modelo de dados precisar de uma revisão arquitetural profunda
/speckit.tasks
O que você passa
Normalmente vazio. O agente lê plan.md, data-model.md, contracts/ e research.md automaticamente.
O que é gerado
tasks.md
Tarefas implementáveis, com dependências, marcação de paralelismo e ordem de execução.
GPT-5.5 thinking: medium
Uso usual
- Logo após o /plan estar revisado e aprovado
- Para transformar a arquitetura em passos concretos e implementáveis
Também use quando...
- O plano foi atualizado e as tasks antigas ficaram desatualizadas
- Quiser identificar quais tarefas podem ser paralelizadas entre devs
- Precisar exportar o trabalho para GitHub Issues com o /taskstoissues
/speckit.analyze
O que você passa
Normalmente vazio. O agente cruza spec, plan e tasks automaticamente.
O que detecta
- Spec fala de X mas tasks não criaram endpoint
- Plan usa PostgreSQL mas tasks não criaram migration
- Constitution exige teste mas tasks não incluem testes
- Modelo sem campos suficientes para a spec
Uso usual
- Após gerar as tasks, como último gate antes do /implement
- Para garantir que spec, plan e tasks estão consistentes entre si
Também use quando...
- A spec ou o plan mudaram depois que as tasks já foram geradas
- Suspeitar que algum requisito ficou sem cobertura nas tasks
- Quiser auditoria antes de um PR grande ou entrega de sprint
/speckit.implement
O que você passa
Normalmente vazio. O agente executa as tarefas do tasks.md em sequência.
⚠ O agente pode rodar npm, dotnet e outros comandos locais. Certifique-se de ter as ferramentas instaladas.
O que é gerado
Código real. Estrutura de arquivos, entidades, migrations, endpoints, telas, testes — tudo conforme spec + plan + tasks.
GPT-5.5 thinking: medium
Uso usual
- Após o /analyze confirmar consistência — esse é o momento de codar
- Para executar as tasks em sequência, gerando código real
Também use quando...
- Quiser implementar apenas um subconjunto de tasks (informe quais)
- Retomar uma implementação pausada a partir de uma task específica
- Precisar re-implementar uma task que gerou bug ou ficou incompleta
/speckit.taskstoissues
O que você passa
- Repositório de destino
- Labels a aplicar
- Milestone e prioridade
O que é gerado
Issues no GitHub criadas a partir do tasks.md, prontas para triagem e atribuição.
Uso usual
- Após o /tasks, quando o projeto é gerenciado via GitHub Issues
- Para sincronizar o backlog do Spec Kit com o board do time
Também use quando...
- O time não usa o Spec Kit diretamente mas acompanha pelo GitHub
- Quiser atribuir milestones, labels ou prioridades antes de implementar
- Precisar recriar as issues após uma revisão grande das tasks
Camada de Terminal
Comandos specify
| Comando | Quando usar |
|---|---|
| uv tool install specify-cli --from git+https://github.com/github/[email protected] | Instalar globalmente a versão atual (0.8.13) |
| uvx --from git+https://github.com/github/spec-kit.git specify init <projeto> | Rodar sem instalar globalmente |
| specify init <projeto> --integration opencode | Criar projeto novo já configurado com OpenCode |
| specify init --here --integration opencode | Inicializar na pasta atual (projeto existente) |
| specify init --here --force --integration opencode | Inicializar em pasta existente, sobrescrevendo |
| specify init <projeto> --script sh | Forçar scripts Bash/Zsh |
| specify init <projeto> --script ps | Forçar scripts PowerShell |
| specify check | Verificar se todas as ferramentas necessárias estão instaladas |
| specify version | Ver versão atual do CLI |
| specify version --features | Ver recursos suportados nessa versão |
| specify self check | Verificar se existe versão mais nova disponível |
| Comando | Quando usar |
|---|---|
| specify integration list | Ver todos os agentes de IA suportados |
| specify integration install <key> | Adicionar integração (ex: opencode, claude, copilot, cursor-agent) |
| specify integration uninstall [key] | Remover integração instalada |
| specify integration switch <key> | Trocar a integração padrão ativa |
| specify integration use <key> | Usar integração já instalada sem mudar o padrão |
| specify integration upgrade [key] | Atualizar arquivos da integração para versão mais nova |
Agentes suportados:
copilot · claude · codex · gemini · roo · opencode · qwen · cursor-agent · windsurf | Comando | Quando usar |
|---|---|
| specify extension search [query] | Procurar extensões disponíveis no catálogo |
| specify extension add <name> | Instalar uma extensão (Jira, GitHub Issues, Security Review, etc.) |
| specify extension remove <name> | Remover extensão instalada |
| specify extension list | Listar extensões instaladas no projeto |
| specify extension info <name> | Ver detalhes de uma extensão específica |
| specify extension update [name] | Atualizar uma ou todas as extensões |
| specify extension enable <name> | Habilitar extensão desativada |
| specify extension disable <name> | Desabilitar sem remover |
| specify extension set-priority <name> <priority> | Resolver conflito de prioridade entre extensões |
| specify extension catalog list | Listar catálogos de extensões disponíveis |
| specify extension catalog add <url> | Adicionar catálogo externo de extensões |
| specify extension catalog remove <name> | Remover catálogo |
💡 Extensão = adicionar capacidade nova ao fluxo (Jira, GitHub Issues, wireframe, QA, arquitetura, security review, etc.)
| Comando | Quando usar |
|---|---|
| specify preset search [query] | Procurar presets disponíveis |
| specify preset add [preset_id] | Instalar um preset |
| specify preset remove <preset_id> | Remover preset instalado |
| specify preset list | Listar presets instalados |
| specify preset info <preset_id> | Ver detalhes de um preset |
| specify preset resolve <name> | Ver qual template será usado para determinado comando |
| specify preset enable <preset_id> | Habilitar preset desativado |
| specify preset disable <preset_id> | Desabilitar sem remover |
| specify preset set-priority <preset_id> <priority> | Definir prioridade entre presets conflitantes |
| specify preset catalog list | Listar catálogos de presets |
| specify preset catalog add <url> | Adicionar catálogo de presets externo |
| specify preset catalog remove <name> | Remover catálogo |
💡 Preset = mudar o formato e comportamento dos templates existentes (ex: preset de compliance, preset da empresa, preset para arquitetura específica)
| Comando | Quando usar |
|---|---|
| specify workflow run <source> | Rodar fluxo automatizado (ex: Full SDD Cycle) |
| specify workflow resume <run_id> | Retomar fluxo que pausou ou falhou |
| specify workflow status [run_id] | Ver status atual de um workflow |
| specify workflow list | Listar workflows instalados |
| specify workflow add <source> | Instalar novo workflow |
| specify workflow remove <workflow_id> | Remover workflow |
| specify workflow search [query] | Procurar workflows disponíveis no catálogo |
| specify workflow info <workflow_id> | Ver detalhes de um workflow |
| specify workflow catalog list | Listar catálogos de workflows |
| specify workflow catalog add <url> | Adicionar catálogo externo |
| specify workflow catalog remove <index> | Remover catálogo |
💡 Workflow = automatizar sequência de comandos com gates e checkpoints. O "Full SDD Cycle" encadeia specify → plan → tasks → implement com pontos de revisão.
Regra de Ouro
O fluxo ideal para
projetos reais
constitution
Leis permanentes
→
specify
Problema e regras de negócio
→
clarify
Remove ambiguidades
→
checklist
Valida requisitos
→
plan
Stack e arquitetura
→
tasks
Passos implementáveis
→
analyze
Detecta contradições
→
implement
Código real
🔄 Nova demanda fora do escopo? Nunca implementa direto.
Sempre que surgir algo novo, rode primeiro:
/speckit.specify Atualize a spec atual para incluir a nova demanda abaixo, sem criar
conceitos duplicados e mantendo compatibilidade com a arquitetura existente:
[nova demanda] # Depois repita normalmente: /speckit.plan → /speckit.tasks → /speckit.analyze → /speckit.implement
⚠ Antipadrões do vibe coding
- Pedir "faz tudo de uma vez" em um prompt gigante sem spec, plan ou tasks
- Implementar diretamente sem passar pelo fluxo (entidade duplicada garantida)
- Colocar stack técnica no
/speckit.specify— ela pertence ao/speckit.plan - Pular o
/speckit.analyzee ir direto pro implement — contradições viram bugs - Não usar a
constitution— sem leis globais o agente inventa padrões a cada feature