Specs são o novo código-fonte quando AI gera a implementação

Agentes de AI coding geram implementação mais rápido do que a maioria dos times consegue clarificar o que quer construir. O gargalo se moveu. Não é mais velocidade de digitação, conhecimento de frameworks, nem expertise algorítmica. É a capacidade de expressar intent com precisão suficiente para que uma máquina produza comportamento correto na primeira tentativa — e comportamento previsível em cada tentativa subsequente. Código não é mais o recurso escasso. Clareza é. Specs são o novo código-fonte porque são o artefato que determina o que o sistema realmente faz, enquanto código gerado é cada vez mais uma representação derivada e descartável desse intent.

Essa mudança não é incremental. Redefine como product managers definem requisitos, como engenheiros investem seu tempo, como times medem qualidade, e onde vive a accountability quando algo quebra. As organizações que tratam specs como contratos vivos e enforceáveis estão entregando mais rápido e regredindo menos do que as que ainda as tratam como artefatos de coordenação escritos para humanos e esquecidos por máquinas.

AI torna specs fracas mais caras, não mais baratas

Cada requisito ambíguo que antes produzia um pull request confuso agora produz cinco implementações confiantes e contraditórias no tempo que levava para escrever o ticket. Um agente não para para fazer perguntas de clarificação. Preenche lacunas com suposições plausíveis, gera código que compila e passa nos testes que escreveu para si mesmo, e segue em frente. A ambiguidade não emerge até a integração, a review, ou produção — quando o custo de correção é mais alto.

Uma spec vaga como "construa um dashboard de billing" gera um sistema com suposições embutidas em cada camada: qual role de usuário vê quais dados, se valores são brutos ou líquidos, como assinaturas deletadas aparecem em agregados, o que acontece quando a fonte de dados está indisponível, se o componente faz streaming ou polling. Cada suposição é um defeito potencial. Cada defeito é invisível até que um humano com conhecimento de domínio inspecione a saída — o que derrota o propósito de usar um agente para economizar tempo.

A economia se inverteu. Quando implementação era cara, uma spec imprecisa custava horas extras de engenharia para interpretar. Agora que implementação é barata, uma spec imprecisa custa o retrabalho de descartar código gerado que satisfaz a letra do requisito mas viola seu intent. Quanto mais barata a geração de código se torna, mais cara a ambiguidade cresce.

O velho PRD era um artefato de coordenação — a nova spec é um contrato de execução

Documentos de requisitos de produto tradicionais serviam um propósito humano: alinhar stakeholders, registrar decisões, e dar aos engenheiros contexto suficiente para tomar decisões durante a implementação. Eram lidos uma vez, parcialmente, e depois superados por conversas no Slack, comentários no Figma, e decisões feitas mid-sprint que nunca voltaram ao documento.

Esse workflow não sobrevive ao desenvolvimento agentic. Um agente lê a spec literalmente. Não tem acesso à thread de Slack onde o PM clarificou que "usuários ativos" significa "logados nos últimos 30 dias, excluindo contas internas." Não tem memória do standup onde o designer disse que o empty state deveria mostrar um prompt de onboarding em vez de uma tela em branco. Gera o que a spec diz, não o que o time quis dizer.

A nova spec é um contrato de execução — um artefato versionado e enforceável que o agente trata como autoritativo. Define:

• Intent: qual outcome o sistema deve produzir, para quem, sob quais condições.
• Constraints: budgets de performance, fronteiras de segurança, requisitos de compliance, padrões de acessibilidade.
• Interfaces: formatos de input, formatos de output, respostas de erro, contratos de API.
• Invariantes: regras que nunca devem ser violadas independente do path de implementação (e.g., "o total de uma fatura nunca é negativo," "dados de um usuário deletado nunca são retornados na sessão de outro usuário").
• Exemplos: pares concretos de input-output que servem como documentação e como test cases.
• Modos de falha: o que acontece quando dependências estão indisponíveis, dados são malformados, ou rate limits são atingidos.

Quando algum desses elementos falta, o agente preenche a lacuna com seu próprio julgamento — que é estatisticamente plausível mas não necessariamente correto para o domínio específico.

Critérios de aceitação devem se tornar testes executáveis

