Configuración de Claude Code en VS Code: Crea un Mejor Starter Multi-Stack con CLAUDE.md

La mayoría de las configuraciones de Claude Code comienzan con un único archivo CLAUDE.md que intenta cubrir todo. Eso funciona bien para proyectos pequeños de un solo stack. Pero si trabajas con múltiples stacks tecnológicos, ese archivo crece hasta convertirse en un bloque de instrucciones inflado que desperdicia contexto y diluye la orientación que Claude realmente necesita para la tarea en cuestión.

En este tutorial, construirás una configuración modular de Claude Code para VS Code que se adapta al stack con el que estés trabajando. En lugar de un archivo masivo, crearás un CLAUDE.md ligero que actúa como router, respaldado por reglas condicionales, subagents especializados, hooks de automatización y plantillas de prompts reutilizables. Al final, tendrás un directorio .claude/ portable que podrás instalar en cualquier proyecto.

El starter completo está disponible en InkByteStudio/claude-code-vscode-multistack-starter. Puedes seguir el tutorial paso a paso o clonar el repositorio y usarlo como referencia.

Lo que vas a construir

Esta es la estructura completa que crearás:

.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

La arquitectura sigue un patrón de dos niveles. Las reglas incondicionales (common, testing, git, security) se cargan en cada sesión y proporcionan orientación base. Las reglas condicionales por stack usan paths en el frontmatter para cargarse solo cuando Claude lee o edita archivos que coinciden con patrones glob específicos. Esto significa que una sesión de Python solo ve las reglas de Python, una sesión de Laravel solo ve las reglas de Laravel, y el contexto se mantiene ligero.

Por qué lo modular supera a lo monolítico

Un CLAUDE.md monolítico para un proyecto de seis stacks podría tener entre 400 y 600 líneas. En una sesión donde solo estás editando archivos Python, el 80 por ciento de esas instrucciones son ruido. La carga condicional cambia la ecuación:

• Monolítico: aproximadamente 400 líneas cargadas en cada sesión
• Modular (sesión solo Python): aproximadamente 80 líneas (reglas compartidas más python-fastapi.md)
• Modular (sesión Laravel más Docker): aproximadamente 120 líneas (reglas compartidas más laravel.md más docker-devops.md)

Menos ruido significa mejor señal, lo que se traduce en respuestas más precisas. También significa que cada responsable de stack mantiene su propio archivo en lugar de que todos peleen por un único documento compartido.

Paso 1: Inicializar Claude Code en VS Code

Abre tu proyecto en VS Code y asegúrate de que la extensión Claude Code esté instalada y autenticada. Ejecuta el comando /init desde el chat de Claude Code para generar un CLAUDE.md por defecto en la raíz de tu proyecto.

El archivo por defecto será un punto de partida básico. Lo reemplazarás por completo en el siguiente paso, pero ejecutar /init primero asegura que Claude Code reconozca el proyecto y que se cree el directorio .claude/.

Ahora deberías tener un archivo CLAUDE.md en la raíz de tu proyecto y un directorio .claude/.

Paso 2: Crear el router CLAUDE.md

Reemplaza el CLAUDE.md por defecto con una guía de proyecto ligera que actúe como router. En lugar de contener todas tus reglas, describe el proyecto a alto nivel e importa las reglas incondicionales usando la sintaxis @.

Crea CLAUDE.md en la raíz de tu proyecto:

# 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 like architecture
  review, UI work, or SQL investigation.
- **Hooks** in `.claude/settings.json` run lightweight automation on session
  start and after edits.
- **Prompts** in `.claude/prompts/` provide reusable workflow templates for
  common tasks.

## Stack detection

Identify the active stack from the repository structure before making changes.

Common stack indicators:
- Laravel/PHP: `composer.json`, `artisan`, `routes/`, `app/`, `config/`
- React/Next.js: `package.json`, `next.config.*`, `app/`, `pages/`,
  `src/components/`
