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 requisitos 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 os limites 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 gate de assay por ticket avalia cada ticket contra seus próprios critérios e os de nível de spec.
guardrails — Regras 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.” “Deve funcionar com PostgreSQL 15.” “Não pode exceder 50MB de bundle.”
Guardrails são os limites que você impõe. Cobrem tanto o comportamento do agente — o que o agente deve ou não fazer — quanto os limites técnicos ou de negócio rígidos que a implementação não pode ultrapassar.
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.
folderStructures — 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.
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 cinco estados em duas fases:
Planejamento: draft → planning → ready
Implementação: in_progress → done
done é terminal — cada ticket passa no seu próprio gate de assay por ticket conforme é entregue, então não há uma fase separada de review de nível de spec. A especificação permanece no único estado planning enquanto você a constrói; não existe um corredor de sub-estados de planejamento com auto-transição. A máquina de planejamento de 7 fases (planning_spec → epic_decomposition → epic_expansion → ticket_decomposition → ticket_expansion → cross_validation → planned) avança na sessão de planejamento, não na especificação. A spec move para ready quando o gate de Planning Review passa, e para in_progress quando a primeira work session inicia.
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 requisitos. “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
- Épicos & Tickets — As unidades atômicas dentro de uma especificação
- Blueprints — Artefatos de design visual e estrutural vinculados a specs
- Gates de Qualidade — Os dois gates que guardam cada especificação
- Ciclos de Vida — Os dois lifecycles que impulsionam o SpecForge