May 9, 2026
Spec-Driven Development (SDD) é um termo recente que vem sendo utilizado em conjunto com jornadas de agentes de AI para descrever documentos de especificação. A ideia é obter melhores resultados ao se utilizar esses agentes como geradores de código.
Table of Contents
Pode parecer algo novo, mas não é. Criamos documentos de especificação desde os primórdios da engenharia, antigamente eram chamados de "Documentação de Requisitos", você deve se lembrar desse termo em uma de suas aulas sobre "Padrões de Projetos" e similares.
A questão é que tudo isso é cíclico, e estamos mais uma vez focados no uso de algo que sempre foi verdade, mas que convenhamos, sempre foi negligenciado:
Boas documentações mudam tudo.
Isso se torna ainda mais importante atualmente com o intenso uso de agentes de IA focados em geração de código. Documentos não são apenas lidos por humanos, mas também por esses mesmos agentes que irão na maior parte das vezes serem os responsáveis pelas implementações. Aqui surge um caso de uso relevante para a utilização de estratégias focadas em SDD como veremos adiante.
Spec (Specification) que em português significa "especificação", é utilizado para representar esses documentos com detalhes específicos sobre regras de negócio, decisões técnicas, histórias de usuário, cenários de testes, etc. Não é muito diferente do que tínhamos há algum tempo, é literalmente descrever como o sistema ou determinada funcionalidade deve ser e se comportar.
Por ser um conceito novo existem alguns debates sobre qual é o melhor momento para usar SDD, alguns dizem que projetos de Greenfield são melhores, outros que em projetos Brownfield as coisas começam a ficar um pouco mais caóticas.
São termos utilizados para definir escopo e estado de projetos, o primeiro sendo projetos criados do zero e o segundo, projetos já em andamento.
Isso se relaciona com outro debate recorrente sobre o assunto: Spec-First, Spec-anchored e Spec-as-source, a maior parte das abordagens existentes focam na implementação de Spec-first, ou seja, documentos são criados primeiro e depois usados como fontes de implementação pelos agentes de IA.
Spec-anchored e Spec-as-source são abordagens evolutivas do processo, nas quais os documentos não são apenas usados como requisitos iniciais ou detentores de regras, mas como peças-chave de evolução dos workflows, juntamente com a evolução do sistema.
Documentação é algo vivo, ela representa o estado atual das aplicações e precisa evoluir juntamente com o sistema, pois humanos e agentes de IA irão utilizá-la como fonte de verdade para implementações e validações.
Atualmente, uma das maiores problemáticas em relação ao uso de IAs assistentes de código é justamente a geração de um código que faça sentido levando em consideração regras de negócio, limitações e decisões técnicas. Outro aspecto relevante é o custo de tokens, tokens são caros e muitas vezes os assistentes se perdem fazendo coisas sem sentido, até lá, já torramos uma quantidade de dinheiro em conta.
Estratégias de SDD ajudam a criar um foco no que realmente é preciso ser feito e principalmente o que não deve ser feito, o que pode trazer bons resultados e com um menor custo reduzindo interações desnecessárias das LLMs.
Vejamos alguns exemplos de estratégias de SDD utilizadas hoje em dia:
As abordagens acima não são as únicas existentes, mas são boas opções para começar a testar SDD em seus projetos. Vamos dar uma olhada em como de fato é estruturado um desses arquivos de spec.
# Feature Specification: Formulário de login
**Feature Branch**: `feat/login-form`
**Created**: 2026-05-09
**Status**: Draft
**Input**: Crie uma especificação para uma tela de login...
### User Story 1 - Successful Login (Priority: P1)
As a registered user, I want to enter my email and password into the login form so that I can access my account.
**Why this priority**: Core functionality; without successful login, users cannot use the application.
**Independent Test**: Can be fully tested by entering valid credentials and clicking "Login". Success is confirmed when the user is redirected or granted access.
**Acceptance Scenarios**:
1. **Given** the login page is loaded, **When** I enter a valid email and matching password and click "Login", **Then** I should be redirected to the application dashboard.
2. **Given** I am on the login form, **When** I click the password field, **Then** the characters I type should be masked for security.
...
## Requirements *(mandatory)*
### Functional Requirements
- **FR-001**: System MUST provide a clearly labeled text input field for the user's email address.
...
Observe que o arquivo acima descreve com detalhes regras de negócio e cenários de validação, ainda não temos nenhum detalhe técnico ou sugestão de código, isso é importante para delimitar o escopo de implementação para os agentes de IA.
Esse arquivo foi gerado a partir da CLI disponibilizada pelo próprio Spec-Kit. A instalação é simples e vai lhe permitir criar os arquivos de spec bem rápido. Como podemos ver na imagem abaixo, após o start de um novo projeto, cria-se uma spec com o comando /specify:
Apesar de ser uma boa estratégia, podemos citar alguns contrapontos sobre o uso de SDD, afinal, nem tudo é bala de prata.
O primeiro ponto é que podemos cair em casos de overengineering, ou em bom português, "Matar uma formiga com uma bazuca" (desculpem-me formigas 🐜). A ideia de sair criando um arquivo de especificação para tudo e deixar o Claude resolver parece incrível, mas até que ponto estaremos desperdiçando recursos preciosos (e extremamente caros) para simplesmente trocar uma label de um botão em uma tela do frontend?
Criar um documento de especificação detalhado leva tempo, como disse anteriormente documentações precisam evoluir junto com o sistema, então se tivermos inúmeros arquivos de especificação pra cada coisa, precisaremos passar muito tempo atualizando essas documentações, pois elas precisam refletir o estado do sistema hoje.
Então, você pode estar se perguntando: "Por que simplesmente não colocamos algum agente de IA para gerar essas documentações?", muito bom, questionamento extremamente válido, mas aqui vai outra provocação:
Até que ponto os agentes de IA possuem total domínio sobre seu negócio?
Se levarmos em consideração uma abordagem greenfield, ok, SDD será incrível, pois podemos modelar o sistema de acordo com o que estamos fazendo e ir orientando agentes de IA sobre como desejamos as specs e implementações.
Mas em cenários complexos, como em projetos existentes, é diferente, se o seu sistema/produto já possui uma boa documentação e esta é confiável, então sim, é completamente possível usarmos um agente para criar specs a partir do que ele já sabe do sistema e alimentá-lo com essas informações. Mas cá entre nós, sabemos que não é bem assim, pouquíssimos produtos possuem documentações completas, e quando têm, estão desatualizadas, aí eu volto a pergunta para você:
No seu contexto, seria trivial delegar toda a geração de specs para um agente de IA?
Esse é apenas um exemplo, podemos pensar em outros cenários, acredito que o ideal é um equilíbrio entre o que vale a pena ou não criar extensos documentos de especificação com histórias de usuário, cenários de teste, etc. Equilíbrio é a chave.
Para encerrar gostaria de compartilhar com você como tenho utilizado SDD em meu dia a dia, estarei utilizando uma aplicação criada especialmente para esse artigo para servir como exemplo, no final você encontra o link para o repositório.
Estou seguindo uma estratégia simplificada para a criação dos arquivos de spec, usando uma mistura dos três conceitos já citados aqui: spec-first, anchored e as-source.
Iniciamos o processo gerando um arquivo inicial descrevendo o que está no escopo da versão e o que está de fora, além de cenários de validação, requisitos, etc. Vejamos como o arquivo é estruturado:
# Read-It-Later — Specification
> Spec-Driven Development document. Requirement keywords (**MUST**, **MUST NOT**, **SHOULD**, **SHOULD NOT**, **MAY**, **REQUIRED**, **RECOMMENDED**, **OPTIONAL**) are used as defined in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119).
---
## 1. Purpose
The system **MUST** provide a minimal personal "read-it-later" application that allows a single user to:
1. Submit a website URL through a web form.
2. Persist the URL together with metadata automatically extracted from the target page.
3. List every previously stored URL on a dedicated page.
The system **MUST NOT** implement authentication, multi-user support, or content synchronization in this iteration. Those concerns are explicitly out of scope (see §13).
...
O principal fator aqui é o uso de palavras-chave nas descrições, sendo:
Esses e outros termos foram introduzidos na RFC2119, e servem para delimitar o nível de importância dos requisitos, sendo uma maneira consistente de descrever o nível de importância de cada requisito.
Em meus testes percebi que nem sempre os agentes seguem as regras descritas nas especificações, ainda que atualmente os agentes possuem maiores janelas de contexto, eles ainda se perdem quando há arquivos extensos e com muitas regras. Por esse motivo precisamos estar atentos e sempre revisar as estratégias utilizadas.
Algo que tem me ajudado nesse processo é pedir ao agente para "agir" como revisor, analisar e fazer sugestões sobre o arquivo de spec.md, obviamente ele não terá todo o contexto sobre aquela implementação, mas o resultado pode trazer alguma utilidade, como foi nesse caso:
- The backend **MUST** enable CORS for the frontend origin (default `http://localhost:8501`). The allowed origin **SHOULD** be configurable via environment variable `FRONTEND_ORIGIN`
+ The frontend **MUST** call the backend from server-side Python (e.g. `requests`/`httpx`) running inside the Streamlit process; the browser never calls the backend directly. The backend therefore **MUST NOT** be required to expose CORS headers, and CORS middleware **SHOULD NOT** be installed unless a browser-side client is introduced in a later iteration.
...
A instrução anterior dizia que o backend precisaria habilitar o CORS (uma regra de segurança entre frontend e backend). Mas após a revisão, o agente identificou que isso não era necessário, uma vez que um dos principais requisitos é delegar as chamadas às APIs para o servidor, nesse caso o frontend não precisa e nem deve fazer chamadas diretas para a API. Então não precisamos de CORS, já que o servidor conhece a origem.
Esse simples cenário ilustra que mesmo gerando uma spec que "parece" ser o suficiente ainda sim podem existir pontos de falha, o ideal é sempre ter quality gates para uma completa validação.
É um termo utilizado para descrever padrões de qualidade que se deseja atingir para determinado objetivo, no nosso caso, precisamos de algumas etapas de validação antes de passar para as implementações.
Acredito que vale a pena testar os conceitos de SDD e tirar suas próprias conclusões, uma vez que nem sempre sabemos exatamente quais são os requisitos necessários para implementar tal feature, e se sabemos, muito provavelmente isso irá mudar conforme o sistema cresce.
Por esse motivo acredito ser fundamental a ideia de documentações que evoluam junto com o sistema, assim, conseguimos manter a qualidade e um melhor entendimento das regras para humanos e máquinas.
Tudo ainda é muito novo e estão sendo discutidas quais são as melhores formas de se trabalhar e extrair o máximo de SDD. O melhor cenário aqui é estudar esses novos conceitos, testá-los e acima de tudo questionar se vale ou não a pena para o seu caso de uso.
Eu vou ficando por aqui, lhe agradeço pelo seu interesse e tempo de leitura. Deixo aqui o repositório da aplicação que citei no início dessa seção. Dê uma olhada especial no arquivo spec.md no qual utilizo os conceitos apresentados. Bons estudos e obrigado! ;)