Claude Code en profundidad: del terminal a un sistema operativo de agentes

Claude Code no es simplemente una herramienta que escribe código más deprisa. Es una forma distinta de organizar el trabajo: un agente con acceso al repositorio, al terminal, a las pruebas y a las herramientas que decidas conectarle. Cuando se configura con contexto, método, permisos y revisión, puede convertirse en una capacidad compartida por todo un equipo.

En Impulsa3 llevamos esa idea a un terreno más amplio con I3OS, nuestro caso práctico de agentización. I3OS no nació para acumular bots ni para sustituir el criterio profesional. Nació para conectar el contexto de cada cliente con métodos reutilizables, datos autorizados, herramientas y revisión humana.

Claude Code es una de las piezas que mejor permite entender ese cambio. Este artículo reúne los fundamentos, la configuración, las Skills, los Hooks, MCP, los subagentes, la automatización, los plugins y la ejecución en tu propio equipo. La tesis es sencilla: la productividad no aparece cuando le das más autonomía al modelo, sino cuando diseñas mejor el sistema en el que trabaja.

1. Qué cambia cuando pasas del asistente al agente

Un asistente conversacional responde a lo que le das. Un agente puede trabajar con el entorno que le autorizas. En Claude Code, ese entorno suele ser un repositorio: archivos, comandos, Git, tests, documentación y, si lo configuras, servicios externos.

• Chatbot: recibe texto y devuelve texto. El usuario mueve manualmente la información y ejecuta las decisiones.
• Copiloto: sugiere líneas, funciones o respuestas dentro de una interfaz de desarrollo.
• Agente: recibe un resultado deseado, inspecciona el contexto, usa herramientas, modifica artefactos y verifica lo que ha hecho.
• Sistema agentizado: convierte esa capacidad en un método repetible, medible, gobernado y reutilizable por un equipo.

Por eso Claude Code puede explicar una base de código, implementar una funcionalidad que afecta a varios ficheros, ejecutar pruebas, analizar un fallo de CI, preparar una revisión o proponer un cambio de arquitectura. Pero también puede equivocarse a gran velocidad. El acceso a más herramientas no elimina la necesidad de criterio: la hace más importante.

Esta es la conexión con lo que entendemos por agentes de IA en la empresa: la autonomía útil no es una propiedad mágica del modelo. Es el resultado de combinar objetivo, contexto, herramientas, permisos, verificación y responsabilidad.

2. El modelo mental correcto: explorar, planificar, ejecutar y verificar

El error más habitual es abrir Claude Code y pedirle que empiece a programar antes de que entienda el problema. En un proyecto real, el flujo profesional se parece más a una mini-cadena de ingeniería:

1. Explorar

Primero, Claude debe leer la estructura del repositorio, localizar los ficheros relevantes, entender cómo se ejecuta el proyecto y detectar las convenciones existentes. En esta fase no buscamos que produzca código. Buscamos que construya un modelo mental y formule preguntas.

2. Planificar

Después se define el resultado, se separan las tareas, se identifican dependencias y se explicitan los riesgos. Un plan bueno no es una lista de frases genéricas: indica qué cambia, qué no cambia, cómo se comprobará y qué decisiones necesitan aprobación.

3. Ejecutar

La implementación se hace por pasos pequeños. Claude puede editar, ejecutar comandos, leer errores y corregir. La persona debe mantener visible el objetivo, revisar los diffs y evitar que una primera solución razonable se convierta en una cadena de parches sin dirección.

4. Verificar y preservar

El trabajo no termina cuando Claude dice que ha terminado. Hay que ejecutar tests, linters, type-checks, comprobaciones visuales o pruebas de negocio. El resultado debe quedar en un commit, una pull request, una documentación o un artefacto que otra persona pueda revisar.

La velocidad de Claude Code se nota en la ejecución. La calidad se decide antes y después: en el contexto que recibe y en la verificación que exigimos.

3. Primeros pasos: cómo empezar sin convertirlo en magia

La primera sesión debería ocurrir en un proyecto real, pero con una tarea de bajo riesgo. La secuencia más útil es:

