Spec Driven Development: desenvolvimento assistido por agentes

SDD na era da IA - Apresentação

Apresentando o curso e objetivos

Boas-vindas a outro curso da Alura. Neste curso, veremos Spec Driven Development (Desenvolvimento Orientado por Especificação).

Vamos analisar, sob a perspectiva da pessoa desenvolvedora, como utilizamos ferramentas de LLM (Large Language Model, Modelo de Linguagem Grande) para auxiliar no desenvolvimento de software (programa de computador), algo que muitas empresas já demandam no dia a dia para geração de código. No entanto, vamos introduzir estrutura nesse processo de desenvolvimento.

Contextualizando as ferramentas e abordagem

Estamos com o Claude aberto, mas é possível acompanhar este curso com Claude, Gemini, Codex, LLaMA, ou a ferramenta que preferir; qualquer LLM funciona hoje. Contudo, utilizaremos o Claude neste curso.

Vamos estruturar nosso trabalho dentro do Spec Driven Development. Nosso processo de desenvolvimento não será apenas solicitar a geração de código ou de funcionalidades de maneira desorganizada e aleatória. Em vez disso, vamos entender o que precisamos fazer para que o LLM não perca contexto, não se desvie da tarefa, compreenda com clareza o que deve ser feito e quais são os problemas em jogo, além de discutir as diferenças entre escrevermos código diretamente e solicitar que um LLM o faça, sendo nós quem escreve em linguagem natural.

Analisando diferenças e iniciando o projeto

Qual é a diferença entre escrever nesses dois casos? Vamos analisar tudo isso e montar um projeto.

Partiremos de um projeto já preexistente, um projeto de e-commerce (comércio eletrônico), escolhido por ser um domínio muito comum: muitas pessoas o conhecem e, mesmo sem ter trabalhado diretamente nessa área, entendem intuitivamente como funciona. Implementaremos nossa abordagem Spec Driven (orientado a especificação).

Estruturando documentação e especificações

Teremos a parte de documentação da arquitetura do nosso sistema, como definimos as regras de negócio, como descrevemos um módulo do nosso sistema, o que é uma especificação de fato, como produzimos uma especificação, de onde a extraímos e por que fazemos dessa maneira. Reuniremos um conjunto de documentos para, ao final, termos nosso sistema implementado.

Como caso de uso, implementaremos o cancelamento de pedidos. Também validaremos essa funcionalidade: haverá uma rotina de testes no Postman (ferramenta de testes de API) para utilizarmos e, como podemos notar, no nosso código também foram implementados testes para garantir que o que solicitamos seja realizado corretamente.

Debatendo implicações e encerrando a introdução

No entanto, quem escreveu esse código — tanto os testes quanto a implementação — foi o LLM (modelo de linguagem grande). Qual problema podemos ter com isso? É uma discussão aberta que teremos: trata-se de uma área que ainda está mudando bastante, mas é um debate muito interessante para o dia a dia de uma pessoa desenvolvedora.

Vamos em frente e estudar.

SDD na era da IA - Contexto e ferramentas

Contextualizando o ponto de partida do projeto

Vamos iniciar nosso curso de Spec Driven Development (Desenvolvimento guiado por especificação). Estamos com o projeto do curso, isto é, o código que vamos implementar — parte do qual já está pronto. Vamos começar em um projeto já iniciado para adicionar o Spec Driven Development, em um caso mais real e alinhado ao que a maioria de vocês vivencia no dia a dia. Geralmente, já existe uma base de código; dificilmente começamos em um cenário de Greenfield (projeto iniciado do zero), no qual podemos fazer tudo como quisermos.

Vamos trabalhar com um código já preparado, que já possui algumas rotas. Temos uma API REST, um back-end (servidor), e ela está em execução no Docker (plataforma de contêineres). Mantemos o Docker aberto com três contêineres em execução:

• Postgres;
• Redis;
• Nossa API.

Apresentando a documentação e verificações iniciais