- Python/FastAPI: `pyproject.toml`, `requirements.txt`, `app/`, `main.py`
- Node/Express: `package.json`, `server.js`, `src/`, `routes/`
- Docker/DevOps: `Dockerfile`, `docker-compose.yml`, `.github/workflows/`
- SQL/Data: migration files, schema dumps, reporting queries, ETL scripts

## Default behavior

- Explain the plan before major edits.
- Prefer the smallest useful diff.
- Reuse existing patterns before adding new abstractions.
- Do not add dependencies unless there is a clear reason.
- Update docs when behavior changes.

## Imported rules (always loaded)

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

## Prompt helpers (available on demand)

@.claude/prompts/bugfix.md
@.claude/prompts/refactor.md
@.claude/prompts/code-review.md
@.claude/prompts/onboarding.md

Ahora deberías tener un CLAUDE.md limpio y legible que describe la estructura del proyecto e importa las reglas compartidas sin contener detalles específicos de cada stack.

Paso 3: Agregar reglas incondicionales

Crea cuatro archivos de reglas en .claude/rules/ que se carguen en cada sesión. Estos cubren preocupaciones transversales que aplican independientemente del stack con el que estés trabajando.

Crea .claude/rules/common.md:

# Common Rules

- Match the project's existing naming, folder, and formatting conventions.
- Prefer explicit code over clever code.
- Do not rewrite unrelated files.
- Preserve comments that explain business logic.
- Keep functions and classes cohesive and focused.
- Prefer configuration over hardcoding where the project already supports it.
- When changing behavior, note user-visible impact.
- Use 2-space indentation for JS/TS/JSON, 4-space for Python/PHP unless the
  project uses something else.
- Follow the existing import style and module organization.

Crea .claude/rules/testing.md:

# Testing Rules

- Run only the most relevant tests first.
- Prefer one file, one suite, or one command over full-suite runs.
- If adding logic, add or update tests when the project already has test
  coverage in that area.
- If tests are missing, suggest the smallest useful test addition.
- Report what was run, what passed, and what was not verified.
- Use the stack-appropriate test runner:
  - PHP/Laravel: `php artisan test --filter=...` or `./vendor/bin/phpunit`
  - React/Next.js: `npm test -- <name>` or `npx vitest run <name>`
  - Python: `pytest -k ...` or `uv run pytest`
  - Node/Express: `npm test -- <name>` or `npm run test:unit`

Crea .claude/rules/git.md:

# Git Rules

- Keep changes scoped to the task.
- Summarize changed files in plain language.
- Use conventional commit style: `type(scope): description`
  - Types: feat, fix, refactor, test, docs, chore, ci, perf
- Call out migrations, config changes, and any manual deployment steps.
- Suggest focused branch names: `type/short-description`
  (e.g., `fix/auth-redirect`, `feat/user-export`).
- Never force-push to main or shared branches without explicit approval.

Crea .claude/rules/security.md:

# Security Rules

- Never expose secrets, tokens, or private keys in code or logs.
- Never commit `.env`, credentials, or key files.
- Avoid logging sensitive values (passwords, tokens, PII).
- Validate input boundaries on API and DB changes.
- Sanitize user input before rendering (prevent XSS) or querying
  (prevent SQL injection).
- Flag auth, permission, or data exposure risks clearly.
- For destructive shell or SQL operations, explain scope before execution.
- Run `npm audit`, `pip audit`, or `composer audit` when adding dependencies.

Estos cuatro archivos no tienen frontmatter paths, lo que significa que Claude los carga incondicionalmente en cada sesión.

Ahora deberías tener cuatro archivos de reglas en .claude/rules/ cubriendo estándares de código, filosofía de testing, convenciones de git y directrices de seguridad.

Paso 4: Agregar reglas condicionales por stack

Las reglas condicionales son donde el enfoque modular realmente rinde frutos. Cada archivo de regla de stack incluye un bloque paths en su frontmatter YAML que le indica a Claude que lo cargue solo cuando lee o edita archivos que coinciden con esos patrones glob.

