AGENTS.md na prática: como orientar a IA dentro de um projeto

A IA recebe uma tarefa de manutenção Delphi e sugere trocar uma dependência, alterar uma assinatura pública ou gravar dados durante uma análise. Você explica as restrições, e a conversa melhora. Na próxima tarefa, precisa repetir o mesmo contexto. O problema não é somente a qualidade do pedido: os acordos do projeto ainda dependem de alguém lembrar de transmiti-los.

Um arquivo de orientações pode organizar esses acordos, desde que a ferramenta saiba onde encontrá-lo e a equipe saiba mantê-lo. Ele não deve reunir toda a documentação, todas as decisões antigas e todos os pedidos do histórico. Deve ajudar a trabalhar naquele ambiente, localizando referências relevantes e estabelecendo limites verificáveis.

Neste capítulo da série sobre instruções para IA, vamos construir um exemplo de AGENTS.md para um projeto Delphi fictício. Explicaremos raiz do projeto, módulo, precedência e conferência antes de usá-los. O comportamento de descoberta descrito aqui é o documentado para o Codex em 4 de outubro de 2026; não será apresentado como uma regra de todos os assistentes.

Se o desafio é explicitar comportamentos e conferir alterações, SDD em Delphi aprofunda especificações, contratos e critérios de aceite. Consulte o sumário e a degustação gratuita para avaliar como ligar essas orientações à implementação e aos testes. Um arquivo de instruções é mais útil quando participa desse entendimento, não quando funciona apenas como uma lista de preferências.

Primeiro, o que é uma orientação de projeto

Uma orientação de projeto descreve como trabalhar num ambiente compartilhado. Pode explicar onde estão os contratos, quais alterações exigem discussão e como registrar uma verificação. Seu alcance é diferente do pedido atual. “Revise esta alteração” escolhe a tarefa; “não apresente teste sugerido como teste executado” estabelece uma condição que continuará relevante em outras revisões.

AGENTS.md é um nome de arquivo usado para fornecer esse tipo de orientação a agentes de programação que o reconhecem. A documentação oficial do Codex descreve como ele encontra e combina esses arquivos. O formato não garante obediência nem substitui controles técnicos: ele oferece instruções que devem ser acompanhadas por evidências do trabalho.

A raiz é o diretório principal do projeto. Um módulo é uma parte da aplicação, como a importação de pedidos, que pode ter regras específicas. O diretório de trabalho é o local a partir do qual a ferramenta conduz a tarefa. Esses conceitos importam porque não basta existir um arquivo em algum lugar: precisamos compreender qual caminho de descoberta está sendo usado.

No exemplo, a raiz terá acordos compartilhados e o módulo terá orientações sobre a prévia da importação. A divisão não exige uma arquitetura específica de Delphi. Ela pode servir tanto a um sistema antigo quanto a um projeto novo, desde que as referências e os comandos correspondam ao ambiente real.

O que o Codex documenta sobre descoberta

Segundo a documentação consultada, o Codex combina orientações globais e arquivos ao longo do caminho da raiz até o diretório de trabalho. Em cada diretório, procura AGENTS.override.md antes de AGENTS.md e inclui no máximo um arquivo dessa camada. Orientações mais próximas do diretório de trabalho prevalecem sobre anteriores quando conflitantes. A página também descreve limites de tamanho e nomes alternativos configuráveis.

Essa descrição não significa uma busca automática em todos os subdiretórios para qualquer tarefa. Por isso, o local de início merece conferência. Não trate a presença de um arquivo num módulo como prova de que ele foi carregado numa sessão iniciada em outro lugar. A seção de verificação da configuração orienta conferir as fontes ativas.

Precedência significa qual orientação prevalece quando há conflito entre camadas. Ela não é uma recomendação para escrever regras contraditórias. Se um módulo possui uma exceção legítima, é melhor explicá-la com seu alcance. Se duas pessoas registraram expectativas incompatíveis, a equipe precisa resolver o entendimento; depender da ordem dos arquivos apenas esconderia a disputa.

Neste capítulo, não alteramos a configuração de um agente nem executamos uma sessão Codex para medir descoberta. O exemplo representa uma proposta de organização baseada na documentação. Essa limitação é importante: desenhar uma árvore correta não demonstra que a instalação do leitor usa o mesmo perfil, caminho ou configuração.

Uma raiz que orienta sem carregar o projeto inteiro

Imagine um sistema empresarial Delphi com módulos de vendas e importação. A equipe quer que o assistente preserve contratos públicos, não use dados reais de clientes em exemplos e consulte a documentação de compilação antes de afirmar que executou testes. Essas orientações podem ficar na raiz porque se aplicam a mais de uma área.

O arquivo pode ser pequeno. A equipe não precisa copiar a documentação completa de cada módulo para ele. Em vez disso, pode indicar onde estão os materiais e em que situação devem ser consultados. Essa seleção mantém a instrução útil para tarefas diferentes, como revisar uma importação ou corrigir uma mensagem na tela de vendas.