Realizamos algumas verificações e temos o Postman com toda a documentação organizada, incluindo:

• Rotas de verificação de saúde do sistema;
• Registro de nova pessoa usuária;
• Registro de pessoa usuária duplicada;
• Lista de produtos;
• Entre outras rotas pertinentes.

Tudo isso está preparado para executarmos os testes e evoluirmos a aplicação.

Apresentando a abordagem em nuvem e avisos iniciais

Vamos implementar o Spec Driven Development utilizando esta ferramenta neste projeto, com o suporte da ferramenta de Cloud (nuvem). Mantemos a ferramenta de Cloud aberta para organizar o projeto. Trabalhamos com uma API de e-commerce, na branch principal (main), e vamos usar a Cloud como nossa ferramenta, atuando como agente de IA para conduzir o Spec Driven Development.

Antes de começarmos, precisamos registrar alguns avisos. Tudo o que vamos discutir neste curso ainda está em debate ativo. Não há uma conclusão definitiva nem um consenso geral sobre qual é a melhor forma de aplicar essas práticas ou sobre a relevância exata de cada abordagem.

Discutindo tendências e escopo do curso

A relevância do tema está em alta com as IAs. Analisaremos como isso pode evoluir nos próximos anos, o que tende a mudar e o que provavelmente permanecerá. Dada a velocidade atual, mudanças significativas podem ocorrer em poucos meses.

Neste curso, apresentaremos uma discussão ampla e geral, com ideias sobre como implementar o Spec Driven (orientado por especificação), como aplicá-lo e quais pontos críticos levar para o dia a dia ao trabalhar em uma base de código utilizando o Spec Driven. Trata-se de uma discussão abrangente sobre aspectos que podem mudar nos próximos meses, no próximo semestre, ao longo deste ano ou mesmo no ano que vem, considerando o ritmo acelerado da evolução tecnológica.

Explorando o ecossistema de ferramentas e módulos da API

A evolução ocorre tanto no campo das IAs quanto no dos modelos. Cada novo modelo lançado traz capacidades adicionais. A cada nova versão do Harness (arcabouço), surgem novidades; o próprio Cloud Code (código em nuvem) é um Harness, isto é, uma ferramenta que envolve o LLM. O LLM é uma parte; o Harness é outra. O Harness adiciona habilidades e funcionalidades que podemos utilizar, como as próprias Skills (habilidades), os Workflows (fluxos de trabalho), além da forma de navegar e realizar o scaffolding (geração de estrutura) em nossas pastas. Esses recursos não são necessariamente responsabilidade do LLM, e sim do Harness. À medida que o Harness é atualizado, passamos a contar com novas funcionalidades e vantagens no uso.

Neste curso, nós vamos utilizar um projeto de uma API (Interface de Programação de Aplicações) de e-commerce (comércio eletrônico). Teremos módulos de autorização, carrinho, categorias, pedidos, pagamentos, produtos e usuários. Trabalharemos com esses módulos utilizando o Spec Driven (orientado por especificação). Partiremos de uma base de código já iniciada e mostraremos como incorporar o Spec Driven (orientado por especificação) a esse projeto.

SDD na era da IA - O que é Spec Driven Development?

Contextualizando o projeto ECOMICS e o Spec-Driven Development

Como dissemos, temos o projeto da nossa API de e-commerce. Vamos trabalhar nele, tomar esse projeto que já possui código e transformá-lo, ou tratá-lo, como um projeto no qual vamos passar a utilizar Spec-Driven Development (desenvolvimento orientado por especificação). Para isso, vamos entender melhor o que isso significa e quais são algumas possibilidades e metodologias.

Novamente, tudo o que vamos dizer aqui pode mudar. Ainda há muita discussão e não existe um consenso geral sobre como abordar essa forma de desenvolver software, que é muito nova.

Comparando código e especificação como fonte da verdade

