Usar IA para programar ya no es un truco. Es otra forma de trabajar. Lo que cambia el resultado no es solo pedirle cosas a un chat: es armar un sistema alrededor (reglas, memoria, skills, arquitectura y criterios de aceptación). Sin eso, terminas en vibe coding: código que parece funcionar hasta que alguien lo revisa de verdad.
En este post cuento cómo trabajo con Cursor, Antigravity y chats como Claude o Grok, y por qué archivos como AGENTS.md y MEMORY.md dejaron de ser un gusto personal y se volvieron una convención compartida en el ecosistema de agentes de código.
El problema no es el modelo: es el contexto
Un agente (o un chat con acceso a tu repo) sin contexto es un junior brillante el primer día: inventa carpetas, ignora tests, arregla lo que no pediste y declara éxito. Con un harness (guías, sensores y límites) se comporta más como alguien a quien le dejaste onboarding escrito.
Eso es lo que buscan formatos como AGENTS.md: un lugar predecible, en Markdown plano, donde vive lo que la IA necesita y el README humano no debería cargar.
AGENTS.md: el README para agentes
AGENTS.md es un formato abierto: un README pensado para agentes. Nació del ecosistema de agentes de código (Codex, Cursor, Amp, Jules, Factory y otros) y hoy lo mantiene la Agentic AI Foundation, bajo la Linux Foundation. Miles de proyectos open source ya lo usan.
La idea es simple:
README.md→ humanos (qué es el proyecto, cómo arrancar).AGENTS.md→ agentes e IDEs agenticos (comandos de build/test, estilo, seguridad, qué no tocar, cómo abrir un PR).
No exige campos obligatorios. Es Markdown. Lo que importa es que cualquier herramienta sepa dónde mirar y que las instrucciones no dependan de un solo vendor.
En la práctica, un buen AGENTS.md responde:
- Cómo instalar, correr y probar.
- Convenciones de código y de commits.
- Límites duros (“no deploy sin permiso”, “no inventar diseño”, “no meter React en este módulo”).
- Dónde está la arquitectura y qué decisiones ya están tomadas.
MEMORY.md: continuidad entre sesiones
AGENTS.md es la constitución. MEMORY.md es el diario de sesión: qué quedó a medias, qué se decidió ayer, qué bug ya se diagnosticó. Yo lo trato como contexto que se lee al empezar y se actualiza al cerrar, para no pagar otra vez el onboarding en cada chat o agente.
Si AGENTS.md evita que la IA rompa reglas, MEMORY.md evita que olvide el estado del trabajo.
Skills: procedimientos reutilizables
Además de reglas globales, uso skills: paquetes de instrucciones para tareas concretas (crear un post, armar un PR, revisar seguridad, montar una regla). No son magia: son playbooks versionados. El agente o el chat no improvisan el ritual cada vez; siguen un procedimiento que ya validé.
Eso escala mejor que pegar el mismo prompt enorme en cada conversación.
Otras convenciones del ecosistema (aunque yo casi no las use)
AGENTS.md y MEMORY.md no son lo único que circula. En repos agenticos también aparecen formatos que otros equipos adoptan con más fuerza que yo:
BRIEF.md/*.brief.md/docs/briefs/: briefing de una feature o campaña (objetivo, alcance, no-goals y criterios de aceptación; a veces con frontmatter YAML). Hay herramientas que emiten ese brief haciaAGENTS.md, Cursor o Claude. Yo casi no los uso en el día a día; otros sí los tratan como la puerta de entrada al SDD.CLAUDE.md,GEMINI.md, reglas de Cursor (.cursor/rules): adaptadores por herramienta. Misma idea de instrucciones del proyecto, distinto nombre o carpeta. Lo sano es no duplicar: un núcleo portable (AGENTS.md) y, si hace falta, un archivo delgado que lo importe.spec.md/ PRD por pieza de trabajo: una spec viva por ticket o epic, no solo reglas globales del repo.- ADRs y
PLAN.md/ checklists de sesión: decisiones duraderas frente a un plan corto de la sesión actual.
No hace falta adoptar todas. Lo útil es saber que existen: el mercado está convergiendo en documentar el contrato con el agente, aunque el nombre del archivo cambie según el equipo o el vendor.
Las herramientas que uso (y las que solo menciono)
Mi stack diario es práctico, no maximalista. Para editar y construir código uso IDEs agenticos: entornos donde el agente no es un plugin de lado, sino parte del flujo (editor, terminal, diffs, reglas del repo). Ahí entran Cursor (ecosistema de X) y Antigravity (Google). Con ambos armé este portafolio. No los separo en “este hizo más que el otro”: son el mismo tipo de herramienta, de vendors distintos, y el valor está en el sistema alrededor (AGENTS.md, MEMORY.md, ADRs), no en el logo.
Además uso chats como Claude o Grok para pensar arquitectura, redactar specs, revisar copy o desbloquear decisiones. A veces sin abrir el editor; a veces pegando contexto o diffs a mano.
En el mismo mapa aparecen también Claude Code, OpenAI Codex, OpenCode y similares. Yo no los uso como flujo principal, pero sí los menciono: suelen ser agentes en terminal o CLIs que también se apoyan (o pueden puentearse) a convenciones como AGENTS.md o CLAUDE.md. Por eso un archivo portable en el repo importa: puedes cambiar de IDE o de chat sin reescribir el onboarding desde cero.
Primero arquitectura, después el agente
Antes de pedirle features a un agente (o a un chat), defino aunque sea en breve el tipo de arquitectura del proyecto. No uso la misma plantilla para todo: según el dominio elijo Clean Architecture, MVC, MVVM, hexagonal u otro estilo que encaje. Eso va junto con:
- límites del sistema y módulos,
- contratos (API, tipos, eventos),
- criterios de “listo” (tests, casos borde, no-goals),
- dónde viven las decisiones (ADRs / docs).
Sin arquitectura, la IA rellena el vacío con supuestos (y a menudo mezcla capas). Con un estilo claro y escrito, implementa dentro de un marco.
Spec-Driven Development (SDD): programar con contrato
Spec-Driven Development no nació como moda de marketing. Surge cuando la gente se dio cuenta de que pedir features a un agente “a vibes” escala mal: el individuo produce más diffs, pero el equipo pierde trazabilidad, capacidad de revisión y estabilidad. La respuesta fue volver a poner la especificación en el centro: no un documento de 40 páginas, sino un contrato entre humano e IA (y entre humanos del equipo).
Hay trabajo reciente que lo formaliza como disciplina para ingeniería de software agentica (artículo conceptual): la spec recupera accountability, verificabilidad y transferibilidad, justo lo que el vibe coding diluye. En la práctica, el contrato suele incluir:
- qué se construye y qué no,
- aceptación verificable,
- descomposición en tareas pequeñas,
- evidencia de que se cumplió (tests, demos, checks).
El vibe coding es lo contrario: “hazme algo que se vea bien” y rezar. SDD no elimina la IA; la gobierna.
En mi flujo eso se ve así: primero escribo (a veces con Claude o Grok) el qué y el cómo se prueba; después lo ejecuto en un IDE agentico (Cursor o Antigravity) dentro de esas reglas. La spec sola no basta: necesita un entorno que la haga cumplir. Ahí entra el harness.
Harness engineering: el sistema alrededor
Si SDD dice qué debe pasar, el harness engineering arma el arnés que hace más probable acertar y corrige errores antes de la revisión humana. Guías de antemano, sensores después, límites siempre.
En mi práctica el harness incluye:
- Guías (feedforward):
AGENTS.md, skills, arquitectura, specs. - Sensores (feedback): tests, linters, typecheck, CI.
- Límites: qué se puede tocar y qué requiere mi OK.
- Memoria de trabajo:
MEMORY.md, notas de sesión, ADRs.
No son caminos distintos: la spec es control antes; el harness es control durante y después. Juntos cierran el ciclo que el vibe coding deja abierto.
Cómo acelera mi trabajo (de verdad)
No uso IA para “no pensar”. La uso para:
- Bajar el costo de exploración (buscar, proponer, bocetar; a menudo en chat).
- Ejecutar trabajo mecánico dentro de reglas ya escritas, en los IDEs agenticos.
- Mantener ritmo sin perder trazabilidad (docs + tests).
La regla de oro sigue vigente: pedir evidencia (archivo, línea, comando). Un “listo al 100%” sin prueba no cuenta.
Recursos
- Sitio oficial: agents.md
- Codex y
AGENTS.md(referencia del ecosistema): Custom instructions with AGENTS.md - Quién lo mantiene: Agentic AI Foundation / Linux Foundation (About en el sitio)
- Harness engineering: Martin Fowler, Harness engineering for coding agent users
- SDD / ASE (visión): Spec-Driven Development for Agentic Software Engineering
- Cursor: Cursor Docs
- Antigravity (Google): antigravity.google
Lo que me llevo
Trabajar bien con agentes y chats no es vibe coding con mejor marketing. Es especificar, acotar, instrumentar y revisar. AGENTS.md y MEMORY.md son el onboarding portable; las skills, los procedimientos; la arquitectura y el SDD, el contrato; el harness, lo que convierte intención en calidad repetible.
Yo acelero con Cursor, Antigravity y conversaciones en Claude o Grok. Lo que decide si voy en la dirección correcta no es el logo de la herramienta: es el sistema.