👋 Soy Alex dc y además de escribir sobre vibe coding, agentes y crear software con IA aquí en Agentes IA, explico cómo aprovechar la IA para emprendedores en La Mafia IA ➜ 🧠 La Newsletter más leída de Substack en español.
✦ Somos +19.000 y puedes unirte gratis, aquí.
He probado todas las herramientas de código con IA según iban saliendo. Instalé Claude Code la semana que salió. Pasé por Gemini CLI, por Codex CLI (el primer agente de terminal de OpenAI), por Cursor y por OpenCode. Exprimí Antigravity en su lanzamiento, cuando regalaban cuota casi infinita.
Y luego la lista de las menos populares: Windsurf, Warp (un terminal con agentes dentro), Factory, Cline y tres o cuatro más.
De todo eso, lo único que que ha sobrevivido todo este tiempo (aunque convenientemente recortado) es un archivo md.
Por qué necesitas un AGENTS.md
Los primeros meses fueron de escribir código con ayuda.
Autocompletado con esteroides. Aceptabas la sugerencia o la rechazabas, y el trabajo seguía siendo tuyo.
Después llegaron los agentes de terminal y el trabajo cambió de sitio. Ya no escribes: describes, y luego revisas. Suena a mejora, y lo es, pero mueve el cuello de botella.
Antes el límite era lo rápido que tecleabas. Ahora es lo rápido que detectas que algo está mal.
Hubo una época en la que explorar era gratis. Cada compañía lanzaba su producto con la cuota abierta de par en par (antigravity, windsurf, etc), porque lo que querían era que lo usaras: sesiones eternas, dejabas al agente leerse el repo entero antes de tocar nada y daba igual lo que costase.
Luego llegó la resaca. Restringieron hasta el absurdo, y no se libró ninguno: Antigravity pasó de tener una cuota más generosa que la defensa del Real Madrid 2026 a unos límites que no te duraban ni 15 minutos (con Gemini pro). Claude Code, Copilot, todos por el mismo camino.
Ahí aprendí lo que no había aprendido en los meses de buffet libre.
Cuando los tokens son gratis, la exploración es gratis. El agente lee cuarenta ficheros, se hace su mapa mental y acierta.
Cuando te racionan, cada fichero que lee sin necesidad te sale caro. Tienes que darle el mapa hecho.
Un archivo de instrucciones deja de ser una comodidad. Pasa a definir la velocidad y el coste de tu trabajo.
lo que se repite es lo que merece una instrucción
Durante este proceso vi cambiar nombres, modelos, interfaces, precios y límites. Los fallos recurrentes eran más estables:
el agente empezaba a construir sin mirar lo que ya existía;
inventaba una API en vez de consultar la documentación;
arreglaba el mensaje de error sin reproducir el bug;
declaraba que algo funcionaba sin haber ejecutado el check;
tocaba archivos que no hacían falta;
y, cuando un test molestaba, encontraba “maneras creativas” para que dejara de molestar.
Eso es lo que merece estar escrito. No “escribe código limpio”. No “sé cuidadoso”.
el filtro
Hay librerías llenas de archivos CLAUDE.md o AGENTS.md, totalmente inútiles… o peor aún. PERJUDICIALES.
Lo primero que tiene que cumplir este archivo hoy en día son las siguientes dos condiciones:
Corrige un fallo que los modelos actuales siguen cometiendo.
No lo resuelve ya tu linter, tu formatter o el propio modelo por defecto.
Coge cualquier AGENTS.md de los que circulan y aplícale esto. Vas a borrar la mitad. Como poco.
Fuera “usa siempre llaves en los if“ (eso es Prettier, no una IA). Fuera “deja líneas en blanco entre bloques”, “reduce la indentación”, “evita números mágicos”. Lleva año y pico siendo comportamiento por defecto: ocupa contexto y no cambia nada.
Las que sí importa
⮕ Escribe el test de regresión que falla antes del fix y pasa después.
⮕ Nunca debilites, borres o reescribas un test solo para que pase. La mejor del archivo. Sin ella, la anterior se cumple haciendo trampa.
⮕ Busca antes de construir. Prefiero los patrones y helpers que ya existen.
⮕ Reporta cualquier check que no pudiste ejecutar. El agente no miente cuando dice que funciona: omite que no lanzó los tests.
⮕ Para APIs poco conocidas o sensibles a versión, consulta la documentación real.
Mi AGENTS.md (o CLAUDE.md)
La IA ha reducido mucho el coste de producir código. Eso aumenta el valor de decidir qué código merece existir.
También aumenta el coste de dejar pasar código mediocre: cuando generar es barato, la basura se acumula más deprisa.
Por eso sigo leyendo el código. Sigo pensando en arquitectura, límites de visibilidad, dependencias, datos y producto. El agente puede escribir el cambio; no puede asumir la responsabilidad de que el cambio sea el correcto.
Mi actividad pública también refleja ese desplazamiento. Ya no solo uso agentes para construir productos. Construyo infraestructura alrededor de ellos: skills, memoria, contexto, procedencia y formas de verificar que una instrucción no se convierta en otra fuente de deriva.
La primera vez que lo instales
Los archivos que se comparten son 100% estilo portable. Cero datos del proyecto. Ni un comando de build, ni las capas reales de la arquitectura, ni una trampa concreta del repo. Y entonces el agente adivina cómo verificar su trabajo. Cuando adivina mal, te dice que está listo igualmente.
Mi AGENTS.md consta de 2 partes:
Arriba ⮕ hechos de este repo. Comandos reales, capas reales, ejemplos canónicos (apuntar al fichero donde algo está bien hecho, en vez de describir la convención en prosa), recetas para lo que se repite y trampas del proyecto.
Abajo ⮕ comportamiento portable. Idéntico en todos tus repos. Si llevas varios, muévelo a tu configuración global.
Setup
La mitad de arriba hay que rellenarla, y en estos tiempos ya no es necesario que seas tú quien mejor conoce los comandos que usa tu CI.
Por eso el archivo lleva un comentario SETUP con instrucciones para que la propia IA lo rellene inspeccionando el repositorio: que saque los comandos de los scripts y del CI (no de lo que parezca razonable), que deduzca la arquitectura de las dependencias reales y no de los nombres de las carpetas, que no invente advertencias, que borre las secciones donde no encontró nada.
Y en el último paso, que borre el propio comentario SETUP.
Funciona una vez y desaparece. Después deja de consumir contexto en cada sesión.
💡 Esto es más simple de lo que parece: pegas el archivo en la raíz del repo y le dices al agente “sigue el bloque SETUP”.
El prompt AGENTS.md
Pégalo en la raíz de tu repo y dile al agente que ejecute el bloque SETUP. Dos minutos.
<!-- SETUP — run once when adopting this file in a repository. Inspect the repository before filling the section above the divider. 1. Replace every <...> with facts verified from the repo. 2. Prefer commands actually used in package scripts, CI, Makefiles or project docs. 3. Infer architecture from real dependencies and representative code, not folder names alone. 4. Point Canonical examples to existing, representative implementations. 5. Add Recipes only for established multi-step workflows. 6. Add Gotchas only when supported by code, docs, CI or an observed failure. Never invent warnings. 7. Delete any section for which you found nothing useful. Do not leave placeholders or empty headings. 8. Do not modify the portable rules below the divider while performing setup. 9. When finished, delete this SETUP comment. Keep this file short. It is a map, not project documentation. -->
## Commands
Build: `<cmd>`
Test: `<cmd>`
Single test: `<cmd>`
Lint/format: `<cmd>`
## Architecture
- `<Controllers call services, never repositories or database clients directly.>`
- `<Services access persistence through repositories.>`
## Canonical examples
- `<Auth: src/...>`
- `<API endpoint: src/...>`
- `<Database access: src/...>`
## Recipes
<!-- Only for established recurring work where steps are easy to miss. -->
### `<Add an API endpoint>`
1. `<>`
2. `<>`
## Gotchas
<!-- Add from real constraints or failures, not anticipation. Delete stale entries. -->
- `<Tests need the db container: docker compose up -d db>`
- `<src/generated/ is generated. Don't edit it; run: cmd>`
---
## Verification
- Run the relevant checks before saying the work is done.
- Report any check you could not run. Never claim unverified work is verified.
- For unfamiliar or version-sensitive APIs, check the actual documentation. Don't guess from memory.
## Scope
- Do only what was asked. No unrequested refactors or "while I'm here" cleanups.
- Keep changes scoped to the task. Minimize the diff.
- Search before building. Prefer existing patterns, helpers and abstractions over introducing new ones.
- If behavior is unclear, inspect the code, tests and docs for evidence. Ask only when ambiguity remains and materially affects behavior.
- Don't add a dependency when the problem can reasonably be solved with what is already available.
- Never widen visibility for convenience.
## Bugs
- For bug fixes, write a regression test that fails before the fix and passes after it.
- Never weaken, delete or rewrite a test just to make it pass. Change tests only when the requested behavior changes.
- Never swallow errors: no empty catches, silent fallbacks or default values that hide failures.
## Prose
- Use the fewest words needed. No superlatives, praise or conversational filler.
- Comment why, not what. If code needs a "what" comment, make the code clearer instead.
- Commits: imperative subject, <=50 chars, no period. Use the body only when the reason is not obvious from the diff.
## When rules conflict
Correctness beats convenience.
Smallest diff beats style.
Evidence beats assumptions.Aviso
Esto no es magia y conviene decirlo.
El modelo va a seguir alucinando. Un archivo de reglas no le da conocimiento que no tiene: le da límites. Sigues teniendo que verificar, y por eso media docena de las reglas que sobreviven van justamente de verificar.
En sesiones largas el archivo se diluye. Cuando el contexto se llena, las instrucciones del principio pierden peso frente a los últimos veinte ficheros que ha leído. La solución no está en el archivo: está en abrir sesión nueva por feature en vez de arrastrar una conversación de tres horas.
Y hay una trampa de la que no te libra nadie: un archivo de reglas crece solo. Cada vez que algo falla te dan ganas de añadir una línea. Encogerlo hay que hacerlo a mano.
Añade una regla después de un fallo real, nunca en previsión de uno que imaginas. Y borra las que llevan meses sin dispararse.
Mantenimiento
No añado reglas porque imagino que algún día podrían ser útiles. Añado una después de un fallo real.
Tampoco considero que una regla sea permanente por haber entrado una vez. Si lleva meses sin corregir nada, la elimino. Un archivo de instrucciones crece solo; encogerlo requiere una decisión consciente.
El objetivo final no es conseguir que el agente siga más órdenes. Es reducir el número de veces que tengo que repetir la misma corrección y hacer más difícil que una salida plausible se confunda con una salida verificada.
El archivo no sustituye al criterio. Lo conserva.
OpenAI, Harness engineering. De dónde sale lo del mapa y las ~100 líneas.
Anthropic, Best practices for Claude Code. El test por línea y la tabla de qué incluir y qué excluir.
Mi GitHub: alexdcd.
Para más sobre IA:
Nuestra newsletter principal → LA MAFIA IA para Emprendedores
Si te interesa estar más al día: En mis perfiles en redes comento las noticias más importantes en tiempo real, me puedes encontrar en:
⮕ 💼 Linkedin | 𝕏 x.com | ＠Thread | 📶 Telegram
Este post fue escrito por un humano. Las herramientas IA me ayudaron a investigar y organizar. El criterio, los ejemplos y las opiniones son 100% míos.
SI HAS LLEGADO HASTA AQUÍ IGUAL TAMBIÉN TE INTERESA:
Hermes vs OpenClaw
👋 Soy Alex dc y además de escribir sobre vibe coding, agentes y crear software con IA aquí en Agentes IA 🤖🧑💻 by Mafia IA, explico cómo aprovechar la IA a emprendedores en La Mafia IA ➜ 🧠 La Newsletter más leída de Substack en español.