Dê ao agente contexto útil do repositório

Comece pela cópia de trabalho atual

Um agente precisa de saber que repositório e branch está a alterar. Precisa também de saber se o diretório de trabalho contém alterações sem relação com a tarefa. Estes factos afetam o que pode editar com segurança e a interpretação do diff final.

Antes da implementação, peça ao agente que inspecione as instruções do projeto e a configuração dos pacotes. Um comando de outro repositório pode estar errado neste. Conhecer o nome do framework não determina a versão instalada nem as convenções do projeto.

Para uma alteração pequena, forneça o módulo relevante, o código que o chama, os testes e a decisão de arquitetura. Acrescente informação quando a investigação revelar uma necessidade concreta.

Use as instruções do repositório para regras estáveis

Um ficheiro de instruções pode descrever comandos suportados, limites de módulos, requisitos de revisão e ações que exigem uma decisão do responsável. A convenção AGENTS.md oferece às ferramentas de programação um local reconhecível para esta informação. O suporte desta convenção e a precedência das instruções podem variar; confirme o comportamento da sua ferramenta.

Guarde as regras estáveis do projeto no repositório. Mantenha a tarefa atual no respetivo enunciado. Não transforme o ficheiro de instruções num histórico de todas as conversas nem numa lista de planos temporários.

Uma instrução útil diz: «Executar os testes de integração de autorização quando uma rota alterar o comportamento de acesso.» Uma instrução vaga diz: «Ter sempre cuidado com a segurança.» A primeira identifica uma condição e uma ação que o revisor consegue verificar.

Compare as instruções com o código

As instruções ficam desatualizadas quando mudam comandos, diretórios ou a arquitetura. Se um guia referir um script em falta, inspecione a configuração dos pacotes. Se um documento afirmar que um serviço só permite leitura, inspecione as permissões antes de confiar nessa afirmação.

Registe o conflito. Use provas diretas sobre a versão atual para compreender o comportamento da implementação. Não descarte silenciosamente uma política intencional só porque o código antigo a viola. A política e o comportamento atual respondem a perguntas diferentes.

Por exemplo, o guia pode proibir escritas diretas num branch partilhado, enquanto um script antigo ainda as executa. A resposta correta é preservar a política e corrigir o script. O código existente não autoriza a repetição de uma ação proibida.

Mantenha o contexto relevante e seguro

Um repositório completo pode conter credenciais, dados de teste privados, exportações de clientes e logs antigos de apoio. O acesso ao repositório não torna automaticamente todos os ficheiros adequados a um serviço de modelos.

Use ferramentas aprovadas e as regras de tratamento de dados. Exclua segredos do contexto. Sempre que possível, substitua exemplos de clientes por dados inventados. Verifique as ferramentas ligadas além dos ficheiros enviados: um conector de pesquisa pode obter informação que nunca esteve no prompt inicial.

A instrução «não ler segredos» num repositório é uma orientação útil. Não substitui a limitação do acesso ao armazenamento de segredos e aos diretórios sensíveis.

Deixe um registo útil para a pessoa seguinte

No fim, registe no pull request o comportamento alterado, a verificação e os limites por resolver. Atualize a documentação permanente do projeto quando mudar o processo suportado. Evite copiar para o repositório a transcrição completa do agente.

O registo deve permitir que outra pessoa repita o trabalho de manutenção sem reconstruir uma conversa longa. Ligue aos documentos canónicos e mantenha uma descrição de referência única para cada regra estável.

Um bom contexto reduz a investigação repetida. Também facilita a deteção de erros, porque torna explícitos o comportamento esperado e os comandos que funcionam.