Um exemplo didático de conteúdo é:

## Acordos de trabalho

- Preserve contratos públicos; proponha separadamente mudanças incompatíveis.
- Não use dados reais de clientes em exemplos ou testes.
- Não modifique arquivos quando a tarefa solicitada for somente análise.

## Como localizar evidências

Para compilar ou executar testes, consulte docs/ambiente.md.
Para regras da importação, consulte docs/importacao.md.

## Entrega

Informe o que foi alterado ou analisado, as verificações executadas
e as limitações encontradas. Diferencie teste executado de teste sugerido.

Os caminhos são fictícios e precisam existir antes de o modelo ser usado. A ausência de um comando universal é intencional. Copiar uma instrução de compilação de outro projeto pode produzir uma tentativa inútil ou alterar artefatos sem necessidade. O arquivo deve apontar o procedimento efetivo da equipe, incluindo dependências e condições relevantes.

“Preserve contratos públicos” também precisa ser contextualizado. Um contrato é uma expectativa compartilhada sobre entradas, saídas e comportamento. Numa manutenção, modificar uma assinatura pode afetar outros consumidores. A orientação pede que o impacto seja discutido, mas não proíbe para sempre qualquer evolução. Regras absolutas sem processo de exceção tendem a gerar impasses.

O módulo acrescenta o que realmente é específico

Infográfico ilustrativo gerado por IA. Síntese autoral de responsabilidades, apoiada na documentação de AGENTS.md; não representa um fluxo oficial de descoberta nem uma interface real.

Para a importação, vamos considerar a prévia que mostra as linhas recebidas antes da gravação. A alteração fictícia rejeita linhas sem código do produto, incluindo aquelas com somente espaços. Essa regra precisa ter uma fonte de domínio reconhecida. Não deveria nascer apenas num arquivo de instruções porque o exemplo parecia conveniente.

O módulo pode acrescentar uma orientação de revisão: confrontar a alteração com a especificação vigente, examinar casos de ausência e espaços e verificar se linhas rejeitadas ficam fora da gravação. O detalhe está ligado ao trabalho naquele módulo, não à rotina inteira de todos os desenvolvedores.

Uma organização ilustrativa seria:

projeto/
  AGENTS.md
  docs/
    ambiente.md
    importacao.md
  modulos/
    importacao/
      AGENTS.md

Neste desenho, os caminhos de documentação mencionados nos exemplos são relativos à raiz do projeto. Essa convenção deve ser escrita no arquivo real; não suponha que toda ferramenta resolverá referências locais da mesma maneira. Se houver um arquivo de substituição no mesmo diretório, confira qual conteúdo foi selecionado antes de avaliar a tarefa.

## Revisão da importação

Consulte a especificação vigente indicada em docs/importacao.md.
Examine a prévia e o caminho de gravação separadamente.

Não conclua que uma linha foi impedida de gravar apenas porque
a interface exibiu uma mensagem de rejeição.

Quando faltar evidência, registre a lacuna e proponha a verificação
necessária. Não invente resultado de execução.

Esse trecho não substitui a especificação. Ele explica como usar a referência e quais confusões a revisão deve evitar. A mesma distinção foi construída no artigo introdutório sobre AGENTS.md e skills. Aqui, a aplicação está na distribuição entre alcance geral e detalhe do módulo.

Também não é preciso criar um arquivo em cada pasta. Se um subdiretório não tem orientação própria, acrescentar uma cópia dos acordos gerais cria manutenção sem benefício evidente. Comece pelo problema recorrente e pelo lugar em que ele ocorre. A hierarquia deve reduzir ambiguidade, não aumentar o número de documentos para serem revisados.

Transforme preferências vagas em condições conferíveis

“Use boas práticas” oferece pouca direção para uma revisão concreta. A pessoa ou o assistente precisa adivinhar quais práticas são prioritárias. Uma orientação mais útil pode pedir que uma alteração preserve o contrato existente ou apresente a justificativa para modificá-lo. A condição permite localizar uma evidência, mesmo que a decisão final ainda dependa de julgamento humano.

“Teste tudo” também esconde problemas. O projeto pode não ter ambiente disponível, alguns testes podem precisar de serviços e uma execução ampla pode ser inadequada para aquela tarefa. Melhor identificar o conjunto pertinente e exigir que o relatório registre o comando utilizado, o resultado e as limitações. Quando não houve execução, esse fato deve aparecer.

Nem toda condição cabe num verificador automático. Uma revisão arquitetural pode exigir argumentação sobre dependências e responsabilidades. Ainda assim, a entrega pode apontar o material examinado e explicar o raciocínio. Verificável não significa reduzir todo julgamento a um número; significa deixar o resultado acessível à conferência.

Para projetos existentes, essa disciplina se conecta à manutenção Delphi com apoio de IA: delimitar a mudança, proteger comportamentos e observar evidências. O arquivo de orientações ajuda a lembrar o processo, mas não demonstra que a alteração respeitou essas condições.

Uma conferência antes da primeira tarefa real

