Esta é a segunda parte de um total de 5 artigos sobre Spec-Driven Development. Se estiver chegando agora, comece pela Parte 1.

Parte 2 – Anatomia de Uma Especificação Executável: EARS, GEARS e Markdown Estruturado

No contexto de SDD, a palavra “especificação” deixa de significar aquele documento estático, criado em um editor de texto, exportado em PDF e esquecido em alguma pasta do repositório. Ela passa a representar algo vivo. Um artefato que evolui junto com o software, que acompanha as decisões do time e que faz parte do próprio fluxo de desenvolvimento.

Uma especificação em SDD não fica isolada da implementação. Ela vive ao lado do código, no mesmo repositório, sob o mesmo controle de versão. É versionada com Git, o que garante rastreabilidade completa das mudanças, histórico claro de decisões e alinhamento contínuo entre intenção e execução. Mais do que isso, ela é estruturada para ser compreendida por pessoas e também por Agentes de Inteligência Artificial, funcionando como uma interface formal entre intenção humana e execução computacional.

Ferramentas como GitHub Spec Kit e Claude Code ilustram bem essa abordagem moderna. A especificação é organizada de forma hierárquica e rigorosa, conduzindo o raciocínio do abstrato ao concreto. Primeiro a intenção, depois os requisitos, em seguida os critérios e por fim os detalhes operacionais. Essa decomposição não é apenas estética. Ela reduz ambiguidade, preserva contexto e aumenta a fidelidade da implementação à intenção original.

Vamos compreender isso em mais detalhes.

Os Componentes Essenciais da Arquitetura SDD

A anatomia de um projeto SDD robusto compõe-se de múltiplos artefatos interligados, cada um com um propósito distinto na cadeia de comando da IA:

SPEC.md (A Definição da Intenção): Este documento define o “O Quê” e o “Porquê”. Ele encapsula as histórias de usuários, as regras de negócio fundamentais, os requisitos não funcionais (como SLAs de latência, padrões de segurança e conformidade) e os critérios de aceitação. O SPEC.md deve ser agnóstico em relação à implementação técnica específica, focando puramente no valor e no comportamento esperado.

PLAN.md (A Estratégia Técnica): Este artefato traduz a intenção abstrata do SPEC.md em decisões técnicas concretas. Ele define o “Como”. É aqui que se especificam o stack tecnológico, o esquema do banco de dados, as assinaturas das APIs, a estrutura de diretórios e as dependências de terceiros. O PLAN.md atua como a ponte entre o negócio e a engenharia, travando as decisões arquiteturais antes da codificação.

TASKS.md (A Execução Operacional): Derivada diretamente do plano, esta é uma lista de tarefas atômicas, sequenciais e verificáveis. Cada tarefa é projetada para ser pequena o suficiente para que um Agente de IA a execute com alta probabilidade de sucesso (single-shot ou few-shot) sem estourar sua janela de contexto ou capacidade de raciocínio.19

constitution.md (A Governança e Compliance): Um arquivo global ou específico do projeto que define as “leis imutáveis” que o agente deve obedecer em todas as suas ações. Exemplos incluem diretrizes como “Sempre utilize tipagem estrita em TypeScript”, “Nunca exponha segredos ou chaves de API no código cliente” ou “Prefira composição sobre herança”. Este documento funciona como um guardrail ético e técnico permanente.

Linguagens de Especificação: A Precisão de EARS e GEARS

Para que uma especificação seja processada com máxima eficiência e mínima ambiguidade por um LLM, a linguagem natural deve ser disciplinada.

A sintaxe EARS (Easy Approach to Requirements Syntax), originalmente desenvolvida na Rolls-Royce para a engenharia de sistemas aeroespaciais complexos, foi redescoberta e adaptada para o SDD como uma ferramenta poderosa para reduzir a variância na interpretação dos agentes.

Mais recentemente, a comunidade de engenharia de software evoluiu este conceito para o GEARS (Generalized Expression for AI-Ready Specs), uma adaptação do EARS otimizada especificamente para os padrões de tokenização e raciocínio lógico dos modelos de IA modernos.

Padrões EARS e GEARS na Prática

