Cómo usar Claude Code: planifica, dale buenos prompts y mantén el control

Casi todos conocen Claude por el chat: pegas código, recibes una respuesta, la copias y esperas que encaje. Claude Code funciona de otra manera. Trabaja dentro de tu proyecto: lee los archivos, hace los cambios, ejecuta tus tests y hace commit del resultado, pidiendo permiso por el camino. Así resulta mucho más útil que un chatbot para el software real, y más fácil de usar mal. Esta guía explica cómo usar Claude Code bien: instalarlo, la primera sesión, planificar antes de que escriba, prompts con los que pueda actuar, la configuración que lo mantiene encarrilado y los límites que conviene conocer antes de confiarle tu código.

Qué es Claude Code (y qué no es)

Claude Code es la herramienta de programación agéntica de Anthropic. «Agéntica» significa que no solo sugiere código: trabaja en bucle, elige su siguiente paso, usa herramientas y comprueba el resultado hasta terminar. En la práctica, busca en tu repositorio, lee y edita archivos del proyecto, ejecuta comandos de shell como tus tests o tu linter, usa git y se conecta a herramientas externas. La idea de ese bucle está en nuestra guía sobre qué son los agentes de IA.

Funciona en varios sitios con el mismo motor, y la configuración del proyecto te acompaña:

• La terminal: la versión completa, y la que trata esta guía.
• VS Code y los IDE de JetBrains: extensiones con diffs en línea y opción de compartir tu selección.
• La aplicación de escritorio: la pestaña Code de la app de Claude, con revisión visual de diffs y varias sesiones a la vez.
• La web y las apps móviles: en claude.ai/code, para tareas largas en repositorios que no tienes en local.

No es un autocompletado que termina tu línea, ni un sustituto de saber qué debe hacer tu código. Es más bien un compañero rápido e incansable recién llegado: lo lee todo enseguida, pero solo sabe lo que hay en el repositorio y lo que le cuentas. Si buscas respuestas, explicaciones o una segunda opinión sobre un fragmento, el chat normal de nuestra guía sobre cómo usar Claude es más sencillo.

Cómo instalar Claude Code e iniciar una sesión

Necesitas un plan de pago (Pro, Max, Ultra, Team o Enterprise), una cuenta de Claude Console con créditos de API o acceso mediante un proveedor de nube compatible como Amazon Bedrock. El plan gratuito no lo incluye.

El instalador recomendado es un comando. En macOS, Linux o WSL, ejecuta en una terminal curl -fsSL https://claude.ai/install.sh | bash. En Windows PowerShell es irm https://claude.ai/install.ps1 | iex. Homebrew (brew install --cask claude-code) y WinGet (winget install Anthropic.ClaudeCode) también sirven, pero, al contrario que el instalador nativo, no se actualizan solos. En Windows nativo, instala además Git for Windows para que Claude Code use una shell Bash.

Después:

1. En una terminal nueva, ejecuta claude --version para comprobarlo. Si no lo encuentra, la carpeta de instalación aún no está en tu PATH.
2. Entra en la carpeta de un proyecto con cd y escribe claude.
3. Inicia sesión cuando te lo pida. Se abre el navegador; las credenciales se guardan, así que basta una vez.
4. Escribe /help para ver los comandos disponibles. Con / solo, se listan comandos y skills según tecleas.

¿Prefieres no tocar la terminal? Instala la extensión de VS Code o abre la pestaña Code de la app de escritorio. Todo lo que sigue vale igual, con botones en vez de algunos atajos.

Tu primera sesión: explora y luego haz un cambio pequeño

No empieces con «hazme una funcionalidad». Deja que Claude Code lea el proyecto y te cuente qué encuentra. Verás cómo razona y cazarás malentendidos antes de que se vuelvan cambios. Sirven preguntas simples: «¿qué hace este proyecto?», «¿dónde está el punto de entrada principal?» o «explícame la estructura de carpetas». Con un código desconocido, pide una visita guiada completa:

