El ecosystem completo de Claude Code

Course: B1 — Claude Code Pro: Lo que no sabías Lesson: 1 de 10 Objetivo: Entender el alcance completo de Claude Code a través de casos reales y hacer un gap analysis personal de qué features usas vs. cuáles no.

El iceberg: por qué la mayoría usa el 20%

Claude Code funciona bien desde el primer minuto. Instalas, escribes un prompt y ya recibes valor. No hay un momento de fricción que te obligue a explorar más allá del default — y eso hace que la mayoría de developers lleve meses usando la herramienta al veinte o treinta por ciento de su capacidad real.

El patrón se repite: devs que llevan meses con Claude Code no han tocado el sistema de instrucciones persistentes, nunca configuraron permisos específicos para sus proyectos, desconocen los hooks de automatización, no han explorado el modo no-interactivo para pipelines. Están usando la punta del iceberg.

Esta lesson existe para construir el mapa completo. El objetivo no es dominar cada pieza hoy — es saber qué existe, entender cómo se conecta, y al final del módulo tener claro dónde están tus gaps personales.

Los 8 componentes del ecosystem

Claude Code no es solo un chat en la terminal. Es un ecosystem de ocho capas que trabajan juntas:

1. El CLI (interfaz central)

El punto de entrada a todo. El comando claude arranca la sesión interactiva. Pero el CLI también expone flags para modo headless, control de presupuesto, selección de modelo y más. La mayoría de los usuarios lo usa solo en modo conversacional — desconociendo que el mismo binario sirve para automatización sin supervisión humana.

2. El sistema de instrucciones (CLAUDE.md hierarchy)

Claude lee archivos de instrucciones en texto plano antes de cada sesión. No hay que repetir el contexto en cada conversación — vive en archivos que Claude carga automáticamente. Hay tres niveles:

• Global (~/.claude/CLAUDE.md): aplica a todos tus proyectos en esa máquina. Convenio de nombres que siempre usas, tu stack preferido, preferencias de estilo.
• Proyecto (CLAUDE.md en la raíz): las instrucciones de ese proyecto específico. Tech stack, arquitectura, convenciones del equipo, personas del equipo.
• Subdirectorio (CLAUDE.md en cualquier folder): instrucciones para una parte específica del código — "este directorio es el frontend, sigue estas reglas de componentes".

Claude agrega todos los niveles aplicables al iniciar. El resultado: Claude ya "sabe" tu proyecto desde el primer mensaje.

3. Configuración y permisos (settings.json hierarchy)

Controla qué puede y qué no puede hacer Claude en tu entorno: qué comandos puede ejecutar, qué herramientas tiene disponibles, qué archivos puede tocar, variables de entorno que debe conocer.

Tres niveles con jerarquía explícita — el más específico gana:

• ~/.claude/settings.json — global (menor precedencia)
• .claude/settings.json — proyecto (precedencia media)
• .claude/settings.local.json — local, no se commitea (mayor precedencia)

El nivel local existe para configuraciones personales de tu máquina que no deben pisarse con las del equipo — credenciales locales, paths específicos de tu setup.

4. Skills (comandos personalizados)

Las skills son comandos que tú creas para Claude, escritos como archivos Markdown en .claude/skills/. Se activan con /nombre-del-skill. Pueden hacer cualquier cosa: llamar herramientas externas, ejecutar código, preparar contexto específico, correr workflows completos.

Las skills pueden ser de proyecto (solo accesibles en ese contexto) o globales (disponibles en cualquier proyecto). Existe una comunidad creciente que comparte skills para revisiones de seguridad, generación de tests, manejo de branches, documentación, entre muchos otros.

5. Hooks (automatización event-driven)

Los hooks son acciones que corren automáticamente en respuesta a eventos de Claude. Se configuran en settings.json. Los eventos disponibles:

• PreToolUse — antes de que Claude llame cualquier herramienta
• PostToolUse — después de cada tool call
• Stop — cuando Claude termina su respuesta
• Notification — cuando Claude envía una notificación al usuario

Casos de uso: correr tests automáticamente al terminar, validar que ningún comando destructivo se ejecute sin confirmación, hacer logging de qué cambió Claude, enviar notificación al teléfono cuando termina una tarea larga.

6. MCP (Model Context Protocol)

Estándar abierto de Anthropic que define cómo Claude se conecta con herramientas externas. Antes de MCP, integrar Claude con una base de datos o un API externo requería soluciones custom. Con MCP, hay un protocolo estándar: cualquiera construye un servidor MCP para su herramienta, y Claude lo puede usar.

Servidores MCP disponibles: bases de datos (PostgreSQL, SQLite, Supabase), GitHub, Notion, web browsing, sistemas de archivos remotos, Slack, Figma, Linear. Cuando conectas varios, Claude se convierte en un hub de operaciones que puede coordinar múltiples sistemas.

La configuración vive en settings.json bajo la clave mcpServers, o se gestiona con claude mcp add.

7. Plan Mode

Modo deliberado donde Claude presenta un plan antes de ejecutar cualquier cambio. Claude describe los pasos que va a seguir, espera aprobación, y solo entonces actúa. Útil para tareas complejas o destructivas donde no quieres sorpresas.

Se activa con Shift+Tab antes de enviar un mensaje en la TUI.

8. Unattended automation (modo no-interactivo)

Claude puede trabajar sin que estés supervisando. Con el flag -p (print/headless), Claude toma el prompt, ejecuta la tarea completa y devuelve el resultado — sin interfaz interactiva. Esto habilita usar Claude en CI/CD, scripts cron, pipelines de automatización.

El flag --max-budget-usd controla cuánto puede gastar, y hay controles granulares sobre qué herramientas puede usar en modo autónomo.

El mental model: capas de personalización