A forma mais forte de uma spec é aquela onde os critérios de aceitação não são descrições em prosa que um humano interpreta — são assertions executáveis que o sistema valida continuamente. Isso não é novo em princípio. Behavior-Driven Development (BDD) tentou isso há duas décadas. O que mudou é que agentes de AI agora conseguem consumir critérios de aceitação estruturados e gerar tanto a implementação quanto a verificação em um único passo.

A mudança prática:

• Antes: PM escreve "o dashboard deve carregar em menos de 2 segundos." Engenheiro interpreta isso como um target p95 medido no cliente, ou talvez na API, ou talvez só em desenvolvimento. Ninguém verifica depois do lançamento.
• Depois: a spec estabelece latency_p95_ms: 2000, measurement_point: client_first_contentful_paint, environment: production. O agente gera a implementação, o teste de performance, e o alerta de monitoramento. O constraint é enforceável desde o primeiro deployment.

Esse padrão se estende a todo tipo de requisito. Modelos de permissão se tornam matrizes de acesso por role que o agente implementa como políticas RLS e testa como assertions de integração. Regras de validação de dados se tornam constraints de schema que o agente gera junto com os componentes de formulário. Empty states se tornam variantes de UI enumeradas que o agente renderiza para cada combinação de disponibilidade de dados.

Os eval rubrics que product managers escrevem para sistemas de AI seguem o mesmo princípio: a definição de "comportamento correto" é a especificação, e a especificação é executável. A distinção entre requisito e teste se dissolve.

Constraints importam mais do que instruções

Instruções dizem ao agente o que construir. Constraints dizem o que nunca deve quebrar. Em um mundo de código gerado, constraints são mais duráveis que instruções porque sobrevivem à regeneração — o agente pode reescrever a implementação inteira, mas os invariantes se mantêm.

Uma spec construída em torno de instruções:

"Construa um workflow de reembolso que envia um email de confirmação e atualiza o ledger."

Uma spec construída em torno de constraints:

"O workflow de reembolso deve: (1) nunca processar um reembolso que exceda o valor do cargo original, (2) produzir uma entrada de ledger idempotente keyed em refund_id, (3) emitir um evento de auditoria antes de qualquer mutação de estado, (4) completar em menos de 5 segundos no p99, (5) degradar gracefully se o serviço de email estiver indisponível — o reembolso prossegue, o email é retentado assincronamente."

A spec baseada em instruções dá ao agente liberdade para construir um sistema que funciona no happy path. A spec baseada em constraints dá ao agente um contrato que funciona em produção — incluindo os failure cases, race conditions, e edge states que instruções rotineiramente omitem.

Por isso refatorar antes da automação com AI importa como pré-requisito: os constraints devem existir como regras enforceáveis no sistema antes que o agente possa respeitá-los. Um constraint que só vive em conhecimento tribal é invisível para o agente e será violado.

O checklist de specs: o que uma especificação agent-ready inclui

Nem toda spec precisa de verificação formal. Mas toda spec que impulsiona código gerado por agentes precisa desses sete elementos para produzir output confiável:

1. Intent — uma frase descrevendo o outcome que o sistema produz para o usuário final. Não a implementação, não a abordagem técnica — o outcome.
2. Constraints — requisitos não funcionais codificados como limiares mensuráveis: budgets de latência, tetos de error rate, limites de custo, fronteiras de segurança.
3. Interfaces — contratos de input e output tipados. Request schemas, response shapes, event payloads. O agente não consegue gerar código de integração correto sem saber o que o sistema fala.
4. Invariantes — regras de domínio que devem se manter sob todas as circunstâncias. Sobrevivem reescritas de implementação e servem como âncoras de regressão.
5. Exemplos — cenários concretos com inputs específicos e outputs esperados. Funcionam como test cases e desambiguação para edge conditions.
6. Modos de falha — o que o sistema faz quando dependências falham, dados são inválidos, ou recursos se esgotam. Se a spec não define comportamento de degradação, o agente não vai implementá-lo.
7. Expectativas de teste — a estratégia de verificação. Unit, integração, performance, segurança. O que é testado, como, e quais limiares constituem um pass.

Uma spec que não inclui algum desses elementos está incompleta para desenvolvimento impulsionado por agentes. O agente ainda vai gerar código — vai gerar código que parece correto mas se comporta imprevisivelmente nas fronteiras que a spec não cobriu.

