Claude Code: reglas de equipo y memoria con CLAUDE.md

La ventaja está en dedicar menos tiempo a explicar lo mismo al inicio de cada sesión. Pensemos en un cálculo hipotético: cuatro desarrolladores que repiten tres minutos de preparación en cinco sesiones cada uno dedican 60 minutos a la semana a volver a explicar el contexto. Un archivo de instrucciones compartido permite mantener esa información en un solo lugar. Compara el tiempo que ahorras en repeticiones con el que dedicas a mantenerlo; el ahorro no está garantizado.

¿Qué es CLAUDE.md?

CLAUDE.md es un archivo Markdown con instrucciones que Claude Code lee para trabajar en tu proyecto, adaptarse a tu forma de trabajar o seguir las pautas de tu organización. Puedes verlo como el documento de referencia del equipo. La memoria automática es el cuaderno de notas que Claude mantiene a su lado. Tú defines las instrucciones; Claude escribe las notas. Ambos aportan contexto a sus decisiones. Guía de memoria de Anthropic

La distinción útil es qué debe seguir siendo válido de una sesión a otra. Un comando de pruebas obligatorio pertenece al archivo de instrucciones. Tu comentario de que una explicación fue demasiado detallada puede convertirse en una preferencia aprendida. La tarea actual pertenece a la conversación.

Esta separación sigue la guía oficial de directorios. No necesitas una carpeta .claude llena de archivos para empezar. Comienza con el documento de instrucciones y añade otro archivo solo cuando tenga una función clara.

Dónde guardar CLAUDE.md: proyecto, usuario y organización

Para un equipo pequeño, incorpora al control de versiones un archivo de proyecto en la raíz del repositorio. Guarda tus preferencias personales en el archivo de usuario para que no se apliquen por accidente al resto del equipo.

Estos son los ámbitos y las ubicaciones documentados. Los archivos administrados por la organización no se pueden excluir mediante ajustes individuales, aunque su texto sigue funcionando como orientación.

Al iniciarse, Claude carga los archivos de instrucciones del directorio de trabajo y de sus directorios superiores. Las instrucciones de los subdirectorios se cargan cuando trabaja con archivos de esas carpetas. El contenido de los archivos se combina: añadir uno más específico no elimina las instrucciones contradictorias que haya en otros. Mantén la coherencia entre las pautas de usuario y las del proyecto. Cómo se cargan las instrucciones

Un ejemplo de CLAUDE.md para un equipo de producto pequeño

Anota las decisiones que evitan errores recurrentes. El siguiente ejemplo parte de un producto en TypeScript que usa pnpm y ya tiene definidos los scripts lint, typecheck y test. Antes de incorporarlo al repositorio, sustituye los comandos y las rutas por otros que hayas comprobado en tu proyecto.

Cada sección incluye una línea que explica para qué sirve. Son convenciones propuestas para un equipo, no valores predeterminados de Anthropic.

# Product Team Instructions

## Product Intent
Why: Keep implementation tied to the customer problem.
- Read the task's acceptance criteria before changing code.
- Ask when missing product behavior would change the solution.

## Working Commands
Why: Make verification repeatable across teammates and sessions.
- Use pnpm for this repository; keep pnpm-lock.yaml consistent.
- Run pnpm lint and pnpm typecheck for application changes.
- Run pnpm test for behavior changes; report any checks not run.

## Change Boundaries
Why: Keep reviews small and dependencies deliberate.
- Follow nearby patterns before adding a new abstraction.
- Ask before adding a runtime dependency or changing public APIs.
- Keep unrelated cleanup out of the change.

## Data and Migrations
Why: Make data changes reviewable and reversible where possible.
- Add schema changes through the existing migration workflow.
- Describe compatibility and rollback concerns in the handoff.
- Use synthetic data in examples and tests.

## Quality
Why: Catch user-visible regressions before review.
- Add a focused regression test when fixing a behavior bug.
- Check loading, empty and error states when changing UI flows.
- State remaining uncertainty instead of calling unchecked work done.

