Spec-driven development vale a pena? Lições inesperadas de quem testou as principais ferramentas

O hype em torno da IA generativa para desenvolvimento de software continua evoluindo, e um novo termo ganhou força em 2024: Spec-driven development (SDD). Mas o que exatamente isso significa? E mais importante: vale a pena adotar essa abordagem em seus projetos?

Neste artigo, vamos explorar três ferramentas que prometem revolucionar o desenvolvimento com IA através de especificações: Kiro, spec-kit e Tessl Framework. Spoiler: a realidade é bem mais complexa do que o marketing sugere.

O que é spec-driven development?

Spec-driven development é uma abordagem onde você escreve uma "spec" (especificação) detalhada antes de codificar com IA. A ideia central é que essa spec se torna a fonte da verdade tanto para desenvolvedores quanto para os agentes de IA.

Segundo o GitHub: "Neste novo mundo, manter software significa evoluir especificações. […] A língua franca do desenvolvimento se move para um nível mais alto, e o código é a abordagem de última milha."

A Tessl define de forma ainda mais ambiciosa: "Uma abordagem de desenvolvimento onde specs — não código — são o artefato principal. Specs descrevem intenção em linguagem estruturada e testável, e agentes geram código para corresponder a elas."

Três níveis de implementação

Após analisar as diferentes ferramentas e suas propostas, podemos identificar três níveis distintos de SDD:

1. Spec-first: Uma especificação bem pensada é escrita primeiro e usada no fluxo de trabalho assistido por IA

2. Spec-anchored: A spec é mantida mesmo após a tarefa ser concluída, para evolução e manutenção contínua da feature

3. Spec-as-source: A spec é o arquivo fonte principal ao longo do tempo, apenas ela é editada pelo desenvolvedor, que nunca toca diretamente no código

Nem todas as ferramentas aspiram aos três níveis, e muitas deixam vago qual é a estratégia de manutenção de specs ao longo do tempo.

O que é uma spec, afinal?

Esta é a pergunta fundamental. A definição mais próxima de um consenso que encontramos compara uma spec a um "Documento de Requisitos de Produto" (PRD).

Nossa definição proposta: Uma spec é um artefato estruturado, orientado a comportamento - ou conjunto de artefatos relacionados - escrito em linguagem natural que expressa funcionalidade de software e serve como orientação para agentes de IA.

É importante diferenciar specs de documentos de contexto geral. Contexto geral inclui arquivos de regras ou descrições de alto nível do produto e da base de código. Algumas ferramentas chamam isso de memory bank (banco de memória). Esses arquivos são relevantes em todas as sessões de codificação, enquanto specs são específicas para tarefas que criam ou modificam funcionalidades específicas.

Kiro: simplicidade pode ser demais ou de menos

Kiro é a ferramenta mais leve das três analisadas. Ela parece ser principalmente spec-first, com exemplos focados em tarefas ou user stories individuais, sem menção clara de como usar o documento de requisitos de forma spec-anchored ao longo do tempo.

Workflow do Kiro

Requirements → Design → Tasks

Cada etapa é representada por um documento markdown, e o Kiro guia você através dessas três etapas dentro de sua distribuição baseada no VS Code.

Requirements (Requisitos): Estruturados como lista de requisitos, onde cada um representa uma "User Story" (no formato "Como um...") com critérios de aceitação (em formato "DADO... QUANDO... ENTÃO...")

Design: Documento de design com seções estruturadas dependendo da tarefa

Tasks (Tarefas): Lista de tarefas que traçam de volta aos números dos requisitos, com elementos extras de UI para executar tarefas uma por uma

O Kiro também possui o conceito de memory bank, que eles chamam de "steering" (direcionamento). Seu conteúdo é flexível, e o workflow não depende de arquivos específicos. A topologia padrão inclui: product.md, structure.md, tech.md.

O problema do sledgehammer

Quando tentei usar o Kiro para corrigir um bug pequeno, rapidamente ficou claro que o workflow era como usar uma marreta para quebrar uma noz. O documento de requisitos transformou esse pequeno bug em 4 "user stories" com um total de 16 critérios de aceitação, incluindo pérolas como: "User story: Como desenvolvedor, quero que a função de transformação lide com casos extremos graciosamente, para que o sistema permaneça robusto quando novos formatos de categoria são introduzidos."

