Parte 4: Los 7 Puntos de Extensión en una Base de Código de Producción

Hemos estado usando Claude Code como nuestra herramienta principal de desarrollo durante aproximadamente un año. No como un experimento paralelo. No para generar boilerplate. Como la forma principal en que se escribe, revisa, prueba, despliega y documenta código a través de un monorepo con 8 microservicios NestJS, 3 apps de frontend, un voice bot en Python, un SDK y un CLI.

Durante ese tiempo, hemos construido más de 50 skills, configurado múltiples MCP servers, escrito hooks de seguridad y reescrito nuestro CLAUDE.md más veces de las que puedo contar. Algunos de esos puntos de extensión se componen bellamente. Otros entran en conflicto de maneras que la documentación no advierte.

Esta es la Parte 4 de nuestra serie sobre el stack de extensiones de Claude. La Parte 1 cubrió el modelo mental y el framework de decisión. La Parte 2 profundizó en CLAUDE.md, hooks y skills. La Parte 3 cubrió MCP servers, connectors y Claude Apps. Este artículo es diferente: sin teoría, sin frameworks de decisión. Solo un recorrido de cómo se ven los 7 puntos de extensión en una base de código de producción, qué compone bien y qué haríamos diferente.

La base de código: con qué estamos trabajando

Nuestra plataforma es un monorepo con 17 proyectos que abarcan dos lenguajes, tres destinos de despliegue y flujos de desarrollo muy diferentes. Aquí está el panorama:

Backend: 8 microservicios NestJS (gestión de agentes, interacciones, base de conocimiento, canales, integraciones, escenarios, evaluaciones y un gateway de plataforma). Comparten un paquete común para autenticación, health checks y comunicación entre servicios. MongoDB para persistencia, Redis para transporte.

Frontend: 3 apps Next.js — un dashboard de administración, una UI de analíticas de voz y una plataforma de evaluaciones. Todas comparten un SDK común para hooks de datos y acceso a API.

SDK y CLI: Un SDK de TypeScript (@chanl-ai/platform-sdk) que provee React hooks, módulos de API y un CLI. Tanto las apps de frontend como el CLI lo consumen. El SDK es la fuente única de verdad para todo acceso a datos — desde herramientas de agentes hasta memoria y analíticas.

Voice bot: Un servicio Python usando Pipecat para IA de voz en tiempo real. Diferente lenguaje, diferente destino de despliegue (Pipecat Cloud en lugar de Fly.io), diferente todo.

MCP server: Un MCP server alojado en Vercel que le da a agentes de IA externos acceso a las herramientas y datos de nuestra plataforma.

Esto importa porque el stack de extensiones necesita manejar todo. Los patrones de backend TypeScript son diferentes de los patrones de frontend React. Python tiene convenciones diferentes a TypeScript. Desplegar en Fly.io es diferente de desplegar en Vercel o Pipecat Cloud. Una configuración monolítica sería demasiado genérica para ser útil o tan larga que Claude ignoraría la mayor parte.

Esa tensión — amplitud vs. profundidad, reglas universales vs. orientación específica por contexto — es el problema central que el stack de extensiones resuelve.

CLAUDE.md en la práctica: la estrategia de 3 niveles

Estructuramos las instrucciones del proyecto en tres niveles. El CLAUDE.md raíz proporciona navegación y reglas universales. Los archivos CLAUDE.md a nivel de servicio proporcionan contexto específico del proyecto. Las reglas con alcance se cargan automáticamente según qué archivos estés tocando.

Nivel 1: CLAUDE.md raíz (~500 líneas)

El CLAUDE.md raíz es el punto de entrada. Establece reglas estrictas que aplican en todas partes, proporciona navegación para encontrar cualquier cosa en el monorepo, y documenta el patrón orquestador para trabajo multi-proyecto.

Aquí está la estructura a la que llegamos después de meses de iteración:

# CLAUDE.md
 
## Session Start — Context Before Code
Every session begins here. Load context for the topic
before writing any code.
 
## Work Routing — Orchestrator + Subagent Architecture
The main thread plans, dispatches, reviews. Subagents implement.
 
## Hard Rules
10 non-negotiable rules. Link to full doc.
 
## Quick Commands
make backend, make api-get, make deploy-staging...
 
## Architecture
Scoped rules mapping, reference docs, related repos.
 
## Services Overview
Port/route table for all 8 services.
 
## Deploy
Fly.io, Vercel, Pipecat Cloud commands.
 
## Skills (Slash Commands)
Quick reference for /commit, /deploy, /plan, /board...