Entre as metodologias possíveis, podemos começar falando do código como fonte da verdade. Ou seja, o código é a fonte. Essa era a forma como costumávamos operar antes de termos agentes de LLMs (Large Language Models, Modelos de Linguagem de Grande Porte) e antes de conseguirmos gerar código por meio de assistentes. Nesse modelo, sempre escrevemos o código, o código dita as regras, é o que está em produção e é a fonte da verdade.

Entretanto, estamos passando por uma mudança. Com os LLMs e com as IAs, agora temos a especificação. Passamos a criar documentação que descreve e especifica — por isso falamos em “spec” — o que queremos: quais funcionalidades, quais módulos, quais são as regras de negócio e como determinada funcionalidade deve comportar-se. A especificação torna-se a fonte da verdade, uma vez que o LLM pode ler essa especificação, interpretá-la e transformá-la em código.

No cenário ideal, geramos uma especificação bem detalhada, com todos os pormenores; o assistente lê e gera o código exatamente como queremos, atendendo a todas as regras definidas. Assim, a especificação passa a ser a fonte da verdade. Nesse ponto, ocorre uma mudança: saímos do modelo em que o código é a fonte da verdade, com a intervenção direta da pessoa profissional no código, para o modelo em que a especificação é a fonte da verdade, e a intervenção humana ocorre principalmente na especificação. A partir do momento em que isso estiver bem estruturado, uma das possibilidades é deixarmos de tocar no código: quem cuida de 100% dele é o nosso assistente, o LLM.

Apresentando a abordagem híbrida com spec anchor

No mundo real, porém, o que mais deve ocorrer hoje, especialmente se você é uma pessoa desenvolvedora, é algo intermediário. O código continua sendo a fonte da verdade, mas a especificação ainda dita muitos aspectos. É aqui que podemos falar de spec anchor (ancoragem na especificação). Isso não é necessariamente novo: quando começávamos uma feature (funcionalidade), normalmente havia uma pessoa PM, uma pessoa PO que definia a sprint (ciclo de desenvolvimento) conosco, esclarecia dúvidas, e uma pessoa BA fazendo análise de negócio e estabelecendo regras. Já existia uma série de estruturas ao redor do time de TI que forneciam as regras. Em alguns casos, precisávamos definir pontos durante o desenvolvimento, mas havia uma boa infraestrutura para criar documentação que descrevia as regras de negócio, e então seguíamos para a codificação como time de TI.

Esse spec anchor (ancoragem na especificação) é, em linhas gerais, isso: a especificação permanece junto ao código e é utilizada para evoluir o sistema, mantendo-se acoplada a ele, mas isso não impede intervenções diretas no código para modificar o que for necessário. Temos, portanto, os extremos:

• Código como fonte da verdade: mexemos apenas no código.
• Especificação como fonte da verdade: mexemos apenas na especificação.
• Ancoragem na especificação: fazemos as duas coisas em paralelo — criamos a especificação, pedimos ao LLM que gere o código, e realizamos alguns ajustes manuais por razões específicas.

Definindo especificação segundo Martin Fowler

Antes de discutir esses motivos, vamos definir o que é a especificação neste contexto. Vamos adotar a definição de Martin Fowler. Em seu blog, há um artigo sobre Spec-Driven Development (desenvolvimento orientado por especificação) com diversas observações. Ele propõe que uma especificação é uma estrutura ou artefato orientado a comportamento — podendo ser um conjunto de artefatos, não necessariamente um único documento — escrito em linguagem natural, que expressa e descreve a funcionalidade e serve de guia para agentes de código baseados em IA.

Portanto, quando falamos de especificação aqui, utilizamos essa definição de Martin Fowler para “spec”. Vale lembrar que, mesmo antes da IA, já existiam várias metodologias para gerar documentação: especificações técnicas, funcionais e não funcionais, análise de requisitos etc. Assim, quando falamos de “spec”, referimo-nos ao documento que servirá principalmente como guia para o nosso agente de IA.