Aquí está el archivo completo de reglas de Laravel como ejemplo principal. Crea .claude/rules/laravel.md:

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

# Laravel / PHP Guidance

## Architecture
- Prefer existing Laravel conventions before custom patterns.
- Keep controllers thin.
- Put reusable business logic in services, actions, or domain classes
  if that pattern already exists.
- Use Form Requests for request validation when appropriate.
- Prefer Eloquent scopes, relationships, and query builders over
  duplicated query logic.

## Database
- Treat migrations as review-sensitive changes.
- Prefer additive schema changes unless a breaking change is intentional.
- For large updates, think about indexing, chunking, locking, and
  rollback impact.

## Commands
- `php artisan test --filter=...`
- `php artisan route:list`
- `php artisan migrate --pretend`
- `composer test`
- `./vendor/bin/phpunit`

## Review checklist
- Validation correct?
- Auth/authorization preserved?
- N+1 or query performance issues?
- Migration safety reviewed?
- API response shape consistent?

Ahora crea los cinco archivos de reglas de stack restantes. Cada uno sigue el mismo patrón: frontmatter paths en la parte superior, luego orientación específica del stack.

Crea .claude/rules/react-next.md con estos paths:

---
paths:
  - "**/*.tsx"
  - "**/*.jsx"
  - "**/components/**"
  - "**/pages/**"
  - "**/next.config.*"
---

Incluye orientación sobre diseño de componentes, gestión de estado, límites servidor/cliente de Next.js, convenciones de estilo y una checklist de revisión que cubra accesibilidad, estados de carga y corrección de tipos.

Crea .claude/rules/python-fastapi.md con estos paths:

---
paths:
  - "**/*.py"
  - "**/requirements*.txt"
  - "**/pyproject.toml"
---

Incluye orientación sobre diseño de APIs, validación, patrones asíncronos y una checklist de revisión que cubra type hints, alineación de schemas y manejo de errores.

Crea .claude/rules/node-express.md con estos paths:

---
paths:
  - "**/server/**"
  - "**/routes/**/*.js"
  - "**/routes/**/*.ts"
  - "**/middleware/**"
  - "**/server.js"
  - "**/app.js"
---

Incluye orientación sobre estructura de rutas, middleware, manejo de errores y una checklist de revisión que cubra validación, autenticación y seguridad de logs.

Crea .claude/rules/docker-devops.md con estos paths:

---
paths:
  - "**/Dockerfile*"
  - "**/docker-compose*.yml"
  - "**/compose*.yml"
  - "**/.github/workflows/**"
  - "**/nginx/**"
---

Incluye orientación sobre cambios en contenedores, pipelines CI/CD, seguridad para cambios que impactan producción y una checklist de revisión que cubra reproducibilidad de builds, manejo de secretos y estrategias de rollback.

Crea .claude/rules/sql.md con estos paths:

---
paths:
  - "**/*.sql"
  - "**/migrations/**"
  - "**/seeds/**"
  - "**/seeders/**"
---

Incluye orientación sobre diseño de consultas, seguridad para sentencias UPDATE y DELETE, consideraciones de rendimiento y una checklist de revisión que cubra manejo de nulls, duplicación en joins y estrategia de rollback.

Ahora deberías tener seis archivos de reglas condicionales en .claude/rules/, cada uno con frontmatter paths que limita cuándo se carga.

Paso 5: Crear subagents

Los subagents son agentes especializados definidos en .claude/agents/ con sus propios system prompts, acceso a herramientas y selección de modelo. Son útiles para tareas de múltiples pasos donde una perspectiva enfocada es beneficiosa.

Crea .claude/agents/laravel-architect.md:

---
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
---

You are a Laravel-focused engineering subagent.

## Priorities
- Follow Laravel conventions already present in the repo.
- Keep controllers thin. Push logic into services, actions, or domain classes.
- Recommend safe migration patterns. Prefer additive schema changes.
- Call out validation, auth, and query performance risks.
- Prefer focused diffs and small follow-up steps.

