Claude Code: guía de inicio en español (instalación, CLAUDE.md y primeros pasos)

Claude Code es una herramienta de Anthropic que funciona como un agente de programación: entiende tu proyecto, edita archivos en varios lugares, ejecuta comandos y se integra con tus herramientas de desarrollo. No es un autocompletado, es más parecido a un compañero al que le describes una tarea y que la lleva a cabo mientras tú revisas.

En esta guía verás cómo instalarlo, cómo iniciar tu primera sesión y las tres cosas que más ayudan a sacarle provecho: CLAUDE.md, los skills y los hooks.

Dónde puedes usarlo

Todas las superficies usan el mismo motor, así que tu configuración se comparte entre ellas:

• Terminal (CLI): la versión más completa.
• Extensión de VS Code (y Cursor): diffs en línea, menciones con @ y revisión de planes dentro del editor.
• Plugin de JetBrains.
• App de escritorio (macOS y Windows).
• Web, en claude.ai/code.

La mayoría de las superficies requieren una suscripción de Claude o una cuenta de la Anthropic Console (la app de escritorio requiere una suscripción de pago). La CLI, VS Code y JetBrains también admiten proveedores de terceros. Consulta los requisitos vigentes en la documentación oficial.

Instalación en la terminal

En macOS, Linux o WSL, el instalador nativo es la opción recomendada y se actualiza solo:

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

En Windows con PowerShell:

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

Si usas Homebrew:

brew install --cask claude-code

Con Homebrew las actualizaciones no son automáticas: corre brew upgrade claude-code de vez en cuando.

Abre una terminal nueva y verifica la instalación:

claude --version

Tu primera sesión

Entra a la carpeta de un proyecto y ejecuta claude:

cd mi-proyecto
claude

La primera vez te pedirá iniciar sesión. Después, escribe lo que necesitas en lenguaje natural. Por ejemplo:

• “Explícame cómo está organizado este proyecto.”
• “Escribe pruebas para el módulo de autenticación, ejecútalas y corrige lo que falle.”
• “Haz commit de mis cambios con un mensaje descriptivo.”

Según el modo de permisos en que estés, Claude te pedirá aprobación antes de acciones como editar archivos o correr comandos. Léelas antes de aceptar: es tu principal control.

También sirve como comando

Claude Code sigue la filosofía de Unix, así que puedes usarlo dentro de scripts y con pipes usando -p:

git diff main --name-only | claude -p "revisa estos archivos en busca de problemas de seguridad"

Esto es útil para automatizar tareas en CI o revisar logs.

CLAUDE.md: las instrucciones de tu proyecto

CLAUDE.md es un archivo markdown en la raíz de tu proyecto que Claude lee al iniciar cada sesión. Aquí defines lo que no quieres repetir todo el tiempo: convenciones de código, librerías preferidas, comandos para correr pruebas, decisiones de arquitectura.

Puedes generarlo con el comando /init: Claude analiza tu código y crea un archivo con los comandos de compilación, las instrucciones de pruebas y las convenciones que descubre. Si ya existe un CLAUDE.md, sugiere mejoras en lugar de sobrescribirlo. Un ejemplo para un blog en Astro:

# Blog

- Framework: Astro + Tailwind. No cambiar de framework.
- Los artículos están en `src/content/blog` en Markdown.
- Todo el contenido y la interfaz van en español.
- Antes de terminar una tarea, corre `yarn build`.

Según la documentación, las instrucciones específicas y concisas se siguen mejor, y conviene apuntar a menos de 200 líneas por archivo. Escribe lo que Claude no puede deducir leyendo el código. Ten en cuenta que CLAUDE.md es contexto, no una configuración obligatoria: para bloquear una acción de forma segura usa un hook. Claude además genera una memoria automática mientras trabaja, guardando aprendizajes entre sesiones.

Skills y hooks

• Skills: empaquetan flujos de trabajo repetibles que se invocan con /nombre. Te enseño a crear uno en este artículo.
• Hooks: ejecutan comandos de shell antes o después de las acciones de Claude, por ejemplo formatear el código tras cada edición o correr el linter antes de un commit.

Subagentes y MCP

Cuando una tarea es grande, Claude Code puede lanzar varios agentes que trabajan en paralelo en partes distintas. Y con MCP (Model Context Protocol) puede conectarse a servicios externos como Jira, Slack o Sentry. De eso trata el artículo sobre MCP.

Buenas prácticas para empezar

1. Pide un plan antes de cambios grandes. Revisarlo cuesta menos que deshacer código.
2. Trabaja con Git limpio. Así cualquier cambio es reversible con un git diff o git checkout.
3. Da contexto y criterios de éxito. “Arregla el bug” es peor que “el formulario falla al enviar con campos vacíos; debe mostrar un error y las pruebas deben pasar”.
4. Revisa siempre el resultado. Tú eres el responsable de lo que se despliega.

Conclusión

Instalar Claude Code lleva un par de minutos; lo que marca la diferencia es dedicarle un rato a tu CLAUDE.md y a los flujos que repites. En los siguientes artículos vamos a extenderlo con skills y con servidores MCP.

Fuentes

• Claude Code: Overview (documentación oficial)