Para bugs simples ou mudanças pequenas, o Kiro adiciona complexidade desnecessária ao invés de simplificar o processo.

Spec-kit: ambição do GitHub com realidade confusa

Spec-kit é a versão do GitHub de SDD. É distribuído como uma CLI que pode criar configurações de workspace para diversos coding assistants comuns. Uma vez configurado, você interage com o spec-kit via comandos slash no seu assistente de codificação.

Workflow do spec-kit

Constitution → 𝄆 Specify → Plan → Tasks 𝄇

O conceito de memory bank do spec-kit é um pré-requisito para a abordagem spec-driven. Eles chamam isso de constitution (constituição). A constitution contém os princípios de alto nível que são "imutáveis" e devem sempre ser aplicados a cada mudança. É basicamente um arquivo de regras muito poderoso usado intensamente pelo workflow.

Em cada etapa (specify, plan, tasks), o spec-kit instancia um conjunto de arquivos e prompts usando scripts bash e templates. O workflow faz uso pesado de checklists dentro dos arquivos para rastrear esclarecimentos necessários, violações da constitution, tarefas de pesquisa, etc.

Topologia de arquivos complexa

Uma única spec no spec-kit é composta por múltiplos arquivos:

• Arquivos de especificação

• Documentos de planejamento

• Listas de tarefas detalhadas

• Checklists de validação

• Notas de pesquisa

À primeira vista, o GitHub parece aspirar a uma abordagem spec-anchored. No entanto, o spec-kit cria uma branch para cada spec criada, o que indica que eles veem uma spec como um artefato vivo durante o tempo de vida de uma solicitação de mudança, não o tempo de vida de uma feature.

A realidade do review

O spec-kit criou MUITOS arquivos markdown para revisar no meu teste. Eles eram repetitivos, tanto entre si quanto com o código que já existia. Alguns já continham código. No geral, eram muito verbosos e tediosos para revisar.

Para ser honesto: prefiro revisar código do que todos esses arquivos markdown.

Tessl Framework: a aposta mais ousada (e arriscada)

(Ainda em beta privado)

Como o spec-kit, o Tessl Framework é distribuído como uma CLI que cria toda a estrutura de workspace para diversos coding assistants.

O Tessl é a única das três ferramentas que explicitamente aspira a uma abordagem spec-anchored, e está até explorando o nível spec-as-source de SDD. Uma spec Tessl pode servir como o artefato principal que é mantido e editado, com o código até marcado com um comentário no topo dizendo // GENERATED FROM SPEC - DO NOT EDIT.

Exemplo de spec Tessl

@generate
Component: UserProfileManager

@purpose
Manages user profile data and operations

@api
class UserProfileManager {
  getUserProfile(userId: string): Promise<UserProfile>
  updateUserProfile(userId: string, data: Partial<UserProfile>): Promise<void>
}

@test
- Should retrieve user profile by ID
- Should update user profile with valid data
- Should throw error for invalid user ID

@behavior
- Cache user profiles for 5 minutes
- Validate all profile updates before saving
- Log all profile access attempts

Tags como @generate ou @test indicam ao Tessl o que gerar. A seção API mostra a ideia de definir pelo menos as interfaces expostas para outras partes da codebase na spec.

O problema do MDD revisitado

Colocar as specs para spec-as-source em um nível de abstração bastante baixo, por arquivo de código, provavelmente reduz a quantidade de etapas e interpretações que o LLM precisa fazer. Mesmo neste nível baixo de abstração, o não-determinismo é visível quando você gera código múltiplas vezes da mesma spec.

Isso nos lembra do Model-Driven Development (MDD) do passado. Os modelos em MDD eram basicamente specs, embora não em linguagem natural, mas expressos em UML customizado ou DSL textual. Construíamos geradores de código customizados para transformar essas specs em código.

MDD nunca decolou para aplicações de negócio porque criava overhead e constraints demais. LLMs removem parte desse overhead, mas o preço é o não-determinismo. E a estrutura parseável do MDD também tinha vantagens: podíamos fornecer muito suporte de ferramentas para escrever specs válidas, completas e consistentes.

Spec-as-source pode acabar com as desvantagens tanto do MDD quanto dos LLMs: inflexibilidade E não-determinismo.

Observações críticas sobre SDD

Um workflow para todos os tamanhos?