La idea clave: el CLAUDE.md raíz es un hub de navegación, no una enciclopedia. Le dice a Claude qué existe y dónde encontrarlo. Las reglas reales viven en archivos con alcance que se cargan bajo demanda.

Lo aprendimos de la manera difícil. Nuestro CLAUDE.md solía tener más de 600 líneas — contenía todos los patrones de backend, todas las reglas de frontend, todos los procedimientos de deploy, todo. Claude frecuentemente ignoraba reglas enterradas profundamente en el archivo. Dividirlo en un hub de navegación con reglas con alcance fue un punto de inflexión.

Nivel 2: CLAUDE.md a nivel de servicio

Cada uno de los 17 proyectos tiene su propio CLAUDE.md con detalles específicos del proyecto:

# CLAUDE.md - agent-service
 
> **Parent docs**: See root CLAUDE.md for hard rules and architecture.
 
Quick reference for agent-service development.
 
**Port**: 8002
**Owner**: Agent configuration, tools, prompts, memory
**Consumers**: MCP server, interactions-service, platform-sdk
 
**Deploy**: Part of mono deploy (make deploy-staging)
**Health**: curl -sf http://localhost:8002/health
**Logs**: make dev-logs SVC=agent
 
## Endpoints
| Method | Path           | Description     |
|--------|----------------|-----------------|
| POST   | /agents        | Create agent    |
| GET    | /agents        | List agents     |
| GET    | /agents/stats  | Workspace stats |
...

Estos archivos son concisos — puerto, endpoints, propietarios, trampas. Cuando un subagente se despacha para trabajar en agent-service, lee este archivo e inmediatamente conoce el terreno.

Nivel 3: reglas con alcance (el game-changer)

Las reglas con alcance en .claude/rules/ son la funcionalidad más subestimada en todo el stack de extensiones. Cada archivo de reglas tiene un frontmatter globs: que le dice a Claude cuándo cargarlo:

# .claude/rules/backend-services.md
---
globs:
  - "services/**/*.ts"
  - "packages/nestjs-common/**/*.ts"
  - "packages/platform-server/**/*.ts"
---
 
# Backend Services — chanl-platform
Rules and patterns for NestJS microservice development...

# .claude/rules/frontend-apps.md
---
globs:
  - "apps/**/*.tsx"
  - "apps/**/*.ts"
  - "apps/**/*.css"
  - "packages/platform-sdk/src/react/**/*.ts"
---
 
# Frontend Apps — chanl-platform
Rules for React apps, shadcn components, design tokens...

Cuando editas un archivo de servicio backend, solo se cargan las reglas de backend. Cuando editas un componente React, solo se cargan las reglas de frontend. Esto significa que Claude obtiene contexto profundo y relevante sin desperdiciar tokens en reglas irrelevantes.

Aquí está nuestro directorio completo de reglas:

.claude/rules/
  api-contracts.md         # Response format, pagination, error codes
  backend-services.md      # NestJS modules, schemas, DTOs
  deploy-infra.md          # Fly.io, Vercel, Doppler, Docker
  figma-design-system.md   # Design tokens, component architecture
  frontend-apps.md         # React, shadcn, responsive, state
  inter-service.md         # ServiceProxy, auth flow, Redis transport
  lessons-backend.md       # Hard-won debugging lessons (backend)
  lessons-deploy.md        # Hard-won debugging lessons (deploy)
  lessons-frontend.md      # Hard-won debugging lessons (frontend)
  lessons-integration.md   # Hard-won debugging lessons (integration)
  sdk-cli.md               # SDK modules, hooks, query keys, CLI
  wizard-dialog-ux.md      # Multi-step dialog patterns

Los archivos lessons-* merecen mención especial. Cada vez que pasamos más de 30 minutos depurando algo que Claude debería haber sabido, lo documentamos:

# lessons-backend.md
 
### mongoose-doc-save-race-condition
**Trigger**: any code using doc.save() for updates
**What happened**: concurrent updates overwrite each other
**Why wrong**: save() loads full document, modifies in memory,
  writes back — no atomicity
**Fix**: use findByIdAndUpdate(id, { $set: {...} },
  { new: true, runValidators: true }). Always.

Estos se archivan con globs que coinciden con los tipos de archivo relevantes, así que la próxima vez que Claude toca un modelo Mongoose, automáticamente ve la lección. Tenemos alrededor de 30 de estos a través de cuatro archivos. Han prevenido cientos de errores repetidos.

Skills en la práctica: más de 50 y contando