1. Abre el terminal en un repositorio que conozcas y que puedas restaurar con Git.
2. Pide a Claude que explique la arquitectura y que cite los ficheros donde ha encontrado cada respuesta.
3. Solicita un cambio pequeño y explícito, por ejemplo una prueba o una mejora localizada.
4. Haz que ejecute la comprobación del proyecto y te enseñe el diff.
5. Corrige sus supuestos antes de darle una tarea más grande.

La instalación cambia según el sistema y el método de autenticación. Conviene seguir la documentación oficial de Claude Code para obtener el comando actualizado. Después, la pregunta importante no es «¿qué prompt le escribo?», sino «¿qué necesita saber para trabajar como alguien que acaba de incorporarse a mi equipo?».

Una instrucción inicial útil sería: Explora el repositorio, explícame cómo se ejecuta, identifica los riesgos de esta tarea y hazme las preguntas que necesites antes de proponer cambios. Es una forma sencilla de obligar al agente a comprender antes de actuar.

4. Contexto y configuración: el sistema empieza en los archivos

La diferencia entre una sesión genérica y una sesión que parece conocer el proyecto está en el contexto persistente. Claude Code puede leer reglas de proyecto, preferencias personales y configuración técnica. Cada pieza tiene una función distinta:

CLAUDE.md: menos documentación, más decisiones

Un CLAUDE.md útil no es un manual interminable ni una copia de la documentación pública del framework. Es el lugar donde se escriben las cosas que Claude no debería tener que adivinar: cómo arrancar el proyecto, qué comandos pasan en CI, qué patrones se consideran correctos, qué directorios no debe tocar y por qué existe una decisión aparentemente extraña.

En I3OS aplicamos una separación parecida: Project = el contexto que recuerda; Skill = el método que sabe aplicar. En Claude Code, el proyecto aporta la realidad concreta y los skills convierten la experiencia del equipo en una capacidad activable.

Permisos: autonomía graduada, no modo YOLO

Claude Code puede leer, editar, ejecutar comandos y conectarse a servicios. Cada permiso amplía la capacidad y también la superficie de riesgo. La configuración profesional parte del mínimo necesario:

• Permite comandos de lectura y pruebas antes que comandos destructivos.
• Restringe el acceso por comando, directorio, dominio o tipo de herramienta.
• Evita credenciales reales en el repositorio, el prompt o los logs.
• Exige aprobación humana para publicar, borrar, desplegar, enviar mensajes o tocar datos sensibles.
• Revisa periódicamente los permisos: lo que era excepcional suele acabar siendo permanente.

La autonomía debe aumentar por evidencia, no por entusiasmo. Si una tarea falla de forma imprevisible, la respuesta no suele ser darle más permisos. Primero hay que mejorar el contexto, el método o la verificación. Esta es también una de las conclusiones de nuestro trabajo sobre supervisión humana.

5. Skills: convertir el conocimiento del equipo en un método reusable

Una Skill no es un prompt largo con un nombre bonito. Es una receta operativa que explica cuándo usarla, qué contexto necesita, qué pasos debe seguir, qué herramientas puede utilizar y cómo debe entregar el resultado.

Un ejemplo sencillo sería una Skill de auditoría de una landing:

---
name: auditar-landing
description: Revisa una landing en busca de problemas de conversión, accesibilidad y rendimiento.
---

1. Identifica el objetivo de negocio y la audiencia.
2. Revisa estructura, propuesta de valor y llamadas a la acción.
3. Comprueba accesibilidad, responsive y estados de error.
4. Ejecuta las pruebas disponibles y documenta la evidencia.
5. Devuelve hallazgos priorizados, no una lista genérica de opiniones.
6. No modifiques archivos sin pedir aprobación explícita.

La fuerza de la Skill está en que se puede mejorar con cada uso. Si el agente olvida comprobar el contraste, se añade al método. Si una fuente no es fiable, se fija una regla. Si una tarea necesita la aprobación del cliente, se convierte en un punto de control.

• Skill de exploración: entender un repositorio, un cliente o una cuenta sin tocar nada.
• Skill de producción: ejecutar un procedimiento con entradas y salidas claras.
• Skill de evaluación: comparar el resultado con una rúbrica y devolver evidencias.
• Skill de mantenimiento: actualizar documentación, tests o configuraciones cuando cambia el sistema.

