Claude Code en equipo, cómo mantener vivo CLAUDE.md sin que se convierta en un cubo de basura

En solitario con Claude Code todo va fluido. Tienes tu CLAUDE.md, conoces cada hook, sabes exactamente por qué el slash command /deploy está montado así. Entonces entra el primer compañero al repo, clona, abre Claude Code, y de repente el output es distinto. Las respuestas se leen diferente, las convenciones de code style se ignoran, el slash command /deploy genera una rama que nadie esperaba.

Eso no es que Claude Code esté roto. Es falta de higiene de equipo. CLAUDE.md, hooks y slash commands son precisamente los sitios donde los workflows solitarios se caen en cuanto hay más de una persona implicada. Este playbook trae 10 pasos para compartir todo eso limpio, sin que nadie haga commit por error de sus notas privadas y sin que una persona doble en silencio la config compartida.

Asumo que usas Git y tienes un flujo con GitHub o GitLab. Quien todavía no esté familiarizado con Git para IA, que mire antes el mini-módulo L1-08 a L1-10.

Paso 1, separa los dos CLAUDE.md, compartido y privado

Primera regla. Hay dos sitios para CLAUDE.md y cada uno tiene su trabajo distinto. El CLAUDE.md compartido vive en la raíz del repo y se comitea. El CLAUDE.md privado vive en ~/.claude/CLAUDE.md en tu máquina y nunca se comitea.

El archivo compartido contiene todo lo que aplica al equipo. Stack técnico, code style, convenciones de ramas, comandos de test, rutas de deploy. El archivo privado contiene tus preferencias personales. Que en pair coding te gustan más explicaciones, que en tu máquina usas pnpm en lugar de npm, que el modo claude --print no te convence.

Si mezclas eso, viene el caos. Una persona encuentra "escribe siempre comentarios en inglés" en el CLAUDE.md del repo, otra jamás lo habría escrito así. Separar, ya y con consistencia.

Paso 2, mantén corto el CLAUDE.md del repo

La tentación es grande de que cada uno meta su nota favorita. Tras tres semanas el archivo tiene 800 líneas, nadie lo lee, Claude Code lo carga igual en cada contexto. Eso es desperdicio de tokens y drift garantizado.

Mantén el CLAUDE.md del repo por debajo de 200 líneas. Lo que no quepa va a docs/claude/, una estructura de documentación propia que Claude lee cuando hace falta. El CLAUDE.md del repo entonces apunta a esos archivos por ruta en vez de duplicar contenido. Ahorra tokens y deja clara la fuente de la verdad.

Regla del pulgar. Si no has leído el CLAUDE.md del repo de principio a fin en 5 minutos, es demasiado largo.

Paso 3, secciones con responsables

Estructura el CLAUDE.md del repo en secciones, y escribe detrás de cada sección quién la mantiene. Ejemplo.

## Stack técnico (owner: todos)
- Next.js 16, Prisma 7, Postgres
- Pnpm para package management
- Vitest para tests

## Workflow de deploy (owner: Anna)
- main hace deploy automático a Vercel
- staging vía `pnpm deploy:staging`

## Migraciones de base de datos (owner: Tim)
- SIEMPRE `prisma migrate dev --name <slug>` en local
- NUNCA `db push --force-reset` en CI

Si algo está en el CLAUDE.md del repo sin owner, nadie lo actualizará tras tres semanas. Con owner, una persona entra, revisa, hace un PR. Mismo principio que cualquier otra doc.

Paso 4, mete el directorio .claude en el repo

Claude Code deja skills, slash commands y hooks específicos del proyecto bajo .claude/ en el repo. Eso va a Git. Lo que no va son los logs personalizados y los cachés, así que necesitas una entrada en .gitignore.

# .gitignore
.claude/cache/
.claude/sessions/
.claude/local-settings.json

Lo que se comitea es .claude/skills/, .claude/commands/ y .claude/hooks/. Más un .claude/README.md que explica brevemente qué hay en el directorio y quién lo mantiene.

Si tu equipo no separa esto, cada uno tiene logs distintos en Git y los pull requests se convierten en un infierno de conflictos. Mejor montarlo limpio ahora que migrar después.

Paso 5, una persona es skill owner por proyecto

Las skills son add-ons tipo capacidad que Claude usa en un proyecto. En un proyecto solitario cada uno escribe las suyas. En un proyecto de equipo UNA persona TIENE que llevarlas. Si no, cada uno tiene su variante de "skill de code review" y el output deja de ser reproducible.

Búscate o elegid a una persona como skill owner. Esa persona mergea las nuevas skills, revisa conflictos y quita las obsoletas. Los demás pueden proponer, hacer drafts, pero el merge pasa por la única persona. Suena burocrático, pero es exactamente lo que vas a agradecer tras tres semanas de drift.