Tenemos 38 skills en .claude/commands/ y 15 más en .claude/skills/. Se dividen en cuatro categorías: flujo de trabajo, dominio, operacional y multi-proyecto.

Skills de Flujo de Trabajo

Estos gestionan el ciclo de vida del desarrollo:

El skill /commit es el más complejo. Aquí está su encabezado:

---
description: Review + reflect + commit in one flow
argument-hint: [type] [scope] [message] OR [--wip] OR [--push]
allowed-tools: Bash(git:*), Bash(make:*), Bash(pnpm:*),
  Read, Edit, Write, Glob, Grep, AskUserQuestion
---

Ejecuta siete fases: verificar el plan activo, revisar cambios contra el plan, analizar la transcripción de la conversación buscando algo que se haya pasado, sincronizar con el project board de GitHub, verificar que los tests de casos de uso pasen, proponer un mensaje de commit, y opcionalmente hacer push. El campo allowed-tools restringe lo que Claude puede hacer dentro del skill — puede ejecutar comandos git y make, leer y editar archivos, pero nada más.

Skills de Dominio

Estos codifican expertise sobre partes específicas de la base de código:

El skill /nestjs-coder es esencialmente un experto empaquetado. Incluye documentación de flujo de trabajo TDD, plantillas de patrones, un archivo de trampas y scripts. Cuando se despacha para implementar una funcionalidad, sigue la metodología RED-GREEN-REFACTOR usando nuestros patrones específicos:

.claude/skills/nestjs-coder/
  SKILL.md           # Main skill definition
  TDD-WORKFLOW.md    # RED → GREEN → REFACTOR steps
  PATTERNS.md        # Entity relations, response formats
  GOTCHAS.md         # Common pitfalls
  templates/         # Schema, DTO, controller templates
  scripts/           # Test runner helpers

Skills Operacionales

Estos proporcionan observabilidad y mantenimiento:

Skills Multi-proyecto

Algunos skills funcionan a través de múltiples repositorios:

El skill /context es uno de nuestros favoritos. Antes de escribir cualquier código, ejecutas /context mcp o /context voice y carga archivos de conocimiento preconstruidos sobre esa área — documentos de arquitectura, cambios recientes, trampas conocidas. Esto reemplaza la exploración costosa donde Claude pasaría 10 minutos leyendo archivos para construir contexto que ya hemos documentado.

Qué hace un buen Skill

Después de construir más de 50, hemos aprendido qué separa los skills útiles del ruido:

El campo de descripción es más importante que el cuerpo. Claude decide si invocar un skill basándose en la descripción — un resumen de una línea en el frontmatter. Si es vaga ("Utilidad de deploy útil"), Claude no sabrá cuándo usarla. Si es específica ("Deploy chanl-platform to staging or production on Fly.io"), Claude la coincide de manera confiable.

Los Skills deben tener patrones de argumentos claros. El campo argument-hint le dice a Claude qué entradas espera el skill. /deploy staging es claro. Un skill que toma argumentos posicionales sin nombre es confuso.

Delimita las herramientas permitidas. Un skill de deploy no debería poder editar archivos fuente. Un skill de code review no debería poder ejecutar deploys. El campo allowed-tools es tu límite de permisos.

Elimina skills que se superponen. Retiramos varios skills que se superponían con otros. Cuando Claude ve dos skills que podrían coincidir con una solicitud, a veces elige el incorrecto o pregunta al usuario para elegir — ambos son fricción. Consolida agresivamente.

Hooks: la red de seguridad

Los Hooks interceptan llamadas de herramientas antes de que se ejecuten. Son la capa de cumplimiento mecánico — CLAUDE.md sugiere comportamiento, los hooks lo aplican.

Hook a nivel de proyecto: compuerta de deploy a producción

Nuestro .claude/settings.json configura un hook PreToolUse en todos los comandos Bash:

{
  "permissions": {
    "deny": [
      "Bash(gh pr merge*--squash*)",
      "Bash(gh pr merge*--rebase*)"
    ]
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/block-prod-deploy.sh"
          }
        ]
      }
    ]
  }
}

La lista deny bloquea absolutamente los merges squash y rebase (siempre usamos merge commits). El script del hook verifica cada comando Bash contra una lista de patrones destructivos de producción:

#!/bin/bash
# Exit 0 with no output = allow
# Exit 0 with hookSpecificOutput JSON = force user prompt
# Exit 2 = hard block
 
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
[ -z "$COMMAND" ] && exit 0
 
REASON=""
 