Perguntas frequentes sobre specs como código-fonte para AI?

O nível de rigor da spec depende do raio de explosão da feature e da complexidade do domínio envolvido.

Toda feature precisa de uma spec completa antes que AI gere código?

Features de baixo risco e bem entendidas — um filtro novo em uma lista, uma mudança de copy, um endpoint CRUD para uma ferramenta interna — precisam de especificação mínima. O domínio é estreito, os modos de falha são óbvios, e o custo de regeneração é baixo. Features de alto risco — qualquer coisa que toque billing, permissões, integridade de dados, ou orquestração cross-service — precisam de specs completas baseadas em constraints porque o custo de uma suposição incorreta se compõe com cada dependência downstream.

Qual formato uma spec agent-ready deve usar?

Markdown no repositório, versionado junto ao código. O formato importa menos que a estrutura: intent, constraints, interfaces, invariantes, exemplos, modos de falha, expectativas de teste. Alguns times usam YAML ou JSON schemas estruturados para campos machine-readable (budgets de latência, matrizes de roles). Outros mantêm tudo em prosa com test cases executáveis em arquivos companion. O constraint chave é que a spec deve ser verificável — um humano ou uma máquina pode confirmar se a implementação a satisfaz.

Quem escreve a spec — o PM ou o engenheiro?

Ambos. O PM define intent, constraints e invariantes — o que o sistema deve fazer e o que nunca deve fazer. O engenheiro adiciona interfaces, modos de falha e expectativas de teste — como o sistema se integra e como a correção é verificada. A spec é um artefato de colaboração, não um documento de handoff. Quando ambas perspectivas faltam, o agente opera com um olho fechado.

Um ponto de vista oposto

Um argumento reconhecido no campo sustenta que exigir specs completas antes da implementação reintroduz atrasos tipo waterfall em um workflow ágil. Agentes modernos podem gerar implementações exploratórias, surfar edge cases que o time não havia considerado, e refinar iterativamente tanto a spec quanto o código em um feedback loop ajustado. Exigir specs completas upfront assume que o time conhece todos os requisitos de antemão — o que raramente é verdade para features novas.

Essa visão está correta sobre descoberta. Agentes são excelentes para expor as implicações de um requisito gerando uma implementação candidata que revela lacunas. O erro está em confundir exploração com produção. Uma implementação exploratória gerada sem constraints é um protótipo — útil para aprender, perigoso se shipado. A spec não precisa estar completa antes que o agente comece; precisa estar enforced antes que o output do agente entre no sistema. Descoberta e enforcement são fases distintas, não filosofias competidoras.

O que vale a pena lembrar

• Quando implementação se torna barata, ambiguidade se torna a parte mais cara do software. O gargalo se moveu de digitar código para especificar intent.
• Specs não são mais documentos de coordenação para humanos. São contratos de execução para agentes — o artefato que determina o que o sistema realmente faz.
• Constraints são mais duráveis que instruções. Um agente pode reescrever toda a implementação; os invariantes devem se manter independente do que aconteça.
• Uma spec agent-ready completa inclui intent, constraints, interfaces, invariantes, exemplos, modos de falha e expectativas de teste.
• A spec é uma colaboração entre PM (intent, constraints, invariantes) e engenharia (interfaces, modos de falha, expectativas de teste). Nenhuma perspectiva sozinha é suficiente.
• Descoberta e enforcement são fases distintas. Agentes podem explorar sem specs; não podem shipar sem elas.

Conclusão

As organizações que entregam mais rápido com agentes de AI não são as que têm os melhores prompts. São aquelas cujas especificações são precisas o suficiente para que o código gerado satisfaça o intent na primeira passada e mantenha a correção através de ciclos de regeneração. A spec se moveu de um artefato de coordenação que humanos folheiam durante o kickoff para o ambiente de execução que agentes tratam como autoritativo. Isso muda quem faz o quê em um time de produto: product managers se tornam autores de specs cujo output determina diretamente o comportamento do sistema, e engenheiros se tornam arquitetos de constraints cujo trabalho é tornar essas specs enforceáveis. A pergunta para todo time adotando desenvolvimento agentic não é "qual modelo de AI deveria gerar o código" — é "quem é dono da spec, e ela é precisa o suficiente para produzir o sistema correto?"