DEV M3 · Claude Code, MCP & Integration — Resumen de estudio

Curso 3 de 5 · 21 pantallas, 8 secciones, 8 checkpoints, ~142 min

El problema de fondo: lo que funciona en tu máquina tiene que funcionar cuando otro lo ejecuta, en producción y contra sistemas reales. Permisos, contexto durable, empaquetado, MCP y autenticación empresarial.

1. Loop de Claude Code, permission modes y gates humanos

Loop: explore → plan → code. Primero lee y entiende, luego propone un plan y solo con tu aprobación edita y ejecuta. Plan mode lo mantiene en exploración (sin edits ni comandos).

Dónde vive la configuración:

• Usuario: ~/.claude/settings.json. Todos tus proyectos.
• Proyecto: .claude/settings.json, que se commitea. Todo el equipo.
• Local: .claude/settings.local.json. Personal y git-ignorado.
• Enterprise: managed-settings.json. Nadie puede sobrescribirla.

Una regla deny siempre gana a una allow, sea cual sea el modo. El control más durable es un deny a nivel enterprise (aplica incluso en bypass).

¿Dónde va el gate humano? Pregunta: ¿qué es lo peor si esto corre sin que nadie lo revise?

• Bajo riesgo y reversible (formato, edits en el directorio de trabajo) → sin gate (acceptEdits).
• Difícil de revertir o una ruta sensible (escritura fuera del directorio, comando destructivo, archivo protegido) → gate antes de ejecutar (deny rule, default o plan).
• Código marcado como sensible → el agente nunca es el único gate: una persona revisa antes del merge.

Revisión de código con IA: son hallazgos para priorizar, no un veredicto. Confía en lo que se puede probar con el diff (null check faltante, recurso sin cerrar) y verifica las líneas que cita. Lo que afirme sobre el runtime u otros sistemas es una hipótesis a probar. Dale las convenciones del equipo para que no tenga que adivinarlas.

⚠️ Watch out: con bypass para "solo renombrar endpoints", el patrón /v1/legacy/ coincidió también con /deploy/config/prod/ y un script borró 3 archivos de producción. Lo que habría pedido confirmación era la ejecución del script (en acceptEdits, un rm directo dentro del directorio no pide confirmación; en default sí). Pon deny rules antes de cambiar de modo; si quieres menos prompts, usa auto en vez de bypass.

Checkpoint 1: piezas C (allow Bash(npm run:*), deny rm y git push) + D (deny Read(.env.production)). Gate: b, un humano aprueba el cambio al archivo de configuración de despliegue antes de escribirlo.

2. Contexto durable: CLAUDE.md, rules, hooks y subagents

• CLAUDE.md: se lee en cada sesión y se antepone al prompt. /init genera una versión inicial que debes validar.
  • Contenido: comandos de tests, convenciones del framework, rutas prohibidas, decisiones de estilo.
  • Fallo principal: el tamaño. Cada línea diluye las demás. Por encima de unas pocas centenas de líneas, audítalo.
• Rules files (.claude/rules/): guía específica por ruta. Lo que los acota es el paths glob del frontmatter, no la carpeta. Sin paths cargan siempre, como CLAUDE.md.
  • "Nunca modificar el schema" → CLAUDE.md.
  • "Todo SQL del módulo db con transacción explícita" → .claude/rules/database.md con paths: ["src/db/*/.sql"].
• Hooks: scripts en eventos del ciclo de vida. Se ejecutan siempre, decida lo que decida el modelo (guardrail vs convención). Se configuran en settings o con /hooks.
  • PreToolUse: antes de la tool. Puede bloquear con exit code 2 (la razón va a stderr y el agente la ve).
  • PostToolUse: después. No bloquea; sirve para formatear, correr tests o hacer auditoría.
  • UserPromptSubmit: antes de procesar el prompt (inyectar contexto o validar).
  • Stop: al terminar la respuesta.
  • Notification: cuando se pide permiso o tras 60 s inactivo.
  • SessionStart / SessionEnd: inicialización y cierre.
• Subagents: contexto aislado; solo devuelven el resultado.
  • Explore y Plan (built-in) omiten CLAUDE.md y el git status para ser rápidos. General-purpose los carga.
  • Si una regla del proyecto debe respetarse → general-purpose o un subagent custom.
  • Los subagents custom no ven los Skills salvo que los listes en su frontmatter (.claude/agents).