Paso 6, versiona los slash commands como código

Los slash commands son atajos pequeños como /deploy o /review-pr. Si Tim cambia /deploy por la mañana porque tiene un edge case y tú deployas por la tarde, eso puede salir mal. Los slash commands son código, trátalos como código.

Tres reglas. Primera, cada cambio en un slash command va por pull request, no directo a main. Segunda, en el mensaje del commit pones QUÉ cambió, no solo "update deploy". Tercera, en el CLAUDE.md del repo hay una sección que explica brevemente qué hace cada slash command compartido.

Si un slash command solo tiene sentido para una persona, va al directorio privado ~/.claude/commands/, no al repo.

Paso 7, separa los hooks que cuestan dinero

Los hooks pueden hacer llamadas API, así que pueden costar dinero. Si alguien monta un hook que llama a Claude Haiku en cada tool use y eso corre sin avisar para los 5 miembros del equipo todo el día, pueden ser unos cientos de euros al mes.

Marca en .claude/hooks/README.md qué hooks cuestan dinero y cuáles no. Los que cuestan dinero deberían ser opt-in, solo quien los activa los corre. Activar hooks costosos por defecto en el repo es una pequeña dictadura.

Regla del pulgar. Por cada hook nuevo, una estimación "cuesta unos X céntimos por 100 llamadas" en el comentario. Ahorra después la pregunta incómoda "¿por qué la factura de Anthropic está en 400 euros este mes?".

Paso 8, los pull requests a CLAUDE.md necesitan review

Suena obvio, no lo es. Muchos equipos comitean directo a main cuando "solo cambia la nota para Claude". Eso provoca drift porque nadie ve el cambio.

Pon la regla. CLAUDE.md, .claude/skills/, .claude/commands/ y .claude/hooks/ necesitan code review como cualquier código normal. En el comentario del review, explica brevemente por qué hizo falta el cambio. Si el reviewer no entiende por qué llega un cambio en una skill, eso es señal de que el cambio probablemente no es consenso de equipo.

Bonus. En cambios al CLAUDE.md puedes adicionalmente revisar si el archivo sigue por debajo de las 200 líneas (ver paso 2). Si no, vuelve el efecto basurero.

Paso 9, limpieza trimestral en equipo

Cada tres meses hacéis una hora de "día de limpieza de CLAUDE.md". Juntos en pantalla, una llamada de Zoom, scrolleáis por todo lo que se ha acumulado en config de Claude. Qué se sigue usando, qué está obsoleto, qué puede irse.

Mi ritmo es mediados de enero, mediados de abril, mediados de julio, mediados de octubre. Suena poco, basta. Lo que pasa entre limpiezas se atrapa en los pull requests. Lo que se te va de la cabeza entre mayo y julio, lo atrapa el día de limpieza.

Procedimiento concreto. Tres columnas en una pizarra. Mantener, cambiar, borrar. Por skill, por slash command, por hook una tarjeta, todos votan, al final una persona mueve las tarjetas a los montones. Borráis en un único pull request, no en cinco sueltos.

Paso 10, documentación de onboarding para nuevos miembros

Si Lisa entra al equipo el lunes, no debería tener que rebuscar antes en 200 líneas de CLAUDE.md. Escribid una doc de onboarding de 30 minutos en docs/claude/onboarding.md. Qué tiene que instalar Lisa en local, qué variante de Claude Code (Pro o API), qué hooks debería activar, cuáles costosos mejor no, qué skills son obligatorias y cuáles opcionales.

Más un smoke test. Al final del onboarding, Lisa hace una tarea como "describe qué pasa en src/lib/auth.ts con la ayuda de Claude Code". Si el output se ve como el estándar del equipo, está montada. Si no, falta algo en su config local y lo arregláis ahora en vez de dentro de dos semanas cuando ya esté frustrada.

Quien no escribe el onboarding obliga a cada compañero nuevo a buscar el mismo camino por sí solo, y cada uno de esos caminos tiene una solución distinta. Ese es el nacimiento del drift.

Qué viene después

Si has terminado esto, tu setup de equipo es sólido. El siguiente paso sensato es el playbook "Tus propios slash commands para Claude Code", donde aprendes a construir limpio el siguiente slash command compartido. Si todavía no tenéis hooks comiteados, "Hooks contra alucinaciones" merece la pena como segundo paso. Y si estás pensando en actualizar a Claude Code 2.x mientras el equipo sigue en 1.9, mira el playbook "Estrategia de update para Claude Code" antes de que alguien tenga un workflow roto el lunes por la mañana.