eps1.3IA

Engenharia de Contexto - Parte 3: Spec-Driven Development

Em vez de um prompt gigante e torcer pelo melhor, especificações em markdown viram a fonte da verdade: PRD, Tech Spec, tarefas, review e QA, passo a passo com o Claude Code.

10 min de leitura

Você abre o agente de IA e escreve: “cria um site para a minha empresa, bonito e responsivo”. Ele cria. O resultado até parece bom na primeira olhada, mas não tem o seu menu, não fala com o seu público, usa uma stack que ninguém do time conhece e não tem um teste sequer.

O problema não é o modelo. É o contexto. Na parte 1 vimos que a LLM só trabalha com o que está na janela de contexto, e na parte 2 vimos como Rules e Skills dão memória e habilidades ao agente. Falta organizar o que ele vai construir, como e em que ordem. É isso que o Spec-Driven Development resolve.

Este post é baseado numa apresentação que fiz para o time, em que construímos uma landing page do zero usando esse fluxo. Todo o material está no repositório github.com/renangabriel27/spec-driven-development: comandos, templates, rules, os documentos gerados e o próprio site, que está no ar em fretadao-site.vercel.app.

O que é Spec-Driven Development

Spec-Driven Development (SDD, desenvolvimento orientado a especificações) é trabalhar com documentos como fonte da verdade, em vez de prompts soltos. Antes de escrever código, o agente ajuda você a escrever:

  • PRD (Product Requirements Document): o o quê e o porquê. Problema, objetivos, histórias de usuário, requisitos funcionais numerados e, muito importante, o que está fora do escopo.
  • Tech Spec: o como. Arquitetura, componentes, interfaces, decisões de stack, estratégia de testes e sequência de desenvolvimento.
  • Tasks: o PRD e a Tech Spec quebrados em tarefas pequenas, cada uma com subtarefas, critérios de sucesso e os próprios testes.

Esses arquivos ficam em markdown dentro do repositório, e é aí que mora o pulo do gato: eles viram a memória do trabalho. Qual tarefa já foi feita, qual teste falta, o que foi decidido e por quê. Você fecha a sessão, abre outra no dia seguinte e o agente continua de onde parou, sem você reexplicar nada.

Em vez de mandar um prompt gigante toda vez, você trabalha em cima de especificações que foram discutidas, revisadas e aprovadas.

Ferramentas que já fazem isso

Já existem ferramentas prontas para esse fluxo:

  • GitHub Spec Kit: kit open source do GitHub com CLI, templates e prompts para ir da especificação ao plano técnico e às tarefas.
  • Kiro: IDE da AWS que transforma um prompt em requisitos, documento de design e lista de tarefas antes de gerar código.
  • Compozy: projeto open source feito por brasileiros, que orquestra vários agentes (Claude Code, Codex, Gemini CLI, Cursor) num pipeline com memória compartilhada. Vale abrir o repositório só para estudar como as skills dele são organizadas.

Elas são ótimas, mas escondem as etapas. Neste post vamos fazer o fluxo na mão, com um comando para cada fase, para entender o que acontece por baixo dos panos. Depois disso, qualquer uma dessas ferramentas fica bem mais fácil de entender.

Comandos: o prompt que você não precisa reescrever

Na parte 2 falamos de Rules e Skills. O fluxo deste post usa um terceiro recurso do Claude Code: os comandos.

Um comando é um prompt que você usaria sempre igual, salvo num arquivo em .claude/commands/. Em vez de colar as mesmas 80 linhas de instrução toda vez, você digita /create-prd e pronto.

A diferença para uma Skill é quem aciona. A Skill deixa o nome e a descrição na janela de contexto, e o próprio agente decide quando carregar. O comando não ocupa nada no contexto até você chamar, e só você chama. Para um fluxo em etapas, em que você quer controlar exatamente quando cada fase começa, isso é uma vantagem. (Esses comandos também poderiam ser Skills; usei comandos para apresentar o conceito.)

O repositório tem um comando para cada etapa:

.claude/
  commands/
    create-prd.md
    create-techspec.md
    create-tasks.md
    run-task.md
    run-review.md
    run-qa.md
    run-bugfix.md
  agents/
    task-reviewer.md
  rules/
    common/       ← testing, frontend, git, security, debug
    typescript/