El ecosystem no es una lista de features independientes — es un sistema de capas que se suman:

Claude base (modelo)
  + instrucciones persistentes (CLAUDE.md global → proyecto → subdirectorio)
  + herramientas y permisos (settings.json global → proyecto → local)
  + automatizaciones (hooks en settings.json)
  + herramientas externas (MCP servers)
  + comandos propios (skills)
  = Tu Claude Code personalizado

El resultado es que dos developers usando el mismo Claude Code pueden tener experiencias completamente distintas — uno tiene un asistente genérico, el otro tiene un colega que ya conoce su proyecto, sus patrones, sus reglas del equipo.

La clave conceptual es que las capas no son independientes: se multiplican. Instrucciones bien escritas hacen que cada respuesta de Claude sea más precisa. Permisos afinados eliminan fricciones de confirmación innecesaria. Hooks automatizan validaciones que antes requerían memoria del developer. Skills encapsulan conocimiento repetido. Cuando tres o más capas funcionan correctamente juntas, el resultado no es la suma — es el producto.

Casos reales de adopción

Simon Willison (simonwillison.net) — developer veterano conocido por sqlite-utils, Datasette y por escribir con honestidad sobre AI tooling — ha documentado su proceso con Claude Code en su blog. Un patrón que describe resonó con muchos en la comunidad: por meses usó la herramienta de forma puramente conversacional, repitiendo contexto en cada sesión. Al descubrir el sistema de instrucciones persistentes, la pregunta obvia fue por qué había tardado tanto en usarlas. No es negligencia — es que la herramienta funciona bien sin ellas, así que no hay fricción que te empuje a explorar.

Patterns de comunidad (r/ClaudeAI, foros de dev) — hay reportes recurrentes de developers que describen el momento de "caer" en que llevaban meses usando el basic setup cuando alguien les mostró una feature avanzada. El gap más común reportado: las instrucciones persistentes de proyecto. El segundo más común: los hooks.

Equipos que van all-in — cuando equipos de desarrollo adoptan el ecosystem completo — instrucciones de proyecto bien escritas, permisos afinados, skills compartidas por el equipo — reportan que la conversación cambia. En vez de explicarle a Claude el contexto cada vez, Claude ya lo sabe. En vez de repetir los patrones del equipo, Claude los sigue por default.

El patrón de la curva discontinua — una observación recurrente en foros y comunidades de Claude Code: la curva de valor no es lineal. Hay un plateau durante las primeras semanas de uso básico, y luego un salto pronunciado en el momento en que el developer configura correctamente las instrucciones y los permisos. Ese salto suele describirse como "el día que mi Claude Code se convirtió en mi Claude Code" — el momento donde la herramienta deja de sentirse genérica y empieza a sentirse personalizada. La buena noticia: ese salto no requiere semanas — requiere unas horas bien invertidas y el mapa mental correcto.

Anti-patterns comunes

Instalar y nunca configurar — usar Claude Code como chat sin tocar el sistema de instrucciones. Resultado: repites contexto en cada sesión.

Poner todo en las instrucciones globales — mezclar instrucciones de distintos proyectos en el nivel global contamina el contexto. Claude lleva información irrelevante a cada proyecto.

Permisos demasiado permisivos — un allow: everything en la configuración de permisos elimina los controles de seguridad. Claude puede ejecutar comandos destructivos sin fricción.

No usar Plan Mode para tareas complejas — saltarse la revisión del plan en tareas que modifican muchos archivos o hacen operaciones irreversibles es un riesgo innecesario.

Ignorar los hooks — configurar Claude sin hooks significa que cada tarea termina y tú tienes que acordarte de correr los tests, actualizar el log, revisar el diff.

Gap analysis como método

El gap analysis es el ejercicio central de esta lesson. La pregunta es simple: de los 8 componentes del ecosystem, ¿cuáles usas regularmente, cuáles conoces pero no usas, y cuáles no conocías?

Los gaps más accionables son los del segundo grupo — conoces la feature pero no la usas. La barrera es solo tiempo y práctica, no aprendizaje desde cero.

El segundo paso del gap analysis es priorizar. No todos los gaps valen lo mismo para cada developer. Para alguien que trabaja con múltiples servicios externos, conectar Claude con MCP puede ser transformador. Para alguien que hace muchas operaciones complejas de refactoring, dominar Plan Mode puede ser la inversión con más retorno. La priorización debe alinearse con el trabajo real que haces — no con una jerarquía universal de features.

El tercer paso es comprometerse con uno. El error más común después de hacer el gap analysis es identificar cinco gaps y no trabajar ninguno porque "son todos importantes". La metodología correcta: elige uno, impleméntalo en tu proyecto real esta semana, verifica que está funcionando, y solo entonces pasa al siguiente.

El ejercicio práctico de esta lesson (checklist de 40 items) desglosa cada componente en features específicas para ayudarte a hacer ese inventario con granularidad. Termina con la identificación de tus top-5 gaps y un plan concreto para la primera semana.

Fuentes

• Anthropic. "Claude Code overview" — documentación oficial. https://docs.claude.com/en/docs/claude-code/overview
• Anthropic. "Claude Code settings" — jerarquía de configuración. https://docs.claude.com/en/docs/claude-code/settings
• Anthropic. "Claude Code skills" — referencia de skills. https://docs.claude.com/en/docs/claude-code/skills
• Anthropic. "Claude Code quickstart" — patrón de onboarding. https://docs.claude.com/en/docs/claude-code/quickstart
• Anthropic. "Introducing Claude Code" — contexto de lanzamiento. https://www.anthropic.com/news/claude-code
• Willison, Simon. Blog posts sobre AI tooling. https://simonwillison.net/tags/claude-code/
• Latent Space (swyx). Episodios sobre AI engineering en producción. https://latent.space/