Instruções para agentes de IA no projeto

Introdução

Quando você começa uma tarefa com um assistente de programação, parte do contexto do projeto não está no código: convenções, comandos, arquitetura e decisões que a equipe já tomou. Se essas informações ficam apenas na conversa, é preciso repeti-las em cada sessão.

Arquivos de instrução dentro do repositório ajudam a registrar esse conhecimento junto com o projeto. Assim, ferramentas que reconhecem esses arquivos podem consultá-los ao trabalhar no código. O mesmo espaço também pode guardar orientações editoriais, como a forma de escrever os artigos de um site.

Que tipo de informação vale guardar?

Use esses arquivos para registrar informações que o agente precisaria receber de novo em tarefas diferentes, por exemplo:

• comandos disponíveis para lint, build e execução local;
• organização de pastas e decisões de arquitetura que não sejam óbvias pelo código;
• convenções de código, conteúdo, SEO e nomenclatura;
• procedimentos recorrentes para revisar ou publicar mudanças.

Como esses arquivos costumam ser versionados junto com o projeto, não coloque neles tokens, senhas ou outros segredos. Guarde instruções e referências ao contexto; mantenha credenciais nos mecanismos próprios do ambiente.

Neste site, por exemplo, o AGENTS.md orienta os agentes a consultar um guia de estilo e um template antes de criar artigos. Dessa forma, a voz do autor acompanha o processo de produção de conteúdo junto com as regras técnicas do projeto.

Mantenha as instruções objetivas e revise-as quando o projeto mudar. Informações repetidas, contraditórias ou que já podem ser descobertas facilmente no repositório ocupam espaço e podem desviar a atenção do agente.

AGENTS.md e CLAUDE.md

O Codex CLI lê arquivos AGENTS.md globais e os encontrados do diretório raiz do projeto até a pasta de trabalho. Isso permite registrar orientações gerais na raiz e adicionar regras mais específicas em subpastas, se necessário.

O Claude Code usa arquivos CLAUDE.md como contexto persistente e, desde a versão 2.1.277, também pode ler AGENTS.md diretamente. Na configuração padrão, ele escolhe CLAUDE.md ou AGENTS.md: se houver CLAUDE.md, .claude/CLAUDE.md ou CLAUDE.local.md no diretório de trabalho ou em um diretório acima, carrega os arquivos CLAUDE.md e não lê AGENTS.md diretamente. A configuração de projeto claude-md-and-agents-md pode mudar esse comportamento para carregar os dois.

Quando ambos coexistem, importar AGENTS.md no CLAUDE.md com @AGENTS.md compartilha as instruções gerais e também atende sessões em que a leitura direta de AGENTS.md não está disponível. Claude Code evita carregar duas vezes um arquivo que já entrou por importação.

Um exemplo simples:

# CLAUDE.md
 
@AGENTS.md
 
## Orientações específicas do Claude Code
 
[Inclua aqui instruções que só se aplicam ao Claude Code.]

No arquivo compartilhado, mantenha as regras que servem a mais de uma ferramenta. O CLAUDE.md pode então acrescentar detalhes próprios do Claude Code sem duplicar as instruções gerais. A documentação do Claude Code também permite organizar instruções por pasta ou tipo de arquivo quando o projeto precisa de regras mais específicas.

Uma estrutura como esta separa instruções compartilhadas, detalhes da ferramenta e material editorial:

AGENTS.md
CLAUDE.md
articles/
├── GUIA-DE-ESTILO-DO-AUTOR.md
└── TEMPLATE-ARTIGO-TECNICO-IA.md

Neste repositório, o agente consulta os dois arquivos editoriais antes de escrever e usa a tag IA nos novos artigos para incluí-los na página temática. Ao preparar um texto novo, ele fica em articles/ para revisão; só depois de conferir autoria, fontes e capa vai para content/posts/.

Como incluir a forma de escrever

Se o agente vai ajudar a produzir artigos, não deixe o estilo apenas implícito nos textos antigos. Crie um guia curto com padrões observados nos artigos e indique um template como ponto de partida. O guia pode registrar, por exemplo, o uso de linguagem direta, exemplos técnicos, opiniões identificadas como opiniões e ressalvas ao comparar ferramentas.

No AGENTS.md, indique os caminhos e quando consultar os arquivos:

Antes de criar ou revisar artigos:
- Leia `articles/GUIA-DE-ESTILO-DO-AUTOR.md`.
- Use `articles/TEMPLATE-ARTIGO-TECNICO-IA.md` como ponto de partida para artigos técnicos.

Isso não obriga todo texto a seguir uma estrutura fixa. Tutoriais, relatos e artigos de opinião podem precisar de formatos diferentes. O agente deve consultar o guia, adaptar o template e confirmar com o autor qualquer experiência pessoal que não esteja registrada nas fontes.

Instrução não substitui revisão

Arquivos como AGENTS.md e CLAUDE.md orientam o comportamento do assistente; eles não garantem que cada instrução será seguida nem funcionam como controle de segurança. Continue revisando código e conteúdo, executando as verificações adequadas ao projeto e configurando permissões separadamente.

Conclusão

Registrar as orientações no repositório reduz a repetição entre sessões e permite que diferentes agentes encontrem o contexto necessário. Com um AGENTS.md compartilhado, um CLAUDE.md que o importa e um guia editorial separado, também fica mais simples preservar a escrita do autor enquanto o site passa a publicar sobre novas ferramentas.

Referências

• Custom instructions with AGENTS.md — OpenAI Codex — consulta em 12 out. 2026.
• How Claude remembers your project — Anthropic — consulta em 12 out. 2026.