Una idea está empezando a aparecer con distintas formas en el trabajo con agentes: tal vez no necesitas construir una aplicación; tal vez necesitas describir bien un sistema de trabajo.
Guillermo Rauch lo resumió con una frase provocadora: “The software powering this is English in AGENTS.md.” Su ejemplo era una carpeta de investigación, notas en Markdown y un agente capaz de leerlas, buscarlas y correlacionarlas. Sin una aplicación de notas propia, sin un grafo dibujado a mano y sin otra base de datos que mantener.
La intuición es buena. También es fácil llevarla demasiado lejos.
Un archivo AGENTS.md no reemplaza mágicamente al software. Lo que sí puede reemplazar es una cantidad enorme de software accidental: formularios que sólo existen para imponer un formato, paneles que apenas envuelven archivos, APIs que no hacen más que mover texto y bases de datos creadas para información que nunca necesitó consultas relacionales.
El cambio importante no es que el inglés haya sustituido a TypeScript. Es que ahora el lenguaje natural puede funcionar como una política ejecutable sobre herramientas y archivos que ya existen.
La tesis, sin humo
En el patrón más simple:
| Pieza tradicional | Sistema basado en agentes |
|---|---|
| Base de datos | Archivos y carpetas |
| Schema | Convenciones escritas en AGENTS.md |
| API | Herramientas de lectura, búsqueda y escritura |
| Interfaz | Conversación con el agente |
| Lógica de aplicación | Instrucciones en lenguaje natural |
| Sincronización | Git, almacenamiento compartido o sync de archivos |
| Reporte | Markdown, HTML o cualquier artefacto generado bajo demanda |
Esto funciona porque un agente de coding ya sabe usar el filesystem. Puede ejecutar rg, abrir archivos, comparar versiones, actualizar índices y producir una página estática. No necesita que cada una de esas acciones tenga un botón.
El formato AGENTS.md formaliza una parte de esta relación. Es, en palabras de su documentación, un README para agentes: un lugar predecible donde explicar comandos, convenciones, pruebas y límites. Además puede anidarse; las instrucciones más cercanas al archivo sobre el que se trabaja tienen prioridad.
Ese detalle importa. Un AGENTS.md no es únicamente un prompt largo. Es una capa de reglas situada dentro de la misma estructura que gobierna.
Un programa hecho de cuatro cosas
Decir que “el software es inglés” es una buena frase y una descripción incompleta. En realidad, el sistema tiene cuatro piezas:
- Instrucciones: qué debe hacer el agente y bajo qué reglas.
- Estado: los archivos que puede leer y modificar.
- Capacidades: terminal, buscador, APIs, navegador, deploy.
- Verificación: pruebas, schemas, revisiones y permisos.
El inglés describe el comportamiento, pero no ejecuta nada por sí solo. El modelo interpreta las instrucciones; las herramientas producen efectos; el filesystem conserva el resultado; las verificaciones deciden si ese resultado es aceptable.
Una analogía más honesta sería:
AGENTS.md → política
LLM → intérprete
tools → instrucciones de máquina
filesystem → memoria y estado
tests/evals → contrato observable
git → historial y rollbackEsta distinción evita el error más común del entusiasmo por Software 3.0: confundir una descripción plausible con un sistema confiable.
El ejemplo perfecto: una carpeta de investigación
Imagina que durante meses investigas arquitectura, herramientas de agentes y diseño de producto. El reflejo tradicional sería elegir una app de notas, diseñar tags, instalar plugins y dedicar una tarde a decidir cómo se ve el grafo.
El patrón basado en archivos puede ser mucho más aburrido:
research/
├── AGENTS.md
├── index.md
├── architecture/
│ ├── monoliths.md
│ └── event-driven.md
├── agents/
│ ├── context-engineering.md
│ └── evals.md
├── decisions/
│ └── 2026-07-27-use-plain-markdown.md
└── sessions/
└── 2026-07-27-notes.mdEl AGENTS.md puede indicar:
- qué frontmatter usa cada nota;
- cuándo crear una nueva y cuándo actualizar una existente;
- cómo registrar fuentes y distinguir hechos de inferencias;
- qué archivos consultar antes de responder;
- cómo mantener
index.md; - cuándo generar un reporte compartible;
- qué datos nunca deben salir de la carpeta.
Después preguntas: “¿Qué patrones se repiten entre nuestras notas sobre specs y evals?” El agente busca, lee, contrasta y responde. Si necesitas compartir el resultado, puede generar HTML estático y dejarlo listo para publicar.
No hay una UI especial porque, para ese usuario técnico, la conversación ya es la UI.
Por qué esta idea apareció ahora
Los archivos de configuración escritos en prosa no son nuevos. Los equipos llevan décadas guardando runbooks, convenciones y checklists en repositorios. Lo nuevo es tener un intérprete razonablemente competente capaz de aplicar esas instrucciones en contextos que no enumeramos de antemano.
Andrej Karpathy llamó Software 2.0 al software cuyo comportamiento emerge de datos y optimización en lugar de escribirse línea por línea. Su idea posterior de Software 3.0 empuja el cambio una capa más: programamos parte del comportamiento mediante lenguaje natural y un modelo funciona como runtime.
Simon Willison llevó la idea al extremo literal con un prompt en la línea shebang:
#!/usr/bin/env -S llm -f
Generate an SVG of a pelican riding a bicycleEl archivo es ejecutable. Cambiar la oración cambia el resultado. El texto se comporta como código, aunque su salida no sea determinista en el sentido clásico.
Vercel llegó a una conclusión parecida al diseñar eve. Un agente vive en un directorio: instructions.md define su trabajo, otros archivos declaran herramientas, skills, conexiones, canales y horarios.
Pero eve también muestra el límite de la frase. Para llevar un agente a producción hacen falta ejecución durable, sandboxes, aprobaciones humanas, observabilidad y evals. El inglés define la intención; la infraestructura sigue cargando las consecuencias.
AGENTS.md no es documentación pasiva
Un README suele explicar un sistema después de que alguien lo construyó. Un AGENTS.md bien usado participa en la construcción.
Puede ordenar:
- ejecuta estas pruebas antes de declarar éxito;
- no modifiques archivos fuera de este directorio;
- usa fuentes primarias para cifras;
- conserva cambios del usuario que no pertenecen a tu tarea;
- solicita aprobación antes de publicar;
- registra decisiones irreversibles;
- si dos instrucciones chocan, aplica esta precedencia.
Esas frases alteran el comportamiento del agente. Por eso conviene tratarlas con la misma seriedad que una configuración de CI: versionarlas, revisarlas en pull request y probar que producen el resultado deseado.
La cercanía con el código también ayuda. En un monorepo puede existir una regla general en la raíz y reglas específicas dentro de payments/, mobile/ o docs/. No hay que cargar un manual corporativo entero para cambiar un componente. El contexto puede revelarse conforme el agente se acerca al trabajo.
Ese principio —contexto pequeño, localizado y verificable— también aparece detrás de herramientas como Spec-Kit. La diferencia es de intensidad: Spec-Kit estructura el ciclo completo de una feature; AGENTS.md define las reglas persistentes bajo las que cualquier tarea debe ejecutarse.
Cómo escribir uno que no se convierta en un “god prompt”
Un AGENTS.md de cinco mil líneas puede ser tan difícil de mantener como una clase de cinco mil líneas. El lenguaje natural no elimina la complejidad: puede esconderla mejor.
Una versión útil comienza pequeña y responde siete preguntas.
1. ¿Qué es este espacio?
Dos o tres oraciones. Propósito, audiencia y resultado esperado.
2. ¿Dónde está la verdad?
Qué archivos son canónicos, cuáles son derivados y cuáles nunca deben editarse directamente.
3. ¿Cómo se escribe?
Formato, naming, frontmatter y criterio para crear, actualizar, mover o eliminar.
4. ¿Cómo se busca?
Qué índices revisar primero, qué comandos usar y cuándo ampliar la búsqueda.
5. ¿Qué puede cambiar el agente?
Permisos, zonas prohibidas y acciones que requieren confirmación.
6. ¿Cómo se comprueba el resultado?
Tests, lint, schemas, revisión de enlaces, fuentes mínimas o checklist editorial.
7. ¿Cómo termina una tarea?
Qué debe reportar: archivos modificados, evidencia, decisiones y pendientes reales.
Una base mínima podría verse así:
# Sistema de investigación
## Propósito
Conservar notas verificables y convertirlas en decisiones o
reportes sin depender de una aplicación propietaria.
## Fuente de verdad
- `notes/` contiene conocimiento revisado.
- `inbox/` contiene material sin verificar.
- Nunca presentes `inbox/` como hecho.
## Escritura
- Una tesis principal por archivo.
- Incluye fecha, fuentes y estado: borrador o revisado.
- Actualiza una nota existente antes de crear una duplicada.
## Operación
- Busca primero con `rg`.
- Distingue cita, hecho, inferencia y opinión.
- No publiques ni borres sin aprobación explícita.
## Verificación
- Todo dato cuantitativo necesita fuente o método.
- Revisa enlaces antes de cerrar la tarea.
- Resume qué cambió y qué sigue incierto.No intenta prever cada pregunta futura. Define invariantes. Las instrucciones que sólo aplican a una tarea deben vivir en esa tarea, no inflar para siempre el archivo global.
Cuándo funciona especialmente bien
Este patrón brilla cuando el problema consiste principalmente en leer, transformar y relacionar texto:
- investigación personal o de equipo;
- bitácoras técnicas y ADRs;
- documentación viva;
- specs y planes;
- catálogos pequeños o medianos;
- generación de reportes;
- operaciones internas con revisión humana;
- repositorios donde los archivos ya son la fuente de verdad.
También funciona cuando el costo de construir una interfaz supera el beneficio. Para una persona que ya vive en terminal y Git, conversar con un agente puede ser más rápido que navegar seis pantallas.
Es una aplicación práctica de “menos código, mejor criterio”: no construyas una plataforma sólo para sentir que el problema parece importante.
Cuándo no conviene
El filesystem no se convierte en PostgreSQL porque un modelo sepa leer Markdown.
No es una buena sustitución cuando necesitas:
- colaboración simultánea con resolución formal de conflictos;
- transacciones, invariantes y consistencia fuerte;
- consultas agregadas sobre millones de registros;
- permisos detallados por fila o campo;
- una interfaz accesible para usuarios no técnicos;
- latencia y costo predecibles por operación;
- auditoría regulatoria donde cada cambio exige controles específicos.
Tampoco conviene delegar al modelo decisiones destructivas sólo porque están descritas en inglés. Si una acción puede mover dinero, exponer información, eliminar datos o afectar producción, necesita permisos estrechos y aprobación.
La regla práctica es simple: usa archivos cuando el estado es documental; usa una base de datos cuando el estado es transaccional. A veces el sistema correcto usa ambos.
Los cuatro riesgos que no desaparecen
El modelo cambia
Una actualización puede interpretar distinto la misma instrucción. Versionar el prompt ayuda, pero no fija el runtime. Por eso los comportamientos importantes necesitan evals o comprobaciones externas.
La prosa admite ambigüedad
“Hazlo bien” no es una especificación. “No publiques sin aprobación explícita” sí se puede observar. Las instrucciones útiles describen decisiones, límites y evidencia.
Cada lectura cuesta
Un archivo enorme consume contexto y distrae. La solución no es otro mega-prompt, sino jerarquía: reglas generales pequeñas y conocimiento especializado que se carga cuando corresponde.
La autoridad puede confundirse
Un agente puede sintetizar dos notas y producir una conclusión convincente que ninguna fuente sostiene. Guardar fuentes, estados de revisión y desacuerdos sigue siendo obligatorio.
La capacidad de correlacionar no reemplaza la procedencia.
Lo que cambia para quien construye software
Si este patrón se consolida, una parte del oficio se mueve de implementar pantallas a diseñar entornos de decisión.
Hay que decidir:
- qué contexto debe ser persistente;
- qué información debe revelarse sólo cuando hace falta;
- qué capacidades recibe cada agente;
- qué acciones necesitan aprobación;
- cómo se observa una ejecución;
- qué eval demuestra que una regla sigue funcionando;
- qué debe continuar siendo código determinista.
Esto no reduce la necesidad de ingeniería. Cambia su centro de gravedad.
En nuestra comparativa de frameworks de AI coding aparecía el mismo patrón: el valor no está en acumular agentes, comandos o capas. Está en dar al sistema el contexto mínimo correcto y límites que sobrevivan a una sesión.
Nuestra conclusión
“The software is English” importa porque obliga a revisar un reflejo caro: construir una app antes de comprobar que necesitamos una.
Para muchos sistemas personales e internos, una carpeta bien diseñada, un AGENTS.md, Git y un agente competente pueden reemplazar meses de software incidental. El resultado es portable, legible y fácil de abandonar sin perder los datos.
Pero el inglés no elimina el runtime, la seguridad ni las pruebas. Sólo mueve parte de la lógica a un lugar que más personas pueden leer y modificar.
La oportunidad no es dejar de programar. Es reservar el código para aquello que de verdad exige código: consistencia, rendimiento, seguridad, interfaces compartidas e invariantes. El resto puede empezar como una política clara sobre archivos simples.
Y ésa es una buena disciplina incluso si mañana desaparecen los agentes.
Convertimos este enfoque en una skill funcional: AGENTS.md como programa. Se puede copiar como SKILL.md, abrir como texto plano o entregar directamente a un agente.
Si su organización ya tiene conocimiento repartido entre documentos, chats y procesos manuales, podemos ayudarle a decidir qué parte necesita software para agentes y qué parte sólo necesita mejores reglas.
Referencias
- AGENTS.md — formato abierto para orientar agentes
- Vercel — Introducing eve
- Simon Willison — Using LLM in the shebang line of a script
- Andrej Karpathy — Software 2.0
- Andy Matuschak — Evergreen notes
- Maggie Appleton — Digital garden
TL;DR — AGENTS.md puede funcionar como programa operativo: el agente interpreta, las herramientas ejecutan, los archivos conservan el estado y las pruebas ponen límites. Sirve para reemplazar software accidental, no bases de datos, permisos ni ingeniería de producción.