Como Rastrear e Recuperar Maus Funcionamentos de Agentes de IA na Base de Código
makedreamJuly 30, 2026
0
Computing/Software
Comments (0)
Log in to leave a comment
No posts yet
makedreammakedreamLog in to leave a comment
No posts yet
Quando você conecta um agente de IA como Claude Code ou Codex a um repositório backend com mais de 100.000 linhas de código, a velocidade inicial impressiona. No entanto, em um determinado momento, basta inserir algumas linhas de prompt incorretas para que a IA ultrapasse a linha de defesa e altere utilitários compartilhados ou arquivos de configuração de ambiente. Os logs de sessão aumentam para megabytes, o build quebra, e, após passar uma hora analisando o Git Diff para encontrar o arquivo causador, surge o pensamento de que teria sido melhor escrever tudo do zero.
Para dar autonomia ao agente sem causar danos desnecessários aos arquivos, é necessária uma separação rígida e clara, juntamente com um sistema visual de rastreamento de traces.
À medida que a janela de contexto cresce, é comum que os agentes ignorem arquivos de instruções em linguagem natural, como o CLAUDE.md ou o .aiignore. Solicitações no nível do prompt são apenas recomendações; assim que o contexto é perdido, a execução de ferramentas pelo agente ultrapassa os limites sem hesitação.
Para bloquear fisicamente o acesso do agente, é necessário colocar diretamente na raiz do projeto o .claude/settings.json, um motor determinístico de controle de permissões.
json { "permissions": { "deny": [ "Edit(src/core/config/**)", "Edit(src/shared/utils/**)", "Read(./.env*)", "Bash(rm -rf *)" ], "ask": [ "Edit(src/api/v1/legacy/**)" ] } }
Após definir regras explícitas de bloqueio, é mais seguro trancar o acesso também no nível do sistema de arquivos. Para scripts de build de produção ou arquivos de chaves de segurança, o ideal é remover as permissões de escrita no nível do SO.
.claude/settings.json na raiz do projeto.permissions.deny as configurações de ambiente, caminhos de utilitários compartilhados e comandos Bash destrutivos.chmod 444 .env* no terminal.Com esse controle de permissões configurado, é possível eliminar grande parte dos erros de build causados por modificações inesperadas da IA em módulos compartilhados.
Se os logs de sessão (.jsonl) ficarem restritos apenas ao ambiente local do desenvolvedor, será difícil identificar a causa quando ocorrer um efeito colateral posteriormente. Configure um fluxo de trabalho do GitHub Actions para compactar e verificar os traces da sessão no momento do Pull Request.
`yaml
name: AI Agent Session Audit & Risk Analysis
on:
pull_request:
types: [opened, synchronize]
jobs:
audit-session:
runs-on: ubuntu-latest
steps:
- name: Checkout Code
uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Setup Mindwalk Telemetry Extractor
run: |
docker run --rm -v ${{ github.workspace }}:/workspace \
cosmtrek/mindwalk:v0.1.0 parse --log-dir=./.claude/sessions --out=telemetry.json
- name: Run Deterministic Repo Audit
id: repo_audit
run: |
curl -sSL https://github.com/aletheore/releases/download/v1.0/aletheore -o aletheore
chmod +x aletheore
./aletheore audit --telemetry=telemetry.json --max-allowed-depth=3
- name: Upload Mindwalk 3D Visual Artifact
uses: actions/upload-artifact@v4
with:
name: mindwalk-3d-trace-${{ github.event.pull_request.number }}
path: telemetry.json
`
Ao integrar um motor de análise baseado em Rust ou o Tree-sitter para verificar se o agente saiu do escopo, você pode fazer o build do CI falhar imediatamente caso haja alterações em módulos superiores fora do intervalo permitido.
É útil calcular o risco de alteração com base na conectividade dos nós em vez de focar apenas no número de linhas de código.
Aqui, é o número de arquivos modificados e é a conectividade média 3D dos nós alterados. Se o limite for ultrapassado, configure o sistema para enviar um link do mapa de visualização 3D via notificação no Slack, permitindo que o revisor identifique o nível de risco instantaneamente.
Quando o agente causar uma grande confusão, em vez de descartar todo o commit, você deve rastrear a linha do tempo e restaurar seletivamente apenas os arquivos contaminados. Após extrair o intervalo de tempo exato em que o mau funcionamento começou, use o jq para obter o prompt e os caminhos de raciocínio daquele momento a partir do log JSONL.
bash jq -c 'select(.timestamp >= "2026-07-11T14:20:00Z" and .timestamp <= "2026-07-11T14:25:00Z") | {timestamp: .timestamp, prompt: .payload.prompt, tool_use: .payload.tool_use, thinking: .payload.thinking}' \ ./.claude/sessions/session_abc123.jsonl
Com a causa identificada, o processo de recuperação deve ser dividido nas 3 etapas a seguir:
git checkout <PRE_AI_COMMIT_SHA> -- src/legacy/broken_module.ts)git clean -fd -- src/unwanted_generated_dir/)Utilizando este método, você pode restaurar com precisão apenas os arquivos afetados, sem o contratempo de perder trechos de código que estão funcionando perfeitamente.
Em um ambiente monorepo, se o número de nós aumentar para dezenas de milhares, a própria ferramenta de visualização pode travar. Se o navegador ficar lento, a depuração se torna uma tarefa desagradável. Para remover diretórios desnecessários do alvo de renderização, configure corretamente o filtro de exclusão no mindwalk.config.json.
json { "visualization": { "excludePatterns": [ "**/node_modules/<strong>", "</strong>/vendor/<strong>", "</strong>/.git/<strong>", "</strong>/dist/<strong>", "</strong>/coverage/<strong>", "</strong>/*.log", "**/*.pb.go" ], "maxDepth": 5, "groupingStrategy": "directory-segmented" } }
Por fim, ao executar pipelines de visualização ou ferramentas de análise em um container Docker em segundo plano, limite a alocação de recursos para que a sua IDE local não trave.
mindwalk.config.json para excluir nós de diretórios de dependências da visualização.--cpus="1.5" e --memory="2g" ao executar o container.--nice=19 ao final do comando de execução em segundo plano para reduzir a prioridade de CPU ao nível mais baixo.