DESIGN.md: el archivo que sigue a AGENTS.md

Qué es DESIGN.md y qué no cubre AGENTS.md

DESIGN.md es un archivo Markdown situado en la raíz del repositorio que explica a un agente de programación con IA por qué el código tiene su estructura actual. AGENTS.md responde a otra pregunta: cómo trabajar en este repositorio. Esto incluye el comando de compilación, el comando de pruebas, el análisis estático que debe superarse y las rutas que no deben modificarse. DESIGN.md registra las decisiones ya establecidas y lo que deja de funcionar si se revierte alguna de ellas.

Un agente de programación, es decir, una herramienta como Claude Code o Cursor que lee y modifica el repositorio por su cuenta, actúa con confianza de forma predeterminada. Encuentra un patrón que no reconoce y lo mejora. Una caché escrita manualmente se convierte en Redis (un almacén de datos en memoria), porque eso es lo que suele ser una caché en la mayoría del código que el modelo ha leído. AGENTS.md no lo impide, porque make test funciona de las dos formas. La regla que se infringió nunca se documentó en un lugar que el agente pudiera leer.

Si todavía no ha escrito el primer archivo, empiece por ahí. AGENTS.md y el archivo HUMAN.md que se encuentra junto a él explica el formato y dónde busca cada herramienta este archivo. El contenido siguiente es el capítulo posterior a ese.

Qué contiene realmente un DESIGN.md publicado

La forma más rápida de aprender el formato es leer los archivos que las empresas publican sobre sí mismas. El repositorio official-design-md sólo incluye esos archivos. Su regla de inclusión ocupa una línea, y esa línea es el objetivo de la colección:

Every entry here is a DESIGN.md published by the company or project itself — not extracted, not reverse-engineered, not community-made.

En agosto de 2026 incluye siete: Atlassian, Clerk, Mintlify, Nuxt, Resend, Vercel y VoltAgent. Cada archivo se encuentra en una URL pública estable, así que puede leer uno ahora mismo desde un terminal.

curl -s https://nuxt.com/design.md | head -n 60
curl -s https://vercel.com/design.md | wc -w

Ambos son documentos de sistemas de diseño. Describen cómo debe verse un producto: color, tipografía, espaciado y movimiento. No se centre sólo en el tema, porque lo útil es la estructura del texto, no el contenido específico.

El archivo de Nuxt tiene aproximadamente 2,100 palabras, y la mayor parte consiste en una regla acompañada de su motivo:

Dark mode is the default theme.
Colors are semantic (`primary`, `neutral`, `error`…) rather than hardcoded hex values in components.
Don't hardcode `#00DC82` in UI code — use `text-primary` or `color="primary"`.

El archivo de Vercel es más largo, unas 6,500 palabras en agosto de 2026, y va un paso más allá. Uno de sus encabezados es Reject generated-design reflexes. Debajo aparece una lista de los recursos a los que recurre un generador competente cuando nadie le ha indicado que no lo haga:

Hard reject decorative gradients, gradient text, glows, blobs, stripes, textures, grid backgrounds, glass effects, paper simulations, colored side rails, ornamental shadows, and fake depth.

Esa frase define el tipo de archivo. Es una lista escrita de los valores predeterminados que produce un modelo seguro de sí mismo, publicada para que el modelo deje de producirlos. Todo DESIGN.md que merezca incorporarse al repositorio es esa lista aplicada a un dominio concreto.

¿Por qué publican las empresas su propio DESIGN.md?

La comunidad se adelantó. awesome-design-md contiene 73 archivos obtenidos mediante ingeniería inversa a partir de sitios web públicos. Cada uno usa el mismo formato de nueve secciones. Así, se puede indicar a un agente que use uno de ellos y genere algo parecido a ese diseño. Estos archivos son útiles, pero siguen siendo suposiciones. Nadie de esas empresas los revisó.

Un archivo de primera mano es diferente porque es la fuente, no una interpretación del resultado. Cuando Vercel cambia su escala tipográfica, vercel.com/design.md cambia con ella. Una copia extraída en marzo sigue enseñando a tu agente la escala anterior, y nada en tu repositorio indica que la copia quedó obsoleta.

Siete editores son pocos, y el repositorio lo reconoce: el estándar es nuevo y su adopción oficial está creciendo. Ambas colecciones las mantiene VoltAgent, un framework de agentes de código abierto que también publica su propio archivo. Por tanto, considera la lista un seguimiento y no un censo neutral. Aun así, merece la pena observarla por quiénes son esos siete. Son las empresas cuyo código de front-end copian más otros desarrolladores, y sus archivos se están convirtiendo en el ejemplo práctico de lo que es un DESIGN.md. Compara la trayectoria de AGENTS.md: agents.md ya contabiliza más de 60,000 proyectos de código abierto que usan el formato, y la supervisión corresponde a Agentic AI Foundation dentro de Linux Foundation. Las convenciones para archivos legibles por agentes se están estableciendo rápidamente, y lo hacen desde las organizaciones líderes.

Qué debe incluir un DESIGN.md cuando el proyecto no tiene interfaz de usuario

