[{"data":1,"prerenderedAt":2417},["ShallowReactive",2],{"blog-post-agents-md-best-practices-pt-br":3,"related-posts-agents-md-best-practices-pt-br":2390},{"id":4,"title":5,"author":6,"body":12,"category":2360,"date":2361,"description":2362,"extension":50,"featured":2363,"hideToc":69,"image":2364,"imageAlt":5,"imageHeight":2365,"imageWidth":2366,"itemList":2367,"lang":2368,"meta":2369,"navigation":69,"noindex":2363,"path":2371,"readingTime":2372,"redirected":2363,"relatedSlugs":2367,"seo":2373,"seoTitle":2374,"stem":2375,"subtitle":2376,"tags":2377,"updatedDate":2388,"__hash__":2389},"blog/blog/agents-md-best-practices-pt-br.md","AGENTS.md Boas Práticas: Qual Deve Ser o Tamanho, Modelo e Exemplos",{"name":7,"role":8,"avatar":9,"url":10,"bio":11},"Shabnam Katoch","Growth Head","/img/avatars/shabnam-profile.jpeg","https://www.betterclaw.io/about","Shabnam leads growth at BetterClaw and has spent the past three years building organic distribution for AI-native products. She writes about no-code agent builders, content strategy, and what it actually takes to grow without an ads budget.",{"type":13,"value":14,"toc":2311},"minimark",[15,27,40,45,183,191,204,207,210,213,216,224,227,230,233,316,319,328,331,334,356,363,367,370,381,384,389,392,395,398,402,405,423,426,430,433,437,440,444,453,457,473,477,489,497,500,504,507,540,543,549,553,556,564,567,589,592,616,619,623,629,633,641,644,647,651,654,662,665,766,769,773,776,779,783,786,789,792,796,799,805,811,830,841,844,850,853,858,861,879,920,923,1024,1030,1036,1040,1052,1065,1088,1098,1104,1111,1115,1118,1126,1170,1179,1201,1214,1217,1223,1227,1230,1239,1245,1255,1258,1262,1270,1345,1353,1372,1376,1379,1386,1390,1399,1402,1416,1420,1423,1426,1432,1470,1488,1493,1497,1500,1781,1784,1788,1791,1795,1881,1888,1892,2032,2035,2039,2178,2181,2184,2188,2191,2202,2206,2210,2217,2221,2224,2228,2231,2235,2241,2245,2263,2267,2276,2280,2283,2287,2293,2297,2300,2304,2307],[16,17,18,19,26],"p",{},"AGENTS.md é um arquivo Markdown na raiz de um repositório de código que instrui agentes de programação com IA sobre como trabalhar naquele projeto: stack, comandos de build e teste, estilo de código, restrições de arquitetura e limites. A página ",[20,21,25],"a",{"href":22,"rel":23},"https://agents.md",[24],"nofollow","agents.md"," lista mais de 20 ferramentas que o leem, incluindo OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Jules, Zed, Windsurf, Devin, Aider e opencode. Claude Code também o lê, embora por padrão só quando o projeto não possui um CLAUDE.md.",[28,29,32],"callout",{"label":30,"type":31},"Qual deve ser o tamanho do AGENTS.md?","quick-answer",[16,33,34,35,39],{},"Mire em ",[36,37,38],"strong",{},"menos de 100 linhas"," e considere 150 como o ponto em que é preciso começar a deletar. O próprio limite da Anthropic para CLAUDE.md é de 200 linhas, e o Codex para de carregar arquivos de instruções quando o total chega a 32 KiB. Arquivos menores custam menos e são mais fáceis de seguir para o agente. Adicione uma regra só quando um agente errar e delete-a quando o agente acertar sem que você precise instruí-lo.",[41,42,44],"h2",{"id":43},"modelo-mínimo-de-agentsmd-copie-este","Modelo mínimo de AGENTS.md (copie este)",[46,47,52],"pre",{"className":48,"code":49,"language":50,"meta":51,"style":51},"language-md shiki shiki-themes github-light","# AGENTS.md\n\n## Project overview\nNext.js 15 App Router, React 19, TypeScript, Tailwind CSS, Drizzle ORM.\n\n## Setup\nInstall: `pnpm install`  ·  Env: copy `.env.example` to `.env.local`\n\n## Build and test\nBuild: `pnpm build`  ·  Test: `pnpm test`  ·  Lint: `pnpm lint --fix`\n\n## Code style\nFunctional components with hooks only. Named exports only.\n\n## Boundaries\nNever edit files in /generated/. Never commit .env or secrets.\n","md","",[53,54,55,64,71,77,84,89,95,117,122,128,149,154,160,166,171,177],"code",{"__ignoreMap":51},[56,57,60],"span",{"class":58,"line":59},"line",1,[56,61,63],{"class":62},"surfw","# AGENTS.md\n",[56,65,67],{"class":58,"line":66},2,[56,68,70],{"emptyLinePlaceholder":69},true,"\n",[56,72,74],{"class":58,"line":73},3,[56,75,76],{"class":62},"## Project overview\n",[56,78,80],{"class":58,"line":79},4,[56,81,83],{"class":82},"sgsFI","Next.js 15 App Router, React 19, TypeScript, Tailwind CSS, Drizzle ORM.\n",[56,85,87],{"class":58,"line":86},5,[56,88,70],{"emptyLinePlaceholder":69},[56,90,92],{"class":58,"line":91},6,[56,93,94],{"class":62},"## Setup\n",[56,96,98,101,105,108,111,114],{"class":58,"line":97},7,[56,99,100],{"class":82},"Install: ",[56,102,104],{"class":103},"sYu0t","`pnpm install`",[56,106,107],{"class":82},"  ·  Env: copy ",[56,109,110],{"class":103},"`.env.example`",[56,112,113],{"class":82}," to ",[56,115,116],{"class":103},"`.env.local`\n",[56,118,120],{"class":58,"line":119},8,[56,121,70],{"emptyLinePlaceholder":69},[56,123,125],{"class":58,"line":124},9,[56,126,127],{"class":62},"## Build and test\n",[56,129,131,134,137,140,143,146],{"class":58,"line":130},10,[56,132,133],{"class":82},"Build: ",[56,135,136],{"class":103},"`pnpm build`",[56,138,139],{"class":82},"  ·  Test: ",[56,141,142],{"class":103},"`pnpm test`",[56,144,145],{"class":82},"  ·  Lint: ",[56,147,148],{"class":103},"`pnpm lint --fix`\n",[56,150,152],{"class":58,"line":151},11,[56,153,70],{"emptyLinePlaceholder":69},[56,155,157],{"class":58,"line":156},12,[56,158,159],{"class":62},"## Code style\n",[56,161,163],{"class":58,"line":162},13,[56,164,165],{"class":82},"Functional components with hooks only. Named exports only.\n",[56,167,169],{"class":58,"line":168},14,[56,170,70],{"emptyLinePlaceholder":69},[56,172,174],{"class":58,"line":173},15,[56,175,176],{"class":62},"## Boundaries\n",[56,178,180],{"class":58,"line":179},16,[56,181,182],{"class":82},"Never edit files in /generated/. Never commit .env or secrets.\n",[16,184,185,186,190],{},"Substitua pelo seu próprio stack e comandos, mantenha o arquivo curto e adicione seções apenas quando um agente errar. ",[20,187,189],{"href":188},"#the-annotated-template-copy-and-adapt","A versão anotada"," mais adiante explica o que vai em cada seção.",[16,192,193,194,197,198,203],{},"O formato está definido em ",[20,195,25],{"href":22,"rel":196},[24]," e mantido no GitHub (",[20,199,202],{"href":200,"rel":201},"https://github.com/agentsmd/agents.md",[24],"agentsmd/agents.md","). Mais de 60.000 projetos open source o utilizam, e ele agora está sob a tutela da Agentic AI Foundation, parte da Linux Foundation. Ainda assim, a maioria dos arquivos AGENTS.md é muito longa, muito vaga ou gerada por um LLM — o que piora o agente. Aqui explicamos como escrever um que funcione e continue funcionando.",[16,205,206],{},"Nosso agente de programação gerava componentes de classe sem parar. Toda a base de código era React funcional com hooks. O README dizia \"React 19, functional components\". O guia de contribuição explicava isso com detalhes.",[16,208,209],{},"O agente não leu o README. Ele não sabe que deveria fazer isso.",[16,211,212],{},"Aí adicionamos um arquivo AGENTS.md com uma única linha na seção de estilo: Always use functional components with hooks. Never use class components. Junto com um exemplo de código mostrando o jeito correto.",[16,214,215],{},"O problema desapareceu imediatamente.",[16,217,218,219,223],{},"Trabalhando com mais de um agente? Leia como ",[20,220,222],{"href":221},"/blog/agents-md-multi-agent-best-practices","organizar o AGENTS.md para múltiplos agentes"," sem conflitos nem desvios.",[41,225,30],{"id":226},"qual-deve-ser-o-tamanho-do-agentsmd",[16,228,229],{},"Resposta curta: menos de 100 linhas é o objetivo, 150 é o sinal de alerta e 200 é o limite máximo que a Anthropic estabelece para o seu próprio equivalente. Na prática, a maioria dos bons arquivos tem entre 30 e 80 linhas.",[16,231,232],{},"De onde vem cada número (cada um mede algo diferente, verificado em 23 de outubro de 2026):",[234,235,236,252],"table",{},[237,238,239],"thead",{},[240,241,242,246,249],"tr",{},[243,244,245],"th",{},"Fonte",[243,247,248],{},"O que diz",[243,250,251],{},"O que mede",[253,254,255,271,290,305],"tbody",{},[240,256,257,265,268],{},[258,259,260],"td",{},[20,261,264],{"href":262,"rel":263},"https://code.claude.com/docs/en/memory",[24],"Documentação de memória do Claude Code da Anthropic",[258,266,267],{},"\"Mire em menos de 200 linhas por arquivo CLAUDE.md. Arquivos mais longos consomem mais contexto e reduzem o seguimento.\" O Claude Code exibe um aviso ao iniciar se um arquivo ultrapassar o limite recomendado.",[258,269,270],{},"Recomendação oficial para CLAUDE.md, que cumpre o mesmo papel que AGENTS.md",[240,272,273,280,287],{},[258,274,275],{},[20,276,279],{"href":277,"rel":278},"https://developers.openai.com/codex/guides/agents-md",[24],"OpenAI Codex",[258,281,282,283,286],{},"Para de adicionar arquivos de instruções quando o tamanho total atinge ",[53,284,285],{},"project_doc_max_bytes",", por padrão 32 KiB",[258,288,289],{},"Um limite de carregamento estrito para toda a cadeia de arquivos, não um objetivo de qualidade",[240,291,292,299,302],{},[258,293,294],{},[20,295,298],{"href":296,"rel":297},"https://arxiv.org/abs/2602.11988",[24],"Estudo da ETH de Zurique (arXiv:2602.11988)",[258,300,301],{},"Arquivos de contexto \"não melhoram a taxa de sucesso em tarefas em geral, mas aumentam os custos de inferência em mais de 20% em média\"",[258,303,304],{},"Custo e sucesso de arquivos de contexto em geral, não do tamanho especificamente",[240,306,307,310,313],{},[258,308,309],{},"Fóruns de desenvolvimento (outubro de 2026)",[258,311,312],{},"Arquivos que crescem a centenas de linhas costumam ser ignorados; o consenso prático é menos de 100 linhas",[258,314,315],{},"Experiência prática, não um estudo controlado",[16,317,318],{},"Por que dizemos menos de 100 se a Anthropic diz 200? Porque cada linha é carregada em cada sessão, cada linha custa tokens a cada execução e quase cada linha além das primeiras 50 é uma regra que o modelo já seguiria de qualquer forma. A equipe da ETH de Zurique descobriu que resumos de repositório — o que provedores de modelos recomendam incluir com mais frequência — basicamente não serviam de nada, porque os agentes leem a base de código diretamente. Remova-os e a maioria dos arquivos fica bem abaixo de 100 linhas.",[16,320,321,322,327],{},"Duas limitações honestas. Primeiro: um estudo controlado de Damon McMillan de 2026 (",[20,323,326],{"href":324,"rel":325},"https://arxiv.org/abs/2605.10039",[24],"arXiv:2605.10039",", 1.650 sessões do Claude Code, 16.050 observações) descobriu que, para uma única regra simples de estilo de código, nem o tamanho do arquivo nem a posição da regra nem dividir o arquivo nem um arquivo contraditório numa pasta adjacente produziam diferença mensurável no seguimento. O que importava era a tarefa e o quanto o agente já tinha avançado na sessão: cada função adicional que ele escrevia estava associada a cerca de 5,6% a menos de chance de seguir a regra. Tamanho, portanto, não é mágico. Segundo: esse estudo testou uma única regra trivial em modelos Claude. Arquivos reais contêm dezenas de regras competindo pela atenção, e é exatamente aí que o aviso da Anthropic sobre seguimento entra em cena.",[16,329,330],{},"A leitura prática: um arquivo curto não conserta uma tarefa mal feita, mas um arquivo longo torna qualquer tarefa mais cara e dá ao agente mais oportunidades de ignorar justamente a regra que importa.",[16,332,333],{},"Sinais de que seu AGENTS.md é longo demais:",[335,336,337,341,344,347,350,353],"ul",{},[338,339,340],"li",{},"Ele explica por que você escolheu seu stack ou descreve a história do projeto.",[338,342,343],{},"Contém uma árvore de diretórios ou uma lista de dependências que o agente poderia ler diretamente do repositório.",[338,345,346],{},"Inclui um procedimento em múltiplas etapas (uma checklist de release, um runbook de migração). Isso pertence a uma skill que só é carregada quando necessário.",[338,348,349],{},"Você encontra duas regras que dizem coisas diferentes sobre o mesmo comportamento.",[338,351,352],{},"O Claude Code avisa ao iniciar, ou o Codex descarta silenciosamente arquivos além de 32 KiB.",[338,354,355],{},"Você não se lembra mais por que metade das regras existe.",[16,357,358],{},[359,360],"img",{"alt":361,"src":362},"A tabela nutricional do AGENTS.md: menos de 100 linhas no total, com stack, comandos, estilo de código com exemplos, limites e uma seção git curta.","/img/blog/agents-md-best-practices-nutrition-label.jpg",[41,364,366],{"id":365},"o-que-entra-em-um-agentsmd-e-o-que-não-entra","O que entra em um AGENTS.md (e o que não entra)",[16,368,369],{},"O erro comum é tratar o AGENTS.md como documentação. Explicações longas. Filosofia de arquitetura. Justificativas de design. História do projeto.",[16,371,372,373,376,377,380],{},"Seu agente não precisa saber por que você escolheu Next.js em vez de Remix. Ele precisa saber que você usa Next.js 15 com App Router e que o comando de teste é ",[53,374,375],{},"pnpm test",", não ",[53,378,379],{},"npm test",".",[16,382,383],{},"Estas são as seções que importam, na ordem em que devem aparecer:",[385,386,388],"h3",{"id":387},"stack-do-projeto-5-a-10-linhas","Stack do projeto (5 a 10 linhas)",[16,390,391],{},"Linguagem, framework, dependências principais, runtime. Seja específico.",[16,393,394],{},"Bom: Next.js 15 App Router, React 19, TypeScript 5.4, Tailwind CSS, Drizzle ORM, Bun",[16,396,397],{},"Ruim: Esta é uma aplicação web moderna construída com React e várias bibliotecas de suporte.",[385,399,401],{"id":400},"comandos-de-build-e-teste-5-a-10-linhas","Comandos de build e teste (5 a 10 linhas)",[16,403,404],{},"Comandos exatos com flags exatas. O gerenciador de pacotes importa. Os targets de build importam.",[16,406,407,408,411,412,415,416,419,420],{},"Bom: Build: ",[53,409,410],{},"bun run build",". Test: ",[53,413,414],{},"bun test",". Lint: ",[53,417,418],{},"bun run lint --fix",". Deploy: ",[53,421,422],{},"bun run deploy:staging",[16,424,425],{},"Ruim: Execute os comandos habituais de build e teste conforme descrito no package.json.",[385,427,429],{"id":428},"convenções-de-estilo-de-código-10-a-20-linhas-com-exemplos","Convenções de estilo de código (10 a 20 linhas, com exemplos)",[16,431,432],{},"Um exemplo de código por convenção vale mais que três parágrafos de descrição. Esta é a lição mais importante dos arquivos AGENTS.md eficazes. Mostrar, não contar.",[385,434,436],{"id":435},"restrições-de-arquitetura-5-a-15-linhas","Restrições de arquitetura (5 a 15 linhas)",[16,438,439],{},"Regras de estrutura de diretórios. Limites de módulos. Restrições de importação. Direção do fluxo de dados.",[385,441,443],{"id":442},"limites-5-a-10-linhas","Limites (5 a 10 linhas)",[16,445,446,447,452],{},"O que o agente nunca deve tocar. \"Nunca fazer commit de secrets\" foi a restrição útil mais frequente na ",[20,448,451],{"href":449,"rel":450},"https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/",[24],"análise do GitHub de mais de 2.500 arquivos agents.md",". Adicione: arquivos gerados, módulos legados, arquivos de configuração que não devem mudar e diretórios gerenciados por outras ferramentas.",[385,454,456],{"id":455},"fluxo-de-trabalho-do-git-5-linhas","Fluxo de trabalho do Git (5 linhas)",[16,458,459,460,463,464,463,467,463,470,380],{},"Nomes de branches, formato de mensagens de commit, convenções de PR. Apenas squash merge. Conventional Commits: ",[53,461,462],{},"feat:",", ",[53,465,466],{},"fix:",[53,468,469],{},"chore:",[53,471,472],{},"docs:",[385,474,476],{"id":475},"o-que-deixar-de-fora","O que deixar de fora",[16,478,479,480,484,485,380],{},"Procedimentos de múltiplas etapas (uma checklist de release, um runbook de migração) não pertencem a um arquivo carregado em cada sessão. A documentação de memória da Anthropic diz o mesmo sobre CLAUDE.md: mova-os para uma skill que o agente só carrega quando a tarefa exige. Nosso guia ",[20,481,483],{"href":482},"/blog/agent-skills-vs-mcp","Agent Skills vs. MCP"," explica onde traçar essa linha, e o carregamento sob demanda é uma razão importante pela qual ",[20,486,488],{"href":487},"/blog/skills-that-reduce-token-usage","as skills podem reduzir o uso de tokens",[16,490,491,492,496],{},"Conexões de ferramentas também não vão aqui. Esses são servidores MCP configurados na própria ferramenta (veja ",[20,493,495],{"href":494},"/blog/what-is-mcp-model-context-protocol","o que é MCP","). AGENTS.md pode dizer quando usar uma ferramenta, não como se conectar a ela.",[16,498,499],{},"Regras que nunca podem ser quebradas também não pertencem aqui. AGENTS.md é orientação, não imposição. Se algo deve sempre acontecer antes de cada commit ou nunca deve acontecer, use um pre-commit hook, um hook do Claude Code ou uma regra de permissão. O arquivo pode explicar a regra; o hook a impõe.",[41,501,503],{"id":502},"o-ciclo-de-vida-das-regras-adicione-quando-quebrar-apague-quando-aprendido","O ciclo de vida das regras: adicione quando quebrar, apague quando aprendido",[16,505,506],{},"Esse hábito mantém um AGENTS.md curto por anos, não apenas semanas.",[508,509,510,516,522,528,534],"ol",{},[338,511,512,515],{},[36,513,514],{},"Comece com 30 a 50 linhas:"," stack, comandos, estilo de código com um exemplo cada, limites.",[338,517,518,521],{},[36,519,520],{},"Adicione uma regra apenas quando um agente errar mais de uma vez."," Um erro pode ser da tarefa; dois são uma lacuna no arquivo.",[338,523,524,527],{},[36,525,526],{},"Formule a regra como uma diretiva com exemplo, não como uma explicação."," \"Money is Decimal, never float\" vale mais que um parágrafo sobre precisão.",[338,529,530,533],{},[36,531,532],{},"Teste sem a regra a cada poucas semanas ou após uma atualização de modelo."," Delete a linha e execute o mesmo tipo de tarefa. Se o agente acertar sem instruções, a regra é peso morto. Modelos mais novos seguem por conta própria muitas convenções que os mais antigos precisavam que escrevessem explicitamente.",[338,535,536,539],{},[36,537,538],{},"Revise o arquivo inteiro a cada trimestre,"," e no mesmo PR quando uma convenção mudar.",[16,541,542],{},"Um teste útil para cada linha: um desenvolvedor competente que nunca viu esse repositório cometeria esse erro? Se não, delete. Você está pagando tokens para prever ao modelo seus próprios valores padrão.",[16,544,545],{},[359,546],{"alt":547,"src":548},"Trate o AGENTS.md como um bonsai: adicione quando quebrar, pode quando aprender.","/img/blog/agents-md-best-practices-bonsai-pt.jpg",[41,550,552],{"id":551},"regras-contraditórias-fazem-mais-estrago-que-regras-duplicadas","Regras contraditórias fazem mais estrago que regras duplicadas",[16,554,555],{},"Uma regra duplicada desperdiça alguns tokens. Uma contradição torna o comportamento do agente imprevisível, porque ele precisa escolher um lado e você não controla qual.",[16,557,558,559,563],{},"A Anthropic diz isso diretamente em sua ",[20,560,562],{"href":262,"rel":561},[24],"documentação de memória",": \"Se duas instruções se contradizem, o Claude pode escolher uma arbitrariamente.\" Isso se aplica entre arquivos também: seu arquivo raiz, um arquivo de subdiretório, um arquivo global pessoal e quaisquer arquivos de regras terminam no mesmo contexto.",[16,565,566],{},"Onde as contradições costumam se esconder:",[335,568,569,572,583,586],{},[338,570,571],{},"Um arquivo raiz que diz \"use Jest\" e o arquivo de um pacote que diz \"use Vitest\" sem especificar que é só para aquele pacote.",[338,573,574,575,578,579,582],{},"Seu arquivo global pessoal (",[53,576,577],{},"~/.codex/AGENTS.md"," ou ",[53,580,581],{},"~/.claude/CLAUDE.md",") com uma regra específica do projeto que está errada em outros repositórios.",[338,584,585],{},"Uma regra antiga que nunca foi deletada após uma migração (\"use the v1 API client\").",[338,587,588],{},"Uma regra e sua exceção em seções diferentes.",[16,590,591],{},"Como encontrá-las:",[335,593,594,604,610],{},[338,595,596,603],{},[36,597,598,599,602],{},"Execute ",[53,600,601],{},"/doctor prompt-audit"," no Claude Code"," (versão 2.1.283 em diante). A documentação da Anthropic o descreve como uma verificação que \"encontra instruções para modelos mais antigos, referências a arquivos ou comandos inexistentes e arquivos que se contradizem\", e sugere mudanças sem alterar nada até que você aprove. Por padrão cobre seus arquivos CLAUDE.md, CLAUDE.local.md e AGENTS.md.",[338,605,606,609],{},[36,607,608],{},"Em qualquer ferramenta, você pode perguntar ao agente:"," \"List every instruction you've been given about testing, and flag any two that conflict.\"",[338,611,612,615],{},[36,613,614],{},"Escreva regras de subdiretórios como especializações"," (\"este pacote usa Vitest\"), nunca como inversões do arquivo raiz.",[16,617,618],{},"Um detalhe por precisão: o estudo de McMillan mencionado antes descobriu que um arquivo contraditório numa pasta adjacente não tinha efeito mensurável sobre uma única regra trivial. Isso não torna as contradições inofensivas. Significa que o dano surge quando regras competem, e é exatamente isso que um arquivo em crescimento descontrolado cria.",[41,620,622],{"id":621},"os-três-erros-que-tornam-o-agentsmd-inútil","Os três erros que tornam o AGENTS.md inútil",[16,624,625],{},[359,626],{"alt":627,"src":628},"Os três erros do AGENTS.md: Gerado por um LLM, Descreve em vez de mostrar, Nunca é atualizado.","/img/blog/agents-md-best-practices-hall-of-shame-pt.jpg",[385,630,632],{"id":631},"erro-1-deixar-um-llm-gerá-lo","Erro 1: deixar um LLM gerá-lo",[16,634,635,636,640],{},"É o mais comum e o mais prejudicial. No ",[20,637,639],{"href":296,"rel":638},[24],"estudo da ETH de Zurique",", arquivos gerados por LLM reduziram o sucesso em 0,5% no SWE-bench Lite e em 2% no AGENTbench, perderam em 5 de 8 cenários e adicionaram entre 2,45 e 3,92 passos extras por tarefa. Arquivos escritos por desenvolvedores foram melhores (cerca de +4% no AGENTbench), mas também custaram até 19% a mais.",[16,642,643],{},"Por quê? LLMs geram instruções genéricas e prolixas que dizem o óbvio. \"Follow best practices for error handling.\" \"Write clean, maintainable code.\" \"Use descriptive variable names.\" Seu agente já sabe tudo isso.",[16,645,646],{},"Escreva seu AGENTS.md à mão. Se usar um agente para fazer um rascunho, trate-o como o primeiro PR de um funcionário novo: delete tudo o que for genérico e mantenha apenas o que for específico do seu projeto.",[385,648,650],{"id":649},"erro-2-descrever-convenções-em-vez-de-mostrá-las","Erro 2: descrever convenções em vez de mostrá-las",[16,652,653],{},"Ruim:",[46,655,660],{"className":656,"code":658,"language":659},[657],"language-text","Use our custom error handling approach where errors bubble up through\nthe service layer and are caught by the global error handler rather\nthan being caught at individual function level.\n","text",[53,661,658],{"__ignoreMap":51},[16,663,664],{},"Bom:",[46,666,670],{"className":667,"code":668,"language":669,"meta":51,"style":51},"language-js shiki shiki-themes github-light","// Error handling: Let errors propagate. Do not wrap individual calls\n// in try/catch. The global handler catches everything.\n\n// CORRECT\nasync function getUser(id) {\n  const user = await db.users.findById(id);\n  return user;\n}\n\n// WRONG\nasync function getUser(id) {\n  try {\n    const user = await db.users.findById(id);\n    return user;\n  } catch (e) {\n    logger.error(e);\n    throw e;\n  }\n}\n","js",[53,671,672,677,682,686,691,696,701,706,711,715,720,724,729,734,739,744,749,755,761],{"__ignoreMap":51},[56,673,674],{"class":58,"line":59},[56,675,676],{},"// Error handling: Let errors propagate. Do not wrap individual calls\n",[56,678,679],{"class":58,"line":66},[56,680,681],{},"// in try/catch. The global handler catches everything.\n",[56,683,684],{"class":58,"line":73},[56,685,70],{"emptyLinePlaceholder":69},[56,687,688],{"class":58,"line":79},[56,689,690],{},"// CORRECT\n",[56,692,693],{"class":58,"line":86},[56,694,695],{},"async function getUser(id) {\n",[56,697,698],{"class":58,"line":91},[56,699,700],{},"  const user = await db.users.findById(id);\n",[56,702,703],{"class":58,"line":97},[56,704,705],{},"  return user;\n",[56,707,708],{"class":58,"line":119},[56,709,710],{},"}\n",[56,712,713],{"class":58,"line":124},[56,714,70],{"emptyLinePlaceholder":69},[56,716,717],{"class":58,"line":130},[56,718,719],{},"// WRONG\n",[56,721,722],{"class":58,"line":151},[56,723,695],{},[56,725,726],{"class":58,"line":156},[56,727,728],{},"  try {\n",[56,730,731],{"class":58,"line":162},[56,732,733],{},"    const user = await db.users.findById(id);\n",[56,735,736],{"class":58,"line":168},[56,737,738],{},"    return user;\n",[56,740,741],{"class":58,"line":173},[56,742,743],{},"  } catch (e) {\n",[56,745,746],{"class":58,"line":179},[56,747,748],{},"    logger.error(e);\n",[56,750,752],{"class":58,"line":751},17,[56,753,754],{},"    throw e;\n",[56,756,758],{"class":58,"line":757},18,[56,759,760],{},"  }\n",[56,762,764],{"class":58,"line":763},19,[56,765,710],{},[16,767,768],{},"O exemplo de código transmite instantaneamente o que três parágrafos de descrição não conseguem.",[385,770,772],{"id":771},"erro-3-não-atualizá-lo","Erro 3: não atualizá-lo",[16,774,775],{},"Um AGENTS.md com nomes de tabelas obsoletos, comandos descontinuados ou restrições de arquitetura superadas é pior do que não ter nenhum. Ele leva o agente ativamente pelo caminho errado.",[16,777,778],{},"Atualize-o no mesmo PR em que as convenções mudam e siga o ciclo de vida de regras descrito acima. Se um agente produz repetidamente a mesma saída incorreta, há uma lacuna no seu arquivo. Se ele produz a saída correta sem a regra, há uma linha a deletar.",[41,780,782],{"id":781},"o-agentsmd-realmente-funciona","O AGENTS.md realmente funciona?",[16,784,785],{},"Sim, mas apenas a variante escrita à mão e específica.",[16,787,788],{},"O ceticismo é legítimo. Se você deixou um agente escrever seu AGENTS.md, executou e não viu melhoria, isso é exatamente o que a pesquisa prevê. Os autores da ETH de Zurique descobriram que os agentes seguem bem as instruções nesses arquivos. O problema é que a maioria dos arquivos está cheia de instruções que não mudam nada.",[16,790,791],{},"O que funciona é restrito: instruções que dizem ao agente algo que ele não poderia ter deduzido da base de código. Seu gerenciador de pacotes. Seu comando de teste com as flags exatas. O único diretório que ele nunca deve tocar. A convenção da sua base de código que parece incomum para um modelo treinado com o código de todo mundo.",[41,793,795],{"id":794},"agentsmd-vs-claudemd-vs-cursorrules-qual-você-precisa","AGENTS.md vs CLAUDE.md vs .cursorrules (qual você precisa?)",[16,797,798],{},"Comece com AGENTS.md e adicione arquivos específicos de cada ferramenta apenas quando precisar de suas funções especiais.",[16,800,801],{},[359,802],{"alt":803,"src":804},"Um núcleo universal e três arquivos: AGENTS.md, CLAUDE.md e .cursorrules.","/img/blog/agents-md-best-practices-file-comparison-pt.jpg",[16,806,807,810],{},[36,808,809],{},"AGENTS.md"," tem a compatibilidade mais ampla. Mais de 20 ferramentas o leem nativamente. É o formato universal.",[16,812,813,816,817,820,821,824,825,829],{},[36,814,815],{},"CLAUDE.md"," é o arquivo próprio do Claude Code. Ele traz funcionalidades que AGENTS.md não tem, como importações ",[53,818,819],{},"@path"," e arquivos ",[53,822,823],{},".claude/rules/"," adaptados a tipos de arquivo. Você não precisa mais dele para o Claude Code ver seu AGENTS.md (veja ",[20,826,828],{"href":827},"#how-claude-code-reads-agentsmd","Como o Claude Code lê o AGENTS.md"," abaixo), mas assim que um CLAUDE.md existe, o Claude Code para de ler AGENTS.md por padrão. Se mantiver ambos, faça o CLAUDE.md importar o arquivo compartilhado:",[46,831,835],{"className":832,"code":833,"language":834,"meta":51,"style":51},"language-markdown shiki shiki-themes github-light","@AGENTS.md\n","markdown",[53,836,837],{"__ignoreMap":51},[56,838,839],{"class":58,"line":59},[56,840,833],{"class":82},[16,842,843],{},"Mantenha AGENTS.md como única fonte de verdade para todas as ferramentas, e que CLAUDE.md contenha esse import mais as personalizações do Claude que você realmente precisar. Note que imports organizam um arquivo mas não o enxugam: a documentação da Anthropic aponta que arquivos importados são carregados junto com o CLAUDE.md que os importa e por isso contam no mesmo contexto. Um symlink de CLAUDE.md para AGENTS.md também funciona, mas a Anthropic recomenda o import se alguém do time usar Windows, onde o Git pode fazer checkout do symlink como um arquivo de texto simples.",[16,845,846,849],{},[36,847,848],{},".cursorrules"," é específico do Cursor. Seu diferencial é o frontmatter com globs de arquivo que ativa instruções diferentes por tipo de arquivo. Se seu time usa Cursor e precisa de regras por tipo de arquivo, adicione-as.",[16,851,852],{},"A maior parte do conteúdo é idêntica nos três arquivos. Comandos de build, regras de arquitetura, convenções de teste e limites não mudam de ferramenta para ferramenta. Um utilitário chamado rule-porter pode converter entre formatos se necessário.",[16,854,855],{},[20,856],{"id":857},"how-claude-code-reads-agentsmd",[41,859,828],{"id":860},"como-o-claude-code-lê-o-agentsmd",[16,862,863,864,869,870,873,874,878],{},"O Claude Code lê AGENTS.md desde a ",[20,865,868],{"href":866,"rel":867},"https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md",[24],"versão 2.1.277"," (lançada em 18 de setembro de 2026), com uma condição importante: por padrão ele lê AGENTS.md ",[36,871,872],{},"apenas quando não há CLAUDE.md",". Isso vem diretamente da ",[20,875,877],{"href":262,"rel":876},[24],"documentação de memória da Anthropic",":",[234,880,881,891],{},[237,882,883],{},[240,884,885,888],{},[243,886,887],{},"Seu repositório contém",[243,889,890],{},"Claude Code lê",[253,892,893,901,909],{},[240,894,895,898],{},[258,896,897],{},"Um AGENTS.md e nenhum CLAUDE.md nem CLAUDE.local.md no seu diretório de trabalho ou acima",[258,899,900],{},"Seu AGENTS.md",[240,902,903,906],{},[258,904,905],{},"Um AGENTS.md e um CLAUDE.md ou CLAUDE.local.md no seu diretório de trabalho ou acima",[258,907,908],{},"Apenas seus arquivos CLAUDE.md",[240,910,911,917],{},[258,912,913,914],{},"Um CLAUDE.md que importa AGENTS.md com ",[53,915,916],{},"@AGENTS.md",[258,918,919],{},"Seu CLAUDE.md, com AGENTS.md incluído via import",[16,921,922],{},"Os detalhes que costumam causar problemas:",[335,924,925,946,952,968,985,1014],{},[338,926,927,930,931,463,933,578,936,939,940,942,943,945],{},[36,928,929],{},"O que conta como \"um CLAUDE.md\":"," um ",[53,932,815],{},[53,934,935],{},".claude/CLAUDE.md",[53,937,938],{},"CLAUDE.local.md"," no seu diretório de trabalho ou em qualquer diretório acima. Seu ",[53,941,581],{}," pessoal, o CLAUDE.md gerenciado da sua organização e arquivos ",[53,944,823],{}," não contam e continuam sendo carregados junto ao AGENTS.md.",[338,947,948,951],{},[36,949,950],{},"A armadilha do CLAUDE.local.md:"," se você criar um CLAUDE.local.md para suas notas pessoais não commitadas, o Claude Code silenciosamente para de ler o AGENTS.md do seu time.",[338,953,954,957,958,960,961,964,965],{},[36,955,956],{},"O que é carregado:"," cada ",[53,959,809],{}," e ",[53,962,963],{},".claude/AGENTS.md"," do seu diretório de trabalho para cima ao iniciar a sessão, mais o AGENTS.md de um subdiretório quando o Claude abre um arquivo lá. Numa sessão interativa você verá uma linha como ",[53,966,967],{},"no CLAUDE.md found; AGENTS.md loaded: ....",[338,969,970,973,974,463,977,980,981,984],{},[36,971,972],{},"O que é ignorado:"," ",[53,975,976],{},"AGENTS.local.md",[53,978,979],{},"AGENTS.override.md"," e tudo dentro de um diretório ",[53,982,983],{},".agents/",". O arquivo override é uma convenção do Codex, não do Claude Code.",[338,986,987,990,991,994,995,998,999,1002,1003,1006,1007,1010,1011,380],{},[36,988,989],{},"Mudar o comportamento padrão:"," digite ",[53,992,993],{},"/config"," e defina ",[36,996,997],{},"Project instructions"," como ",[53,1000,1001],{},"claude-md-or-agents-md"," (o padrão), ",[53,1004,1005],{},"claude-md-and-agents-md"," (ler ambos, com CLAUDE.md primeiro por diretório), ",[53,1008,1009],{},"claude-md"," (ignorar AGENTS.md) ou ",[53,1012,1013],{},"managed-only",[338,1015,1016,1019,1020,1023],{},[36,1017,1018],{},"Avisos de tamanho:"," o Claude Code avisa ao iniciar e em ",[53,1021,1022],{},"/status"," quando um arquivo ultrapassa o limite recomendado e quando vários arquivos individualmente aceitáveis ultrapassam juntos um limite compartilhado.",[16,1025,1026,1027,1029],{},"Duas notas sobre versões. Antes da v2.1.281 (23 de setembro de 2026), sessões no Amazon Bedrock, Google Vertex AI, Microsoft Foundry, gateways LLM ou com telemetria desativada continuavam lendo apenas CLAUDE.md. E a primeira sessão após atualizar da v2.1.276 ou anterior pode ainda não captar AGENTS.md; ele será carregado a partir da próxima sessão. Se você usa uma versão mais antiga, o import ",[53,1028,916],{}," dentro de um CLAUDE.md funciona em todos os lugares e nunca faz o arquivo ser lido duas vezes.",[16,1031,1032,1033,1035],{},"Se você tinha conectado isso manualmente antes, o conselho da Anthropic é: mantenha um CLAUDE.md que só contenha ",[53,1034,916],{}," (é inofensivo), ou delete-o; substitua um CLAUDE.md que em palavras instrua o Claude a ler AGENTS.md por um import real; e remova qualquer hook SessionStart que imprima AGENTS.md, pois agora ele adiciona uma segunda cópia ao contexto.",[41,1037,1039],{"id":1038},"claude-code-não-está-lendo-o-agentsmd-as-quatro-causas","Claude Code não está lendo o AGENTS.md? As quatro causas",[16,1041,1042,1043,1046,1047,1051],{},"Se o Claude Code está ignorando seu AGENTS.md, quase sempre é por uma dessas quatro razões. Verifique-as nessa ordem. Tudo aqui vem da ",[20,1044,877],{"href":262,"rel":1045},[24]," e do ",[20,1048,1050],{"href":866,"rel":1049},[24],"changelog do Claude Code",", verificado em 23 de outubro de 2026.",[16,1053,1054,1057,1058,960,1060,1062,1063,380],{},[36,1055,1056],{},"1. O arquivo está no lugar ou com o nome errado."," Ao iniciar a sessão, o Claude Code carrega ",[53,1059,809],{},[53,1061,963],{}," do seu diretório de trabalho e de qualquer diretório acima. Se você iniciar o Claude numa pasta acima do repositório, o AGENTS.md do repo é um arquivo de subdiretório e não é carregado ao iniciar. Inicie na raiz do repo e nomeie o arquivo exatamente como ",[53,1064,809],{},[16,1066,1067,1070,1071,1073,1074,998,1076,1078,1079,1081,1082,1084,1085,1087],{},[36,1068,1069],{},"2. Um CLAUDE.md tem prioridade."," Na maioria das vezes o culpado é um CLAUDE.local.md esquecido. Adicione ",[53,1072,916],{}," ao CLAUDE.md, ou defina ",[36,1075,997],{},[53,1077,1005],{}," em ",[53,1080,993],{},". Verifique se a configuração não é ",[53,1083,1009],{}," nem ",[53,1086,1013],{},", pois ambas ignoram AGENTS.md completamente.",[16,1089,1090,1093,1094,1097],{},[36,1091,1092],{},"3. Você está usando uma versão com um bug já corrigido."," Execute ",[53,1095,1096],{},"claude --version",". Antes da v2.1.281, sessões com Bedrock, Vertex, Foundry, gateway e sem telemetria liam apenas CLAUDE.md. A v2.1.290 (5 de outubro de 2026) corrigiu que o AGENTS.md de um subdiretório não fosse anexado quando você mencionava um arquivo de lá com @. Atualize o Claude Code e abra uma nova sessão.",[16,1099,1100,1103],{},[36,1101,1102],{},"4. É um arquivo aninhado que ainda não foi carregado."," O AGENTS.md de um subdiretório não é lido ao iniciar. O Claude Code o carrega quando o Claude abre um arquivo naquele diretório, e apenas se esse diretório não tiver seu próprio CLAUDE.md. Coloque no arquivo raiz as regras que sempre devem se aplicar.",[16,1105,1106,1107,1110],{},"Para confirmar o que foi carregado, execute ",[53,1108,1109],{},"/memory"," e procure pelo caminho do seu AGENTS.md.",[41,1112,1114],{"id":1113},"o-agentsmd-funciona-com-o-openai-codex","O AGENTS.md funciona com o OpenAI Codex?",[16,1116,1117],{},"Sim. O Codex lê AGENTS.md nativamente, e o mesmo arquivo funciona no Codex, Cursor, Gemini CLI e Claude Code sem modificações.",[16,1119,1120,1121,1125],{},"As regras de resolução do Codex são mais estratificadas que as da maioria das ferramentas. Segundo o ",[20,1122,1124],{"href":277,"rel":1123},[24],"guia de AGENTS.md da OpenAI para Codex",", ele constrói a cadeia de instruções uma vez por execução:",[335,1127,1128,1148,1164],{},[338,1129,1130,1133,1134,1137,1138,1141,1142,1144,1145,1147],{},[36,1131,1132],{},"Global:"," no seu home do Codex (",[53,1135,1136],{},"~/.codex",", ou onde ",[53,1139,1140],{},"CODEX_HOME"," apontar), o Codex lê ",[53,1143,979],{}," se existir e, caso contrário, ",[53,1146,809],{},". Apenas um arquivo é usado nesse nível.",[338,1149,1150,1153,1154,1156,1157,1159,1160,1163],{},[36,1151,1152],{},"Projeto:"," partindo da raiz do projeto (geralmente a raiz do Git), desce até o seu diretório de trabalho atual. Em cada diretório verifica ",[53,1155,979],{},", depois ",[53,1158,809],{},", depois os nomes que você listou em ",[53,1161,1162],{},"project_doc_fallback_filenames",", e usa no máximo um arquivo por diretório.",[338,1165,1166,1169],{},[36,1167,1168],{},"Mesclagem:"," os arquivos são concatenados da raiz para baixo, de modo que os arquivos mais próximos ao seu local de trabalho ficam por último e sobrescrevem os anteriores.",[16,1171,1172,1175,1176,1178],{},[36,1173,1174],{},"Limite de tamanho."," O Codex ignora arquivos vazios e para de adicionar arquivos quando o tamanho total atinge ",[53,1177,285],{},", por padrão 32 KiB. Isso se aplica a toda a cadeia, não por arquivo. Você pode aumentar o valor, mas se estiver perto do limite, é melhor deletar linhas:",[46,1180,1184],{"className":1181,"code":1182,"language":1183,"meta":51,"style":51},"language-toml shiki shiki-themes github-light","# ~/.codex/config.toml\nproject_doc_fallback_filenames = [\"TEAM_GUIDE.md\", \".agents.md\"]\nproject_doc_max_bytes = 65536\n","toml",[53,1185,1186,1191,1196],{"__ignoreMap":51},[56,1187,1188],{"class":58,"line":59},[56,1189,1190],{},"# ~/.codex/config.toml\n",[56,1192,1193],{"class":58,"line":66},[56,1194,1195],{},"project_doc_fallback_filenames = [\"TEAM_GUIDE.md\", \".agents.md\"]\n",[56,1197,1198],{"class":58,"line":73},[56,1199,1200],{},"project_doc_max_bytes = 65536\n",[16,1202,1203,1093,1206,1209,1210,1213],{},[36,1204,1205],{},"Verificar o que foi carregado.",[53,1207,1208],{},"codex --ask-for-approval never \"Summarize the current instructions.\""," na raiz do repo. O Codex reconstrói a cadeia a cada execução (uma vez por sessão na TUI interativa), então não há cache a limpar quando você editar um arquivo; basta reiniciá-lo. Se esse teste terminar com ",[53,1211,1212],{},"stream disconnected before completion",", é um erro de conexão, não um problema do arquivo de instruções.",[16,1215,1216],{},"Um aviso prático. O Codex executa os comandos de build e teste do seu AGENTS.md no seu sandbox. Um comando errado não gera um erro útil; o agente o executa, vê que falhou e contorna o problema. Antes de confiar em um comando do seu AGENTS.md, execute-o palavra por palavra em um terminal limpo.",[16,1218,1219,1220,1222],{},"O Claude Code não lê ",[53,1221,979],{}," nem os nomes de arquivo fallback do Codex. Se um repositório serve a ambos os agentes, mantenha as regras compartilhadas em arquivos AGENTS.md normais.",[41,1224,1226],{"id":1225},"agentsmd-global-vs-por-diretório","AGENTS.md global vs por diretório",[16,1228,1229],{},"Há três escopos, e confundi-los é uma fonte comum do \"por que o agente está ignorando minhas instruções\".",[16,1231,1232,1235,1236,1238],{},[36,1233,1234],{},"Global (pessoal)."," Um arquivo no diretório de configuração da sua ferramenta, como ",[53,1237,577],{},". Aplica-se a todos os projetos que você abrir. Use para preferências que são suas, não do projeto. Não é commitado, então seus colegas nunca o veem.",[16,1240,1241,1244],{},[36,1242,1243],{},"Raiz do repositório."," O arquivo que a maioria das pessoas tem em mente quando diz \"AGENTS.md\". Está commitado no repo e compartilhado com todo o time. Use para regras que se aplicam em todo o projeto.",[16,1246,1247,1250,1251,1254],{},[36,1248,1249],{},"Subdiretório."," Estende o arquivo raiz para um diretório específico. Use quando um diretório tem regras realmente diferentes: um pacote com seu próprio comando de build, um diretório ",[53,1252,1253],{},"/mobile"," com um framework diferente.",[16,1256,1257],{},"A maioria dos projetos precisa apenas do arquivo raiz. Se o seu AGENTS.md raiz está longo demais, a solução é deletar linhas, não distribuí-las em diretórios.",[41,1259,1261],{"id":1260},"agentsmd-aninhado-e-global-qual-vence","AGENTS.md aninhado e global: qual vence",[16,1263,1264,1265,1269],{},"Resposta curta: o arquivo mais próximo do código sendo editado vence, e o que você digitar no chat supera qualquer arquivo. É assim que o ",[20,1266,1268],{"href":22,"rel":1267},[24],"FAQ do agents.md"," coloca: \"O AGENTS.md mais próximo do arquivo sendo editado vence; prompts explícitos do usuário no chat sobrescrevem tudo.\"",[234,1271,1272,1287],{},[237,1273,1274],{},[240,1275,1276,1278,1281,1284],{},[243,1277],{},[243,1279,1280],{},"Arquivo global (pessoal)",[243,1282,1283],{},"Como arquivos aninhados interagem",[243,1285,1286],{},"Arquivo override",[253,1288,1289,1304,1326],{},[240,1290,1291,1296,1299,1302],{},[258,1292,1293],{},[36,1294,1295],{},"Especificação agents.md",[258,1297,1298],{},"Não definido",[258,1300,1301],{},"O arquivo mais próximo na árvore de diretórios tem prioridade",[258,1303,1298],{},[240,1305,1306,1310,1318,1321],{},[258,1307,1308],{},[36,1309,279],{},[258,1311,1312,1314,1315,1317],{},[53,1313,577],{}," (ou ",[53,1316,979],{}," lá), lido primeiro",[258,1319,1320],{},"Um arquivo por diretório da raiz do projeto para baixo, concatenados com os arquivos mais próximos por último; limite total padrão de 32 KiB",[258,1322,1323,1325],{},[53,1324,979],{}," substitui o AGENTS.md daquele diretório",[240,1327,1328,1333,1339,1342],{},[258,1329,1330],{},[36,1331,1332],{},"Claude Code",[258,1334,1335,1336,1338],{},"Sem AGENTS.md global; seu arquivo pessoal é ",[53,1337,581],{},", carregado junto ao AGENTS.md",[258,1340,1341],{},"Arquivos a partir do seu diretório de trabalho para cima são carregados ao iniciar; o de um subdiretório é carregado quando o Claude abre um arquivo lá",[258,1343,1344],{},"Não é lido",[16,1346,1347,1348,1352],{},"Para o Claude Code, a ",[20,1349,1351],{"href":262,"rel":1350},[24],"documentação da Anthropic"," descreve os arquivos de instruções como concatenados, não se sobrescrevendo, e avisa que o Claude pode escolher arbitrariamente quando há arquivos contraditórios. No Claude Code \"o mais próximo vence\" é uma tendência, não uma garantia. Estas regras se aplicam em todos os lugares:",[335,1354,1355,1361,1366],{},[338,1356,1357,1360],{},[36,1358,1359],{},"Não contradiga, especialize."," Um arquivo de subdiretório deve adicionar regras para aquele diretório, não inverter as do arquivo raiz.",[338,1362,1363],{},[36,1364,1365],{},"Preferências pessoais no global, regras do projeto no repo.",[338,1367,1368,1371],{},[36,1369,1370],{},"Diga no prompt quando importar."," Uma exceção pontual vai no prompt, não numa mudança do AGENTS.md.",[41,1373,1375],{"id":1374},"o-agentsmd-deve-ser-commitado-no-git","O AGENTS.md deve ser commitado no git?",[16,1377,1378],{},"Sim. AGENTS.md pertence ao controle de versão, ao lado do código que ele descreve, na raiz do repositório. Cada colaborador e cada ferramenta de IA o lê de lá, e as mudanças são revisadas no mesmo PR que a mudança de convenção que as originou.",[16,1380,1381,1382,1385],{},"Duas exceções. Preferências pessoais vão no seu arquivo global, não no repo. E nunca inclua secrets ou URLs internas diretamente; referencie-as a partir de ",[53,1383,1384],{},".env"," ou de um arquivo excluído pelo gitignore.",[41,1387,1389],{"id":1388},"segurança-o-agentsmd-é-uma-superfície-de-prompt-injection","Segurança: o AGENTS.md é uma superfície de prompt injection",[16,1391,1392,1393,1398],{},"O time de IA Red Team da NVIDIA demonstrou uma injeção indireta de AGENTS.md contra o OpenAI Codex em que uma ",[20,1394,1397],{"href":1395,"rel":1396},"https://developer.nvidia.com/blog/mitigating-indirect-agents-md-injection-attacks-in-agentic-environments/",[24],"dependência maliciosa sequestra o comportamento do agente"," explorando a precedência de instruções. O ataque requer uma dependência já comprometida, então não há motivo para pânico com cada repositório que você clonar. Mas demonstra que arquivos de instruções para agentes são contexto executável e ampliam a superfície de ataque da cadeia de suprimentos.",[16,1400,1401],{},"As medidas de proteção práticas:",[335,1403,1404,1407,1410,1413],{},[338,1405,1406],{},"Leia o AGENTS.md de qualquer repositório que você clonar antes de executar um agente nele.",[338,1408,1409],{},"Trate AGENTS.md como um Makefile ou um script post-install. Ele influencia comandos que rodam na sua máquina.",[338,1411,1412],{},"Revise mudanças no AGENTS.md com o mesmo cuidado que mudanças na configuração de CI.",[338,1414,1415],{},"Execute agentes num sandbox quando possível, para que uma instrução despercebida cause menos dano.",[41,1417,1419],{"id":1418},"além-do-código-agentsmd-para-agentes-de-negócio","Além do código: AGENTS.md para agentes de negócio",[16,1421,1422],{},"A ideia por trás do AGENTS.md surgiu em repositórios de código, mas o princípio se aplica a qualquer agente de IA: dê a ele contexto breve e específico logo no início e ele trabalhará melhor. A lição sobre o tamanho também se aplica. Um agente de negócio com uma descrição de papel de duas páginas a segue pior do que um com dez linhas claras.",[16,1424,1425],{},"Para agentes de negócio (suporte, vendas, operações), a configuração equivalente abrange:",[16,1427,1428],{},[359,1429],{"alt":1430,"src":1431},"Do AGENTS.md à configuração: o mesmo princípio para agentes de negócio.","/img/blog/agents-md-best-practices-business-agents-pt.jpg",[335,1433,1434,1440,1446,1452,1458,1464],{},[338,1435,1436,1439],{},[36,1437,1438],{},"Identidade:"," quem é o agente, seu papel e tom.",[338,1441,1442,1445],{},[36,1443,1444],{},"Capacidades:"," quais ferramentas e aplicativos ele pode usar.",[338,1447,1448,1451],{},[36,1449,1450],{},"Restrições:"," o que ele não deve fazer e quais ações precisam de aprovação humana.",[338,1453,1454,1457],{},[36,1455,1456],{},"Nível de confiança:"," apenas rascunhos, age com aprovação ou age de forma autônoma dentro de limites.",[338,1459,1460,1463],{},[36,1461,1462],{},"Regras de escalonamento:"," quando transferir para uma pessoa.",[338,1465,1466,1469],{},[36,1467,1468],{},"Formato de saída:"," como ele deve responder.",[16,1471,1472,1473,1477,1478,1482,1483,1487],{},"Para agentes de programação, AGENTS.md é um arquivo que você escreve e mantém. Para agentes de negócio, essa configuração é mais fácil de gerenciar num construtor visual. É assim que o ",[20,1474,1476],{"href":1475},"/","construtor de agentes de IA"," da BetterClaw funciona: identidade, capacidades, restrições, níveis de confiança (Internal, Specialist, Lead), regras de escalonamento e formato de saída são campos no construtor, versionados para você, e não há arquivo que você possa esquecer de atualizar. Cada agente pode usar sua própria chave de modelo sem markup. ",[20,1479,1481],{"href":1480},"/free-plan","Comece grátis com a BetterClaw",": o plano Starter custa $19/mês, e o ",[20,1484,1486],{"href":1485},"/pricing","Pro custa $49/mês"," para 5 agentes.",[16,1489,1490],{},[20,1491],{"id":1492},"the-annotated-template-copy-and-adapt",[41,1494,1496],{"id":1495},"o-modelo-anotado-copie-e-adapte","O modelo anotado (copie e adapte)",[16,1498,1499],{},"Aqui está um AGENTS.md mínimo e eficaz. Delete as seções que não se aplicam. Um arquivo mais curto e correto supera um extenso e genérico.",[46,1501,1503],{"className":48,"code":1502,"language":50,"meta":51,"style":51},"# Project Name\n\nNext.js 15 App Router, React 19, TypeScript 5.4, Tailwind CSS, Drizzle ORM, Bun.\n\n## Commands\n\nBuild: `bun run build`\nTest: `bun test`\nLint: `bun run lint --fix`\nSingle test: `bun test path/to/file.test.ts`\n\n## Code Style\n\nFunctional components only. Never class components.\nUse `const` exclusively. Never `var`, never `let` unless reassignment is needed.\nNamed exports only. Never default exports.\n\n// Component example:\nexport const UserCard = ({ name, email }: UserCardProps) => {\n  return \u003Cdiv className=\"p-4\">{name}\u003C/div>;\n};\n\n## Error Handling\n\nLet errors propagate. Do not wrap individual calls in try/catch.\nThe global error handler in middleware.ts catches everything.\n\n## Architecture\n\n/app         -> Routes and page components\n/components  -> Shared UI components\n/lib         -> Business logic and utilities\n/db          -> Database schema and migrations\n\nNever import from /app into /lib. Data flows one direction.\n\n## Boundaries\n\nNever modify files in /generated/.\nNever commit .env or any file containing secrets.\nThe /legacy/ module uses sync code. Do not convert to async.\n\n## Git\n\nSquash merge only.\nConventional commits: feat:, fix:, chore:, docs:.\nBranch format: type/short-description (e.g., feat/user-auth).\n",[53,1504,1505,1510,1514,1519,1523,1528,1532,1539,1547,1555,1563,1567,1572,1576,1581,1604,1609,1613,1618,1623,1629,1635,1640,1646,1651,1657,1663,1668,1674,1679,1685,1691,1697,1703,1708,1714,1719,1724,1729,1735,1741,1747,1752,1758,1763,1769,1775],{"__ignoreMap":51},[56,1506,1507],{"class":58,"line":59},[56,1508,1509],{"class":62},"# Project Name\n",[56,1511,1512],{"class":58,"line":66},[56,1513,70],{"emptyLinePlaceholder":69},[56,1515,1516],{"class":58,"line":73},[56,1517,1518],{"class":82},"Next.js 15 App Router, React 19, TypeScript 5.4, Tailwind CSS, Drizzle ORM, Bun.\n",[56,1520,1521],{"class":58,"line":79},[56,1522,70],{"emptyLinePlaceholder":69},[56,1524,1525],{"class":58,"line":86},[56,1526,1527],{"class":62},"## Commands\n",[56,1529,1530],{"class":58,"line":91},[56,1531,70],{"emptyLinePlaceholder":69},[56,1533,1534,1536],{"class":58,"line":97},[56,1535,133],{"class":82},[56,1537,1538],{"class":103},"`bun run build`\n",[56,1540,1541,1544],{"class":58,"line":119},[56,1542,1543],{"class":82},"Test: ",[56,1545,1546],{"class":103},"`bun test`\n",[56,1548,1549,1552],{"class":58,"line":124},[56,1550,1551],{"class":82},"Lint: ",[56,1553,1554],{"class":103},"`bun run lint --fix`\n",[56,1556,1557,1560],{"class":58,"line":130},[56,1558,1559],{"class":82},"Single test: ",[56,1561,1562],{"class":103},"`bun test path/to/file.test.ts`\n",[56,1564,1565],{"class":58,"line":151},[56,1566,70],{"emptyLinePlaceholder":69},[56,1568,1569],{"class":58,"line":156},[56,1570,1571],{"class":62},"## Code Style\n",[56,1573,1574],{"class":58,"line":162},[56,1575,70],{"emptyLinePlaceholder":69},[56,1577,1578],{"class":58,"line":168},[56,1579,1580],{"class":82},"Functional components only. Never class components.\n",[56,1582,1583,1586,1589,1592,1595,1598,1601],{"class":58,"line":173},[56,1584,1585],{"class":82},"Use ",[56,1587,1588],{"class":103},"`const`",[56,1590,1591],{"class":82}," exclusively. Never ",[56,1593,1594],{"class":103},"`var`",[56,1596,1597],{"class":82},", never ",[56,1599,1600],{"class":103},"`let`",[56,1602,1603],{"class":82}," unless reassignment is needed.\n",[56,1605,1606],{"class":58,"line":179},[56,1607,1608],{"class":82},"Named exports only. Never default exports.\n",[56,1610,1611],{"class":58,"line":751},[56,1612,70],{"emptyLinePlaceholder":69},[56,1614,1615],{"class":58,"line":757},[56,1616,1617],{"class":82},"// Component example:\n",[56,1619,1620],{"class":58,"line":763},[56,1621,1622],{"class":82},"export const UserCard = ({ name, email }: UserCardProps) => {\n",[56,1624,1626],{"class":58,"line":1625},20,[56,1627,1628],{"class":82},"  return \u003Cdiv className=\"p-4\">{name}\u003C/div>;\n",[56,1630,1632],{"class":58,"line":1631},21,[56,1633,1634],{"class":82},"};\n",[56,1636,1638],{"class":58,"line":1637},22,[56,1639,70],{"emptyLinePlaceholder":69},[56,1641,1643],{"class":58,"line":1642},23,[56,1644,1645],{"class":62},"## Error Handling\n",[56,1647,1649],{"class":58,"line":1648},24,[56,1650,70],{"emptyLinePlaceholder":69},[56,1652,1654],{"class":58,"line":1653},25,[56,1655,1656],{"class":82},"Let errors propagate. Do not wrap individual calls in try/catch.\n",[56,1658,1660],{"class":58,"line":1659},26,[56,1661,1662],{"class":82},"The global error handler in middleware.ts catches everything.\n",[56,1664,1666],{"class":58,"line":1665},27,[56,1667,70],{"emptyLinePlaceholder":69},[56,1669,1671],{"class":58,"line":1670},28,[56,1672,1673],{"class":62},"## Architecture\n",[56,1675,1677],{"class":58,"line":1676},29,[56,1678,70],{"emptyLinePlaceholder":69},[56,1680,1682],{"class":58,"line":1681},30,[56,1683,1684],{"class":82},"/app         -> Routes and page components\n",[56,1686,1688],{"class":58,"line":1687},31,[56,1689,1690],{"class":82},"/components  -> Shared UI components\n",[56,1692,1694],{"class":58,"line":1693},32,[56,1695,1696],{"class":82},"/lib         -> Business logic and utilities\n",[56,1698,1700],{"class":58,"line":1699},33,[56,1701,1702],{"class":82},"/db          -> Database schema and migrations\n",[56,1704,1706],{"class":58,"line":1705},34,[56,1707,70],{"emptyLinePlaceholder":69},[56,1709,1711],{"class":58,"line":1710},35,[56,1712,1713],{"class":82},"Never import from /app into /lib. Data flows one direction.\n",[56,1715,1717],{"class":58,"line":1716},36,[56,1718,70],{"emptyLinePlaceholder":69},[56,1720,1722],{"class":58,"line":1721},37,[56,1723,176],{"class":62},[56,1725,1727],{"class":58,"line":1726},38,[56,1728,70],{"emptyLinePlaceholder":69},[56,1730,1732],{"class":58,"line":1731},39,[56,1733,1734],{"class":82},"Never modify files in /generated/.\n",[56,1736,1738],{"class":58,"line":1737},40,[56,1739,1740],{"class":82},"Never commit .env or any file containing secrets.\n",[56,1742,1744],{"class":58,"line":1743},41,[56,1745,1746],{"class":82},"The /legacy/ module uses sync code. Do not convert to async.\n",[56,1748,1750],{"class":58,"line":1749},42,[56,1751,70],{"emptyLinePlaceholder":69},[56,1753,1755],{"class":58,"line":1754},43,[56,1756,1757],{"class":62},"## Git\n",[56,1759,1761],{"class":58,"line":1760},44,[56,1762,70],{"emptyLinePlaceholder":69},[56,1764,1766],{"class":58,"line":1765},45,[56,1767,1768],{"class":82},"Squash merge only.\n",[56,1770,1772],{"class":58,"line":1771},46,[56,1773,1774],{"class":82},"Conventional commits: feat:, fix:, chore:, docs:.\n",[56,1776,1778],{"class":58,"line":1777},47,[56,1779,1780],{"class":82},"Branch format: type/short-description (e.g., feat/user-auth).\n",[16,1782,1783],{},"São menos de 50 linhas, e cada uma é específica. Se crescer além de 100, volte ao ciclo de vida de regras e comece a deletar.",[41,1785,1787],{"id":1786},"exemplos-de-agentsmd-três-arquivos-para-três-tipos-de-projeto","Exemplos de AGENTS.md: três arquivos para três tipos de projeto",[16,1789,1790],{},"Arquivos reais são mais curtos e mais peculiares que modelos, porque contêm apenas o que os agentes daquele projeto erram repetidamente. Estes três são exemplos representativos para mostrar essa variedade, não cópias do arquivo de nenhum repositório específico.",[385,1792,1794],{"id":1793},"exemplo-1-uma-aplicação-web-nextjs-12-linhas","Exemplo 1: uma aplicação web Next.js (12 linhas)",[46,1796,1798],{"className":48,"code":1797,"language":50,"meta":51,"style":51},"# Storefront\n\nNext.js 15 App Router, TypeScript, Tailwind, Bun.\n\nBuild: `bun run build` | Test: `bun test` | Lint: `bun run lint --fix`\n\nServer Components by default. Add `'use client'` only for event handlers or hooks.\nNever fetch in a Client Component. Fetch in the page, pass data down as props.\nNamed exports only.\n\nNever edit `/app/generated/`. It is regenerated on every build.\nNever add a dependency without asking. This bundle is size-budgeted.\n",[53,1799,1800,1805,1809,1814,1818,1836,1840,1851,1856,1861,1865,1876],{"__ignoreMap":51},[56,1801,1802],{"class":58,"line":59},[56,1803,1804],{"class":62},"# Storefront\n",[56,1806,1807],{"class":58,"line":66},[56,1808,70],{"emptyLinePlaceholder":69},[56,1810,1811],{"class":58,"line":73},[56,1812,1813],{"class":82},"Next.js 15 App Router, TypeScript, Tailwind, Bun.\n",[56,1815,1816],{"class":58,"line":79},[56,1817,70],{"emptyLinePlaceholder":69},[56,1819,1820,1822,1825,1828,1831,1834],{"class":58,"line":86},[56,1821,133],{"class":82},[56,1823,1824],{"class":103},"`bun run build`",[56,1826,1827],{"class":82}," | Test: ",[56,1829,1830],{"class":103},"`bun test`",[56,1832,1833],{"class":82}," | Lint: ",[56,1835,1554],{"class":103},[56,1837,1838],{"class":58,"line":91},[56,1839,70],{"emptyLinePlaceholder":69},[56,1841,1842,1845,1848],{"class":58,"line":97},[56,1843,1844],{"class":82},"Server Components by default. Add ",[56,1846,1847],{"class":103},"`'use client'`",[56,1849,1850],{"class":82}," only for event handlers or hooks.\n",[56,1852,1853],{"class":58,"line":119},[56,1854,1855],{"class":82},"Never fetch in a Client Component. Fetch in the page, pass data down as props.\n",[56,1857,1858],{"class":58,"line":124},[56,1859,1860],{"class":82},"Named exports only.\n",[56,1862,1863],{"class":58,"line":130},[56,1864,70],{"emptyLinePlaceholder":69},[56,1866,1867,1870,1873],{"class":58,"line":151},[56,1868,1869],{"class":82},"Never edit ",[56,1871,1872],{"class":103},"`/app/generated/`",[56,1874,1875],{"class":82},". It is regenerated on every build.\n",[56,1877,1878],{"class":58,"line":156},[56,1879,1880],{"class":82},"Never add a dependency without asking. This bundle is size-budgeted.\n",[16,1882,1883,1884,1887],{},"Por que funciona: a regra de ",[53,1885,1886],{},"'use client'"," é exatamente o que um agente erra de forma confiável em projetos App Router, formulada como regra mais exceção em uma única linha.",[385,1889,1891],{"id":1890},"exemplo-2-um-backend-python-com-fastapi-16-linhas","Exemplo 2: um backend Python com FastAPI (16 linhas)",[46,1893,1895],{"className":48,"code":1894,"language":50,"meta":51,"style":51},"# Billing API\n\nPython 3.12, FastAPI, SQLAlchemy 2.0 (async), Alembic, uv.\n\nInstall: `uv sync` | Run: `uv run uvicorn app.main:app --reload`\nTest: `uv run pytest -x` | Single test: `uv run pytest tests/test_invoices.py::test_name`\n\nAll DB access is async. Never use the sync Session. Never call `.commit()` in a\nroute handler; the dependency in `app/deps.py` handles the transaction boundary.\n\nPydantic models live in `app/schemas/`. SQLAlchemy models live in `app/models/`.\nNever import a SQLAlchemy model into a route signature.\n\nSchema changes require a migration: `uv run alembic revision --autogenerate -m \"...\"`.\nNever edit an existing migration that has been merged.\n\nMoney is `Decimal`, never `float`. Amounts are stored in minor units (cents).\n",[53,1896,1897,1902,1906,1911,1915,1928,1941,1945,1956,1967,1971,1988,1993,1997,2007,2012,2016],{"__ignoreMap":51},[56,1898,1899],{"class":58,"line":59},[56,1900,1901],{"class":62},"# Billing API\n",[56,1903,1904],{"class":58,"line":66},[56,1905,70],{"emptyLinePlaceholder":69},[56,1907,1908],{"class":58,"line":73},[56,1909,1910],{"class":82},"Python 3.12, FastAPI, SQLAlchemy 2.0 (async), Alembic, uv.\n",[56,1912,1913],{"class":58,"line":79},[56,1914,70],{"emptyLinePlaceholder":69},[56,1916,1917,1919,1922,1925],{"class":58,"line":86},[56,1918,100],{"class":82},[56,1920,1921],{"class":103},"`uv sync`",[56,1923,1924],{"class":82}," | Run: ",[56,1926,1927],{"class":103},"`uv run uvicorn app.main:app --reload`\n",[56,1929,1930,1932,1935,1938],{"class":58,"line":91},[56,1931,1543],{"class":82},[56,1933,1934],{"class":103},"`uv run pytest -x`",[56,1936,1937],{"class":82}," | Single test: ",[56,1939,1940],{"class":103},"`uv run pytest tests/test_invoices.py::test_name`\n",[56,1942,1943],{"class":58,"line":97},[56,1944,70],{"emptyLinePlaceholder":69},[56,1946,1947,1950,1953],{"class":58,"line":119},[56,1948,1949],{"class":82},"All DB access is async. Never use the sync Session. Never call ",[56,1951,1952],{"class":103},"`.commit()`",[56,1954,1955],{"class":82}," in a\n",[56,1957,1958,1961,1964],{"class":58,"line":124},[56,1959,1960],{"class":82},"route handler; the dependency in ",[56,1962,1963],{"class":103},"`app/deps.py`",[56,1965,1966],{"class":82}," handles the transaction boundary.\n",[56,1968,1969],{"class":58,"line":130},[56,1970,70],{"emptyLinePlaceholder":69},[56,1972,1973,1976,1979,1982,1985],{"class":58,"line":151},[56,1974,1975],{"class":82},"Pydantic models live in ",[56,1977,1978],{"class":103},"`app/schemas/`",[56,1980,1981],{"class":82},". SQLAlchemy models live in ",[56,1983,1984],{"class":103},"`app/models/`",[56,1986,1987],{"class":82},".\n",[56,1989,1990],{"class":58,"line":156},[56,1991,1992],{"class":82},"Never import a SQLAlchemy model into a route signature.\n",[56,1994,1995],{"class":58,"line":162},[56,1996,70],{"emptyLinePlaceholder":69},[56,1998,1999,2002,2005],{"class":58,"line":168},[56,2000,2001],{"class":82},"Schema changes require a migration: ",[56,2003,2004],{"class":103},"`uv run alembic revision --autogenerate -m \"...\"`",[56,2006,1987],{"class":82},[56,2008,2009],{"class":58,"line":173},[56,2010,2011],{"class":82},"Never edit an existing migration that has been merged.\n",[56,2013,2014],{"class":58,"line":179},[56,2015,70],{"emptyLinePlaceholder":69},[56,2017,2018,2021,2024,2026,2029],{"class":58,"line":751},[56,2019,2020],{"class":82},"Money is ",[56,2022,2023],{"class":103},"`Decimal`",[56,2025,1597],{"class":82},[56,2027,2028],{"class":103},"`float`",[56,2030,2031],{"class":82},". Amounts are stored in minor units (cents).\n",[16,2033,2034],{},"Por que funciona: a regra do dinheiro. Uma linha clara que previne toda uma classe de erros caros de detectar.",[385,2036,2038],{"id":2037},"exemplo-3-um-monorepo-22-linhas","Exemplo 3: um monorepo (22 linhas)",[46,2040,2042],{"className":48,"code":2041,"language":50,"meta":51,"style":51},"# Platform monorepo\n\npnpm workspaces + Turborepo. Node 22.\n\napps/web    -> Next.js 15 storefront\napps/admin  -> Vite + React admin panel\npackages/ui -> Shared component library\npackages/db -> Drizzle schema and client\n\nAlways run commands from the repo root: `pnpm turbo build --filter=web`.\nNever `cd` into a package and run `pnpm install` there.\n\nTest: `pnpm turbo test` | Single app: `pnpm turbo test --filter=admin`\n\napps/* may import from packages/*. packages/* must never import from apps/*.\npackages/ui must never import from packages/db. UI takes data as props.\n\nAdding a dependency to a package: `pnpm add \u003Cpkg> --filter=\u003Cpackage-name>`.\n\nEach app has its own AGENTS.md with framework-specific rules. This file covers\nthe workspace-level rules only.\n",[53,2043,2044,2049,2053,2058,2062,2067,2072,2077,2082,2086,2096,2112,2116,2129,2133,2145,2150,2154,2164,2168,2173],{"__ignoreMap":51},[56,2045,2046],{"class":58,"line":59},[56,2047,2048],{"class":62},"# Platform monorepo\n",[56,2050,2051],{"class":58,"line":66},[56,2052,70],{"emptyLinePlaceholder":69},[56,2054,2055],{"class":58,"line":73},[56,2056,2057],{"class":82},"pnpm workspaces + Turborepo. Node 22.\n",[56,2059,2060],{"class":58,"line":79},[56,2061,70],{"emptyLinePlaceholder":69},[56,2063,2064],{"class":58,"line":86},[56,2065,2066],{"class":82},"apps/web    -> Next.js 15 storefront\n",[56,2068,2069],{"class":58,"line":91},[56,2070,2071],{"class":82},"apps/admin  -> Vite + React admin panel\n",[56,2073,2074],{"class":58,"line":97},[56,2075,2076],{"class":82},"packages/ui -> Shared component library\n",[56,2078,2079],{"class":58,"line":119},[56,2080,2081],{"class":82},"packages/db -> Drizzle schema and client\n",[56,2083,2084],{"class":58,"line":124},[56,2085,70],{"emptyLinePlaceholder":69},[56,2087,2088,2091,2094],{"class":58,"line":130},[56,2089,2090],{"class":82},"Always run commands from the repo root: ",[56,2092,2093],{"class":103},"`pnpm turbo build --filter=web`",[56,2095,1987],{"class":82},[56,2097,2098,2101,2104,2107,2109],{"class":58,"line":151},[56,2099,2100],{"class":82},"Never ",[56,2102,2103],{"class":103},"`cd`",[56,2105,2106],{"class":82}," into a package and run ",[56,2108,104],{"class":103},[56,2110,2111],{"class":82}," there.\n",[56,2113,2114],{"class":58,"line":156},[56,2115,70],{"emptyLinePlaceholder":69},[56,2117,2118,2120,2123,2126],{"class":58,"line":162},[56,2119,1543],{"class":82},[56,2121,2122],{"class":103},"`pnpm turbo test`",[56,2124,2125],{"class":82}," | Single app: ",[56,2127,2128],{"class":103},"`pnpm turbo test --filter=admin`\n",[56,2130,2131],{"class":58,"line":168},[56,2132,70],{"emptyLinePlaceholder":69},[56,2134,2135,2138,2142],{"class":58,"line":173},[56,2136,2137],{"class":82},"apps/* may import from packages/",[56,2139,2141],{"class":2140},"sLX6V","*. packages/*",[56,2143,2144],{"class":82}," must never import from apps/*.\n",[56,2146,2147],{"class":58,"line":179},[56,2148,2149],{"class":82},"packages/ui must never import from packages/db. UI takes data as props.\n",[56,2151,2152],{"class":58,"line":751},[56,2153,70],{"emptyLinePlaceholder":69},[56,2155,2156,2159,2162],{"class":58,"line":757},[56,2157,2158],{"class":82},"Adding a dependency to a package: ",[56,2160,2161],{"class":103},"`pnpm add \u003Cpkg> --filter=\u003Cpackage-name>`",[56,2163,1987],{"class":82},[56,2165,2166],{"class":58,"line":763},[56,2167,70],{"emptyLinePlaceholder":69},[56,2169,2170],{"class":58,"line":1625},[56,2171,2172],{"class":82},"Each app has its own AGENTS.md with framework-specific rules. This file covers\n",[56,2174,2175],{"class":58,"line":1631},[56,2176,2177],{"class":82},"the workspace-level rules only.\n",[16,2179,2180],{},"Por que funciona: as regras de direção de importação e a última linha, que diz ao agente que existem instruções mais específicas mais abaixo na árvore.",[16,2182,2183],{},"O fio condutor: cada linha é uma regra que um agente quebraria sem instruções, formulada como diretiva em vez de explicação. Nenhuma descreve para que serve o projeto e nenhuma chega perto de 100 linhas.",[41,2185,2187],{"id":2186},"resumo-rápido","Resumo rápido",[16,2189,2190],{},"O melhor AGENTS.md é o que seu time realmente mantém. Comece com 30 linhas. Adicione uma regra quando um agente cometer o mesmo erro duas vezes. Delete-a quando o agente acertar sem instruções. Mantenha abaixo de 100 linhas, procure contradições a cada trimestre e imponha o que for crítico com um hook em vez de com uma frase.",[16,2192,2193,2194,2197,2198,2201],{},"E se seus agentes forem de negócio e não de programação, toda essa configuração pertence a um construtor visual, não a um arquivo Markdown. ",[20,2195,2196],{"href":1485},"Construa seu agente na BetterClaw",", ou ",[20,2199,2200],{"href":1480},"comece agora"," com sua própria chave de modelo.",[41,2203,2205],{"id":2204},"perguntas-frequentes","Perguntas frequentes",[385,2207,2209],{"id":2208},"qual-deve-ser-o-tamanho-de-um-arquivo-agentsmd","Qual deve ser o tamanho de um arquivo AGENTS.md?",[16,2211,2212,2213,2216],{},"Mire em menos de 100 linhas e comece a deletar quando ultrapassar 150. A Anthropic recomenda manter CLAUDE.md, o arquivo equivalente, abaixo de 200 linhas porque \"arquivos mais longos consomem mais contexto e reduzem o seguimento\", e o Codex para de carregar arquivos de instruções por padrão quando o total supera 32 KiB. Um ",[20,2214,639],{"href":296,"rel":2215},[24]," descobriu que arquivos de contexto aumentam os custos de inferência em mais de 20% em média sem melhorar o sucesso em geral, então cada linha tem um custo. Na prática, a maioria dos bons arquivos tem entre 30 e 80 linhas.",[385,2218,2220],{"id":2219},"meu-agentsmd-é-longo-demais","Meu AGENTS.md é longo demais?",[16,2222,2223],{},"Provavelmente, se ele explica por que você escolheu seu stack, contém uma árvore de diretórios ou lista de dependências, inclui procedimentos passo a passo, tem duas regras que se contradizem ou você não se lembra mais por que metade das regras existe. O Claude Code também avisa ao iniciar se um arquivo ultrapassar o limite recomendado. Delete tudo o que o agente poderia ler diretamente do código e mova procedimentos para skills.",[385,2225,2227],{"id":2226},"o-que-é-um-arquivo-agentsmd","O que é um arquivo AGENTS.md?",[16,2229,2230],{},"AGENTS.md é um arquivo Markdown na raiz de um repositório de código que fornece instruções específicas do projeto para agentes de programação com IA: comandos de build, estilo de código, restrições de arquitetura, testes e limites. Mais de 20 ferramentas o leem nativamente, incluindo OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Jules, Zed, Windsurf e Devin. O Claude Code o lê quando o projeto não tem um CLAUDE.md. Mais de 60.000 projetos open source o utilizam, e ele está sob a tutela da Agentic AI Foundation na Linux Foundation.",[385,2232,2234],{"id":2233},"o-que-fazer-se-meu-agente-ignorar-uma-regra","O que fazer se meu agente ignorar uma regra?",[16,2236,2237,2238,2240],{},"Primeiro verifique se o arquivo foi realmente carregado (",[53,2239,1109],{}," no Claude Code, ou peça ao Codex que resuma suas instruções). Depois torne a regra mais concreta e adicione um exemplo. Em seguida procure uma segunda regra que a contradiga. Se a regra nunca pode ser quebrada, não dependa do arquivo: use um hook ou uma configuração de permissões que se aplique independentemente do que o agente decidir.",[385,2242,2244],{"id":2243},"o-claude-code-lê-o-agentsmd","O Claude Code lê o AGENTS.md?",[16,2246,2247,2248,578,2250,2252,2253,998,2255,1078,2257,2259,2260,2262],{},"Sim, desde a versão 2.1.277 do Claude Code (18 de setembro de 2026). Por padrão ele lê AGENTS.md apenas quando não há nenhum CLAUDE.md, ",[53,2249,935],{},[53,2251,938],{}," no seu diretório de trabalho ou acima. Para que leia ambos, defina ",[36,2254,997],{},[53,2256,1005],{},[53,2258,993],{},", ou escreva ",[53,2261,916],{}," no seu CLAUDE.md. Ele não lê AGENTS.override.md nem AGENTS.local.md.",[385,2264,2266],{"id":2265},"como-agentsmd-claudemd-e-cursorrules-se-relacionam","Como AGENTS.md, CLAUDE.md e .cursorrules se relacionam?",[16,2268,2269,2270,2273,2274,380],{},"AGENTS.md tem a compatibilidade mais ampla. CLAUDE.md é o arquivo próprio do Claude Code e adiciona importações ",[53,2271,2272],{},"@"," e regras por caminho. .cursorrules adiciona regras específicas do Cursor baseadas em globs. A maior parte do conteúdo é idêntica nos três. Comece com AGENTS.md como única fonte de verdade e, se adicionar um CLAUDE.md, comece-o com um import ",[53,2275,916],{},[385,2277,2279],{"id":2278},"devo-usar-um-llm-para-gerar-meu-agentsmd","Devo usar um LLM para gerar meu AGENTS.md?",[16,2281,2282],{},"Não. No estudo da ETH de Zurique, arquivos de contexto gerados por LLM reduziram o sucesso em 5 de 8 cenários e adicionaram entre 2,45 e 3,92 passos extras por tarefa. LLMs escrevem conselhos genéricos que o agente já segue. Escreva à mão, ou trate um rascunho gerado por IA como algo que você vai cortar, não commitar.",[385,2284,2286],{"id":2285},"posso-usar-o-mesmo-agentsmd-para-codex-e-claude-code","Posso usar o mesmo AGENTS.md para Codex e Claude Code?",[16,2288,2289,2290,2292],{},"Sim. O Codex o lê nativamente; o Claude Code o lê enquanto o projeto não tiver um CLAUDE.md, e caso contrário precisa de um import ",[53,2291,916],{}," no CLAUDE.md. Lembre que o Claude Code ignora o AGENTS.override.md do Codex. Por isso mantenha regras compartilhadas em arquivos AGENTS.md normais e execute cada comando do arquivo num terminal limpo antes de confiar nele.",[385,2294,2296],{"id":2295},"commito-o-agentsmd-ou-o-adiciono-ao-gitignore","Commito o AGENTS.md ou o adiciono ao .gitignore?",[16,2298,2299],{},"Commite-o. É documentação do projeto e pertence à raiz do repositório para que cada colaborador e cada ferramenta leiam as mesmas instruções. Mantenha preferências pessoais no arquivo global da sua ferramenta e nunca inclua secrets.",[385,2301,2303],{"id":2302},"os-princípios-do-agentsmd-podem-ser-aplicados-a-agentes-de-negócio","Os princípios do AGENTS.md podem ser aplicados a agentes de negócio?",[16,2305,2306],{},"Sim. A mesma ideia (contexto breve e específico sobre identidade, capacidades, restrições e limites) se aplica a qualquer agente de IA. Para agentes de negócio, as seções são identidade, capacidades, restrições, níveis de confiança, regras de escalonamento e formato de saída, e são mais fáceis de gerenciar num construtor visual como a BetterClaw do que num arquivo Markdown.",[2308,2309,2310],"style",{},"html pre.shiki code .surfw, html code.shiki .surfw{--shiki-default:#005CC5;--shiki-default-font-weight:bold}html pre.shiki code .sgsFI, html code.shiki .sgsFI{--shiki-default:#24292E}html pre.shiki code .sYu0t, html code.shiki .sYu0t{--shiki-default:#005CC5}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html pre.shiki code .sLX6V, html code.shiki .sLX6V{--shiki-default:#24292E;--shiki-default-font-style:italic}",{"title":51,"searchDepth":66,"depth":66,"links":2312},[2313,2314,2315,2324,2325,2326,2331,2332,2333,2334,2335,2336,2337,2338,2339,2340,2341,2342,2347,2348],{"id":43,"depth":66,"text":44},{"id":226,"depth":66,"text":30},{"id":365,"depth":66,"text":366,"children":2316},[2317,2318,2319,2320,2321,2322,2323],{"id":387,"depth":73,"text":388},{"id":400,"depth":73,"text":401},{"id":428,"depth":73,"text":429},{"id":435,"depth":73,"text":436},{"id":442,"depth":73,"text":443},{"id":455,"depth":73,"text":456},{"id":475,"depth":73,"text":476},{"id":502,"depth":66,"text":503},{"id":551,"depth":66,"text":552},{"id":621,"depth":66,"text":622,"children":2327},[2328,2329,2330],{"id":631,"depth":73,"text":632},{"id":649,"depth":73,"text":650},{"id":771,"depth":73,"text":772},{"id":781,"depth":66,"text":782},{"id":794,"depth":66,"text":795},{"id":860,"depth":66,"text":828},{"id":1038,"depth":66,"text":1039},{"id":1113,"depth":66,"text":1114},{"id":1225,"depth":66,"text":1226},{"id":1260,"depth":66,"text":1261},{"id":1374,"depth":66,"text":1375},{"id":1388,"depth":66,"text":1389},{"id":1418,"depth":66,"text":1419},{"id":1495,"depth":66,"text":1496},{"id":1786,"depth":66,"text":1787,"children":2343},[2344,2345,2346],{"id":1793,"depth":73,"text":1794},{"id":1890,"depth":73,"text":1891},{"id":2037,"depth":73,"text":2038},{"id":2186,"depth":66,"text":2187},{"id":2204,"depth":66,"text":2205,"children":2349},[2350,2351,2352,2353,2354,2355,2356,2357,2358,2359],{"id":2208,"depth":73,"text":2209},{"id":2219,"depth":73,"text":2220},{"id":2226,"depth":73,"text":2227},{"id":2233,"depth":73,"text":2234},{"id":2243,"depth":73,"text":2244},{"id":2265,"depth":73,"text":2266},{"id":2278,"depth":73,"text":2279},{"id":2285,"depth":73,"text":2286},{"id":2295,"depth":73,"text":2296},{"id":2302,"depth":73,"text":2303},"Best Practices","2026-10-30","Qual o tamanho ideal do AGENTS.md (menos de 100 linhas), modelo para copiar, exemplos, como Codex e Claude Code o carregam e como evitar regras acumuladas.",false,"/img/blog/agents-md-best-practices-pt.jpg",675,1200,null,"pt-BR",{"canonical":2370},"https://www.betterclaw.io/blog/agents-md-best-practices","/blog/agents-md-best-practices-pt-br","16 min de leitura",{"title":5,"description":2362},"AGENTS.md: Boas Práticas, Tamanho, Modelo e Exemplos","blog/agents-md-best-practices-pt-br","Como escrever um AGENTS.md que os agentes de código com IA realmente seguem: o tamanho certo (e por que menor vence), um modelo para copiar e colar, exemplos reais, como Codex e Claude Code o carregam e o ciclo de vida das regras que evita que ele apodreça.",[2378,2379,2380,2381,2382,2383,2384,2385,2386,2387],"agents.md best practices","how long should agents.md be","agents md too long","agents md max length","agents md file","agents md template","agents md example","agents md size","codex agents md","global agents md","2026-10-23","GMhoN_TM2_oRkytKf_p9KQZ5_MbrzqigeqN-npgjL5A",[2391,2400,2409],{"stem":2392,"title":2393,"description":2394,"date":2395,"image":2396,"category":2397,"redirected":2363,"author":2398,"readingTime":2399},"blog/pi-coding-agent-setup","Pi Coding Agent: Install, Models and Extensions (2026)","Install Pi 1.4, connect a model with /login or an API key, add MCP servers and extensions, and fix the common errors. Every command tested.","2026-10-26","/img/blog/pi-coding-agent-setup.jpg","Guides",{"name":7,"role":8,"avatar":9,"bio":11},"10 min read",{"stem":2401,"title":2402,"description":2403,"date":2404,"image":2405,"category":2406,"redirected":2363,"author":2407,"readingTime":2408},"blog/231k-weekly-impressions-two-people-zero-ad-spend","How We Got 231K Weekly Google Impressions With 2 People and $0 Ad Spend","We went from 769 to 1,952 weekly clicks in 10 weeks with no ads. Here's the GSC data, what flopped, and the content formula we'd use if starting over.","2026-07-15","/img/blog/231k-weekly-impressions-two-people-zero-ad-spend.jpg","Strategy",{"name":7,"role":8,"avatar":9,"bio":11},"9 min read",{"stem":2410,"title":2411,"description":2412,"date":2413,"image":2414,"category":2360,"redirected":2363,"author":2415,"readingTime":2416},"blog/agents-md-best-practices","AGENTS.md Best Practices: How Long It Should Be, Template, Examples","How long AGENTS.md should be (under 100 lines), a copy-paste template, examples, how Codex and Claude Code load it, and how to stop rules piling up.","2026-06-11","/img/blog/agents-md-best-practices.jpg",{"name":7,"role":8,"avatar":9,"bio":11},"16 min read",1793359752838]