## Project References
Why: Point to maintained decisions without copying the whole wiki.
- Read docs/product-decisions.md when product behavior is unclear.
- Read docs/release-checklist.md before preparing a release.

Las referencias de este ejemplo son instrucciones normales para consultar documentos cuando sea pertinente. Crea esos documentos o cambia las rutas. Se han dejado como referencias a propósito, sin importaciones automáticas.

Guarda el archivo, inicia una sesión desde el repositorio y ejecuta /context para comprobar la lista de memoria cargada al inicio. Usa /memory para abrir y editar el archivo de instrucciones. Después, asigna a Claude una tarea real y pequeña, y comprueba si los comandos y los límites resultan útiles. Cómo inspeccionar la memoria

Separa las reglas por tipo de archivo de las instrucciones generales

Mueve una regla a .claude/rules/ cuando no haga falta para la mayoría de las tareas. Por ejemplo, un cambio de frontend no necesita llevar consigo todas las convenciones de los manejadores de la API.

Crea .claude/rules/api.md con una cabecera paths. Un glob es un patrón de nombres de archivo; src/api/**/*.ts selecciona los archivos TypeScript de ese directorio y sus subdirectorios.

---
paths:
  - "src/api/**/*.ts"
---

# API Rules
- Validate external input before passing it to application logic.
- Use the existing error response format.
- Add a focused test when changing an endpoint's behavior.

El patrón determina cuándo se incorpora esa instrucción al contexto. Sin paths, la regla se carga siempre al inicio. Dividir un documento largo en varios archivos de reglas no ahorra contexto por sí solo: hay que delimitar cuándo se carga cada uno. Reglas según la ruta

Usa importaciones para compartir texto, teniendo en cuenta el contexto que consumen

Una importación como @docs/team-conventions.md dentro de CLAUDE.md incorpora ese archivo al contexto al iniciar la sesión. Las rutas relativas se resuelven desde el archivo que contiene la importación. Escribe la importación fuera de las comillas invertidas o los bloques de código de Markdown, ya que estos conservan el texto como literal. Las importaciones del proyecto que apuntan fuera del directorio de trabajo solicitan aprobación. Sintaxis de importación

Importa una convención breve que otro equipo ya mantenga si hace falta en todas las sesiones. Para una lista larga de comprobaciones antes de un lanzamiento, conviene una referencia normal como la del ejemplo inicial. Una importación reorganiza las instrucciones, pero no reduce la cantidad de texto que Claude lee al arrancar.

¿Ya usas AGENTS.md? Mantén una sola fuente de instrucciones

Claude Code puede usar AGENTS.md directamente en lugar de CLAUDE.md a partir de la versión 2.1.277, cuando esa compatibilidad esté disponible. El comportamiento predeterminado tiene una condición importante: no debe haber ningún CLAUDE.md, .claude/CLAUDE.md ni CLAUDE.local.md en el directorio de trabajo o en sus directorios superiores. Los archivos de instrucciones de usuario y de organización no impiden esta alternativa. Cómo se carga AGENTS.md

Por eso, CLAUDE.local.md puede generar confusión con facilidad. Añadir notas personales al proyecto puede cambiar qué archivo de instrucciones compartidas se carga en tu sesión.

Si necesitas ambos archivos, abre /config y establece Project instructions en claude-md-and-agents-md. Otra opción es incluir @AGENTS.md en un CLAUDE.md situado en el mismo directorio; esa importación también funciona cuando la lectura directa de AGENTS.md no está disponible. Evita mantener dos copias de las reglas del equipo. Nuestra guía para configurar AGENTS.md explica esta elección con más detalle.

Memoria de Claude Code: deja que la memoria automática guarde lo aprendido

La memoria automática permite a Claude guardar preferencias útiles, correcciones y contexto del proyecto entre conversaciones. Claude decide qué merece la pena conservar y puede que no guarde nada durante una sesión. Está activada de forma predeterminada en las sesiones locales. Memoria automática