## When reviewing code
- Check for N+1 queries and suggest eager loading where needed.
- Verify Form Request validation covers edge cases.
- Confirm authorization checks are in place.
- Look for missing indexes on frequently queried columns.

## When writing code
- Use Eloquent relationships and scopes over raw queries.
- Follow existing factory and seeder patterns for test data.
- Keep route definitions clean and grouped logically.
- Use Laravel's built-in helpers before adding custom utilities.

Crea los cinco agentes restantes en .claude/agents/ siguiendo el mismo patrón:

• react-ui.md — Especialista en UI con React y Next.js. Enfocado en estructura de componentes, flujo de estado, accesibilidad y estilos. Configura model: sonnet, maxTurns: 20.
• python-api.md — Especialista en Python y FastAPI. Enfocado en diseño de endpoints, modelos Pydantic, patrones asíncronos y seguridad de tipos. Configura model: sonnet, maxTurns: 25.
• node-backend.md — Especialista en Node.js y Express. Enfocado en middleware, manejo de errores, organización de rutas y patrones asíncronos. Configura model: sonnet, maxTurns: 25.
• devops-reviewer.md — Especialista en Docker y DevOps. Enfocado en Dockerfiles, pipelines CI/CD, revisión de infraestructura y seguridad. Configura model: sonnet, maxTurns: 20.
• sql-investigator.md — Especialista en SQL y bases de datos. Enfocado en optimización de consultas, revisión de schemas, seguridad de migraciones y análisis de datos. Configura model: sonnet, maxTurns: 20.

Cada agente incluye un campo description que le indica a Claude cuándo sugerir delegar a ese agente. El campo tools controla qué herramientas puede usar el agente. El campo maxTurns limita cuántos pasos puede dar el agente antes de devolver el control.

Ahora deberías tener seis archivos de agentes en .claude/agents/, uno por stack.

Paso 6: Configurar hooks

Los hooks son scripts de shell ligeros que se ejecutan automáticamente en eventos específicos del ciclo de vida de Claude Code. Crea la configuración de hooks y los scripts.

Crea .claude/settings.json:

{
  "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
          }
        ]
      }
    ]
  },
  "permissions": {
    "allow": [],
    "deny": []
  }
}

La variable $CLAUDE_PROJECT_DIR se resuelve a la raíz del proyecto, de modo que las rutas funcionan independientemente del directorio de trabajo actual.

Crea .claude/hooks/session-start.sh:

#!/usr/bin/env bash
# Runs on SessionStart via .claude/settings.json
# Detects active stacks and checks environment readiness.

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
DETECT_SCRIPT="$SCRIPT_DIR/../../scripts/detect-stack.sh"

if [ -x "$DETECT_SCRIPT" ] || [ -f "$DETECT_SCRIPT" ]; then
  stacks_json=$(bash "$DETECT_SCRIPT" 2>/dev/null || echo '{"stacks": []}')
  stacks_list=$(echo "$stacks_json" | grep -o '"[^"]*"' \
    | grep -v stacks | grep -v detected_at | tr -d '"' \
    | paste -sd', ' -)
  if [ -n "$stacks_list" ]; then
    echo "Detected stacks: $stacks_list"
  else
    echo "No specific stack detected. Check project files manually."
  fi
else
  echo "No specific stack detected. Check project files manually."
fi

# Check for missing .env
if [ -f .env.example ] && [ ! -f .env ]; then
  echo "Warning: .env.example exists but .env is missing. Copy and configure it."
fi

exit 0

Crea .claude/hooks/post-edit-check.sh:

#!/usr/bin/env bash
# Runs after Edit/Write tool use via .claude/settings.json
# Performs lightweight lint checks based on the edited file type.

INPUT=$(cat)
if command -v jq &>/dev/null; then
  FILE=$(echo "$INPUT" | jq -r '.file_path // empty' 2>/dev/null)