Ele também aponta que existem variantes: cada variante de desenvolvimento orientado por especificação define seu próprio enfoque para essa estrutura. Não há, portanto, uma estrutura única, um senso comum consolidado, nem uma boa prática amplamente difundida que todas as pessoas sigam da mesma maneira. Há várias metodologias e abordagens para Spec-Driven Development, e cada uma define o nível de detalhe, a organização dos artefatos dentro do projeto e a própria estrutura desses artefatos. É uma definição ampla, mas, em resumo, quando falamos de “spec”, referimo-nos a qualquer documento que vai guiar nosso agente de código, escrito em linguagem natural e que descreva a funcionalidade do software.

Estruturando artefatos e contexto para o agente

No nosso dia a dia, teremos um cenário no qual o nosso assistente de IA está no meio do fluxo e precisa considerar alguns elementos — os artefatos. Assim como nós, ao escrever código, precisamos levar certos pontos em conta, o agente de IA também precisa. Podemos dividir esses pontos, de forma geral, em algumas categorias:

• Negócio.
• Arquitetura do sistema.
• Regras gerais ou políticas do sistema.

As regras podem ser, por exemplo, usar apenas esta stack (pilha) tecnológica.

Nossa stack (pilha) tecnológica é TypeScript, com React, com Jest para realizar testes, e vamos executar tudo em Docker quando for backend (camada de back-end). Nosso banco de dados será SQL.

Aqui estão as políticas; essas são as regras. A arquitetura define como esses elementos se comportam, como se comunicam entre si e como interagem. Portanto, tratamos da arquitetura do software. As necessidades de negócio serão as regras gerais. Para criar qualquer feature (funcionalidade), nosso agente deve considerar esses pontos.

Acima desse conjunto mais fixo — regras, necessidades e arquitetura, que não mudam com tanta frequência — teremos a especificação, que é o documento mencionado anteriormente. Ele descreve uma feature (funcionalidade) específica, um módulo concreto, uma área detalhada, em um nível menor, ou melhor, com maior nível de detalhe, dentro do projeto. A partir disso, geraremos nosso código, que pode ser tanto o código de testes quanto o código de execução em produção. Nosso assistente de IA, representado aqui no centro, precisa considerar todos esses elementos ao gerar o código, pois queremos que o sistema funcione corretamente. Esse será nosso agente. Esse agente partirá da especificação e gerará código.

Organizando memory bank e skills do sistema

As demais partes citadas — necessidades de negócio, arquitetura, políticas e regras — colocaremos no que hoje é chamado de memory bank (repositório de memória), que é basicamente o que fica do lado do harness (orquestrador), da Cloud (nuvem), do Gemini ou do Codex que estivermos usando. Também são documentos, mas, diferentemente da especificação, que descreve a funcionalidade do software, eles descrevem a arquitetura e regras mais gerais, restringindo o que o agente pode fazer. Assim, existe uma série de decisões tomadas antes da própria especificação, que guardamos nesse memory bank, que ficará do lado do harness.

Também teremos skills (habilidades). Se tivermos um processo padrão para fazer um PR (pull request), podemos ter uma skill (habilidade) para isso. Se tivermos um processo padrão, um template (modelo) de como uma feature (funcionalidade) deve ser descrita para que a especificação fique correta, podemos ter uma skill (habilidade) para isso. A arquitetura do sistema e as limitações que queremos impor como arquitetura podem ser registradas nesse documento. Vamos manter, em linhas gerais, essa separação de conceitos dentro do nosso sistema durante o desenvolvimento.

Nesse memory bank (repositório de memória), teremos a descrição e o objetivo do sistema, regras de arquitetura, a definição da stack (pilha) de trabalho, workflows (fluxos de trabalho) e templates (modelos) a serem utilizados. De modo geral, esses elementos permanecem nesse memory bank. Entretanto, cada pessoa ou cada abordagem que quisermos aplicar com Spec Driven (orientado por especificação) pode variar isso, adicionando ou removendo itens desse memory bank, dessa caixa de acessórios e artefatos, que nosso agente consultará ocasionalmente.

Enfrentando limitações e conflitos e definindo próximos passos

