¿Qué es DESIGN.md para Agentes de Codificación?

Los agentes de codificación son seguros, rápidos y arquitectónicamente despistados sobre tu base de código hasta que les digas lo contrario. Dale a Claude Code o Codex un ticket vago y felizmente escribirá código que compila, pasa una prueba rápida y viola silenciosamente el límite entre tu capa de dominio y tu capa HTTP. El agente no leyó tus documentos de diseño. Leyó los archivos que pudo ver, hizo coincidir patrones y adivinó. Un archivo DESIGN.md soluciona el problema de las conjeturas al plasmar tu intención arquitectónica en el único lugar donde un agente siempre busca: el propio repositorio.

TL;DR

DESIGN.md es un archivo de repositorio de convención comunitaria que registra la intención arquitectónica, las restricciones y las decisiones de diseño de una base de código en Markdown simple para que los agentes de codificación (Claude Code, Codex, Cursor) generen código que se ajuste al sistema en lugar de ir en su contra. Responde a la pregunta "por qué el código tiene esta forma", mientras que AGENTS.md responde a "cómo construyo y pruebo".

Introducción

Aquí está el modo de fallo que todos los equipos que adoptan agentes de codificación encuentran en una semana. Le pides a un agente que añada un endpoint de reembolso a un servicio de pagos. Devuelve un controlador funcional que llama directamente a la base de datos desde el controlador, ignora el error de la pasarela e inventa un nuevo tipo de moneda porque no notó que ya tenías uno. El diff está limpio. Las pruebas pasan. También está mal de tres maneras que solo un revisor que conoce la arquitectura puede detectar. El agente no es malo codificando; es ciego a las decisiones que viven en tu cabeza, en una página de Notion o en un hilo de Slack de hace ocho meses.

DESIGN.md es la respuesta a la que ha llegado un número creciente de equipos. Es un único archivo Markdown, incluido en la raíz del repositorio, que le dice a cualquier agente los hechos fundamentales sobre tu sistema: las reglas de capas, las invariantes que nunca deben romperse, los patrones que elegiste a propósito y los que rechazaste. No es una especificación de proveedor y no hay un comité que lo posea; es una convención, de la misma manera que ARCHITECTURE.md y CONTRIBUTING.md son convenciones. Pero se empareja naturalmente con los archivos de instrucciones específicos de las herramientas que los agentes ya leen, y para el trabajo de API y backend es uno de los documentos de mayor valor que puedes escribir.

Qué es DESIGN.md realmente

DESIGN.md es un registro de texto plano del porqué tu código tiene la forma que tiene. No lo que hace (eso es el README), no cómo ejecutarlo (eso es AGENTS.md), sino el razonamiento que un ingeniero sénior le explicaría a un nuevo empleado el primer día antes de dejarle tocar algo importante.

Piensa en las conversaciones que no están en ningún archivo. "No llamamos a la pasarela de pago desde el hilo de solicitud; todo pasa por la tabla outbox porque la pasarela se agota por tiempo de espera bajo carga". "El dinero es siempre un recuento entero de unidades menores; prohibimos los flotantes después del incidente de redondeo". "El agregado Account posee las mutaciones de saldo; nada más escribe en el libro mayor". Esas son decisiones de diseño. Son invisibles para un agente que lee el código fuente, porque la fuente muestra el resultado de la decisión, no la decisión o su justificación. Un agente puede ver que Account.debit() existe. No puede ver que deliberadamente lo convertiste en la única ruta de escritura, por lo que alegremente añadirá una segunda.

La convención tiene sus raíces en prácticas más antiguas y bien establecidas. El patrón ARCHITECTURE.md (popularizado por el escrito ampliamente citado de Alex Kladov) argumenta que un repositorio debe contener un mapa de alto nivel de la base de código que explique la estructura y las invariantes sin intentar mantenerse sincronizado línea por línea con el código. Los Registros de Decisiones de Arquitectura (ADR) capturan decisiones individuales y su justificación a lo largo del tiempo. DESIGN.md es lo que obtienes cuando escribes ese tipo de documento para una audiencia que incluye un agente de codificación: conciso, declarativo, orientado a decisiones y ubicado donde el agente realmente lo cargará.

