CLAUDE.md vs AGENTS.md vs SKILL.md vs DESIGN.md

Lea desde el alcance más estrecho hacia afuera. Una regla en un archivo más específico prevalece sobre una más general, y una regla que el usuario escribe en la sesión prevalece sobre cualquier archivo.

1. Lo que el usuario dice en la sesión — siempre prevalece, incluso cuando contradice un archivo.
2. `SKILL.md` — activo solo mientras se invoca esa skill, y limitado a ella.
3. `CLAUDE.md` / archivo específico de la herramienta — el comportamiento de esta herramienta en este repositorio.
4. `AGENTS.md` — las reglas del proyecto para cualquier agente.
5. `DESIGN.md` — el contrato visual, referenciado por los anteriores en lugar de competir con ellos.

Este es el primero que debe escribir. Es leído por un conjunto creciente de agentes, no pertenece a ningún proveedor y contiene aquello que es válido independientemente de quién realice el trabajo: cómo compilar, cómo probar, qué no tocar y qué convenciones sigue realmente la base de código.

La disciplina clave es el coste. Se carga en cada solicitud, por lo que cada línea se paga permanentemente. Una regla merece un lugar en el archivo solo si cambia el comportamiento predeterminado, se aplica de forma generalizada y es costoso cometer un error en ella. Los catálogos de comandos, los esquemas de API y los procedimientos de configuración deben ir en un documento con un enlace de una sola línea.

# AGENTS.md

## Build and verify
- `pnpm dev` on :4000. Never run `pnpm build` — it corrupts the shared dev cache.
- Verify with `tsc --noEmit`, not a build.

## Conventions
- Server work goes in `src/server/` as server actions, not API routes.
- Never hardcode theme colors; use the semantic tokens in DESIGN.md.

## Before you act
- Changing the payment flow: read `docs/PRICING.md` first.

El error recurrente es mantener CLAUDE.md y AGENTS.md como dos copias completas. Divergen silenciosamente, y esa divergencia se manifiesta cuando un agente sigue con seguridad una regla que usted eliminó hace dos meses.

# CLAUDE.md

@AGENTS.md

## Claude Code only
- Use the local browser tool for hydration checks; the remote one stalls RSC.
- Slash commands live in `.claude/commands/`.

La distinción que hace que las skills funcionen: AGENTS.md está *siempre* en el contexto, y una skill se carga *cuando es relevante*. Esa diferencia es una decisión de presupuesto. Una lista de verificación de revisión de código de 400 líneas en AGENTS.md se paga en cada solicitud, incluso en las que solo corrigen una errata. Esa misma lista como skill no cuesta nada hasta que la revisión comienza realmente.

Por lo tanto, la prueba no es la importancia, sino la frecuencia. Las reglas que se aplican a casi todas las solicitudes pertenecen al archivo siempre cargado. Los procedimientos que se aplican a un tipo específico de tarea —desplegar, revisar, generar una migración— pertenecen a una skill.

Aquí está la brecha. AGENTS.md no tiene un lugar natural para una rampa de colores. CLAUDE.md trata sobre el comportamiento de las herramientas. Una skill se invoca, no es ambiental. Por lo tanto, el contrato visual acaba en ninguna parte, y un agente sin contrato visual recurre a los valores por defecto, que es por qué los sitios creados por IA convergen en un mismo aspecto.

Un DESIGN.md cierra esa brecha. Como mínimo, contiene design tokens semánticos para modo claro y oscuro, la combinación y escala tipográfica, el sistema de espaciado y radios, y los aciertos y errores que evitan que un agente invente un patrón nuevo cuando se encuentra con un caso desconocido.

# DESIGN.md

## Color (semantic, light + dark)
--background / --foreground / --card / --primary / --muted-foreground …

## Type
Headings: Fraunces 600, -0.02em. Body: Inter 400, 1.6.
Scale: 0.875 / 1 / 1.25 / 1.5 / 2 / 3rem.

## Motifs
Hairline rules between sections. Radius scales with element size.

## Don't
No gradient text. No shadow on flat surfaces. Never hardcode a hex.

La razón por la que este archivo funciona donde un prompt no lo hace es poco glamurosa: se vuelve a leer al inicio de cada sesión. Las instrucciones mantenidas en la conversación se degradan a medida que crece el contexto. Un archivo no.

No, y empezar con los cuatro es un error. En orden aproximado de retorno de inversión:

1. `AGENTS.md` primero. Mayor valor por línea, funciona en diversas herramientas, fácil de escribir.
2. `DESIGN.md` después, si desarrolla UI. Es la mayor mejora de calidad con el menor esfuerzo, porque nada más lo cubre.
3. `CLAUDE.md` como una importación de una sola línea, más un anexo solo cuando tenga reglas específicas de la herramienta.
4. Skills al final, una vez que note que el mismo procedimiento largo se explica repetidamente.

Los archivos suelen compararse según su *finalidad*. Vale la pena saber cómo se utilizan en la práctica, porque la brecha entre la convención y la práctica es donde comienza la mayor parte de la confusión.

Analizamos 299 archivos DESIGN.md en la raíz de repositorios públicos de GitHub y los medimos. El primer hallazgo replantea toda la comparación: solo el 24% de ellos describe el diseño visual. El otro 76% son documentos de arquitectura de software: cómo se construye un sistema, no cómo se ve un producto.

Dentro de los 72 que describen genuinamente un sistema visual, no se está respetando la división de responsabilidades argumentada anteriormente. El 86% no utiliza nombres de roles de color semánticos, por lo que el archivo no puede aplicarse a ningún componente que no haya descrito explícitamente, que es precisamente la función para la que existe. El 76% no establece prohibiciones, y las prohibiciones son la forma de instrucción que los agentes siguen con mayor fiabilidad. El 69% omite el modo oscuro, dejando que todo un tema sea inventado.

La lectura práctica: la mayoría de los proyectos que añaden un DESIGN.md están escribiendo un documento en lugar de un contrato. La diferencia radica en si un agente puede resolver un valor a partir de él sin tener que adivinar.