else
  FILE=$(echo "$INPUT" | grep -o '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' \
    | head -1 | sed 's/.*"file_path"[[:space:]]*:[[:space:]]*"//;s/"$//')
fi

if [ -z "$FILE" ]; then
  exit 0
fi

EXT="${FILE##*.}"

case "$EXT" in
  php)
    if command -v php &>/dev/null; then
      php -l "$FILE" 2>&1 || true
    fi
    ;;
  py)
    if command -v ruff &>/dev/null; then
      ruff check "$FILE" 2>&1 || true
    elif command -v python3 &>/dev/null; then
      python3 -m py_compile "$FILE" 2>&1 || true
    fi
    ;;
  ts|tsx|js|jsx)
    if command -v npx &>/dev/null; then
      npx eslint "$FILE" --no-error-on-unmatched-pattern 2>&1 || true
    fi
    ;;
  sql)
    echo "SQL file edited: $FILE -- review before executing."
    ;;
esac

exit 0

Haz ambos scripts de hook ejecutables:

chmod +x .claude/hooks/session-start.sh .claude/hooks/post-edit-check.sh

Ahora deberías tener dos scripts de hook y un settings.json que los conecta a los eventos del ciclo de vida SessionStart y PostToolUse.

Paso 7: Construir el script de detección de stacks

El script de detección de stacks escanea archivos marcadores en la raíz del proyecto y genera un objeto JSON listando los stacks detectados. El hook de inicio de sesión llama a este script para darle a Claude contexto inmediato del proyecto.

Crea scripts/detect-stack.sh:

#!/usr/bin/env bash
# Standalone stack detection script.
# Outputs detected stacks as JSON for use by other tools.

stacks=()

{ [ -f artisan ] || [ -f composer.json ]; } && stacks+=("laravel")
{ [ -f next.config.js ] || [ -f next.config.mjs ] || [ -f next.config.ts ]; } \
  && stacks+=("react-next")
[ -f package.json ] && grep -q '"react"' package.json 2>/dev/null \
  && stacks+=("react")
{ [ -f pyproject.toml ] || [ -f requirements.txt ]; } \
  && stacks+=("python-fastapi")
[ -f package.json ] && { [ -f server.js ] || [ -f app.js ]; } \
  && stacks+=("node-express")
{ [ -f Dockerfile ] || [ -f docker-compose.yml ] || [ -f compose.yml ]; } \
  && stacks+=("docker-devops")

# Check for SQL-heavy projects
sql_count=$(find . -maxdepth 3 -name "*.sql" 2>/dev/null | head -5 | wc -l)
[ "$sql_count" -gt 0 ] && stacks+=("sql")

# Output as JSON
json="["
for i in "${!stacks[@]}"; do
  [ "$i" -gt 0 ] && json+=","
  json+="\"${stacks[$i]}\""
done
json+="]"

echo "{\"stacks\": $json, \"detected_at\": \"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"}"

Hazlo ejecutable:

chmod +x scripts/detect-stack.sh

Así es como el script mapea archivos marcadores a identificadores de stack:

Stack ID	Archivos marcadores	Lógica de detección
laravel	artisan, composer.json	Existe cualquiera de los archivos
react-next	next.config.js, .mjs, .ts	Existe cualquier archivo de configuración
react	package.json con "react"	React en dependencias
python-fastapi	pyproject.toml, requirements.txt	Existe cualquiera de los archivos
node-express	package.json + server.js/app.js	Archivo de paquete más punto de entrada
docker-devops	Dockerfile, docker-compose.yml, compose.yml	Existe cualquier configuración
sql	Archivos *.sql dentro de 3 niveles	Al menos un archivo SQL encontrado

Ejecutar el script produce una salida como esta:

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

Ahora deberías tener un script de detección de stacks funcional que genera JSON limpio.

Paso 8: Agregar plantillas de prompts

Las plantillas de prompts son flujos de trabajo reutilizables almacenados en .claude/prompts/. Están disponibles bajo demanda cuando necesitas un enfoque estructurado para una tarea común.

