Compartir el CLAUDE.md del equipo entre proyectos con un paquete Composer y @import

Hola, bienvenido. Con esta lección empieza el bloque opcional del paquete Composer de convenciones. Vamos a crear el paquete cursosdesarrolloweb/conventions con la guideline del equipo y sus 3 primeros documentos de convención, a instalarlo en helpdesk desde Sail y a importarlo en la primera línea de CLAUDE.md. Así, lo que dice cómo es el código del equipo se escribe en un solo sitio y llega igual a todos los repos.

Si tu equipo no comparte convenciones de código entre proyectos, porque solo tiene uno o porque cada proyecto sigue las suyas, puedes saltarte este bloque entero. Los bloques que vienen después funcionan igual con el paquete y sin él. Y si te saltaste el bloque de QA, guardia y subagentes, puedes seguir aquí sin problema. Cuando una lección de este bloque modifique un archivo del plugin que cambió el bloque que no hiciste, copia el archivo completo en vez de aplicar el diff. Del CHANGELOG.md, copia solo la entrada nueva.

En la primera lección repartimos la configuración del equipo en 3 sitios, y dijimos que el paquete Composer contiene cómo es el código. Hasta ahora no lo hemos necesitado, porque el plugin team solo lleva cómo se trabaja. Pero las convenciones de código también se copiaron de repo en repo. Cuando Marta compara los .ai/docs/ de sus repos, 9 de los 15 documentos son distintos en al menos un repo. Y en uno de ellos alguien cambió la guideline del proyecto, .ai/guidelines/project.md, y no volvió a compilar CLAUDE.md con Boost, así que Claude siguió leyendo la versión anterior.

El paquete resuelve las 2 cosas. Los documentos viven en el paquete y llegan a cada repo con composer update, con su versión apuntada en composer.lock. Y la guideline que resume las convenciones no se compila: CLAUDE.md la importa desde vendor/ con una sola línea, así que lo que lee Claude es siempre lo que trae la versión instalada del paquete.

El paquete es un repo más en team/, junto a claude-plugins y helpdesk. Al terminar esta lección va a tener esto:

resources/guidelines/conventions.md es lo que va a importar CLAUDE.md. resources/docs/ guarda los documentos de convención, que Claude lee cuando va a crear una pieza. Y resources/rules/ guarda las rules que remiten a esos documentos, listas para copiarlas a cada repo.

El paquete se instala en require y no en require-dev. En esta lección solo lleva texto, pero en la siguiente llevará código que el proyecto necesita para funcionar, y lo que está en require-dev no se instala en producción con composer install --no-dev. Las herramientas de QA (Pint, Larastan, Rector y Pest) siguen en el require-dev de cada proyecto, como hasta ahora.

Es un repo nuevo, así que le vamos a abrir su pestaña. Como la carpeta conventions todavía no existe, la abrimos en ~/code/team. Desde cualquier pestaña de la sesión:

En la pestaña nueva, reescribimos el layout con todas las pestañas, la de conventions ya con la carpeta del repo, que vamos a crear enseguida y en la que se va a quedar:

Y en la misma pestaña, vamos a crear las carpetas:

Vamos a empezar por el manifiesto del paquete, conventions/composer.json:

El nombre, cursosdesarrolloweb/conventions, es el que pondrá cada repo en su require, y debes cambiar cursosdesarrolloweb por tu usuario o tu organización, igual que en el namespace. license es proprietary, que es lo que la documentación de Composer indica para el código que no es de código abierto.

Con version nos apartamos de lo habitual. La documentación de Composer recomienda no escribirla cuando se puede deducir de los tags del repo, y en un paquete público es lo normal. Nosotros la vamos a escribir siempre, por 2 motivos. El primero es que el repositorio path que vamos a usar enseguida la necesita: sin ella, Composer ve la rama como dev-main y composer require no encuentra ninguna versión que cumpla ^1.0. El segundo es que el tag de cada versión lo vamos a crear a partir de este campo, así que siempre coinciden.

extra.laravel.providers registra el service provider con el package discovery de Laravel, así que ningún repo tiene que añadirlo a mano. Vamos a crear el provider vacío, en conventions/src/ConventionsServiceProvider.php:

De momento no hace nada. Más adelante registrará el comando que instala el paquete en un repo, y lo creamos ya para que Laravel lo descubra desde la primera versión.