Una Skill no sustituye al profesional: empaqueta un método para que el profesional pueda dedicar su atención a las decisiones difíciles. Cuanto más se repite una tarea, más valor tiene convertirla en una capacidad compartida y revisable.

6. Hooks: las reglas que no dependen de que el modelo se acuerde

Las instrucciones de CLAUDE.md orientan al agente, pero siguen siendo instrucciones que el modelo interpreta. Un Hook introduce una automatización determinista en un momento concreto del ciclo de trabajo: antes de una herramienta, después de una edición, cuando una sesión termina o cuando el contexto cambia.

• Ejecutar el formateador después de editar.
• Lanzar tests o análisis estático después de una modificación.
• Bloquear patrones de secretos antes de guardar un fichero.
• Registrar qué herramienta se ha usado y con qué resultado.
• Notificar que una tarea ha terminado sin mantener una ventana abierta.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

El ejemplo es deliberadamente simple: el comando real depende de cada stack y conviene evitar que un Hook lento bloquee toda la sesión. La regla práctica es colocar en Hooks lo que debe ocurrir siempre y dejar en las Skills lo que necesita interpretación.

Para una empresa, la pregunta decisiva es: ¿qué errores queremos impedir por diseño, incluso si el modelo propone una solución aparentemente correcta?

7. MCP: cuando Claude deja de trabajar con una copia del mundo

El Model Context Protocol permite conectar Claude Code con herramientas y fuentes externas mediante interfaces estructuradas. En vez de copiar manualmente una conversación de Slack, un documento, una incidencia o una métrica, el agente puede consultar el sistema autorizado y trabajar con información más cercana a la fuente.

• Documentación y conocimiento: consultar un repositorio de decisiones, un wiki o documentos de proyecto.
• Producto y operaciones: leer incidencias, tareas, calendarios o estados de despliegue.
• Calidad: abrir la aplicación, capturar una pantalla, consultar logs o ejecutar una comprobación.
• Empresa: conectar datos y procesos internos siempre con permisos, trazabilidad y propósito definido.

MCP no es una excusa para conectar todo. Cada servidor añade herramientas, contexto, permisos y una dependencia más. La conexión correcta es la que reduce el trabajo de reconstruir información sin crear una superficie de riesgo desproporcionada.

En la práctica, conecta primero una fuente que tenga dueño, datos relativamente limpios y un caso de uso concreto. Después mide si mejora el resultado. Si la información necesita copiarse, interpretarse o validarse manualmente de todas formas, probablemente el problema no se resuelve añadiendo otro servidor.

La diferencia entre una API genérica y un servidor de herramientas con contexto está en que el agente puede trabajar con una interfaz preparada para consultar y actuar. En el modelo de I3OS, esta capa equivale a conectar la IA con los datos y sistemas reales del cliente, no a pedirle que improvise con una copia desactualizada.

8. Subagentes: dividir el trabajo sin perder la responsabilidad

Un subagente es una sesión especializada que trabaja en un contexto aislado y devuelve un resultado resumido al agente principal. Es útil cuando una tarea puede separarse por objetivo: investigar una dependencia, revisar seguridad, analizar logs, explorar una parte del repositorio o ejecutar una evaluación independiente.

• Explorador: busca dónde vive una funcionalidad y devuelve un mapa de ficheros.
• Revisor: analiza un diff con una rúbrica concreta y no modifica nada.
• Investigador: compara alternativas y documenta trade-offs.
• Verificador: ejecuta pruebas y aporta evidencia de lo que pasa.

Los subagentes no multiplican automáticamente la inteligencia. Multiplican el trabajo y el coste si los lanzamos sin una división clara. No tiene sentido poner cinco agentes a editar los mismos ficheros ni pedir a todos que hagan una auditoría genérica. La paralelización funciona cuando cada agente tiene un contrato pequeño y una salida útil.

En tareas que puedan modificar código, los worktrees de Git permiten aislar ramas y evitar que varias sesiones se pisen. Aun así, la integración final debe tener un punto de revisión común. Un agente puede producir un cambio; el equipo decide si ese cambio pertenece al producto.