PROD_MAKE_TARGETS=(
  "deploy-prod"
  "deploy-prod-full"
  "deploy-agents-prod"
  "release-promote"
  "mcp-deploy-prod"
  "voice-bot-deploy-prd"
  "doppler-sync-prod"
)
 
for target in "${PROD_MAKE_TARGETS[@]}"; do
  if echo "$COMMAND" | grep -qE "make\s+.*\b${target}\b"; then
    REASON="Production deploy: make $target"
    break
  fi
done
 
# If production command detected, force user confirmation
if [ -n "$REASON" ]; then
  cat <<EOF
{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "ask",
    "permissionDecisionReason": "$REASON — confirm to proceed"
  }
}
EOF
fi

Los deploys a staging pasan automáticamente. Los deploys a producción requieren que el usuario apruebe en el prompt del CLI. Esto es defensa en profundidad — CLAUDE.md dice "nunca hacer deploy a producción sin confirmación", pero el hook lo aplica mecánicamente incluso cuando Claude está en medio de una tarea compleja y podría olvidarlo.

Hook global: permisos de directorio

También ejecutamos un hook global en ~/.claude/hooks/directory-permissions.sh que aplica a todos los proyectos. Auto-aprueba operaciones seguras (Read, Grep, Glob) y bloquea comandos verdaderamente destructivos sin importar el contexto del proyecto.

El hook recibe entrada JSON con el nombre de la herramienta y parámetros, luego toma una decisión:

# Explicit safe tools (always approve)
case "$TOOL_NAME" in
  Read|Grep|Glob|WebFetch|WebSearch|Write|Edit)
    approve "Safe tool auto-approved" ;;
esac
 
# Check Bash commands for dangerous patterns
is_blocked_bash() {
  local full="$CMD"
  # Block rm -rf on critical paths
  # Block git push --force to main
  # Block destructive database operations
  ...
}

El patrón del hook es simple: parsea la entrada JSON, verifica contra tus reglas, genera una decisión. Los tres resultados posibles — permitir silenciosamente, preguntar al usuario, o bloqueo absoluto — te dan control granular.

Hooks que desearíamos haber escrito antes

Empezamos con todas las reglas de seguridad en CLAUDE.md. Durante meses, nos basamos en "Nunca hacer push a main" y "Nunca hacer deploy a producción sin preguntar" como instrucciones de texto. Funcionaban el 95% de las veces. Las fallas del 5% fueron lo suficientemente catastróficas como para que deberíamos haber escrito hooks desde el primer día.

La lección: cualquier cosa que sería un problema serio si se viola una vez merece un hook, no solo una instrucción de CLAUDE.md.

MCP servers: donde Claude se encuentra con el mundo

Conectamos múltiples MCP servers a Claude Code, cada uno sirviendo un propósito diferente. Los MCP servers proporcionan acceso a datos y acciones que Claude no puede obtener del sistema de archivos por sí solo.

Nuestro stack de MCP servers

Cómo MCP complementa los Skills

La relación entre MCP servers y skills es una de las composiciones más naturales del stack. Los Skills definen el flujo de trabajo. Los MCP servers proporcionan los datos. Raramente entran en conflicto porque operan a niveles diferentes.

Ejemplo: nuestro skill /deploy conoce la secuencia de despliegue — build, push, verificar health, ejecutar smoke tests, publicar en Slack. El MCP server de Slack maneja el paso "publicar en Slack." El skill no necesita conocer la API de Slack. El MCP server no necesita conocer el flujo de despliegue. Separación limpia.

Otro ejemplo: nuestro skill /commit incluye una fase que sincroniza con el project board de GitHub. Si se estaba trabajando en un issue, el skill de commit actualiza su estado. La integración del board sucede a través de comandos del CLI gh (no MCP), pero el patrón es el mismo — el skill orquesta, la herramienta externa provee acceso.

El pipeline de Figma a código

Una de nuestras integraciones MCP más productivas es la conexión con Figma. Al implementar UI desde diseños, el flujo es:

1. get_design_context desde Figma MCP — código estructurado para el componente objetivo
2. get_screenshot — referencia visual
3. El archivo de reglas de frontend (auto-cargado vía reglas con alcance) le dice a Claude cómo adaptar — reemplazar colores crudos con tokens semánticos, reemplazar spacing arbitrario con valores de grid de 8pt, usar componentes shadcn existentes
4. El MCP de shadcn busca en el registro de componentes patrones existentes para copiar

Este pipeline convierte un frame de Figma en un componente de producción en minutos. Las reglas con alcance son críticas — sin ellas, Claude usaría las clases crudas de Tailwind de Figma en lugar de nuestro sistema de tokens semánticos.

