Cómo Usar Claude Code: Tutorial Paso a Paso

Introducción: ¿Qué es Claude Code?

Si alguna vez has intentado integrar un asistente de programación con IA en tu flujo de trabajo diario en la terminal, probablemente te hayas topado con el mismo problema: sabes lo que quieres lograr, pero no estás seguro de cómo configurar todo de forma segura, evitar interrupciones constantes y aun así confiar en los cambios que se están realizando.

En esta guía, aprenderás a usar Claude Code de manera práctica y repetible como una herramienta de línea de comandos para trabajo de desarrollo real. Comenzarás con una instalación segura, pasarás a la planificación en modo de solo lectura y luego avanzarás a ediciones en entorno aislado (sandbox) y ejecuciones de prueba. A partir de ahí, crearás Skills reutilizables, conectarás herramientas externas con MCP y automatizarás medidas de seguridad con Hooks—todo sin perder el control de tu código fuente.

Este recorrido está dirigido a desarrolladores (independientes o en equipo) que se sienten cómodos en la terminal y quieren un flujo de trabajo de programación con IA lo suficientemente seguro para proyectos reales. Si estás configurando esto en una organización, también es útil saber dónde se almacenan las credenciales, por ejemplo, el macOS Keychain cifrado en macOS.

Comencemos configurando el acceso para que tu primera sesión sea fluida.

Obtén acceso, instala Claude Code e inicia sesión

Antes de empezar a delegar trabajo de desarrollo real a Claude Code, necesitas una instalación limpia y un método de autenticación que se ajuste a cómo planeas usarlo.

Sigue estos pasos para instalar Claude Code y confirmar que puedes autenticarte:

1. Confirma que tienes Node.js 18+ instalado ejecutando node -v y verificando que reporte v18 o superior.
2. Instala Claude Code de forma global con: npm install -g @anthropic-ai/claude-code.
3. Inicia una sesión interactiva ejecutando claude, luego inicia sesión ingresando /login y completando el flujo en el navegador para tu cuenta de Claude.ai (recomendado) o Console.
4. Si prefieres autenticación basada en clave para scripts o uso no interactivo, configura ANTHROPIC_API_KEY en tu entorno de shell. Si tu organización usa proveedores de nube, confirma si debes autenticarte a través de Bedrock/Vertex para no configurar el tipo de credencial incorrecto.

Algunas cosas a tener en cuenta:

• Si estás en WSL y el instalador falla por detección de sistema operativo o un desajuste de npm/Node de Windows, usa el enfoque de corrección para WSL (incluyendo la opción documentada de instalación --force --no-os-check) y evita usar sudo, contra lo cual la documentación advierte explícitamente.
• Si estás iniciando sesión con una cuenta Free/Pro/Max, revisa tus controles de datos: desde el 28 de agosto de 2025, los usuarios consumidores pueden elegir si sus sesiones de programación pueden usarse para mejorar futuros modelos de Claude.

Después de este paso, claude debería iniciarse sin errores, y después de /login deberías poder enviar un prompt corto y recibir una respuesta.

Puntos clave:

• Instalaste Claude Code y estableciste un método de inicio de sesión funcional para tu entorno.
• Debes configurar correctamente la ruta de credenciales (/login interactivo vs clave API vs proveedor administrado) antes de intentar flujos de trabajo reales.
• Debes estar atento a problemas de rutas de WSL/Node y confirmar la configuración de compartición de datos de tu cuenta para no llevarte sorpresas después.

Abre un proyecto y planifica de forma segura: asistente de programación con IA en modo de solo lectura

Antes de dejar que Claude Code modifique archivos o ejecute comandos, quieres que entienda tu código fuente y proponga un enfoque concreto en un modo que impida la ejecución.

Sigue estos pasos para abrir tu repositorio y forzar un ciclo de planificación seguro:

1. Navega a la raíz de tu proyecto ejecutando cd /path/to/your-repo (elige la carpeta que contiene tu package.json, pyproject.toml o go.mod).

2. Inicia Claude Code desde ese directorio ejecutando claude, luego confirma que aterrizas en un prompt interactivo vinculado a este repositorio.

