La mayoría de la orientación de CLAUDE.md está escrita para desarrolladores individuales que trabajan en un proyecto a la vez. El trabajo de agencia es diferente: tienes una cartera de proyectos de clientes, cada uno con sus propias convenciones, y el mismo ingeniero podría tocar seis de ellos en una semana. La estrategia de CLAUDE.md que funciona para un desarrollador individual falla a escala de agencia. Este es el enfoque de funcionamiento que hemos establecido en Seahawk Media después de 18 meses de iteración en más de 200 repositorios activos de clientes.
Idea clave: CLAUDE.md a escala de agencia necesita tres capas — estándares a nivel de agencia, sobrescrituras por cliente y notas por engagement — para que un ingeniero pueda moverse entre seis repositorios con el contexto correcto.CLAUDE.md at agency scale needs three layers, agency-wide standards, client overrides, and per-engagement notes, so one engineer can move across six repos with the right context.
Si estás ejecutando una agencia que usa Claude Code diariamente y descubres que los ingenieros obtienen resultados muy diferentes en proyectos, este artículo es la solución estructural.
Por qué el consejo de CLAUDE.md para desarrolladores individuales falla a escala de agencia
El consejo estándar de CLAUDE.md es: escríbelo una vez, optimízalo para tu proyecto, mantenlo bajo 500 líneas. Eso funciona cuando tienes un proyecto. Cuando tienes 50 repositorios de clientes, surgen tres problemas. El mismo ingeniero no puede recordar qué convenciones aplican a qué cliente. Los ingenieros nuevos que se incorporan a un proyecto enfrentan cincuenta archivos CLAUDE.md diferentes. El contenido de CLAUDE.md se desvía conforme los ingenieros actualizan un proyecto y olvidan los otros.
Resolver esto a escala de agencia requiere un enfoque estratificado: estándares de agencia en un lugar, sobrescrituras específicas del cliente en otro, y contexto por proyecto en un tercero. Las capas se apilan en lugar de duplicarse.
El modelo de tres capas CLAUDE.md
Capa 1: estándares de toda la agencia
Un único archivo CLAUDE.md vive en un repositorio privado de GitHub de nuestra agencia. Cubre: estilo de código en los lenguajes que entregamos, nuestros patrones prohibidos, nuestras convenciones de testing, nuestros estándares de seguridad, nuestra regla editorial de ortografía británica, nuestros defaults de deployment. Este archivo tiene aproximadamente 400 líneas y cambia algunas veces al año.
Cada nuevo proyecto de cliente comienza symlinkeando o copiando este archivo. Los cambios en el archivo de toda la agencia se incorporan a los proyectos en una cadencia de revisión trimestral. Los ingenieros pueden confiar en que estas convenciones sean idénticas sin importar qué proyecto abran.
Capa 2: CLAUDE.md específico del cliente
Cada repositorio de cliente tiene su propio CLAUDE.md que importa el de toda la agencia y añade especificidades del cliente: su stack, su hosting, sus plugins, sus convenciones de equipo, su voz editorial, sus plugins prohibidos. Este archivo típicamente tiene entre 100 y 200 líneas y cambia cuando la forma del engagement del cliente cambia.
Usamos una directiva de inclusión simple al inicio: "## Agency standards" con un enlace al archivo de toda la agencia, luego "## Client-specific" con los overrides. Claude lee ambos porque están en el árbol del proyecto.
Capa 3: notas por engagement
Contexto específico con límite de tiempo: el objetivo del sprint actual, los hallazgos de discovery activos, el registro de decisiones recientes, la lista de preguntas abiertas. Vive en CLAUDE_NOTES.md o similar, actualizado semanalmente durante el engagement, archivado al cierre del engagement.
Aquí es donde la mayoría de agencias fallan en la higiene de CLAUDE.md. Las primeras dos capas se mantienen limpias; la tercera se desvía y envejece. Resolvemos esto con una cadencia de revisión del viernes por la tarde: cada ingeniero revisa su CLAUDE_NOTES.md activo y o lo actualiza o lo archiva.
La lista de patrones prohibidos que se acumula
El elemento de mayor apalancamiento único de nuestro CLAUDE.md a nivel de agencia es la lista de patrones prohibidos. Veinte entradas, actualizadas trimestralmente. Ejemplos de la lista actual:
Nunca uses eval() en ningún lenguaje que enviemos.
Nunca uses query_posts() en WordPress (usa WP_Query en su lugar).WordPress (use WP_Query instead).
Nunca uses any en TypeScript sin un comentario explícito "// suppressed: <reason>".
Nunca uses document.write() en ningún contexto.
Nunca hagas commit de secretos a git, jamás, independientemente de la rama.
Nunca uses guiones largos en ninguna copia dirigida al cliente (estándar de operación para evitar detección de IA).
Nunca desactives RLS en tablas de Supabase para arreglar un bug.Supabase tables to fix a bug.
Nunca hagas push directamente a main (siempre PR).
Nunca crees un archivo nuevo cuando uno existente puede ser editado.
La lista se amplía porque cada vez que un ingeniero incumple una de estas reglas, añadimos la regla. Claude lee la lista de patrones prohibidos en cada sesión y se niega a generar código que los viole. La clase de bugs que solíamos enviar a staging desapareció.
Qué mantener fuera de CLAUDE.md
Cinco cosas que explícitamente no incluimos en los archivos CLAUDE.md de agencia:
Actualizaciones del estado del proyecto. Se vuelven obsoletas; pertenecen a Linear o Notion.
Fundamentación arquitectónica larga. Pertenece a documentos de diseño; CLAUDE.md debe referenciarla, no duplicarla.
Secretos del lado del cliente, credenciales o cualquier cosa sensible. Incluso los archivos CLAUDE.md privados son demasiado propensos a filtraciones.
Preferencias personales de ingenieros individuales. Los estándares deben ser de toda la agencia; las preferencias específicas del ingeniero pertenecen a su propio .claude/settings.json.
Texto de marketing o lenguaje de ventas. CLAUDE.md es contexto de ingeniería; debe leerse como si lo escribiera un ingeniero senior para otros ingenieros.
Cómo CLAUDE.md cambia la ecuación de contratación
Un ingeniero senior que puede entregar trabajo en todo el portafolio de clientes sin re-aprender cada proyecto en cada visita es dramáticamente más valioso que uno que no puede. El sistema de tres capas CLAUDE.md es lo que hace eso posible. El tiempo de onboarding para nuevos ingenieros cayó de aproximadamente 2 semanas de rampa específica del proyecto a 3 días porque las convenciones están codificadas en lugar de ser tribales.
Mismo ingeniero, más output, menos costo de onboarding, menos overhead de cambio de contexto. El pipeline de contratación envió menos ingenieros junior y más senior una vez que tuvimos este sistema en place porque los ingenieros junior ya no eran necesarios para absorber el contexto específico del proyecto que había sido la única forma en que las convenciones se transferían previamente.
Bottom line
CLAUDE.md a escala de agencia es un sistema de capas: estándares de toda la agencia como base, overrides específicos del cliente en el medio, notas por engagement en la parte superior. La lista de patrones prohibidos es la sección de mayor apalancamiento. Evita contenido obsoleto en la capa por engagement con una cadencia de revisión del viernes.
Implementa el modelo de tres capas y tus ingenieros dejarán de entregar output inconsistente en todo el portafolio. Sáltate esto y estás pagando por asistencia de IA que produce trabajo diferente dependiendo de cuál proyecto el ingeniero haya abierto de último.
Preguntas frecuentes
¿Qué es un archivo CLAUDE.md?
CLAUDE.md es un archivo de proyecto que le indica a Claude Code tus estándares, stack y convenciones para que su output se ajuste a tu base de código. A escala de agencia, un archivo plano por proyecto no es suficiente, por eso esto usa un modelo de tres capas en muchos repositorios de clientes.
¿Cómo escalas CLAUDE.md en muchos proyectos de clientes?
Con un modelo de tres capas: estándares de toda la agencia que se aplican en todas partes, sobrescrituras específicas del cliente por cuenta, y notas por engagement para un proyecto dado. El mismo ingeniero puede moverse entre seis repositorios de clientes en una semana y tener el contexto correcto en cada uno sin reescribirlo.
¿Qué no debería ir en CLAUDE.md?
Secretos, cualquier cosa que cambie constantemente, y ruido que diluya las reglas importantes. Mantenlo en estándares y convenciones duraderos. Un CLAUDE.md saturado se ignora; uno ajustado y estructurado en capas que establece claramente los patrones prohibidos es lo que realmente cambia el output.
¿CLAUDE.md cambia cómo contratas?
Reduce el costo de onboarding. Cuando los estándares viven en un CLAUDE.md estructurado en capas, un ingeniero nuevo hereda las convenciones de la agencia a través de la herramienta en lugar de meses de conocimiento tribal. Desplaza la contratación hacia el criterio y lejos de memorizar el estilo de la casa.