Dogfooding nuestro propio MCP server

Usamos el MCP server de nuestro propio producto en desarrollo. Esto es simultáneamente útil y humilde. Cuando el MCP server se rompe en dev, lo experimentamos como desarrolladores antes de que nuestros usuarios lo hagan. Hemos detectado múltiples problemas de esta manera — bugs de resolución de herramientas, casos límite de autenticación, desbordamiento de ventana de contexto por respuestas de herramientas verbosas.

El problema de respuestas verbosas vale la pena mencionarlo. Una de nuestras herramientas MCP devuelve datos detallados de analíticas. En versiones tempranas, una sola llamada de herramienta volcaba más de 2,000 tokens de JSON en el contexto de Claude. En unas pocas llamadas de herramientas en una sesión, quemábamos presupuesto de ventana de contexto rápidamente. Aprendimos a diseñar respuestas de herramientas MCP con el costo de ventana de contexto en mente — devolver resúmenes por defecto, ofrecer endpoints de detalle para profundizar. Si estás construyendo tu propio MCP server, nuestra guía para construir tu primer MCP server cubre los fundamentos del protocolo, y patrones avanzados de MCP cubre las lecciones de diseño de respuestas que aprendimos de la manera difícil.

El patrón orquestador: subagentes a escala

Para cualquier trabajo que toque más de un proyecto en el monorepo, el hilo principal de Claude actúa como orquestador. Nunca escribe código directamente para tareas multi-proyecto. En su lugar, planifica, despacha y revisa.

Fase 0: clarificar

Antes de cualquier código, el orquestador carga contexto para el tema relevante y hace preguntas de clarificación. Lee config/projects.yaml para identificar qué proyectos están afectados y determina la pila de capas — servicios backend, módulos SDK, componentes UI.

Fase 1: plan de tareas

Las tareas se ordenan de adentro hacia afuera siguiendo lo que llamamos la cebolla DRY:

1. Tareas de backend primero — cambios de esquema, DTOs, controllers, services, tests
2. Tareas de SDK después — tipos, métodos de módulo, React hooks, tests
3. Tareas de UI al final — componentes y páginas que consumen hooks del SDK

Este orden importa. UI depende de SDK. SDK depende de API. Si construyes UI primero y descubres que la forma del API está mal, estás reelaborando tres capas en lugar de una.

Cada tarea obtiene criterios de aceptación explícitos y requisitos de tests. La descripción de la tarea incluye: qué implementar, qué test escribir y qué constituye terminado.

Fase 2: despachar

Cada subagente recibe un paquete de contexto:

Project: agent-service
Path: services/agent-service/
CLAUDE.md: services/agent-service/CLAUDE.md
Rules: .claude/rules/backend-services.md
Task: Add lastActive timestamp to agent schema.
  Update on every agent interaction.
  Test: verify timestamp updates on PATCH /agents/:id
Commands: build, test, health from projects.yaml

Las tareas independientes se despachan en paralelo. Las tareas dependientes se despachan secuencialmente — el subagente de SDK espera a que el subagente de backend termine para conocer la forma final del API.

Fase 3: verificar

El orquestador revisa todos los resultados de subagentes para consistencia multi-proyecto. ¿Los tipos del SDK coinciden con la respuesta real del API? ¿Los hooks de UI usan los métodos correctos del SDK? ¿Las aserciones de los tests coinciden con la implementación?

Esta fase detecta brechas de integración que ningún subagente individual puede ver. Un subagente de backend podría devolver { items: [...] } mientras el subagente de SDK esperaba { data: [...] }. El orquestador detecta la discrepancia.

Barreras de alcance

Hemos codificado verificaciones de radio de impacto en el CLAUDE.md:

Si un cambio toca esquemas centrales o contratos compartidos, enumera el radio de impacto completo antes de escribir cualquier código.

Disparadores específicos:

• Cambio de campo de esquema en una entidad central (Agent, Interaction, Scenario) — mapear TODOS los consumidores downstream primero
• Más de 5 tareas en una sesión — dividir en múltiples PRs
• Cambio en módulo compartido (el paquete NestJS común) — cada servicio depende de él, ¿qué se rompe?
• Cambio de contrato API (forma de respuesta, códigos de estado) — SDK y todas las apps consumidoras pueden romperse

Estas barreras han prevenido varios desastres de "renombré un campo y rompí 12 cosas."

Qué compone bien (y qué entra en conflicto)

