Um dos padrões mais elegantes do desenvolvimento spec-driven é como ele usa a estrutura de arquivos e pastas do repositório como contrato de workflow legível por máquina. O Ruby on Rails popularizou a ideia de 'convenção sobre configuração' vinte anos atrás para aplicações web. O mesmo princípio, aplicado ao desenvolvimento orientado por agentes, transforma seu repositório num motor de workflow auto-descritivo.
A estrutura que emergiu nas implementações líderes (Spec Kit, Kiro e inúmeras configurações customizadas) segue um template consistente. Um diretório dedicado no repositório (tipicamente .sdlc/ ou .specs/) contém duas categorias de conteúdo:
Contexto de projeto: visão geral do propósito do sistema, stack tecnológico e limites. Registros de decisões de arquitetura documentando padrões e convenções. Padrões de codificação e regras de nomenclatura. Templates reutilizáveis para cada tipo de artefato que os agentes produzirão. Esse contexto se aplica globalmente a cada feature, cada sessão de agente, cada decisão. É o equivalente codificado do que um engenheiro sênior carrega na cabeça após anos num projeto.
Artefatos por feature: cada feature ou requisito ganha seu próprio subdiretório contendo a especificação de requisito, propostas de arquitetura específicas, e um subdiretório de especificações de tarefas de implementação. Tudo relacionado a uma única feature vive num único local.
O que eleva isso de mera organização para genuína engenharia de workflow é que os padrões de nomeação e hierarquia de diretórios codificam informação que a camada de controle usa para operar. A engine sabe quais arquivos se aplicam globalmente e quais são escopados por feature. Pode identificar relações pai-filho entre requisitos e tarefas pelo parsing da árvore de diretórios. Valida completude automaticamente: todos os critérios de aceite estão cobertos por pelo menos uma tarefa? Computa o que pode rodar em paralelo versus sequencial. E previne transições prematuras: um requisito não pode ser marcado como completo se qualquer tarefa constituinte ainda está em andamento.
Rastreabilidade como Propriedade Estrutural
Cada artefato carrega linkagem explícita em seus metadados (tipicamente cabeçalhos YAML embutidos em arquivos markdown). Uma especificação de tarefa identifica qual requisito implementa. Um commit identifica qual tarefa cumpre. Uma proposta de arquitetura referencia o requisito que a motivou.
Isso cria o que chamo de 'rastreabilidade por construção' em vez de 'rastreabilidade por documentação'. A cadeia de auditoria existe porque a estrutura exige, não porque alguém lembrou de anotar. Nas indústrias em que trabalho (mineração, energia, serviços financeiros), reguladores querem entender não apenas o que foi construído mas a cadeia de raciocínio que levou a cada decisão. Quando seu workflow produz essa cadeia como subproduto natural, compliance deixa de ser um workstream separado.
Vi o valor disso mais claramente durante uma revisão de governança para um cliente de recursos naturais. Quando auditores perguntaram por que um determinado pipeline de dados usava uma abordagem de processamento em vez de outra, o time conseguiu rastrear do código implantado à spec da tarefa, da tarefa ao requisito, e do requisito à proposta de arquitetura onde o agente documentou sua racionalização e as alternativas consideradas. Essa rastreabilidade existia não porque alguém sentou e criou para a auditoria. Existia porque o workflow de desenvolvimento a produziu automaticamente.
Existe um princípio mais profundo aqui que conecta com como sempre pensei sobre plataformas de dados e arquitetura de analytics. Quando eu construía plataformas de dados empresariais na Austrália uma década atrás, a lição mais difícil era que o valor da plataforma não estava no stack tecnológico. Estava na camada de metadados: dicionários de dados, rastreamento de linhagem, regras de qualidade e políticas de governança que tornavam os dados confiáveis e reutilizáveis. Retire essa camada e você tem um data lake caro que ninguém confia. O mesmo princípio se aplica ao desenvolvimento orientado por agentes. As especificações, convenções e registros de arquitetura são a camada de metadados da sua fábrica de software.
O relatório Qodo 2025 de AI Code Quality fornece suporte quantitativo. Equipes usando processos estruturados de revisão de código por IA viram melhorias de qualidade saltarem para 81 por cento (contra 55 por cento sem estrutura). Um estudo separado da Atlassian mostrou que quase 39 por cento dos comentários deixados por agentes de IA em revisões de código levaram a correções reais.
Este artigo é de O SDLC Agêntico por Carlos Aggio.