Arquivos que atrasam um assistente

Alguns arquivos são mais difíceis do que outros para um assistente trabalhar, e o motivo geralmente não é o código em si. Um caminho na sua documentação que mudou de lugar. Um arquivo gerado que não pode ser editado com segurança. Um diretório que exige uma permissão que o agente não tem. Você provavelmente já sabe, mais ou menos, quais são esses arquivos, porque já se irritou com eles. O Pathrule registra isso com precisão.

O que é registrado

Quando uma ferramenta chamada por um assistente falha, três coisas são armazenadas: o tipo de ferramenta, o arquivo em que ela estava trabalhando e um código curto que indica como a falha aconteceu. file_not_found, permission_denied, timeout, rate_limit, token_limit, syntax_error, ou unknown quando a falha é real, mas nada a reconhece.

O registro é só isso. Não o comando. Não a mensagem de erro. Não o arquivo. Uma contagem e um código, associados a um caminho. Em um espaço de trabalho Cloud, essas contagens e códigos ficam armazenados junto com o espaço de trabalho no Pathrule Cloud.

A falha é observada, não relatada. O hook de ferramenta do Pathrule acompanha a própria chamada, então a contagem não depende de o assistente perceber o próprio erro, lembrar de uma sessão ou chamar qualquer coisa depois. Um assistente que falha em silêncio e segue em frente é registrado exatamente como um que anuncia a falha. A duração da chamada faz parte da mesma observação, e é isso que permite distinguir um comando que travou de um que foi recusado. Isso vale para os clientes em que o Pathrule tem hooks de ferramenta: Claude Code, Codex, Cursor e GitHub Copilot. O Windsurf não tem hooks do Pathrule, então as chamadas de ferramenta dele não são observadas dessa forma.

Antes de tudo, o caminho é normalizado para a forma relativa ao espaço de trabalho, o que importa mais do que parece. Em um notebook, um caminho absoluto é /Users/<name>/…, e esse nome não tem por que ir parar em conhecimento compartilhado. Caminhos relativos também fazem com que o mesmo arquivo seja agrupado corretamente em toda a equipe, em vez de uma vez por máquina.

Para que serve

Um retrato de onde o trabalho emperra. Com o tempo, as falhas são agrupadas por arquivo, ferramenta e código. O resultado é uma lista curta, não um gráfico: os arquivos em que um assistente mais falha, e de que forma. Um arquivo que aparece repetidamente com file_not_found costuma ser um caminho desatualizado em algum lugar das suas próprias instruções. Um com syntax_error costuma ser um arquivo realmente difícil de editar. Um com permission_denied costuma ser um problema de configuração que você resolve uma vez só.

Aprendizado da recuperação. Se um turno recebeu conhecimento do Pathrule e mesmo assim esbarrou em falhas, esse conhecimento recebe um sinal negativo, e alguns tipos de falha pesam mais do que um erro comum, porque tendem a indicar que a orientação mandou o assistente para um lugar aonde ele não conseguia ir. Esse sinal entra no ciclo descrito em como a recuperação encontra o conhecimento certo. O conhecimento que continua aparecendo em turnos que dão errado passa, aos poucos, a ter menos chance de ser escolhido, sem que ninguém precise revisá-lo.

O que o sinal não consegue ver

Esta parte depende do assistente que você usa, e não é uniforme.

As ferramentas de arquivo reportam falhas corretamente. Uma leitura, edição ou escrita que falha chega com a mensagem, é classificada e vai parar no arquivo certo. Esse é o caso que importa, porque é o caminho do arquivo que torna uma contagem acionável.

Com comandos de shell, muitas vezes isso não acontece. Alguns assistentes não reportam nenhum código de saída, então um comando que falha e um que dá certo chegam com a mesma cara. O Pathrule não deduz uma falha a partir do texto de saída: um resultado de busca pode conter legitimamente as palavras "no such file or directory", e uma falha errada associada a um arquivo é pior do que uma falha que ficou de fora. Quando o assistente não reporta uma falha, nada é registrado, e quando ele reporta uma que nenhuma regra reconhece, o código é unknown em vez de um palpite.

O que ele não faz

Registrar uma falha não bloqueia a chamada de ferramenta nem aparece no contexto do assistente. Uma falha é um fato sobre a sua base de código, registrado depois que aconteceu. Ela não muda o que o assistente tem permissão para fazer, e um arquivo com um histórico ruim não passa a ser tratado como proibido. Nada aqui é uma pontuação atribuída a uma pessoa: o registro diz respeito a arquivos, não a quem estava trabalhando neles.