La regla que trasladamos a I3OS es la misma: cada capacidad debe tener un propósito, una fuente de contexto, un método y una persona responsable.

9. Plugins y Agent Plugins: empaquetar capacidades para que viajen

Cuando un equipo crea varias Skills, Hooks, agentes y conexiones MCP, aparece una necesidad natural: empaquetarlos. Los plugins permiten distribuir una capacidad completa con una estructura que otras personas puedan instalar, revisar y actualizar.

La referencia que compartes desde la publicación de midudev en LinkedIn apunta precisamente a una conversación importante: si cada cliente de agentes empaqueta las extensiones con un formato distinto, los equipos terminan duplicando trabajo. La Agent Plugins Specification propone un contrato abierto y agnóstico para empaquetar componentes como Skills y servidores MCP.

La especificación 1.0.0 define un manifiesto plugin.json, una estructura de Skills con archivos SKILL.md y un esquema para la configuración MCP cuando el plugin la incluye. No significa que todos los clientes soporten automáticamente todos los plugins. Significa que el ecosistema tiene una base común sobre la que construir portabilidad y distribución.

mi-plugin/
├── plugin.json
├── skills/
│   └── auditar-landing/
│       └── SKILL.md
└── mcp.json

Para Impulsa3, esta evolución es especialmente relevante. Si un método de análisis, QA, onboarding o producción se convierte en una capacidad bien documentada, interesa que no quede atada a una única sesión ni a la memoria de una persona. Un plugin puede ser el embalaje; la gobernanza y el criterio siguen siendo responsabilidad de la organización.

La especificación se presenta como un estándar abierto y neutral, con desarrollo público y participación de distintos actores del ecosistema. Conviene seguirla como señal de hacia dónde va la distribución de agentes, sin confundir todavía una especificación con una garantía de interoperabilidad total.

10. Claude Code en tu propio equipo: Remote Control y el debate sobre el cómputo

La ejecución remota introduce una distinción que no conviene simplificar. Una sesión de Claude Code puede ejecutarse en la infraestructura cloud del proveedor, o puede ejecutarse en tu propio ordenador y ser controlada desde otra interfaz. No son lo mismo.

La referencia de Anthropic que compartes, Run Claude Code sessions on your own compute, anticipa esta dirección. La documentación actual lo concreta como Remote Control: ejecutas Claude Code en tu máquina y utilizas claude.ai o la aplicación móvil para continuar y supervisar la sesión. El sistema de archivos, las herramientas locales y los servidores MCP permanecen disponibles en tu entorno.

# En una sesión nueva
claude remote-control

# O desde una sesión interactiva existente
/remote-control

Esto puede ser muy útil para un equipo que necesita conservar un entorno privado, herramientas internas o datos que no quiere mover a una máquina efímera. Pero «se ejecuta en mi equipo» no significa «no sale ningún dato». La conexión remota sincroniza la conversación y la actividad para que puedas verla desde otros dispositivos. Hay que revisar la política de datos, los permisos, el acceso físico, el sueño del portátil y la disponibilidad de la red.

La decisión correcta depende del riesgo y del trabajo. Un análisis que solo necesita un repositorio limpio puede ejecutarse en la nube. Una tarea que necesita tu servidor de desarrollo, tus MCP locales o datos internos puede requerir tu propio cómputo. En ambos casos, la seguridad no se delega al nombre del producto: se diseña en las credenciales, los límites y la revisión.

11. El puente con I3OS: de una herramienta para programar a un sistema de trabajo

El caso de I3OS ayuda a ver la diferencia entre utilizar Claude Code de forma individual y construir una capacidad organizativa. En nuestro sistema, el objetivo no es que cada persona aprenda una colección distinta de prompts. El objetivo es que el trabajo pueda conservar contexto, aplicar método, consultar las fuentes adecuadas y producir un resultado revisable.