⚠️ Watch out: con un CLAUDE.md de 847 líneas, la regla de "no tocar /legacy/tokens/" (línea 347) quedó diluida y se editó igual. El historial y las notas archivadas no van ahí. La regla que no puedes permitirte diluir debería ser un hook.

Checkpoint 2: PreToolUse + un script que lee la tool call de stdin y sale con código 2 si la ruta es .env.production (razón en stderr).

3. Empaquetar workflows: Skills, comandos y plugins

El mismo SKILL.md en 4 runtimes:

3 reglas de portabilidad:

1. La descripción es el criterio de coincidencia.
2. No asumas un filesystem ni tools locales.
3. Los subagents no heredan Skills.

• Comandos personalizados: hoy se recomiendan los Skills (invocas con /skill-name o se cargan solos). .claude/commands/ es legacy. Para que solo corra cuando lo llames: disable-model-invocation: true.
• Plugins: agrupan Skills, hooks, subagents y MCP servers en una unidad versionada.
  • Sus comandos llevan el nombre del plugin como namespace (/payments:run-tests). Renombrar el plugin renombra todos sus comandos.
  • Marketplaces: el oficial viene incluido; se agregan con /plugin marketplace add <owner/repo>.
  • Enterprise: despliegue por managed settings, allowlist de marketplaces + extraKnownMarketplaces para empujarlos a todos. El scope managed tiene prioridad y no se puede sobrescribir.
  • Riesgo: un plugin solo lleva lo que empaqueta. Si dependías de un deny rule o un hook local que no incluiste, esa protección no viaja.

⚠️ Watch out: un Skill con /Users/alexmorgan/projects/deploy-utils/validate.sh se instaló bien en todas partes pero falló en todas menos en la máquina del autor; otro necesitaba DEPLOY_TOKEN sin documentarlo. Usa $CLAUDE_PROJECT_DIR (scripts del proyecto) y ${CLAUDE_PLUGIN_ROOT} (scripts del plugin), incluye los assets, documenta y valida las variables de entorno, y prueba en una máquina limpia.

Checkpoint 3: Claude Code → SKILL.md en .claude/skills · Messages API → headers beta + sin dependencias locales · Agent SDK → settingSources explícito · Managed → recurso de agente + header beta. Checkpoint 4: defecto C (ruta absoluta) · fix C ($CLAUDE_PROJECT_DIR).

4. Servidores MCP

• MCP: un servidor expone tools, resources y prompts a cualquier cliente MCP. Se construye una vez y se usa en todas partes.
  • Resource: datos de solo lectura que el cliente pone en contexto directamente. Direct (dirección fija) o templated (con un parámetro en la dirección). Verifica que tu cliente los soporte.
  • Prompt: plantilla verificada que se invoca por nombre, para que todos los clientes obtengan la misma calidad.
• Transportes: stdio (local, subproceso) · HTTP (remoto; el recomendado) · SSE (legacy).
• Costo de contexto: por defecto Claude Code difiere las definiciones de tools y las busca cuando hacen falta. Hay un modo opt-in que las carga al inicio si caben en ~10% de la ventana. Conecta solo lo que necesitas.
• Prompt caching:
  • Breakpoint con cache_control: ephemeral (hasta 4). Orden: tools → system → messages.
  • TTL de 5 min desde la última lectura; opcional 1 h con ttl: "1h".
  • Un solo carácter distinto invalida la caché.
  • Mínimo ~1,024 tokens para cachear.
• RAG: clásico (chunks + embeddings indexados de antemano) vs agentic search (busca en el momento). Escala con costo plano por request, pero solo es tan bueno como lo que encuentra (usa nombres de archivo descriptivos).

Scopes:

• Local: ~/.claude.json bajo la ruta del proyecto. Personal, solo ese proyecto.
• User: en tus settings personales. Todos tus proyectos, no se comparte.
• Project: .mcp.json en la raíz, se commitea. Todo el equipo. Un servidor stdio arranca en la máquina de cada quien (cada uno necesita, por ejemplo, Node instalado).
• Enterprise: managed settings, lo empuja el administrador.

