Lições Práticas da Construção de uma Base de Código de 350 Mil Linhas em Solitário com Agentes de IA

Ambiente de Engenharia como Contexto

O projeto de 52 dias do desenvolvedor (600 commits, ~965 mil linhas de código processadas, 356 mil linhas de código de produção) revelou que a qualidade da saída dos agentes depende criticamente do ambiente de engenharia, não apenas do modelo. A própria base de código serve como sistema de contexto do agente, eliminando a necessidade de arquivos separados de RAG ou memória.

Limites arquiteturais claros provaram ser essenciais. A base de código segue uma camada DDD rigorosa: camada de domínio para estruturas de dados, camada de serviço para lógica de negócios, camada de handler para conversão de formato HTTP, com 22 módulos de domínio tendo limites claros. Isso diz aos agentes onde fazer alterações.

A estrutura de diretórios funciona como documentação com alinhamento de nomenclatura entre stacks. Para um recurso como "Loop": backend/internal/domain/loop/ para estruturas de dados, backend/internal/service/loop/ para lógica, web/src/components/loops/ para frontend. Este mapeamento direto do conceito do produto para o caminho do código elimina a necessidade de os agentes explorarem toda a base de código.

Amplificação de Dívida Técnica

A dívida técnica se espalha exponencialmente com agentes de IA. Quando os desenvolvedores fazem compromissos temporários — contornando a camada de serviço para consultar o banco de dados diretamente ou usando números mágicos hardcoded — os agentes reutilizam sistematicamente esses padrões como abordagens legítimas. Diferente de engenheiros humanos que reconhecem código ruim como minas terrestres, os agentes tratam padrões existentes como precedentes válidos.

A lição prática: a refatoração regular se torna essencial não por estética, mas para manter a pureza do sinal de engenharia. Quando boas práticas dominam, os agentes amplificam boas práticas; quando atalhos dominam, os agentes amplificam atalhos. Isso representa um custo de manutenção único no desenvolvimento colaborativo com agentes.

Tipagem Forte como Portão de Qualidade

Usar Go + TypeScript + Proto fornece detecção de erros em tempo de compilação que desloca os erros dos agentes do tempo de execução para o tempo de desenvolvimento. Funções geradas por agentes com assinaturas incompatíveis causam falhas de build. TypeScript detecta incompatibilidades de formato de API imediatamente. Código gerado por Proto não compila se os formatos de mensagem mudarem sem sincronização do backend. Esses erros passariam despercebidos para o tempo de execução em linguagens fracamente tipadas.

Sistema de Feedback de Quatro Camadas

Agentes precisam de quatro camadas de feedback para iteração eficiente:

• Compilação — hot-reload, reinícios do Go em menos de 1 segundo, erros de tipo do TypeScript sinalizados em tempo real. Elimina erros de sintaxe e tipo.
• Testes unitários — 700+ testes cobrindo camadas de domínio e serviço. Agentes sabem em 5 minutos se introduziram regressões, especialmente para condições de limite como isolamento multi-inquilino.
• Testes E2E — validação end-to-end de caminhos funcionais reais. Captura problemas de integração que os testes unitários não alcançam.
• Pipeline de CI — cada PR executa suíte completa de testes, linting, verificação de tipos, build multi-plataforma. A rede de segurança final antes do merge.

As quatro camadas fornecem latência crescente e cobertura expandida: a primeira camada confirma alterações de linha única, enquanto a quarta camada valida refatoração entre módulos.