DESIGN.md: decisiones que AGENTS.md no explica

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

DESIGN.md es un archivo Markdown situado en la raíz del repositorio. Explica a un agente de programación basado en 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 pasar y las rutas que no se deben modificar. DESIGN.md registra las decisiones ya establecidas y qué se rompe cuando se revierte alguna de ellas.

Un agente de programación, es decir, una herramienta como Claude Code o Cursor que lee y edita el repositorio por su cuenta, actúa con confianza de forma predeterminada. Encuentra un patrón que no reconoce y lo mejora. Un sistema de caché escrito 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 ha leído el modelo. AGENTS.md no lo evita, porque make test funciona de las dos formas. La regla que se incumplió nunca se había escrito 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 estos archivos. Lo que sigue es el capítulo posterior.

Qué hay realmente dentro de un DESIGN.md publicado

La forma más rápida de conocer 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.

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 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. No se centre en el tema, porque lo útil es la estructura del texto, no su contenido.

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 elementos que un generador competente suele elegir cuando nadie le indica que no debe hacerlo:

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 genera un modelo con confianza, publicada para que el modelo deje de generarlos. Todo DESIGN.md que merezca incorporarse a un repositorio es esa lista aplicada a algún dominio.

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

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

Un archivo publicado por la propia empresa 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 su agente la escala anterior, y nada del repositorio le indicará que la copia quedó obsoleta.

Siete empresas son pocas, y el repositorio lo reconoce: el estándar es nuevo y su adopción oficial está creciendo. VoltAgent mantiene ambas colecciones. Es un framework de agentes de código abierto que también publica su propio archivo. Por eso, debe leer la lista como un seguimiento y no como un censo neutral. Aun así, merece la pena observarla por quiénes son esas siete empresas. Son las empresas cuyo código de front-end copian más otros desarrolladores. Sus archivos se están convirtiendo en el ejemplo práctico de lo que es un DESIGN.md. Compare la trayectoria de AGENTS.md: agents.md ya registra más de 60,000 proyectos de código abierto que usan el formato, y la Agentic AI Foundation, dentro de la Linux Foundation, se encarga de su mantenimiento. Las convenciones para archivos legibles por agentes se están estableciendo rápidamente, y lo hacen desde las organizaciones más importantes.

Qué debe contener 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, de otro modo, un editor seguro de sí mismo infringiría sin darse cuenta.

Invariantes. Una frase por cada uno. Debe indicar algo que tiene que seguir siendo cierto después de cualquier edición. «Todas las escrituras pasan 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 ante una tarea que nunca había previsto. Un invariante sin explicación 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 único VPS, por lo que un mapa en el proceso es más rápido y elimina un daemon que mantener activo. Hay que reconsiderarlo 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 estará actuando correctamente: nunca se le indicó la restricción. Esta es la sección que justifica todo el archivo.

Límites. Los puntos en los que una edición pequeña puede tener un impacto amplio. 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 presupone que sólo se ejecuta una copia. Debe nombrarlos e indicar qué coste tiene cambiar cada uno.

Vocabulario. Si el código usa tenant y el equipo usa 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 escribir de memoria: invariantes y alternativas rechazadas. Deje el resto sólo como encabezados. Un archivo con cuatro líneas honestas es útil. Uno con cuarenta líneas inventadas no lo es.

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 haga suposiciones. 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 común se lee bien y no enseña nada. Empieza explicando qué hace el proyecto, enumera las funciones, explica cómo instalarlo y termina con la licencia. Todo eso ya está en el README, y nada explica por qué las cosas son como son.

Eso tiene dos costes. El primero es el contexto. Un archivo que el agente lee al principio de cada tarea se paga en cada tarea, y una sección de instalación duplicada es una sobrecarga inútil dentro de una ventana fija. Administrar esa ventana es una habilidad específica, 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 el 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 con «eso ya lo probamos».

¿Cómo se sabe 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 conduzca directamente a una invariante: «Añade un trabajo en segundo plano que marque como caducadas las filas obsoletas». Un archivo que cumple su función se refleja en la respuesta antes de que aparezca cualquier 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 directamente, se cumple una de estas dos condiciones: el archivo no se está leyendo o la invariante está redactada con suficiente ambigüedad como para admitir objeciones.

Controle también el recuento de tokens, porque este archivo se carga en cada turno. Si el uso de 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 descrita en un espacio de trabajo de Claude Code en un VPS con tmux, no conserva 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 se guarda esa explicación para que perdure.

Empieza por las decisiones que generan discusiones

La primera versión tarda veinte minutos. Abre las últimas solicitudes de cambios en las que un revisor escribió «no, aquí lo hacemos de otra forma». Cada uno de esos comentarios es un invariante que nunca se documentó y un punto en el que un agente cometerá el mismo error, más rápido y con más frecuencia que una persona. Añade información al archivo cuando te falle, no según un calendario. Si todavía estás determinando cómo encajan los agentes en un flujo 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 en el mismo sentido que AGENTS.md. AGENTS.md tiene su propio sitio en agents.md, más de 60,000 proyectos de código abierto lo utilizan y su mantenimiento está a cargo de Agentic AI Foundation, que forma parte de Linux Foundation. A fecha de agosto de 2026, DESIGN.md no tiene un organismo responsable ni una especificación publicada. Lo que sí tiene es adopción de primera mano: siete empresas, entre ellas Vercel, Nuxt, Atlassian y Resend, publican uno en una URL pública, y una colecció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 las secciones.

¿DESIGN.md debería ser sólo 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, cuando uno de ellos puede ignorarse. Sepárelos cuando AGENTS.md deje de poder revisarse rápidamente o cuando observe que las dos partes cambian a ritmos distintos. AGENTS.md cambia cuando cambia la compilación. DESIGN.md cambia cuando cambia una decisión, lo que ocurre con menos frecuencia y tiene más 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 un registro fechado de una sola decisión, y un proyecto bien mantenido acumula docenas de ellos en una carpeta. Eso es un historial, y cargar un historial resulta costoso, porque un 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.

¿Cuánto debe ocupar un DESIGN.md?

Debe ser lo bastante corto para cargarlo en cada interacción sin que resulte una carga. Los ejemplos publicados son largos porque especifican un lenguaje visual completo: a fecha de agosto de 2026, el archivo de Nuxt tiene unas 2,100 palabras y el de Vercel unas 6,500. 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 el agente cometería un error al hacer de otro modo.