How to Use Claude Code (Beginner Guide)

Tabla de contenidos

• A quién va dirigida esta guía
• Capítulo 1: ¿Qué es Claude Code?
• Capítulo 2: Instalar Claude Code
• Capítulo 3: Inicia tu primera sesión
• Capítulo 4: Haz mejores preguntas
• Capítulo 5: Realiza tu primer cambio de código
• Capítulo 6: Usa CLAUDE.md como memoria del proyecto
• Capítulo 7: Usa el modo plan antes de hacer cambios grandes
• Capítulo 8: Gestiona el contexto, los comandos y los permisos
• Capítulo 9: Amplía Claude Code con habilidades, ganchos y MCP
• Capítulo 10: Un flujo de trabajo seguro para principiantes
• Errores comunes que los principiantes deben evitar
• Preguntas frecuentes

A quién va dirigida esta guía

Claude Code puede resultar intimidante la primera vez que se abre. No se comporta como una herramienta de autocompletado normal: puede inspeccionar un proyecto, buscar archivos, editar código, ejecutar comandos, resumir errores y ayudar a verificar si un cambio funciona. Todo esto es muy potente, pero también significa que los principiantes necesitan un modelo mental claro antes de dejarlo actuar libremente en un repositorio real.

Esta guía es para ti si:

• Has oído hablar de Claude Code pero aún no lo has probado.
• Lo has instalado, pero no sabes muy bien qué escribir primero.
• Utilizas herramientas como GitHub Copilot y quieres entender en qué se diferencia Claude Code.
• Buscas un flujo de trabajo seguro para pedirle a Claude Code que edite archivos.
• Quieres comprender conceptos sencillos para principiantes como CLAUDE.md, el modo plan, las habilidades, los ganchos (hooks) y el protocolo MCP.

El objetivo no es convertirte en un experto en automatización en una sola sentada, sino ayudarte a utilizar Claude Code con confianza desde el primer día y mostrarte qué pasos dar a continuación.

Capítulo 1: ¿Qué es Claude Code?

Claude Code es un asistente de programación basado en agentes desarrollado por Anthropic. En lugar de limitarse a sugerir las siguientes líneas de código, puede llevar a cabo una tarea de varios pasos: leer archivos, comprender la estructura del proyecto, proponer modificaciones, editar el código, ejecutar pruebas y explicar los resultados.

Esto es lo que lo diferencia de una herramienta de autocompletado convencional.

Tipo de herramienta	Qué suele hacer	Cómo interactúas con ella
Autocompletado de código	Sugiere código cerca de tu cursor	Sigues escribiendo el código manualmente
Asistente de chat	Responde preguntas o redacta fragmentos de código	Copias, pegas y adaptas la respuesta
Claude Code	Realiza tareas de desarrollo dentro de tu proyecto	Describes el objetivo y revisas sus acciones

Por ejemplo, en lugar de preguntar:

Write a React component for a login form.

puedes pedirle:

Find the existing auth UI pattern in this repo and add a login form that matches it. Run the relevant tests afterward.

Claude Code puede inspeccionar el proyecto antes de decidir dónde y cómo realizar los cambios. Ese es el cambio principal: no te limitas a pedir código, sino un flujo de trabajo completo.

Claude Code se parece más a un compañero de programación capaz de trabajar en todo el proyecto que a una simple herramienta de autocompletado.

Capítulo 2: Instalar Claude Code

Antes de realizar la instalación, asegúrate de contar con lo siguiente:

• Una terminal o línea de comandos.
• Un proyecto de código en el que puedas hacer pruebas con seguridad.
• Acceso mediante una suscripción a Claude, una cuenta de Claude Console o un proveedor compatible.
• Git instalado si quieres que Claude Code inspeccione las diferencias (diffs) y trabaje con fluidez en los repositorios.

Instalación nativa recomendada

Para macOS, Linux o WSL, ejecuta:

curl -fsSL https://claude.ai/install.sh | bash

Para Windows PowerShell, ejecuta:

irm https://claude.ai/install.ps1 | iex

Para la consola de comandos de Windows (CMD), utiliza el comando específico de la guía de inicio rápido oficial:

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Una vez completada la instalación, verifícala con:

claude --version

Si el sistema indica que no se encuentra el comando claude, es posible que el directorio de instalación no esté incluido en la variable PATH. En macOS o Linux, el binario suele encontrarse en ~/.local/bin; en Windows, en %USERPROFILE%\.local\bin.

Otras opciones de instalación

Claude Code también es compatible con gestores de paquetes como Homebrew y WinGet:

brew install --cask claude-code

winget install Anthropic.ClaudeCode

La instalación nativa suele ser la opción más recomendada para principiantes, ya que se actualiza automáticamente en segundo plano. Los métodos mediante gestores de paquetes pueden requerir actualizaciones manuales.

Un proceso de instalación sencillo en la terminal: instalar, verificar con claude --version y abrir la carpeta del proyecto.

Capítulo 3: Inicia tu primera sesión

Abre una terminal dentro de la carpeta de tu proyecto:

cd /path/to/your/project claude

Al utilizarlo por primera vez, Claude Code te pedirá que inicies sesión. Sigue el flujo de autenticación en el navegador y regresa a la terminal.

Una vez dentro de Claude Code, comienza con una pregunta de solo lectura:

What does this project do?

A continuación, prueba con:

Explain the folder structure.

What commands should I run to test this project?

Estas consultas son ideales para principiantes, ya que permiten que Claude Code inspeccione el proyecto sin modificar ningún archivo de inmediato.

Una primera sesión segura comienza comprendiendo el proyecto en lugar de lanzarse a cambiar código al instante.

Capítulo 4: Haz mejores preguntas

Claude Code ofrece sus mejores resultados cuando describes con claridad el objetivo, el contexto relevante y los criterios de éxito. Aunque una instrucción imprecisa puede funcionar, una indicación precisa le da a Claude un objetivo mucho mejor definido.

Instrucción imprecisa	Instrucción ideal para principiantes
Arregla el error.	La página de inicio de sesión falla cuando el campo de correo está vacío. Encuentra la causa, arréglala y ejecuta las pruebas correspondientes.
Añade pruebas.	Añade pruebas para el flujo de cierre de sesión, especialmente para el caso en que la sesión del usuario haya expirado.
Actualiza la documentación.	Actualiza el archivo README para que un nuevo desarrollador pueda instalar las dependencias, ejecutar la aplicación y pasar las pruebas.
Mejora la interfaz de usuario.	Mejora el espaciado de la página de configuración para que coincida con el diseño del panel actual. Muéstrame las diferencias antes de editar.

Utiliza esta fórmula sencilla para redactar tus instrucciones:

Objetivo: Lo que deseas cambiar. Contexto: Archivos, errores o comportamientos relevantes. Restricciones: Lo que Claude debe evitar. Verificación: Cómo debe comprobar Claude el trabajo realizado.

Ejemplo:

Goal: Fix the failing checkout test. Context: The failure happens in tests/checkout.test.ts when discount codes are applied. Constraints: Do not change public API names. Verification: Run the checkout test file after the fix.

La línea de verificación es especialmente importante. Claude Code resulta mucho más útil cuando es capaz de comprobar su propio trabajo.

Capítulo 5: Realiza tu primer cambio de código

Para tu primera modificación, elige una tarea de bajo riesgo:

• Añadir una breve sección al README.
• Corregir una errata.
• Añadir una prueba unitaria sencilla.
• Explicar y refactorizar una función auxiliar pequeña.

Ejemplo de instrucción:

Update the README with a short "Running tests" section. First inspect package.json to find the right test command. Show me the proposed change before editing.

Por lo general, Claude Code seguirá estos pasos:

1. Leerá los archivos pertinentes. 2. Decidirá qué es necesario modificar. 3. Mostrará la propuesta de edición. 4. Pedirá tu aprobación. 5. Aplicará el cambio si das el visto bueno. 6. Ejecutará un comando si la tarea requiere verificación.

No apruebes nada a ciegas. Revisa las diferencias (diffs). Si algo no te convence, pídele que lo modifique:

This is too long for the README. Make it shorter and keep only the commands.

Los principiantes deben tratar las diferencias de Claude Code igual que una solicitud de extracción (pull request): leerlas, cuestionarlas y aprobarlas después.

