[{"data":1,"prerenderedAt":2416},["ShallowReactive",2],{"blog-post-agents-md-best-practices-es":3,"related-posts-agents-md-best-practices-es":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-es.md","Buenas prácticas de AGENTS.md: cuánto debe medir, plantilla y ejemplos",{"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,862,880,921,924,1025,1031,1037,1041,1053,1066,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 es un archivo Markdown en la raíz de un repositorio de código que le indica a los agentes de programación con IA cómo trabajar en ese proyecto: stack, comandos de compilación y prueba, estilo de código, restricciones de arquitectura y límites. La página ",[20,21,25],"a",{"href":22,"rel":23},"https://agents.md",[24],"nofollow","agents.md"," lista más de 20 herramientas que lo leen, incluidas OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Jules, Zed, Windsurf, Devin, Aider y opencode. Claude Code también lo lee, aunque por defecto solo cuando el proyecto no tiene un CLAUDE.md.",[28,29,32],"callout",{"label":30,"type":31},"¿Cuánto debe medir AGENTS.md?","quick-answer",[16,33,34,35,39],{},"Apunta a ",[36,37,38],"strong",{},"menos de 100 líneas"," y considera que 150 es el punto en el que hay que empezar a borrar. El límite propio de Anthropic para CLAUDE.md es de 200 líneas, y Codex deja de cargar archivos de instrucciones cuando el total alcanza 32 KiB. Los archivos más cortos cuestan menos y son más fáciles de seguir para el agente. Agrega una regla solo cuando un agente cometa un error y bórrala cuando el agente lo haga bien sin que se lo indiques.",[41,42,44],"h2",{"id":43},"plantilla-mínima-de-agentsmd-cópiala","Plantilla mínima de AGENTS.md (cópiala)",[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],{},"Sustituye tu propio stack y comandos, mantenlo corto y agrega secciones solo cuando un agente cometa un error. ",[20,187,189],{"href":188},"#the-annotated-template-copy-and-adapt","La versión anotada"," más adelante explica qué va en cada sección.",[16,192,193,194,197,198,203],{},"El formato está definido en ",[20,195,25],{"href":22,"rel":196},[24]," y mantenido en GitHub (",[20,199,202],{"href":200,"rel":201},"https://github.com/agentsmd/agents.md",[24],"agentsmd/agents.md","). Más de 60.000 proyectos de código abierto lo utilizan, y ahora está bajo la tutela de la Agentic AI Foundation, parte de la Linux Foundation. Aun así, la mayoría de los archivos AGENTS.md son demasiado largos, demasiado vagos o generados por un LLM, lo que empeora al agente. Aquí te explicamos cómo escribir uno que funcione y siga funcionando.",[16,205,206],{},"Nuestro agente de programación generaba componentes de clase sin parar. Toda la base de código era React funcional con hooks. El README decía \"React 19, functional components\". La guía de contribución lo explicaba con detalle.",[16,208,209],{},"El agente no leyó el README. No sabe que debería hacerlo.",[16,211,212],{},"Entonces agregamos un archivo AGENTS.md con una sola línea en la sección de estilo: Always use functional components with hooks. Never use class components. Y un ejemplo de código que mostraba la forma correcta.",[16,214,215],{},"El problema desapareció de inmediato.",[16,217,218,219,223],{},"¿Trabajas con más de un agente? Lee cómo ",[20,220,222],{"href":221},"/blog/agents-md-multi-agent-best-practices","organizar AGENTS.md para múltiples agentes"," sin conflictos ni desviaciones.",[41,225,30],{"id":226},"cuánto-debe-medir-agentsmd",[16,228,229],{},"Respuesta corta: menos de 100 líneas es el objetivo, 150 es la señal de alerta y 200 es el límite máximo que Anthropic establece para su propio equivalente. En la práctica, la mayoría de los buenos archivos tienen entre 30 y 80 líneas.",[16,231,232],{},"De dónde viene cada cifra (cada una mide algo distinto, verificado el 23 de octubre de 2026):",[234,235,236,252],"table",{},[237,238,239],"thead",{},[240,241,242,246,249],"tr",{},[243,244,245],"th",{},"Fuente",[243,247,248],{},"Qué dice",[243,250,251],{},"Qué mide",[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],"Documentación de memoria de Claude Code de Anthropic",[258,266,267],{},"\"Apunta a menos de 200 líneas por archivo CLAUDE.md. Los archivos más largos consumen más contexto y reducen el seguimiento.\" Claude Code muestra una advertencia al inicio si un archivo supera el límite recomendado.",[258,269,270],{},"Recomendación oficial para CLAUDE.md, que cumple el mismo 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],{},"Deja de agregar archivos de instrucciones cuando el tamaño total alcanza ",[53,284,285],{},"project_doc_max_bytes",", que por defecto es 32 KiB",[258,288,289],{},"Un límite de carga estricto para toda la cadena de archivos, no un objetivo de calidad",[240,291,292,299,302],{},[258,293,294],{},[20,295,298],{"href":296,"rel":297},"https://arxiv.org/abs/2602.11988",[24],"Estudio de la ETH de Zúrich (arXiv:2602.11988)",[258,300,301],{},"Los archivos de contexto \"no mejoran la tasa de éxito en las tareas en general, pero aumentan los costos de inferencia en más del 20% de media\"",[258,303,304],{},"Costo y éxito de los archivos de contexto en general, no de la longitud en particular",[240,306,307,310,313],{},[258,308,309],{},"Foros de desarrollo (octubre de 2026)",[258,311,312],{},"Los archivos que crecen hasta cientos de líneas suelen ignorarse; el consenso práctico es menos de 100 líneas",[258,314,315],{},"Experiencia práctica, no un estudio controlado",[16,317,318],{},"¿Por qué decimos menos de 100 si Anthropic dice 200? Porque cada línea se carga en cada sesión, cada línea cuesta tokens en cada ejecución y casi cada línea más allá de las primeras 50 es una regla que el modelo seguiría de todas formas. El equipo de la ETH de Zúrich descubrió que los resúmenes de repositorio —lo que los proveedores de modelos recomiendan incluir con más frecuencia— básicamente no servían de nada, porque los agentes leen la base de código directamente. Elimínalos y la mayoría de los archivos quedan muy por debajo de 100 líneas.",[16,320,321,322,327],{},"Dos limitaciones honestas. Primero: un estudio controlado de Damon McMillan de 2026 (",[20,323,326],{"href":324,"rel":325},"https://arxiv.org/abs/2605.10039",[24],"arXiv:2605.10039",", 1650 sesiones de Claude Code, 16.050 observaciones) descubrió que, para una única regla simple de estilo de código, ni el tamaño del archivo ni la posición de la regla ni dividir el archivo ni un archivo contradictorio en una carpeta adyacente producían una diferencia medible en el seguimiento. Lo que sí importaba era la tarea y cuánto había avanzado ya el agente en la sesión: cada función adicional que escribía se asociaba con aproximadamente un 5,6% menos de probabilidad de seguir la regla. La longitud, por tanto, no es mágica. Segundo: ese estudio probó una única regla trivial en modelos Claude. Los archivos reales contienen docenas de reglas que compiten por la atención, y ahí es exactamente donde entra en juego la advertencia de Anthropic sobre el seguimiento.",[16,329,330],{},"La lectura práctica: un archivo corto no arregla una tarea mal planteada, pero uno largo hace que cualquier tarea sea más cara y le da al agente más oportunidades de ignorar justo la regla que importa.",[16,332,333],{},"Señales de que tu AGENTS.md es demasiado largo:",[335,336,337,341,344,347,350,353],"ul",{},[338,339,340],"li",{},"Explica por qué elegiste tu stack o describe la historia del proyecto.",[338,342,343],{},"Contiene un árbol de directorios o una lista de dependencias que el agente podría leer directamente del repositorio.",[338,345,346],{},"Incluye un procedimiento paso a paso (una checklist de lanzamiento, un runbook de migración). Eso pertenece a una skill que solo se carga cuando se necesita.",[338,348,349],{},"Encuentras dos reglas que dicen cosas distintas sobre el mismo comportamiento.",[338,351,352],{},"Claude Code te advierte al inicio, o Codex descarta en silencio los archivos que superan los 32 KiB.",[338,354,355],{},"Ya no recuerdas por qué existe la mitad de las reglas.",[16,357,358],{},[359,360],"img",{"alt":361,"src":362},"La etiqueta nutricional de AGENTS.md: en menos de 100 líneas, con stack, comandos, estilo de código con ejemplos, límites y una sección corta de git.","/img/blog/agents-md-best-practices-nutrition-label-es.jpg",[41,364,366],{"id":365},"qué-va-en-un-agentsmd-y-qué-no","Qué va en un AGENTS.md (y qué no)",[16,368,369],{},"El error común es tratar AGENTS.md como documentación. Explicaciones largas. Filosofía de arquitectura. Justificaciones de diseño. Historia del proyecto.",[16,371,372,373,376,377,380],{},"Tu agente no necesita saber por qué elegiste Next.js en lugar de Remix. Necesita saber que usas Next.js 15 con App Router y que el comando de prueba es ",[53,374,375],{},"pnpm test",", no ",[53,378,379],{},"npm test",".",[16,382,383],{},"Estas son las secciones que importan, en el orden en que deben aparecer:",[385,386,388],"h3",{"id":387},"stack-del-proyecto-5-a-10-líneas","Stack del proyecto (5 a 10 líneas)",[16,390,391],{},"Lenguaje, framework, dependencias clave, runtime. Sé concreto.",[16,393,394],{},"Bien: Next.js 15 App Router, React 19, TypeScript 5.4, Tailwind CSS, Drizzle ORM, Bun",[16,396,397],{},"Mal: Esta es una aplicación web moderna construida con React y varias bibliotecas de soporte.",[385,399,401],{"id":400},"comandos-de-compilación-y-prueba-5-a-10-líneas","Comandos de compilación y prueba (5 a 10 líneas)",[16,403,404],{},"Comandos exactos con flags exactas. El gestor de paquetes importa. Los targets de compilación importan.",[16,406,407,408,411,412,415,416,419,420],{},"Bien: 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],{},"Mal: Ejecuta los comandos habituales de compilación y prueba como se describe en el package.json.",[385,427,429],{"id":428},"convenciones-de-estilo-de-código-10-a-20-líneas-con-ejemplos","Convenciones de estilo de código (10 a 20 líneas, con ejemplos)",[16,431,432],{},"Un ejemplo de código por convención vale más que tres párrafos de descripción. Esta es la enseñanza más importante de los archivos AGENTS.md eficaces. Mostrar, no contar.",[385,434,436],{"id":435},"restricciones-de-arquitectura-5-a-15-líneas","Restricciones de arquitectura (5 a 15 líneas)",[16,438,439],{},"Reglas de estructura de directorios. Límites de módulos. Restricciones de importación. Dirección del flujo de datos.",[385,441,443],{"id":442},"límites-5-a-10-líneas","Límites (5 a 10 líneas)",[16,445,446,447,452],{},"Qué no debe tocar nunca el agente. \"Nunca hacer commit de secrets\" fue la restricción útil más frecuente en el ",[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álisis de GitHub de más de 2500 archivos agents.md",". Agrega: archivos generados, módulos legacy, archivos de configuración que no deben cambiar y directorios gestionados por otras herramientas.",[385,454,456],{"id":455},"flujo-de-trabajo-de-git-5-líneas","Flujo de trabajo de Git (5 líneas)",[16,458,459,460,463,464,463,467,463,470,380],{},"Nombres de ramas, formato de mensajes de commit, convenciones de PR. Solo 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},"qué-dejar-fuera","Qué dejar fuera",[16,478,479,480,484,485,380],{},"Los procedimientos de varios pasos (una checklist de lanzamiento, un runbook de migración) no pertenecen a un archivo que se carga en cada sesión. La documentación de memoria de Anthropic dice lo mismo sobre CLAUDE.md: muévelos a una skill que el agente solo carga cuando la tarea lo requiere. Nuestra guía ",[20,481,483],{"href":482},"/blog/agent-skills-vs-mcp","Agent Skills vs. MCP"," explica dónde trazar esa línea, y la carga bajo demanda es una razón clave por la que ",[20,486,488],{"href":487},"/blog/skills-that-reduce-token-usage","las skills pueden reducir el uso de tokens",[16,490,491,492,496],{},"Las conexiones de herramientas tampoco van aquí. Esos son servidores MCP configurados en la propia herramienta (ver ",[20,493,495],{"href":494},"/blog/what-is-mcp-model-context-protocol","qué es MCP","). AGENTS.md puede decir cuándo usar una herramienta, no cómo conectarse a ella.",[16,498,499],{},"Las reglas que nunca deben romperse tampoco van aquí. AGENTS.md es orientación, no aplicación. Si algo debe ocurrir siempre antes de cada commit o nunca debe ocurrir, usa un pre-commit hook, un hook de Claude Code o una regla de permisos. El archivo puede explicar la regla; el hook la aplica.",[41,501,503],{"id":502},"el-ciclo-de-vida-de-las-reglas-agrégala-cuando-falle-bórrala-cuando-se-aprenda","El ciclo de vida de las reglas: agrégala cuando falle, bórrala cuando se aprenda",[16,505,506],{},"Este hábito mantiene un AGENTS.md corto durante años, no solo semanas.",[508,509,510,516,522,528,534],"ol",{},[338,511,512,515],{},[36,513,514],{},"Empieza con 30 a 50 líneas:"," stack, comandos, estilo de código con un ejemplo cada uno, límites.",[338,517,518,521],{},[36,519,520],{},"Agrega una regla solo cuando un agente cometa un error más de una vez."," Un error puede ser de la tarea; dos son una laguna en el archivo.",[338,523,524,527],{},[36,525,526],{},"Formula la regla como una directiva con ejemplo, no como una explicación."," \"Money is Decimal, never float\" vale más que un párrafo sobre precisión.",[338,529,530,533],{},[36,531,532],{},"Prueba sin la regla cada pocas semanas o después de una actualización de modelo."," Borra la línea y ejecuta el mismo tipo de tarea. Si el agente lo hace bien sin indicaciones, la regla es peso muerto. Los modelos más nuevos siguen por sí solos muchas convenciones que los más antiguos necesitaban que les escribieran.",[338,535,536,539],{},[36,537,538],{},"Revisa el archivo completo cada trimestre,"," y en el mismo PR cuando cambie una convención.",[16,541,542],{},"Una prueba útil para cada línea: ¿un desarrollador competente que nunca haya visto este repositorio cometería este error? Si no, bórrala. Estás pagando tokens para predecirle al modelo sus propios valores predeterminados.",[16,544,545],{},[359,546],{"alt":547,"src":548},"Trata tu AGENTS.md como un bonsái: agrega cuando falle, poda cuando aprenda.","/img/blog/agents-md-best-practices-bonsai.jpg",[41,550,552],{"id":551},"las-reglas-contradictorias-hacen-más-daño-que-las-duplicadas","Las reglas contradictorias hacen más daño que las duplicadas",[16,554,555],{},"Una regla duplicada desperdicia unos pocos tokens. Una contradicción hace que el comportamiento del agente sea impredecible, porque tiene que elegir un lado y tú no controlas cuál.",[16,557,558,559,563],{},"Anthropic lo dice directamente en su ",[20,560,562],{"href":262,"rel":561},[24],"documentación de memoria",": \"Si dos instrucciones se contradicen, Claude puede elegir una de forma arbitraria.\" Esto aplica entre archivos también: tu archivo raíz, un archivo de subdirectorio, un archivo global personal y cualquier archivo de reglas terminan en el mismo contexto.",[16,565,566],{},"Dónde se esconden las contradicciones:",[335,568,569,572,583,586],{},[338,570,571],{},"Un archivo raíz que dice \"usa Jest\" y el archivo de un paquete que dice \"usa Vitest\" sin aclarar que eso es solo para ese paquete.",[338,573,574,575,578,579,582],{},"Tu archivo global personal (",[53,576,577],{},"~/.codex/AGENTS.md"," o ",[53,580,581],{},"~/.claude/CLAUDE.md",") con una regla específica del proyecto que es incorrecta en otros repositorios.",[338,584,585],{},"Una regla antigua que nunca se borró después de una migración (\"use the v1 API client\").",[338,587,588],{},"Una regla y su excepción en secciones distintas.",[16,590,591],{},"Cómo encontrarlas:",[335,593,594,604,610],{},[338,595,596,603],{},[36,597,598,599,602],{},"Ejecuta ",[53,600,601],{},"/doctor prompt-audit"," en Claude Code"," (versión 2.1.283 en adelante). La documentación de Anthropic lo describe como una comprobación que \"encuentra instrucciones para modelos más antiguos, referencias a archivos o comandos inexistentes y archivos que se contradicen entre sí\", y sugiere cambios sin modificar nada hasta que des tu aprobación. Por defecto cubre tus archivos CLAUDE.md, CLAUDE.local.md y AGENTS.md.",[338,605,606,609],{},[36,607,608],{},"En cualquier herramienta, puedes preguntarle al agente:"," \"List every instruction you've been given about testing, and flag any two that conflict.\"",[338,611,612,615],{},[36,613,614],{},"Escribe las reglas de subdirectorios como especializaciones"," (\"este paquete usa Vitest\"), nunca como inversiones del archivo raíz.",[16,617,618],{},"Un matiz por precisión: el estudio de McMillan mencionado antes encontró que un archivo contradictorio en una carpeta adyacente no tenía efecto medible sobre una única regla trivial. Eso no hace que las contradicciones sean inofensivas. Significa que el daño surge cuando reglas compiten, y eso es exactamente lo que crea un archivo que crece sin control.",[41,620,622],{"id":621},"los-tres-errores-que-dejan-agentsmd-inservible","Los tres errores que dejan AGENTS.md inservible",[16,624,625],{},[359,626],{"alt":627,"src":628},"Tres errores que arruinan AGENTS.md: Lo escribió un LLM, Describir en vez de mostrar, Nunca se actualiza.","/img/blog/agents-md-best-practices-hall-of-shame-es.jpg",[385,630,632],{"id":631},"error-1-dejarlo-escribir-a-un-llm","Error 1: dejarlo escribir a un LLM",[16,634,635,636,640],{},"Es el más común y el más dañino. En el ",[20,637,639],{"href":296,"rel":638},[24],"estudio de la ETH de Zúrich",", los archivos generados por LLM redujeron el éxito en un 0,5% en SWE-bench Lite y en un 2% en AGENTbench, perdieron en 5 de 8 escenarios y añadieron entre 2,45 y 3,92 pasos extra por tarea. Los archivos escritos por desarrolladores funcionaron mejor (unos +4% en AGENTbench), aunque también costaron hasta un 19% más.",[16,642,643],{},"¿Por qué? Los LLM generan instrucciones genéricas y verbosas que dicen lo obvio. \"Follow best practices for error handling.\" \"Write clean, maintainable code.\" \"Use descriptive variable names.\" Tu agente ya sabe todo eso.",[16,645,646],{},"Escribe tu AGENTS.md a mano. Si usas un agente para hacer un borrador, trátalo como el primer PR de un empleado nuevo: elimina todo lo genérico y conserva solo lo específico de tu proyecto.",[385,648,650],{"id":649},"error-2-describir-las-convenciones-en-lugar-de-mostrarlas","Error 2: describir las convenciones en lugar de mostrarlas",[16,652,653],{},"Mal:",[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],{},"Bien:",[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],{},"El ejemplo de código transmite al instante lo que tres párrafos de descripción no logran.",[385,770,772],{"id":771},"error-3-no-actualizarlo","Error 3: no actualizarlo",[16,774,775],{},"Un AGENTS.md con nombres de tablas obsoletos, comandos descatalogados o restricciones de arquitectura superadas es peor que no tener ninguno. Lleva activamente al agente por el camino equivocado.",[16,777,778],{},"Actualízalo en el mismo PR en el que cambian las convenciones y sigue el ciclo de vida de reglas descrito arriba. Si un agente produce repetidamente la misma salida incorrecta, hay una laguna en tu archivo. Si produce la salida correcta sin la regla, hay una línea que borrar.",[41,780,782],{"id":781},"realmente-funciona-agentsmd","¿Realmente funciona AGENTS.md?",[16,784,785],{},"Sí, pero solo la variante escrita a mano y específica.",[16,787,788],{},"El escepticismo es legítimo. Si dejaste que un agente escribiera tu AGENTS.md, lo ejecutaste y no viste mejoras, eso es exactamente lo que predice la investigación. Los autores de la ETH de Zúrich descubrieron que los agentes siguen bien las instrucciones de estos archivos. El problema es que la mayoría de los archivos están llenos de instrucciones que no cambian nada.",[16,790,791],{},"Lo que funciona es acotado: instrucciones que le dicen al agente algo que no podría haber deducido de la base de código. Tu gestor de paquetes. Tu comando de prueba con las flags exactas. El único directorio que nunca debe tocar. La convención de tu base de código que parece inusual para un modelo entrenado con el código de todos los demás.",[41,793,795],{"id":794},"agentsmd-vs-claudemd-vs-cursorrules-cuál-necesitas","AGENTS.md vs CLAUDE.md vs .cursorrules (¿cuál necesitas?)",[16,797,798],{},"Empieza con AGENTS.md y añade archivos específicos de cada herramienta solo cuando necesites sus funciones especiales.",[16,800,801],{},[359,802],{"alt":803,"src":804},"Un núcleo universal y dos extensiones: AGENTS.md primero, el resto después.","/img/blog/agents-md-best-practices-file-comparison-es.jpg",[16,806,807,810],{},[36,808,809],{},"AGENTS.md"," tiene la compatibilidad más amplia. Más de 20 herramientas lo leen de forma nativa. Es el formato universal.",[16,812,813,816,817,820,821,824,825,829],{},[36,814,815],{},"CLAUDE.md"," es el archivo propio de Claude Code. Trae funciones que AGENTS.md no tiene, como importaciones ",[53,818,819],{},"@path"," y archivos ",[53,822,823],{},".claude/rules/"," adaptados a tipos de archivo. Ya no lo necesitas para que Claude Code vea tu AGENTS.md (ver ",[20,826,828],{"href":827},"#how-claude-code-reads-agentsmd","Cómo lee Claude Code el AGENTS.md"," más adelante), pero en cuanto existe un CLAUDE.md, Claude Code deja de leer AGENTS.md por defecto. Si mantienes ambos, haz que CLAUDE.md importe el archivo compartido:",[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],{},"Mantén AGENTS.md como única fuente de verdad para todas las herramientas, y que CLAUDE.md contenga ese import más las personalizaciones de Claude que realmente necesites. Ten en cuenta que los imports organizan un archivo pero no lo reducen: la documentación de Anthropic señala que los archivos importados se cargan junto con el CLAUDE.md que los importa y por tanto cuentan en el mismo contexto. Un symlink de CLAUDE.md a AGENTS.md también funciona, pero Anthropic recomienda el import si alguien del equipo usa Windows, donde Git puede hacer checkout del symlink como un archivo de texto plano.",[16,845,846,849],{},[36,847,848],{},".cursorrules"," es específico de Cursor. Su característica especial es el frontmatter con globs de archivo que activa distintas instrucciones según el tipo de archivo. Si tu equipo usa Cursor y necesita reglas por tipo de archivo, agrégalas.",[16,851,852],{},"La mayor parte del contenido es idéntico en los tres archivos. Los comandos de compilación, las reglas de arquitectura, las convenciones de prueba y los límites no cambian de una herramienta a otra. Una utilidad llamada rule-porter puede convertir entre formatos si hace falta.",[16,854,855],{},[20,856],{"id":857},"how-claude-code-reads-agentsmd",[41,859,861],{"id":860},"cómo-lee-claude-code-el-archivo-agentsmd","Cómo lee Claude Code el archivo AGENTS.md",[16,863,864,865,870,871,874,875,879],{},"Claude Code lee AGENTS.md desde la ",[20,866,869],{"href":867,"rel":868},"https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md",[24],"versión 2.1.277"," (publicada el 18 de septiembre de 2026), con una condición importante: por defecto lee AGENTS.md ",[36,872,873],{},"solo cuando no hay un CLAUDE.md",". Esto viene directamente de la ",[20,876,878],{"href":262,"rel":877},[24],"documentación de memoria de Anthropic",":",[234,881,882,892],{},[237,883,884],{},[240,885,886,889],{},[243,887,888],{},"Tu repositorio contiene",[243,890,891],{},"Claude Code lee",[253,893,894,902,910],{},[240,895,896,899],{},[258,897,898],{},"Un AGENTS.md y ningún CLAUDE.md ni CLAUDE.local.md en tu directorio de trabajo o por encima",[258,900,901],{},"Tu AGENTS.md",[240,903,904,907],{},[258,905,906],{},"Un AGENTS.md y un CLAUDE.md o CLAUDE.local.md en tu directorio de trabajo o por encima",[258,908,909],{},"Solo tus archivos CLAUDE.md",[240,911,912,918],{},[258,913,914,915],{},"Un CLAUDE.md que importa AGENTS.md con ",[53,916,917],{},"@AGENTS.md",[258,919,920],{},"Tu CLAUDE.md, con AGENTS.md incluido mediante el import",[16,922,923],{},"Los detalles que suelen causar problemas:",[335,925,926,947,953,969,986,1015],{},[338,927,928,931,932,463,934,578,937,940,941,943,944,946],{},[36,929,930],{},"Qué cuenta como \"un CLAUDE.md\":"," un ",[53,933,815],{},[53,935,936],{},".claude/CLAUDE.md",[53,938,939],{},"CLAUDE.local.md"," en tu directorio de trabajo o en cualquier directorio por encima. Tu ",[53,942,581],{}," personal, el CLAUDE.md gestionado de tu organización y los archivos ",[53,945,823],{}," no cuentan y se siguen cargando junto a AGENTS.md.",[338,948,949,952],{},[36,950,951],{},"La trampa de CLAUDE.local.md:"," si creas un CLAUDE.local.md para tus notas personales sin commitear, Claude Code silenciosamente deja de leer el AGENTS.md de tu equipo.",[338,954,955,958,959,961,962,965,966],{},[36,956,957],{},"Qué se carga:"," cada ",[53,960,809],{}," y ",[53,963,964],{},".claude/AGENTS.md"," desde tu directorio de trabajo hacia arriba al iniciar la sesión, más el AGENTS.md de un subdirectorio cuando Claude abre un archivo ahí. En una sesión interactiva verás una línea como ",[53,967,968],{},"no CLAUDE.md found; AGENTS.md loaded: ....",[338,970,971,974,975,463,978,981,982,985],{},[36,972,973],{},"Qué se ignora:"," ",[53,976,977],{},"AGENTS.local.md",[53,979,980],{},"AGENTS.override.md"," y todo lo que esté dentro de un directorio ",[53,983,984],{},".agents/",". El archivo override es una convención de Codex, no de Claude Code.",[338,987,988,991,992,995,996,999,1000,1003,1004,1007,1008,1011,1012,380],{},[36,989,990],{},"Cambiar el comportamiento predeterminado:"," escribe ",[53,993,994],{},"/config"," y establece ",[36,997,998],{},"Project instructions"," en ",[53,1001,1002],{},"claude-md-or-agents-md"," (el valor por defecto), ",[53,1005,1006],{},"claude-md-and-agents-md"," (leer ambos, con CLAUDE.md primero por directorio), ",[53,1009,1010],{},"claude-md"," (ignorar AGENTS.md) o ",[53,1013,1014],{},"managed-only",[338,1016,1017,1020,1021,1024],{},[36,1018,1019],{},"Advertencias de tamaño:"," Claude Code avisa al inicio y en ",[53,1022,1023],{},"/status"," cuando un archivo supera el límite recomendado y cuando varios archivos individualmente aceptables superan juntos un límite compartido.",[16,1026,1027,1028,1030],{},"Dos notas sobre versiones. Antes de v2.1.281 (23 de septiembre de 2026), las sesiones en Amazon Bedrock, Google Vertex AI, Microsoft Foundry, gateways LLM o con telemetría desactivada seguían leyendo solo CLAUDE.md. Y la primera sesión tras actualizar desde v2.1.276 o anterior puede que aún no recoja AGENTS.md; se cargará a partir de la siguiente sesión. Si usas una versión más antigua, el import ",[53,1029,917],{}," dentro de un CLAUDE.md funciona en todas partes y nunca hace que el archivo se lea dos veces.",[16,1032,1033,1034,1036],{},"Si antes lo habías conectado a mano, el consejo de Anthropic es: mantén un CLAUDE.md que solo contenga ",[53,1035,917],{}," (es inofensivo), o bórralo; reemplaza un CLAUDE.md que en palabras instruya a Claude a leer AGENTS.md por un import real; y elimina cualquier hook SessionStart que imprima AGENTS.md, porque ahora añade una segunda copia al contexto.",[41,1038,1040],{"id":1039},"claude-code-no-lee-agentsmd-las-cuatro-causas","¿Claude Code no lee AGENTS.md? Las cuatro causas",[16,1042,1043,1044,1047,1048,1052],{},"Si Claude Code ignora tu AGENTS.md, casi siempre es por una de estas cuatro razones. Compruébalas en este orden. Todo lo que aparece aquí proviene de la ",[20,1045,878],{"href":262,"rel":1046},[24]," y del ",[20,1049,1051],{"href":867,"rel":1050},[24],"changelog de Claude Code",", verificado el 23 de octubre de 2026.",[16,1054,1055,1058,1059,961,1061,1063,1064,380],{},[36,1056,1057],{},"1. El archivo está en el lugar o con el nombre equivocado."," Al iniciar la sesión, Claude Code carga ",[53,1060,809],{},[53,1062,964],{}," desde tu directorio de trabajo y cualquier directorio por encima. Si inicias Claude en una carpeta superior al repositorio, el AGENTS.md del repo es un archivo de subdirectorio y no se carga al inicio. Inicia en la raíz del repo y llama al archivo exactamente ",[53,1065,809],{},[16,1067,1068,1071,1072,1074,1075,999,1077,999,1079,1081,1082,1084,1085,1087],{},[36,1069,1070],{},"2. Un CLAUDE.md tiene prioridad."," Lo más habitual es que el culpable sea un CLAUDE.local.md olvidado. Agrega ",[53,1073,917],{}," al CLAUDE.md, o establece ",[36,1076,998],{},[53,1078,1006],{},[53,1080,994],{},". Comprueba que la configuración no sea ",[53,1083,1010],{}," ni ",[53,1086,1014],{},", porque ambas omiten AGENTS.md por completo.",[16,1089,1090,1093,1094,1097],{},[36,1091,1092],{},"3. Estás usando una versión con un bug ya corregido."," Ejecuta ",[53,1095,1096],{},"claude --version",". Antes de v2.1.281, las sesiones con Bedrock, Vertex, Foundry, gateway y sin telemetría solo leían CLAUDE.md. La v2.1.290 (5 de octubre de 2026) corrigió que el AGENTS.md de un subdirectorio no se añadiera cuando mencionabas un archivo de ese directorio con @. Actualiza Claude Code y abre una nueva sesión.",[16,1099,1100,1103],{},[36,1101,1102],{},"4. Es un archivo anidado que aún no se ha cargado."," El AGENTS.md de un subdirectorio no se lee al inicio. Claude Code lo carga cuando Claude abre un archivo en ese directorio, y solo si dicho directorio no tiene su propio CLAUDE.md. Pon en el archivo raíz las reglas que siempre deben aplicarse.",[16,1105,1106,1107,1110],{},"Para confirmar qué se cargó, ejecuta ",[53,1108,1109],{},"/memory"," y busca la ruta de tu AGENTS.md.",[41,1112,1114],{"id":1113},"agentsmd-funciona-con-openai-codex","¿AGENTS.md funciona con OpenAI Codex?",[16,1116,1117],{},"Sí. Codex lee AGENTS.md de forma nativa, y el mismo archivo funciona en Codex, Cursor, Gemini CLI y Claude Code sin modificaciones.",[16,1119,1120,1121,1125],{},"Las reglas de resolución de Codex están más estratificadas que las de la mayoría de herramientas. Según la ",[20,1122,1124],{"href":277,"rel":1123},[24],"guía de AGENTS.md de OpenAI para Codex",", construye la cadena de instrucciones una vez por ejecución:",[335,1127,1128,1148,1164],{},[338,1129,1130,1133,1134,1137,1138,1141,1142,1144,1145,1147],{},[36,1131,1132],{},"Global:"," en tu home de Codex (",[53,1135,1136],{},"~/.codex",", o donde apunte ",[53,1139,1140],{},"CODEX_HOME","), Codex lee ",[53,1143,980],{}," si existe y, si no, ",[53,1146,809],{},". Solo se usa un archivo en este nivel.",[338,1149,1150,1153,1154,1156,1157,1159,1160,1163],{},[36,1151,1152],{},"Proyecto:"," partiendo de la raíz del proyecto (generalmente la raíz de Git), desciende hasta tu directorio de trabajo actual. En cada directorio comprueba ",[53,1155,980],{},", luego ",[53,1158,809],{},", luego los nombres que hayas listado en ",[53,1161,1162],{},"project_doc_fallback_filenames",", y toma como máximo un archivo por directorio.",[338,1165,1166,1169],{},[36,1167,1168],{},"Fusión:"," los archivos se concatenan de raíz a hoja, de modo que los archivos más cercanos a tu lugar de trabajo quedan al final y anulan los anteriores.",[16,1171,1172,1175,1176,1178],{},[36,1173,1174],{},"Límite de tamaño."," Codex omite los archivos vacíos y deja de agregar archivos en cuanto el tamaño total alcanza ",[53,1177,285],{},", que por defecto es 32 KiB. Esto aplica a toda la cadena, no por archivo. Puedes aumentar el valor, pero si estás cerca del límite, es mejor borrar líneas:",[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 qué se cargó.",[53,1207,1208],{},"codex --ask-for-approval never \"Summarize the current instructions.\""," en la raíz del repo. Codex reconstruye la cadena en cada ejecución (una vez por sesión en la TUI interactiva), así que no hay caché que limpiar cuando edites un archivo; solo reinícialo. Si esa prueba termina con ",[53,1211,1212],{},"stream disconnected before completion",", es un error de conexión, no un problema del archivo de instrucciones.",[16,1215,1216],{},"Un aviso práctico. Codex ejecuta los comandos de compilación y prueba de tu AGENTS.md en su sandbox. Un comando incorrecto no genera un error útil; el agente lo ejecuta, ve que falla y rodea el obstáculo. Antes de confiar en un comando de tu AGENTS.md, ejecútalo tal cual en un terminal limpio.",[16,1218,1219,1220,1222],{},"Claude Code no lee ",[53,1221,980],{}," ni los nombres de archivo fallback de Codex. Si un repositorio sirve a ambos agentes, mantén las reglas comunes en archivos AGENTS.md normales.",[41,1224,1226],{"id":1225},"agentsmd-global-vs-a-nivel-de-directorio","AGENTS.md global vs a nivel de directorio",[16,1228,1229],{},"Hay tres alcances, y confundirlos es una fuente habitual del \"¿por qué el agente ignora mis instrucciones?\".",[16,1231,1232,1235,1236,1238],{},[36,1233,1234],{},"Global (personal)."," Un archivo en el directorio de configuración de tu herramienta, como ",[53,1237,577],{},". Se aplica a todos los proyectos que abras. Úsalo para preferencias que son tuyas, no del proyecto. No se commitea, así que tus compañeros nunca lo ven.",[16,1240,1241,1244],{},[36,1242,1243],{},"Raíz del repositorio."," El archivo que la mayoría de la gente tiene en mente cuando dice \"AGENTS.md\". Está commiteado en el repo y lo comparte todo el equipo. Úsalo para reglas que aplican en todo el proyecto.",[16,1246,1247,1250,1251,1254],{},[36,1248,1249],{},"Subdirectorio."," Amplía el archivo raíz para un directorio concreto. Úsalo cuando un directorio tiene reglas realmente distintas: un paquete con su propio comando de compilación, un directorio ",[53,1252,1253],{},"/mobile"," con un framework diferente.",[16,1256,1257],{},"La mayoría de los proyectos solo necesitan el archivo raíz. Si tu AGENTS.md raíz es demasiado largo, la solución es borrar líneas, no distribuirlas en directorios.",[41,1259,1261],{"id":1260},"agentsmd-anidado-y-global-cuál-prevalece","AGENTS.md anidado y global: cuál prevalece",[16,1263,1264,1265,1269],{},"Respuesta corta: el archivo más cercano al código que se edita gana, y lo que escribas en el chat supera cualquier archivo. Así lo expresan las ",[20,1266,1268],{"href":22,"rel":1267},[24],"FAQ de agents.md",": \"El AGENTS.md más cercano al archivo que se edita gana; los prompts explícitos del usuario en el chat anulan todo.\"",[234,1271,1272,1287],{},[237,1273,1274],{},[240,1275,1276,1278,1281,1284],{},[243,1277],{},[243,1279,1280],{},"Archivo global (personal)",[243,1282,1283],{},"Cómo interactúan los archivos anidados",[243,1285,1286],{},"Archivo override",[253,1288,1289,1304,1326],{},[240,1290,1291,1296,1299,1302],{},[258,1292,1293],{},[36,1294,1295],{},"Especificación agents.md",[258,1297,1298],{},"No definido",[258,1300,1301],{},"El archivo más cercano en el árbol de directorios tiene prioridad",[258,1303,1298],{},[240,1305,1306,1310,1318,1321],{},[258,1307,1308],{},[36,1309,279],{},[258,1311,1312,1314,1315,1317],{},[53,1313,577],{}," (o ",[53,1316,980],{}," en esa ruta), se lee primero",[258,1319,1320],{},"Un archivo por directorio desde la raíz del proyecto hacia abajo, concatenados con los archivos más cercanos al final; límite total de 32 KiB por defecto",[258,1322,1323,1325],{},[53,1324,980],{}," reemplaza al AGENTS.md de ese directorio",[240,1327,1328,1333,1339,1342],{},[258,1329,1330],{},[36,1331,1332],{},"Claude Code",[258,1334,1335,1336,1338],{},"Sin AGENTS.md global; tu archivo personal es ",[53,1337,581],{},", que se carga junto a AGENTS.md",[258,1340,1341],{},"Los archivos desde tu directorio de trabajo hacia arriba se cargan al inicio; el de un subdirectorio se carga cuando Claude abre un archivo en él",[258,1343,1344],{},"No se lee",[16,1346,1347,1348,1352],{},"Para Claude Code, la ",[20,1349,1351],{"href":262,"rel":1350},[24],"documentación de Anthropic"," describe los archivos de instrucciones como concatenados, no como que se sobreescriben entre sí, y advierte que Claude puede elegir arbitrariamente cuando hay archivos contradictorios. En Claude Code \"el más cercano gana\" es una tendencia, no una garantía. Estas reglas aplican en todas partes:",[335,1354,1355,1361,1366],{},[338,1356,1357,1360],{},[36,1358,1359],{},"No contradigas, especializa."," Un archivo de subdirectorio debe añadir reglas para ese directorio, no invertir las del archivo raíz.",[338,1362,1363],{},[36,1364,1365],{},"Preferencias personales en global, reglas del proyecto en el repo.",[338,1367,1368,1371],{},[36,1369,1370],{},"Dilo en el prompt cuando sea importante."," Una excepción puntual va en el prompt, no en un cambio de AGENTS.md.",[41,1373,1375],{"id":1374},"se-debe-commitear-agentsmd-en-git","¿Se debe commitear AGENTS.md en git?",[16,1377,1378],{},"Sí. AGENTS.md pertenece al control de versiones, junto al código que describe, en la raíz del repositorio. Cada colaborador y cada herramienta de IA lo lee desde ahí, y los cambios se revisan en el mismo PR que el cambio de convención que los originó.",[16,1380,1381,1382,1385],{},"Dos excepciones. Las preferencias personales van en tu archivo global, no en el repositorio. Y nunca incluyas secrets o URLs internas directamente; haz referencia a ellos desde ",[53,1383,1384],{},".env"," o desde un archivo excluido por gitignore.",[41,1387,1389],{"id":1388},"seguridad-agentsmd-es-una-superficie-de-inyección-de-prompts","Seguridad: AGENTS.md es una superficie de inyección de prompts",[16,1391,1392,1393,1398],{},"El equipo de IA Red Team de NVIDIA demostró una inyección indirecta de AGENTS.md contra OpenAI Codex en la que una ",[20,1394,1397],{"href":1395,"rel":1396},"https://developer.nvidia.com/blog/mitigating-indirect-agents-md-injection-attacks-in-agentic-environments/",[24],"dependencia maliciosa secuestra el comportamiento del agente"," explotando el orden de precedencia de las instrucciones. El ataque requiere una dependencia ya comprometida, así que no hay razón para entrar en pánico con cada repositorio que clones. Pero demuestra que los archivos de instrucciones para agentes son contexto ejecutable y amplían la superficie de ataque de la cadena de suministro.",[16,1400,1401],{},"Las medidas de protección prácticas:",[335,1403,1404,1407,1410,1413],{},[338,1405,1406],{},"Lee el AGENTS.md de cualquier repositorio que clones antes de ejecutar un agente sobre él.",[338,1408,1409],{},"Trata AGENTS.md como un Makefile o un script post-install. Influye en comandos que se ejecutan en tu máquina.",[338,1411,1412],{},"Revisa los cambios en AGENTS.md con el mismo cuidado que los cambios en la configuración de CI.",[338,1414,1415],{},"Ejecuta los agentes en un sandbox cuando sea posible, para que una instrucción que pase desapercibida cause menos daño.",[41,1417,1419],{"id":1418},"más-allá-del-código-agentsmd-para-agentes-de-negocio","Más allá del código: AGENTS.md para agentes de negocio",[16,1421,1422],{},"La idea detrás de AGENTS.md surgió en repositorios de código, pero el principio se aplica a cualquier agente de IA: dale contexto breve y específico al inicio y trabajará mejor. La lección sobre la longitud también aplica. Un agente de negocio con una descripción de rol de dos páginas la sigue peor que uno con diez líneas claras.",[16,1424,1425],{},"Para los agentes de negocio (soporte, ventas, operaciones), la configuración equivalente abarca:",[16,1427,1428],{},[359,1429],{"alt":1430,"src":1431},"Del archivo a la configuración: el mismo principio para agentes de negocio.","/img/blog/agents-md-best-practices-business-agents-es.jpg",[335,1433,1434,1440,1446,1452,1458,1464],{},[338,1435,1436,1439],{},[36,1437,1438],{},"Identidad:"," quién es el agente, su rol y tono.",[338,1441,1442,1445],{},[36,1443,1444],{},"Capacidades:"," qué herramientas y aplicaciones puede usar.",[338,1447,1448,1451],{},[36,1449,1450],{},"Restricciones:"," qué no debe hacer y qué acciones requieren aprobación humana.",[338,1453,1454,1457],{},[36,1455,1456],{},"Nivel de confianza:"," solo borradores, actúa con aprobación o actúa de forma autónoma dentro de límites.",[338,1459,1460,1463],{},[36,1461,1462],{},"Reglas de escalado:"," cuándo transferir a una persona.",[338,1465,1466,1469],{},[36,1467,1468],{},"Formato de salida:"," cómo debe responder.",[16,1471,1472,1473,1477,1478,1482,1483,1487],{},"Para los agentes de programación, AGENTS.md es un archivo que escribes y mantienes. Para los agentes de negocio, esta configuración es más fácil de gestionar en un constructor visual. Así funciona el ",[20,1474,1476],{"href":1475},"/","constructor de agentes de IA"," de BetterClaw: identidad, capacidades, restricciones, niveles de confianza (Internal, Specialist, Lead), reglas de escalado y formato de salida son campos en el constructor, versionados por ti, y no hay ningún archivo que puedas olvidar actualizar. Cada agente puede usar tu propia clave de modelo sin recargo. ",[20,1479,1481],{"href":1480},"/free-plan","Prueba BetterClaw gratis",": el plan Starter cuesta $19/mes, y ",[20,1484,1486],{"href":1485},"/pricing","Pro cuesta $49/mes"," para 5 agentes.",[16,1489,1490],{},[20,1491],{"id":1492},"the-annotated-template-copy-and-adapt",[41,1494,1496],{"id":1495},"la-plantilla-anotada-cópiala-y-adáptala","La plantilla anotada (cópiala y adáptala)",[16,1498,1499],{},"Aquí tienes un AGENTS.md mínimo y eficaz. Elimina las secciones que no apliquen. Un archivo más corto y correcto supera a uno extenso y 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],{},"Son menos de 50 líneas, y cada una es específica. Si supera las 100, vuelve al ciclo de vida de reglas y empieza a borrar.",[41,1785,1787],{"id":1786},"ejemplos-de-agentsmd-tres-archivos-para-tres-tipos-de-proyecto","Ejemplos de AGENTS.md: tres archivos para tres tipos de proyecto",[16,1789,1790],{},"Los archivos reales son más cortos y más raros que las plantillas, porque solo contienen lo que los agentes de ese proyecto se equivocan una y otra vez. Estos tres son ejemplos representativos para mostrar ese rango, no copias del archivo de ningún repositorio en concreto.",[385,1792,1794],{"id":1793},"ejemplo-1-una-aplicación-web-nextjs-12-líneas","Ejemplo 1: una aplicación web Next.js (12 líneas)",[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 qué funciona: la regla de ",[53,1885,1886],{},"'use client'"," es exactamente lo que un agente se equivoca de forma fiable en proyectos App Router, formulada como regla más excepción en una sola línea.",[385,1889,1891],{"id":1890},"ejemplo-2-un-backend-python-con-fastapi-16-líneas","Ejemplo 2: un backend Python con FastAPI (16 líneas)",[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 qué funciona: la regla del dinero. Una línea clara que previene toda una clase de errores caros de detectar.",[385,2036,2038],{"id":2037},"ejemplo-3-un-monorepo-22-líneas","Ejemplo 3: un monorepo (22 líneas)",[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 qué funciona: las reglas de dirección de importación y la última línea, que le dice al agente que existen instrucciones más específicas más adelante en el árbol.",[16,2182,2183],{},"El hilo conductor: cada línea es una regla que un agente rompería sin indicaciones, formulada como directiva en lugar de explicación. Ninguna describe para qué sirve el proyecto y ninguna se acerca siquiera a las 100 líneas.",[41,2185,2187],{"id":2186},"la-versión-corta","La versión corta",[16,2189,2190],{},"El mejor AGENTS.md es el que tu equipo mantiene de verdad. Empieza con 30 líneas. Agrega una regla cuando un agente cometa el mismo error dos veces. Bórrala cuando el agente lo haga bien sin indicaciones. Mantenlo por debajo de 100 líneas, busca contradicciones cada trimestre y aplica lo que sea crítico con un hook en lugar de con una frase.",[16,2192,2193,2194,2197,2198,2201],{},"Y si tus agentes son de negocio y no de programación, toda esa configuración pertenece a un constructor visual, no a un archivo Markdown. ",[20,2195,2196],{"href":1485},"Construye tu agente en BetterClaw",", o ",[20,2199,2200],{"href":1480},"empieza ya"," con tu propia clave de modelo.",[41,2203,2205],{"id":2204},"preguntas-frecuentes","Preguntas frecuentes",[385,2207,2209],{"id":2208},"cuánto-debe-medir-un-archivo-agentsmd","¿Cuánto debe medir un archivo AGENTS.md?",[16,2211,2212,2213,2216],{},"Apunta a menos de 100 líneas y empieza a borrar cuando supere las 150. Anthropic recomienda mantener CLAUDE.md, el archivo equivalente, por debajo de 200 líneas porque \"los archivos más largos consumen más contexto y reducen el seguimiento\", y Codex deja de cargar archivos de instrucciones por defecto cuando el total supera los 32 KiB. Un ",[20,2214,639],{"href":296,"rel":2215},[24]," encontró que los archivos de contexto aumentan los costos de inferencia en más del 20% de media sin mejorar el éxito en general, así que cada línea tiene un precio. En la práctica, la mayoría de los buenos archivos tienen entre 30 y 80 líneas.",[385,2218,2220],{"id":2219},"mi-agentsmd-es-demasiado-largo","¿Mi AGENTS.md es demasiado largo?",[16,2222,2223],{},"Probablemente, si explica por qué elegiste tu stack, contiene un árbol de directorios o una lista de dependencias, incluye procedimientos paso a paso, tiene dos reglas que se contradicen o ya no recuerdas por qué existe la mitad de las reglas. Claude Code también te avisa al inicio si un archivo supera el límite recomendado. Borra todo lo que el agente podría leer directamente del código y mueve los procedimientos a skills.",[385,2225,2227],{"id":2226},"qué-es-un-archivo-agentsmd","¿Qué es un archivo AGENTS.md?",[16,2229,2230],{},"AGENTS.md es un archivo Markdown en la raíz de un repositorio de código que da instrucciones específicas del proyecto a los agentes de programación con IA: comandos de compilación, estilo de código, restricciones de arquitectura, pruebas y límites. Más de 20 herramientas lo leen de forma nativa, incluidas OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Jules, Zed, Windsurf y Devin. Claude Code lo lee cuando el proyecto no tiene un CLAUDE.md. Más de 60.000 proyectos de código abierto lo utilizan, y está bajo la tutela de la Agentic AI Foundation en la Linux Foundation.",[385,2232,2234],{"id":2233},"qué-hago-si-mi-agente-ignora-una-regla","¿Qué hago si mi agente ignora una regla?",[16,2236,2237,2238,2240],{},"Primero comprueba que el archivo se haya cargado realmente (",[53,2239,1109],{}," en Claude Code, o pídele a Codex que resuma sus instrucciones). Luego hazla más concreta y agrega un ejemplo. Después busca una segunda regla que la contradiga. Si la regla nunca puede romperse, no dependas del archivo: usa un hook o una configuración de permisos que se aplique independientemente de lo que decida el agente.",[385,2242,2244],{"id":2243},"lee-claude-code-el-agentsmd","¿Lee Claude Code el AGENTS.md?",[16,2246,2247,2248,578,2250,2252,2253,999,2255,999,2257,2259,2260,2262],{},"Sí, desde la versión 2.1.277 de Claude Code (18 de septiembre de 2026). Por defecto lee AGENTS.md solo cuando no hay ningún CLAUDE.md, ",[53,2249,936],{},[53,2251,939],{}," en tu directorio de trabajo ni por encima. Para que lea ambos, establece ",[36,2254,998],{},[53,2256,1006],{},[53,2258,994],{},", o escribe ",[53,2261,917],{}," en tu CLAUDE.md. No lee AGENTS.override.md ni AGENTS.local.md.",[385,2264,2266],{"id":2265},"cómo-se-relacionan-agentsmd-claudemd-y-cursorrules","¿Cómo se relacionan AGENTS.md, CLAUDE.md y .cursorrules?",[16,2268,2269,2270,2273,2274,380],{},"AGENTS.md tiene la compatibilidad más amplia. CLAUDE.md es el archivo propio de Claude Code y añade importaciones ",[53,2271,2272],{},"@"," y reglas por ruta. .cursorrules añade reglas específicas de Cursor basadas en globs. La mayor parte del contenido es idéntico en los tres. Empieza con AGENTS.md como única fuente de verdad y, si añades un CLAUDE.md, empiézalo con un import ",[53,2275,917],{},[385,2277,2279],{"id":2278},"debo-usar-un-llm-para-generar-mi-agentsmd","¿Debo usar un LLM para generar mi AGENTS.md?",[16,2281,2282],{},"No. En el estudio de la ETH de Zúrich, los archivos de contexto generados por LLM redujeron el éxito en 5 de 8 escenarios y añadieron entre 2,45 y 3,92 pasos extra por tarea. Los LLM escriben consejos genéricos que el agente ya sigue. Escríbelo a mano, o trata un borrador generado por IA como algo que vas a recortar, no a commitear.",[385,2284,2286],{"id":2285},"puedo-usar-el-mismo-agentsmd-para-codex-y-claude-code","¿Puedo usar el mismo AGENTS.md para Codex y Claude Code?",[16,2288,2289,2290,2292],{},"Sí. Codex lo lee de forma nativa; Claude Code lo lee mientras el proyecto no tenga un CLAUDE.md, y de lo contrario necesita un import ",[53,2291,917],{}," en el CLAUDE.md. Ten en cuenta que Claude Code ignora el AGENTS.override.md de Codex. Por eso mantén las reglas compartidas en archivos AGENTS.md normales y ejecuta cada comando del archivo en un terminal limpio antes de confiar en él.",[385,2294,2296],{"id":2295},"commiteo-agentsmd-o-lo-agrego-al-gitignore","¿Commiteo AGENTS.md o lo agrego al .gitignore?",[16,2298,2299],{},"Commitéalo. Es documentación del proyecto y pertenece a la raíz del repositorio para que cada colaborador y cada herramienta lean las mismas instrucciones. Mantén las preferencias personales en el archivo global de tu herramienta y nunca incluyas secrets.",[385,2301,2303],{"id":2302},"se-pueden-aplicar-los-principios-de-agentsmd-a-los-agentes-de-negocio","¿Se pueden aplicar los principios de AGENTS.md a los agentes de negocio?",[16,2305,2306],{},"Sí. La misma idea (contexto breve y específico sobre identidad, capacidades, restricciones y límites) aplica a cualquier agente de IA. Para los agentes de negocio, las secciones son identidad, capacidades, restricciones, niveles de confianza, reglas de escalado y formato de salida, y son más fáciles de gestionar en un constructor visual como BetterClaw que en un archivo 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":861},{"id":1039,"depth":66,"text":1040},{"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","Cuánto debe medir AGENTS.md (menos de 100 líneas), plantilla para copiar, ejemplos, cómo lo cargan Codex y Claude Code y cómo evitar que se acumulen reglas.",false,"/img/blog/agents-md-best-practices-es.jpg",675,1200,null,"es",{"canonical":2370},"https://www.betterclaw.io/blog/agents-md-best-practices","/blog/agents-md-best-practices-es","16 min de lectura",{"title":5,"description":2362},"AGENTS.md: buenas prácticas, plantilla y ejemplos","blog/agents-md-best-practices-es","Cómo escribir un AGENTS.md que los agentes de programación con IA sí sigan: la longitud correcta (y por qué gana el más corto), una plantilla para copiar y pegar, ejemplos reales, cómo lo cargan Codex y Claude Code, y el ciclo de vida de las reglas que evita que el archivo se pudra.",[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","e3BBuTqhUNXtO34Ln7jQD3zyPC_SseuKxKkkZrGhT8M",[2391,2398,2407],{"stem":2392,"title":2393,"description":2394,"date":2361,"image":2395,"category":2360,"redirected":2363,"author":2396,"readingTime":2397},"blog/agents-md-best-practices-pt-br","AGENTS.md Boas Práticas: Qual Deve Ser o Tamanho, Modelo e Exemplos","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.","/img/blog/agents-md-best-practices-pt.jpg",{"name":7,"role":8,"avatar":9,"url":10,"bio":11},"16 min de leitura",{"stem":2399,"title":2400,"description":2401,"date":2402,"image":2403,"category":2404,"redirected":2363,"author":2405,"readingTime":2406},"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":2408,"title":2409,"description":2410,"date":2411,"image":2412,"category":2413,"redirected":2363,"author":2414,"readingTime":2415},"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",1793359752838]