• Project: separa el contexto de cada cliente, producto o iniciativa.
• CLAUDE.md y reglas: fijan las convenciones y decisiones que deben mantenerse.
• Skills: convierten una práctica de una persona experta en un procedimiento compartido.
• MCP y conectores: acercan los datos y herramientas reales al flujo de trabajo.
• Hooks y permisos: hacen que ciertos controles no dependan de la memoria del modelo.
• Subagentes: separan investigación, ejecución y evaluación cuando la tarea lo merece.
• Revisión humana: conserva la responsabilidad sobre el cliente, el negocio y la comunicación externa.

En el caso de éxito de I3OS contamos cómo un piloto SEO se convirtió en una arquitectura que conecta operaciones, tecnología, contenidos, squads de cliente y adopción interna. Claude Code encaja en esta visión porque hace posible iterar rápido sobre los métodos: documentarlos, probarlos, conectarlos y corregirlos.

Un agente aislado automatiza una tarea. Un sistema agentizado mejora la forma en que una organización aprende y entrega valor.

12. Un caso práctico: construir una capacidad de revisión de frontend

Imaginemos una capacidad interna para revisar una landing antes de entregarla a un cliente. Un flujo inmaduro sería pedir: «revisa esta página y dime si está bien». Un sistema mejor diseñado separa el trabajo:

1. El Project aporta el objetivo de negocio, la audiencia, la identidad de marca y las restricciones del cliente.
2. Una Skill define la rúbrica: propuesta de valor, jerarquía, conversión, accesibilidad, responsive y rendimiento.
3. MCP permite consultar la analítica, abrir la página en un navegador y recuperar incidencias relacionadas.
4. Un Hook ejecuta el lint y bloquea secretos o errores básicos antes de que el agente entregue el resultado.
5. Un subagente revisa la accesibilidad y otro contrasta la implementación con el diseño.
6. La persona responsable recibe un informe con evidencias, decide qué se corrige y aprueba la entrega.

La diferencia no está en tener un prompt más sofisticado. Está en haber diseñado un circuito donde cada pieza tiene una función y donde el resultado se puede revisar. Es el mismo principio que aplicamos al rediseño de procesos con IA: antes de automatizar, hay que entender el proceso real, sus decisiones, sus excepciones y su criterio de calidad.

13. Gobernanza: la IA acelera, pero no firma

Cuanto más capaz es el agente, más importante es decidir dónde termina su autonomía. En Impulsa3 resumimos esta idea así: la IA acelera; no firma. El sistema puede preparar, analizar y proponer. Las decisiones que afectan al cliente, al negocio, a los datos sensibles o a la reputación necesitan una persona responsable.

• Acceso con propósito: cada herramienta debe responder a una necesidad concreta del flujo.
• Menor privilegio: la identidad del agente solo debe tener el alcance que necesita.
• Fuentes con responsable: un dato sin fecha, dueño o calidad conocida no se convierte en fiable por estar conectado.
• Revisión antes de ejecutar: publicar, borrar, desplegar, contratar o comunicar necesita aprobación.
• Trazabilidad: conviene poder saber qué se consultó, qué se cambió, qué pruebas se ejecutaron y quién validó.
• Privacidad por diseño: la información sensible no debe entrar en un flujo solo porque técnicamente sea posible.

Estas reglas conectan con la calidad del dato, el comité de IA y la necesidad de pasar de pilotos a sistemas controlados. La gobernanza no es una capa burocrática que aparece después de la innovación: forma parte del diseño técnico.

14. Cómo implantar Claude Code en un equipo sin crear caos

Una adopción responsable puede empezar con un solo flujo y crecer a partir de la evidencia. Este recorrido suele ser más sólido que repartir licencias y esperar que aparezca una metodología espontánea:

1. Elige una tarea repetitiva y revisable. Investigación, documentación, QA, análisis de logs o mantenimiento suelen ser buenos puntos de partida.
2. Define el resultado y la evidencia. Antes de usar el agente, decide qué significa «hecho» y cómo se comprobará.
3. Construye el contexto mínimo. Reúne fuentes, comandos, restricciones, excepciones y responsables.
4. Documenta el método como una Skill. No escondas la forma correcta de trabajar dentro de una conversación.
5. Añade controles deterministas. Usa permisos y Hooks para evitar errores recurrentes.
6. Conecta solo las herramientas necesarias. Cada servidor MCP debe tener un caso de uso y un dueño.
7. Mide y mejora. Registra tiempo, calidad, retrabajo, errores, coste, intervenciones y satisfacción del equipo.
8. Escala la capacidad, no el ruido. Si funciona, empaqueta el método, forma al equipo y decide si merece convertirse en plugin o servicio compartido.