Teremos de lidar com problemas. Assim como já enfrentávamos problemas no desenvolvimento de software quando trabalhávamos diretamente com código — como transferência de informação entre equipes, desacoplamento, ou conhecimento de negócio centralizado em uma pessoa ou em um time dentro do sistema inteiro —, a manutenção se torna difícil porque o conhecimento não está distribuído por toda a equipe. Esses problemas que surgem quando escrevemos código diretamente em equipe também aparecem aqui ao lidar com a LLM (Large Language Model, Modelo de Linguagem Amplo), pois ela pode ter uma janela de contexto pequena. Embora a janela de contexto venha aumentando com os novos modelos, ela ainda pode ser insuficiente para o tamanho do código que estamos escrevendo ou para o tamanho da feature (funcionalidade) que estamos desenvolvendo.

Além disso, podemos ter má interpretação das regras de negócio por parte do agente. Ao escrevermos em linguagem natural — em português no nosso caso, mas em qualquer língua natural —, há ambiguidade e a possibilidade de termos descrito algo que foi mal interpretado. Na discussão sobre a sintaxe de linguagens de programação versus a forma como falamos e escrevemos em linguagem natural, existe uma diferença muito grande. É nesse ponto que muitas pessoas encontram dificuldades ao aprender programação, porque a sintaxe do código — em JavaScript, C#, ou qualquer linguagem — é muito estrita e feita para eliminar a ambiguidade, enquanto o idioma natural é cheio de ambiguidade e possibilidades de interpretação, não sendo tão exato. Há, portanto, uma discussão importante sobre como descrever e o que escrever para não sermos mal interpretados pelo agente.

Dave Farley, engenheiro de software, signatário de um manifesto e profissional experiente, tem um canal no YouTube sobre engenharia de software. Ele publicou um vídeo, já um pouco antigo — de cerca de um ano ou um ano e meio —, no qual aborda essa diferença entre linguagem de programação e linguagem natural; é um conteúdo muito interessante.

Podemos ter, ainda, regras conflitantes na forma como escrevemos nossos documentos, artefatos e especificações. Se o sistema for muito grande, podemos ter módulos com regras conflitantes; em um trecho do código podemos afirmar uma coisa, na especificação outra e, em outro lugar, algo diferente, gerando conflito. Como resolvemos conflitos nesse caso? Como fornecemos contexto suficiente para que nosso agente entenda se há, de fato, um conflito, ou se existe alguma separação implícita que nós, como pessoas, conhecemos do negócio e do sistema, e que faz com que não haja conflito? Se realmente houver conflito, precisamos lidar com ele.

Frequentemente deixamos coisas implícitas e não comunicamos tudo que o agente precisa. Ao trabalharmos em equipe, existe um conhecimento comum que facilita a comunicação; o jargão técnico de qualquer área também facilita isso. Uma palavra pode significar algo bem mais amplo e acelerar a comunicação. Esse conhecimento implícito, muitas vezes, esquecemos de comunicar à IA, porque a IA não o possui. Precisamos transmiti-lo e ser muito mais rigorosos ao escrever a especificação.

Vamos lidar com esses problemas. Temos uma série de abordagens diferentes para realizar Spec Driven (orientado por especificação). Agora, vamos analisar nossa base e definir o primeiro passo necessário para transformar uma base de código existente em algo Spec Driven (orientado por especificação) e, assim, desenvolver uma feature (funcionalidade) dentro dela.

Sobre o curso Spec Driven Development: desenvolvimento assistido por agentes

O curso Spec Driven Development: desenvolvimento assistido por agentes possui 166 minutos de vídeos, em um total de 37 atividades. Gostou? Conheça nossos outros cursos de IA para Programação em Inteligência Artificial, ou leia nossos artigos de Inteligência Artificial.

Matricule-se e comece a estudar com a gente hoje! Conheça outros tópicos abordados durante o curso:

• SDD na era da IA
• Definição de escopo
• Engenharia e gestão de contexto
• Implementação de código
• Testes e considerações