De forma predeterminada, los archivos se guardan en ~/.claude/projects/<project>/memory/. Los worktrees y subdirectorios de un mismo repositorio comparten ese directorio de memoria en tu máquina. Un worktree es otra copia de trabajo del repositorio, de modo que empezar a trabajar allí en una rama no te da un cuaderno de notas independiente. Estos archivos no se comparten automáticamente con otros integrantes del equipo, otras máquinas ni entornos en la nube. Ubicación de los archivos

MEMORY.md es el índice. Al iniciar una sesión, Claude carga sus primeras 200 líneas o 25KB, lo que se alcance antes. Los archivos con detalles sobre cada tema se leen cuando hacen falta. Ese límite se aplica a la carga inicial del índice, no a la cantidad total de memoria que puedes almacenar. Cómo se carga la memoria automática

Usa /memory como punto de entrada: muestra las ubicaciones de memoria, abre los archivos en tu editor, da acceso a la carpeta de memoria automática y permite activarla o desactivarla. Usa /context para comprobar qué archivos CLAUDE.md y de reglas se cargaron al inicio. Controles de memoria

Indica con claridad dónde quieres guardar cada cosa. «Recuerda que prefiero informes de entrega más breves» pide una nota aprendida. «Añade nuestro comando obligatorio de pruebas a CLAUDE.md» pide una instrucción que se mantendrá al día. Una regla que necesita todo el equipo no debería depender de una nota en el directorio personal de un desarrollador.

No des por hecho que un subagente normal recibe ese cuaderno de notas. La memoria automática de la conversación principal no se carga en los subagentes normales; los forks que heredan la conversación principal son una excepción, y los subagentes pueden tener su propia memoria configurada. Consulta nuestra guía de subagentes de Claude Code cuando repartas trabajo entre agentes. Cómo funciona la memoria de los subagentes

Cómo desactivar la memoria automática

Elige el control adecuado para lo que quieres hacer:

• Tu configuración de usuario: abre /memory y desactiva la memoria automática. El interruptor guarda autoMemoryEnabled en ~/.claude/settings.json.
• Un proyecto: establece "autoMemoryEnabled": false en sus ajustes. Usa .claude/settings.json para una configuración compartida del proyecto o .claude/settings.local.json para un ajuste local que la sobrescriba.
• Un inicio controlado mediante el entorno: establece CLAUDE_CODE_DISABLE_AUTO_MEMORY=1.

Estos son los controles de desactivación y las ubicaciones de configuración documentados. Desactivar la memoria automática deja disponible el mecanismo independiente de instrucciones de CLAUDE.md. Si también quieres eliminar las notas antiguas, revisa y borra expresamente esos archivos Markdown.

Una revisión mensual de la memoria automática

Plantéala como una breve revisión editorial de lo que Claude llevará consigo al trabajo futuro. La frecuencia mensual es una propuesta de hábito para el equipo, no un requisito del producto.

1. Abre /memory y explora la carpeta de memoria automática. Lee MEMORY.md y sigue sus referencias hasta las notas concretas.
2. Elimina el contexto que ya no sirve. Borra plazos vencidos, planes abandonados y excepciones que hayan dejado de aplicarse. Contrasta las notas dudosas con el estado actual del proyecto.
3. Unifica las correcciones repetidas. Conserva una formulación precisa en lugar de varias versiones ligeramente distintas.
4. Convierte las decisiones duraderas del equipo en instrucciones compartidas. Traslada las convenciones que todos necesitan al CLAUDE.md del repositorio o a una regla con el ámbito adecuado; después, elimina la nota personal redundante.
5. Acorta el índice. Deja referencias breves en MEMORY.md y los detalles en archivos temáticos. Comprueba tanto el número de líneas como el tamaño en bytes frente al límite de carga inicial.
6. Prueba con una sesión nueva. Verifica la lista de instrucciones con /context y observa si aparecen consejos obsoletos en la siguiente tarea real.

