agents-md-setup

Haga de AGENTS.md la fuente única de verdad para las instrucciones del agente/proyecto, y apunte el archivo de cada herramienta a él mediante un enlace simbólico. Un solo archivo, leído por todos los agentes — sin duplicación, sin desviación.

Por qué este diseño

• AGENTS.md es el estándar emergente entre herramientas (Cursor, Codex y otras lo leen).
• Claude Code lee CLAUDE.md. No se puede hacer que el motor lea AGENTS.md en su lugar mediante un prompt o un skill, pero un enlace simbólico CLAUDE.md → AGENTS.md hace que Claude abra CLAUDE.md y obtenga el contenido de AGENTS.md. Ese es el mecanismo; no se necesita nada más.
• Resultado: edite solo AGENTS.md; todos los agentes se mantienen sincronizados.

Decisión: ¿qué hay ya?

1. Ningún archivo → cree AGENTS.md a partir de la plantilla de abajo.
2. Solo CLAUDE.md (un archivo real) → conviértalo en la fuente de verdad:

   git mv CLAUDE.md AGENTS.md       # conserva el historial (o: mv si no está en seguimiento)
   

3. Solo AGENTS.md → manténgalo tal cual (bien).
4. Ambos existen como archivos reales → NO sobrescriba a ciegas. Compárelos; fusione en AGENTS.md (gana como el archivo canónico), confirme con el usuario si los contenidos difieren, luego elimine el CLAUDE.md independiente.
5. CLAUDE.md ya es un enlace simbólico a AGENTS.md → ya está hecho; pare.

Cree el enlace simbólico

ln -s AGENTS.md CLAUDE.md
git add AGENTS.md CLAUDE.md        # git lo almacena como un enlace simbólico real (modo 120000)

Verifique que se confirmó como enlace simbólico, no como copia:

git ls-files -s CLAUDE.md          # el modo debe ser 120000

Opcionalmente, apunte otras herramientas al mismo archivo:

ln -s AGENTS.md GEMINI.md
mkdir -p .github && ln -s ../AGENTS.md .github/copilot-instructions.md

Monorepos (Turborepo / workspaces)

Mantenga un AGENTS.md raíz para las convenciones de todo el repositorio (con el enlace simbólico CLAUDE.md como arriba), luego agregue un AGENTS.md con ámbito en cada workspace que necesite sus propias reglas — apps/<app>/AGENTS.md, packages/<pkg>/AGENTS.md — cada uno con su propio enlace simbólico hermano creado desde ese directorio para que el destino sea relativo:

cd apps/web && ln -s AGENTS.md CLAUDE.md   # CLAUDE.md -> ./AGENTS.md (mismo directorio)

• Claude Code lee el CLAUDE.md más cercano para los archivos en los que está trabajando, por lo que los archivos anidados complementan la raíz en lugar de reemplazarla. Ponga cosas de todo el repositorio en la raíz; ponga solo el delta específico del paquete en cada workspace — no duplique la raíz.
• Siempre haga que cada enlace simbólico sea relativo a su propia carpeta (ln -s AGENTS.md CLAUDE.md mientras está en cd dentro del workspace), nunca apuntando de vuelta a la raíz — los enlaces relativos en el mismo directorio sobreviven a la desprotección/movimiento.
• Turborepo en sí no lee estos archivos (son para los agentes), por lo que no se necesita ningún cambio en turbo.json. Si desea que se muestren, aún puede notar la convención en el AGENTS.md raíz.

README

Si no hay README.md, genere uno mínimo (nombre del proyecto, descripción de una línea, comandos de configuración/ejecución). Mantenga la documentación orientada a humanos en README.md y las instrucciones del agente en AGENTS.md — no mezcle las dos.

Advertencia para Windows / CI (importante)

Los enlaces simbólicos de Git necesitan core.symlinks=true y pueden fallar en desprotecciones de Windows o algunos runners de CI (el enlace simbólico se materializa como un archivo de texto que contiene AGENTS.md). Si el proyecto apunta a Windows, prefiera el fallback: un real CLAUDE.md pequeño cuyo contenido completo es un puntero —

Véase [AGENTS.md](./AGENTS.md) para instrucciones del proyecto + agente.

— aceptando que debe mantenerse sincronizado manualmente (o mediante una comprobación). El enlace simbólico es mejor en todas partes donde los enlaces simbólicos son confiables.

No lo deshaga después

Si ve que CLAUDE.md es un enlace simbólico a AGENTS.md, eso es intencional — edite AGENTS.md, nunca reemplace el enlace simbólico con una copia.

Plantilla de AGENTS.md

# AGENTS.md

Instrucciones para agentes de IA y humanos que trabajan en este repositorio.
`CLAUDE.md` es un enlace simbólico a este archivo; este archivo es la fuente de verdad.

## Resumen del proyecto
<qué es esto, en 1–3 oraciones>

## Comandos
- instalar: `…`
- desarrollo: `…`
- compilar: `…`
- test / lint / formatear: `…`

## Convenciones
- <estilo de código, lenguaje/runtime, formato>
- Mensajes de commit: <ej. Commits Convencionales>
- <todo lo que un agente no debe hacer, o debe hacer siempre>

## Estructura
<directorios clave y qué contiene cada uno>