3. Cambia al Modo Plan escribiendo /plan (o alterna entre modos con Shift+Tab / Alt+M).

4. (Opcional) Si quieres que el modo plan sea el predeterminado para cada sesión, crea un archivo .claude/settings.json usando las opciones oficiales de configuración:

   • Agrega "defaultMode": "plan" para que las nuevas sesiones se abran en modo planificación por defecto.
   • Agrega una lista de permissions.deny para archivos que nunca quieras que Claude Code lea (.env, secrets/, archivos de credenciales).

5. Verifica tu configuración activa ejecutando claude config list como se recomienda en la guía de configuración, luego confirma que tus ajustes se aplicaron.

6. Pide un plan lo suficientemente específico para aprobar: "En modo plan, describe el conjunto mínimo de cambios para corregir X, lista los archivos exactos que vas a modificar e incluye los comandos que ejecutarías para validarlo." Confirma que Claude solo propone pasos (porque el modo plan no ejecuta nada).

Algunas cosas a tener en cuenta:

• Mantén tu primer prompt acotado: un plan que nombre archivos, funciones y comandos es mucho más fácil de aprobar que una reescritura general.
• Si te sientes tentado a acelerar después de que te guste el plan, trata acceptEdits como una configuración intencional de "fase de implementación", no algo que actives mientras aún estás explorando.
• Si claude config list no refleja tus cambios, verifica que creaste .claude/settings.json en el repositorio desde el cual iniciaste Claude Code.

Sabrás que este paso funcionó cuando Claude responda con un plan estructurado (archivos a modificar + comandos de validación) y no intente ejecutar herramientas ni modificar archivos mientras permanezcas en el Modo Plan.

Puntos clave:

• Abriste Claude Code en el contexto correcto del proyecto y forzaste un flujo de trabajo de planificación primero antes de cualquier ejecución.
• Debes configurar el Modo Plan y los controles de alcance de tu .claude/settings.json antes de pedir trabajo de múltiples pasos.
• Debes estar atento a desajustes de configuración (repositorio incorrecto, ruta de archivo incorrecta) y solo cambiar a modos de permisos más rápidos después de haber aprobado un plan concreto.

Aplica cambios, ejecuta pruebas y habilita el entorno aislado para generación de código con IA

Ahora que tienes un plan aprobado, el objetivo es implementarlo con acceso de escritura controlado y luego validar el cambio con comandos de prueba reales en un entorno de ejecución más seguro.

Sigue estos pasos para aplicar el plan, ejecutar validaciones y reducir riesgos:

1. Cuando tu plan esté listo, Claude Code te preguntará "¿Cómo te gustaría proceder?" y ofrecerá opciones como "Sí, y aceptar ediciones automáticamente" o "Sí, aprobar ediciones manualmente"—elige una para comenzar la implementación.
2. Aprueba las ediciones de archivos por lotes, luego revisa inmediatamente lo que cambió ejecutando git diff en un panel de terminal separado.
3. Habilita la ejecución en entorno aislado ejecutando el comando /sandbox y seleccionando la opción de sandbox que se ajuste a tu flujo de trabajo.
4. Prefiere la ejecución automática en sandbox para tareas rutinarias eligiendo el modo de auto-aprobación para que Claude pueda ejecutar comandos comunes de pruebas y linting sin detenerse repetidamente para pedir aprobación.
5. Ejecuta el comando de prueba de tu proyecto desde la raíz del repositorio, como npm run test o pytest && coverage report como se muestra en los ejemplos de la herramienta bash.
6. Maneja intencionalmente los comandos incompatibles con el sandbox: si Claude Code ofrece la vía de escape para ejecutar algo fuera del sandbox, detente y verifica que el comando sea seguro antes de permitirlo.

Algunas cosas a tener en cuenta:

• Mantén la "fase de edición" y la "fase de verificación" separadas: primero revisa los diffs, luego ejecuta las pruebas.
• Trata la ejecución de comandos como un riesgo más alto porque puede ser acceso directo al sistema; en caso de duda, ejecuta el comando tú mismo o mantenlo en el sandbox.
• Si las pruebas fallan, no amplíes el alcance; pide a Claude que corrija solo las pruebas fallidas o la ruta mínima de código implicada en el fallo, y luego vuelve a ejecutar.