templates/
  prd-template.md
  techspec-template.md
  tasks-template.md
  task-template.md
tasks/
  prd-site-fretadao/           ← tudo que o fluxo gera fica aqui

O desafio: uma landing page a partir de um design

O desafio da apresentação foi criar o site institucional do Fretadão, uma página só, a partir de um design pronto. (Não é o site oficial da empresa: é material didático, e o conteúdo serve só para ilustrar o processo.)

Primeira dica, e talvez a mais importante para front-end: comece pelas imagens. Eu gerei o mockup do site no Claude Design e salvei as telas na pasta site/ do projeto, uma imagem por seção. Com o design na mão, o agente sabe exatamente o que construir, e a diferença de qualidade é enorme em relação a descrever o layout em texto.

Mockup do hero do site do Fretadão gerado no Claude Design: título "O caminho casa-trabalho-casa, mais humano.", botões de agendar reunião e um card com a rota do dia

Esse é o hero, a primeira das seis imagens. As outras cobrem as soluções, o “como funciona”, o manifesto, o CTA final e o rodapé.

Passo 1: o PRD (/create-prd)

O comando create-prd tem três regras no topo, em destaque:

<critical>NÃO GERE O PRD SEM ANTES FAZER PERGUNTAS DE CLARIFICAÇÃO</critical>
<critical>EM HIPOTESE NENHUMA, FUJA DO PADRÃO DO TEMPLATE DO PRD</critical>

O fluxo é: esclarecer, planejar e só então redigir, seguindo o templates/prd-template.md. E o foco é no o quê e no porquê, nunca no como.

Chamei assim:

/create-prd Gostaria de criar um site one page do Fretadão com base no design das imagens em @site

Antes de escrever uma linha, ele analisou as imagens e me fez perguntas:

  • Qual o objetivo principal do site: gerar leads B2B ou fortalecer a marca?
  • O que acontece quando alguém clica em “Agendar reunião”?
  • O conteúdo precisa ser editável sem mexer no código?
  • Os links do rodapé funcionam nesta entrega ou ficam fora do escopo?
  • Qual é o público prioritário?
  • Precisa de Google Analytics?

Respondi que era um site de marca, estático, com o botão redirecionando para uma ferramenta externa de agendamento, navegação por âncoras, links do rodapé fora do escopo, sem analytics e responsivo. O PRD saiu com visão geral, objetivos, histórias de usuário, requisitos numerados e a lista do que não será feito:

### 2. Seção Hero

**Requisitos funcionais:**
2.1. Exibir badge de credibilidade: "A solução nº1 em mobilidade corporativa no Brasil".
2.2. Exibir headline principal: "O caminho casa–trabalho–casa, mais humano."
2.4. Exibir dois botões de ação: "Agendar reunião →" (primário) e "Conhecer soluções" (secundário).
2.5. Exibir widget ilustrativo de rota ("Sua rota de hoje") com ponto de embarque e destino, simulando a experiência do app.

Requisitos numerados não são burocracia: são eles que o review e o QA vão conferir lá no final. Este PRD fechou com 28 deles, do 1.1 ao 9.4, e a seção “Fora de Escopo” deixou claro o que não entra: páginas internas, área logada, integrações com CRM e analytics, agendamento nativo.

Passo 2: a Tech Spec (/create-techspec)

Com o PRD aprovado, o próximo comando traduz requisito em decisão técnica:

/create-techspec @tasks/prd-site-fretadao/prd.md

Antes de perguntar qualquer coisa, o comando manda o agente explorar o projeto, ler as rules em .claude/rules e pesquisar. Para isso ele usa duas ferramentas externas via MCP.

MCP (Model Context Protocol) é a forma de conectar a sua ferramenta de IA a outros sistemas: ClickUp, Google Drive, GitHub, um navegador. Lembra das tools da parte 1? Um MCP é um pacote de tools que alguém já escreveu para você. Aqui usamos dois:

  • Context7: busca a documentação atualizada de bibliotecas e frameworks, para o agente não decidir com base em uma versão antiga do React que ele viu no treinamento.
  • Playwright: controla um navegador de verdade, para testes ponta a ponta (vamos usar no QA).

