AGENTS.md y DESIGN.md en temas de Shopify: cómo darle contexto a Sidekick y a tu agente

Si le has pedido a un agente de IA que modifique un tema de Shopify, seguramente te pasó: el Liquid funciona, pero no sigue las convenciones del tema, inventa clases nuevas o usa colores en duro en vez de los ajustes del tema. Shopify acaba de darle una respuesta oficial a ese problema: dos archivos Markdown en la raíz del tema, AGENTS.md y DESIGN.md, que le dan a cualquier agente el contexto que le falta.

Llegan con la Fall ‘26 Edition de Shopify (la nota para desarrolladores es del 28 de octubre de 2026), junto con Canvas, la nueva superficie de diseño donde los comerciantes construyen su tienda con Sidekick, anunciada el 1 de octubre de 2026. Todo lo que sigue sale de la documentación de shopify.dev consultada el 30 de octubre de 2026.

Qué son y para qué sirven

Según la documentación, los agentes construyen sobre un tema más rápido y de forma más consistente cuando saben cómo funciona el tema y cuál es la intención de diseño detrás. Esa información viaja en dos archivos:

• AGENTS.md: explica cómo está construido el tema, para que el agente aproveche su arquitectura y sus convenciones.
• DESIGN.md: registra la intención de diseño, para que el agente extienda el diseño de forma coherente cuando construye algo nuevo.

Son contexto para agentes: no son plantillas, Shopify no los renderiza y los compradores nunca los ven.

Los leen dos tipos de agentes:

• Sidekick en Canvas: cuando un comerciante le pide a Sidekick cambiar el tema en Canvas, Sidekick lee estos archivos antes de hacer cambios. Y si le piden cambios de estilo, puede actualizar DESIGN.md para que los siguientes cambios sigan la nueva dirección.
• Tu agente local: cuando desarrollas el tema en tu equipo, los archivos son parte del directorio del tema y los agentes compatibles con el formato AGENTS.md los leen como instrucciones del proyecto.

Lo interesante es que es el mismo contexto en los dos lados: lo que escribes en local es lo que lee Sidekick en el administrador, y las decisiones de diseño que Sidekick registra te llegan la próxima vez que hagas pull del tema.

Dónde van y qué reglas tienen

Los dos archivos van en la raíz del tema, junto a las carpetas de siempre:

.
├── AGENTS.md
├── DESIGN.md
├── assets
├── blocks
├── config
├── layout
├── locales
├── sections
├── snippets
└── templates

Las reglas de la documentación:

• Todos los temas los admiten y los dos son opcionales. Puedes tener uno, ambos o ninguno.
• El nombre distingue mayúsculas y minúsculas: exactamente AGENTS.md y DESIGN.md. Shopify no guarda otras variantes como agents.md o Design.md.
• Solo en la raíz del tema. Archivos con esos nombres en otras carpetas no están soportados.
• Hasta 50 KB cada uno.
• Formato libre: es Markdown sin estructura obligatoria.

No lo confundas con agents.md.liquid

Ojo con el nombre: el AGENTS.md de la raíz no es la plantilla agents.md.liquid. Esa plantilla vive en templates y renderiza la página pública /agents.md, la que leen los agentes de compra para saber cómo comprar en la tienda. El AGENTS.md de la raíz es código fuente del tema para agentes de programación y no se sirve en la tienda.

Qué poner en AGENTS.md

La idea es explicar lo que un agente no deduce leyendo un par de archivos y los errores que quieres que evite. Sin este contexto, dice la documentación, el agente recurre a su conocimiento general de temas de Shopify: suele bastar para escribir Liquid que funciona, pero no para seguir los patrones que hacen que tu tema sea consistente y mantenible.

Como referencia, el tema base que usa Canvas para crear temas nuevos incluye un AGENTS.md con estos apartados:

• Reglas no negociables: la lista corta de reglas que todo cambio debe cumplir.
• Modelo de composición: cómo encajan plantillas, bloques y snippets, y qué archivo es dueño de cada parte de la página.
• Contratos de bloques y snippets: la forma que sigue cada bloque, cómo expone sus ajustes y cuándo usar un snippet en su lugar.
• Estilos y tokens: dónde viven los estilos, qué tokens de diseño usar y dónde está la intención de diseño (DESIGN.md).
• JavaScript: cómo estructura el tema sus custom elements y maneja eventos.
• Traducciones: cómo agregar textos visibles para el usuario.
• Guía de decisiones: respuestas rápidas, como si un elemento nuevo debe ser bloque o snippet.

Si creas un tema con Canvas y haces pull, tienes un ejemplo completo para estudiar.

Tres consejos de la documentación para escribirlo:

1. Escribe reglas, no tutoriales. Los agentes ya saben Liquid y HTML; dedica el archivo a lo específico de tu tema.
2. Explica el porqué. Una regla con su razón ayuda al agente en los casos que la regla no cubre.
3. Mantenlo al día. Actualízalo en el mismo cambio que introduce un patrón nuevo.

Este es un ejemplo propio, no de la documentación, para un tema ficticio:

# AGENTS.md

## Reglas no negociables
- Todo texto visible va en `locales/es.default.json`. Nunca escribas textos en duro en Liquid.
- No uses jQuery. El JavaScript del tema son custom elements en `assets/`.
- Colores, tipografías y espaciados salen de los ajustes del tema (`settings.*`), nunca de valores fijos.

## Composición
- Cada sección se arma con bloques de `blocks/`. Si un elemento lo debe poder mover el comerciante, es un bloque; si solo se reutiliza en código, es un snippet.

## Antes de tocar estilos
- Lee `DESIGN.md` antes de cualquier cambio visual.

Qué poner en DESIGN.md

Si AGENTS.md explica cómo está construido el tema, DESIGN.md explica cómo se ve y se siente la tienda. La documentación lo llama el “contrato de diseño” de la tienda: los ajustes del tema en config definen qué se renderiza, y DESIGN.md explica por qué.

Suele cubrir:

• Resumen de marca: qué vende la tienda, a quién y cómo debe hacer sentir a la gente.
• Tesis de diseño: una frase que conecta la marca con el sistema visual.
• Colores: nombre, valor, token y función de cada uno.
• Tipografía: familias, pesos, tamaños, interlineado, espaciado entre letras y el rol de cada estilo.
• Espaciado y composición: márgenes, radios, sombras y layout, como el ancho máximo de página.
• Componentes: cómo se ven botones, tarjetas de producto, encabezados, pies de página y campos de formulario.
• Qué hacer y qué no: reglas explícitas.
• Movimiento: los patrones de animación e interacción del tema.

Y tres consejos de la documentación:

1. Nombra los tokens. Refiérete a los tokens y ajustes del tema, no a valores fijos, para que el agente aplique las elecciones del comerciante en vez de escribirlas en duro.
2. Sé explícito. “No uses más de dos familias tipográficas” funciona mejor que “mantenlo simple”, porque el agente puede comprobarlo.
3. Registra decisiones, no código. Los detalles de implementación van en el código y en AGENTS.md.

Si una parte de tu DESIGN.md se genera con alguna herramienta (el tema base de Canvas empieza con un índice generado de tokens y clases), márcala claramente para que los agentes la conserven, y explica en AGENTS.md cómo mantenerla al día.

Sincronización: CLI, GitHub y editor

Los dos archivos se manejan como cualquier otro archivo del tema:

• Shopify CLI 4.8.4 o posterior los incluye en shopify theme pull, shopify theme push y shopify theme package. Si usas una versión anterior, actualízala. (Si no conoces estos comandos, los expliqué en Shopify CLI para temas.)
• Integración con GitHub: se sincronizan en los dos sentidos entre el repositorio y el tema conectado.
• Editor de código del administrador: puedes abrirlos y editarlos ahí.
• GraphQL Admin API: se leen con la conexión files del objeto OnlineStoreTheme y se escriben con la mutación themeFilesUpsert.