Crea .claude/prompts/bugfix.md:

# Bugfix Workflow

Use this prompt when diagnosing and fixing a bug.

## Steps

1. **Describe the bug**: What is the expected behavior vs. actual behavior?
2. **Reproduce**: Find or write a minimal reproduction. If tests exist,
   write a failing test first.
3. **Diagnose**: Trace the code path. Check logs, error messages, and recent
   changes. Narrow down to the root cause before proposing a fix.
4. **Fix**: Apply the smallest change that addresses the root cause.
   Do not refactor unrelated code.
5. **Verify**: Run the failing test (or the narrowest relevant test suite)
   to confirm the fix. Run lint and typecheck.
6. **Document**: Note what caused the bug, what the fix does, and any
   follow-up work needed.

## Checklist before committing
- [ ] Root cause identified (not just symptoms addressed)
- [ ] Fix is scoped to the bug (no unrelated changes)
- [ ] Test covers the failure case
- [ ] Existing tests still pass
- [ ] No regressions introduced

Crea tres plantillas de prompts más en .claude/prompts/:

• refactor.md — Un flujo de trabajo de refactorización estructurado: identifica el objetivo, define el alcance del impacto, planifica pasos incrementales, ejecuta un paso a la vez, verifica que los tests pasen en cada paso y documenta la motivación en el mensaje de commit.
• code-review.md — Una checklist de revisión de código que cubre seguridad (secretos, inyección, autenticación), corrección (casos límite, rutas de error), rendimiento (N+1, asincronía, paginación), legibilidad (nombres, diffs enfocados) y testing (cobertura, aserciones significativas). Califica los hallazgos como Crítico, Advertencia o Sugerencia.
• onboarding.md — Un flujo de trabajo de onboarding de proyecto: explora la estructura de directorios, identifica el stack, encuentra puntos de entrada, documenta comandos de build y ejecución, mapea la arquitectura, verifica convenciones y produce un documento resumen.

Puedes invocar cualquier plantilla de prompt durante una sesión de Claude Code con /nombre-del-prompt o referenciándola con @.claude/prompts/nombre.md.

Ahora deberías tener cuatro plantillas de prompts cubriendo los flujos de trabajo de desarrollo más comunes.

Paso 9: Crear el script de instalación

El script de instalación copia toda la configuración en un proyecto existente. Esto hace que el starter sea portable entre todos tus repositorios.

Crea scripts/install-local.sh:

#!/usr/bin/env bash
# Install this Claude Code starter config into an existing project.
# Usage: ./scripts/install-local.sh [target-directory]

set -e

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
REPO_DIR="$(dirname "$SCRIPT_DIR")"
TARGET="${1:-.}"

# Resolve to absolute path
TARGET="$(cd "$TARGET" && pwd)"

echo "Claude Code Multi-Stack Starter Installer"
echo "==========================================="
echo ""
echo "Source: $REPO_DIR"
echo "Target: $TARGET"
echo ""

# Check if .claude/ already exists
if [ -d "$TARGET/.claude" ]; then
  echo "Warning: $TARGET/.claude/ already exists."
  read -rp "Overwrite existing config? (y/N): " confirm
  if [[ ! "$confirm" =~ ^[Yy]$ ]]; then
    echo "Aborted."
    exit 0
  fi
fi

# Copy .claude/ directory
echo "Copying .claude/ config..."
mkdir -p "$TARGET/.claude"
cp "$REPO_DIR/.claude/settings.json" "$TARGET/.claude/settings.json"
cp -r "$REPO_DIR/.claude/rules" "$TARGET/.claude/"
cp -r "$REPO_DIR/.claude/agents" "$TARGET/.claude/"
cp -r "$REPO_DIR/.claude/hooks" "$TARGET/.claude/"
cp -r "$REPO_DIR/.claude/prompts" "$TARGET/.claude/"

# Copy CLAUDE.md if it doesn't exist
if [ -f "$TARGET/CLAUDE.md" ]; then
  echo "CLAUDE.md already exists in target. Skipping (review manually)."
