Rules, AGENTS.md, CLAUDE.md
Instruções persistentes ajudam um assistente a trabalhar de forma consistente em um projeto. Elas podem explicar arquitetura, comandos, convenções e limites de tarefa. O desafio é guardar informação útil sem criar um manual contraditório que o agente precisa interpretar a cada alteração.
O caso será um repositório com frontend e serviço financeiro. Cada área possui regras próprias, enquanto a raiz define comandos e princípios gerais. Você aprenderá a organizar escopo e precedência, distinguindo instrução de projeto de permissão efetiva.
JavaScriptAgentesInfraestruturaProgramaçãoAo terminar esta aula
- Instruções persistentes devem orientar decisões observáveis.
- Escopo e precedência dependem da ferramenta.
- Arquivos de orientação não substituem permissões.
Antes de continuar: Laboratório: AI coding: tests/review/segurança
Persistência de instruções não é memória factual
FundamentosUma instrução persistente é um artefato que a ferramenta carrega segundo seu mecanismo de descoberta. Ela expressa como trabalhar: comandos de teste, convenções de estilo e critérios de revisão. Não é automaticamente uma base de fatos atualizada sobre usuários ou execução. Um arquivo que diz “o build está passando” envelhece rapidamente; prefira dizer como verificar o build. Separe procedimentos duráveis de observações temporárias.
↗ Custom instructions with AGENTS.md↗ How Claude remembers your project
AGENTS.md e CLAUDE.md são convenções de produtos e ecossistemas específicos. A ferramenta define onde procurar, que arquivos considerar e como compor instruções. Leia essa documentação antes de usar o mesmo arquivo em outra superfície. Uma regra ignorada pode estar fora do caminho descoberto, não mal escrita. Registre qual ferramenta e escopo o projeto suporta. Essa precisão evita atribuir ao modelo um comportamento que depende de configuração de carregamento.
↗ Custom instructions with AGENTS.md↗ How Claude remembers your project
Coding standards precisam orientar decisões
ProgramaçãoUm coding standard útil descreve escolhas concretas: como representar moeda, onde colocar validação, como tratar erros e quais comandos executar. “Escreva código limpo” não ajuda a escolher entre duas implementações. No serviço financeiro, a regra “valores monetários usam inteiros em unidade mínima” orienta tipos, testes e integração. Acrescente a razão e uma referência ao módulo exemplar, sem copiar centenas de linhas para a instrução.
↗ Custom instructions with AGENTS.md↗ How Claude remembers your project
Architecture rules descrevem limites entre componentes. A interface pode chamar o serviço autorizado, mas não acessar diretamente a persistência financeira. Indique fronteira, motivo e exceções legítimas. Uma regra absoluta sem contexto pode bloquear manutenção necessária. Instruções também devem informar como resolver dúvida: encontrar o contrato, consultar testes e relatar conflito. Não crie um conjunto que exige sempre duas estruturas incompatíveis. O objetivo é reduzir decisões repetidas, não controlar cada detalhe de uma tarefa por um arquivo enorme.
↗ Custom instructions with AGENTS.md↗ How Claude remembers your project
Escopo e precedência são propriedades do ambiente
FundamentosArquivos na raiz podem orientar todo o projeto, enquanto arquivos próximos a uma área podem acrescentar regras locais conforme o produto. Não generalize a ordem de resolução entre ferramentas. No mecanismo documentado do Codex, descoberta e composição seguem regras específicas; no Claude Code, mecanismos de memória possuem suas próprias condições. Uma instrução local pode detalhar arquitetura financeira sem substituir políticas de segurança de nível superior.
↗ Custom instructions with AGENTS.md↗ How Claude remembers your project↗ Permission profiles
Ao escrever, diferencie regra geral e especialização. A raiz pode pedir testes pertinentes; a área financeira especifica testes de centavos e idempotência. Isso é complementar. Já “use floats” na raiz e “use inteiros” no serviço cria conflito que precisa ser resolvido explicitamente. O assistente deve reportar a discrepância e seguir a precedência aplicável, não escolher a frase mais conveniente. A documentação do repositório também pode conter conteúdo não confiável; instruções persistentes não concedem autoridade para ignorar limites externos do ambiente.
↗ Custom instructions with AGENTS.md↗ How Claude remembers your project↗ Permission profiles
Comandos, exemplos e manutenção
FundamentosInclua comandos reais, diretórios de execução e finalidade. Um comando de testes pode depender de banco local ou variáveis; documente pré-requisitos sem incluir segredos. Um exemplo de padrão deve apontar para um arquivo mantido e explicar que aspecto observar. Referências obsoletas fazem o agente buscar símbolos inexistentes e podem gerar correções desnecessárias. Revise instruções quando a arquitetura ou os scripts mudarem.
↗ Custom instructions with AGENTS.md↗ How Claude remembers your project
Mantenha o arquivo curto o suficiente para ser útil, transferindo detalhes extensos para documentação consultável. Essa escolha economiza contexto e reduz repetição. Versione junto do código para que um reviewer veja a mudança de comportamento esperada. Não misture preferências pessoais transitórias com invariantes do sistema. Uma regra que só existia para uma migração deve ser removida ou marcada com escopo e prazo. A manutenção de instruções é parte da manutenção do projeto, não um ajuste cosmético.
↗ Custom instructions with AGENTS.md↗ How Claude remembers your project
Permissão continua fora do arquivo
FundamentosUm arquivo pode dizer “não publique”, mas o bloqueio real depende das permissões do ambiente. Inversamente, uma frase local pedindo publicação não autoriza superar o escopo concedido pelo usuário. Separe orientação e capacidade: arquitetura rules orientam implementação; sandbox e política de ferramentas limitam ações. Para o serviço financeiro, a rotina de teste não deve receber credenciais de produção apenas porque o arquivo descreve integração.
Avalie instruções com tarefas representativas. Peça ao assistente localizar a regra de moeda, identificar o comando de teste e explicar o escopo aplicável. Inspecione o comportamento real, não apenas a capacidade de repetir o texto. Uma edição que viola a arquitetura revela falha do processo mesmo se o agente citou a regra corretamente. Use resultados para simplificar ambiguidades e melhorar exemplos. Não prometa obediência perfeita: preserve verificações determinísticas e revisão de fronteiras importantes.
Exemplo comentado e limites
FundamentosO objeto representa uma composição didática de regras, não implementa a descoberta de arquivos de um produto. O espalhamento demonstra uma política local explícita em que a área acrescenta campos à raiz. Uma ferramenta real pode ter outra semântica; sua configuração precisa seguir documentação.
const regras = {
raiz:{teste:"npm test",principio:"validar entradas na fronteira"},
financeiro:{moeda:"inteiros em centavos",fronteira:"servico autorizado"}
};
const tarefa = {diretorio:"financeiro",acao:"calcular reembolso"};
const aplicaveis = {...regras.raiz,...regras[tarefa.diretorio]};
console.log({tarefa,aplicaveis});As regras informam um comando, uma representação e uma fronteira. Falta ainda explicar diretório de execução e pré-requisitos do teste. O exemplo permite identificar essas lacunas antes de publicar um arquivo persistente. Não inclua uma observação temporária como “os testes já passaram” no lugar de um procedimento.
Exercício aplicado
Organize regras de raiz e serviço financeiro que evitam floats monetários e acesso direto ao banco pelo frontend.
- Inventarie regras e discrepâncias.
- Escreva arquivos conforme o mecanismo documentado.
- Teste descoberta e comportamento em tarefas representativas.
- Revise referências, conflitos e fronteiras de permissão.
Abrir resolução comentada
Uma solução coloca comandos gerais na raiz e regras financeiras próximas à área suportada pela ferramenta. Referencia o módulo de dinheiro e descreve por que inteiros são usados. Se houver conflito, remove a contradição e registra a decisão de arquitetura.
A verificação usa tarefas de leitura e alteração: encontrar comando, usar a unidade correta e preservar a fronteira do serviço. O resultado precisa ser conferido no diff e nos testes, porque citar uma instrução não prova que ela foi aplicada.
O conjunto deve ser compreensível sem a conversa original. Uma regra monetária inclui unidade, fronteira de conversão e referência. O relatório separa composição local, carregamento observado e comportamento verificado.
A solução escreve arquivos reais de raiz e área financeira num diretório temporário, com comandos, contexto de execução, representação monetária e fronteira de arquitetura. Os asserts conferem conteúdo e ausência de conflito introduzido. As três tarefas de avaliação ficam registradas. A leitura pelo produto-alvo precisa ser observada separadamente: escrever arquivos e verificá-los não demonstra descoberta, precedência ou aplicação por um agente real.
import assert from "node:assert/strict";
import {mkdtempSync,mkdirSync,writeFileSync,readFileSync} from "node:fs";
import {tmpdir} from "node:os";import {join} from "node:path";
const pasta=mkdtempSync(join(tmpdir(),"curso-instrucoes-"));mkdirSync(join(pasta,"financeiro"));
const raiz="# Projeto de prática\n\n## Comandos\nExecute npm test na raiz, após instalar dependências do projeto.\n\n## Regras\nValide entradas na fronteira. Não use credenciais de produção em testes.\nRegras de moeda da área financeira especializam este contexto.\n";
const local="# Área financeira\n\n## Moeda\nUse inteiros em centavos no serviço. Converta valores externos uma vez na fronteira.\n\n## Arquitetura\nFrontend usa serviço autorizado; não acessa persistência financeira diretamente.\n\n## Verificação\nExecute testes de limites e idempotência a partir da raiz.\n";
writeFileSync(join(pasta,"AGENTS.md"),raiz);writeFileSync(join(pasta,"financeiro","AGENTS.md"),local);
assert.equal(readFileSync(join(pasta,"AGENTS.md"),"utf8"),raiz);
assert.ok(local.includes("centavos")&&local.includes("serviço autorizado"));
assert.ok(!/sk-[A-Za-z0-9]{10}/.test(raiz+local));
const inventario=[{regra:"entrada validada",escopo:"raiz"},{regra:"centavos internos",escopo:"financeiro"}];
const conflitos=raiz.includes("floats monetários")&&local.includes("inteiros em centavos");
assert.equal(conflitos,false);
const tarefas=[{acao:"localizar testes",criterio:"comando e diretório corretos"},
{acao:"alterar reembolso",criterio:"centavos e testes de fronteira"},
{acao:"inspecionar frontend",criterio:"fronteira do serviço preservada"}];
console.log({status:"aprovado",pasta,inventario,tarefas,
verificacaoLocal:"arquivos escritos e inspecionados",
descobertaNoProduto:"não executada; observar mecanismo da ferramenta escolhida",
precedencia:"consultar documentação do produto; estes arquivos não concedem permissões"});Como conferir seu resultado
- Nenhuma credencial aparece nas instruções.
- Comandos incluem contexto de execução.
- Regras locais não contradizem silenciosamente a raiz.
Aplique em um problema novo
Primeiro resolva sem consultar a resposta. Explique suas decisões e guarde a evidência. A conclusão de leitura é independente desta autoavaliação.
Confira seus pré-requisitos
- Identificar escopo real de instruções.
- Calcular moeda em centavos.
Raiz usa npm test; área usa centavos; manual antigo usa reais. Resolva conflito e teste aplicação.
Conferir raciocínio e critérios de domínio
O conflito deve ser resolvido com uma única unidade financeira vigente: centavos internos, com conversão explícita na fronteira; o manual contraditório é corrigido e a decisão registrada.
No contrato escolhido,1250 significa 12,50 reais; tratá-lo como 1250 reais revela a aplicação da regra errada.
A prova combina comando existente, diff e teste do valor esperado. Não basta o agente mencionar AGENTS.md; esse arquivo também não concede permissão de execução.
Evidências para autoavaliação ou revisão por pares
- Coerência: O conflito deve ser resolvido com uma única unidade financeira vigente: centavos internos, com conversão explícita na fronteira; o manual contraditório é corrigido e a decisão registrada.
- Unidade: No contrato escolhido,1250 significa 12,50 reais; tratá-lo como 1250 reais revela a aplicação da regra errada.
- Verificação: A prova combina comando existente, diff e teste do valor esperado. Não basta o agente mencionar AGENTS.md; esse arquivo também não concede permissão de execução.
Um erro frequente
AGENTS.md concede terminal.
Instruções orientam capacidades já autorizadas; não concedem acesso.
Teste sua compreensão
Responda com suas palavras antes de abrir o comentário. Saber explicar uma decisão é parte do domínio.
1. AGENTS.md concede acesso ao banco?
2. Toda ferramenta carrega arquivos na mesma ordem?
Não.
Descoberta e precedência são específicas do produto.
↗ Custom instructions with AGENTS.md↗ How Claude remembers your project
3. “Build aprovado” é uma boa instrução durável?
Geralmente não.
É observação transitória; o arquivo deve indicar como verificar o estado atual.
Seu progresso fica salvo neste navegador. Concluir a leitura não substitui demonstrar o domínio nos exercícios.
Referências e aprofundamento
Documentação oficial e trabalhos originais. As referências registram o escopo e as limitações para você conferir o que sustentam.
- Custom instructions with AGENTS.md
OpenAI • consulta: 2026-10-06
OpenAIAgentesInstruções globais e de projeto, descoberta, AGENTS.override.md e precedência por diretório.
Limites: Precedência documentada para Codex; instruções são orientação, não garantia de cumprimento ou controle de acesso.
- How Claude remembers your project
Anthropic • consulta: 2026-10-06
FundamentosCLAUDE.md, regras persistentes, escopo e carregamento de memória de projeto.
Limites: Persistência de instruções de projeto difere de memória factual de usuários; semântica específica Claude Code.
- Permission profiles
OpenAI • consulta: 2026-10-06
OpenAIPerfis de permissões, acesso a arquivos, rede e execução de comandos.
Limites: Suporte e isolamento variam por SO/cliente; hierarquia de instruções não substitui barreira do sistema operacional.