Kiro e spec-kit fornecem um workflow opinativo cada, mas nenhum deles parece adequado para a maioria dos problemas de codificação da vida real. Em particular, não está claro como eles atenderiam a diferentes tamanhos de problemas para serem geralmente aplicáveis.

Falsa sensação de controle?

Mesmo com todos esses arquivos, templates, prompts, workflows e checklists, frequentemente vi o agente não seguir todas as instruções. Sim, as janelas de contexto agora são maiores, o que é frequentemente mencionado como um dos habilitadores do spec-driven development. Mas só porque as janelas são maiores não significa que a IA vai captar adequadamente tudo que está lá.

Exemplo real: O spec-kit fez muita pesquisa sobre código existente, o que foi ótimo. Mas no final, o agente ignorou as notas de que eram descrições de classes existentes e as gerou novamente, criando duplicatas.

Quem é o usuário-alvo?

Muitas demos e tutoriais de ferramentas spec-driven development incluem coisas como definir metas de produto e feature, até incorporam termos como "user story". A ideia aqui pode ser usar IA como habilitador para cross-skilling, fazendo desenvolvedores participarem mais pesadamente na análise de requisitos?

Mas isso não é explicitado. É apresentado como dado que um desenvolvedor faria toda essa análise. E isso levanta questões sobre para qual tamanho e tipo de problema o SDD é destinado.

Conclusões: hype vs realidade

Em meu uso pessoal de codificação assistida por IA, também frequentemente passo tempo elaborando cuidadosamente alguma forma de spec primeiro para dar ao agente de codificação. Então o princípio geral de spec-first é definitivamente valioso em muitas situações, e as diferentes abordagens de como estruturar essa spec são muito procuradas.

Questões essenciais ainda sem resposta

1. Como lidar efetivamente com diferentes tamanhos de problemas? Nenhuma das ferramentas parece ter encontrado o equilíbrio certo

2. Specs vs código: o que é mais fácil de revisar e manter? Minha experiência sugere que código ainda ganha

3. Como separar spec funcional de técnica? A confusão persiste mesmo com ferramentas dedicadas

4. Spec-anchored realmente funciona na prática? Faltam casos de uso de longo prazo em codebases reais

5. Estamos amplificando problemas existentes? Review overload e alucinações podem piorar

O problema da difusão semântica

O termo "spec-driven development" ainda não está bem definido, e já está semanticamente difuso. Recentemente ouvi pessoas usando "spec" basicamente como sinônimo de "prompt detalhado".

Verschlimmbesserung: melhorando para pior?

Especialmente com as abordagens mais elaboradas que criam muitos arquivos, não posso deixar de pensar na palavra composta alemã "Verschlimmbesserung": estamos piorando algo na tentativa de melhorá-lo?

FAQ sobre Spec-Driven Development

P: Devo adotar spec-driven development agora?
R: Depende. Para features grandes e complexas em projetos greenfield, pode valer a experimentação. Para manutenção diária e bugs pequenos, provavelmente adiciona overhead desnecessário.

P: Qual ferramenta escolher: Kiro, spec-kit ou Tessl?
R: Cada uma tem trade-offs. Kiro é mais simples mas limitado. Spec-kit é ambicioso mas verboso. Tessl é inovador mas ainda em beta. Teste com casos de uso reais antes de comprometer.

P: Spec-driven é o futuro do desenvolvimento?
R: É cedo para dizer. As ferramentas estão evoluindo rapidamente, mas ainda há questões fundamentais sobre escalabilidade, manutenibilidade e adequação a diferentes tipos de problemas.

P: Specs substituem testes?
R: Não. Specs descrevem intenção e comportamento esperado, mas testes ainda são essenciais para validação e regressão.

P: Como começar com SDD sem ferramentas dedicadas?
R: Comece praticando spec-first: escreva documentos de contexto detalhados e requisitos estruturados antes de pedir ao seu coding assistant para implementar. Use markdown simples e itere baseado no feedback.

Conclusão final: Spec-driven development é uma ideia promissora, mas as implementações atuais ainda estão encontrando seu lugar. A abordagem spec-first tem valor comprovado, mas os níveis spec-anchored e spec-as-source levantam questões sobre complexidade, manutenibilidade e se estamos realmente resolvendo os problemas certos. Vale a pena experimentar, mas com expectativas realistas e consciência das limitações.