Dos propiedades hacen que funcione. Está en el repositorio, por lo que el agente lo lee con las mismas herramientas que lee el código; no necesitas un plugin o una llamada a la API. Y se trata de la intención, por lo que sigue siendo útil incluso cuando los archivos se mueven. Renombra un paquete y tus capturas de pantalla del README se pudren; la regla "la lógica de dominio nunca importa el framework web" sigue siendo cierta.

DESIGN.md vs AGENTS.md vs CLAUDE.md vs README

Estos archivos se superponen lo suficiente como para confundir a la gente y difieren lo suficiente como para que fusionarlos en uno solo sea un error. La versión corta: README es para la incorporación de humanos, AGENTS.md es el contrato operativo para agentes, CLAUDE.md es el archivo de instrucciones específico de Claude, y DESIGN.md es el razonamiento arquitectónico del que todos se benefician.

AGENTS.md es ahora un formato real y ampliamente adoptado; el proyecto agents.md lo describe como "un formato simple y abierto para guiar a los agentes de codificación", utilizado en decenas de miles de proyectos y gestionado bajo la Agentic AI Foundation de la Linux Foundation. Su función es operativa: pasos de construcción, comandos de prueba, estilo de código, convenciones de commit, lo que le dirías a un nuevo compañero de equipo para que no se atasque. Según la documentación de memoria de Claude Code de Anthropic, CLAUDE.md desempeña el mismo rol de instrucción específicamente para Claude; la documentación incluso recomienda que si ya tienes un AGENTS.md, crees un CLAUDE.md que lo importe con @AGENTS.md para que ambas herramientas lean una única fuente de verdad.

Observa lo que falta en esas descripciones: una profunda justificación arquitectónica. AGENTS.md y CLAUDE.md están diseñados para ser cortos. La documentación de Claude Code recomienda explícitamente mantener CLAUDE.md por debajo de las 200 líneas porque los archivos más largos consumen contexto y reducen la fiabilidad con la que el modelo los sigue. Una explicación arquitectónica real, los límites, las invariantes, las alternativas rechazadas, las reglas del modelo de datos, no cabrán allí sin inflarlo. Por lo tanto, lo referencias en su lugar. DESIGN.md se convierte en el documento profundo; AGENTS.md / CLAUDE.md lo señalan con una sola línea.

La relación es complementaria, no competitiva. Una configuración limpia para un entorno Claude + Codex se ve así: README.md para humanos; un AGENTS.md con construcción/prueba/estilo; un CLAUDE.md que es solo @AGENTS.md más dos líneas solo para Claude; y DESIGN.md que contiene la arquitectura, enlazado desde AGENTS.md para que cada agente lo cargue bajo demanda. Sin duplicación, cada archivo tiene un solo trabajo. Si deseas una exploración más profunda de cómo estructurar el contexto de Claude a través de estos archivos, los flujos de trabajo de Claude Code explican el modelo de memoria en la práctica.

Qué incluir en DESIGN.md (con una plantilla)

DESIGN.md debe responder a las preguntas que un agente no puede inferir del código: la forma del sistema, las reglas que no aparecen en ningún archivo individual y las decisiones que tomaste a propósito. Mantenlo declarativo. Cada sección debe leerse como una regla que un revisor haría cumplir, no como un ensayo.

Cubre esto:

• Forma del sistema: las capas o módulos y la dirección en que fluyen las dependencias. Una frase por límite.
• Invariantes: cosas que siempre deben ser ciertas. Decláralas como absolutos. "Los saldos nunca son negativos fuera de un descubierto autorizado". "Cada llamada externa es idempotente por clave de solicitud".
• Decisiones clave y su justificación: las elecciones que parecen arbitrarias hasta que sabes por qué. Incluye el porqué; la justificación es lo que evita que un agente lo "arregle".
• Alternativas rechazadas: lo que deliberadamente no hiciste, para que un agente no lo proponga como una idea nueva. Esta única sección previene una gran clase de malas sugerencias.
• Reglas de datos y dominio: representación monetaria, manejo de tiempo/zona horaria, identificadores, borrado suave, multi-tenencia.
• La fuente de verdad del contrato API: dónde reside la especificación OpenAPI y la regla de que es autoritaria sobre los tipos escritos a mano.
• Dónde va el nuevo código: un mapa corto de "si añades X, pertenece a Y" para que los agentes dejen de dispersar la lógica.
• Fuera de alcance / no tocar: archivos generados, módulos heredados en migración, cualquier cosa que un agente deba dejar en paz.

Aquí tienes una plantilla completa, escrita para un servicio de API de pagos realista. Cópiala, elimina lo que no se aplique, rellena el resto.

# DESIGN.md: Servicio de API de Pagos

Este archivo registra la intención arquitectónica y las decisiones detrás de ella.
Léelo antes de generar o modificar código. Si un cambio entra en conflicto
con una regla aquí, detente y señálalo en lugar de intentar solucionarlo sin respetar la regla.

## Forma del sistema

En capas, las dependencias apuntan solo hacia adentro:

  http (handlers, DTOs)  ->  app (casos de uso)  ->  domain (entidades,
  invariantes)  <-  infra (db, clientes de pasarela)

- `domain/` no tiene importaciones de `http/`, `app/`, ni de ningún framework.
- `infra/` implementa interfaces declaradas en `domain/` o `app/`.
- `http/` nunca toca la base de datos o la pasarela de pago directamente.
  Llama a un caso de uso en `app/`.

## Invariantes (siempre deben cumplirse)

- Una entrada del libro mayor es inmutable una vez escrita. Las correcciones son nuevas
  entradas compensatorias, nunca actualizaciones o eliminaciones.
- El saldo de la cuenta se deriva de las entradas del libro mayor, no se almacena como un
  campo mutable que el código pueda establecer directamente.
- El dinero es un recuento entero de unidades menores (centavos) más un código de moneda ISO-4217.
  Nunca un flotante. Nunca mezclar monedas en una operación.
- Cada llamada a una pasarela de pago externa es idempotente, identificada por
  `idempotency_key`. Los reintentos no deben realizar un doble cargo.
- Los saldos nunca son negativos a menos que una `OverdraftPolicy` explícita
  lo autorice para esa cuenta.

## Decisiones clave y justificación

- **Patrón Outbox para llamadas a la pasarela.** Los controladores escriben una fila de intención
  en la misma transacción de DB que el cambio de negocio, luego un worker llama
  a la pasarela. Justificación: la pasarela se agota por tiempo de espera bajo carga;
  hacerlo en línea hizo que la latencia de las solicitudes y el manejo de fallos
  no tuvieran un responsable claro. No llamar a la pasarela desde un controlador de solicitud.
- **Única ruta de escritura por agregado.** Solo `Account.post_entry()`
  escribe en el libro mayor. Justificación: una segunda ruta de escritura causó la
  desviación de saldo de Mar-2025. Añadir nuevo comportamiento como métodos en el
  agregado, no como nuevas consultas.
- **Event sourcing solo para el libro mayor.** El resto del sistema es
  CRUD. Justificación: necesitamos una pista de auditoría perfecta para el dinero y
  nada más, y el event sourcing completo era demasiado costoso en otros lugares.

## Alternativas rechazadas (no reintroducir)

- Carga perezosa de ORM a través de agregados; causó N+1s y límites de transacción
  poco claros. Los repositorios devuelven agregados completamente cargados.
- Almacenar el saldo como una columna actualizada in situ; ver incidente de desviación
  de saldo. El saldo siempre se deriva.
- Una biblioteca genérica `Money` obtenida del registro; tenemos nuestra
  propia `domain/money.py`; úsala.
- Webhooks síncronos a comerciantes desde el hilo de solicitud;
  bloquean y fallan silenciosamente. Usar la cola de notificaciones.

## Reglas de datos y dominio