La mayoría del software que se ejecuta en un VPS no tiene un lenguaje visual que especificar. El archivo sigue siendo útil, porque el mecanismo no tiene nada que ver con el color. Se trata de documentar las restricciones que un editor con criterio infringiría sin darse cuenta.

Invariantes. Una frase para cada una, que indique algo que debe seguir siendo cierto después de cualquier edición. «Toda escritura pasa por queue.enqueue(). Una escritura directa en la base de datos omite el registro de auditoría, y la exportación de cumplimiento lee ese registro». Un invariante acompañado de su motivo sigue siendo válido incluso ante una tarea que no había previsto. Un invariante aislado parece una preferencia, y las preferencias se eliminan durante la optimización.

Alternativas rechazadas. La opción obvia y el motivo por el que se descartó. «No usamos Redis para la caché. El servicio se ejecuta en un solo VPS, por lo que un mapa dentro del proceso es más rápido y hay un daemon menos que mantener activo. Reevalúe esta decisión cuando exista un segundo servidor de aplicaciones». Sin ese párrafo, si se pide a un agente que acelere la caché, añadirá Redis, y tendrá motivos para hacerlo: nunca le indicó la restricción. Esta es la sección que justifica todo el archivo.

Límites. Los lugares donde una pequeña edición tiene un gran radio de impacto. El esquema de la base de datos. El prefijo de ruta público que los clientes ya utilizan en sus scripts. El archivo de configuración que lee un despliegue antes de iniciar la aplicación. La entrada de cron que supone que sólo se ejecuta una copia. Nómbrelos e indique qué coste tiene cambiar cada uno. Si el agente también puede acceder a la web abierta, por ejemplo mediante una instancia de SearXNG autohospedada y configurada como backend de búsqueda, ese también es un límite que conviene documentar, porque el archivo debe indicar qué texto obtenido puede influir en el código y cuál sólo se le puede devolver citado.

Vocabulario. Si el código dice tenant y el equipo dice customer, documente la correspondencia. Un agente que se equivoca aquí produce código que se lee bien, pero representa el concepto incorrecto. Es el tipo de error más difícil de detectar durante la revisión.

Un DESIGN.md que puede copiar hoy

# DESIGN.md

## What this service is
One paragraph. What it does, who calls it, where it runs.

## Invariants
- Every write goes through `queue.enqueue()`. Direct writes skip the audit log.
- Timestamps are stored as UTC integers. Only the display layer converts them.
- One process writes to SQLite. The database is in WAL mode, and a second writer
  gets `database is locked` under load.

## Rejected alternatives
- **Redis for caching.** Rejected: one VPS, one process, an in-process map is
  enough. Revisit at two application servers.
- **An ORM for the reporting queries.** Rejected: the reports are four hand-tuned
  SQL statements. The generated query joined the same table twice.

## Boundaries
- `schema.sql` is append-only. A column rename needs a migration and a deploy window.
- The `/v1/` routes are public. Customers script against them, so the response
  shape is frozen.

## Vocabulary
- `tenant` in code is what the docs and the billing system call a customer account.

## Keeping this file honest
Update it in the commit that changes the decision. A stale DESIGN.md is worse
than no DESIGN.md, because the agent believes it.

Complete hoy las dos secciones que puede redactar de memoria: invariantes y alternativas rechazadas. Deje el resto como encabezados. Un archivo con cuatro líneas honestas es útil. Uno con cuarenta líneas inventadas no lo es. Si el repositorio contiene varios paquetes, un solo archivo raíz no servirá para todos. En ese caso, aplique la misma separación por directorios que funciona con archivos AGENTS.md anidados en un monorepo: un archivo raíz breve para las decisiones compartidas por todo el repositorio y otro más pequeño junto a cada paquete que tenga decisiones propias.

Algunas herramientas cargan todos los archivos markdown del directorio raíz del repositorio y otras cargan sólo el archivo que se les indica. No dé por hecho que se comportan igual. Añada una referencia a AGENTS.md:

Read DESIGN.md before editing anything under `src/`. It lists the invariants and
the alternatives that were already rejected.

El antipatrón: un DESIGN.md que repite el README

La versión incorrecta más habitual se lee bien, pero no enseña nada. Empieza explicando qué hace el proyecto, enumera sus funciones, explica cómo instalarlo y termina con la licencia. Todo eso ya está en el README, y ninguna de esas líneas explica por qué las cosas son como son.

Eso tiene dos costes. El primero es el contexto. Un archivo que el agente lee al inicio de cada tarea se procesa en todas las tareas, y una sección de instalación duplicada consume espacio sin aportar valor dentro de una ventana fija. Administrar esa ventana es una habilidad propia, que se trata en administrar la ventana de contexto en Claude Code. La versión breve es esta: todo lo que se cargue automáticamente debe ser el texto de mayor valor del repositorio.

El segundo coste es peor. Dos copias de la misma afirmación terminan divergiendo. El README dice que el servicio escucha en 8080, DESIGN.md todavía dice 3000 y el agente no tiene forma de determinar cuál debe prevalecer. Por tanto, elige una y escribe código basándose en ella. Un archivo que a veces es incorrecto se consulta con la misma confianza que uno que siempre es correcto.

