Si estás usando IA para programar, tu repo probablemente no está preparado.

Durante años, un repositorio era código + README.

Hoy eso ya no es suficiente.

Porque ya no estás trabajando solo.

Estás trabajando con agentes.

Durante años, un repositorio necesitaba poco más que código, un README.md, algo de documentación y, con suerte, una guía de contribución decente.

Eso funcionaba porque el principal lector del repo era una persona.

Pero ahora cada vez más trabajo pasa por agentes de IA: asistentes que leen código, modifican archivos, ejecutan tests, revisan documentación, generan interfaces, escriben issues, preparan PRs o automatizan partes enteras del desarrollo.

Y ahí aparece un problema bastante evidente:

los agentes no necesitan solo acceso al código. Necesitan contexto.

Necesitan saber qué hace el proyecto, cómo se trabaja dentro de él, qué decisiones ya se tomaron, qué restricciones existen, qué APIs están disponibles, qué estilo debe respetarse y para quién se está construyendo.

El resultado es que los repos empiezan a llenarse de nuevos archivos y estándares que funcionan como una especie de “capa de contexto” para humanos y agentes.

No todos son nuevos. Algunos llevan años con nosotros. Pero con la llegada de los agentes se han vuelto mucho más importantes.

Vamos a ordenar el mapa.

📄 Documentación: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes

El README.md sigue siendo el archivo más importante de casi cualquier repositorio.

Normalmente responde a preguntas básicas:

Para una persona, el README.md es la puerta de entrada.

Para una IA, también.

Pero tiene un límite claro: el README explica el proyecto, no necesariamente cómo trabajar dentro de él.

Puede decirte qué hace una librería, pero no siempre te dice:

Por eso están apareciendo archivos más específicos.

📄 Documentación: https://agents.md/

AGENTS.md es uno de los archivos más interesantes de esta nueva etapa.

La idea es simple: si un agente va a trabajar en un repo, necesita instrucciones estables.

No quieres repetir en cada prompt:

Eso debería vivir en el proyecto.

Un AGENTS.md puede definir:

La diferencia con README.md es clara:

Esto se vuelve especialmente útil cuando varios agentes o herramientas distintas van a interactuar con el mismo código.

Sin ese archivo, cada agente tiene que inferir demasiado.

Y cuando una IA infiere demasiado, empieza la diversión.

📄 Documentación: https://audiencemd.ai/

Hay una pieza que muchas veces falta.

Un repo puede explicar qué hace.
Puede explicar cómo se trabaja.
Puede explicar cómo se despliega.
Puede explicar cómo se ve.

Pero no siempre explica para quién existe.

Ahí entra la idea de AUDIENCE.md.

La premisa es sencilla:

No basta con decir:

La pregunta real es:

Un AUDIENCE.md puede definir:

Esto no solo sirve para proyectos de código.

También puede servir para:

La diferencia con una “buyer persona” tradicional es importante.

No se trata de inventar a “María, 34 años, vive en Madrid y toma café”.

Eso casi nunca ayuda.

Se trata de capturar contexto útil para tomar mejores decisiones.

Algo como:

Eso sí cambia cómo escribes, qué priorizas y qué evitas.

Si README.md explica qué es, AGENTS.md cómo trabajar, y DESIGN.md cómo debe sentirse, AUDIENCE.md explica para quién existe.

📄 Claude: https://docs.anthropic.com
📄 Gemini: https://ai.google.dev
📄 Cursor: https://docs.cursor.sh

Además de AGENTS.md, muchas herramientas han empezado a usar sus propios archivos de contexto.

Por ejemplo:

Esto tiene sentido: cada herramienta tiene sus matices, sus capacidades y su forma de leer contexto.

Pero también genera un problema:

el contexto empieza a fragmentarse.

Un equipo puede acabar con:

Y entonces surge la pregunta:

No es necesariamente malo tener archivos específicos por herramienta, pero conviene separar bien dos cosas:

Si no, cada asistente acaba viendo una versión ligeramente distinta del proyecto.

Y eso, tarde o temprano, se nota.

📄 Referencia: https://llmstxt.org

llms.txt es otro estándar que ha ganado visibilidad.

La idea es crear un archivo en una web o proyecto que ayude a los modelos de lenguaje a entender qué documentación es relevante.

Suele servir para:

Es especialmente útil para documentación pública, SDKs, APIs, productos SaaS o proyectos con mucho contenido repartido.

Podríamos decir que:

Y eso ya es mucho.

Porque muchos errores de IA no vienen de falta de capacidad, sino de haber leído el contexto equivocado.

📄 Documentación: https://modelcontextprotocol.io

MCP, o Model Context Protocol, no es un archivo tipo .md, pero sí forma parte de este mapa.

