Rules, AGENTS.md, CLAUDE.md
Você escreverá um conjunto pequeno de instruções persistentes para um repositório fictício. O objetivo é que outra pessoa ou assistente encontre comandos, padrões e limites sem precisar interpretar uma longa conversa. A entrega inclui exemplos de tarefas para avaliar o arquivo.
Primeiro escolha a ferramenta-alvo e confira seu mecanismo de descoberta. Se não houver ferramenta instalada, produza o desenho e as verificações locais, declarando que o carregamento real não foi testado. Um simulador de composição não substitui essa integração.
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: Leitura: Rules, AGENTS.md, CLAUDE.md
Inventariar regras existentes
FundamentosLeia scripts, convenções de moeda e limites de arquitetura antes de escrever. Separe o que é fato observável no código do que é decisão desejada para o projeto. Se o frontend hoje acessa diretamente uma tabela, não declare que a fronteira já é respeitada. Registre a discrepância e o plano autorizado para corrigi-la. Reúna apenas regras que influenciam tarefas recorrentes. Uma instrução que explica o comando de teste e a unidade monetária tende a ser mais útil que uma lista genérica de adjetivos sobre qualidade.
Escrever raiz e área
FundamentosNa raiz, indique estrutura, comandos gerais e como verificar alterações. Na área financeira, acrescente representação de moeda, política de autorização e referências ao contrato. Use frases observáveis: valores recebidos em reais são convertidos uma vez na fronteira; cálculos internos usam centavos. Inclua pré-requisitos dos testes sem credenciais. Confira se cada regra local complementa a geral ou entra em conflito. Se conflitar, reescreva a raiz ou explicite a exceção legítima conforme o mecanismo do produto, em vez de esperar que o agente adivinhe.
↗ Custom instructions with AGENTS.md↗ How Claude remembers your project
Avaliar descoberta e aplicação
FundamentosPrepare três tarefas: localizar testes, alterar cálculo de reembolso e inspecionar um componente frontend. Observe quais arquivos de instrução são carregados na ferramenta-alvo. Depois examine o resultado da tarefa, procurando unidade correta e respeito à fronteira. Pedir que o agente recite a regra só testa leitura, não aplicação. Quando uma regra não aparece, confira caminho, nome e configuração antes de aumentar o texto. Registre versão da ferramenta e escopo observado para que um colega consiga repetir a avaliação.
↗ Custom instructions with AGENTS.md↗ How Claude remembers your project
Manter e revisar
FundamentosAbra uma revisão do arquivo junto com as mudanças de scripts ou arquitetura que o afetam. Remova referências quebradas e instruções de migração que perderam validade. Para regras extensas, deixe um resumo e um link a documentação mantida. O arquivo não precisa carregar todo o manual em cada tarefa. Preserve a política de permissões no ambiente: dizer como testar não concede autorização para produção. A entrega final contém regras concisas, tarefas de avaliação e uma lista explícita de integrações não verificadas.
Testar um agente novo
AgentesFaça uma avaliação de retomada com um agente ou sessão que não recebeu a conversa de preparação. Forneça uma tarefa de cálculo monetário e observe se encontra instruções, usa centavos e executa verificações pertinentes. Registre o contexto efetivamente carregado quando a ferramenta permitir, sem exigir raciocínio privado. Compare com uma sessão em que os arquivos não estão disponíveis para identificar o benefício observado. O resultado não precisa ser uma promessa de obediência perfeita: a rubrica é comportamento no diff, comando executado e fronteira respeitada. Se houver falha, simplifique a regra ou corrija descoberta antes de repetir proibições. Esse teste conecta a entrega ao objetivo da fase: padrões recuperáveis sem reexplicar manualmente toda a arquitetura.
Caso adicional para diagnóstico e decisão
FundamentosIntroduza um conflito deliberado: a raiz pede valores em reais e a área financeira pede centavos. Escreva qual decisão você tomaria antes de consultar a ferramenta e justifique com o contrato de escopo. Depois verifique a precedência documentada do produto-alvo e resolva a contradição nos arquivos. Não deixe as duas regras contraditórias apenas esperando que a composição funcione. Faça uma tarefa que atravessa frontend e serviço: a interface recebe reais, a fronteira converte e o serviço calcula em centavos. A rubrica exige transição de unidade explícita e instruções complementares. Compare arquivo longo com resumo e referência a contrato mantido. O segundo reduz repetição, mas só funciona se a referência existe e o agente a consulta quando precisa. Preserve esse cenário na avaliação de retomada para detectar regressão na descoberta ou na interpretação do escopo.
↗ Custom instructions with AGENTS.md↗ How Claude remembers your project
Execução, inspeção e diagnóstico
FundamentosExecute a composição didática e confira os campos aplicáveis. Acrescente uma regra conflitante de moeda para perceber que sobrescrever um campo pode esconder um problema de documentação. Em seguida, escreva os arquivos para a ferramenta-alvo e faça a avaliação de descoberta quando houver acesso.
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});Se o agente usa floats apesar da regra, verifique se o arquivo foi carregado, se a tarefa está no escopo e se um exemplo contraditório influenciou a escolha. Se o comando falha, confira diretório e pré-requisitos. Corrija a causa concreta antes de acrescentar proibições repetidas.
Exercício aplicado
Entregue instruções de raiz e área com comandos verificáveis, padrões monetários e tarefas de avaliação.
- 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.
Regra: dois itens 500 centavos e taxa única 125. Escreva instrução de raiz/área e teste descoberta.
Conferir raciocínio e critérios de domínio
A raiz descreve o comando comum; a área financeira declara centavos e taxa única. O manual em reais precisa conversão explícita ou correção, pois não há duas unidades internas simultaneamente válidas.
O total é 500+500+125=1125 centavos, ou R$11,25. Aplicar a taxa a cada item gera 1250 e falha o teste do contrato.
O teste do cálculo detecta a diferença de 125 centavos. Ele não demonstra que o produto carregou as instruções; essa descoberta exige inspeção separada da execução.
Evidências para autoavaliação ou revisão por pares
- Escopo das instruções: A raiz descreve o comando comum; a área financeira declara centavos e taxa única. O manual em reais precisa conversão explícita ou correção, pois não há duas unidades internas simultaneamente válidas.
- Cálculo em centavos: O total é 500+500+125=1125 centavos, ou R$11,25. Aplicar a taxa a cada item gera 1250 e falha o teste do contrato.
- Descoberta separada: O teste do cálculo detecta a diferença de 125 centavos. Ele não demonstra que o produto carregou as instruções; essa descoberta exige inspeção separada da execução.
Um erro frequente
Regra mais próxima sempre vence.
Precedência depende do produto e do mecanismo documentado.
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.