Capítulo 6: Usa CLAUDE.md como memoria del proyecto

CLAUDE.md es un archivo en formato Markdown que proporciona a Claude Code un contexto persistente sobre el proyecto. Si este archivo existe en tu repositorio, Claude Code lo lee al inicio de cada sesión. Imagínalo como una nota de incorporación para un compañero competente.

Puedes crearlo manualmente o pedirle a Claude Code que lo inicialice con:

/init

Un archivo CLAUDE.md básico y útil para principiantes puede tener este aspecto:

# Guía del proyecto ## Stack - Next.js - TypeScript - pnpm - Vitest ## Comandos habituales - Instalar dependencias: pnpm install - Ejecutar servidor de desarrollo: pnpm dev - Ejecutar pruebas: pnpm test - Ejecutar linter: pnpm lint ## Reglas - Utiliza pnpm, no npm. - No edites archivos en src/legacy a menos que se solicite explícitamente. - Prefiere los componentes existentes en src/components/ui. - Ejecuta las pruebas de las áreas modificadas antes de dar la tarea por concluida.

Mantenlo breve. Un archivo CLAUDE.md demasiado extenso puede convertirse en ruido. Incluye únicamente aquellos aspectos que Claude no pueda deducir de forma fiable a partir del código:

• El gestor de paquetes correcto.
• Comandos que se apartan de las convenciones habituales.
• Directorios importantes que se deben evitar.
• Reglas de arquitectura específicas del proyecto.
• Expectativas en cuanto a las pruebas.

Evita llenarlo con consejos genéricos como «escribe código limpio», ya que Claude ya lo sabe. Utiliza CLAUDE.md para indicar datos y normas concretas que importan en tu proyecto.

CLAUDE.md proporciona a Claude Code instrucciones estables sobre el proyecto para que no tengas que repetirlas en cada sesión.

Capítulo 7: Usa el modo plan antes de hacer cambios grandes

El modo plan (plan mode) indica a Claude Code que investigue y proponga un plan sin modificar ningún archivo. Esto resulta sumamente útil para los principiantes, ya que ralentiza el flujo de trabajo y aporta precaución antes de realizar cambios arriesgados.

Utiliza el modo plan cuando:

• La tarea afecte a varios archivos.
• No tengas claro cuál es el mejor enfoque.
• Estés trabajando en código que no te resulta familiar.
• Quieres comparar diferentes opciones antes de editar.
• El cambio pueda influir en el comportamiento en producción.

Puedes activar el modo plan desde la interfaz de comandos:

claude --permission-mode plan

Dentro de una sesión, también puedes utilizar:

/plan Investigate why image upload fails and propose a fix. Do not edit files yet.

O bien alternar entre los modos de permisos pulsando Mayús + Tab si tu interfaz de Claude Code lo admite.

Un buen ejemplo de instrucción de planificación:

Use plan mode. Inspect the authentication flow and propose how to add password reset. Do not edit files yet. Include the files you expect to modify and the tests you would run.

Una vez que Claude proponga un plan, puedes aprobarlo, pedir cambios o seguir planificando. Si el plan es demasiado vago, no continúes; pídele uno más preciso:

Make the plan more specific. Name the likely files, risks, and verification steps.

El modo plan es la alternativa ideal para principiantes que buscan que Claude Code piense antes de empezar a editar.

Capítulo 8: Gestiona el contexto, los comandos y los permisos

Las sesiones de Claude Code cuentan con una ventana de contexto. A medida que la sesión se alarga, Claude acumula más historial que procesar: mensajes, contenidos de archivos, resultados de comandos, diferencias y explicaciones, lo que puede hacer que las sesiones largas pierdan enfoque.

Utiliza estos comandos desde el principio:

Comando	Qué hace	Caso de uso para principiantes
/help	Muestra los comandos disponibles	Aprender las funciones compatibles en tu sesión
/clear	Borra el historial de la conversación	Empezar desde cero al cambiar de tarea
/compact	Resume la sesión actual	Conservar la información clave reduciendo el contexto
/init	Crea un archivo CLAUDE.md inicial	Dotar a Claude de memoria sobre el proyecto
/login	Inicia sesión o cambia de cuenta	Solucionar problemas de autenticación
/permissions	Gestiona las acciones permitidas	Ajustar lo que Claude puede hacer de forma automática