O uso de EARS/GEARS introduz palavras-chave gatilho que categorizam os requisitos, facilitando o “parsing” lógico pelo modelo de IA e permitindo a detecção automática de conflitos. A estrutura unificada do GEARS, por exemplo, segue o padrão: O <sujeito> deve <comportamento>.

A tabela abaixo ilustra como esses padrões transformam requisitos vagos em instruções precisas para agentes:

tabela2

A precisão sintática do EARS e do GEARS funciona efetivamente como uma “linguagem de programação para requisitos”. Isso permite que Agentes de IA avançados não apenas gerem código, mas também realizem análise estática da própria especificação, detectando conflitos lógicos (por exemplo, dois requisitos “Quando” que prescrevem comportamentos opostos para o mesmo gatilho) antes que uma única linha de código seja escrita.

Markdown Como a “Lingua Franca” da IA

A escolha quase universal do Markdown (arquivos .md) como formato padrão para SDD não é acidental nem meramente estética. O Markdown possui características técnicas que o tornam ideal para o consumo por LLMs:

  • Eficiência de Tokens: O Markdown consome significativamente menos tokens do que formatos estruturados verbosos como JSON, XML ou YAML para representar a mesma densidade de informação semântica, permitindo que mais contexto caiba na janela do modelo.
  • Hierarquia Semântica: O uso de cabeçalhos (#, ##, ###) cria uma árvore hierárquica natural que os modelos de atenção (Transformer) utilizam para ponderar a importância relativa das seções e entender o escopo.
  • Natureza Híbrida e Flexível: Permite a mistura fluida de linguagem natural (para intenção e nuance) com blocos de código estruturado, tabelas de dados e até diagramas declarativos (como Mermaid.js), que agentes modernos são capazes de interpretar tanto visualmente quanto textualmente.

O Papel Crítico dos Arquivos de Contexto (.ai, .cursorrules, memory)

Além dos documentos de especificação principais, o SDD moderno depende de uma infraestrutura de arquivos de suporte que funcionam como a “memória de longo prazo” e o contexto operacional do projeto.

Arquivos de Regras e Direcionamento: Ferramentas como o editor Cursor utilizam arquivos como .cursorrules para injetar instruções de sistema em cada prompt enviado ao modelo. No SDD avançado, o conteúdo desses arquivos não é estático; ele é derivado dinamicamente da constitution.md e do PLAN.md ativo, garantindo que o agente esteja sempre alinhado com as diretrizes vigentes.

Memory Banks (Bancos de Memória): Projetos como o Spec Kit implementam uma camada de “memória” explícita que armazena decisões arquiteturais passadas, lições aprendidas e preferências do usuário. Isso permite que o agente “aprenda” com erros anteriores sem a necessidade de reprocessar todo o histórico de conversação, simulando uma continuidade cognitiva.

Exemplo Prático: A Transformação de Algo Vago em Executabilidade

Para ilustrar a potência do SDD, considere um pedido inicial vago: “Crie uma app de lista de tarefas”. No fluxo de trabalho SDD, o agente (atuando sob a persona de um Arquiteto de Software) não começaria a codificar. Em vez disso, ele iniciaria um processo de entrevista para preencher o template SPEC.md:

Entrevista: O agente questiona: “A app deve suportar múltiplos usuários ou é local? Precisa funcionar offline? Qual é a prioridade crítica: velocidade de resposta ou consistência de dados?”

Geração e Formalização EARS: Baseado nas respostas, o agente gera requisitos formais:

  • Req 1 (Event-Driven): “Quando o usuário adicionar uma nova tarefa, o sistema deve salvá-la imediatamente no banco de dados local (SQLite) para garantir latência zero.”
  • Req 2 (State-Driven): “Enquanto houver conectividade de rede ativa, o sistema deve sincronizar as alterações do banco local com a API remota em segundo plano.”

Validação e Congelamento: O usuário revisa o SPEC.md gerado. Uma vez aprovado, este arquivo é “congelado” (frozen) e serve como input imutável para a fase subsequente de Planejamento.

Essa formalização transforma “vibes” e desejos abstratos em instruções computáveis e verificáveis, estabelecendo a fundação para uma implementação robusta.

Ou seja, documentamos conhecimento e especificação e usamos para automatizar a construção de aplicações com Agentes de IA. O conhecimento em Engenharia de Software se torna mais importante do que nunca!

Continuaremos na Parte 3.

Equipe DSA