Lições Práticas do Uso de Agentes de IA em uma Base de Código de 100k LOC

Seis Técnicas Concretas para Desenvolvimento em Larga Escala Assistido por IA

Um desenvolvedor recentemente documentou sua experiência usando agentes de IA (Claude Code + Cursor) para construir uma camada de API compatível com pandas sobre o motor analítico chDB. O projeto envolveu alinhar mais de 600 métodos entre dois sistemas e custou aproximadamente US$ 20 mil em tokens. Aqui estão as lições específicas e acionáveis que eles compartilharam.

Detalhes Principais da Implementação

• Manter um arquivo de regras CLAUDE.md: Como a IA não tem memória entre sessões, eles cometeram um arquivo de regras ao repositório contendo cada padrão que a IA continuava errando, cada atalho que eles proibiram e cada decisão arquitetônica que foi estabelecida. Isso também serviu como interface de colaboração da equipe. Eles alertam contra deixar esse arquivo se tornar um "manifesto de 500 linhas" que a IA começará a ignorar.
• Observe o raciocínio, não apenas a saída: Nos estágios iniciais, ler como a IA pensa é mais valioso do que o que ela entrega. Quando sua lógica se afasta da sua, pergunte: meu pensamento estava errado ou simplesmente não o comuniquei adequadamente?
• Use periodicamente um agente sem contexto como crítico: Eles começaram a usar um agente novo (claude.ai/code, não o CLI do Claude Code) sem memória do projeto para avaliar seu trabalho da perspectiva de um observador externo crítico e racional. Duas palavras-chave importam: crítico (substitua o modo acomodador padrão da IA) e racional (exija raciocínio estruturado, não sensações).
• Use o sistema alvo como oráculo de teste: Como seu objetivo era corresponder a uma API existente, eles encontraram código real em uso (notebooks do GitHub/Kaggle), trocaram uma linha de importação e compararam as saídas em vez de inventar casos de teste.
• Regras sobre prompts: Eles observaram como a IA toma atalhos e escreveram proibições explícitas. Por exemplo: quando os testes falhavam devido a incompatibilidade na ordem das linhas, o movimento favorito da IA era adicionar .sort_values() para fazer o teste passar. Eles proibiram isso explicitamente. Casos que genuinamente não podem ser correspondidos são marcados como XFAIL, nunca silenciosamente ignorados.
• Sistema de arquivos sobre histórico de conversa para pipelines multiagente: Eles orquestram fluxos de trabalho multiagente com scripts Python onde o sistema de arquivos é a camada de contexto compartilhada. Cada agente escreve seu trabalho em um diretório de rastreamento, e o próximo lê o que precisa. Padrões-chave que funcionaram: separação de funções, decisões estruturadas (APROVAR/REJEITAR/ESCALAR como JSON para fluxo de controle determinístico) e reversão automática do git em caso de falha.

O desenvolvedor observa que a IA se destaca em trabalhos em escala - alinhar centenas de funções, gerar milhares de testes, capturar regressões - mas o julgamento ("isso é um bug ou uma funcionalidade? A arquitetura está correta?") permanece responsabilidade do humano.