Skip to Content
ConceitosEspecificações

Especificações

Uma especificação é uma descrição completa de uma feature ou entregável. Ela contém tudo que um agente precisa para entender, planejar e implementar — de objetivos e restrições ao grafo de dependência completo.

O Que É uma Especificação?

A spec é a unidade de planejamento no SpecForge. Você descreve o que quer em linguagem natural, e o motor decompõe em épicos, tickets e um grafo de dependência. Dois gates de qualidade validam o plano e a implementação antes que qualquer coisa seja entregue.

Mas uma especificação é mais que uma descrição. Após o planejamento, ela se torna um objeto estruturado com contexto, critérios de qualidade, decisões técnicas e padrões herdados. Cada campo existe para dar aos agentes a informação que precisam para implementar corretamente — sem adivinhar.

Anatomia de uma Especificação

Uma especificação planejada contém quatro grupos de campos. Você não preenche todos manualmente — alguns são definidos durante a criação, outros emergem durante a fase de planejamento conforme o agente decompõe e refina.

Contexto — O Que Construir

Esses campos definem o espaço do problema. Eles respondem: “O que estamos construindo, por quê, e o que está no escopo?”

goals — O que a spec deve alcançar. São resultados, não tarefas. “Usuários podem redefinir sua senha via email” é um objetivo. “Criar um endpoint de redefinição de senha” é um passo de ticket — pertence a um nível abaixo.

Use goals para alinhar o agente com a intenção. Quando o agente enfrentar uma decisão não coberta por tickets (e vai acontecer), os goals são o desempate. Se um goal diz “minimizar atrito do usuário”, o agente escolhe a opção de UX mais simples.

requirements — Requisitos funcionais e não-funcionais. “Tokens JWT expiram após 15 minutos” é funcional. “Endpoint de login responde em menos de 200ms” é não-funcional.

Goals vs requirements: Goals descrevem resultados. Requirements descrevem restrições sobre como esses resultados devem funcionar. Uma spec pode ter o goal “autenticação segura” e o requirement “usar bcrypt com fator de custo 12.” O goal explica por quê, o requirement explica quão rigoroso.

scope — O que está dentro e fora. Escopo explícito previne que agentes façam gold-plating. “No escopo: autenticação email/senha, redefinição de senha. Fora do escopo: provedores OAuth, 2FA.” Sem isso, um agente ambicioso pode construir OAuth porque parece a coisa certa a fazer.

Sempre defina o fora-de-escopo. É mais útil que o dentro-do-escopo. Agentes entendem o que construir a partir dos tickets. O que eles não sabem é onde parar.

background — Contexto para entender a feature. Arquitetura existente do sistema, lógica de negócio relevante, personas de usuário, decisões anteriores. Este é o documento de onboarding para o agente — tudo que um novo desenvolvedor precisaria saber antes de começar.

Background é opcional mas de alto valor. Uma spec com bom background produz decomposição melhor porque o agente entende o sistema no qual está construindo.

Qualidade — Como Validar

Esses campos definem critérios de sucesso e limites. Eles respondem: “Como sabemos que está pronto, e o que o agente nunca deve fazer?”

acceptanceCriteria — Condições que devem ser atendidas para a spec ser considerada completa. São critérios de nível de spec, distintos dos critérios de nível de ticket. “Todos os endpoints retornam formato de erro consistente” é nível de spec. “Login retorna 401 em credenciais inválidas” é nível de ticket.

Critérios de aceite de nível de spec capturam preocupações transversais. Tickets individuais podem passar seus próprios critérios mas violar um padrão de toda a spec. O Implementation Review avalia ambos os níveis.

guardrails — Restrições que agentes devem seguir durante a implementação. “Nunca armazenar senhas em texto puro.” “Sempre usar queries parametrizadas.” “Não modificar o schema do modelo de usuário existente.”

Guardrails vs constraints: Guardrails são sobre comportamento do agente — o que o agente deve ou não fazer. Constraints são sobre o sistema — limitações técnicas ou de negócio que existem independentemente de quem está implementando.

constraints — Limitações técnicas ou de negócio. “Deve funcionar com PostgreSQL 15.” “Não pode exceder 50MB de bundle.” “Deve suportar Node 18+.”

Constraints são fatos sobre o mundo. Guardrails são regras que você está impondo. A distinção importa porque constraints não são negociáveis — são limites rígidos. Guardrails podem ser ajustados se as circunstâncias mudarem.