La comprobación es rápida. Si un párrafo encajaría sin problemas en el README, elimínelo de DESIGN.md. Lo que quede debe ser la parte que explicaría en voz alta durante una revisión de código, la parte que empieza por «eso ya lo probamos».

¿Cómo saber si el archivo funciona?

No hay un linter para esto. Puede ejecutar una comprobación en un minuto.

Asigne al agente una tarea que conduzca directamente a un invariante: «Añade un trabajo en segundo plano que marque las filas obsoletas como expiradas». Un archivo que cumple su función se refleja en la respuesta antes de que aparezca código: el agente debería indicar que el trabajo escribe mediante queue.enqueue(), porque una escritura directa omitiría el registro de auditoría. Si abre una conexión a la base de datos y escribe, sólo puede ocurrir una de estas dos cosas: el archivo no se está leyendo o el invariante está redactado de forma tan imprecisa que permite discutirlo.

Vigile también el recuento de tokens, porque este archivo se carga en cada turno. Si el uso del contexto aumenta después de añadir DESIGN.md y las respuestas no mejoran, el archivo contiene prosa que el agente ya conocía. Lectura de los contadores de tokens en Claude Code muestra en qué se consume ese presupuesto.

Esto es especialmente importante cuando el agente se ejecuta en un servidor y no en su portátil. Un agente que trabaja en una sesión de larga duración, como la configuración de un espacio de trabajo de Claude Code en un VPS con tmux, no recuerda la conversación del día anterior. El repositorio es la memoria. Todo lo que explicó en el chat y nunca confirmó en el repositorio se pierde en la siguiente sesión. DESIGN.md es donde debe guardar esa explicación para que sobreviva.

Empiece por las decisiones que suelen generar desacuerdos

La primera versión lleva veinte minutos. Abra las últimas solicitudes de incorporación de cambios en las que un revisor haya escrito «no, aquí lo hacemos de otra manera». Cada uno de esos comentarios representa un invariante que nunca se documentó y un punto en el que un agente cometerá el mismo error, más rápido y con mayor frecuencia que una persona. Añada contenido al archivo cuando le falle, no según un calendario. Si todavía está determinando dónde encajan los agentes en un flujo de trabajo de desarrollo normal, la guía de 2026 para aprender sobre agentes de IA es un siguiente paso razonable.

FAQ

¿DESIGN.md es un estándar oficial?

No de la misma forma que AGENTS.md. AGENTS.md tiene un sitio web en agents.md, más de 60,000 proyectos de código abierto lo utilizan y su gestión está a cargo de Agentic AI Foundation, que forma parte de Linux Foundation. En agosto de 2026, DESIGN.md no tiene un organismo responsable ni una especificación publicada. Lo que sí tiene es adopción por parte de los proveedores: siete empresas, incluidas Vercel, Nuxt, Atlassian y Resend, publican uno en una URL pública, y una recopilación de la comunidad contiene otros 73 obtenidos mediante ingeniería inversa a partir de sitios públicos. Trátelo como una convención que puede adoptar ahora y ampliar libremente, porque nada valida los nombres de sus secciones.

¿DESIGN.md debe ser sólo una sección de AGENTS.md?

Para un repositorio pequeño, sí. Un archivo que el agente lea con seguridad es mejor que dos archivos, si uno de ellos se ignora. Sepárelos cuando AGENTS.md deje de poder revisarse rápidamente o cuando observe que ambas partes cambian con frecuencias distintas. AGENTS.md cambia cuando cambia la compilación. DESIGN.md cambia cuando cambia una decisión, algo menos frecuente y de mayor importancia. Al separarlos, añada una línea a AGENTS.md que indique al agente que debe leer DESIGN.md antes de editar código, porque no todas las herramientas cargan todos los archivos markdown del directorio raíz.

¿En qué se diferencia DESIGN.md de un registro de decisiones de arquitectura?

Un ADR (registro de decisiones de arquitectura) es un registro fechado de una decisión, y un proyecto bien gestionado acumula decenas de ellos en un directorio. Eso es un historial, y cargar un historial resulta costoso, porque el agente tendría que leerlos todos para determinar cuáles siguen siendo válidos. DESIGN.md refleja el estado actual y está escrito para leerse completo en cada tarea. Mantenga ambos si ya escribe ADR. El ADR indica qué se decidió y cuándo. DESIGN.md indica qué es válido hoy y es el archivo que debe indicar al agente que consulte.

¿Qué longitud debe tener un DESIGN.md?

Debe ser lo bastante corto para cargarlo en cada turno sin que resulte innecesario. Los ejemplos publicados son largos porque especifican todo un lenguaje visual: el archivo de Nuxt tiene unas 2,100 palabras y el de Vercel unas 6,500 en agosto de 2026. Un servicio backend normalmente necesita mucho menos. Empiece con una página y amplíelo sólo cuando un agente cometa un error que una sola frase habría evitado. La longitud no es el criterio. Cada línea debe describir algo que, de otro modo, el agente haría mal.