Skill-Driven Development: Como reduzimos 5 dias de trabalho para 4 horas com IA estruturada
Uma metodologia para transformar IA de copiloto em executor dentro de um sistema de engenharia
A IA sabe programar. Mas não conhece suas regras.
Imagine criar uma funcionalidade completa em uma aplicação corporativa. Não é um componente isolado — são 35 arquivos, distribuídos em 6 camadas arquiteturais, que precisam respeitar 12 convenções simultâneas. Entidade, interfaces de repositório, mapeamento de persistência, comandos, consultas, DTOs, controlador, modelos de formulário, validadores, views, módulos JavaScript, testes unitários.
Um desenvolvedor sênior faz isso em 5 dias. Não porque seja difícil, mas porque é meticuloso. São dezenas de decisões implícitas tomadas automaticamente pela experiência: “esse campo é um Value Object, preciso mapear como componente”; “essa busca textual precisa normalizar acentos dos dois lados”; “esse controlador não pode ter atributo anti-CSRF porque usamos Double Submit Cookie via AJAX”.
Quando pedimos para uma IA fazer o mesmo trabalho, ela gera código que funciona — mas viola metade dessas convenções. A IA não sabe que nosso ORM usa herança customizada. Não sabe que separamos repositórios de leitura e escrita. Não sabe que nossos formulários unificam criação e edição num único endpoint.
Essa é a promessa quebrada do vibe coding: velocidade imediata, dívida técnica exponencial.
A pergunta que nos fizemos foi diferente: como fazer a IA respeitar as regras da nossa equipe?
Cada erro virou uma restrição. Cada processo virou uma skill.
A resposta não veio de um planejamento top-down. Emergiu iterativamente, ao longo de meses de trabalho real com IA em produção.
O padrão era sempre o mesmo: a IA gerava código, revisávamos, encontrávamos um desvio das nossas convenções, e corrigíamos. Depois de corrigir o mesmo erro pela terceira vez, decidimos codificar a restrição num arquivo simples: “quando editar arquivos nesta pasta, siga estas regras”. A IA passou a respeitar.
Fizemos isso com cada camada. As regras dos controladores não são as mesmas das entidades. As regras dos comandos não são as mesmas das consultas. Cada camada ganhou seu próprio conjunto de restrições, carregado automaticamente quando a IA toca naquele tipo de arquivo.
Em paralelo, codificamos os processos repetitivos. Criar uma entidade segue sempre as mesmas fases: perguntar propriedades, detectar tipos especiais, verificar auditoria, gerar arquivos, registrar constantes, rodar build. Cada processo virou uma skill — um documento estruturado com fases obrigatórias, quality gates e checklist final.
Depois de 2 meses:
12 skills (processos codificados com fases obrigatórias)
13 rules (restrições por camada arquitetural)
22 documentos de referência (conhecimento detalhado sob demanda)
49 quality gates (checklist obrigatório antes de declarar pronto)
Resultado: 5 dias → 4 horas. Redução de 94%.
Não chamamos isso de “usar IA melhor”. Chamamos de Skill-Driven Development.
Os 5 Pilares do SDD
Skill-Driven Development (SDD) é uma metodologia de engenharia de software onde o conhecimento técnico é codificado em skills reproduzíveis — processos com fases obrigatórias, quality gates, adaptação parametrizada e enforcement automático por camada. A IA é o executor; as skills são o método.
- Codificação de Conhecimento Tácito
O ativo mais valioso de uma equipe não está no código — está na cabeça dos desenvolvedores seniores. São as centenas de decisões implícitas que eles tomam sem pensar.
O SDD transforma esse conhecimento em processos executáveis. Cada skill descreve fases obrigatórias (perguntas, leitura de referências, geração, validação), quality gates (build deve passar, testes devem cobrir todos os cenários) e checklist final (49 itens verificados antes de declarar pronto).
O resultado: um desenvolvedor júnior com acesso às skills produz código que segue exatamente as mesmas convenções que o sênior seguiria.
E não se limita a código. Em um dos projetos, estamos migrando uma aplicação Rails de 2013 para .NET 10 — o tipo de projeto que normalmente leva meses só de análise. Criamos uma skill de planejamento de migração: uma entrevista guiada de 8 fases que coleta tabelas do legado, classifica colunas, detecta dependências, e gera um documento de plano estruturado antes de tocar em qualquer código. A migração é feita em fases — feature por feature, não big bang. Cada feature legada, com suas regras de negócio enterradas há 13 anos, é analisada, planejada e implementada num fluxo contínuo. Até o processo de pensar foi codificado como skill.
- Progressive Disclosure
Modelos de linguagem têm uma janela de contexto finita. Carregar todo o conhecimento de uma vez causa compressão e perda de qualidade.
O SDD resolve com três camadas:
Camada 1: Metadata (sempre carregado) → 5 linhas
Camada 2: Corpo da skill (na invocação) → 50-130 linhas
Camada 3: Referências (sob demanda) → 200-500 linhas cada
A IA só carrega a Camada 3 quando realmente precisa. Uma skill de segurança, por exemplo, tem 94 linhas no corpo mas referencia 4 documentos que só são lidos quando o código apresenta padrões daquela categoria.
- Constraint-based Enforcement
Documentação passiva não funciona. O SDD usa restrições ativas que carregam automaticamente baseadas no arquivo sendo editado.
Cada regra tem um padrão de caminho. Quando a IA edita um arquivo que corresponde, as restrições carregam automaticamente:
Editou uma entidade? Regras de herança e Value Objects carregam
Editou um comando? Regras de CQRS e tipagem carregam
Editou um controlador? Regras de segurança e formulário carregam
São 13 guardiões automáticos, um por camada, que eliminam drift sem depender de memória.
- Replicabilidade Parametrizada
O maior teste de uma metodologia: funciona em outro contexto?
Uma skill especializada detecta 8 dimensões da arquitetura do projeto alvo (framework, padrão arquitetural, ORM, tipo de chave primária, frontend, injeção de dependência, testes, ferramentas de IA) e aplica um merge de 3 níveis:
Nunca tocar: artefatos próprios do projeto alvo
Merge preservando: adaptar mantendo customizações locais
Update seletivo: atualizar padrões defasados
Exportamos para dois projetos com arquiteturas diferentes. Em um, o padrão CQRS foi automaticamente adaptado para Service Layer. Cerca de 60 arquivos por exportação, todos adaptados.
- Orquestração com Isolamento
Criar uma funcionalidade gera 30+ arquivos. Se um único agente tenta tudo, após 15 arquivos o contexto comprime e a qualidade degrada.
O SDD divide em subagentes com escopo isolado:
Agente principal (orquestrador)
├── Subagente 1: Domínio + persistência
├── Subagente 2: Aplicação (comandos + consultas)
└── Subagente 3: Web (controlador + views + JS)
Cada um começa com contexto limpo. Para trabalho independente (testes), rodam em paralelo.
Onde o SDD se posiciona
O desenvolvimento assistido por IA é um espectro:
Zero restrições 100% rígido
| |
Vibe Coding Cursor Rules ★ SDD ★ Scaffolding Software Factories
AbordagemO que faz bemO que faltaVibe CodingVelocidade no protótipoSem padrões, dívida técnicaCursor RulesEnforcement básicoSem fases, sem processosAgentes autônomosAutonomia para issuesNão conhecem suas convençõesScaffoldingBoilerplate rápidoTemplate fixo, não adaptaSoftware Factories (MS, 2005)Visão de processosDSLs complexas, sem IA, morreram
As Software Factories tiveram a visão certa nos anos 2000: codificar padrões em processos reutilizáveis. Falharam por três razões: DSLs complexas, rigidez para variações, sem executor inteligente. O SDD resolve as três: Markdown em vez de DSLs, detecção automática de arquitetura, LLM como executor.
Retroalimentação contínua: cada exportação gerou lições que melhoraram o sistema original. Da primeira, 9 correções. Da segunda, mais 5. O sistema fica mais robusto a cada projeto.
Como começar: 3 passos
O SDD emergiu iterativamente e pode ser adotado da mesma forma:
Passo 1: Codifique 1 processo — Escolha o processo mais repetitivo. Documente com fases obrigatórias: perguntas, referências, execução, validação.
Passo 2: Adicione 2–3 restrições — Identifique as convenções mais violadas. Crie regras por camada com padrão de caminho.
Passo 3: Teste e itere — Execute com a IA. Cada desvio vira nova restrição. Em 2–3 sprints, os primeiros pilares funcionam.
Conclusão
A corrida por produtividade com IA está focada na ferramenta errada. Não é sobre qual modelo ou qual IDE. É sobre o que a IA sabe sobre o seu projeto.
A IA não precisa de mais contexto. Ela precisa de mais restrições.
O conhecimento tácito da sua equipe é o ativo mais valioso. Hoje ele existe na cabeça de pessoas que podem sair amanhã. O SDD transforma esse conhecimento em infraestrutura permanente — e de quebra, reduz 5 dias para 4 horas.