Mientras que archivos como README.md, AGENTS.md o llms.txt describen contexto, MCP permite que un agente se conecte a herramientas y fuentes de datos externas.

Por ejemplo:

La diferencia es importante:

En proyectos cada vez más automatizados, esta distinción importa.

Un agente sin instrucciones puede hacer tonterías.
Un agente con herramientas pero sin contexto puede hacer tonterías más rápido.

MCP es potente, pero necesita convivir con buenas reglas, permisos y documentación.

📄 Documentación oficial: https://www.openapis.org

OpenAPI lleva años siendo clave para documentar APIs.

Pero con agentes de IA se vuelve todavía más interesante.

Una especificación OpenAPI permite entender:

Para un developer, esto ya era útil.

Para un agente, es casi una interfaz de trabajo.

Si un modelo tiene una buena descripción OpenAPI, puede razonar mejor sobre cómo usar una API, generar clientes, escribir tests, crear documentación o incluso conectar flujos entre servicios.

Aquí no hablamos de un estándar nuevo, sino de uno que cambia de valor con el contexto actual.

OpenAPI ya no es solo documentación para humanos.

También es una forma de hacer que una API sea operable por agentes.

📄 Guía ADR: https://adr.github.io

Los ADR, o Architecture Decision Records, son registros de decisiones arquitectónicas.

Un ADR suele responder:

Ejemplos:

Esto es muy útil para personas nuevas en un equipo.

Y también para agentes.

Porque un agente sin memoria histórica puede intentar “mejorar” algo reabriendo debates que ya estaban cerrados.

Puede proponer una migración que el equipo descartó hace meses.

Puede cambiar una arquitectura sin entender sus restricciones.

Puede optimizar una parte del sistema rompiendo una decisión de producto o infraestructura.

Los ADR ayudan a evitar eso.

No porque bloqueen el cambio, sino porque dan contexto sobre por qué el sistema es como es.

📄 GitHub Security: https://docs.github.com/en/code-security

SECURITY.md es un archivo habitual en proyectos open source.

Define cómo reportar vulnerabilidades, qué versiones tienen soporte y qué canal usar para problemas de seguridad.

Pero con agentes de IA también tiene otro valor: marca límites.

Un agente que trabaja sobre un repo debería entender que no todos los errores se gestionan igual.

No es lo mismo:

SECURITY.md ayuda a que ciertas cosas no acaben en un issue público cuando deberían reportarse de forma privada.

También deja claro qué espera el proyecto cuando aparece un problema sensible.

En un mundo con agentes generando código, revisando PRs y automatizando tareas, esto no es decorativo.

Es higiene básica.

📄 Documentación: https://stitch.withgoogle.com/docs/design-md/overview

No existe un estándar universal tan asentado como README.md o SECURITY.md, pero cada vez tiene más sentido ver archivos tipo DESIGN.md.

Un agente que genera UI necesita saber más que “haz una pantalla bonita”.

Necesita contexto como:

Sin eso, la IA tiende a producir interfaces genéricas.

Correctas, quizá.

Pero genéricas.

Un DESIGN.md puede actuar como puente entre diseño, producto y código.

Y si un proyecto usa agentes para generar pantallas, landing pages, emails o componentes, este tipo de contexto deja de ser opcional.

Todos estos archivos apuntan a la misma dirección.

Los repositorios están dejando de ser solo lugares donde vive el código.

Cada vez más, se están convirtiendo en espacios donde vive el contexto operativo del proyecto.

Eso incluye:

Y esto importa porque los agentes no trabajan bien solo con prompts largos.

Trabajan mejor cuando el contexto está:

El prompt puntual sirve para una tarea.

El contexto estable sirve para muchas.

También hay que decirlo: no todo proyecto necesita diez archivos extra.

Un side project pequeño quizá vive perfectamente con un buen README.md.

El problema aparece cuando el proyecto crece, cuando entran más personas, o cuando empiezas a delegar trabajo en agentes.

Ahí la falta de contexto se paga.

No siempre en errores grandes.

A veces se paga en pequeñas decisiones malas:

Los archivos de contexto no eliminan esos problemas, pero reducen mucho la improvisación.

La diferencia entre una IA útil y una IA peligrosa no es el modelo.

Es el contexto que le das.

Si mañana quisieras preparar tu repo para trabajar mejor con IA:

La tendencia no es tener más documentación por tener más documentación.

La tendencia es convertir el contexto importante en algo explícito.

Algo que pueda leer una persona.

Y también un agente.

Porque si vamos a pedirle a la IA que trabaje sobre productos reales, no basta con darle acceso al repo.

Hay que darle criterio.

Y el criterio no aparece por arte de magia.

Se escribe, se versiona y se mantiene.

Los agentes no necesitan magia.

Necesitan buen contexto.