Como Organizar Agentes de Rede Neural no Seu Projeto Sem Caos e rm -rf Acidental

Um problema comum frequentemente surge com assistentes de IA autônomos no código. Você dá ao modelo acesso ao terminal e ao sistema de arquivos, pede para ele construir o projeto ou corrigir um bug, e alguns minutos depois ele decide limpar o cache e exclui algo valioso. Ou começa a improvisar, esquecendo completamente os acordos arquiteturais que você discutiu há uma hora.

O repositório vudovn/ag-kit oferece uma solução sistemática para esse problema. É um conjunto pronto de contratos, regras e ferramentas para o ambiente Google Antigravity. Ele transforma interações caóticas de redes neurais em um processo previsível com separação de funções e proteção contra ações perigosas.

O Que Está Dentro do Kit

Após a inicialização, o AG Kit cria uma estrutura .agents/ na raiz do projeto. Lá dentro você encontrará descrições declarativas de funções especializadas, habilidades, fluxos de trabalho prontos e memória de longo prazo.

Quando um projeto abre no Google Antigravity, o ambiente lê essa configuração. Em vez de um único chatbot universal tentando fazer tudo de uma vez, as tarefas começam a ser distribuídas para especialistas focados.

O repositório inclui os seguintes componentes:

• 20 agentes com foco específico para diferentes tarefas de desenvolvimento
• 47 habilidades com regras e lógica de validação
• 13 cenários prontos invocados via comandos de barra
• 6 regras gerais de workspace
• Módulo de memória de longo prazo em .agents/memory/ para preservar decisões arquiteturais

Gancho Protetor para Comandos de Console

A parte mais prática do kit é o interceptor integrado PreToolUse. Antes de executar um comando no terminal, o sistema o processa através de um script local validate-tool-call.mjs.

Se um agente tenta executar rm -rf /, formatar o disco ou sobrescrever partições do sistema, o script bloqueia imediatamente a execução e retorna um erro. Enquanto isso, limpezas rotineiras como remover node_modules ou dist continuam sem atrasos.

A configuração do gancho é definida em .agents/hooks.json:

{
  "enabled": true,
  "PreToolUse": [
    {
      "matcher": "run_command",
      "command": "node .agents/hooks/validate-tool-call.mjs",
      "timeout": 10
    }
  ]
}

Esse mecanismo não substitui controles de permissão regulares ou sandboxing, mas protege contra erros fatais de redes neurais.

Cenários Claros via Comandos de Barra

Em vez de escrever instruções longas no chat do zero cada vez, o kit oferece processos prontos. Você simplesmente digita um comando de barra na interface.

Aqui estão alguns exemplos dos 13 cenários incluídos:

• /plan primeiro constrói um plano de implementação detalhado e uma lista de verificação sem mexer no código-fonte
• /coordinate executa várias tarefas de pesquisa em paralelo e depois compila um resumo unificado
• /debug concentra o agente em encontrar causas de bugs a partir de logs e fatos, proibindo adivinhações
• /remember registra decisões técnicas importantes e acordos na memória permanente do projeto
• /verify executa verificações e testes para provar que o código realmente funciona

Versionamento e Atualizações Seguras

Os criadores do projeto trataram prompts e regras como código-fonte regular. Cada agente, cenário e regra tem uma versão semântica clara. O estado do kit é capturado nos arquivos .agents/manifest.json e .agents/manifest.lock.json.

As atualizações também são tratadas com cuidado. O comando ag-kit update não sobrescreve suas configurações locais. Ele mescla as alterações e cria automaticamente um backup exato na pasta .ag-kit-backups/.

Se uma nova atualização quebrar algo, você pode restaurar o estado anterior com um único comando:

ag-kit rollback

Como Experimentar no Seu Projeto

Você vai precisar de Node.js versão 22 ou mais recente e Python 3.10+. Inicialize em um repositório existente com um único comando:

npx @vudovn/ag-kit init

Para verificar se a configuração foi implantada corretamente e os ganchos estão funcionando, o projeto inclui scripts de validação integrados:

npm run check:agents
npm run check:antigravity

Você pode testar o gancho protetor sem executar comandos perigosos reais, enviando um payload de teste diretamente para o script de validação:

printf '%s' '{"tool_args":{"CommandLine":"rm -rf /"}}' \
  | node .agents/hooks/validate-tool-call.mjs

A resposta deve mostrar a mensagem BLOCKED by AG Kit, e o processo deve sair com um código diferente de zero.

Para Quem Esta Ferramenta É Útil

O AG Kit será útil para equipes e desenvolvedores individuais que escolheram o Google Antigravity como ambiente principal e querem trazer ordem aos fluxos de trabalho de IA. Em projetos grandes onde o contexto se polui rapidamente, a separação rígida em 20 funções e o salvamento de decisões na memória economizam tempo considerável.

Dito isso, há uma limitação a ser considerada: a compatibilidade total é garantida apenas dentro do Antigravity. Outros editores podem ler os arquivos de marcação em .agents/, mas as reações de ganchos e o roteamento automático não funcionarão lá.