Especificações: Escreva uma vez, rode em qualquer lugar

Disclaimer

Este texto foi inicialmente concebido pela IA Generativa em função da transcrição de um vídeo do canal Dev + Eficiente. Se preferir acompanhar por vídeo, é só dar o play.

Introdução

Na era dos LLMs acessíveis, uma mudança fundamental(há anos desejada) está acontecendo na forma como desenvolvemos software. Uma vez que sabemos o que queremos fazer, em vez de sair codando o que é necessário, podemos guiar o agente baseado em LLM para realizar o bootstrap do código e deixar para nós apenas os refinamentos.

Neste post, vou mostrar como tenho aplicado essa abordagem em projetos reais e o setup que tem funcionado muito bem para mim.

A Nova Dinâmica: Especificação Antes do Código

Antes, após passar pelo processo de engenharia de requisitos - levantamento, alinhamento com stakeholders, refinamento para descobrir o valor real - você tinha que sair codando tudo manualmente.

Agora, você ainda precisa codar, mas parte significativa desse código pode ser produzida por agentes de código como Claude Code ou similares.

O Trabalho Que Vem Antes Do Código

A fase de engenharia de requisitos sempre foi importante para acelerar entregas(sim, acelerar!) e diminuir custos, mas ainda é subestimada. Essa fase envolve:

Levantamento de requisitos
Alinhamento com stakeholders e clientes
Refinamento para descobrir o valor real
Entendimento do "por que" por trás de cada funcionalidade

Agora, com LLMs, essa fase se torna ainda mais crucial porque a qualidade da especificação influencia diretamente o passo extra de tentar traduzir a especificação de negócio para algo mais próximo do código e possa guiar o agente.

Meu Setup Atual

Não considero isso um setup definitivo, mas sim incremental, baseado na minha experiência como usuário dessas ferramentas. Com esse setup, já consegui codar:

Dois serviços completos do zero
Um app para WhatsApp de controle financeiro
Um serviço de análise de atividades da plataforma Dev + Eficiente
Um curso completo criado através de LLM, escrevendo especificações dos capítulos

A Metodologia: Especificações Como Legado

Criando Arquivos de Especificação

Ao invés de colocar tudo direto no prompt, escrevo especificações em arquivos de texto. Isso cria um histórico valioso por várias razões:

Legado para novas pessoas: Facilita o entendimento do que foi feito. Aqui, além de termos o legado de cartões lá no board, podemos ter agora especificações de código versionadas no repositório.
Pesquisabilidade: Permite buscar por decisões e implementações passadas. Se você tratar a especificação como algo imutável, isso fica legal demais.
Consumo por LLMs: Tudo que produzimos pode ser consumido por programas que utilizam LLMs
Rastreabilidade: Mantém a linha de raciocínio que gerou determinado código. Algo que sempre quis.

Estrutura Base: O meu arquivo CLAUDE.md

Uso um arquivo de contexto padrão que inclui:

Preferência por português em comentários
Padrões de design que considero importantes
Padrões para escrita de testes
Padrões para logs

Especificações Detalhadas

Para cada tarefa, crio uma especificação que inclui:

Objetivo: O que exatamente quero implementar
Local do código: Onde deve ser criado
Referências: APIs, documentações, exemplos relevantes
Detalhes de implementação: Nível de especificidade baseado na complexidade

Exemplos Práticos

Tarefa Simples: Importação de Cursos

Para uma tarefa básica de importar cursos da plataforma que utilizamos para entregar a Jornada Dev + Eficiente, especifiquei:

A API de listagem a ser consumida
A documentação de referência
Que deveria importar apenas cursos não importados anteriormente
Que precisava apenas do ID e nome do curso
Que deveria escrever os testes para o controller.

Tarefa Complexa: Importação de Atividades

Para uma tarefa mais elaborada de importar atividades de alunos, fui muito mais específico:

Defini o design da solução com abstrações claras
Especifiquei uma estrutura de "processo de importação" como controlador principal
Detalhei tarefas específicas para cada aluno como filhas do processo principal
Incluí controle de status para continuidade em caso de problemas
Especifiquei formatos de retorno e estruturas de dados

O Nível de Especificidade

A quantidade de detalhes que você fornece depende de alguns fatores:

Quanto contexto você tem: Conhecimento do domínio e tecnologias
O quanto aceita sugestões: Disposição para iterar vs. acertar na primeira
Proximidade do resultado final: O quanto consegue imaginar da implementação inteira

Para minimizar iterações, não basta apenas falar de padrões de design. É necessário quebrar as informações e dar direcionamento específico para que o código saia próximo do que tenho em mente.

Trabalhando em Conjunto, Não Delegando

Existe uma diferença importante entre delegar completamente o raciocínio (que considero nocivo) e trabalhar em conjunto com o LLM. O processo envolve:

Planejamento: Pedir para o LLM criar um plano baseado na especificação
Implementação guiada: Acompanhar a implementação e ajustar conforme necessário
Refinamento: Preencher lacunas que não foram bem especificadas
Iteração: Ajustar partes que você ainda estava descobrindo durante a especificação

Resultados na Prática

O padrão que mais tenho observado é que o LLM:

Implementa tudo com código aceitável, ou
Faz um bootstrap interessante que precisa de ajustes pontuais

Do ponto de vista de tempo versus código que gera valor, sinto que consigo utilizar melhor meu tempo com ferramentas como Claude Code. Me sinto mais capaz de:

Ser veloz na implementação
Codar coisas que sei o que quero mas não sei os detalhes técnicos
Trabalhar com bibliotecas e frameworks. Por mais que você domine, alguns são muito grandes e sempre escapa coisas.
Focar no que realmente importa: a lógica de negócio e arquitetura

Mantendo o Histórico de Trabalho

Uma prática interessante é usar o comando /export do Claude para exportar sessões de trabalho. Isso permite:

Revisitar sessões de trabalho
Entender como estou evoluindo no processo
Refletir sobre a colaboração com o LLM
Manter registro das decisões tomadas

Conclusão

A mudança de paradigma de "começar codando" para "começar especificando o código" representa uma evolução natural no desenvolvimento de software. Não se trata de substituir o desenvolvedor, mas de potencializar sua capacidade de entrega.

Jornada Dev+ Eficiente

Se você gostou deste conteúdo, conheça a Jornada Dev + Eficiente, nosso treinamento focado em fazer com que você se torne uma pessoa cada vez mais capaz de entregar software que gera valor na ponta final, com máximo de qualidade e eficiência.

Acesse https://deveficiente.com/oferta-20-por-cento para conhecer tudo que oferecemos.