Revisão de código antes do commit: agentes especializados pra cobrir o meu próprio ponto cego entre backend e frontend

O problema que ninguém nomeia até doer

Quem revisa o próprio código fora da própria especialidade revisa pior, e isso vale mesmo quando o "time" é uma pessoa só. Num projeto pessoal com backend e frontend separados, meu background é forte em backend: anos de prática, um checklist de review que já vive na cabeça sem esforço. Frontend eu escrevo, mas não com a mesma profundidade, e é exatamente aí que a atenção de quem entende do assunto desaparece sem avisar. O código passa, os testes passam, o commit acontece, e a revisão que eu faria com rigor de especialista, se estivesse revisando backend, simplesmente não acontece com o mesmo padrão quando o arquivo é um componente Vue.

Foi esse o sintoma que apareceu ao tocar sozinho dois repositórios de stacks bem diferentes: um backend e um frontend. Não é um problema de disciplina, é estrutural. Ninguém segura na cabeça, ao mesmo tempo, o checklist de segurança de backend com a mesma profundidade que as convenções de composables de frontend, especialmente quando um dos dois lados não é a sua especialidade original.

O gatilho: um artigo, uma pergunta diferente

O ponto de partida foi um artigo sobre como um time usava IA para antecipar problemas de code review, guidelines versionadas, um ponto de entrada único para agentes, subagentes especializados e consolidação dos achados antes da entrega. A pergunta natural foi se o mesmo padrão fazia sentido sozinho, num projeto pessoal, sem um segundo revisor humano pra cobrir o lado onde minha experiência é mais rasa. Uma primeira tentativa de aplicar essa ideia foi dentro de um assistente de conhecimento pessoal baseado em RAG: ali, o "revisar antes do commit" fazia sentido para proteger invariantes específicos daquele sistema (confiança calculada de forma consistente, degradação graciosa quando dependências externas faltam, drift entre arquivos gerados e fonte). Ficou claro rapidamente que era um problema diferente do que estava doendo no dia a dia: naquele caso era revisão de conhecimento; aqui era code review real, de mudança real, em dois repositórios com stacks e riscos completamente diferentes, e, principalmente, com um nível de familiaridade minha bem desigual entre os dois lados.

Essa distinção foi o que definiu a proposta separada: agentes de review pré-commit para os dois repositórios do projeto, desacoplados do assistente de conhecimento, atacando diretamente o ponto onde a falta de especialidade em frontend deixava passar coisas que eu jamais deixaria passar em backend.

A solução: regras versionadas por domínio, não um revisor genérico

A decisão de design mais importante foi rejeitar um "revisor único genérico" e, em vez disso, versionar o conhecimento de review como está estruturalmente distribuído entre os domínios reais do sistema. Cada domínio vira um arquivo de regras curto, em prosa, revisável como qualquer outro código.

No repositório de backend:

No repositório de frontend:

Dos itens listados, o que se mostrou de maior valor prático foi o rastreamento de callers dentro do domínio de type safety: verificar não só se a função nova está tipada, mas se todo lugar que a chama continua consistente com a mudança. É exatamente o tipo de checagem que um humano cansado, revisando fora da própria especialidade, pula, e que gera bug em produção silenciosamente.

Cada repositório ganhou também um orquestrador, no frontend, um arquivo de skill dedicado, seguindo o mesmo padrão já usado para outras automações do repositório, complementando (não substituindo) o skill de code review genérico já existente. O orquestrador lê os arquivos de regra, aplica-os ao diff da mudança e devolve um relatório único, categorizado.

O contrato: consultivo, não bloqueante

Uma decisão deliberada, herdada da experiência anterior com o assistente de conhecimento: a v1 não trava entrega automaticamente. O papel do agente é produzir um relatório com achados categorizados por severidade, a decisão de bloquear a entrega continua sendo minha. Isso existe por dois motivos:

• Calibração inicial imprevisível. Domínios como manutenibilidade (DRY, simplicidade) são inerentemente mais subjetivos do que segurança ou type safety. Sem dados reais de quantos achados desse tipo são falsos positivos, bloquear automaticamente geraria ruído e, rapidamente, eu mesmo passaria a ignorar o agente, o pior desfecho possível para uma ferramenta desse tipo.
• Confiança se constrói, não se decreta. Um agente consultivo que acerta na maioria das vezes ganha o direito de, eventualmente, bloquear certas categorias de achado (por exemplo, segurança com alta confiança). Um agente bloqueante que erra uma vez perde a credibilidade inteira.

O gatilho de execução foi formalizado numa seção específica das instruções que qualquer sessão de agente lê antes de começar a trabalhar no repositório, instruindo-a a rodar o playbook antes de considerar a tarefa concluída.

Rollout em fases

Nenhum dos dois repositórios recebeu o conjunto completo de domínios de uma vez. O rollout seguiu o mesmo padrão de faseamento usado no restante do sistema de agentes internos:

1. Estrutura sem automação — os arquivos de regra existem e são revisáveis, mesmo antes de qualquer agente lê-los automaticamente.
2. Orquestrador funcional — o skill lê as regras e produz o relatório, ainda sem estar amarrado ao fluxo obrigatório.
3. Gatilho obrigatório — qualquer sessão de agente passa a rodar o playbook antes de finalizar.
4. Piloto com calibração — achados conhecidos injetados propositalmente em cada categoria, para medir taxa de falso positivo antes de considerar qualquer bloqueio automático futuro.

Os domínios mais "objetivos" (segurança, type safety, testes) foram semeados com o checklist de review que eu já aplicava de cabeça no lado onde tenho mais prática, o backend. Os mais recentes (observabilidade, resiliência) entraram com regras iniciais mais enxutas, para evoluir com uso real em vez de tentar prever tudo de antemão.

O que ficou claro depois de rodar isso de verdade

Uma vez ativo, o hook de auto-revisão passou a interceptar literalmente qualquer sessão de agente antes da entrega, inclusive sessões de trabalho em outros projetos, quando as instruções eram lidas no contexto errado. Isso expôs um ponto que a proposta original não tinha antecipado: um playbook desse tipo, referenciado de forma global demais, vaza para onde não devia. A correção não é técnica exótica, é escopo explícito: o hook precisa declarar claramente a que repositório e a que conjunto de regras ele pertence, para não disparar fora do contexto certo.

Essa é, talvez, a lição mais transferível de todo o exercício: regras versionadas e agentes especializados resolvem o problema do olhar crítico que falta, mas só se o escopo de ativação for tão bem desenhado quanto as próprias regras.

Resumindo

• O problema real não era "falta de IA no code review", era perda de atenção especializada ao revisar sozinho o lado onde minha experiência é mais recente.
• A solução foi desacoplar conhecimento de review em regras versionáveis por domínio, revisáveis como qualquer código.
• Um orquestrador lê essas regras e produz um relatório único e categorizado, sem decidir travar a entrega, isso continua sendo humano, pelo menos nesta fase.
• O gatilho fica formalizado nas instruções do agente, não em automação solta.
• Rollout em fases, com piloto de calibração antes de qualquer discussão sobre bloqueio automático.