Modular CLAUDE.md: Multi-Stack Claude Code Setup

La mayoría de archivos CLAUDE.md que se encuentran en la práctica son un único documento masivo que cubre cada stack, convención y caso extremo que el equipo haya discutido. El contenido en sí suele estar bien. El problema es la forma de entregarlo. Volcar 400 o más líneas de instrucciones en cada sesión de Claude Code desperdicia contexto y confunde las prioridades, porque Claude carga todo sin importar en qué estés trabajando realmente.

Esto importa más de lo que parece. Los LLMs tienen ventanas de contexto finitas, y cada token de instrucción compite con el código que Claude está leyendo y editando. Si trabajas con múltiples stacks, un CLAUDE.md monolítico significa que Claude está leyendo tus convenciones de Docker mientras arreglas un componente React, y absorbiendo tus guías de SQL mientras depuras un endpoint en Python. Una configuración modular de dos niveles soluciona esto cargando solo las reglas relevantes para lo que estás tocando en ese momento. El resultado es más rápido, más preciso y más fácil de mantener.

El problema del CLAUDE.md monolítico

Un CLAUDE.md monolítico típico empieza pequeño. Agregas algunos estándares de código, algunas convenciones de git, quizá una nota sobre tu enfoque preferido de testing. Luego el proyecto crece. Alguien agrega reglas de Laravel. Alguien más agrega patrones de React. El ingeniero de DevOps añade guías de Docker y CI/CD. El equipo de base de datos agrega convenciones de SQL. Seis meses después, tienes un archivo de 500 líneas cubriendo seis stacks, y nadie quiere podarlo porque tienen miedo de romper algo.

Los costos son reales:

Desperdicio de ventana de contexto. Claude carga cada instrucción en cada sesión, incluso cuando solo estás editando archivos de un stack. Una sesión exclusivamente de Python sigue cargando reglas de Laravel, React, Docker y SQL.
Dilución de la señal. Las reglas importantes quedan enterradas en el ruido. Cuando todo tiene la misma prominencia, nada destaca.
Conflictos de merge. Cinco desarrolladores editando un mismo archivo significa conflictos constantes, especialmente en proyectos activos.
Obsolescencia. Las reglas antiguas permanecen porque nadie sabe si eliminarlas causará problemas. El archivo solo crece.

Este es el mismo problema que la ingeniería de software resolvió hace décadas con el god object. La solución también es la misma: separar por responsabilidad, cargar bajo demanda.

La solución: reglas modulares de dos niveles

El claude-code-vscode-multistack-starter reemplaza el enfoque monolítico con una arquitectura de dos niveles. El primer nivel cubre preocupaciones universales que aplican en cada sesión. El segundo nivel cubre reglas específicas de cada stack que se cargan solo cuando Claude toca archivos coincidentes.

Así se ve la estructura de directorios:

.claude/
  rules/
    common.md          # unconditional - always loaded
    testing.md         # unconditional
    git.md             # unconditional
    security.md        # unconditional
    laravel.md         # conditional - paths frontmatter
    react-next.md      # conditional
    python-fastapi.md  # conditional
    node-express.md    # conditional
    docker-devops.md   # conditional
    sql.md             # conditional
  agents/
    laravel-architect.md
    react-ui.md
    python-api.md
    node-backend.md
    devops-reviewer.md
    sql-investigator.md
  hooks/
    session-start.sh
    post-edit-check.sh
  prompts/
    bugfix.md
    refactor.md
    code-review.md
    onboarding.md
  settings.json
CLAUDE.md
scripts/
  detect-stack.sh
  install-local.sh

Nivel 1: Reglas incondicionales se cargan en cada sesión. Son preocupaciones transversales que aplican sin importar qué archivos estés editando: estándares básicos de código, filosofía de testing, convenciones de git y barreras de seguridad. No tienen frontmatter paths, así que Claude siempre las ve.

Nivel 2: Reglas condicionales por stack se cargan solo cuando Claude lee o edita archivos que coinciden con patrones glob específicos. Esta es una característica nativa de Claude Code. Cada archivo de reglas incluye un bloque paths en su frontmatter YAML que le indica a Claude cuándo activarlo.

Por ejemplo, el archivo de reglas de Laravel se activa solo cuando tocas archivos PHP, rutas, código de aplicación, migraciones o vistas:

---
paths:
  - "**/*.php"
  - "**/routes/**"
  - "**/app/**"
  - "**/database/migrations/**"
  - "**/resources/views/**"
---

Las reglas de los demás stacks siguen el mismo patrón. Las reglas de React se activan con .tsx, .jsx y next.config.*. Las reglas de Python se activan con .py y pyproject.toml. Las reglas de Node se activan con server.js, app.js y archivos de middleware. Las reglas de Docker se activan con Dockerfile y archivos compose. Las reglas de SQL se activan con archivos .sql y directorios de migraciones.

La diferencia práctica es significativa. Una sesión exclusivamente de Python carga alrededor de 80 líneas de reglas: los cuatro archivos incondicionales más python-fastapi.md. Una sesión de Laravel más Docker carga alrededor de 120 líneas. Compara eso con un archivo monolítico donde cada sesión carga 400 o más líneas sin importar lo que estés haciendo.

Qué va en CLAUDE.md versus en archivos de reglas

Con esta configuración, CLAUDE.md se convierte en un enrutador ligero en lugar de una enciclopedia. Describe el proyecto a alto nivel, lista los stacks activos, establece expectativas de comportamiento predeterminadas e importa las reglas incondicionales usando la sintaxis @.

Así se ve el CLAUDE.md real:

# Claude Code Project Guide

This repository is a multi-stack starter configuration for Claude Code in VS Code.

## How this repo works

- **Unconditional rules** in `.claude/rules/` (common, testing, git, security)
  load every session.
- **Stack-specific rules** in `.claude/rules/` use `paths` frontmatter to load
  only when you touch matching files.
- **Subagents** in `.claude/agents/` handle focused tasks.
- **Hooks** in `.claude/settings.json` run automation on session start and
  after edits.
- **Prompts** in `.claude/prompts/` provide reusable workflow templates.

## Imported rules (always loaded)

@.claude/rules/common.md
@.claude/rules/testing.md
@.claude/rules/git.md
@.claude/rules/security.md

La regla general es simple. Si aplica a cada sesión, conviértelo en una regla incondicional o ponlo directamente en CLAUDE.md. Si solo importa al tocar ciertos archivos, agrega frontmatter paths y deja que Claude lo cargue bajo demanda.

Subagents para trabajo enfocado

Los subagents son agentes especializados definidos en .claude/agents/ con sus propios system prompts, acceso a herramientas y selección de modelo. Son útiles cuando una tarea se beneficia de experiencia enfocada en lugar de guía general.

El starter incluye seis agentes, uno por stack:

laravel-architect — Modelos Eloquent, migraciones, API resources, Form Requests, patrones de servicio
react-ui — Arquitectura de componentes, gestión de estado, accesibilidad, estilos
python-api — Endpoints FastAPI, modelos Pydantic, patrones async
node-backend — Middleware Express, manejo de errores, estructura de rutas
devops-reviewer — Dockerfiles, pipelines CI/CD, revisión de infraestructura
sql-investigator — Optimización de queries, revisión de esquemas, análisis de datos

Cada agente tiene frontmatter que define sus capacidades. Este es el del arquitecto Laravel:

---
name: laravel-architect
description: Laravel architecture specialist for Eloquent models, migrations,
  API resources, Form Requests, service patterns, and routing.
tools: Read, Edit, Write, Bash, Grep, Glob
model: sonnet
maxTurns: 25
---

La distinción clave entre agentes y reglas es el alcance. Las reglas proporcionan guía ambiental que moldea cómo Claude aborda el código. Los agentes manejan tareas de múltiples pasos y enfocadas donde necesitas una perspectiva especializada. Piensa en las reglas como estándares de código y en los agentes como compañeros especialistas que incorporas a una conversación.

Hooks para automatización ligera

El starter configura dos hooks en .claude/settings.json que se ejecutan automáticamente en puntos específicos del ciclo de vida:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/session-start.sh",
            "timeout": 30
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/post-edit-check.sh",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

El hook SessionStart ejecuta session-start.sh cada vez que comienza una nueva sesión de Claude. Llama a detect-stack.sh, que escanea archivos marcadores y genera un objeto JSON listando los stacks detectados:

{
  "stacks": ["laravel", "docker-devops", "sql"],
  "detected_at": "2026-04-01T12:00:00Z"
}

Esto le da a Claude contexto inmediato sobre la estructura del proyecto sin que el desarrollador tenga que explicarlo manualmente. El hook también verifica si falta un archivo .env cuando existe .env.example.

El hook PostToolUse ejecuta post-edit-check.sh después de cualquier operación Edit o Write. Lee la ruta del archivo editado desde la entrada de la herramienta, determina el tipo de archivo y ejecuta una verificación ligera de lint: php -l para PHP, ruff check para Python, npx eslint para JavaScript y TypeScript, y un recordatorio de revisión manual para archivos SQL. Estas verificaciones se ejecutan automáticamente sin interrumpir al desarrollador.

Resultados y beneficios

Las mejoras prácticas de esta configuración se notan de inmediato:

Contexto más ligero. Una sesión de un solo stack carga de 50 a 80 líneas de reglas en lugar de 400 o más. Eso deja más contexto para el código en el que Claude está trabajando realmente.
Mayor precisión. Claude sigue los patrones específicos de cada stack de forma más confiable cuando no están enterrados en instrucciones no relacionadas. La señal sube, el ruido baja.
Mantenimiento más fácil. Cada responsable de stack edita su propio archivo de reglas. El desarrollador de Laravel actualiza laravel.md, el desarrollador frontend actualiza react-next.md, y nadie tiene conflictos en un archivo monolítico compartido.
Onboarding más rápido. Los nuevos miembros del equipo agregan las reglas de su stack sin tocar archivos compartidos. Las reglas incondicionales representan acuerdos a nivel de equipo que cambian con menos frecuencia.
Portabilidad. Todo el directorio .claude/ se copia limpiamente entre proyectos. El script de instalación maneja la transferencia automáticamente.

Cómo probarlo

El starter es open source y está listo para usar. Hay dos formas de empezar:

Opción 1: Clonar e instalar. Clona el repositorio y ejecuta el script de instalación contra un proyecto existente:

git clone https://github.com/InkByteStudio/claude-code-vscode-multistack-starter.git
cd claude-code-vscode-multistack-starter
./scripts/install-local.sh /path/to/your/project

El script copia el directorio .claude/ y CLAUDE.md en tu proyecto, hace ejecutables los scripts de hooks y ejecuta la detección de stacks para mostrar cuáles se encontraron.

Opción 2: Copia manual. Copia el directorio .claude/ y CLAUDE.md en la raíz de tu proyecto. Elimina las reglas de stack y los agentes que no necesites.

En cualquier caso, lo primero que debes hacer después de instalar es personalizar. Elimina los stacks que no uses. Ajusta las reglas incondicionales para que coincidan con las convenciones de tu equipo. Agrega nuevas reglas de stack para tecnologías que el starter aún no cubra. El starter es una base, no un producto terminado.

Empieza a construir una mejor configuración de Claude Code

La idea central es directa. Deja de volcar cada regla en un solo archivo. Separa por responsabilidad, carga bajo demanda y deja que Claude se enfoque en lo que importa para la tarea actual. Ese principio aplica tanto si usas este starter directamente como si construyes tu propia configuración modular desde cero.

Para un tutorial práctico paso a paso de cómo construir esta configuración desde cero, consulta el tutorial complementario: Claude Code Setup in VS Code: Build a Better Multi-Stack CLAUDE.md Starter.

Si estás evaluando Claude Code junto a otras herramientas de codificación con IA, este enfoque modular vale la pena compararlo con cómo otras herramientas manejan la configuración. Las reglas condicionales de Claude Code mediante frontmatter paths te dan un nivel de control que las configuraciones de un solo archivo en otras herramientas no pueden igualar. Los equipos que ya invierten en agentes de codificación con IA y servidores MCP personalizados encontrarán que la configuración modular de Claude Code encaja naturalmente en el mismo flujo de trabajo.

Para equipos que trabajan en gobernanza y seguridad en torno al desarrollo agéntico, combina esta configuración con nuestra guía para asegurar flujos de trabajo de agentes de codificación con IA y el playbook de seguridad para IA agéntica.

Por qué la mayoría de archivos CLAUDE.md son demasiado grandes: Una mejor configuración multi-stack para Claude Code