Skills más MCP servers componen naturalmente porque operan a niveles de abstracción diferentes. Reglas con alcance más CLAUDE.md raíz componen bien porque dividen amplitud y profundidad. La fricción viene de demasiados skills (parálisis de decisión), respuestas MCP verbosas (quema de contexto) y archivos CLAUDE.md monolíticos que Claude ignora pasadas las primeras 200 líneas.

Composiciones naturales

Skills + MCP = flujo de trabajo con datos. Los Skills definen los pasos. Los MCP servers proporcionan datos externos. El skill de deploy conoce la secuencia, el MCP de Slack publica los resultados. El skill de UI conoce los patrones de componentes, el MCP de Figma proporciona el diseño. Nunca se pisan porque operan a niveles diferentes de abstracción.

Reglas con alcance + CLAUDE.md raíz = contexto sin exceso. El CLAUDE.md raíz se mantiene navegable a ~500 líneas. Las reglas con alcance proporcionan contexto profundo para lo que sea que estés tocando — más de 2,600 líneas de reglas que se cargan selectivamente. Al editar un servicio backend, Claude ve patrones de backend, trampas de Mongoose y reglas de contrato API. Al editar un componente React, ve tokens de diseño, reglas de spacing y patrones de shadcn. La misma sesión puede alternar entre ambos.

Hooks + CLAUDE.md = defensa en profundidad. CLAUDE.md dice "no hacer deploy a producción sin preguntar." El hook lo bloquea mecánicamente. CLAUDE.md reduce los intentos. Los Hooks atrapan los que se escapan. Juntos crean seguridad confiable sin que ninguno sea perfecto por sí solo.

Archivos de lecciones + globs con alcance = memoria institucional. Cuando Claude toca un modelo Mongoose, automáticamente ve la lección sobre condiciones de carrera de doc.save(). Cuando escribe una llamada entre servicios, ve la lección sobre headers de workspace faltantes. Estos previenen errores recurrentes sin saturar el CLAUDE.md principal.

Orquestador + subagentes + CLAUDE.md de servicio = trabajo paralelo multi-proyecto. Cada subagente obtiene exactamente el contexto que necesita. El subagente de backend lee el CLAUDE.md del servicio y las reglas de backend. El subagente de SDK lee las reglas del SDK. El orquestador rastrea dependencias y revisa consistencia. Trabajo que le tomaría horas de cambio de contexto a un solo agente sucede en paralelo.

Puntos de fricción

Demasiados skills = parálisis de decisión. Cuando Claude ve más de 50 skills, a veces elige el incorrecto o pregunta "¿quisiste decir /deploy o /deploy-prod?" Hemos consolidado donde es posible y deprecado skills que se superponen (prefijados con dontuse- para que sigan en control de versiones pero claramente retirados).

MCP servers demasiado verbosos queman contexto. La herramienta de analíticas de nuestro propio MCP server inicialmente devolvía objetos completos de datasets. Unas pocas llamadas de herramientas en una conversación quemaban miles de tokens de contexto. Rediseñamos las respuestas para devolver resúmenes primero, con opciones explícitas de profundización. Regla general: las respuestas de herramientas MCP deberían estar por debajo de 500 tokens a menos que el usuario pida detalle.

Todo en CLAUDE.md falla a escala. Lo probamos empíricamente. Nuestro CLAUDE.md de 600 líneas tenía reglas sobre patrones Mongoose, convenciones de componentes React, procedimientos de deploy y estrategias de testing todo en un archivo. Claude seguía de manera confiable las reglas en las primeras 200 líneas e intermitentemente ignoraba reglas más profundas en el archivo. Dividir en reglas con alcance lo arregló — cada archivo de reglas tiene 100-300 líneas, bien dentro de la atención confiable de Claude.

Skills sin descripciones claras nunca se activan. Tenemos algunos skills con descripciones genéricas como "Code quality utilities" que Claude nunca invoca de forma espontánea. Los skills con descripciones específicas — "Deploy chanl-platform to staging or production on Fly.io" — se invocan de manera confiable. La descripción es una función de coincidencia, no documentación.

El traspaso de contexto a subagentes es imperfecto. Los subagentes no pueden ver la conversación del orquestador. Reciben una descripción de tarea y rutas de archivo, pero pierden matices de la discusión. Lo hemos mitigado haciendo las descripciones de tareas muy explícitas — incluir el "por qué" y las restricciones, no solo el "qué."

Qué haríamos diferente

