Tabla de contenido
- Antes de empezar: requisitos del sistema
- Cómo instalar Claude Code
- Primeros comandos: los 15 minutos más productivos de tu día
- Modos de uso: interactivo, plan y headless
- CLAUDE.md: el archivo que cambia todo
- Skills personalizados: enséñale una vez, úsalo siempre
- Hooks: automatizaciones que corren solas
- MCP: conecta Claude Code a tus herramientas
- Multi-agent: varios agentes trabajando en paralelo
- Trucos avanzados: slash commands, teleport y remote control
- Preguntas frecuentes
- Lo que cambia cuando dejas de teclear y empiezas a dirigir
Este no es un artículo sobre qué es Claude Code ni por qué debería importarte. Si llegas aquí es porque ya decidiste usarlo y necesitas saber cómo. Así que vamos directo al grano: comandos reales, configuraciones reales, flujos de trabajo que puedes copiar hoy mismo. Si quieres el contexto más amplio sobre la herramienta, tienes la guía completa de Claude Code para eso.
Lo que vas a encontrar aquí es un tutorial progresivo. Empieza con la instalación y termina con orquestación de múltiples agentes. Puedes leerlo completo o saltar a la sección que necesitas. Cada parte tiene ejemplos que puedes ejecutar en tu terminal ahora mismo, no teoría genérica sobre inteligencia artificial.
Antes de empezar: requisitos del sistema
Antes de instalar cualquier cosa, confirma que tu entorno cumple con los requisitos mínimos. Claude Code corre en tu terminal local y necesita algunos componentes para funcionar bien. No son muchos, pero si te saltas esta parte después te vas a quedar mirando mensajes de error preguntándote qué salió mal.
En cuanto al sistema operativo, tienes tres opciones principales: macOS 10.15 o superior, Ubuntu 20.04 o superior, y Windows 10 con WSL (Windows Subsystem for Linux) activado. En Windows también puedes correrlo nativamente con Git for Windows, que es una opción más reciente y que funciona sorprendentemente bien. Si usas Windows sin WSL, vas a necesitar instalar Git for Windows primero y asegurarte de que esté en tu PATH.
La única dependencia de software que realmente necesitas es Node.js versión 18 o superior, pero solo si vas a usar el método de instalación via npm (que está deprecado desde 2026). Con el instalador nativo recomendado, Node.js ya no es un requisito. Lo que sí necesitas tener instalado para una experiencia completa es git y ripgrep. Git es casi seguro que ya lo tienes. Ripgrep le permite a Claude Code buscar dentro de tu código de forma mucho más eficiente que grep estándar.
En cuanto a la cuenta, necesitas una suscripción activa a Claude. Funciona con Claude Pro, Max, Teams o Enterprise. También puedes usarlo con una API key directa desde la consola de Anthropic, con Amazon Bedrock o con Google Vertex AI si tu empresa ya tiene esas integraciones. Para la mayoría de personas que empiezan, Claude Max es la opción que tiene más sentido porque incluye Claude Code sin costo adicional.
| Requisito | Detalle | Obligatorio |
|---|---|---|
| Sistema operativo | macOS 10.15+, Ubuntu 20.04+, Windows 10+ | Sí |
| Cuenta Anthropic | Pro, Max, Teams, Enterprise o API key | Sí |
| git | Cualquier versión reciente | Recomendado |
| ripgrep | Para búsqueda eficiente en código | Recomendado |
| Node.js 18+ | Solo si usas npm (método deprecado) | No |
| Git for Windows | Solo en Windows nativo sin WSL | Condicional |
Un detalle que mucha gente ignora: revisa que tu terminal tenga los permisos correctos para ejecutar comandos. En macOS, asegúrate de que Terminal o iTerm2 tengan acceso a las carpetas de tu proyecto. En Linux, verifica que tu usuario tenga los permisos necesarios en el directorio donde vas a trabajar. Estos problemas de permisos son la causa número uno de instalaciones que fallan a mitad del proceso o que corren con comportamientos extraños.
Cómo instalar Claude Code
La instalación cambió a principios de 2026. El método antiguo con npm sigue funcionando pero está oficialmente deprecado, y Anthropic recomienda migrar al instalador nativo porque es más rápido, no tiene dependencias externas y se actualiza solo en segundo plano. Así que olvídate del npm install -g @anthropic-ai/claude-code y usa los comandos nuevos.
https://andresospina.co/wp-content/uploads/2026/03/body-6-installation-300x167.webp 300w, https://andresospina.co/wp-content/uploads/2026/03/body-6-installation-1024x572.webp 1024w, https://andresospina.co/wp-content/uploads/2026/03/body-6-installation-768x429.webp 768w, https://andresospina.co/wp-content/uploads/2026/03/body-6-installation-1536x857.webp 1536w, https://andresospina.co/wp-content/uploads/2026/03/body-6-installation-2048x1143.webp 2048w" sizes="auto, (max-width: 2560px) 100vw, 2560px" />
Para macOS, Linux o WSL, abre tu terminal y ejecuta este comando:
curl -fsSL https://claude.ai/install.sh | bashSi estás en Windows con PowerShell, el comando es diferente:
irm https://claude.ai/install.ps1 | iexY si prefieres CMD en Windows:
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmdDespués de que termine la instalación, verifica que todo quedó bien con dos comandos. Primero confirma la versión instalada, luego corre el diagnóstico integrado:
claude --version
claude doctorclaude doctor revisa tu entorno y te dice si hay algún problema con las dependencias, las variables de entorno o la configuración. Si algo falla, te muestra exactamente qué está mal y, en muchos casos, cómo arreglarlo. Es el equivalente a un chequeo de salud del sistema antes de empezar a trabajar.
Si venías usando npm y quieres migrar al instalador nativo, el proceso es simple:
# Instala el binario nativo
curl -fsSL https://claude.ai/install.sh | bash
Elimina la instalación antigua de npm
npm uninstall -g @anthropic-ai/claude-codeAhora viene la autenticación. La primera vez que corras claude en cualquier directorio, te va a pedir que inicies sesión. Se abre el navegador automáticamente y completas el proceso en unos 30 segundos. Tus credenciales quedan guardadas localmente y no tienes que volver a autenticarte a menos que uses el comando /login para cambiar de cuenta. Si trabajas con API key directa, configura la variable de entorno ANTHROPIC_API_KEY antes de correr cualquier comando.
Primeros comandos: los 15 minutos más productivos de tu día
Con Claude Code instalado y autenticado, lo primero que haces es navegar a un proyecto existente y correr claude. Eso es todo. No hay configuración inicial obligatoria, no hay que decirle qué archivos leer ni en qué lenguaje está el proyecto. Lo analiza solo y en segundos tiene contexto suficiente para empezar a ayudarte.
cd tu-proyecto
claudeUna vez dentro de la sesión interactiva, la primera tarea que le das es que se presente con el proyecto. Prueba con esto para entender qué ve Claude Code cuando mira tu código:
what does this project do?
what technologies does this project use?
explain the folder structure
where is the main entry point?Ahora los comandos que vas a usar el 80% del tiempo. Para hacer cambios en el código, simplemente describes lo que quieres en lenguaje natural. Claude Code analiza los archivos relevantes, propone los cambios y te pide confirmación antes de tocar nada:
add input validation to the user registration form
fix the bug where users can submit empty forms
write unit tests for the auth module and run them
refactor the payment service to use async/awaitPara tareas de git, Claude Code también se integra de forma nativa. Puedes pedirle que revise los cambios, que haga commits con mensajes descriptivos o que cree ramas:
what files have I changed?
commit my changes with a descriptive message
create a new branch called feature/user-auth
create a pull request for these changesLos slash commands son la forma de controlar la sesión en sí. Los más importantes para empezar son tres. /clear limpia el historial de la conversación cuando el contexto se acumula y quieres empezar fresco sin cerrar la sesión. /help muestra todos los comandos disponibles incluyendo los personalizados que hayas creado. Y /init analiza tu proyecto y genera un archivo CLAUDE.md con instrucciones base para Claude Code, que es el primer paso para personalizar la experiencia.
/clear # Limpia el historial de la sesión
/help # Muestra todos los comandos disponibles
/init # Genera CLAUDE.md con contexto del proyecto
/compact # Comprime el historial manteniendo contexto esencialSi quieres hacer una tarea rápida sin abrir una sesión interactiva, puedes usar el modo de un solo comando desde la terminal. El flag -p le dice a Claude Code que procese el prompt, imprima la respuesta y salga:
claude -p "explica qué hace esta función" < src/auth.js
claude -p "cuáles son los archivos que cambié recientemente"
claude "fix the build error"Para continuar una sesión anterior sin tener que repetir el contexto, usa -c para la más reciente o -r para una sesión específica por nombre. Esto es especialmente útil cuando trabajas en un bug que tarda varios días o cuando retomas una tarea después de un descanso:
claude -c # Continúa la sesión más reciente
claude -r "auth-refactor" # Reanuda la sesión llamada auth-refactor
claude -r "auth-refactor" "Finish this PR" # Reanuda con prompt inicialModos de uso: interactivo, plan y headless
Claude Code tiene tres modos de operación distintos y cada uno sirve para situaciones diferentes. Entender cuándo usar cada uno te ahorra frustración y te da más control sobre lo que el agente hace o no hace en tu código. No son excluyentes, puedes combinarlos según la situación.
https://andresospina.co/wp-content/uploads/2026/03/body-6-modes-300x167.webp 300w, https://andresospina.co/wp-content/uploads/2026/03/body-6-modes-1024x572.webp 1024w, https://andresospina.co/wp-content/uploads/2026/03/body-6-modes-768x429.webp 768w, https://andresospina.co/wp-content/uploads/2026/03/body-6-modes-1536x857.webp 1536w, https://andresospina.co/wp-content/uploads/2026/03/body-6-modes-2048x1143.webp 2048w" sizes="auto, (max-width: 2560px) 100vw, 2560px" />
Modo interactivo: el uso diario
El modo interactivo es lo que obtienes cuando corres claude sin flags adicionales. Es una sesión de conversación donde Claude Code puede leer archivos, ejecutar comandos, editar código y pedirte confirmación cuando va a hacer algo potencialmente peligroso. Es el modo que usas para desarrollo cotidiano, exploración de un codebase nuevo o cuando quieres mantener control sobre cada cambio.
En el modo interactivo puedes navegar entre dos estados de permisos presionando Shift+Tab. El primer estado es el modo por defecto, donde Claude Code te pide confirmación antes de ejecutar comandos de bash, editar archivos importantes o hacer cambios que no puede revertir fácilmente. El segundo estado es el modo de aceptar ediciones automáticamente, donde aprueba los cambios de archivos sin preguntarte pero sigue pidiendo permiso para comandos de shell.
Modo plan: piensa antes de ejecutar
El modo plan es uno de los trucos más útiles de Claude Code y que mucha gente ignora. Lo activas con el flag --permission-mode plan o presionando Shift+Tab dos veces dentro de una sesión interactiva. En este modo, Claude Code puede leer archivos, analizar el código, buscar dentro del proyecto y crear un plan detallado, pero no puede modificar nada.
claude --permission-mode planPara qué sirve esto en la práctica: cuando tienes una refactorización grande y quieres ver exactamente qué va a cambiar antes de que cambie algo. O cuando trabajas en código crítico y necesitas revisar el enfoque antes de ejecutarlo. Claude Code genera un documento de plan en formato markdown, te lo muestra, y puedes aprobarlo, modificarlo o descartarlo. Solo después de tu aprobación pasa a ejecutar los cambios.
Una combinación muy práctica es usar plan mode con el flag --allow-dangerously-skip-permissions para que después de aprobar el plan puedas ejecutar todo sin interrupciones:
claude --permission-mode plan --allow-dangerously-skip-permissionsModo headless (print mode): automatización y CI/CD
El modo headless, activado con el flag -p o --print, convierte a Claude Code en una herramienta de línea de comandos programable que se puede pipar, redirigir y componer como cualquier otro programa Unix. No hay sesión interactiva, no espera input del usuario: recibe el prompt, ejecuta la tarea, imprime la respuesta en stdout y sale.
# Analiza logs en tiempo real
tail -f app.log | claude -p "avísame si ves alguna anomalía"
Revisa código antes de un commit
git diff main --name-only | claude -p "revisa estos archivos cambiados por problemas de seguridad"
Genera documentación automáticamente
claude -p "genera JSDoc para todos los archivos en src/ que no tengan documentación"
Output en formato JSON para procesamiento posterior
claude -p "analiza este código y lista los bugs" --output-format json > bugs.jsonPara uso en GitHub Actions o GitLab CI, el modo headless es la base de todo. Un flujo básico de revisión automática de código se ve así:
# .github/workflows/code-review.yml
name: Revisión automática con Claude Code
on: [pull_request]
jobs:
review:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install Claude Code
run: curl -fsSL https://claude.ai/install.sh | bash
- name: Revisar cambios
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
run: |
git diff --name-only origin/main...HEAD | \
claude -p "Revisa estos archivos modificados. Busca bugs, problemas de seguridad y violaciones de convenciones. Formato JSON con severidad alta/media/baja." \
--output-format json --max-turns 5 > review.jsonLos flags más útiles en modo headless son --max-turns para limitar cuántas iteraciones puede hacer el agente, --max-budget-usd para controlar el gasto máximo en API, --allowedTools para restringir qué herramientas puede usar y --output-format para obtener texto plano, JSON o JSON en streaming.
Growth MarketingTodo lo que publico aquí es gratis. Implementarlo contigo tiene precio.
Si algo de lo que leíste te hizo pensar "esto me está pasando", hablemos. Te respondo el mismo día.
Agendar 30 min →CLAUDE.md: el archivo que cambia todo
CLAUDE.md es el archivo de instrucciones persistentes que Claude Code lee al inicio de cada sesión. Vive en la raíz de tu proyecto y funciona como un sistema de contexto permanente: todo lo que escribas ahí estará disponible en cada conversación sin que tengas que repetirlo. Es la diferencia entre explicarle a Claude Code el estilo de código de tu equipo cada vez que abres una sesión, o hacerlo una vez y olvidarte del tema.
La forma más rápida de crear uno es con el comando /init. Esto analiza la estructura de tu proyecto, detecta el stack tecnológico, identifica los comandos de build y test, y genera un CLAUDE.md con esa información base. Después lo editas para agregar las cosas que importan de verdad: convenciones de código de tu equipo, decisiones de arquitectura que no son obvias mirando el código, advertencias sobre partes del código que tienen lógica no intuitiva, y los patrones que quieres que Claude Code siga o evite.
/initUn CLAUDE.md bien estructurado tiene al menos estas secciones. El ejemplo de abajo es para un proyecto real de una startup SaaS:
# Proyecto: Panel de Analytics
Comandos esenciales
- Build: `npm run build`
- Tests: `npm run test:unit`
- Tests e2e: `npm run test:e2e`
- Linter: `npm run lint`
- Dev server: `npm run dev` (puerto 3000)
Stack tecnológico
- Frontend: React 18 + TypeScript + Vite
- Backend: Node.js + Express + Prisma
- DB: PostgreSQL 15
- Auth: Auth0 (no modificar sin revisar con el equipo)
Convenciones de código
- Usar async/await, nunca callbacks ni .then()
- Nombres de archivos en kebab-case
- Componentes React en PascalCase
- Todos los endpoints del API deben tener validación con Zod
Advertencias importantes
- El módulo src/billing/ tiene lógica de reintentos propia. No modificar sin leer billing/README.md
- Las migraciones de base de datos van en prisma/migrations/. Nunca editar manualmente
- Las variables de entorno están documentadas en .env.example
Estilo de commits
- Formato: tipo(scope): descripción corta
- Tipos válidos: feat, fix, chore, docs, refactor, testHay varios niveles de CLAUDE.md según el alcance que necesites. El archivo en la raíz del proyecto aplica a toda esa sesión y debería estar versionado en git para que todo el equipo comparta el mismo contexto. Si tienes un monorepo con subdirectorios que tienen sus propias convenciones, puedes crear CLAUDE.md adicionales en cada subdirectorio y Claude Code los carga automáticamente cuando trabaja en esa parte del código.
Para instrucciones personales que no quieres compartir con el equipo (tu estilo de comunicación preferido, tu configuración de editor, las cosas que te irritan de cómo Claude Code responde), usa ~/.claude/CLAUDE.md. Este archivo aplica a todos tus proyectos pero solo en tu máquina. Agrégalo a tu .gitignore o crea un CLAUDE.local.md en el proyecto que también está en gitignore.
Un truco que no es obvio: puedes pedirle a Claude Code que actualice el CLAUDE.md cuando descubre algo nuevo sobre el proyecto. Si en una sesión le dices "guarda esta convención en el CLAUDE.md", lo hace sin problema. Con el tiempo, el archivo crece orgánicamente con aprendizajes reales del proyecto en lugar de ser un documento que escribiste una vez y nunca actualizaste.
Skills personalizados: enséñale una vez, úsalo siempre
Los skills son comandos personalizados que empaquetan flujos de trabajo repetitivos. La diferencia con simplemente escribir el mismo prompt cada vez es que los skills son reutilizables, se pueden compartir con el equipo, admiten argumentos, y pueden incluir archivos auxiliares como templates o scripts. Desde 2026, los skills reemplazaron el formato antiguo de comandos personalizados en .claude/commands/ aunque ese formato sigue funcionando. Si aún no tienes claro qué es Claude Code en su conjunto, la guía base de Claude Code te da el panorama completo antes de entrar a estas configuraciones avanzadas.
Cada skill es un directorio con un archivo SKILL.md como punto de entrada. La estructura mínima es esta:
mkdir -p .claude/skills/revisar-pr
touch .claude/skills/revisar-pr/SKILL.mdEl contenido del SKILL.md tiene dos partes: un bloque de frontmatter YAML opcional entre triple guiones, y las instrucciones en markdown. El frontmatter define el comportamiento del skill:
---
name: revisar-pr
description: Hace una revisión completa del PR actual buscando bugs, problemas de seguridad y violaciones de estilo
allowed-tools: Read, Grep, Glob, Bash(git diff:*), Bash(git log:*)
---
1. Obtén los archivos modificados: `!git diff --name-only HEAD~1`
2. Revisa los cambios detallados: `!git diff HEAD~1`
3. Para cada archivo modificado, evalúa:
- Bugs potenciales y edge cases no manejados
- Vulnerabilidades de seguridad (SQL injection, XSS, secrets expuestos)
- Cobertura de tests para los cambios nuevos
- Violaciones de las convenciones del CLAUDE.md
4. Genera un reporte organizado por prioridad: alta, media, baja
5. Termina con un resumen ejecutivo de máximo 3 líneasPara invocar este skill desde dentro de una sesión de Claude Code:
/revisar-prLos skills también aceptan argumentos que puedes referenciar con $ARGUMENTS en las instrucciones. Por ejemplo, un skill para arreglar un issue de GitHub:
---
name: fix-issue
description: Lee un issue de GitHub y lo implementa
argument-hint: [número-de-issue]
---
Trabaja en el issue $ARGUMENTS:
1. Lee los detalles del issue (título, descripción, comentarios si los hay)
2. Analiza qué código hay que cambiar para resolverlo
3. Implementa la solución
4. Escribe tests que cubran el caso
5. Verifica que los tests pasen antes de terminarPara skills que quieres disponibles en todos tus proyectos, en lugar de ponerlos en .claude/skills/ dentro del proyecto, los pones en ~/.claude/skills/ en tu directorio home. Claude Code también viene con varios skills precargados que siempre están disponibles sin que tengas que instalar nada: /batch para ejecutar tareas en paralelo en múltiples archivos, /debug para análisis sistemático de bugs, /loop para tareas iterativas, y /simplify para refactorizar código complejo.
Para skills que necesitan correr en un contexto aislado sin afectar la sesión principal, agrega context: fork en el frontmatter. Esto crea un subagente separado que ejecuta el skill y devuelve el resultado. Es útil para tareas largas de investigación o análisis que no quieres que contaminen el contexto de tu sesión principal:
---
name: analisis-seguridad
description: Hace un análisis completo de seguridad del codebase
context: fork
agent: Explore
---
Analiza exhaustivamente el codebase buscando:
1. Secretos o credenciales hardcodeadas
2. Dependencias con vulnerabilidades conocidas
3. Patrones de código inseguros (SQL injection, XSS, path traversal)
4. Configuraciones de seguridad incorrectas
Genera un reporte en formato markdown.Hooks: automatizaciones que corren solas
Los hooks son scripts o comandos que Claude Code ejecuta automáticamente en respuesta a eventos específicos dentro de una sesión. Son la forma de agregar guardianes, validaciones y automatizaciones que corren sin que tengas que pedírselas. Piensa en ellos como middleware para tus sesiones de Claude Code: se ejecutan antes o después de que el agente use herramientas, cuando inicia o termina una sesión, o cuando envías un prompt.
Los hooks se configuran en el archivo .claude/settings.json del proyecto (para hooks del equipo) o en ~/.claude/settings.json (para hooks personales). La estructura básica es un objeto hooks que mapea eventos a arrays de configuraciones:
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write",
"hooks": [
{
"type": "command",
"command": "npm run lint -- --fix $CLAUDE_TOOL_INPUT_FILE_PATH",
"async": true
}
]
}
]
}
}Este ejemplo ejecuta el linter automáticamente cada vez que Claude Code escribe o modifica un archivo. El flag async: true hace que el hook corra en segundo plano sin bloquear la sesión. Los eventos disponibles son:
| Evento | Cuándo ocurre | Casos de uso típicos |
|---|---|---|
| PreToolUse | Antes de que Claude use una herramienta | Bloquear comandos peligrosos, validar inputs |
| PostToolUse | Después de que Claude usa una herramienta | Correr linter, ejecutar tests, loggear cambios |
| UserPromptSubmit | Cuando envías un mensaje | Filtrar prompts, inyectar contexto adicional |
| Stop | Cuando Claude termina una tarea | Verificar que los tests pasen, quality gates |
| SubagentStop | Cuando un subagente termina | Consolidar resultados, notificaciones |
| SessionStart | Al inicio de una sesión | Cargar variables de entorno, inyectar contexto |
Un hook práctico que puedes copiar ahora mismo: bloquear el comando rm -rf para que Claude Code nunca lo ejecute. Crea el archivo .claude/hooks/block-rm.sh:
#!/bin/bash
COMMAND=$(cat /dev/stdin | python3 -c "import sys,json; print(json.load(sys.stdin)['tool_input']['command'])" 2>/dev/null)
if echo "$COMMAND" | grep -q 'rm -rf'; then
echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"Comando destructivo bloqueado por política del proyecto"}}'
exit 0
fi
exit 0Y configura el hook en settings.json:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": ".claude/hooks/block-rm.sh"
}
]
}
]
}
}Los hooks también pueden ser de tipo HTTP para integrar con servicios externos. Por ejemplo, enviar una notificación a Slack cuando Claude Code termina una tarea larga, o registrar en un sistema de auditoría cada archivo que se modifica. El hook HTTP hace un POST con los datos del evento al URL que especifiques y puede leer la respuesta para decidir si aprobar o denegar la acción. Para equipos que quieren trazabilidad completa de qué cambió Claude Code en el código, este tipo de hook es invaluable.
Un hook de Stop que verifica que los tests pasen antes de que Claude Code dé la tarea como terminada es probablemente el más valioso para equipos de desarrollo. Se configura así, y si los tests fallan Claude Code lo sabe y puede intentar arreglar los problemas antes de declarar victoria:
{
"hooks": {
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "npm run test --silent && exit 0 || echo '{\"hookSpecificOutput\":{\"hookEventName\":\"Stop\",\"shouldContinue\":true,\"message\":\"Los tests están fallando. Revisa y arregla antes de terminar\"}}'"
}
]
}
]
}
}MCP: conecta Claude Code a tus herramientas
MCP (Model Context Protocol) es el estándar abierto que permite conectar Claude Code a sistemas externos: bases de datos, APIs, herramientas de gestión de proyectos, servicios de nube y lo que se te ocurra. Cuando configuras un servidor MCP, Claude Code puede interactuar con esa herramienta de forma nativa dentro de la sesión, como si fuera otra herramienta integrada. La diferencia con hacer llamadas de API manualmente es que Claude Code entiende el contexto y puede encadenar acciones sin que tú tengas que orquestarlo.
Hay tres alcances (scopes) para los servidores MCP y es importante entender la diferencia antes de agregar cualquier servidor. El scope local (por defecto) guarda la configuración en tu ~/.claude.json para el proyecto actual solamente y es privado para ti. El scope project guarda la configuración en un archivo .mcp.json en la raíz del proyecto, va a git y todo el equipo puede usarlo. El scope user también es privado pero aplica a todos tus proyectos.
Para agregar servidores MCP, el comando base es claude mcp add con diferentes opciones según el tipo de servidor. Los servidores remotos usan HTTP o SSE, los locales usan stdio:
# Servidor remoto via HTTP (recomendado para servicios SaaS)
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
GitHub via HTTP
claude mcp add --transport http github https://api.githubcopilot.com/mcp/
Notion via HTTP
claude mcp add --transport http notion https://mcp.notion.com/mcp
PostgreSQL local via stdio
claude mcp add --transport stdio db -- npx -y @bytebase/dbhub --dsn "postgresql://usuario:pass@localhost:5432/midb"
Con alcance de proyecto (se comparte con el equipo via .mcp.json)
claude mcp add --transport http jira --scope project https://mcp.atlassian.com/mcpPara gestionar los servidores que ya tienes configurados:
claude mcp list # Lista todos los servidores configurados
claude mcp get sentry # Ver detalles de un servidor específico
claude mcp remove sentry # Eliminar un servidorSi ya tienes Claude Desktop instalado con servidores MCP configurados, puedes importarlos directamente sin tener que reconfigurar todo:
claude mcp add-from-claude-desktopUna vez que tienes servidores configurados, úsalos dentro de las sesiones de Claude Code de forma natural. Si tienes GitHub configurado, puedes pedirle a Claude Code cosas como "revisa los issues abiertos del repositorio y prioriza los tres más críticos", y lo hará a través del MCP de GitHub sin que tengas que copiar y pegar nada. Con una base de datos PostgreSQL conectada, puedes decirle "analiza las queries más lentas del mes pasado y sugiere los índices que faltan" y Claude Code consulta directamente tu base de datos.
Para verificar qué servidores MCP están activos en una sesión y su estado, usa el comando /mcp dentro de Claude Code. Esto muestra todos los servidores conectados, las herramientas que expone cada uno y si hay algún problema de conexión. Las variables de entorno en los archivos .mcp.json se pueden referenciar con la sintaxis ${NOMBRE_VARIABLE} y se resuelven automáticamente del entorno del sistema, lo que te permite compartir la configuración del equipo sin exponer credenciales en el repositorio.
Multi-agent: varios agentes trabajando en paralelo
El modo multi-agent es donde Claude Code da un salto cualitativo en productividad. En lugar de un solo agente trabajando secuencialmente en tareas, puedes orquestar varios agentes que trabajan en paralelo en diferentes partes de un problema. Un agente orquestador coordina el trabajo, delega subtareas a agentes especializados y consolida los resultados. Para proyectos grandes o tareas que se pueden descomponer en partes independientes, esto puede significar la diferencia entre terminar algo en una hora o en un día.
El skill precargado /batch es el punto de entrada más fácil para multi-agent. Analiza tu codebase, lo descompone en 5 a 30 unidades de trabajo independientes, presenta el plan, y cuando lo apruebas crea un agente separado por unidad en un git worktree aislado. Cada agente implementa su parte, corre los tests y abre un pull request. Al final tienes varios PRs listos para revisar en lugar de una sesión larga bloqueada en un solo archivo:
/batch migra src/ de JavaScript a TypeScriptPara orquestar subagentes de forma manual, puedes usar el flag --agents para definir agentes personalizados dinámicamente con JSON, o crear archivos de configuración en .claude/agents/. Cada agente puede tener su propio set de herramientas disponibles, instrucciones específicas y modelo base:
claude --agents '{"investigador":{"description":"Investiga el codebase y documenta patrones","prompt":"Eres un agente especializado en análisis estático de código. Documenta todos los patrones de diseño y anti-patrones que encuentres."}}'Los worktrees de git son fundamentales para el trabajo multi-agent porque permiten que cada agente trabaje en una copia aislada del repositorio sin interferir con los otros. Claude Code maneja esto automáticamente con el flag -w:
# Inicia Claude Code en un worktree aislado
claude -w feature-auth
El agente trabaja en .claude/worktrees/feature-auth/ sin tocar main
Para casos más complejos donde necesitas coordinar múltiples agentes con dependencias entre ellos, la herramienta de subagentes se usa dentro de CLAUDE.md o skills. Por ejemplo, un flujo donde un agente de investigación primero analiza el problema, pasa los resultados a un agente de implementación, y un tercer agente de revisión verifica el resultado antes de hacer merge. Este patrón se documenta en el skill con el tipo context: fork y el campo agent apuntando a un subagente configurado:
---
name: implementar-feature
description: Implementa una feature compleja con investigación previa y revisión posterior
context: fork
agent: general-purpose
---
Proceso para implementar la feature "$ARGUMENTS":
Fase 1 - Investigación: Analiza el codebase existente para entender los patrones actuales, dependencias relevantes y posibles puntos de integración.
Fase 2 - Implementación: Basándote en la investigación, implementa la feature siguiendo los patrones detectados. Escribe tests.
Fase 3 - Revisión: Verifica que no hay regresiones, que los tests pasan y que el código sigue las convenciones del proyecto.
Reporta el resultado con un resumen de los cambios realizados.El comando claude agents desde la terminal lista todos los subagentes configurados en el proyecto, lo que te da visibilidad de qué agentes tienes disponibles antes de iniciar una sesión. También puedes usar el flag --teammate-mode para controlar cómo se muestran los agentes del equipo: en proceso (dentro de la misma terminal), con tmux (en paneles separados) o automático.
Una advertencia importante: los flujos multi-agent consumen muchos más tokens que las sesiones simples. Para proyectos largos, configura --max-budget-usd para evitar sorpresas en la factura. Si usas Claude Max con Claude Code incluido, el consumo se cubre dentro de la suscripción, pero si usas API key directa el costo puede escalar rápido en sesiones de muchos agentes paralelos. El tema de costos y planes lo cubrimos con detalle en el artículo sobre precios de Claude Code.
Trucos avanzados: slash commands, teleport y remote control
Con la base cubierta, estos son los trucos que separan a quien usa Claude Code de forma básica de quien realmente lo aprovecha. No son funciones oscuras de documentación: son cosas que usarás en el trabajo diario una vez que las conozcas.
Slash commands del sistema
Además de los commands personalizados que creas en .claude/commands/ o como skills, Claude Code tiene slash commands del sistema que controlan el comportamiento de la sesión. /compact comprime el historial de la conversación manteniendo el contexto esencial pero liberando espacio en la ventana de contexto, útil cuando llevas mucho tiempo en una sesión y empieza a ponerse lento. /clear borra todo el historial. /context te muestra cuántos tokens estás usando del contexto total disponible.
/compact # Comprime historial, mantiene contexto esencial
/clear # Borra todo el historial de la sesión
/context # Muestra uso actual del contexto
/mcp # Estado de los servidores MCP activos
/login # Cambia de cuenta o método de autenticación
/export # Exporta la conversación completaEl comando /export es más útil de lo que parece. Genera un archivo con toda la conversación, incluyendo los cambios que hizo Claude Code, los comandos que ejecutó y los resultados. Funciona como documentación automática de lo que hiciste en una sesión, útil para auditorías, para reproducir el proceso en otro proyecto, o simplemente para entender qué pasó cuando algo no salió bien.
Teleport: continúa en la web o en el móvil
Teleport resuelve un problema real: iniciaste una sesión en tu terminal con todo el contexto del proyecto y quieres continuar desde Claude.ai en el navegador, o desde el app móvil, sin perder nada. El comando /teleport dentro de Claude Code crea un portal que transfiere tu sesión actual a la interfaz web.
# Dentro de Claude Code: transfiere la sesión a claude.ai
/teleport
Desde la terminal: reanuda una sesión web en tu terminal local
claude --teleportEl flujo inverso también funciona. Si empezaste una tarea en Claude.ai y necesitas que Claude Code tenga acceso a tu filesystem local para implementar los cambios, usas claude --teleport desde la terminal y se conecta a la sesión web activa. Esto es particularmente útil cuando haces un diseño o planificación en el móvil mientras te mueves, y después lo implementas en tu máquina de trabajo sin tener que copiar y pegar el contexto.
Remote Control: Claude Code desde Claude.ai
Remote Control es una función que permite controlar tu instancia local de Claude Code desde Claude.ai o desde el app de Claude, mientras el agente tiene acceso completo a tu filesystem y herramientas locales. Corres el servidor de remote control en tu máquina y te conectas remotamente desde cualquier lugar:
# Inicia el servidor de remote control en tu máquina local
claude remote-control
También puedes iniciarlo para una sesión remota directamente
claude --remote "Implementa la autenticación OAuth para el proyecto en curso"La diferencia con simplemente usar Claude.ai es que Remote Control le da acceso al agente a tu entorno local real: puede leer y editar archivos en tu máquina, correr comandos en tu terminal, acceder a tus servidores de desarrollo locales y usar todos los MCP que tienes configurados. Es como tener un acceso remoto a tu entorno de desarrollo completo pero manejado por el agente.
Menciones con @ y el atajo Ctrl+R
Dentro de cualquier prompt puedes mencionar archivos directamente con @, lo que le dice a Claude Code que cargue ese archivo específico al contexto inmediatamente sin que tenga que buscarlo. Es más preciso que decirle "mira el archivo auth.ts" porque lo carga directamente:
# Ejemplo de mención directa en un prompt
refactoriza @src/auth/login.ts para usar los patrones de @src/auth/register.tsCtrl+R es el historial de prompts, similar al historial de bash. Si escribiste un prompt largo y perfecto en una sesión anterior, puedes recuperarlo con Ctrl+R en lugar de reescribirlo desde cero. Claude Code guarda un historial de tus prompts entre sesiones, así que funciona incluso si cerraste y reabriste el terminal. Para proyectos donde usas los mismos prompts complejos de forma recurrente, esto solo ahorra tiempo.
Finalmente, el modo Vim. Si eres usuario de Vim y te incomoda editar prompts largos con los controles por defecto de la terminal, Claude Code tiene un modo Vim integrado que activas con /vim dentro de la sesión. Desde ese punto puedes editar tus prompts con los keybindings de Vim antes de enviarlos. No es algo que la mayoría necesite, pero si ya sabes Vim es una comodidad que se agradece.
Preguntas frecuentes
¿Claude Code funciona sin conexión a internet?
No. Claude Code necesita conexión a internet para funcionar porque hace llamadas a la API de Anthropic para procesar cada prompt. El cliente en tu terminal es solo la interfaz: todo el procesamiento ocurre en los servidores de Anthropic. Lo que sí funciona localmente son las herramientas de lectura de archivos, ejecución de comandos y búsqueda en el código, pero el modelo de lenguaje siempre requiere conexión.
¿Mis archivos y código se envían a Anthropic?
Claude Code envía el contenido de los archivos que lee al API de Anthropic como parte del contexto de cada solicitud. Esto es necesario para que el modelo entienda tu código. Anthropic tiene una política de privacidad que cubre estos datos, pero si trabajas con código propietario muy sensible, revisa los términos de servicio y considera usar la integración con Amazon Bedrock o Google Vertex AI, que pueden ofrecer garantías adicionales de privacidad según los acuerdos que tengas con esos proveedores.
¿Puedo usar Claude Code con cualquier lenguaje de programación?
Claude Code funciona con cualquier lenguaje de programación porque trabaja sobre archivos de texto plano y entiende la mayoría de lenguajes que existen. Tiene mejor rendimiento con los lenguajes más comunes (Python, JavaScript, TypeScript, Go, Rust, Java, C/C++) pero puede trabajar con COBOL, Fortran, Solidity o cualquier otro lenguaje. La única limitación es el conocimiento del modelo subyacente sobre ese lenguaje específico.
¿Qué diferencia hay entre usar Claude Code y Claude.ai para código?
La diferencia es el acceso al entorno local. Claude.ai en el navegador solo puede ver lo que le copias y pegas en el chat. Claude Code tiene acceso completo a tu filesystem, puede ejecutar comandos en tu terminal, leer múltiples archivos en paralelo, hacer commits de git, correr tests y mucho más. Es la diferencia entre un asesor que solo puede ver los documentos que le muestras versus uno que puede entrar a tu oficina y trabajar con todos tus archivos directamente. Si usas Claude Code para marketing y no solo para programación, revisa también el artículo sobre Claude Code para marketing donde exploramos casos de uso no técnicos.
¿Cuánto consume Claude Code del contexto disponible?
Depende mucho de cuántos archivos lees y qué tan largo es el historial de la sesión. Usa /context dentro de la sesión para ver el uso actual. Cuando el contexto se acerca al límite, el rendimiento baja y Claude Code puede empezar a "olvidar" cosas de la conversación. Los dos remedios son /compact para comprimir el historial manteniendo los puntos clave, o /clear para empezar fresco. Para tareas largas, es buena práctica dividirlas en sesiones más cortas y documentar el estado en CLAUDE.md al final de cada sesión.
Lo que cambia cuando dejas de teclear y empiezas a dirigir
Hay una curva de aprendizaje en Claude Code que no tiene que ver con los comandos sino con el cambio de mentalidad. Al principio lo usas como un autocompletar avanzado: le pides cosas pequeñas y específicas, revisas cada línea, corriges manualmente lo que no quedó bien. Eso está bien para empezar, pero no es donde está el valor real de la herramienta.
El salto ocurre cuando empiezas a delegar tareas completas, no instrucciones. En lugar de "escribe esta función", le dices "implementa la autenticación OAuth para GitHub siguiendo los patrones que ya usamos para Google en auth/google.ts, incluyendo tests y actualizando la documentación". En lugar de revisar código tú mismo, configuras un hook que corre el linter automáticamente y un skill de revisión de PR que busca los problemas que tu equipo suele pasar por alto. Esto es lo que hace que la diferencia entre productividad básica y productividad real con Claude Code sea de 3,5 veces, no de 20%.
La infraestructura que armaste en este tutorial, el CLAUDE.md con las convenciones del proyecto, los skills para tareas repetitivas, los hooks que automatizan la calidad del código, los MCP conectados a tus herramientas, esa infraestructura se amortiza cada vez que la usas. La primera vez que configuras el hook de linting automático te toma 20 minutos. De ahí en adelante es invisible y funciona solo. Lo mismo con el CLAUDE.md: una hora de documentar bien el proyecto te ahorra explicaciones repetidas por meses.
Si quieres entender qué plan de Claude tiene más sentido para tu caso de uso y cuánto cuesta realmente usarlo con la intensidad que muestra este tutorial, el próximo paso es leer el análisis de precios de Claude Code donde comparamos las opciones disponibles con números concretos. Y si ya tienes la herramienta funcionando y quieres ver cómo aplicarla más allá del desarrollo de software, el artículo sobre Claude Code para marketing tiene casos de uso que probablemente no consideraste.
La herramienta ya la tienes instalada. Lo que hace la diferencia ahora es qué tan bien le enseñas cómo trabaja tu equipo.
© 2026 Andres Ospina