else
  cp "$REPO_DIR/CLAUDE.md" "$TARGET/CLAUDE.md"
  echo "Copied CLAUDE.md"
fi

# Make hook scripts executable
chmod +x "$TARGET/.claude/hooks/"*.sh 2>/dev/null || true

# Detect stacks
echo ""
echo "Detecting stacks in target project..."
cd "$TARGET"
stacks_output=$("$REPO_DIR/scripts/detect-stack.sh" 2>/dev/null \
  || echo '{"stacks": []}')
echo "$stacks_output"

# Summary
echo ""
echo "Installation complete."
echo ""
echo "Next steps:"
echo "  1. Review CLAUDE.md and adjust for your project"
echo "  2. Remove stack rules you don't need from .claude/rules/"
echo "  3. Remove agents you don't need from .claude/agents/"
echo "  4. Customize .claude/settings.json hooks"
echo "  5. Open the project in VS Code and start Claude Code"

Hazlo ejecutable:

chmod +x scripts/install-local.sh

Para instalar el starter en un proyecto existente:

./scripts/install-local.sh /path/to/your/project

El script copia el directorio .claude/, preserva cualquier CLAUDE.md existente, hace los hooks ejecutables y ejecuta la detección de stacks en el proyecto destino.

Ahora deberías tener un script de instalación funcional que puede desplegar la configuración en cualquier proyecto.

Paso 10: Probar la configuración

Elige un proyecto existente que use al menos uno de los stacks soportados. Instala la configuración usando el script de instalación o copiando los archivos manualmente. Luego verifica que cada componente funcione.

Verifica que las reglas incondicionales se carguen. Inicia una nueva sesión de Claude Code y pídele a Claude que describa sus reglas activas. Las cuatro reglas incondicionales (common, testing, git, security) deberían estar presentes.

Verifica que las reglas condicionales se activen. Pídele a Claude que lea o edite un archivo que coincida con uno de los patrones de stack. Por ejemplo, abre un archivo .php en un proyecto Laravel. Las reglas de Laravel deberían activarse. Abre un archivo .tsx y las reglas de React deberían activarse en su lugar.

Verifica que los subagents estén disponibles. Pídele a Claude que liste los agentes disponibles o intenta delegar una tarea a un agente específico como laravel-architect.

Verifica que el hook de inicio de sesión se ejecute. Inicia una nueva sesión y comprueba si Claude reporta los stacks detectados. Deberías ver una salida como “Detected stacks: laravel, docker-devops”.

Verifica que el hook post-edit se active. Pídele a Claude que edite un archivo y comprueba si la verificación de lint se ejecuta automáticamente después de la edición.

Si todo funciona, la configuración está lista para uso diario.

Personalización

El starter es una base, no un producto terminado. Así puedes adaptarlo:

Elimina stacks que no uses. Borra los archivos de reglas y agentes de los stacks que no utilizas. Un equipo que solo trabaja con Python puede eliminar laravel.md, react-next.md, node-express.md y sus agentes correspondientes.

Personaliza las reglas incondicionales. Ajusta common.md, testing.md, git.md y security.md para que coincidan con las convenciones de tu equipo. Se cargan en cada sesión, así que mantenlas concisas y relevantes.

Agrega nuevos stacks. Copia un archivo de regla condicional existente, actualiza el frontmatter paths para que coincida con los patrones de archivos de tu nuevo stack y actualiza la orientación. Por ejemplo, para agregar soporte de Rust:

---
paths:
  - "**/*.rs"
  - "**/Cargo.toml"
---

Luego agrega un bloque de detección correspondiente en detect-stack.sh:

[ -f Cargo.toml ] && stacks+=("rust")

Y opcionalmente crea un agente rust-systems.md en .claude/agents/.

Ajusta los timeouts de los hooks. Si tus herramientas de lint son lentas, aumenta los valores de timeout en settings.json. El hook de inicio de sesión tiene un valor por defecto de 30 segundos y el hook post-edit de 60 segundos.

