El problema
Un equipo de ocho ingenieros adopta Claude Code. En dos semanas, cada desarrollador mantiene su propio CLAUDE.md local, nadie sabe qué hace cada comando y una nueva incorporación pasa su primer día completo preguntando "¿ya se intentó esto?" porque ninguna convención del equipo está registrada en un lugar donde el agente pueda leerla sistemáticamente. El problema no es Claude Code — es que el equipo trató la configuración como una preferencia personal en lugar de como infraestructura compartida.
Escalar Claude Code en un equipo no consiste en entregar la herramienta a cada individuo para que la configure a su manera. Consiste en definir las restricciones compartidas una sola vez, centralizadamente, en un nivel que el agente siempre procese.
El concepto central
CLAUDE.md cuenta con una jerarquía por diseño: distingue el ámbito de proyecto (versionado en git, compartido por todo el equipo) del ámbito de usuario (local, no versionado, específico de cada desarrollador). La decisión de arquitectura no es qué escribir en el archivo, sino qué pertenece a cada ámbito. Las convenciones del equipo — formato de commits, directorios que no deben modificarse sin revisión, comandos para ejecutar pruebas — pertenecen al ámbito de proyecto porque toda sesión de cualquier miembro debe cumplirlas. Las preferencias personales — si el ingeniero prefiere explicaciones concisas o detalladas — pertenecen al ámbito de usuario, ya que imponerlas a todo el equipo genera ruido operativo innecesario.
Las reglas específicas de ruta (path-specific rules) resuelven un problema que un único CLAUDE.md monolítico gestiona con dificultad: los proyectos grandes contienen subsistemas con estándares dispares. El directorio de infraestructura requiere políticas de revisión mucho más estrictas que el directorio de componentes de interfaz (UI). Un CLAUDE.md gigantesco intentando abarcar ambos genera ruido para los dos. Las reglas por ruta cargan el contexto únicamente cuando resulta relevante — quien modifica UI no carga directrices de infraestructura, y viceversa.
Los comandos personalizados y las Skills constituyen la segunda palanca de escalabilidad. Un comando de proyecto (.claude/commands/) estandariza procedimientos repetitivos — "revisar una migración de base de datos", "generar el changelog", "verificar si un PR está listo para revisión" — en flujos que cualquier miembro ejecuta de forma homogénea, sin redactar prompts desde cero. Esto asegura consistencia procedural en lugar de depender de la interpretación individual.
El tercer pilar es ejecutar Claude Code de forma no interactiva (headless), especialmente en entornos de CI. El modo -p/--print con --output-format json produce salidas estructuradas en JSON que otras herramientas pueden consumir — permitiendo que una canalización de CI invoque a Claude Code para evaluar un pull request y apruebe o bloquee cambios programáticamente. La salvaguarda arquitectónica esencial: las señales automáticas deben alimentar una revisión independiente (humana o mediante otra fase desacoplada) para casos críticos — jamás permitiendo que el mismo agente que generó el cambio sea el único juez que autorice su fusión.
Ponlo en práctica
En el laboratorio de esta lección construirás una función en Python para clasificar directrices en su ámbito correspondiente (proyecto, usuario o regla de ruta) y simularás el procesamiento de salidas estructuradas en JSON generadas por una revisión headless en CI.