Claude Code para equipos: por qué copiar .claude de repo en repo no basta

Hola, bienvenido. En esta primera lección no vamos a crear nada todavía: vamos a ver qué le pasa a un equipo que copia su .claude/ de repo en repo, qué formas hay de compartir esa configuración y cuál de ellas sigue este curso. Cómo se crea el plugin lo veremos en la lección 5. En esta vamos a decidir dónde vive cada pieza de la configuración, y esa decisión es la que aplicaremos en todas las lecciones del curso.

Copiar la configuración de Claude Code de un repo a otro funciona el primer mes. Después cada copia evoluciona por su cuenta, nadie sabe cuál es la buena y propagar una mejora a mano es un trabajo que no hace nadie. La solución que vamos a construir reparte esa configuración en 3 sitios, cada uno versionado con git: un plugin de Claude Code para cómo se trabaja, un paquete Composer para cómo es el código y el propio repo para lo que solo es de ese proyecto.

Empecemos por el problema. El equipo de Marta son 3 personas: ella, que es la tech lead; Jorge, senior; y Aitor, que es junior y se incorporó hace unos meses. Configuraron su primer proyecto con Sail, composer qa, permisos, skills, hooks, subagentes y arch tests y, como salió bien, lo copiaron en el segundo, en el tercero y así hasta tener 6 repos con el mismo .claude/ de partida. Un día Marta decide comparar las 6 copias y se encuentra con esto. La skill de QA de un proyecto lleva la key de Sonar de otro, porque alguien copió la carpeta sin cambiarla. El deny que bloquea migrate:fresh no bloquea nada, porque está escrito con ./vendor/bin/sail y Claude escribe el comando sin ./. Un repo tiene 12 arch tests y otro 19, porque los 7 que faltan se añadieron después de la copia. La convención de no poner traits en los modelos existe solo en la memoria personal de Jorge y en la de Aitor, que la aprendieron por separado a base de revisiones, y en ningún documento. Y la forma de trabajar con spec, plan y tareas solo la sigue igual una persona, Marta, porque el resto nunca la vio escrita. Ninguna de las 6 copias es igual a otra, y ninguna es la buena.

Fíjate en que aquí nadie ha hecho nada mal. Cuando una configuración se reparte copiando, la fuente desaparece en el momento en que hay 2 copias, y a partir de ahí la única forma de volver a juntarlas es hacerlo a mano, archivo por archivo, en cada repo. Marta hizo la cuenta: propagar una mejora pequeña, como añadir un arch test, eran 8 pasos por repo, con su commit y su pull request. Nadie llegó a hacerlos.

Si trabajas solo, este curso también es para ti. Aunque hoy no compartas tu configuración con nadie, aquí vas a aprender a tratarla como arquitectura: qué va a un plugin, qué a un paquete y qué se queda en cada repo, y cómo se versiona y se publica. Es lo que necesitarás en cuanto tengas varios proyectos o te toque liderar un equipo. Este curso empieza justo ahí, cuando la forma de trabajar que te dejó el curso Setup Profesional Laravel + IA para 2026↗ (se abre en una pestaña nueva) hay que compartirla y mantenerla al día en varios repos a la vez.

Hay 5 formas de que varios repos compartan la configuración de Claude Code, y para elegir entre ellas conviene mirar 3 cosas: qué puede llevar cada una, cómo llega un cambio a los demás repos y cómo se vuelve atrás cuando el cambio sale mal.

Versionar .claude/ en cada repo es lo que hace el equipo de Marta, y ya hemos visto cómo termina. Los symlinks sirven para una máquina, pero no viajan con el repo. Además, Claude Code trata un symlink cuyo destino está fuera del directorio de trabajo como un import externo: no se carga hasta que apruebas los imports externos del proyecto y, aun así, solo se cargan las rules que no llevan paths:, que son justo las que no queremos cargar siempre. El submódulo lleva de todo, pero cada repo apunta a un SHA, actualizarlo es un paso que se olvida y Claude Code no sabe nada de él: ni versión, ni comprobación, ni forma de decirte que te has quedado atrás.

Las 2 últimas son las que tienen versión de verdad, y por eso son las que usa el curso. Fíjate en que no compiten, porque llevan cosas distintas. El paquete Composer lleva lo que el código necesita o lo que es una convención con su test, y llega por Composer, que es una herramienta que el equipo ya usa a diario. El plugin lleva lo que Claude Code ejecuta en su ciclo, y llega por el propio Claude Code, con su versión y su marketplace. Si no tienes claro qué es un plugin o cómo se instala uno de terceros, lo tienes en la lección Plugins de Claude Code: cómo instalarlos con criterio↗ (se abre en una pestaña nueva) del curso de Claude Code; aquí vamos a crear el nuestro.