• Permisos por tool: mcp__server__tool. Puedes permitir mcp__github__create_issue y negar las tools de escritura. Un deny a una tool gana sobre un allow al servidor. En el API Connector, enabled por tool decide si el modelo siquiera la ve (control de alcance y de costo de contexto).
• GitHub MCP: HTTP remoto. Autenticación con Personal Access Token como Bearer, desde una variable de entorno, nunca inline en .mcp.json.
• Linear MCP: OAuth (flujo de login en el navegador; el token se guarda solo).

⚠️ Watch out: se commiteó una API key en .mcp.json. En 48 h estaba en el repo, en 3 máquinas y en CI. Sobrescribir el archivo no la saca del historial → hay que rotarla (y la rotación rompió otros 2 servicios). Correcto: "Bearer ${WAREHOUSE_MCP_TOKEN}". Prevención en 2 capas: regla en CLAUDE.md + hook PreToolUse que bloquee credenciales inline.

Checkpoint 5: SQLite local = stdio + Local · búsqueda de código del equipo = HTTP + Project · experimento = stdio o HTTP + Local · escáner de seguridad para todos = HTTP + Enterprise.

5. Integración empresarial y autenticación

Preguntas que un prototipo ignora: ¿con qué identidad actúa el modelo y es auditable? ¿A qué datos accede y dónde salen? ¿Un admin puede bloquear la configuración? ¿Queda registro para una auditoría?

Manejo de secretos (3 prácticas):

1. Separación: el config tiene la referencia, nunca el valor.
2. Dónde vive el valor: variable de entorno (local o de corta vida) o un secret store (compartido o auditado; una rotación actualiza a todos).
3. Rotación: periódica y de inmediato ante una sospecha de exposición. Un valor en código commiteado no se puede rotar limpiamente.

Además: alcance mínimo por credencial y un registro de qué servicio usa cada una.

Entornos regulados: configuración bloqueada por managed settings · audit hooks PostToolUse · residencia (endpoint HTTP regional + plataforma con región fija).

Modernización de código legacy:

• Plan mode para explorar.
• Hooks que bloqueen rutas sensibles.
• CLAUDE.md con los patrones nuevos (para que no "regrese" a los patrones legacy que lee).
• 3 preguntas antes de empezar:
  1. ¿Cuál es el radio de impacto si algo sale mal?
  2. ¿Cómo se auditan los cambios?
  3. ¿Quién aprueba cada fase?

⚠️ Watch out: OAuth funcionaba en staging y en producción daba redirect URI mismatch. Las redirect URIs se registran por host; muchas empresas exigen apps OAuth separadas por entorno. Inclúyelo en el checklist de despliegue.

Checkpoint 6: Fix B. El 401 indica una key rechazada y hay un secreto en texto plano en un archivo de ruta conocida → rotar + mover a una variable de entorno en el runner de CI y referenciarla. (A deja el mismo defecto de almacenamiento; C usa OAuth, que no corresponde a una cuenta de servicio.)

Tarea acumulativa (3 archivos, 3 bugs)

1. settings.json: bypassPermissions en una estación de producción → acceptEdits (el deny de .env.production estaba bien).
2. SKILL.md: ruta absoluta /Users/priya/... → $CLAUDE_PROJECT_DIR/scripts/validate-migration.sh.
3. .mcp.json: key inline sk-prod-... → Bearer ${WAREHOUSE_MCP_TOKEN} (y rotar la key expuesta).

Para recordar (7 takeaways)

1. El permission mode es una decisión de riesgo, no de velocidad. Los deny rules cubren lo que el modo no cubre.
2. Una revisión de código con IA da hallazgos que priorizar, no un veredicto.
3. Un Skill es portable, pero hay que diseñarlo para que lo sea.
4. Contexto durable = el mecanismo correcto para cada cosa (CLAUDE.md, rules, hooks, subagents).
5. Una configuración compartible necesita componentes portables (rutas relativas, variables documentadas, prueba en una máquina limpia).
6. Transporte y scope son decisiones independientes con consecuencias que dependen una de otra (un servidor stdio en .mcp.json parece compartible y no lo es).
7. En empresas, identifica antes del despliegue: OAuth, variables de entorno, hooks de auditoría, managed settings.