Como Manter Agentes de IA no Código Sob Controle: A Estratégia de Git Hooks que Dá Certo

A IA está revolucionando o desenvolvimento. Ferramentas como Claude ou Copilot criam features completas em instantes. Mas sem freios, elas geram dívida técnica aos montes. Arquivos gigantes de 2000 linhas ou lógicas recursivas malucas transformam seu repositório em um caos. Sua equipe vai te odiar.

A saída? Git hooks compartilhados que bloqueiam código ruim antes de entrar no repo.

O Caos dos Agentes de IA Sem Limites

Sem regras, esses agentes soltam:

• Arquivos inchados que ignoram o princípio de responsabilidade única
• Lógicas complicadas que tornam o debug uma caça ao tesouro
• Commits bagunçados que deixam o histórico do Git ilegível
• Burlas fáceis com --no-verify para pular verificações

Eles querem ajudar, mas priorizam velocidade em vez de qualidade.

Git Hooks: Sua Barreira de Qualidade

Hooks do Git são scripts automáticos que rodam em pontos chave do fluxo. São como porteiros que filtram o que entra.

Duas opções top:

1. pre-commit — Padrão para times Python ou mistos, funciona em qualquer linguagem

2. husky — Perfeito para JS, integra com npm e é super simples

Exemplo prático de configuração:

Regras Essenciais para Agentes de IA

# Config de pre-commit
repos:
  - repo: local
    hooks:
      - id: limite-linhas
        name: Verifica tamanho do arquivo
        entry: python -c "import sys; sys.exit(0 if len(open(sys.argv[1]).readlines()) <= 600 else 1)"
        language: system
        types: [python]
      
      - id: complexidade
        name: Limite de complexidade McCabe
        entry: flake8 --max-complexity=10
        language: system
        types: [python]

Por que esses limites?

• 600 linhas por arquivo — Bloqueia dumps, mas permite arquivos legítimos complexos
• Complexidade McCabe 10 — Garante funções fáceis de testar e entender

Se o agente violar, o hook falha. Sem commit. Hora de refatorar na hora.

Ferramentas que os Agentes Precisam Dominar

Para passar nos hooks, eles precisam refatorar sozinhos:

Python: rope refaz tudo — extrai funções, renomeia vars, divide módulos. Automático e poderoso.

TypeScript/JS: ts-morph mexe no AST para refatorações precisas. Agentes corrigem a própria bagunça.

É código programático, não trabalho manual.

A "Constituição" dos Agentes: Suas Regras Claras

Crie um AGENTS.md no repo como manual oficial:

# Regras para Agentes de Desenvolvimento

## Commits Impecáveis
- Commits descritivos em intervalos lógicos (nada de um mega-commit por tarefa)
- Inclua tickets e explique *o quê* e *por quê*
- Exemplo: "feat(login): Implementa rotação de token OAuth2 [#456]"

## Instalação de Hooks
- Rode `git config core.hooksPath .husky` (ou equivalente)
- Instale antes do primeiro commit
- Teste local antes de push

## Regra de Ouro
- **NUNCA use `--no-verify` sem confirmação explícita do usuário**
- Isso pula todos os checks — justifique por escrito

## Abordagem de Código
- TDD puro: Teste vermelho → Verde → Refatorar
- Escreva o teste falhando primeiro
- Faça passar
- Limpe e otimize
- Arquitetura boa surge natural.

Regras claras turbinam o desempenho dos agentes.

Por Que Isso Muda o Jogo para Sua Equipe

Desenvolvedores humanos já sofrem com código ruim. Com hooks:

✅ Confiança total — Main branch só recebe código decente

✅ Reviews mais rápidos — Foco em lógica, não em bagunça básica

✅ Onboarding fácil — Novatos veem o padrão na prática

✅ Agentes evoluem — Aprendem o que rola e geram melhor

Checklist para Implementar

1. Escolha o framework — pre-commit pro Python, husky pro JS (ou os dois)

2. Defina limites realistas — 600 linhas e complexidade 10 são bons starts, ajuste pro seu código

3. Inclua ferramentas de refatoração — rope ou ts-morph no kit do agente

4. Documente tudo — AGENTS.md com regras e motivos

5. Comece suave — Avisos primeiro, falhas depois

6. Acompanhe — Veja falhas nos hooks; se muitas, afrouxe os limites

Lição Principal

Não é só barrar código ruim. É montar um ambiente onde o bom código é o mais fácil.

Com hooks automáticos, docs claras e ferramentas de refatoração, agentes geram qualidade por padrão. Dividem problemas, focam funções e escrevem commits úteis.

Aí a IA vira aliado de verdade pro time.

Na NameOcean, cuidamos de infra que cresce: domain, hosting, SSL, DNS e fluxos dev. Trate seu código com o mesmo rigor da sua infraestrutura. Comece com Git hooks. Seu time agradece.