English

Mantén un archivo de reglas para tu agente

Deja de repetirle lo mismo a tu asistente de IA en cada sesión. Cada sesión nueva arranca con una ventana de contexto en blanco: tu agente de código olvida el comando de build, el test runner, la regla de "usamos indentación de 2 espacios" — todo. La solución es un archivo de reglas: un archivo markdown en tu repo que documenta tus convenciones una sola vez y que el agente lee automáticamente al inicio de cada sesión.

Por qué un archivo de reglas gana a reescribir

1. Cero repetición. Comandos de build, estándares de código y estructura del proyecto se cargan automáticamente. Nunca los vuelves a explicar.
2. Consistencia. Las mismas reglas aplican en cada sesión, para cada integrante del equipo — el archivo está versionado, así que cambiar una convención es un pull request, no un hilo de Slack.
3. Onboarding instantáneo. Un agente nuevo (o un compañero nuevo) es productivo desde el primer prompt, porque el conocimiento de "así trabajamos aquí" vive junto al código.

Una idea, muchos nombres de archivo

Todos los agentes de código principales soportan el patrón; solo cambia el nombre del archivo:

Si tu repo ya tiene un AGENTS.md, Claude Code puede reutilizarlo: pon @AGENTS.md en su propia línea dentro de CLAUDE.md y el archivo se importa al inicio de la sesión — una sola fuente de verdad que todas las herramientas leen.

Qué poner adentro

Escribe lo que de otra forma volverías a explicar. El mejor detonante: el agente comete el mismo error dos veces — eso es una entrada para el archivo de reglas. Buen contenido:

• Comandos de build, test y ejecución (npm test, make lint) — comandos exactos, no "corre los tests"
• Estándares de código que difieren de los defaults de la herramienta ("indentación de 2 espacios", "sin default exports")
• Estructura del proyecto ("los handlers del API viven en src/api/handlers/")
• Trampas y reglas de "siempre/nunca" ("nunca hacer push directo a main")

Mantenlo específico y corto. La guía de Anthropic para CLAUDE.md recomienda menos de 200 líneas: archivos más largos consumen más contexto y las instrucciones se siguen con menos fiabilidad. Lo concreto gana a lo vago — "Corre npm test antes de hacer commit" funciona; "prueba tus cambios" no.

Trucos avanzados

• Divide por tema. Claude Code lee cada .md en .claude/rules/ (p. ej. testing.md, security.md); Cursor hace lo mismo con .cursor/rules/. Archivos pequeños y enfocados son más fáciles de mantener que un monolito.
• Limita reglas por rutas. Tanto Claude Code como Cursor soportan reglas con globs (frontmatter paths: / globs:) que se cargan solo cuando el agente toca archivos coincidentes — reglas de TypeScript solo para **/*.ts. El contexto se mantiene ligero.
• Importa, no dupliques. La sintaxis @path/to/file de Claude Code trae otros archivos al contexto al arrancar (hasta cuatro niveles de profundidad). Una línea @AGENTS.md mantiene DRY a los repos multi-herramienta.
• Reglas personales vs. de equipo. Deja las convenciones del equipo en el archivo versionado; guarda tus preferencias privadas en un hermano ignorado por git (CLAUDE.local.md) o en tu directorio home.
• Las reglas son contexto, no enforcement. El agente trata el archivo como una guía fuerte, no como configuración dura. Para reglas que nunca deben romperse (comandos bloqueados, rutas protegidas), usa la capa de enforcement de tu herramienta — hooks o permisos — y deja el archivo de reglas para el comportamiento.

Mantenlo al día

Un archivo de reglas desactualizado es peor que ninguno: el agente seguirá con toda confianza las convenciones del trimestre pasado. Revísalo cuando cambien las convenciones, elimina entradas contradictorias (un agente ante dos reglas en conflicto puede elegir cualquiera) y trata las ediciones del archivo de reglas como parte del code review que cambió la convención.

Recursos

• Memoria de Claude Code — archivos CLAUDE.md, reglas e imports
• AGENTS.md — el estándar abierto multi-herramienta de archivos de reglas
• Reglas de proyecto de Cursor (.cursor/rules)
• Instrucciones personalizadas de repositorio de GitHub Copilot