- Todas las marcas de tiempo son UTC, almacenadas como timestamptz, formateadas según RFC 3339
  en el borde. No hay datetimes ingenuos que crucen un límite de función.
- Los IDs son ULIDs generados en la capa de la aplicación, nunca autoincremento de DB.
- No se utiliza el borrado suave. Los registros están activos o se mueven a una
  tabla de archivo mediante un caso de uso explícito.
- Multi-inquilino: cada consulta tiene un alcance definido por `tenant_id`. Un método
  de repositorio sin un alcance de inquilino es un error.

## Fuente de verdad del contrato API

- La especificación OpenAPI 3.1 en `api/openapi.yaml` es autoritaria.
  Los tipos de solicitud/respuesta se generan a partir de ella; no edites manualmente
  los tipos generados en `http/generated/`.
- Endpoints nuevos o modificados: actualiza primero `api/openapi.yaml`, luego
  regenera, luego implementa. La especificación se diseña y revisa en
  Apidog antes de los cambios de código.
- Las respuestas de error siguen RFC 9457 (problem+json). Usa el helper
  `problem()` compartido; no inventes formas de error ad-hoc.

## Dónde va el nuevo código

- Nuevo endpoint: ruta en `http/routes/`, DTO en `http/dto/`, caso
  de uso en `app/usecases/`, lógica de dominio en `domain/`.
- Nueva integración externa: cliente en `infra/clients/`, interfaz
  en `app/ports/`.
- Preocupación transversal (autenticación, logging, idempotencia): middleware en
  `http/middleware/`, nunca en línea en los handlers.

## Fuera de alcance / no tocar

- `http/generated/`: regenerado a partir de OpenAPI, los cambios se pierden.
- `legacy/billing_v1/`: congelado, en migración. No extender.
- `migrations/`: nunca editar una migración aplicada; añadir una nueva.

## En caso de duda

Si un cambio solicitado requiere romper una regla anterior, lo correcto
es indicarlo y proponer la alternativa más pequeña consistente con el diseño,
no eludir la regla en silencio.

Esa última sección importa más de lo que parece. Decirle a un agente qué hacer cuando la solicitud entra en conflicto con el diseño convierte el archivo de documentación pasiva en una barandilla activa. Sin ella, un agente que encuentra una restricción tiende a eludirla y entregar la solución alternativa.

Cómo los agentes de codificación realmente consumen DESIGN.md

Los agentes no tienen un analizador especial para DESIGN.md. Lo consumen de la misma manera que consumen cualquier archivo: leyéndolo con sus herramientas de archivo y tratando el contenido como contexto. Por lo tanto, los mecanismos para que se cargue son importantes, y difieren ligeramente según la herramienta.

El patrón fiable es referenciar DESIGN.md desde el archivo de instrucciones que cada agente ya carga al inicio. Para Claude Code, ese es CLAUDE.md; la documentación de memoria describe una sintaxis de importación @path donde @DESIGN.md expande el archivo en el contexto al inicio de la sesión. Para el ecosistema AGENTS.md, añades una línea en AGENTS.md que lo señala ("Reglas de arquitectura y diseño: ver DESIGN.md; léelo antes de cambios estructurales"). Los agentes que recorren el árbol de directorios recogerán el AGENTS.md más cercano, verán el puntero y extraerán DESIGN.md cuando el trabajo afecte a la arquitectura. De cualquier manera, no estás duplicando contenido; mantienes el archivo operativo corto y permites que el archivo profundo sea profundo.

Tres notas prácticas sobre cómo se comportan estas herramientas:

Primero, el agente trata el archivo como contexto, no como reglas impuestas. La documentación de Claude Code es directa al decir que el contenido de CLAUDE.md es una guía que el modelo intenta seguir, no una restricción estricta. Lo mismo se aplica a cualquier cosa que referencies desde él. Por eso la plantilla formula todo como absolutos comprobables y añade una instrucción explícita de "en caso de duda"; la prosa vaga se ignora bajo presión, las reglas claras se siguen más a menudo.

