Para qué sirve el archivo DESIGN.md en un repositorio

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

DESIGN.md es un archivo markdown en la raíz de su repositorio que explica a un agente de programación por qué el código tiene la estructura actual. AGENTS.md responde a una pregunta distinta: cómo trabajar aquí, lo cual incluye el comando de compilación, el comando de pruebas, el linter que debe superarse y las rutas que no deben tocarse. DESIGN.md registra las decisiones que ya están consolidadas y qué componentes fallan si alguna de ellas se revierte.

Un agente de programación, es decir, una herramienta como Claude Code o Cursor que lee y edita su repositorio de forma autónoma, es confiado por defecto. Si encuentra un patrón que no reconoce, intenta mejorarlo. Una caché escrita a mano se convierte en Redis (un almacén de datos en memoria), porque así es como luce una caché en la mayor parte del código que el modelo ha leído. AGENTS.md no impide esto, porque make test se supera en ambos casos. La regla que se infringió nunca se escribió en un lugar que el agente pudiera leer.

Si aún no ha redactado el primer archivo, comience por ahí. AGENTS.md y el archivo HUMAN.md que lo acompaña cubre el formato y dónde busca cada herramienta. Lo que sigue 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 rastrea únicamente esos archivos. Su regla de inclusión es de una sola línea, y esa línea es el objetivo principal 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.

A fecha de agosto de 2026, enumera siete: Atlassian, Clerk, Mintlify, Nuxt, Resend, Vercel y VoltAgent. Cada archivo se encuentra en una URL pública estable, por lo que puede leer uno en una terminal ahora mismo.

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, movimiento. Lea más allá del tema, porque la parte útil es la estructura de la redacción y no el contenido en sí.

El archivo de Nuxt tiene aproximadamente 2100 palabras, y la mayor parte consiste en una regla acompañada de su justificación:

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 extenso, con unas 6500 palabras en agosto de 2026, y va un paso más allá. Uno de sus encabezados es Reject generated-design reflexes. Debajo se encuentra una lista de lo que un generador capaz busca cuando nadie le ha indicado lo contrario:

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 ser incluido en un repositorio es esa lista para algún dominio específico.

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

La comunidad se adelantó. awesome-design-md contiene 73 archivos de ingeniería inversa obtenidos de sitios web públicos, cada uno redactado con el mismo formato de nueve secciones, de modo que un agente puede procesar uno y generar algo similar a ese diseño. Esos archivos son útiles, pero siguen siendo suposiciones. Nadie en las empresas los revisó.

Un archivo de primera mano es distinto 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ñándole a su agente la escala antigua, y nada en su repositorio le indicará que la copia ha quedado obsoleta.

Siete editores es un número pequeño, y el repositorio lo admite: el estándar es nuevo y la adopción oficial está creciendo. Ambas colecciones son mantenidas por VoltAgent, un framework de agentes de código abierto que también publica su propio archivo, así que lea la lista como un rastreador y no como un censo neutral. Aun así, vale la pena seguirla por quiénes son esos siete. Son las empresas cuyo código de front-end es el más copiado por otros desarrolladores, y sus archivos se están convirtiendo en el ejemplo práctico de lo que es un DESIGN.md. Compare el camino que siguió AGENTS.md: agents.md cuenta ahora con más de 60,000 proyectos de código abierto que utilizan el formato, y la administración recae en la Agentic AI Foundation bajo la Linux Foundation. Las convenciones para archivos legibles por agentes se están consolidando rápidamente, y lo están haciendo desde arriba.

Qué incluir en 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 necesario, ya que el mecanismo no tiene nada que ver con el color. Se trata de documentar las restricciones que un editor confiado violaría sin darse cuenta.

Invariantes. Una frase por cada una, indicando algo que debe permanecer cierto tras cualquier edición. "Toda escritura pasa por queue.enqueue(). Una escritura directa a la base de datos omite el registro de auditoría, y el registro de auditoría es lo que lee la exportación de cumplimiento". Una invariante con su razón adjunta sobrevive al contacto con una tarea que nunca anticipó. Una invariante por sí sola se lee como una preferencia, y las preferencias se optimizan hasta desaparecer.

Alternativas rechazadas. La opción obvia y por qué se descartó. "No usamos Redis para el almacenamiento en caché. El servicio se ejecuta en un solo VPS, por lo que un mapa en memoria es más rápido y es un daemon menos que mantener activo. Revisar esto cuando exista un segundo servidor de aplicaciones". Sin ese párrafo, un agente al que se le pida acelerar la caché añade Redis, y tiene razón al hacerlo: nunca le comunicó la restricción. Esta es la sección que justifica la existencia de 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ública contra el que los clientes ya tienen scripts. El archivo de configuración que un despliegue lee antes de que la aplicación arranque. La entrada de cron que asume que solo se ejecuta una copia. Nómbrelos y diga cuánto cuesta un cambio en cada uno. Si el agente también puede acceder a la web abierta, por ejemplo a través de una instancia de SearXNG autohospedada conectada como su backend de búsqueda, ese es un límite que también vale la pena anotar, porque el archivo debe indicar qué texto obtenido puede influir en el código y cuál solo se cita de vuelta.

Vocabulario. Si el código dice tenant y el equipo dice customer, anote la correspondencia. Un agente que adivina mal aquí produce código que se lee bien pero modela algo incorrecto, lo cual es el tipo de error más difícil de detectar en una revisión.

Un archivo 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 las dos secciones que puede redactar de memoria hoy, invariantes y alternativas rechazadas, y deje el resto como encabezados. Un archivo con cuatro líneas honestas es suficiente. Un archivo con cuarenta líneas supuestas no lo es.

