Un archivo CLAUDE.md parece, a primera vista, una pieza menor de infraestructura: un lugar donde se anotan preferencias y convenciones del repositorio para que Claude Code multi-agent architecture CLAUDE.md no tropiece con las mismas piedras cada vez.
Esa lectura se queda corta cuando el sistema crece.
En una arquitectura multi-agente, CLAUDE.md es el único documento que todos los agentes leen en cada sesión. Según estadísticas de adopción de Claude Code 2026, el 71% de los desarrolladores que usan agentes regularmente usa Claude Code como herramienta principal — lo que convierte al contrato operativo del repo en una pieza de infraestructura crítica, no documentación opcional.
En una arquitectura multiagente, CLAUDE.md deja de ser "el prompt del repo" y empieza a comportarse como un contrato organizacional. No solo dice qué estilo de código preferimos. Define quién puede hacer qué, qué contexto debe cargar cada rol, qué memoria puede tocar, cuándo debe escalar y cómo se coordinan los agentes entre sí.
La tesis es simple: en una arquitectura de agentes Claude Code con múltiples roles, CLAUDE.md debe leerse como un organigrama ejecutable. Claude Code escribe hoy el 4 por ciento de todos los commits públicos en GitHub — con un volumen de commits diarios que creció 3 veces en 8 semanas previas a mayo de 2026. — con un volumen de commits diarios que creció aproximadamente 200 por ciento en las 8 semanas previas a mayo de 2026, según estadísticas de adopción de Claude Code. A esa escala, el contrato operativo de un repo pasa de ser documentación a ser infraestructura. No es documentación pasiva. Es una interfaz de gobierno.
CLAUDE.md en una arquitectura multi-agente real
Cuando empecé a usar Claude Code con arquitectura multi-agente, el primer problema que apareció no fue técnico: fue de gobierno. Con un agente, las reglas implícitas alcanzan. Con quince roles distintos trabajando sobre el mismo codebase, las reglas implícitas producen conflictos.
El más común: dos agentes con instrucciones distintas que llegan a la misma área del código y toman decisiones incompatibles. Un executor que arregla un bug y un reviewer que lo revierte porque violó una convención que el executor no tenía documentada. Un agente de CI que actúa sobre un archivo que el coding agent acaba de modificar sin ningún mecanismo de coordinación.
CLAUDE.md resuelve eso cuando está bien diseñado. No resuelve todos los casos de concurrencia, pero elimina la clase de conflicto más común: el que ocurre porque dos agentes no comparten el mismo modelo mental de qué está permitido.
El mercado ya cambió — y el problema con él
La pregunta dejó de ser si los desarrolladores van a usar IA para programar. En la encuesta de Stack Overflow 2025, el 84% dijo que ya usaba o planeaba usar herramientas de IA en su proceso de desarrollo, y el 28.1% declaraba uso de multi-agent orchestration.
Con un solo agente, muchas decisiones pueden quedar implícitas. Con quince roles distintos en producción — y 73 por ciento de los equipos de ingeniería usando herramientas de IA a diario — el prompt tradicional no alcanza. En proyectos sin un CLAUDE.md bien definido, los conflictos entre agentes suelen descubrirse a los 3 días de operación — lo que puede costar entre 2 y 5 veces el tiempo original de la tarea para limpiar el estado. Con quince roles — agentes que investigan, implementan, revisan, corrigen CI, escriben documentación, preparan releases, mantienen memoria, ejecutan tareas programadas y coordinan — el prompt tradicional no alcanza. Hoy el 84% de equipos de ingeniería usa herramientas de IA diariamente (Stack Overflow 2025), y el 28.1% declara usar orquestación multi-agente. Con quince roles — agentes que investigan, implementan, revisan, corrigen CI, escriben documentación, preparan releases, mantienen memoria, ejecutan tareas programadas y coordinan — el prompt tradicional no alcanza.
Un prompt describe comportamiento esperado. Un contrato define autoridad.
CLAUDE.md como organigrama
| Elemento del contrato | Formato | Dónde vive |
|---|---|---|
| Responsabilidades por rol | Lista de agentes y alcance | CLAUDE.md raíz |
| Archivos sensibles | Paths prohibidos por agente | CLAUDE.md raíz |
| Criterios de escalación | Condiciones con acción clara | CLAUDE.md raíz |
| Contexto especializado | Reglas de módulo o producto | Archivos bajo demanda |
| Memoria durable | Scoped por proyecto/repo | DB (no en CLAUDE.md) |
Un organigrama no solo muestra nombres y cargos. Muestra relaciones de autoridad, responsabilidad y escalación. CLAUDE.md puede cumplir la misma función:
- Qué tipos de agentes existen y qué responsabilidades pertenecen a cada rol
- Qué contexto se carga de forma automática vs. bajo demanda
- Qué cambios requieren confirmación humana o escalación a un rol superior
- Qué tareas pueden ejecutarse en paralelo
- Qué memoria puede leer o escribir cada agente
Alcance y control de blast radius
No todos los archivos tienen el mismo peso. Modificar un componente visual no equivale a modificar autenticación. Un buen CLAUDE.md marca zonas de riesgo con reglas como:
- No modificar archivos de autenticación sin instrucción explícita
- No borrar contenido de directorios críticos
- Preferir editar archivos existentes antes de crear nuevos
- No tocar lockfiles salvo que la tarea lo requiera
- No hacer refactors laterales durante una corrección puntual
En una arquitectura con múltiples roles, el alcance también puede ser dinámico: un executor tiene permiso para editar un conjunto de archivos asignado por el chief; un reviewer puede leer todo pero no modificar nada.
Para el diseño de la personalidad y roles consistentes que viven dentro de esos límites, el artículo sobre consistencia de personalidad en agentes IA es la continuación natural. Y la disciplina de diseño de tareas para agentes define cómo los briefs deben respetar el contrato del CLAUDE.md.
Escalación: cuándo no decidir
Un agente competente no es el que decide todo. Es el que reconoce cuándo una decisión excede su mandato. Algunos umbrales de escalación claros:
- Si una tarea requiere cambiar autenticación → escalar
- Si una solución implica borrar archivos → escalar
- Si hay conflicto entre instrucciones del sistema y pedido del usuario → detenerse y pedir claridad
- Si la corrección local exige rediseñar un paquete compartido → escalar
- Si dos agentes necesitan editar la misma superficie → coordinar antes de escribir
La escalación no siempre significa preguntar al humano. En un sistema de roles, puede significar pasar de executor a chief. Lo importante es que la ruta exista antes del incidente.
Context loading: cargar menos, cargar mejor
Tres reglas de tamaño para un CLAUDE.md efectivo:
- Marco de gobierno: quién puede hacer qué, qué archivos son sensibles, cuándo escalar — permanece en CLAUDE.md.
- Contexto especializado: detalles de módulos específicos, estrategia editorial, arquitectura interna — vive en archivos separados que se cargan bajo demanda.
- Límite práctico: cuando CLAUDE.md supera ~150 líneas, empezá a mover contexto especializado afuera. Un documento que nadie lee completo no es un contrato; es documentación muerta.
La tentación natural es meter todo en CLAUDE.md. Eso convierte el contrato en una enciclopedia frágil.
Un contrato útil debería ser jerárquico. CLAUDE.md define el marco estable y apunta a:
- Souls para identidad de roles
- Skills para flujos repetibles
- Contextos para áreas del sistema
- Scripts para operaciones verificables
Este diseño permite cargar lo necesario sin saturar cada tarea. Un agente de CI no necesita leer toda la estrategia editorial del blog. Un docs-writer no necesita cargar detalles de auth.
En la práctica, esto significa que CLAUDE.md tiene un tamaño óptimo: suficiente para definir el marco de gobierno, no tanto como para convertirse en un documento que nadie lee completo. Cuando CLAUDE.md supera cierto tamaño, es señal de que parte del contenido debería vivir en archivos de contexto especializados que se cargan bajo demanda.
El contrato como defensa contra la deriva
Todo sistema de agentes deriva. Deriva el estilo de respuesta, la interpretación de reglas, el alcance de los cambios, la memoria. CLAUDE.md ofrece un punto de retorno.
Esto es especialmente importante en proyectos que empiezan como scripts y terminan como infraestructura. Sin contrato, la ausencia de gobierno se siente como deuda organizacional.
Llamar a esto prompt engineering es reducir demasiado el problema. La función de CLAUDE.md se parece más a diseño organizacional, control de permisos y arquitectura operativa.
Los sistemas autónomos no se vuelven confiables solamente por mejorar el modelo. Se vuelven confiables cuando el entorno alrededor del modelo mejora sus contratos.
Preguntas frecuentes
¿Qué significa usar CLAUDE.md como contrato para agentes? Significa tratar CLAUDE.md como una regla operativa del sistema. Ahí definís qué puede hacer cada agente, qué contexto debe cargar, cuándo debe escalar y qué límites no puede cruzar.
¿Por qué un prompt tradicional no alcanza en una arquitectura multiagente? Un prompt describe comportamiento esperado, pero no define autoridad, permisos o coordinación. Con varios roles trabajando en paralelo, necesitás reglas explícitas.
¿Qué tipo de decisiones debería documentar CLAUDE.md? Permisos de edición, archivos sensibles, criterios de escalamiento, comandos de prueba y convenciones del repositorio.
¿Cómo ayuda CLAUDE.md a reducir riesgos en equipos que usan Claude Code? Convierte decisiones implícitas en límites claros antes de que el agente actúe, reduciendo refactors innecesarios y cambios peligrosos en archivos críticos.
¿Cuándo conviene actualizar CLAUDE.md? Cada vez que cambian las responsabilidades de los agentes, la arquitectura del repositorio o las reglas de seguridad. Si repetís la misma corrección en varias tareas, esa regla debería vivir en CLAUDE.md.