Cómo gestionar la memoria de Claude Code en varios proyectos: uso en equipo de CLAUDE.md, Memory y Hooks

Cuando un equipo empieza a usar Claude Code de forma habitual, la memoria se vuelve un problema real. Un repositorio usa pnpm, otro usa Poetry; uno exige pruebas antes de tocar código, otro prioriza documentación. Si esas reglas se mezclan, el asistente empieza a aplicar hábitos del proyecto equivocado.

La solución no es meter todas las instrucciones en un prompt enorme. Lo más estable es dividir la memoria: CLAUDE.md para reglas del repositorio, Memory para preferencias transversales y Hooks para comprobaciones automáticas.

Por qué se desordena la memoria entre proyectos

Los equipos reales mantienen frontend, backend, scripts, infraestructura y documentación. Cada parte tiene comandos, riesgos y convenciones distintas. Si todo se explica de forma oral en cada sesión, se pierde tiempo y aparecen errores.

El objetivo no es que Claude Code recuerde más, sino que recuerde lo correcto en el lugar correcto.

Modelo de tres capas

CLAUDE.md explica cómo funciona este proyecto; Memory explica cómo suele colaborar el equipo; Hooks automatiza lo que debe comprobarse siempre.

CLAUDE.md como manual de proyecto

Colócalo en la raíz del repositorio. Debe ser concreto, estable y accionable.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

# Project Guide

## Tech Stack

- Runtime: Node.js 22
- Package manager: pnpm
- Framework: Next.js
- Tests: Vitest and Playwright

## Common Commands

- Install dependencies: `pnpm install`
- Run dev server: `pnpm dev`
- Run unit tests: `pnpm test`
- Run lint: `pnpm lint`
- Run e2e tests: `pnpm test:e2e`

## Working Rules

- Before editing shared UI components, inspect existing usage first.
- Prefer existing helpers in `src/lib` before adding new utilities.
- Do not change database migrations unless the task explicitly asks for it.
- Keep unrelated refactors out of feature fixes.

## Verification

- For UI changes, run `pnpm lint` and the nearest relevant test.
- For API changes, add or update request-level tests.
- For database changes, include migration notes in the final summary.

Así Claude Code no tiene que adivinar comandos, carpetas especiales o zonas sensibles.

No conviertas CLAUDE.md en un cajón de sastre

Si el archivo crece sin control, las reglas importantes se pierden. Conserva solo reglas que cambian el comportamiento real, elimina instrucciones obsoletas, no guardes tareas temporales y evita repetir la misma idea.

Memory para preferencias transversales

Memory es útil para reglas que se aplican a todos los proyectos: idioma de los commits, cuidado con cambios de producción, no revertir cambios sin permiso, revisar móvil en frontend o listar hallazgos antes del resumen en una revisión.

Las rutas, scripts y comandos de un repositorio concreto deben vivir en ese repositorio.

Hooks para automatizar comprobaciones

Hooks puede ejecutar formato, revisar secretos, recordar pruebas al tocar ciertas carpetas, impedir .env en commits o resumir archivos modificados. Debe automatizar acciones claras, no sustituir decisiones humanas.

Estructura recomendada

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

workspace/
├── app-web/
│   ├── CLAUDE.md
│   └── package.json
├── app-api/
│   ├── CLAUDE.md
│   └── pyproject.toml
├── infra/
│   ├── CLAUDE.md
│   └── deploy.ps1
└── docs/
    └── ai-working-rules.md

Cada repositorio mantiene su propio CLAUDE.md. Las reglas comunes pueden vivir en documentación del equipo y solo las preferencias realmente estables pasan a Memory.

Ejemplos por tipo de proyecto

Frontend:

1
2
3
4
5
6

## Frontend Rules

- Use existing components in `src/components` before creating new ones.
- Keep layout stable on mobile and desktop.
- Use `pnpm lint` for quick validation.
- For visual changes, mention what viewport was checked.

Backend:

1
2
3
4
5
6

## Backend Rules

- API handlers live in `src/routes`.
- Database migrations must be reviewed manually.
- Do not change authentication middleware without explicit approval.
- Run `pytest tests/api` after endpoint changes.

Operaciones:

1
2
3
4
5
6

## Operations Rules

- Treat deployment scripts as production-sensitive.
- Do not print secrets or tokens in logs.
- Prefer dry-run mode before changing remote state.
- Summarize changed commands before final handoff.

Cuándo actualizar la memoria

Actualízala cuando Claude Code repite el mismo error, cuando el equipo vuelve a explicar la misma regla, cuando cambia la verificación, cuando se reorganizan carpetas o cuando una regla queda obsoleta.

Uso en revisión de código

Un flujo razonable es: leer CLAUDE.md, inspeccionar las carpetas afectadas, ejecutar la verificación mínima, priorizar bugs y regresiones, y cerrar con un resumen breve. Así la revisión queda anclada al proyecto real.

Errores frecuentes

Meter todo en Memory contamina otros proyectos. Convertir CLAUDE.md en un manual gigante oculta lo importante. Escribir reglas sin Hooks deja comprobaciones repetitivas en manos de la memoria humana. No limpiar reglas antiguas vuelve peligroso el sistema.

Proceso de adopción

1. Añade un CLAUDE.md corto a cada repositorio activo.
2. Incluye stack, comandos, archivos protegidos y verificación.
3. Mueve preferencias transversales a Memory.
4. Automatiza comprobaciones repetidas con Hooks.
5. Revisa reglas obsoletas cada dos semanas.

Resumen

Claude Code funciona mejor en varios proyectos cuando la memoria está separada. Los hechos del repositorio van a CLAUDE.md, las preferencias duraderas a Memory y las comprobaciones repetidas a Hooks. Un buen sistema de memoria no es el más largo, sino el que ayuda a actuar bien en el proyecto correcto.