Luego haz un cambio pequeño y seguro: una errata en el README, un test que falta o un mensaje de error más claro. Observa qué hace. Claude Code muestra cada cambio como un diff y, según el modo de permisos, pregunta antes de aplicarlo o lo aplica y te avisa. Elige Yes si el cambio parece correcto; si no, di qué falla.

Git también se maneja conversando: «¿qué archivos he cambiado?», «crea una rama llamada fix/login-timeout» o «haz commit de mis cambios con un mensaje descriptivo». Trabaja en una rama desde el principio para descartar fácilmente cualquier experimento.

Primero el plan, luego el código

Para algo más que un arreglo pequeño, el hábito más útil es separar pensar de teclear. En modo plan, Claude Code lee archivos y explora, pero no edita tu código fuente hasta que apruebes un plan por escrito. Actívalo con Shift+Tab (la línea de estado muestra «plan mode on») o empieza un prompt suelto con /plan.

Un buen prompt de planificación describe el resultado, las restricciones y cómo comprobar que funciona:

Con el plan listo, ofrece aprobarlo y seguir, aprobarlo revisando cada cambio, o seguir planificando. Léelo bien. Es el momento más barato para detectar una suposición errónea, como editar un archivo generado u olvidar una llamada en otro sitio. Ctrl+G abre el plan en tu editor para cambiarlo antes de aprobarlo.

Cómo escribir prompts con los que Claude Code pueda actuar

Claude Code lee tu repositorio, pero no tu mente ni tu pantalla. El consejo oficial: cuéntale lo que no puede encontrar solo. Nombra el archivo, describe el síntoma y di qué significa «arreglado». «Arregla el bug» lo manda a buscar; «arregla el bug del login que deja la pantalla en blanco tras una contraseña incorrecta» lo pone a trabajar.

Formas de darle contexto directamente:

• Cita archivos con @: @ seguido de una ruta, como @src/auth/session.ts, incluye ese archivo en tu mensaje.
• Pega el error real: la traza completa o la salida del test fallido vale más que una paráfrasis.
• Pega capturas de pantalla: útiles para fallos de maquetación o para copiar un diseño.
• Divide los trabajos grandes en pasos numerados: crea la tabla, luego el endpoint y luego la página que lo usa.

Para bugs, esta estructura funciona bien:

Esa última línea importa. Presionado para que un test pase, cualquier modelo puede caer en editar el test o en capturar y ocultar el error. Avisarlo de entrada lo evita. Nuestros prompts de IA para programar traen más plantillas para revisiones, refactorizaciones y documentación; el generador de prompts para Claude convierte una petición aproximada en un prompt estructurado como estos.

CLAUDE.md, permisos y deshacer: mantén el control

CLAUDE.md es un archivo Markdown en la raíz del proyecto que Claude Code lee al inicio de cada sesión. Con /init redacta uno a partir de tu código; a ti te toca sobre todo borrar líneas. Mantenlo corto (la documentación sugiere menos de 200 líneas) e incluye solo lo que Claude no deduce del código: los comandos exactos de compilación y tests, las convenciones de tu equipo, el paso de despliegue que vive en la cabeza de alguien, las carpetas que nunca debe tocar. Si ya tienes un AGENTS.md para otros agentes de programación, Claude Code puede leerlo en su lugar. Escribir estas instrucciones se parece mucho a escribir un prompt de sistema; nuestro generador de prompts de sistema te ayuda a estructurarlas.

Los modos de permisos deciden qué se ejecuta sin preguntar. Shift+Tab los recorre:

• Manual: Claude lee libremente, pero pregunta antes de editar o ejecutar comandos.
• Accept edits (aceptar cambios): se aplican los cambios y los comandos de archivos habituales en la carpeta del proyecto; los demás comandos siguen preguntando.
• Plan: exploración y plan por escrito, sin editar el código fuente.
• Auto, donde esté disponible: todo se ejecuta, y un modelo clasificador aparte revisa primero las acciones arriesgadas.