Antes de colocar o arquivo em uso, uma pessoa deve conferir seus caminhos e afirmações. A documentação citada existe? O procedimento de compilação corresponde à versão do projeto? Uma instrução autoriza algo que a equipe não pretende autorizar? Essa revisão evita transformar um modelo didático em regra operacional sem adaptação.

Depois, confira o ambiente de descoberta da ferramenta. Identifique o diretório de trabalho, o projeto reconhecido e os arquivos de instrução disponíveis no perfil utilizado. Peça que a sessão informe quais fontes estão ativas e examine os registros oferecidos pelo produto. Não use apenas a capacidade do modelo de repetir uma frase como evidência de cumprimento.

A verificação seguinte é comportamental. Escolha uma tarefa pequena e não sensível, observe o que foi feito e compare com as condições da entrega. Uma análise deveria manter os arquivos intactos; uma verificação não executada deveria ser registrada como limitação. Esses resultados valem mais que um resumo convincente sobre as regras.

Também registre os casos em que a orientação foi inadequada. Se uma instrução exigiu leitura excessiva ou bloqueou uma tarefa legítima, revise seu escopo. A proposta não é ensinar a equipe a obedecer a um documento desatualizado, mas manter um acordo útil. O exemplo deste capítulo ainda precisa dessa avaliação quando adaptado a um projeto.

Cuidados com conflitos, segredos e mudanças de contexto

Uma orientação permanente não deveria carregar o identificador de uma tarefa antiga como se fosse a prioridade atual. Objetivos específicos pertencem ao pedido ou ao plano daquela manutenção. Quando o arquivo começa a funcionar como diário, o leitor precisa descobrir quais instruções ainda valem. Separe decisão recorrente de andamento temporário.

Não inclua credenciais, dados de clientes ou material proprietário desnecessário para a tarefa. Um arquivo compartilhado pode circular com o projeto e ser disponibilizado a ferramentas diferentes. A conveniência de uma orientação não justifica expor um segredo. Descreva como obter acesso autorizado, sem registrar o conteúdo sensível.

Quando um documento consultado contém comandos, preserve a diferença entre fonte e autorização. Uma referência pode ensinar a instalar uma dependência, mas isso não significa que a tarefa de revisão autorizou sua instalação. A engenharia de contexto ajuda a organizar informação; as permissões continuam exigindo decisão própria.

Por fim, não exporte silenciosamente esse comportamento para outras ferramentas. Nomes, descoberta e precedência precisam ser conferidos na documentação do produto utilizado. A equipe pode manter princípios comuns, mas deve adaptar a integração. Um arquivo que funcionou num ambiente não demonstra compatibilidade operacional com outro.

Conclusão

AGENTS.md pode tornar os acordos do projeto mais explícitos, desde que seu alcance seja conhecido e sua aplicação seja conferida. A raiz organiza orientações compartilhadas; o módulo acrescenta detalhes pertinentes; as referências sustentam regras de negócio; a tarefa atual continua sendo escolhida pelo pedido. Nenhuma dessas peças dispensa revisão do resultado.

Comece com poucas orientações ligadas a dificuldades reais e teste sua utilidade numa tarefa pequena. Se a equipe ainda não consegue definir o que a mudança deve preservar, SDD em Delphi aprofunda contratos e critérios de aceite. A degustação permite avaliar esse percurso antes de ampliar a biblioteca de instruções; clareza de arquivo deve acompanhar clareza de engenharia.

Referências

OPENAI. Custom instructions with AGENTS.md. ChatGPT Learn, [s. d.]. Disponível em: https://learn.chatgpt.com/docs/agent-configuration/agents-md. Acesso em: 4 out. 2026.

SILVEIRA, Régys Borges da. AGENTS.md, instruções e skills: como orientar uma IA dentro do projeto. regys.com.br, publicação agendada para 20 out. 2026. Disponível em: https://regys.com.br/agents-md-instrucoes-e-skills-como-orientar-uma-ia-dentro-do-projeto/. Acesso em: 4 out. 2026. Consulta ao rascunho.

SILVEIRA, Régys Borges da. Como usar IA em um projeto Delphi existente sem perder o controle. regys.com.br, publicação agendada para 21 out. 2026. Disponível em: https://regys.com.br/como-usar-ia-em-um-projeto-delphi-existente-sem-perder-o-controle/. Acesso em: 4 out. 2026. Consulta ao arquivo editorial.

SILVEIRA, Régys Borges da. Engenharia de contexto: por que um bom prompt não basta para programar com IA. regys.com.br, publicação agendada para 19 out. 2026. Disponível em: https://regys.com.br/engenharia-de-contexto-por-que-um-bom-prompt-nao-basta-para-programar-com-ia/. Acesso em: 4 out. 2026. Consulta ao rascunho.

SILVEIRA, Régys Borges da. SDD em Delphi. Livros de Régys Borges da Silveira, [s. d.]. Disponível em: https://livros.regys.com.br/sdd-em-delphi. Acesso em: 4 out. 2026.