Dê ao agente um contexto útil do repositório

Comece pelo checkout atual

Um agente precisa saber qual repositório e qual branch está alterando. Também precisa saber se o diretório de trabalho contém alterações sem relação com a tarefa. Esses fatos afetam o que ele pode editar com segurança e como interpretar o diff final.

Peça ao agente que inspecione as instruções do projeto e a configuração do pacote antes de implementar. Um comando lembrado de outro repositório pode estar errado aqui. Um nome conhecido de framework não comprova 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ções quando a investigação mostrar uma necessidade específica.

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

Um arquivo de instruções pode descrever comandos suportados, limites entre módulos, exigências de revisão e ações que precisam de decisão de um responsável. A convenção AGENTS.md dá às ferramentas de programação um local reconhecível para essas informações. O suporte das ferramentas e a precedência das instruções podem variar; confira o comportamento da ferramenta utilizada.

Mantenha as regras estáveis do projeto no repositório. Mantenha a tarefa atual na descrição da tarefa. Não transforme o arquivo de instruções em um histórico de todas as conversas ou em uma lista de planos temporários.

Uma instrução útil diz: “Execute os testes de integração de autorização quando uma rota alterar o comportamento de acesso.” Uma instrução vaga diz: “Sempre tome cuidado com a segurança.” A primeira identifica uma condição e uma ação que o revisor pode verificar.

Confira as instruções no código

Instruções ficam desatualizadas quando comandos, diretórios ou arquitetura mudam. Se um guia mencionar um script ausente, inspecione a configuração do pacote. Se um documento disser que um serviço é somente de leitura, inspecione as permissões antes de confiar nessa afirmação.

Registre o conflito. Use evidências diretas da versão atual para entender o comportamento da implementação. Não descarte silenciosamente uma política intencional 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 em uma branch compartilhada enquanto um script antigo ainda as executa. A resposta correta é preservar a política e corrigir o script. Código existente não é permissão para repetir uma ação proibida.

Mantenha o contexto relevante e seguro

Um repositório inteiro pode conter credenciais, fixtures privadas, exportações de clientes e logs antigos de suporte. Acesso ao repositório não torna automaticamente todos os arquivos adequados para um serviço de modelos.

Use ferramentas aprovadas e regras de tratamento de dados. Exclua segredos do contexto. Substitua exemplos de clientes por dados inventados quando possível. Verifique também as ferramentas conectadas, além dos arquivos enviados: um conector de busca pode recuperar informações que nunca estiveram no prompt inicial.

Uma instrução do repositório que diga “não leia segredos” é uma orientação útil. Ela não substitui a limitação de acesso ao armazenamento de segredos e a diretórios sensíveis.

Deixe um registro útil para a próxima pessoa

Ao concluir, registre no pull request o comportamento alterado, a verificação e os limites não resolvidos. Atualize a documentação duradoura do projeto quando o fluxo de trabalho suportado mudar. Evite copiar toda a transcrição do agente para o repositório.

O registro deve ajudar um futuro mantenedor a repetir o trabalho sem reconstruir uma conversa longa. Inclua links para documentos canônicos e mantenha uma descrição oficial de cada regra estável.

Um bom contexto reduz investigações repetidas. Também facilita a detecção de erros, pois o comportamento esperado e os comandos que funcionam ficam explícitos.