Aprendizado do projeto

Quase tudo o que um agente aprende sobre o seu projeto vem da leitura do código. Por que uma fila para no primeiro erro de rede, por qual helper passa todo fluxo de pagamento, como a equipe resolveu a última discussão sobre tratamento de erros: o agente descobre, usa, e a sessão termina. O próximo agente, ou o agente de um colega, paga para descobrir tudo de novo.

O aprendizado do projeto guarda essas conclusões. O agente salva o que descobriu junto com os arquivos que leu, e todos os agentes do espaço de trabalho partem daí, enquanto o código continuar dizendo a mesma coisa.

O que é uma descoberta

Uma descoberta é algo que um agente concluiu a partir do seu código, junto com os arquivos em que ela se baseia e o que esses arquivos continham quando ele os leu. O Pathrule confere os arquivos com o que está no disco antes de aceitar a descoberta, então uma descoberta só é salva sobre código que existe.

Uma descoberta não é uma memória, uma regra nem uma skill. Ela nunca vira uma delas por conta própria e nunca bloqueia nada. Ela fica em uma camada própria, ao lado do conhecimento que a sua equipe escreveu.

Como ela chega aos agentes

As descobertas chegam no contexto que o agente pede ao Pathrule, por meio de pathrule_get_context. Elas vêm apresentadas como recomendações a verificar, e os agentes são orientados a tratá-las como informação, não como instruções, para que um texto plantado em um arquivo não se transforme em uma ordem permanente.

Uma descoberta só é entregue enquanto as evidências dela se sustentam no seu checkout:

• Fontes inalteradas. A descoberta é entregue.
• Uma fonte mudou. A descoberta fica retida até que um agente leia o código de novo e a confirme ou corrija. Ninguém recebe uma resposta sobre um código que não existe mais.
• Duas descobertas divergem. As duas ficam retidas, em vez de o sistema tentar adivinhar qual está certa.

Essa verificação é feita por checkout, então um colega em uma branch mais antiga ou mais nova recebe apenas as descobertas que valem para o código que ele tem em mãos.

Correção e retirada

Um agente pode corrigir uma descoberta registrando uma nova que a substitui, com fontes verificadas novamente. Uma descoberta que se mostra errada pode ser retirada pela pessoa cujo agente a registrou. A retirada vale para todo o espaço de trabalho de uma vez, e uma tentativa antiga reenviada de uma máquina que estava offline nunca consegue trazê-la de volta.

Os agentes podem listar as descobertas atuais, desatualizadas e conflitantes, incluindo as que foram retidas do contexto, para que uma pessoa veja exatamente o que há na camada e por que algo não foi entregue.

Aprendendo com revisões anteriores

Com acesso ao GitHub pelo seu login existente no gh, um agente pode ler discussões de revisões anteriores no repositório para ver como a equipe decidiu uma questão parecida antes e citar isso em uma descoberta. O Pathrule não armazena os comentários em si e ignora revisões de bots, de pessoas externas e revisões descartadas. Sem acesso ao GitHub, todo o resto continua funcionando.

O que sai da sua máquina

O aprendizado do projeto não precisa de modelo local e não grava nada no seu repositório.

Em um espaço de trabalho local, as descobertas ficam no armazenamento local dele, na sua máquina. Em um espaço de trabalho no Cloud, o Pathrule compartilha a descoberta e a origem dela, ou seja, os caminhos dos arquivos e uma impressão digital do que cada arquivo continha, para que outros checkouts saibam se a descoberta ainda vale. O conteúdo dos arquivos não é enviado. Uma descoberta registrada offline espera em uma fila e é enviada quando a conexão volta.

Não há etapa de revisão

Uma descoberta é compartilhada assim que as fontes dela são confirmadas; nenhuma pessoa a aprova antes. Isso é proposital: as descobertas são recomendações conferidas novamente com o código a cada entrega, não política da equipe. Tudo o que precisa valer para todos os agentes continua pertencendo a uma regra ou a uma memória, escrita e revisada pela sua equipe.

As ferramentas por trás disso estão listadas na referência de ferramentas MCP.