En este punto, tu repositorio debería mostrar solo las ediciones previstas en git diff, y tu comando de prueba debería completarse exitosamente.

Puntos clave:

• Implementaste un plan aprobado y entraste en un ciclo ajustado de "editar → revisar diff → ejecutar pruebas" antes de hacer cualquier otra cosa.
• Obtienes la mayor seguridad y velocidad habilitando el sandbox temprano y ejecutando pruebas dentro de él siempre que sea posible.
• Debes estar atento a solicitudes de usar la vía de escape del sandbox y tratarlas como una señal para ir más despacio y verificar.

Crea tu primer Skill: un tutorial de Claude Code

Una vez que te sientas cómodo con el ciclo "planificar → implementar → probar", la forma más rápida de subir de nivel es hacer reutilizables tus mejores prompts. Los Skills son la forma moderna de hacer esto en Claude Code—son paquetes de capacidades autocontenidos que Claude descubre y carga automáticamente cuando tu solicitud coincide con la descripción del skill.

Un skill es una carpeta que contiene un archivo SKILL.md obligatorio más directorios opcionales de soporte. Claude usa un modelo de divulgación progresiva: lee los metadatos primero (para descubrimiento), carga las instrucciones principales cuando se activa, y extrae archivos de soporte solo cuando es necesario—manteniendo tu contexto ligero.

Aquí está la estructura de carpetas recomendada:

pr-summarizer/
├── SKILL.md          # Required: frontmatter + core instructions
├── references/       # Optional: deep docs, edge cases, API specs
├── examples/         # Optional: sample inputs/outputs
└── scripts/          # Optional: executable helpers (Python/Bash/Node)

Sigue estos pasos para crear y probar tu primer skill:

1. Crea la carpeta del skill en tu proyecto ejecutando mkdir -p .claude/skills/pr-summarizer (usa .claude/skills/ para skills compartidos del proyecto que se suben al repositorio con git, o ~/.claude/skills/ para skills personales).
2. Crea el archivo SKILL.md obligatorio con frontmatter YAML que contenga un name y description—la descripción es crítica porque Claude la usa para decidir cuándo cargar el skill:

---
name: pr-summarizer
description: Summarize a pull request diff and produce a changelog entry. Use when asked to summarize, review, or create release notes from a PR or diff.
allowed-tools: Read, Grep, Glob, Bash(git diff)
---

When triggered, follow these steps:

1. Read the PR title, body, and diff
2. Extract high-level changes, breaking changes, and impacted modules
3. Return a 3-sentence summary and a one-paragraph changelog entry

Example output format:
**Summary:** Added user authentication flow with OAuth2 support...
**Changelog:** This release introduces OAuth2-based authentication...

1. Mantén SKILL.md conciso (apunta a 1,500–2,000 palabras; no superes las 3,000) organizando el contenido de soporte en subcarpetas:

   • references/ — documentación detallada, esquemas, guías de solución de problemas
   • examples/ — entradas/salidas de ejemplo, demos ejecutables
   • scripts/ — ayudantes ejecutables que se ejecutan sin cargarse en el contexto

2. (Opcional) Agrega un archivo de referencia para casos límite. Crea references/EDGE-CASES.md:

# Edge Cases for PR Summarizer

## Merge commits
When summarizing merge commits, focus on the merged branch's changes, not the merge commit itself.

## Empty diffs
If the diff is empty, return: "No code changes detected. This may be a metadata-only update."

Luego referéncialo en tu SKILL.md: "For edge cases, see references/EDGE-CASES.md."

1. Reinicia Claude Code en el repositorio, luego prueba el descubrimiento pidiendo algo que debería activar el skill (por ejemplo: "Resume los cambios de mi último commit como una entrada de changelog") y confirma que Claude carga y sigue las instrucciones de tu skill.
2. Si Claude no activa el skill cuando lo esperas, mejora el campo description agregando palabras clave de activación más claras y frases de ejemplo del usuario, luego prueba de nuevo.