Depois de pesquisar, ele voltou com as perguntas técnicas: Next.js com export estático, Astro, ou Vite com React e TypeScript? Tailwind ou CSS Modules? Que nível de testes? Escolhi Vite + React + TypeScript + Tailwind, testes unitários e E2E, e ícones de uma biblioteca.

A Tech Spec saiu com o resumo da abordagem, a árvore de componentes, as interfaces, os pontos de integração, a estratégia de testes e a sequência de desenvolvimento. Um trecho:

src/
  App.tsx                           ← compositor puro: sem lógica, só composição
  components/
    layout/                         ← Header, Footer
    sections/                       ← HeroSection, SolutionsSection, CtaSection...
    ui/                             ← Button, Card, SectionLabel, RouteWidget
  theme/
    colors.ts                       ← tokens de cor da marca
  constants/
    strings.ts                      ← todo o copy centralizado

Repare na pasta theme/ e no strings.ts. Eles vieram de uma rule do projeto (common/frontend.md) que proíbe cores, fontes e textos soltos nos componentes. É por isso que vale ter Rules prontas antes de começar: a Tech Spec já nasce no padrão do time.

Ela também registra o porquê de cada escolha. Vite em vez de Next.js porque, para uma landing page estática, o overhead de SSR não se justifica. A URL de agendamento numa variável de ambiente (VITE_BOOKING_URL), porque a ferramenta pode trocar de Calendly para HubSpot sem ninguém mexer no código.

Passo 3: as tarefas (/create-tasks)

/create-tasks @tasks/prd-site-fretadao

Duas regras desse comando fazem toda a diferença:

<critical>**ANTES DE GERAR QUALQUER ARQUIVO ME MOSTRE A LISTA DAS TASKS HIGH LEVEL PARA APROVAÇÃO**</critical>
<critical>CADA TAREFA DEVE SER UM ENTREGÁVEL FUNCIONAL E INCREMENTAL</critical>

Na apresentação ao vivo, ele sugeriu quatro tarefas e eu pedi para juntar em duas, para caber no tempo. Na versão final do repositório, o trabalho ficou em três: 1.0 Fundação do Projeto (tema, constantes e componentes base), 2.0 Implementação Visual (as seções) e 3.0 Composição Final e Testes E2E.

No dia a dia, prefira mais tarefas e menores. Cada uma é um ponto em que você pode parar, testar, ver se está do jeito que quer e corrigir o rumo. Se precisar mudar algo, o agente atualiza o PRD ou a Tech Spec junto, e a especificação continua sendo a fonte da verdade.

O resultado é um tasks.md com o checklist geral e um arquivo por tarefa:

# Tarefa 1.0: Fundação do Projeto

<critical>Ler os arquivos de prd.md e techspec.md desta pasta, se você não ler esses arquivos sua tarefa será invalidada</critical>

## Subtarefas
- [ ] 1.1 Inicializar projeto: `npm create vite@latest fretadao-site -- --template react-ts` ...
- [ ] 1.2 Configurar Tailwind v4 ...
- [ ] 1.4 Criar `src/theme/colors.ts`, `typography.ts`, `spacing.ts` e `index.ts` com tokens da marca ...

## Critérios de Sucesso
## Testes da Tarefa

Uma dica de custo: use o modelo mais inteligente que você tiver (no Claude Code, o Opus) para os três primeiros passos. São poucos arquivos de saída, mas é onde as decisões são tomadas, e um erro aqui se multiplica na implementação. Para executar as tarefas, um modelo mais barato como o Sonnet costuma dar conta, porque o caminho já está todo desenhado.

Passo 4: executar e revisar (/run-task)

/run-task @tasks/prd-site-fretadao/1_task.md

O comando lê o PRD, a Tech Spec e a tarefa, faz um resumo e um plano de abordagem e começa a implementar. Três regras seguram a qualidade:

<critical>A TAREFA NÃO PODE SER CONSIDERADA COMPLETA ENQUANTO TODOS OS TESTES NÃO ESTIVEREM PASSANDO, **com 100% de sucesso**</critical>
<critical>Você não pode finalizar a tarefa sem executar o agente de review @task-reviewer, caso ele não passe você deve resolver os problemas e analisar novamente</critical>
<critical>Após completar a tarefa, marque como completa em tasks.md</critical>

