Añades una regla a CLAUDE.md. La semana siguiente pasas una tarea a Codex, y nunca lee la regla. Pegas la misma instrucción en .cursor/rules. Ahora la misma convención vive en tres ficheros, alejándose entre sí a tres velocidades, y ninguno es el sitio donde alguien nuevo miraría para entender por qué el producto funciona como funciona.
Todas las comparativas serias de estos ficheros que he leído discuten lo mismo: cómo hacer que el agente escriba código en tu estilo. Tabs o espacios, qué runner de tests, en qué carpeta va el componente nuevo. Importa, pero es la mitad barata del problema. La mitad cara es dónde viven las decisiones de producto: por qué la auth es stateless, por qué nunca hacemos soft-delete, por qué este endpoint se mantiene idempotente aunque complique el handler. Esas son las instrucciones que, cuando desaparecen, te cuestan una reescritura. Y un fichero de reglas es un mal sitio para ellas.
Para qué sirve de verdad cada fichero
Separemos los tres, porque no son la misma clase de cosa.
AGENTS.md es lo más parecido a un estándar neutral que tiene este espacio. Es un Markdown plano en la raíz del repo que cualquier agente puede leer, definido en abierto en agents.md, y adoptado por varias herramientas en vez de por un solo proveedor. Su trabajo es el contrato operativo del repo: cómo se compila, cómo se corren los tests, qué comandos son seguros, cuál es la estructura. Es agnóstico al agente a propósito, y por eso es el sitio correcto para hechos que son verdad da igual quién ejecute.
CLAUDE.md es la convención de Anthropic para Claude Code, y es útil de verdad cuando Claude Code es tu executor. Anthropic lo documenta en sus buenas prácticas de Claude Code, y puede cargar contexto por directorio, permisos de herramientas, los pequeños rituales que una sesión necesita. La trampa está en el nombre. Es el fichero de Claude. En cuanto enrutas una tarea a otro motor, se queda sin leer.
Las reglas de Cursor (el directorio .cursor/rules) son la misma idea atada a Cursor, con más estructura sobre cuándo aplica cada regla. GitHub Copilot tiene su propia versión también, las instrucciones personalizadas del repositorio. Bien dentro de esa herramienta. Invisible fuera.
Así que el mapa real es: un estándar abierto para los hechos operativos, y un conjunto de ficheros de proveedor para el comportamiento específico de cada herramienta. Ninguno se diseñó para ser la memoria de tu producto.
La línea que decide dónde va una regla
Este es el test que uso. Para cualquier instrucción que vayas a escribir, pregunta: ¿esto es cómo funciona el repo, o por qué el producto decidió algo?
- Cómo funciona el repo es estable, verificable y verdad para todo agente. “Corre
make testantes de decir que está hecho.” “Las migraciones viven endb/migrate.” “Nunca edites ficheros generados.” Esto va en AGENTS.md, porque es el contrato operativo y debe viajar al motor que uses. - Por qué el producto decidió algo es una decisión con un motivo y un radio de daño. “Mantenemos el webhook de pago idempotente porque el proveedor reintenta.” “No cacheamos el saldo porque un saldo obsoleto es un ticket de soporte y una devolución.” Eso no es una convención de código. Es el contrato de producto, y no pinta nada en un fichero que un agente concreto resulta que lee.
Cuando metes decisiones en un fichero de reglas, se estropean tres cosas. El fichero crece hasta que los agentes lo leen en diagonal. Los motivos se comprimen en órdenes, así que el por qué desaparece y solo sobrevive el qué, con lo que el siguiente no distingue una regla que sostiene el edificio de un resto olvidado. Y la decisión pasa a vivir en el formato de una sola herramienta, así que no sobrevive a un cambio de motor. La versión general de esto la argumenté en las especificaciones de software deberían ser portables: el artefacto que carga una decisión tiene que durar más que la herramienta que lo leyó.
Los ficheros de reglas son convenciones. Las decisiones son contratos.
Una convención le dice a un agente cómo encajar. Un contrato le dice qué no puede romper. Los ficheros de reglas están hechos para lo primero y fallan en silencio en lo segundo.
El fallo es silencioso porque nada peta. El agente lee la regla que sigue ahí, la obedece, y produce un build verde contra una instrucción que dejó de ser verdad hace dos sprints. De eso va entero tu fichero de reglas miente a tus agentes: una regla obsoleta no lanza un error, solo despista, con seguridad. Una decisión que solo vive como una línea en CLAUDE.md no lleva motivo pegado ni dueño, así que nadie nota cuando la realidad la deja atrás.
Un contrato se comporta distinto. Carga el motivo, viaja con la tarea en vez de sentarse en un fichero global que todo agente lee a medias, y es comprobable. El criterio de aceptación “el saldo nunca se sirve desde caché” se puede testear. La línea de CLAUDE.md “prefiere lecturas frescas” no. Uno es un gate. El otro es una intuición con buenas intenciones.
Qué guardo en cada sitio
Este es el reparto que corro a diario, operando agentes en más de un motor:
| Instrucción | Dónde vive | Por qué ahí |
|---|---|---|
| Comandos de build y test | AGENTS.md | operativo, agnóstico al motor |
| Estructura del repo, comandos seguros | AGENTS.md | verdad para todo agente |
| Permisos de herramientas de Claude | CLAUDE.md | solo lo lee Claude Code |
| Alcance de reglas de Cursor | .cursor/rules |
solo lo aplica Cursor |
| “Por qué nunca hacemos soft-delete” | la spec / registro de decisión | es una decisión, con motivo |
| Criterios de aceptación de un cambio | el contrato de la tarea | tiene que ser verificable y viajar |
Los ficheros de reglas se quedan pequeños y operativos. Las decisiones viven en artefactos que persisten fuera de cualquier sesión, cargan su motivo y se pueden comprobar, cerca de la tarea que las necesita. Cuando enruto el mismo trabajo a otro modelo, como en enrutar cada tarea al motor correcto, el fichero operativo puede releerlo el motor nuevo y la decisión viaja con el trabajo igualmente. Nada importante queda atrapado en el Markdown de un proveedor.
Dónde encaja PaellaDoc
Es el mismo argumento que el resto de lo que construyo. Un fichero de reglas vale como nota operativa y es peligroso como memoria de producto, porque el contrato de producto tiene que estar por encima de cualquier agente o no es un contrato, solo un ajuste que alquilas hasta que la herramienta cambia. PaellaDoc guarda las decisiones, los criterios de aceptación y los motivos como artefactos de primera clase que viajan con la tarea y se comprueban en el gate, escriba el código el motor que escriba. El AGENTS.md sigue diciéndole al agente cómo compilar. El contrato decide si lo que construyó cuenta. Ese reparto de trabajo es la tesis entera del runtime: tú eres el runtime sosteniéndolo a mano, hasta que lo hace otra cosa.
FAQ
¿Uso AGENTS.md o CLAUDE.md?
Los dos, para trabajos distintos. Guarda los hechos operativos (build, test, estructura, comandos seguros) en AGENTS.md para que todo motor los lea. Guarda el comportamiento específico de Claude en CLAUDE.md si Claude Code es uno de tus executors. No dupliques el mismo contenido en ambos, o heredas el problema de deriva en cuanto una copia cambie.
¿Dónde deberían vivir las decisiones de producto si no en el fichero de reglas?
En un artefacto que cargue el motivo y se pueda verificar, cerca del trabajo que gobierna: una spec, un registro de decisión, o los criterios de aceptación de la tarea. Los ficheros de reglas comprimen las decisiones en órdenes y pierden el por qué, y están atados a una herramienta. Una decisión necesita durar más que la sesión y que el motor.
¿Sigo necesitando las reglas de Cursor si tengo AGENTS.md?
Si usas Cursor y quieres su alcance y su aplicación por glob, sí, para comportamiento específico de la herramienta. Solo que no dejes que se convierta en el único sitio donde se escribe una decisión de verdad, porque es invisible para cualquier otro agente al que puedas enrutar trabajo.