La memoria que construimos para que Claude Code funcione de verdad en equipo

Llevábamos meses aprendiendo a trabajar con Claude Code de forma individual y el equipo había llegado, sin coordinarse, a las mismas conclusiones.El siguiente reto era de otro orden: construir un sistema con Claude Code para equipos que funcionara de forma consistente para toda la organización, sin que cada sesión empezara desde cero.

El momento en el que eso quedó claro fue cuando uno de los ingenieros pidió a Claude que revisara un módulo de autenticación: Claude generó código ejecutable que demostraba cómo explotar la vulnerabilidad en producción, sin que nadie se lo pidiera explícitamente. Esa tarde entendí que lo que el equipo necesitaba era infraestructura.

Lo que documentamos aquí es lo que construimos a partir de eso: la arquitectura del sistema, las decisiones que descartamos, y los dos problemas que todavía no tienen solución.

Claude no solo detectó la vulnerabilidad; también generó el script que la explotaba.

FELIPE POLO
CEO Orbitant

La memoria del equipo no cabe en un solo archivo

El primer CLAUDE.md que pusimos en el repositorio era razonable: convenciones de código, comandos habituales del proyecto, descripción de la arquitectura. Para uso individual funcionaba bien, pero cuando empezamos a trabajar varios ingenieros con Claude al mismo tiempo, el problema apareció rápido. El archivo crecía sin estructura, contenía instrucciones que solo aplicaban a ciertos contextos, y el mantenimiento recaía siempre en las mismas dos personas.

Lo que cambió el funcionamiento fue separar el sistema en tres capas con propósitos distintos:

• Personal (~/.claude/CLAUDE.md): Las preferencias de cada ingeniero a nivel individual. Idioma de respuesta, estilo de comunicación, atajos de workflow propios. No entra en el repositorio: vive en la máquina de cada persona y no es visible para el resto del equipo.
• Proyecto (CLAUDE.md en la raíz): Las convenciones que aplican a todo el equipo. Arquitectura, comandos del proyecto, reglas de seguridad, patrones que Claude debe seguir sin excepción. Este archivo se revisa en PR como cualquier otro código.
• Reglas condicionales (.claude/rules/*.md): Instrucciones que se activan solo cuando Claude trabaja en ciertos paths. Las reglas de validación de endpoints solo se cargan si Claude toca app/api/. Las convenciones de tests solo aplican cuando modifica archivos de test.

Las reglas condicionales resolvieron el problema de fondo: un CLAUDE.md que supera las 200 líneas empieza a ser menos fiable. Claude carga todos los archivos al inicio de cada sesión y los archivos largos diluyen el foco en lo que importa. Cuando el archivo crece demasiado, no es una señal de que hay que añadir más contexto en el mismo sitio, sino una señal de que hay que dividirlo.

El segundo aprendizaje costó más interiorizarlo: cuando Claude comete un error por falta de contexto, la corrección tiene que acabar documentada en el archivo correcto si aplica al equipo. Los ajustes que se hacen en conversación no persisten entre sesiones. Dos semanas después, el siguiente ingeniero que trabaje en ese módulo se encontrará con el mismo problema. Tenemos el comando /memory activo como parte del cierre de sesión precisamente para que este paso no se olvide.

Por qué construir un sistema con Claude Code para equipos cambia la lógica de las skills

Una skill es una capacidad reutilizable definida en un archivo de Markdown que Claude detecta y aplica automáticamente cuando reconoce el contexto. Lo que no aparece en la documentación oficial es el criterio para decidir cuándo merece la pena construir una.

Construir una skill requiere tiempo: diseñarla, probarla, mantenerla actualizada cuando el workflow cambia. Ese esfuerzo solo tiene sentido si el proceso que captura ocurre con suficiente frecuencia y consistencia. El coste en tokens es el criterio menos relevante de los tres que usamos:

1. ¿Es un proceso que se repite con frecuencia? Si ocurre una vez, no merece la pena invertir tiempo en hacerlo. Si ocurre varias veces a la semana con los mismos pasos, ya es candidato.
2. ¿Hay pasos donde la improvisación es costosa? Algunos workflows tienen puntos donde la variabilidad introduce riesgo real: el cierre de una rama de desarrollo, la apertura de un PR, una security review. Una skill convierte esos pasos en un protocolo que Claude sigue siempre de la misma manera.
3. ¿Genera contexto que de otro modo se pierde entre sesiones? Algunas skills no aceleran la ejecución sino que preservan el razonamiento. El valor está en no tener que reconstruirlo en la siguiente sesión ni explicárselo a quien no estuvo en la anterior.

De todas las que hemos construido, tres skills son las que más han cambiado cómo trabaja el equipo: la de systematic debugging, que obliga a Claude a reproducir el bug y formular hipótesis verificables antes de tocar código —sin ella, Claude tiende a hacer cambios a ciegas hasta que algo funciona—; la de verification before completion, que fuerza a ejecutar tests y typecheck antes de declarar una tarea terminada; y la de cierre de rama, que garantiza un orden narrativo en los commits y un PR abierto contra la rama correcta.

El security review del que hablaba al principio acabó siendo también una skill, por ser exactamente el tipo de proceso donde los pasos importan más que la velocidad: hay que reproducir el contexto correcto, revisar con el nivel de profundidad adecuado y documentar el resultado de una forma que sea útil para quien venga después.

Lo que el sistema todavía no resuelve

El sistema funciona. Y tiene dos puntos ciegos que llevamos meses intentando resolver sin éxito. Los mencionamos porque forman parte del cuadro completo: conocerlos antes de construir algo similar vale más que descubrirlos cuando el sistema ya está en marcha.

El contexto entre repositorios

El sistema de CLAUDE.md funciona bien cuando todo vive en el mismo repositorio. Nuestro stack no es así: tenemos servicios separados y Claude no tiene forma nativa de coordinar contexto entre repositorios distintos en una misma sesión. Cuando una tarea toca varios repos, el ingeniero tiene que gestionar ese contexto manualmente: abrir sesiones separadas, trasladar información entre ellas, mantener la coherencia a mano.

Hemos explorado varias alternativas. Todas añaden más fricción de la que eliminan, ya sea por la complejidad de configuración, por el coste en contexto, o simplemente porque la abstracción no encaja bien con cómo está estructurado el proyecto. Por ahora, el problema sigue abierto y lo gestionamos con disciplina manual más que con arquitectura.

La zona gris de la autonomía

Cuanto más configuras el sistema para que Claude actúe con autonomía, más importante se vuelve definir dónde acaba esa autonomía. Tenemos comandos auto-aprobados para operaciones de lectura y test —las que son seguras por definición— y una deny list explícita para operaciones destructivas. Pero entre esos dos extremos hay una zona intermedia: migraciones de base de datos, cambios en configuración de infraestructura, modificaciones de archivos de deployment.

En esa zona, la línea no es clara y cada ingeniero la traza de forma diferente según su experiencia y su tolerancia al riesgo. Eso genera inconsistencias que no hemos resuelto de forma sistemática. Lo más honesto que puedo decir es que la configuración de permisos en Claude Code ofrece las herramientas para definir esa línea, pero definirla bien requiere un acuerdo de equipo que aún estamos construyendo.

El retorno viene de conocer también los límites

Un sistema así no se construye en unas semanas. El que tenemos hoy es el resultado de meses de iteración: archivos CLAUDE.md que se rompieron y se rediseñaron, skills que se abandonaron porque no encajaban, workflows que funcionaban en local y fallaban en producción.

Lo que diferencia a un equipo que usa Claude Code de un equipo que trabaja con Claude Code es exactamente esto: tener un sistema donde los aprendizajes se acumulan en lugar de perderse. Donde cuando Claude comete un error, hay un lugar obvio donde guardar la corrección para que no se repita. Donde los límites son explícitos antes de encontrarlos en producción.

El siguiente reto que estamos explorando es cómo capturar aprendizajes entre proyectos distintos sin contaminar el contexto de cada uno. Todavía no tenemos respuesta. Pero haber identificado con precisión dónde está la pregunta ya es parte del trabajo.

Preguntas frecuentes

¿Por dónde se empieza si el equipo nunca ha estructurado sus CLAUDE.md?
Con el comando /init en el repositorio. Claude analiza el código existente y genera un CLAUDE.md inicial con las convenciones que detecta. No es el sistema definitivo, pero es un punto de partida honesto que evita empezar con un archivo vacío o, peor, con uno importado de otro proyecto sin adaptar.

¿Cuánto tiempo tarda en estabilizarse un sistema así?
En nuestra experiencia, los primeros tres meses son de mucha iteración. El sistema empieza a estabilizarse cuando los ingenieros corrigen a Claude y esa corrección acaba documentada de forma natural, sin que nadie lo pida. Cuando eso ocurre de forma habitual, el sistema está funcionando.