Primeira Especificação

Crie uma especificação, veja o SpecForge decompô-la em épicos e tickets, e prepare-se para a implementação.

Uma especificação é a unidade de trabalho de mais alto nível no SpecForge. Você descreve o que quer construir em linguagem natural. O SpecForge analisa, decompõe em épicos (agrupamentos lógicos) e tickets (tarefas atômicas de implementação), e constrói um grafo de dependência para que o trabalho execute na ordem correta.

Você escreve a intenção. O SpecForge produz o plano.

Experimente em 60 Segundos

Ainda não tem um projeto? Use este exemplo para ver o SpecForge em ação imediatamente.

Passo 1 — Faça o bootstrap da spec e planeje

Faça o bootstrap da especificação você mesmo com a CLI — este é o passo humano:

specforge init

Depois entregue a intenção ao seu agente de código:

Planeje a especificação "Sistema de Autenticação de Usuários":

Implementar autenticação por email/senha com tokens JWT, rotação de refresh token,
reset de senha por email, rate limiting em tentativas de login, e bloqueio de conta
após 5 tentativas falhas. Usar bcrypt para hashing. Incluir middleware para rotas
protegidas.

O agente chama start_planning_session e inicia o planejamento. Em cerca de 30 segundos, você terá:

• 4 épicos — Autenticação Core, Gestão de Tokens, Fluxo de Reset de Senha, Rate Limiting & Bloqueio
• 13 tickets — Cada um com passos de implementação, critérios de aceitação e arquivos esperados
• Um grafo de dependências — Tickets vinculados na ordem correta de execução

Passo 2 — Valide com o Planning Review

A especificação existe, mas está pronta para implementação? Diga ao seu agente:

Rode o planning review para esta especificação

O Planning Review é um quality gate que avalia a especificação ANTES de qualquer código ser escrito. Ele verifica:

• Completude — Todos os tickets têm passos e critérios de aceitação?
• Dependências — O grafo é válido? Sem referências circulares?
• Cobertura — A decomposição cobre tudo que está na descrição?
• Qualidade dos Tickets — Os tickets são atômicos e implementáveis, não épicos vagos disfarçados de tickets?
• Critérios de Aceitação — Os critérios são específicos e verificáveis, não “deve funcionar bem”?

Se o review passa (score ≥ 80), a especificação está pronta. Se não, você recebe findings específicos — “ticket X não tem critérios de aceitação”, “a descrição menciona rate limiting mas nenhum ticket endereça isso” — e você refina até passar.

Este é o primeiro loop de controle: a IA decompõe, o quality gate valida, você refina. A spec melhora a cada iteração. Nenhum código é escrito até que o plano seja sólido.

Passo 3 — Implemente

Uma vez que o Planning Review passa, você tem dois caminhos:

• Manual — Pegue tickets você mesmo, use ferramentas MCP para acompanhar progresso
• Autônomo — Deixe seu agente implementar a especificação inteira com Implementação Autônoma

O quality gate validou o plano. Agora o grafo de dependências garante que os agentes implementam na ordem correta. E o gate de assay de cada ticket valida o código conforme o trabalho é entregue — o segundo loop de controle, rodando por ticket dentro de complete_work_session.

Qualidade na entrada, qualidade na saída. A spec direciona tudo.

Agora tente com o SEU projeto. Você não precisa acertar tudo na primeira tentativa — o Planning Review vai te dizer exatamente o que falta. Forneça sua intenção, deixe a IA decompor, rode o review, e refine com base nos findings. Cada iteração te aproxima de uma spec que os agentes conseguem implementar corretamente de primeira.

Criar uma Especificação pelo Painel

1. Abra seu projeto no painel do SpecForge
2. Clique em New Specification
3. Insira um título — um nome conciso para a feature ou sistema que você está construindo
4. Escreva uma descrição — quanto mais detalhes você fornecer, melhor a decomposição

Por exemplo:

• Título: User Authentication System
• Descrição: Implement email/password authentication with JWT tokens, refresh token rotation, password reset via email, rate limiting on login attempts, and account lockout after 5 failed attempts. Use bcrypt for hashing. Include middleware for protected routes.

Clique em Create e o SpecForge começa o planejamento.

Fazer o Bootstrap de uma Especificação pela CLI

Se você já está no terminal com seu agente de código, não precisa trocar para o navegador. Faça o bootstrap da spec você mesmo e deixe o agente planejá-la:

specforge init

Depois entregue a intenção ao seu agente:

Planeje a especificação "Sistema de Autenticação de Usuários": Implementar
autenticação por email/senha com tokens JWT, rotação de refresh token, reset de
senha por email, rate limiting em tentativas de login, e bloqueio de conta após 5
tentativas falhas.

O agente chama a ferramenta MCP start_planning_session e inicia o planejamento. Tudo que você pode fazer na webapp, pode fazer pelo terminal.

Como a Decomposição Funciona

Após criar uma especificação, a fase de planejamento executa através do seu agente de código via ferramentas MCP:

1. Análise — Sua descrição é analisada em busca de features, restrições e requisitos técnicos
2. Geração de épicos — Agrupamentos lógicos emergem (ex.: “Core Auth”, “Password Reset”, “Rate Limiting”)
3. Criação de tickets — Cada épico é dividido em tickets atômicos e implementáveis
4. Mapeamento de dependências — Tickets são vinculados pelo que deve ser concluído antes que outra coisa possa começar

Isso não é uma lista plana de tarefas. É um grafo acíclico direcionado onde cada ticket conhece seus pré-requisitos.

💡 A qualidade da decomposição escala com a qualidade da sua descrição. Inclua restrições técnicas, preferências de bibliotecas e casos extremos. O SpecForge usa tudo que você fornecer. Uma descrição vaga produz um plano vago — qualidade entra, qualidade sai.

Como é uma Especificação Planejada

Quando o planejamento termina, sua especificação contém uma decomposição detalhada. Veja o que o exemplo acima poderia produzir:

Épicos

Tickets de Exemplo (Core Authentication)

Tickets com status ready não têm dependências pendentes — podem ser trabalhados imediatamente. Tickets com status pending estão aguardando trabalho upstream.

Refinando Sua Especificação

Antes da implementação, você pode refinar pela webapp (edição visual) ou através do seu agente de código (ferramentas MCP):

• Editar tickets — Ajustar escopo, adicionar critérios de aceite ou esclarecer requisitos
• Adicionar dependências — Vincular tickets que precisam de ordenação com a op create_dependencies de action_planning_session
• Verificar ciclos — O SpecForge rejeita dependências circulares automaticamente dentro de create_dependencies — uma aresta que formaria um ciclo é recusada ao submeter o lote (não há ferramenta separada)
• Revisar o caminho crítico — Veja qual cadeia de tickets determina o cronograma geral com get_critical_path

A webapp oferece edição visual com drag-and-drop. As ferramentas MCP oferecem o mesmo poder pelo terminal. Use o que melhor se encaixar no seu contexto.

✅ O gate de revisão de planejamento roda dentro de complete_planning_session — ele retorna uma avaliação por IA (pontuação + achados) da completude da sua especificação antes de passar para a implementação.

O Que Acontece a Seguir

Com uma especificação totalmente planejada e tickets em status ready, você tem dois caminhos:

1. Implementação manual — Pegue tickets você mesmo, use ferramentas MCP para acompanhar o progresso, vincule commits e PRs
2. Implementação autônoma — Deixe seu agente de código implementar a especificação inteira com execução paralela orquestrada

A maioria das equipes começa manual para ganhar confiança, depois parte para o autônomo em especificações maiores.

Próximo: Instalar CLI →