Modos de permisos explicados de forma sencilla

Es posible que Claude Code pida confirmación antes de editar archivos o ejecutar comandos, lo cual constituye una excelente medida de seguridad para quienes empiezan.

Es probable que encuentres modos como los siguientes:

• Modo de revisión predeterminado: revisa las acciones a medida que se producen.
• Modo de aceptación de ediciones: permite las modificaciones y las revisa posteriormente.
• Modo plan: inspecciona y planifica sin editar.
• Modo automático: permite una mayor automatización bajo controles de seguridad, según tu plan y tipo de cuenta.

Los principiantes deben adoptar una postura conservadora: utilizar el modo plan para tareas complejas y revisar las diferencias con atención hasta que adquieran confianza con el flujo de trabajo.

Capítulo 9: Amplía Claude Code con habilidades, ganchos y MCP

Una vez que te sientas cómodo con el uso básico, Claude Code se puede ampliar. No necesitas estas funciones el primer día, pero conviene saber en qué consisten.

CLAUDE.md frente a Habilidades (Skills)

Utiliza CLAUDE.md para mantener un contexto activo permanente sobre el proyecto. Emplea las habilidades para flujos de trabajo reutilizables o instrucciones detalladas que solo deban cargarse cuando sea necesario.

Característica	Ideal para	Ejemplo
CLAUDE.md	Reglas del proyecto que Claude debe conocer siempre	«Usa pnpm. Ejecuta Vitest. Evita src/legacy».
Habilidad (Skill)	Procedimientos repetibles o conocimientos especializados	/release-checklist, /review-api, /write-docs

Una habilidad básica puede ubicarse en:

.claude/skills/review-pr/SKILL.md

Ejemplo:

--- description: Review a pull request for bugs, missing tests, and risky changes. --- Review the current diff. Focus on: - Behavior changes - Missing tests - Error handling - Security or data-loss risk Return findings first, then a short summary.

Y se puede invocar mediante:

/review-pr

Ganchos (Hooks)

Los ganchos se ejecutan cuando ocurren eventos específicos en Claude Code. Un gancho sencillo puede enviar una notificación al escritorio cuando Claude está esperando una entrada, o ejecutar un script de validación antes de ciertos comandos de shell.

Los principiantes deben manejar los ganchos con precaución, ya que uno mal configurado puede generar efectos secundarios confusos. Es mejor empezar con notificaciones inofensivas o comprobaciones de solo lectura.

MCP

MCP corresponde a Model Context Protocol (Protocolo de Contexto de Modelo). Permite que Claude Code se conecte a servicios y herramientas externos. Por ejemplo, un servidor MCP puede conectar Claude con:

• Una base de datos.
• Un navegador web.
• Sentry.
• Slack.
• GitHub.
• Herramientas internas de una empresa.

Dentro de Claude Code, el comando /mcp ayuda a gestionar los servidores MCP conectados y su autenticación. Utiliza MCP cuando Claude necesite datos o acciones ajenos al repositorio local.

CLAUDE.md, las habilidades, los ganchos y MCP resuelven diferentes necesidades de ampliación. Empieza por lo más sencillo y añade solo lo que realmente necesites.

Capítulo 10: Un flujo de trabajo seguro para principiantes

A continuación se detalla un flujo de trabajo práctico que puedes seguir durante tu primera semana.

Paso 1: Comienza con un estado de Git limpio

Antes de pedirle a Claude Code que edite nada:

git status

Si ya tienes trabajo importante sin confirmar, haz un commit o guárdalo temporalmente (stash) primero. Claude Code es más seguro cuando puedes revisar con nitidez qué ha cambiado.

Paso 2: Pide a Claude que comprenda el proyecto

What does this project do? Explain the main folders and the commands I should know.

Paso 3: Crea o perfecciona CLAUDE.md

/init

Revisa el archivo generado, elimina el contenido genérico e incorpora los comandos específicos de tu proyecto.

Paso 4: Utiliza el modo plan para los cambios reales

/plan Add a password reset page. Inspect the existing auth flow and propose a plan first.