successMetrics — Como medir se a spec atingiu seus objetivos após a implementação. “Taxa de sucesso de login > 99.5%.” “Taxa de conclusão de redefinição de senha > 80%.” “Tempo médio de resposta de auth < 150ms.”

Success metrics são pós-implementação. Não afetam o Implementation Review — são para você avaliar após o deploy se a feature está funcionando como pretendido.

Técnico — Como Construir

Esses campos capturam decisões arquiteturais e estrutura técnica. Eles respondem: “Como o sistema se parece?”

architecture — Decisões de design do sistema. Fronteiras de serviço, fluxo de dados, relacionamentos entre componentes. É onde você documenta “o serviço de auth é um módulo separado que o API gateway chama” ou “usamos uma cadeia de middleware para validação de requests.”

Architecture previne que o agente invente a sua própria. Sem ela, dois agentes trabalhando em paralelo podem construir a mesma feature com arquiteturas incompatíveis.

techStack — Tecnologias e frameworks. “TypeScript, Fastify, Prisma, PostgreSQL, Jest.” Agentes usam isso para gerar código na linguagem certa com as bibliotecas certas.

fileStructure — Organização esperada de arquivos. “Services vão em src/services/. Testes espelham a árvore de source em tests/.” Isso garante que agentes produzam código que se encaixa no layout do seu projeto.

apiContracts — Definições de interface. Formatos de request/response, formatos de erro, headers de autenticação. Pode referenciar specs OpenAPI, schemas GraphQL ou descrições em texto.

Padrões Herdados — Como Seu Código Se Parece

Esses campos são especiais. Eles definem padrões que são herdados por cada ticket na especificação. Em vez de repetir “use este estilo de import” em 15 tickets, você define uma vez no nível da spec.

codeStandards — Convenções e regras de estilo de código. “Use named exports. Prefira interface sobre type para formas de objeto. Mensagens de erro seguem o formato [SERVICE_NAME] description.”

commonImports — Imports compartilhados entre tickets. “Todo arquivo de service importa { logger } from '@/lib/logger'.” Agentes incluem automaticamente sem cada ticket precisar especificar.

returnTypes — Padrões de tipo de retorno. “Todos os métodos de service retornam Result<T, AppError>.” “Endpoints de API retornam { data, error, metadata }.” Isso garante consistência em todo o código implementado.

Padrões herdados são os campos de maior alavancagem em uma especificação. Eles se multiplicam em cada ticket. Uma entrada em codeStandards afeta dezenas de arquivos. Sem eles, cada agente inventa suas próprias convenções, e o codebase parece que foi escrito por 15 pessoas diferentes — porque foi.

Ciclo de Status

Uma especificação passa por 10 estados em três fases:

Planejamento: draft → planning → specifying → validating → ready

Implementação: in_progress → ready_for_review

Revisão: in_review → reviewed → completed

Transições dentro da fase de planejamento (o “corredor de planejamento”) acontecem automaticamente baseadas nas suas operações. Criar estrutura move para planning. Adicionar dependências move para specifying. Executar relatórios move para validating. Você não gerencia essas transições — o SpecForge rastreia o que você está fazendo e move o estado de acordo.

Para a máquina de estados completa com todas as transições e regras, veja Estados da Especificação.

O Que Faz uma Boa Especificação

O Planning Review vai capturar problemas estruturais. Mas a diferença entre uma spec que pontua 82 (mal passa) e uma que pontua 95 (passa limpo) se resume a como você a escreve.

Seja específico sobre restrições. “Use bcrypt” é melhor que “use hashing seguro.” O agente não vai errar a adivinhação.

Defina o fora-de-escopo explicitamente. Agentes são ambiciosos. Sem limites, eles constroem mais do que você pediu.

Inclua background. Uma spec que diz “adicionar auth à API” produz um plano genérico. Uma spec que diz “adicionar auth à API Fastify existente que serve uma SPA React, atualmente usando sessões baseadas em cookies, migrando para JWT” produz um plano que se encaixa no seu sistema.

Defina padrões herdados cedo. codeStandards, commonImports e returnTypes cascateiam para cada ticket. Defina uma vez, beneficie-se em todo lugar.

Escreva goals como resultados, não tarefas. “Usuários podem fazer login com email e senha” gera decomposição melhor que “construir um endpoint de login.”

Veja Também

Ciclos de VidaÉpicos & Tickets