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 — Crie a spec

Diga ao seu agente de código:


Crie uma nova especificação SpecForge intitulada "Sistema de Autenticação de Usuários"
com a seguinte descrição:

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 create_specification 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 Implementation Review vai validar o código depois — o segundo loop de controle.

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

Abra seu projeto no painel do SpecForge
Clique em New Specification
Insira um título — um nome conciso para a feature ou sistema que você está construindo
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.

Criar uma Especificação pela CLI

Se você já está no terminal com seu agente de código, não precisa trocar para o navegador. Diga ao seu agente:


Create a new SpecForge specification titled "User Authentication System"
with the following description: 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.

O agente chama a ferramenta MCP create_specification e retorna o ID da nova especificação. 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:

Análise — Sua descrição é analisada em busca de features, restrições e requisitos técnicos
Geração de épicos — Agrupamentos lógicos emergem (ex.: “Core Auth”, “Password Reset”, “Rate Limiting”)
Criação de tickets — Cada épico é dividido em tickets atômicos e implementáveis
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.

Especificação em linguagem natural se decompondo em um grafo estruturado de dependências

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

#	Épico	Tickets
1	Core Authentication	4
2	Token Management	3
3	Password Reset Flow	3
4	Rate Limiting & Lockout	3

Tickets de Exemplo (Core Authentication)

Ticket	Depende De	Status
Set up User model and database schema	—	ready
Implement password hashing with bcrypt	User model	ready
Build registration endpoint	Password hashing	pending
Build login endpoint	Password hashing	pending

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

Grafo de dependências do Auth System com 4 épicos, 13 tickets e bandas de execução por wave

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 add_dependency
Verificar ciclos — O SpecForge previne dependências circulares automaticamente, mas você pode verificar com check_circular_dependencies
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.

✅ Use a ferramenta review_planning para obter uma avaliação por IA 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:

Implementação manual — Pegue tickets você mesmo, use ferramentas MCP para acompanhar o progresso, vincule commits e PRs
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 →