Algunas herramientas cargan cada archivo markdown en la raíz del repositorio y otras cargan solo el que se les indica, así que no haga suposiciones. Añada un puntero 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 común se lee bien pero no enseña nada. Comienza con lo que hace el proyecto, enumera las funciones, explica cómo instalarlo y termina con la licencia. Cada línea de eso ya está en el README, y ninguna explica por qué las cosas son como son.

Eso le cuesta el doble. El primer coste es el contexto. Un archivo que el agente lee al inicio de cada tarea se paga en cada tarea, y una sección de instalación duplicada es puro gasto innecesario frente a una ventana fija. Presupuestar esa ventana es una habilidad en sí misma, tratada en gestión de la ventana de contexto en Claude Code. La versión corta: todo lo que se carga automáticamente debe ser el texto de mayor valor en el repositorio.

El segundo coste es peor. Dos copias de la misma declaración terminan divergiendo. El README dice que el servicio escucha en 8080, DESIGN.md sigue diciendo 3000, y el agente no tiene forma de priorizar uno sobre el otro, así que elige uno y escribe código basado en él. Un archivo que a veces es incorrecto se consulta con la misma confianza que un archivo que siempre es correcto.

La prueba es rápida. Si un párrafo encajaría cómodamente en el README, elimínelo de DESIGN.md. Lo que quede debería ser la parte que usted diría en voz alta en una revisión de código, la parte que comienza con "ya intentamos eso".

¿Cómo saber si el archivo funciona?

No existe un linter para esto. Hay una comprobación que puede realizar en un minuto.

Asigne al agente una tarea que choque directamente con un invariante. "Añade un trabajo en segundo plano que marque las filas obsoletas como expiradas". Un archivo que cumple su función aparece en la respuesta antes que cualquier código: el agente debería indicarle que el trabajo escribe a través de queue.enqueue(), ya que una escritura directa omitiría el registro de auditoría. Si abre una conexión a la base de datos y escribe, ocurre una de estas dos cosas. O el archivo no se está leyendo en absoluto, o el invariante está redactado de forma lo suficientemente ambigua como para ser discutible.

Observe también el recuento de tokens, ya que 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 a dónde va ese presupuesto.

Esto es más importante cuando el agente reside en un servidor en lugar de en su equipo local. Un agente que trabaja en una sesión de larga duración, como la configuración en un espacio de trabajo de Claude Code en un VPS con tmux, no tiene memoria de la conversación de ayer. El repositorio es la memoria. Todo lo que explicó en el chat y nunca confirmó (commit) desaparece en la siguiente sesión, y DESIGN.md es el lugar donde esa explicación debe ir para que perdure.

Comience con las decisiones que generan debate

La primera versión toma veinte minutos. Abra las últimas solicitudes de extracción (pull requests) donde un revisor escribió "no, aquí lo hacemos de otra manera". Cada uno de esos comentarios es un invariante que nunca se documentó, y cada uno es un punto donde un agente cometerá el mismo error, más rápido y con mayor frecuencia que una persona. Añada contenido al archivo cuando este le falle, no siguiendo un calendario. Si todavía está determinando cómo encajan los agentes en un flujo de trabajo de desarrollo normal, la guía de 2026 para aprender sobre agentes de IA es el siguiente paso lógico.

FAQ

¿Es DESIGN.md un estándar oficial?

No de la misma forma que AGENTS.md. AGENTS.md tiene su sitio en agents.md, cuenta con más de 60,000 proyectos de código abierto que lo utilizan y está bajo la administración de la Agentic AI Foundation, parte de la Linux Foundation. A fecha de agosto de 2026, DESIGN.md no posee un organismo rector ni una especificación publicada. Lo que sí tiene es adopción por parte de los desarrolladores principales: siete empresas, incluidas Vercel, Nuxt, Atlassian y Resend, publican uno en una URL pública, y una colección comunitaria contiene 73 más obtenidos mediante ingeniería inversa a partir de sitios públicos. Considérelo una convención que puede adoptar ahora y ampliar libremente, ya que no existe nada que valide los nombres de sus secciones.

¿Debería DESIGN.md ser simplemente una sección de AGENTS.md?

Para un repositorio pequeño, sí. Un solo archivo que el agente lea con seguridad es mejor que dos archivos donde uno sea ignorado. Divídalos cuando AGENTS.md deje de ser legible o cuando note que ambas partes cambian a ritmos diferentes. AGENTS.md cambia cuando cambia la compilación. DESIGN.md cambia cuando cambia una decisión, lo cual es menos frecuente y tiene más peso. Al dividir, añada una línea a AGENTS.md indicando al agente que lea DESIGN.md antes de editar código, ya que no todas las herramientas cargan cada archivo markdown en la raíz.

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

Un ADR (architecture decision record) es un registro fechado de una decisión individual, y un proyecto saludable acumula docenas de ellos en una carpeta. Eso es un historial, y el historial es costoso de cargar, ya que un agente tendría que leerlos todos para determinar cuáles siguen vigentes. DESIGN.md es el estado actual, redactado para ser leído en su totalidad en cada tarea. Mantenga ambos si ya escribe ADRs. El ADR indica qué se decidió y cuándo. DESIGN.md indica qué es cierto hoy, y es al que debe dirigir al agente.

¿Qué extensión debería tener un DESIGN.md?

Lo suficientemente corto como para cargarlo en cada turno sin inconvenientes. 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 a fecha de agosto de 2026. Un servicio de backend suele necesitar mucho menos. Empiece con una página y amplíela solo cuando un agente se equivoque en algo que una sola frase habría evitado. La longitud no es la medida. Cada línea debe ser algo en lo que el agente se equivocaría de otro modo.