Segundo, la longitud y la estructura cambian la adhesión. Los encabezados y las viñetas superan a los párrafos porque el modelo escanea la estructura de la misma manera que un lector. Un muro de filosofía arquitectónica de 3 páginas se hojeará; diez invariantes nítidas bajo un encabezado claro se usarán. Escribe para la recuperación, no para la prosa.

Tercero, el archivo cambia la economía de la revisión, no solo la generación. Incluso cuando un agente lo ignora parcialmente, un revisor puede señalar la regla violada y el agente la corrige en un solo turno ("esto rompe la regla de ruta de escritura única en DESIGN.md"). Ese ciclo de retroalimentación, que basa la corrección en la decisión escrita, es donde se obtiene gran parte del valor real. Los equipos que construyen sus propios arneses de agentes se apoyan precisamente en esto; consulta crea tu propio Claude Code para ver cómo ese ciclo se integra en flujos autónomos.

Anti-patrones y cómo evitar que se deteriore

La forma más rápida de hacer que DESIGN.md sea inútil es escribirlo como una página wiki. Un archivo de diseño deteriorado es peor que no tener ninguno, porque tanto los agentes como los humanos confían en él y se desorientan. Evita esto.

• Reafirmar el código. "La clase UserService maneja usuarios" no le dice a un agente nada que no pueda leer de user_service.py. Si una frase es cierta con solo leer el archivo, córtala. Conserva solo lo que el código no puede decirte: justificación, invariantes, rutas rechazadas.
• Expansión del tutorial. Los tutoriales paso a paso de "cómo añadir una característica" pertenecen a CONTRIBUTING.md o a un skill, no aquí. En el momento en que DESIGN.md tiene comandos de shell y fragmentos para copiar y pegar, es el documento equivocado y caducará a la velocidad de las herramientas.
• La aspiración como hecho. Escribir "el sistema usa CQRS" cuando la mitad no lo hace entrena a los agentes para producir código que coincida con una ficción. Documenta lo que es cierto ahora y hacia dónde te diriges deliberadamente, y etiqueta la diferencia. "Objetivo: todas las escrituras pasan por casos de uso. Actual: legacy/ omite esto; no lo extiendas."
• Sin propietario, sin activador de revisión. Un archivo de diseño del que nadie es responsable se desvía en un trimestre. Asócialo a un activador: revisa DESIGN.md en cualquier PR que añada un módulo, cambie un límite de capa o introduzca una nueva dependencia externa. Pon esa regla en la plantilla del PR. Algunos equipos añaden un elemento de lista de verificación: "¿este cambio modifica una decisión en DESIGN.md? Si así, actualízalo en el mismo PR."
• Teatro de sincronización. No intentes mantenerlo sincronizado línea a línea con el código; es una batalla perdida y la razón por la que los documentos de arquitectura se abandonan. Mantenlo al nivel de decisiones que cambian unas pocas veces al año, no de firmas de funciones que cambian semanalmente. La guía ARCHITECTURE.md de matklad es el instinto correcto aquí: solo escribe lo que es poco probable que cambie a menudo.
• Contradecir los otros archivos de instrucciones. Si AGENTS.md dice una cosa sobre el manejo de errores y DESIGN.md dice otra, los agentes eligen una arbitrariamente. Mantén las reglas operativas en AGENTS.md / CLAUDE.md y las reglas arquitectónicas en DESIGN.md, y no permitas que se superpongan. Cuando deban referenciarse mutuamente, uno apunta al otro; no ambos afirman el mismo hecho.

Un DESIGN.md saludable es corto, denso, declarativo, tiene un propietario y se revisa por un disparador. Si el tuyo es largo, narrativo y fue tocado por última vez hace un año, los agentes están leyendo ficción.

DESIGN.md para bases de código API y backend

Aquí es donde el archivo demuestra su valía. Los servicios API y backend tienen exactamente el tipo de restricciones invisibles y de alto costo en las que los agentes son peores: límites de contrato, semántica de transacciones, idempotencia, integridad de datos, capas. Nada de esto es obvio desde un solo archivo, y cometer errores envía bugs que llegan a producción y afectan el dinero.