La documentación insiste en dos cosas. Primera: CLAUDE.md orienta, y Claude puede decidir que una línea no se aplica. Lo obligatorio va en una regla de denegación (por ejemplo, bloquear la lectura de archivos .env) o en un hook, un script que Claude Code ejecuta en momentos fijos, como antes de cada cambio o cuando intenta terminar. Segunda: nunca uses el modo que se salta todos los permisos fuera de un contenedor o máquina virtual desechable.

Si se tuerce, Esc lo para a mitad de una acción para reconducirlo. Esc dos veces con el prompt vacío, o /rewind, devuelve el código, la conversación o ambos a un punto anterior. Estos puntos de control solo cubren lo que Claude editó con sus propias herramientas, no lo hecho con comandos de shell, así que sigue haciendo commits.

Sesiones largas, costes y automatización

Cada mensaje reenvía la conversación entera, así que las sesiones largas gastan más del margen de tu plan o presupuesto de API. Casi todos los modelos Claude actuales tienen una ventana de contexto de un millón de tokens, y Claude Code compacta automáticamente el historial antiguo, así que rara vez se llena. El problema es pagar por historial que ya no necesitas, y distraerse con él. Los hábitos que ayudan:

• /clear entre tareas no relacionadas: no cuesta nada. /clear [NOMBRE] además nombra la sesión que dejas para volver a ella.
• /compact con un enfoque: /compact conserva los cambios de la API y los comandos de tests resume el resto.
• /usage y /context: muestran en qué se fue tu uso y qué llena el contexto.
• Retoma en vez de volver a explicar: claude -c continúa la última sesión de esa carpeta; /rename más claude --resume [NOMBRE] retoma días después un trabajo con nombre.

Dominado lo básico, va mucho más allá del chat. claude -p "[TAREA]" ejecuta un único prompt y sale, así que puedes pasarle logs por tubería o llamarlo desde scripts y CI; hay integraciones listas para GitHub Actions y GitLab. Los servidores MCP lo conectan con gestores de incidencias, bases de datos, archivos de diseño y otras herramientas. Las skills empaquetan procedimientos repetibles, como una checklist de publicación, que Claude carga solo si hacen falta, y los subagentes resuelven tareas secundarias en paralelo sin saturar la conversación principal.

Lo que Claude Code no puede hacer

• Saber lo que no está escrito: reglas de negocio, el porqué de un código raro o un despliegue que nadie documentó. Si no está en el repositorio, CLAUDE.md o tu prompt, lo adivinará.
• Garantizar código correcto: puede escribir código verosímil que pasa tests flojos y aun así falla en casos límite, seguridad o rendimiento. Revisa los diffs como la pull request de un compañero, sobre todo si tocan autenticación, pagos o borrado de datos.
• Hacer que entiendas tu propio sistema: dejarle escribirlo todo sin leerlo es vibe coding, válido para prototipos y arriesgado para lo que vayas a mantener.
• Resistir por sí solo instrucciones hostiles: las webs, incidencias, dependencias o archivos que lee pueden contener texto pensado para manipularlo. Los avisos de permisos, las reglas de denegación y el sandbox (/sandbox) existen en parte por ello; mira nuestra explicación sobre la inyección de prompts.
• Funcionar gratis: necesita un plan de pago o créditos de API, y las sesiones intensas agotan pronto los límites del plan. Mira los precios actuales antes de integrarlo en el flujo de un equipo.
• Seguir igual mucho tiempo: funciones, comandos y valores por defecto cambian a menudo. Si un comando de esta guía se comporta distinto, mandan la documentación oficial y /help.

Bien usado, te quita lo lento de programar: orientarte en un código desconocido, escribir los tests que te habrías saltado, perseguir un bug por seis archivos. El patrón que funciona no cambia: explora primero, planifica antes de editar, dale una comprobación que ejecutar, mantén CLAUDE.md corto y fiel, y revisa lo que te entrega. Tú sigues siendo el ingeniero; él teclea.

Referencias

• Anthropic — Descripción general de Claude Code (documentación oficial)
• Anthropic — Mejores prácticas para Claude Code
• Wikipedia — Claude (chatbot)