Hooks primero, reglas con alcance desde el primer día, y la mitad de skills con el doble de calidad en las descripciones. Esos tres cambios nos habrían ahorrado meses de retrabajo y docenas de incidentes donde las barreras blandas de CLAUDE.md fallaron bajo presión.

Empezar con Hooks para seguridad

Pasamos nuestros primeros tres meses con todas las reglas de seguridad en CLAUDE.md. "Nunca hacer push a main." "Nunca hacer deploy sin preguntar." "Nunca borrar datos de producción." Estas reglas funcionaban la mayor parte del tiempo. Las fallas eran raras pero severas.

Los Hooks deberían ser lo primero que configures, no lo último. Cualquier regla donde una sola violación cause daño real pertenece a un hook. CLAUDE.md es para orientación y patrones. Los Hooks son para restricciones duras.

Usar reglas con alcance desde el día 1

Escribimos un CLAUDE.md monolítico durante meses antes de descubrir las reglas con alcance. Para cuando lo dividimos, el archivo tenía más de 600 líneas y Claude estaba ignorando secciones enteras.

Si estás empezando un proyecto nuevo: crea .claude/rules/ inmediatamente. Pon tus reglas específicas de dominio en archivos con alcance con patrones glob. Mantén el CLAUDE.md raíz como un hub de navegación que sea genuinamente rápido de escanear.

Menos Skills, mejores

Nuestro conteo de skills creció orgánicamente. Alguien necesitaba un atajo de deploy, así que escribimos /deploy. Luego /deploy-prod para un flujo ligeramente diferente. Luego /deploy-staging como wrapper. Ahora tenemos tres skills donde uno con enrutamiento de argumentos bastaría.

Empieza con la pregunta: "¿Es este un flujo de trabajo distinto, o una variante de uno existente?" Si es una variante, agrega manejo de argumentos al skill existente. Solo crea un skill nuevo cuando el flujo de trabajo sea fundamentalmente diferente.

Mejores descripciones de Skills

El campo description en el frontmatter del skill es la línea más importante del archivo. Inicialmente lo tratamos como documentación. En realidad es una función de coincidencia — Claude lo lee para decidir si invocar el skill.

Mal: "Helpful utility for code operations" Bien: "Review + reflect + commit in one flow" Mejor: "Deploy chanl-platform to staging or production on Fly.io"

Verbos específicos, sustantivos específicos, destinos específicos. Claude coincide con estos.

Invertir en archivos de lecciones temprano

Nuestros archivos de lecciones (lessons-backend.md, lessons-integration.md, etc.) son los artefactos con mayor retorno de inversión en toda la configuración. Cada entrada toma 5 minutos escribirla y ahorra más de 30 minutos cada vez que la misma situación se presenta.

El formato importa: Trigger (¿cuándo aplica esto?), What happened (¿qué salió mal?), Why wrong (causa raíz), Fix (qué hacer en su lugar). Con alcance vía globs para que se carguen automáticamente al tocar archivos relevantes.

Empieza a registrar lecciones desde tu primera sesión de depuración. Te lo agradecerás en una semana.

Diseñar respuestas de herramientas MCP para presupuesto de contexto

Cada token en una respuesta de herramienta MCP es un token que Claude no puede usar para razonar. Lo aprendimos cuando nuestra herramienta MCP de analíticas empezó a devolver blobs JSON de 2KB. Tres llamadas de herramientas en una conversación y Claude se quedaba sin espacio para pensar.

Diseña tus respuestas MCP como respuestas API para móvil: devuelve el payload mínimo útil. Ofrece paginación. Deja que el llamador solicite detalle cuando lo necesite. Tu yo del futuro — quemando presupuesto de ventana de contexto en una sesión compleja de refactoring — apreciará la moderación.

El stack de extensiones en acción: una sesión real

Una sola funcionalidad toca los siete puntos de extensión en secuencia: carga de contexto, planificación de tareas, activación de reglas con alcance, despacho de subagentes, verificación del orquestador, commit con compuerta de hook, y notificación al equipo vía MCP. Aquí está ese flujo para una tarea real: agregar un timestamp lastActive a los agentes que se actualice cada vez que el agente maneje una interacción.

1. El contexto se carga (/context agents). Conocimiento preconstruido sobre la arquitectura del agent-service, esquema, consumidores. Ahorra 10 minutos de exploración.

2. El plan crea tareas (/plan "add lastActive to agents"). El orquestador identifica tres capas: backend (esquema + servicio), SDK (tipos + hooks), UI (columna en lista de agentes). Crea tareas en orden de dependencia.