O task-reviewer é um subagente: um arquivo em .claude/agents/ com uma missão e uma série de instruções, nada mais complexo que isso. Ele identifica a tarefa, olha o git diff, confere o código contra as rules e escreve um 1_task_review.md. Se reprovar, o agente principal corrige e roda a revisão de novo.

E o checkbox marcado no tasks.md é a memória de que falei lá no começo: na próxima sessão, o agente sabe exatamente o que já foi feito.

Passo 5: review, QA e bugfix

Com as tarefas prontas, mais três comandos fecham o ciclo:

  • /run-review: faz um code review da branch inteira com git diff, confere a aderência às rules, à Tech Spec e às tarefas, roda os testes e gera um relatório com status aprovado, aprovado com ressalvas ou reprovado.
  • /run-qa: abre a aplicação num navegador de verdade pelo Playwright MCP, testa cada requisito do PRD (aqueles RF numerados), verifica acessibilidade (WCAG 2.2) e tira screenshots como evidência. Bug encontrado vai para um bugs.md.
  • /run-bugfix: lê o bugs.md, corrige cada bug na causa raiz e cria um teste de regressão para cada um, que falharia se a correção fosse revertida.

Os números do final, todos registrados nos relatórios dentro de tasks/prd-site-fretadao/:

  • As revisões do task-reviewer das tarefas 1 e 2 saíram aprovadas com observações: nada bloqueante, mas com pontos a ajustar, como a fonte que a Tech Spec pedia e não tinha sido carregada.
  • O code review final saiu aprovado com ressalvas.
  • O QA verificou os 28 requisitos do PRD: 28 atendidos, com 48 testes E2E passando e nenhum bug encontrado.

O resultado foi o site fiel ao design, com o código organizado do jeito que a Tech Spec definiu, testes passando e um relatório de cada etapa. E o mais importante: dá para auditar cada decisão, porque está tudo escrito. Dá para ver o site no ar em fretadao-site.vercel.app.

À esquerda, o mockup que entrou no /create-prd. À direita, o site que saiu do fluxo:

Comparação lado a lado da página inteira: à esquerda o mockup do Claude Design, à direita o site final em React e Tailwind, com as mesmas seções na mesma ordem

E a versão mobile, que era um dos requisitos do PRD:

Site final do Fretadão no desktop e no celular, com o menu recolhido no mobile

Leve para o seu dia a dia

Você não precisa usar esses comandos como estão. Eles são um ponto de partida: copie, adapte aos templates e rules do seu time e jogue fora o que não fizer sentido. Talvez você só queira o /run-review no seu fluxo atual, e tudo bem.

Um exemplo que funciona bem com MCP: conecte o MCP da sua ferramenta de gestão (no meu caso, o ClickUp) e peça para o agente criar o PRD a partir do card. A descrição, os comentários e as subtarefas viram contexto, e daí em diante o fluxo é o mesmo: Tech Spec, tarefas, execução.

E isso é só a base. Em cima do SDD já se fala em Harness Engineering, que é cuidar de todo o ferramental em volta do agente (rules, skills, comandos, hooks, review automático no GitHub) para ele produzir código no padrão do time sem quebrar produção, e em loops, em que o agente repete o ciclo executar, revisar e corrigir sozinho até o objetivo ser atingido. Os dois dependem do que vimos aqui: especificações claras para o agente saber quando terminou.

Conclusão

Spec-Driven Development é Engenharia de Contexto aplicada ao ciclo inteiro de uma funcionalidade. Em vez de esperar que um prompt carregue tudo, você constrói o contexto em camadas:

  1. O PRD diz o que construir e por quê, e o que fica de fora
  2. A Tech Spec diz como, no padrão das suas rules
  3. As tasks dividem o trabalho em entregas pequenas e testáveis
  4. Review, QA e bugfix conferem o resultado contra o que foi especificado

Cada etapa gera um arquivo, e cada arquivo vira contexto para a próxima. A especificação passa a ser a fonte da verdade, e o código, a consequência dela.

Na próxima parte: como construir um segundo cérebro com Claude Code e Obsidian, a base de conhecimento que o agente consulta.

Referências

A seguir