Problemas comunes de configuración

Las reglas de stack se cargan en cada sesión

Síntomas: Claude hace referencia a las reglas de Laravel cuando estás editando archivos Python, o todas las reglas de stack aparecen activas independientemente de lo que estés trabajando.

Causa probable: Falta el frontmatter paths en el archivo de regla de stack, o la sintaxis YAML es inválida.

Solución: Abre el archivo de regla y verifica que comience con un bloque paths válido entre delimitadores ---. Revisa errores de sintaxis YAML como comillas faltantes, indentación incorrecta o un --- de cierre faltante.

Los hooks no se ejecutan

Síntomas: No hay salida de detección de stacks al iniciar la sesión. No hay verificación de lint después de las ediciones.

Causa probable: Los scripts de hook no son ejecutables, la ruta en settings.json es incorrecta o la variable $CLAUDE_PROJECT_DIR no se está resolviendo correctamente.

Solución: Ejecuta chmod +x .claude/hooks/*.sh. Verifica que settings.json use el formato de ruta correcto con $CLAUDE_PROJECT_DIR. Comprueba que el directorio scripts exista y contenga detect-stack.sh.

Stack no detectado

Síntomas: El hook de inicio de sesión reporta “No specific stack detected” aunque el proyecto claramente usa un stack soportado.

Causa probable: Los archivos marcadores no están en la raíz del proyecto. En un monorepo, el archivo artisan de Laravel podría estar en backend/ en lugar de la raíz.

Solución: Mueve los archivos marcadores a la raíz, agrega symlinks o modifica detect-stack.sh para verificar layouts comunes de monorepo como packages/, apps/ o services/.

El hook post-edit reporta errores

Síntomas: Errores de lint aparecen después de cada edición, incluso por problemas no relacionados.

Causa probable: La herramienta de lint está reportando problemas preexistentes en el archivo, no problemas causados por la edición.

Solución: Corrige los problemas de lint preexistentes o ajusta el hook post-edit para que solo reporte errores en las líneas modificadas. Como solución rápida, también puedes comentar verificaciones específicas del linter en post-edit-check.sh.

CLAUDE.md es demasiado detallado

Síntomas: El archivo CLAUDE.md está creciendo de nuevo, anulando el propósito de la configuración modular.

Causa probable: Se está agregando orientación específica de stack o detallada al CLAUDE.md en lugar del archivo de regla apropiado.

Solución: Mueve la orientación detallada al archivo correspondiente en .claude/rules/. CLAUDE.md debería mantenerse como un router ligero: visión general del proyecto, indicadores de stack, comportamiento por defecto e importaciones con @. Todo lo demás pertenece a un archivo de regla.

Conclusión

Ahora tienes una configuración modular de Claude Code que se adapta al stack con el que estés trabajando. Las reglas incondicionales proporcionan orientación base consistente. Las reglas condicionales se cargan solo cuando son relevantes. Los subagents ofrecen experiencia enfocada. Los hooks automatizan verificaciones rutinarias. Y el script de instalación hace que toda la configuración sea portable entre proyectos.

El principio clave es simple: carga solo lo que importa para la tarea actual. Eso le da a Claude más contexto para el código en el que realmente está trabajando, y le da a tu equipo una configuración mantenible que escala con el proyecto.

El starter completo está disponible en InkByteStudio/claude-code-vscode-multistack-starter. Clónalo, personalízalo y elimina lo que no necesites.

Para una visión de alto nivel sobre por qué este enfoque modular importa, consulta el artículo complementario: Why Most CLAUDE.md Files Are Too Big. Para entender cómo Claude Code encaja en el panorama más amplio de agentes de codificación con IA, lee AI Coding Agents in 2026: How MCP Is Changing Software Development y Building Custom MCP Servers. Para equipos que están pensando en seguridad y gobernanza alrededor del desarrollo agéntico, complementa esto con Securing AI Coding Agent Workflows y the Agentic AI Security Playbook.