Incluye estos elementos específicos de API en DESIGN.md y la calidad de la salida del agente en los tickets de backend aumentará:

• El contrato es la fuente de verdad, y di dónde está. Declara claramente que la especificación OpenAPI es autoritaria y que los tipos generados no deben editarse a mano. A los agentes les encanta "útilmente" ajustar un tipo generado para que una compilación pase; una línea en DESIGN.md lo detiene. Señala la ruta del archivo de especificación. Si diseñas el contrato primero en Apidog y exportas el documento OpenAPI al repositorio, tu DESIGN.md puede nombrar ese archivo como aquello a lo que cada endpoint debe conformarse, y el agente tiene un objetivo inequívoco. El argumento para diseñar el contrato antes del código se cubre en diseñar APIs para agentes de IA; un contrato primero en diseño es exactamente lo que hace que los manejadores generados por agentes sean seguros de aceptar.
• Límites de transacción y consistencia. ¿Dónde comienza y termina una transacción? ¿Qué está permitido dentro de ella? "Las llamadas externas nunca ocurren dentro de una transacción de DB; usa el outbox." Los agentes por defecto hacen la llamada en línea ingenua cada vez, a menos que el archivo lo prohíba.
• Idempotencia y reintentos. Establece la estrategia de idempotencia como una invariante. Los endpoints de pago, pedido y aprovisionamiento son donde una clave de idempotencia faltante se convierte en un doble cargo. El agente no inferirá esto leyendo un handler.
• Modelo de errores. Una frase: "todos los errores son problem+json a través del helper problem(); nunca inventes formas de error". Sin esto, obtendrías un sobre de error diferente por cada endpoint, lo que rompe a todos los clientes.
• Alcance de autenticación y tenencia. "Cada consulta tiene alcance de inquilino; un método de repositorio sin alcance de inquilino es un error." Esta es una invariante de seguridad, e invisible en cualquier consulta individual, por lo que es exactamente el tipo de regla que debe escribirse.
• Reglas de versionado y cambios disruptivos. Qué se considera un cambio disruptivo, cómo versionas, qué está permitido en una versión menor. Los agentes renombrarán felizmente un campo de respuesta; el archivo les dice que eso es un cambio disruptivo con un proceso.

Para el trabajo de backend, el beneficio es concreto: menos violaciones de capas, sin llamadas a la pasarela en línea inesperadas, formas de error y paginación consistentes, y manejadores conformes al contrato porque el agente fue dirigido a la especificación OpenAPI en lugar de adivinar el esquema. El agente deja de inventar y comienza a conformarse. Si deseas que el agente también ejercite la API que acaba de escribir, la combinación de contrato más diseño es lo que permite a las herramientas y agentes probar contra una interfaz conocida; Descarga Apidog te proporciona el espacio de trabajo con diseño primero, la exportación OpenAPI a la que apunta tu DESIGN.md, y un servidor MCP y un depurador de agentes de IA para verificar que los endpoints generados realmente coinciden con el contrato.

Conclusión

• DESIGN.md registra el porqué tu código tiene la forma que tiene: las invariantes, decisiones y alternativas rechazadas que un agente no puede leer del código fuente.
• Complementa en lugar de reemplazar a AGENTS.md y CLAUDE.md: estos se mantienen cortos y operativos; DESIGN.md contiene la arquitectura profunda y se referencia desde ellos.
• Escríbelo de forma declarativa, como absolutos comprobables más una regla de "en caso de duda, señala el conflicto, no lo evites", para que actúe como una barandilla, no como prosa pasiva.
• Resulta más rentable en bases de código API y backend, donde los límites del contrato, las transacciones, la idempotencia y el alcance de la tenencia son invisibles y costosos de manejar incorrectamente.
• Evita que se deteriore con un propietario y un disparador de revisión vinculado a tu plantilla de PR; nunca lo sincronices línea a línea con el código.
• La mayor ventaja en el backend es nombrar la especificación OpenAPI como autoritaria para que los agentes se ajusten al contrato en lugar de inventar esquemas.
• Diseña ese contrato primero. Descarga Apidog para diseñar APIs primero, exportar la especificación OpenAPI a la que apunta tu DESIGN.md, y probar que los endpoints generados por el agente realmente coinciden con ella.