Algunas cosas a tener en cuenta:

• El campo name debe contener solo letras minúsculas, números y guiones (máximo 64 caracteres); el nombre de la carpeta debe coincidir. La description tiene un máximo de ~1,024 caracteres.
• Nunca escribas secretos o claves API directamente en SKILL.md o archivos de soporte—usa conexiones MCP o variables de entorno para acceder a servicios externos.
• Para skills que necesitan ejecución aislada (manteniendo la conversación principal limpia), agrega context: fork a tu frontmatter; esto ejecuta el skill en un contexto de sub-agente separado.
• Usa allowed-tools en el frontmatter para restringir qué herramientas puede acceder el skill—otorga solo lo necesario.

Sabrás que este paso funcionó cuando Claude cargue automáticamente tu skill basándose en una solicitud que coincida y produzca un resultado en el formato que especificaste en SKILL.md.

Puntos clave:

• Los Skills son la forma moderna y recomendada de empaquetar capacidades reutilizables en Claude Code—han reemplazado en gran medida a los subagentes para la mayoría de los flujos de trabajo.
• Obtienes el mejor descubrimiento escribiendo una description clara con palabras clave de activación explícitas y manteniendo SKILL.md enfocado en las instrucciones principales.
• Debes usar la estructura de carpetas (references/, examples/, scripts/) para mantener tu skill principal conciso mientras le proporcionas a Claude contexto profundo cuando sea necesario.

Conecta herramientas externas de programación con IA mediante MCP

MCP (Model Context Protocol) es un estándar abierto que permite a Claude Code comunicarse con servidores externos que exponen herramientas, recursos y datos. Piénsalo como un adaptador universal: en lugar de pegar descripciones de issues o resultados de bases de datos en tu prompt, conectas un servidor MCP y Claude lo consulta directamente.

Sigue estos pasos para agregar tu primer servidor MCP:

1. Decide si necesitas un servidor HTTP remoto (para servicios en la nube como Notion, Linear o APIs alojadas) o un servidor stdio local (para herramientas que necesitan acceso directo al sistema de archivos); HTTP es lo recomendado para la mayoría de las integraciones.
2. Agrega un servidor MCP remoto usando la CLI: claude mcp add --transport http notion https://mcp.notion.com/mcp (reemplaza con el endpoint real de tu servicio).
3. Para servidores que requieren autenticación, incluye la bandera de encabezado: claude mcp add --transport http linear https://api.linear.app/mcp --header "Authorization: Bearer your-token".
4. Verifica que tu servidor fue agregado ejecutando claude mcp list, luego inspecciona su configuración con claude mcp get <name>.
5. Prueba la conexión pidiendo a Claude que use la integración (por ejemplo: "Lista mis issues abiertos de Linear" o "Encuentra la página de Notion sobre onboarding").

Para servidores locales o configuración compartida en equipo, crea un archivo .mcp.json en la raíz de tu proyecto:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-filesystem"],
      "env": {
        "ALLOWED_PATHS": "/Users/me/projects"
      }
    }
  }
}

Algunas cosas a tener en cuenta:

• Minimiza el alcance de tokens y restringe ALLOWED_PATHS para servidores de sistema de archivos—el principio de mínimo privilegio aplica aquí.
• Los servidores MCP han tenido vulnerabilidades de seguridad corregidas en el pasado; mantén tus servidores actualizados y solo usa servidores de fuentes confiables.
• La salida de herramientas genera una advertencia a los 10,000 tokens y tiene un límite máximo de 25,000 tokens por defecto; considera paginación o acotar más las consultas para respuestas grandes.

Sabrás que este paso funcionó cuando Claude pueda consultar o actuar exitosamente sobre un sistema externo (como listar issues o leer un documento) sin que tengas que pegar el contenido manualmente.

Puntos clave:

• MCP es la forma de conectar Claude Code con herramientas externas y fuentes de datos—es un protocolo abierto soportado en múltiples plataformas de IA.
• Obtienes el mayor valor comenzando con una integración que uses a diario (como tu gestor de issues) y expandiendo solo después de que funcione de manera confiable.
• Debes estar atento a permisos demasiado amplios; acota rutas de archivos y tokens de API de manera restrictiva, y mantén los servidores MCP actualizados.

Automatiza medidas de seguridad con Hooks

Los Hooks te permiten ejecutar comandos de shell automáticamente en puntos específicos del ciclo de vida de Claude Code—cuando envías un prompt, antes o después de que se ejecute una herramienta, o cuando inicia una sesión. Úsalos para automatización ligera como aplicar estilos de código, registrar comandos o bloquear operaciones riesgosas.

Sigue estos pasos para agregar tu primer hook:

1. Decide una automatización de bajo riesgo para comenzar, como registrar cuando Claude ejecuta ciertos comandos o formatear código automáticamente después de ediciones.
2. Agrega un hook al .claude/settings.json de tu proyecto (o ~/.claude/settings.json para alcance de usuario) siguiendo la guía de hooks. Aquí tienes uno inicial que registra cada comando Bash que Claude ejecuta:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"$(date): $(echo $CLAUDE_TOOL_INPUT | jq -r '.command')\" >> ~/.claude/command-log.txt"
          }
        ]
      }
    ]
  }
}

1. Para un hook más práctico, ejecuta Prettier automáticamente en archivos TypeScript después de cada edición agregando un hook PostToolUse:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write $(echo $CLAUDE_TOOL_INPUT | jq -r '.file_path') 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

1. Reinicia Claude Code y activa el hook ejecutando un comando que coincida con tu matcher, luego verifica que el hook se ejecutó revisando tu archivo de log o la salida formateada.
2. Depura hooks ejecutando /hooks dentro de Claude Code para inspeccionar los hooks registrados, o usa claude --debug para ver los registros de ejecución de hooks.

Algunas cosas a tener en cuenta:

• Los hooks ejecutan comandos de shell arbitrarios como tu usuario, así que comienza con acciones de solo lectura o registro antes de agregar algo que modifique el estado.
• Los hooks se ejecutan con un tiempo límite de 60 segundos por defecto; mantén los comandos rápidos para que no retrasen el flujo de trabajo de Claude.
• Usa el código de salida 2 para bloquear una operación (para hooks PreToolUse que deben rechazar comandos peligrosos); otros códigos distintos de cero son advertencias no bloqueantes.

Sabrás que este paso funcionó cuando tu hook se active de manera confiable y produzca una salida observable (una entrada de log, archivo formateado o comando bloqueado) en el punto de activación esperado.

Puntos clave:

• Los Hooks son automatización ligera que ejecuta comandos de shell en puntos específicos del ciclo de vida de Claude Code—úsalos para medidas de seguridad, formateo y registro.
• Obtienes la mayor seguridad comenzando con hooks inofensivos y observables antes de avanzar a cualquier cosa que modifique archivos o bloquee operaciones.
• Debes estar atento a hooks lentos o inestables; pruébalos de forma aislada y usa /hooks o --debug para solucionar problemas.

Avanza más rápido con DeepStation

Leer una guía es un gran comienzo, pero las verdaderas ganancias de velocidad llegan cuando tu configuración de Claude Code se convierte en memoria muscular entre proyectos. DeepStation te ayuda a lograr exactamente eso al acelerar la educación en IA y la innovación a través del poder de la comunidad—para que puedas comparar flujos de trabajo reales, explorar consejos de programación con IA de otros desarrolladores y convertir "prompts de una sola vez" en un proceso consistente y más seguro de Claude Code en el que puedas confiar.

Si estás listo para tomar impulso esta semana, únete ahora y comienza a mejorar junto con otros desarrolladores que están perfeccionando su flujo de trabajo con Claude Code, mejores prácticas de programación con IA y rutinas de automatización para desarrolladores. ¡Regístrate hoy para capacitación en flujos de trabajo de Claude Code y educación en IA! Los lugares en las sesiones activas de la comunidad se llenan rápido—asegura tu lugar y convierte tu próxima sesión de terminal en progreso medible.