El objetivo no es demostrar que un agente puede hacer muchas cosas. Es demostrar que una capacidad concreta mejora el trabajo sin perder control. Cuando el proceso ya está entendido y medido, tiene sentido aumentar la autonomía o paralelizar con subagentes.

15. Qué no conviene hacer

• No empieces por el modo más autónomo. Empieza por observar cómo razona y qué supuestos hace.
• No rellenes CLAUDE.md con información que el agente puede inferir. Reserva el contexto para decisiones, límites y convenciones.
• No conectes MCP por acumulación. Más herramientas pueden significar más coste, más ruido y más superficie de ataque.
• No lances agentes en paralelo sobre los mismos archivos. La velocidad no compensa los conflictos difíciles de revisar.
• No midas el éxito por la cantidad de prompts o Skills. Mídelo por resultados, calidad y capacidad liberada.
• No ocultes la incertidumbre. Un informe que distingue hechos, hipótesis y dudas es más valioso que una respuesta segura pero frágil.

Preguntas frecuentes sobre Claude Code

¿Claude Code es solo para programadores?

Está diseñado alrededor del trabajo con código y terminal, pero su modelo es más amplio: leer contexto, aplicar un método, usar herramientas y producir un resultado revisable. Puede ser útil para documentación técnica, QA, análisis de datos o automatización operativa siempre que exista un entorno claro y una persona responsable.

¿Necesito usar Skills, Hooks, MCP y subagentes desde el primer día?

No. Empieza con una sesión local, un CLAUDE.md corto y una tarea que puedas verificar. Añade Skills cuando el método se repita, Hooks cuando haya controles que deban ejecutarse siempre, MCP cuando necesites datos externos y subagentes cuando exista una división real del trabajo.

¿Remote Control ejecuta Claude en la nube?

Remote Control permite controlar desde la web o el móvil una sesión de Claude Code que sigue ejecutándose en tu máquina. Es diferente de una sesión de Claude Code en la nube. Aun así, la conversación y la actividad se sincronizan para que las interfaces puedan mantenerse conectadas, por lo que hay que revisar la política de datos de tu organización.

¿Agent Plugins ya garantiza que todo funcione en cualquier cliente?

No. La especificación ofrece un formato común para empaquetar extensiones y una base para la portabilidad. La compatibilidad real depende de que cada cliente implemente el estándar y de las capacidades concretas que soporte.

¿Cómo sé si un proceso está preparado para agentizarse?

Cuando puedes explicar su objetivo, fuentes, pasos, excepciones y criterio de calidad, y cuando una segunda persona puede revisar el resultado. Si nadie sabe describir cómo se hace la tarea, primero hay que rediseñarla y documentarla.

Conclusión: el multiplicador no es Claude, es el sistema

Claude Code representa un salto importante porque lleva la IA al lugar donde el trabajo ocurre: el repositorio, el terminal, los tests, los servicios y los procesos. Pero el valor no está en pedirle que haga más cosas sin supervisión. Está en diseñar un flujo donde pueda trabajar con contexto, método y límites.

Las piezas encajan así: CLAUDE.md aporta memoria; las Skills aportan método; MCP aporta conexión; los Hooks aportan determinismo; los subagentes aportan especialización; los plugins aportan distribución; Remote Control aporta continuidad; la revisión humana aporta responsabilidad.

Eso es lo que estamos explorando con I3OS en Impulsa3: convertir la inteligencia artificial en una capacidad organizativa, no en una colección de herramientas aisladas. El objetivo final no es producir más código, más contenido o más automatizaciones. Es liberar capacidad para entender mejor el negocio, resolver problemas complejos y entregar más valor a los clientes.

Si quieres identificar qué procesos de tu empresa pueden agentizarse, diseñar una arquitectura con contexto y gobernanza o acompañar a tu equipo en la adopción, podemos ayudarte a convertir la oportunidad en un sistema de trabajo práctico y medible.