Preguntas Frecuentes

¿Es DESIGN.md un estándar oficial como AGENTS.md?

No. AGENTS.md es un formato definido y ampliamente adoptado, ahora gestionado bajo la Agentic AI Foundation de la Linux Foundation. DESIGN.md es una convención comunitaria sin un único propietario o especificación, en la misma familia que ARCHITECTURE.md y los ADR. Trátalo como un patrón útil que adaptas, no como un estándar al que conformarte.

¿Necesito DESIGN.md si ya tengo AGENTS.md o CLAUDE.md?

Si tu arquitectura tiene restricciones no obvias, sí. AGENTS.md y CLAUDE.md están destinados a ser cortos y operativos; la documentación de Claude Code recomienda mantener CLAUDE.md por debajo de unas 200 líneas. Una justificación arquitectónica profunda no cabe allí sin inflarlo y perjudicar la adhesión, por lo que la pones en DESIGN.md y la referencias. Para el archivo operativo en sí, consulta cómo escribir archivos AGENTS.md.

¿En qué se diferencia DESIGN.md de ARCHITECTURE.md?

Principalmente en la intención y la audiencia. ARCHITECTURE.md es la convención más antigua destinada a colaboradores humanos que mapean la base de código. DESIGN.md es la misma idea escrita para una audiencia que incluye un agente de codificación: más declarativa, centrada en decisiones e invariantes, y referenciada explícitamente desde los archivos de instrucción del agente para que se cargue en el contexto. Muchos equipos usan un solo archivo y un solo nombre; los principios son los mismos.

¿Qué tan largo debe ser DESIGN.md?

Lo suficientemente largo para cubrir las decisiones que los agentes siguen equivocando, lo suficientemente corto para que cada línea gane su lugar. La densidad de decisiones supera a la exhaustividad. Si parece un tutorial o reafirma el código, córtalo. Unas dos a cuatro páginas enfocadas de invariantes y justificación superan una narrativa de quince páginas que ningún agente leerá con atención.

¿Cómo hago que el agente realmente lo lea?

Referéncialo desde el archivo que el agente ya carga al inicio. Para Claude Code, impórtalo desde CLAUDE.md con @DESIGN.md. Para el ecosistema AGENTS.md, añade una línea de puntero en AGENTS.md indicando a los agentes que lean DESIGN.md antes de realizar cambios estructurales. No pegues todo el contenido en el archivo corto; referéncialo para que el archivo operativo se mantenga corto.

¿El agente siempre seguirá DESIGN.md?

No, y deberías diseñar teniendo eso en cuenta. Los archivos de instrucciones del agente son contexto que el modelo intenta seguir, no una configuración impuesta. Escribe las reglas como absolutos claros, añade una instrucción explícita de "señala los conflictos, no los evites", y apóyate en el ciclo de revisión; señalar una regla violada en DESIGN.md consigue una corrección rápida y correcta incluso cuando la primera pasada la omitió.

¿DESIGN.md ayuda específicamente con los problemas de contrato de API?

Mucho. Su uso de mayor valor en el backend es establecer que la especificación OpenAPI es autoritaria y nombrar el archivo, para que los agentes se ajusten al contrato en lugar de inventar esquemas o editar a mano tipos generados. Diseñar ese contrato primero en una herramienta como Apidog le da al agente un objetivo inequívoco al que tu DESIGN.md puede apuntar directamente.

¿Dónde debería vivir DESIGN.md en el repositorio?

En la raíz del repositorio, junto a README.md y AGENTS.md, para que los agentes y los humanos lo encuentren sin buscar. En un monorepo, un DESIGN.md raíz para reglas de todo el sistema más uno por paquete para la arquitectura local funciona bien, reflejando cómo los agentes leen el AGENTS.md más cercano en el árbol de directorios.