Los archivos de memoria automática son Markdown editable, y la política de conservación de las conversaciones no los limpia automáticamente. Alguien tiene que retirar las notas obsoletas. Edición y conservación

Cinco situaciones en las que esta configuración resulta útil

Empieza por los casos en los que las correcciones repetidas ya están retrasando las revisiones. Estas propuestas de trabajo están ordenadas según su utilidad probable para un equipo de producto pequeño.

Dos pequeñas oportunidades para crear algo a partir de estas prácticas

La oportunidad más sólida es una auditoría de las instrucciones del repositorio. Un equipo pequeño podría pagar por una revisión que compruebe los comandos, detecte pautas contradictorias y proponga un documento breve con reglas de ámbito específico. El entregable mínimo útil sería un pull request revisado y una lista de comprobación para repetir la auditoría. DataForSEO estima 260 búsquedas mensuales en Estados Unidos de «claude project instructions». Esa consulta amplia abarca intereses que van más allá de Claude Code; indica interés en encontrar información, no una cantidad de compradores. Una plantilla genérica es fácil de copiar, así que el valor por el que se cobraría tendría que estar en el criterio aplicado a cada repositorio.

Un informe local sobre el estado de la memoria podría ayudar a equipos con muchos repositorios activos. La primera versión podría señalar índices demasiado grandes, referencias a archivos temáticos inexistentes y notas que quizá hayan quedado obsoletas, y dejar que el desarrollador revise los cambios. DataForSEO estima 1,300 búsquedas mensuales en Estados Unidos de «claude code memory». Eso muestra interés en el problema, no demanda de esta herramienta concreta. La dificultad es importante: la antigüedad de un archivo no permite saber si una decisión ya no es válida. Deja las decisiones sobre el significado y la vigencia del contenido en manos de quien conoce el proyecto.

Ambas estimaciones corresponden a consultas en inglés en Estados Unidos, obtenidas el 11 de octubre de 2026 mediante la integración de investigación de DataForSEO del sitio. Son propuestas de productos, no funciones integradas en Claude Code. Para un repositorio pequeño, empieza con el archivo y la revisión mensual antes de comprar o desarrollar cualquiera de las dos opciones.

La memoria aporta contexto, pero no impone límites técnicos

Escribir «nunca hagas esto» en CLAUDE.md no vuelve imposible una acción. Lo mismo ocurre con la memoria automática y con las instrucciones escritas para toda la organización. Claude puede interpretar mal una instrucción vaga o encontrarse con pautas contradictorias. Advertencia de Anthropic

Usa un hook PreToolUse, un control que se ejecuta antes de una acción de herramienta, cuando necesites bloquear esa acción independientemente de la decisión de Claude. Un recordatorio sobre archivos protegidos puede explicar la intención del equipo; para bloquear la acción hace falta implementar un control. Nuestra guía de configuración de hooks de Claude Code explica cómo hacerlo.

Para controlar el tamaño del contexto, busca un documento de instrucciones que alguien pueda mantener de verdad. Anthropic recomienda que cada archivo CLAUDE.md tenga menos de 200 líneas, pero esa recomendación es independiente del límite de carga inicial de MEMORY.md. No rellenes el ejemplo inicial para alcanzar una supuesta cuota ni muevas todo a importaciones pensando que así consumirá menos contexto. Cómo escribir instrucciones eficaces

Preguntas habituales de un equipo pequeño

Para empezar el lunes: reúne las correcciones de tus últimas sesiones, convierte las decisiones recurrentes del equipo en un único CLAUDE.md revisado y pruébalo con una tarea pequeña. Añade la revisión mensual de la memoria al calendario del equipo.

Si necesitas ayuda para convertir estas convenciones en una forma de desarrollar software fiable, consulta nuestro servicio de sistemas de IA en producción.