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 de IA por qué el código tiene su 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 aprobarse y las rutas que no deben tocarse. DESIGN.md registra las decisiones que ya están establecidas 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, actúa con confianza 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 se ve una caché en la mayor parte del código que el modelo ha procesado. AGENTS.md no impide esto, porque make test se ejecuta correctamente en ambos casos. La regla que se infringió nunca se documentó en un lugar que el agente pudiera leer.

Si aún no ha escrito 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 sólo registra esos archivos. Su regla de inclusión ocupa una línea, y esa línea es el objetivo de toda 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 octubre de 2026, enumera once: Ant Design, Atlassian, Clerk, Juspay, Microsoft FAST, Mintlify, Nuxt, Oxide Computer, Resend, Vercel y VoltAgent. Cada archivo está disponible en una URL pública, normalmente en el dominio de quien lo publica y, en los demás casos, en un repositorio público de GitHub, por lo que puede leer uno ahora mismo desde una 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 el aspecto que debe tener un producto: color, tipografía, espaciado y movimiento. Ignore el tema concreto y fíjese en la forma del texto, porque esa es la parte útil.

El archivo de Nuxt tiene aproximadamente 2,000 palabras a fecha de octubre 27, 2026, y la mayor parte consiste en una regla junto con su motivo. Comienza indicando que el modo oscuro es el tema predeterminado. Incluye el verde de marca #00DC82 con una nota que indica que los colores de marca son «Para logotipos, imágenes para redes sociales e impresión. No los use como valores sin procesar en el código de la interfaz de usuario». Cerca del final, una sección titulada Reject these incluye:

Raw hex values or palette classes (`text-gray-500`) in components instead of semantic tokens.

El archivo de Vercel es más largo, con aproximadamente 6,000 palabras a fecha de octubre de 2026, y va un paso más allá. Uno de sus encabezados es Reject generated-design reflexes. Debajo aparece una lista de los elementos que un generador competente elige cuando nadie le ha indicado que no los use:

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 84 archivos extraídos de sitios web públicos, según el recuento de su README del 27 de octubre de 2026. Todos están escritos con el mismo formato de nueve secciones, de modo que se puede indicar uno a un agente y obtener algo parecido a ese aspecto. Esos archivos son útiles, pero siguen siendo suposiciones. Nadie de las empresas los revisó.

Un archivo de primera parte 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 te avisará de que la copia quedó obsoleta.

Once publicadores siguen siendo un número reducido, y el repositorio lo reconoce: el estándar es reciente y la 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, así que debes interpretar la lista como un registro de seguimiento y no como un censo neutral. Aun así, merece la pena observarla por quiénes aparecen en ella. Varios son los publicadores cuyo código de front-end copian más otros desarrolladores, y las incorporaciones más recientes, Ant Design, Microsoft FAST, Juspay y Oxide Computer, son sistemas de diseño sobre los que construyen otros equipos. 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, bajo Linux Foundation. DESIGN.md ha comenzado a seguir el mismo camino. El 21 de abril de 2026, Google publicó como código abierto un borrador de especificación para el formato, disponible como google-labs-code/design.md, con un esquema de tokens y una CLI bajo la licencia Apache-2.0. En octubre de 2026, el formato está en la versión alpha y sigue en desarrollo activo; Google Labs lo mantiene, no una fundación neutral, y describe una identidad visual, por lo que no dice nada sobre las invariantes que necesita un archivo de backend. Las convenciones para archivos legibles por agentes se están estableciendo rápidamente, y lo hacen desde las organizaciones líderes.

Qué incluir en un archivo 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, porque 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 en 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ñadirá Redis, y tendrá razón al hacerlo: nunca se 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 lee un despliegue antes de que la aplicación inicie. 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 documentar, 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, escriba 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 hoy de memoria, 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. Si el repositorio contiene varios paquetes, un único archivo raíz no será adecuado para todos; aplique la misma división por directorio que funciona para archivos AGENTS.md anidados en un monorepo: un archivo raíz breve para las decisiones compartidas y uno más pequeño junto a cada paquete que tenga las suyas propias.

Algunas herramientas cargan todos los archivos markdown en la raíz del repositorio y otras solo cargan 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 características, explica cómo instalarlo y cierra 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 doble. El primer costo 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 costo es peor. Dos copias de la misma declaració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 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 bien en el README, elimínelo de DESIGN.md. Lo que quede debe ser la parte que usted diría en voz alta durante 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 ejecutar en un minuto.

Asigne al agente una tarea que choque directamente con un invariante. "Añade una tarea 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 la tarea 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 vaga 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. Leer 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 portátil. 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 donde debe ir esa explicación 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 aún 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 una siguiente parada razonable.

FAQ

¿Es DESIGN.md un estándar oficial?

No de la misma forma que AGENTS.md. AGENTS.md tiene su sitio oficial en agents.md, lo usan más de 60,000 proyectos de código abierto y cuenta con la tutela de Agentic AI Foundation, que forma parte de Linux Foundation. DESIGN.md tiene una especificación publicada, pero no cuenta con una entidad neutral que la administre. Google publicó una especificación preliminar como código abierto el April 21, 2026, y se encuentra en el repositorio google-labs-code/design.md, bajo la licencia Apache-2.0. En October 2026 está en la versión alpha y sigue en desarrollo activo. Describe una identidad visual: colores, tipografía, diseño y componentes. DESIGN.md también cuenta con adopción directa: eleven empresas y proyectos, entre ellos Vercel, Nuxt, Atlassian y Resend, publican uno. Además, una colección de la comunidad reunía 84 más, extraídos de sitios públicos, al October 27, 2026. Para un archivo de backend con invariantes y alternativas rechazadas, considérelo una convención que puede adoptar ahora y ampliar libremente, porque ninguna especificación cubre esos nombres de sección.

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

Para un repositorio pequeño, sí. Un solo archivo que el agente lea siempre 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 las dos partes cambian a ritmos diferentes. AGENTS.md cambia cuando cambia la compilación. DESIGN.md cambia cuando cambia una decisión, algo menos frecuente y con mayor peso. 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 de la raíz.

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

Un ADR (registro de decisiones de arquitectura) es el registro fechado de una decisión, y un proyecto saludable acumula decenas de ellos en una carpeta. Eso es un historial, y cargar el historial resulta costoso, porque el agente tendría que leerlos todos para determinar cuáles siguen siendo válidos. DESIGN.md representa 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 cierto hoy, y es el archivo que debe señalar al agente.

¿Qué extensión debe tener un DESIGN.md?

Debe ser lo bastante breve para cargarlo en cada turno sin arrepentirse. Los ejemplos publicados son largos porque especifican un lenguaje visual completo: el archivo de Nuxt tiene aproximadamente 2,000 palabras y el de Vercel aproximadamente 6,000 a October 2026. Un servicio de 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 la medida. Cada línea debe describir algo que, de otro modo, el agente haría mal.