Un detalle práctico: como Sidekick puede modificar DESIGN.md, la documentación recomienda hacer pull del tema antes de empezar a trabajar en local, para que tu agente siga las últimas decisiones de diseño de la tienda.

Cómo hacer que Claude Code los lea

Aquí hay dos matices que conviene conocer, ambos de la documentación oficial de Claude Code.

AGENTS.md se lee solo si no hay un CLAUDE.md. Desde Claude Code v2.1.277, si tu carpeta tiene un AGENTS.md y ningún CLAUDE.md, .claude/CLAUDE.md ni CLAUDE.local.md en el directorio de trabajo o por encima, Claude Code lo lee como instrucciones del proyecto. Pero si también tienes un CLAUDE.md, por defecto lee solo el CLAUDE.md. Si ya trabajas con un CLAUDE.md en tus temas (lo expliqué en la guía de inicio de Claude Code), tienes dos opciones:

• Importar AGENTS.md desde tu CLAUDE.md con la sintaxis @:

@AGENTS.md

## Claude Code

Instrucciones que solo aplican a Claude Code.

• O cambiar en /config el ajuste Project instructions a claude-md-and-agents-md, para que lea los dos.

Para comprobar qué cargó, ejecuta /context en la sesión y revisa la lista Memory files.

DESIGN.md no se lee solo. La documentación de Shopify lo advierte: la mayoría de los agentes no leen DESIGN.md automáticamente, así que hay que indicárselo en AGENTS.md o en las skills de tu agente. Y la de Claude Code añade que, si solo se lo dices con palabras, Claude lo verá únicamente si decide abrir el archivo. Mi recomendación es una frase clara en AGENTS.md, como “Lee DESIGN.md antes de cualquier cambio visual”, que entienden igual Sidekick y cualquier otro agente. Si quieres que Claude Code lo cargue siempre, puedes importarlo desde tu CLAUDE.md con @DESIGN.md (mejor ahí que en AGENTS.md, porque la sintaxis @ es de Claude Code y otros agentes la verían como texto). Eso sí, entonces ocupará contexto en cada sesión, también cuando no toques estilos.

Si estas reglas las usas en muchos temas, también puedes empaquetarlas en un skill: lo expliqué en cómo crear un skill en Claude Code.

Lo que no garantizan

La documentación de Shopify lo deja claro en las dos páginas: los agentes de IA no son deterministas. Siguen las reglas de AGENTS.md y la intención de DESIGN.md la mayoría de las veces, pero a veces pueden tomar otro camino. Úsalos para orientar el razonamiento del agente, no como garantía. Si necesitas que algo no ocurra nunca, eso se resuelve con revisiones de código o, en Claude Code, con hooks.

Mi recomendación

1. Empieza por AGENTS.md con 5 a 10 reglas que hoy corriges a mano cada vez que un agente toca el tema.
2. Escribe DESIGN.md con tokens, no con colores en hexadecimal, y con reglas que se puedan comprobar.
3. Actualiza Shopify CLI a 4.8.4 o posterior antes de confiar en que pull y push los sincronicen.
4. Si trabajas con clientes que usan Sidekick, haz pull antes de empezar. Su DESIGN.md puede haber cambiado desde la última vez.

Conclusión

AGENTS.md y DESIGN.md convierten el conocimiento que tienes de un tema (sus convenciones y su estilo) en algo que cualquier agente puede leer: Sidekick en el administrador o el agente que uses en tu editor. Son dos archivos de texto opcionales, sin formato obligatorio y fáciles de mantener. Lo único que hay que vigilar es que tu agente realmente los cargue.

Fuentes

• Agentic workflows for themes (shopify.dev)
• AGENTS.md (shopify.dev)
• DESIGN.md (shopify.dev)
• Bringing shopping into the future: The Fall ‘26 Edition for developers (Shopify News, 28 de octubre de 2026)
• Introducing Canvas (Shopify News, 1 de octubre de 2026)
• Shopify Editions Fall ‘26
• How Claude remembers your project (documentación de Claude Code)