3. Las reglas con alcance se activan. Cuando el subagente de backend abre services/agent-service/src/agents/agent.schema.ts, las reglas de backend y archivos de lecciones se cargan automáticamente. Claude ve el patrón Mongoose de findByIdAndUpdate, no doc.save(). Ve la lección sobre el .id virtual perdido en serialización.

4. El subagente implementa. El subagente de backend agrega el campo al esquema, actualiza el servicio para establecer lastActive en la interacción, escribe un test. El subagente de SDK agrega el tipo y actualiza el hook. El subagente de UI agrega la columna.

5. El orquestador verifica. Verifica que el tipo del SDK coincida con la respuesta del API. Verifica que la columna de UI referencie el hook del SDK, no una llamada directa al API. Ejecuta la suite de tests.

6. El commit pasa por hooks (/commit --push). El skill de commit revisa los cambios, el hook deja pasar los comandos relacionados con staging pero bloquearía cualquier deploy accidental a producción. Después del push, se envía un mensaje al canal de Slack del equipo vía MCP.

Siete puntos de extensión, una tarea: CLAUDE.md para navegación, reglas con alcance para patrones, skill para flujo de trabajo, hook para seguridad, MCP para Slack, subagentes para trabajo paralelo, archivos de lecciones para evitar trampas conocidas.

Ninguno de ellos es complejo individualmente. El poder está en la composición.

Para empezar: una secuencia práctica

Empieza con hooks y un CLAUDE.md mínimo en la semana uno, agrega reglas con alcance en la semana dos, escribe tus primeros skills en la semana tres, y empieza a registrar lecciones en la semana cuatro. Los MCP servers y patrones orquestador vienen después — se acumulan sobre la base.

Semana 1: Hooks + CLAUDE.md mínimo. Escribe hooks para tus restricciones de seguridad duras. Escribe un CLAUDE.md de menos de 200 líneas que cubra estructura del proyecto, comandos clave y las 5 reglas que más te importan.

Semana 2: Reglas con alcance. Crea .claude/rules/ con 2-3 archivos para tus dominios principales (backend, frontend, deploy). Agrega patrones glob. Mueve contenido específico de dominio fuera del CLAUDE.md raíz.

Semana 3: Primeros skills. Escribe 3-5 skills para tus flujos de trabajo más comunes. Commit, deploy y test son buenos puntos de inicio. Enfócate en las descripciones.

Semana 4: Archivos de lecciones. Empieza a registrar lecciones de depuración. Un archivo por dominio. Con alcance vía globs. Esto se acumula — cada semana el archivo de lecciones se vuelve más valioso.

Mes 2: MCP servers. Conecta MCP servers externos que coincidan con tu flujo de trabajo (Figma para diseño a código, Slack para comunicación, base de datos para consultas). Construye tu propio MCP server si estás usando tu propio producto en desarrollo.

Mes 3: Patrón orquestador. Si estás en un monorepo o configuración multi-proyecto, documenta el patrón de despacho de subagentes. Escribe archivos CLAUDE.md a nivel de servicio. Construye el skill /dispatch.

La clave es empezar simple e iterar. Cada artefacto de configuración debería existir porque resolvió un problema real, no porque parecía teóricamente útil.

Este artículo es el más específico de la serie porque se basa en uso real de producción, no teoría. Los patrones aquí evolucionaron durante un año de uso diario, cientos de sesiones de depuración y más reescrituras de CLAUDE.md de las que me gustaría contar.

El stack de extensiones no es un destino — es infraestructura que crece con tu base de código. Los más de 50 skills, reglas con alcance, hooks de seguridad e integraciones MCP que ejecutamos hoy empezaron como un CLAUDE.md de 100 líneas y un sueño. Se verán diferentes en otro año.

Si estás más temprano en el viaje, el resto de esta serie cubre los fundamentos. La Parte 1 tiene el modelo mental para decidir qué punto de extensión usar. La Parte 2 profundiza en CLAUDE.md, hooks y skills. La Parte 3 cubre MCP servers e integraciones externas. Y si quieres ver cómo funciona la gestión de herramientas MCP a escala o qué pasa cuando tu agente tiene 30 herramientas y no sabe cuándo usar cada una, esos artículos tienen el detalle técnico.

Construye la red de seguridad primero. Agrega contexto segundo. Automatiza flujos de trabajo tercero. Esa es la secuencia que funciona.

Aprende IA Agéntica

Una lección por semana: técnicas prácticas para construir, probar y lanzar agentes IA. Desde ingeniería de prompts hasta monitoreo en producción. Aprende haciendo.

Subscribe

500+ ingenieros suscritos