Paso 5: Aprueba ediciones pequeñas y fáciles de revisar

Pide a Claude Code que implemente los cambios por partes:

Implement only the route and form component first. Do not wire email sending yet.

Paso 6: Ejecuta la verificación

Run the relevant tests and tell me exactly what passed or failed.

Si las pruebas fallan, pídele que diagnostique el problema:

The test failed. Explain the failure first, then propose the smallest fix.

Paso 7: Revisa las diferencias finales

git diff

Y a continuación, consulta:

Review the final diff for bugs, missing tests, and unnecessary changes.

Este flujo te mantiene al mando mientras permites que Claude Code realice un trabajo de utilidad.

Errores comunes que los principiantes deben evitar

Error 1: Pedir cambios gigantescos de inmediato

No empieces con:

Rewrite the whole app with a better architecture.

Es mejor empezar con algo más acotado:

Inspect the app architecture and identify the top three refactor opportunities. Do not edit files.

Error 2: No indicar un método de verificación

Si Claude no puede probar el trabajo, es posible que se detenga demasiado pronto. Indícale siempre cómo debe verificarlo:

After the change, run pnpm test -- checkout.

Error 3: Aprobar diferencias sin leerlas

Claude Code puede cometer errores. Revisa los cambios tal y como lo harías con la solicitud de extracción de un compañero.

Error 4: Permitir que una sesión se alargue demasiado

Utiliza /clear al cambiar de tarea y /compact cuando la sesión contenga contexto útil pero se haya vuelto excesivamente larga.

Error 5: Introducir credenciales secretas en las instrucciones o en CLAUDE.md

Nunca pegues claves de API, tokens privados, contraseñas de bases de datos o secretos de producción en las indicaciones ni en los archivos de memoria del proyecto. Utiliza variables de entorno y gestores de secretos.

Error 6: Utilizar extensiones avanzadas demasiado pronto

Las habilidades, ganchos, servidores MCP, subagentes y complementos son muy potentes. Los principiantes deben dominar primero:

1. Iniciar sesiones. 2. Redactar instrucciones claras. 3. Revisar diferencias. 4. Ejecutar pruebas. 5. Utilizar CLAUDE.md. 6. Usar el modo plan.

Añade extensiones más adelante cuando notes fricción repetitiva en tu día a día.

Preguntas frecuentes

¿Claude Code es exclusivo para desarrolladores experimentados?

No, pero resulta mucho más útil cuando comprendes los fundamentos de tu proyecto, Git y la terminal. Los principiantes pueden usarlo de manera segura empezando con preguntas de solo lectura, ediciones pequeñas y el modo plan.

¿Puede Claude Code sustituir el aprendizaje de la programación?

No. Puede acelerar tareas y explicar código, pero sigues necesitando comprender el resultado. Trátalo como a un socio de desarrollo, no como a un sustituto del criterio humano.

¿Edita Claude Code los archivos de forma automática?

Claude Code puede modificar archivos, pero normalmente solicita permiso antes de hacerlo. Puedes seleccionar distintos modos de permisos en función del nivel de revisión que prefieras.

¿Qué debo hacer si Claude Code introduce un cambio erróneo?

Utiliza Git. Revisa el comando git diff, pídele a Claude que explique la modificación o revierte el archivo tú mismo. Para tareas complejas, emplea el modo plan antes de editar.

¿Cuál es el primer comando que debo ejecutar en un proyecto nuevo?

Empieza con:

claude

A continuación, pregunta:

What does this project do, and what commands should I know?

Y después, ejecuta:

/init

para crear un archivo CLAUDE.md básico.

¿Cuándo se debe utilizar MCP?

Utiliza MCP cuando Claude Code necesite acceso a un servicio o herramienta externa, como una base de datos, Sentry, GitHub, Slack o un navegador. No necesitas MCP para la edición local básica de código.

¿Cuándo debo crear una habilidad (skill)?

Crea una habilidad cuando te encuentres pegando repetidamente las mismas instrucciones o listas de comprobación en Claude Code. Por ejemplo, una lista de verificación para lanzamientos, una pauta de revisión de código o un flujo de documentación pueden convertirse en una habilidad.