Guía básica de Claude Code: instalación, permisos, modelos y gestión del contexto

Claude Code es una herramienta de desarrollo con agentes que permite usar Claude de Anthropic desde el terminal y los repositorios de código. No se limita a responder con fragmentos de código, sino que, dentro del ámbito autorizado, explora y edita archivos, ejecuta comandos, realiza pruebas y analiza errores.

Esta guía explica no solo el procedimiento de instalación, sino también cómo configurar los permisos de forma segura, los criterios para elegir el modelo adecuado para cada tarea y cómo gestionar el contexto y las instrucciones del proyecto. Como los comandos y los entornos compatibles pueden actualizarse, al realizar la instalación se deben consultar los comandos más recientes que aparezcan en la documentación oficial de configuración.

Tres formas de programar con Claude

Cada modalidad se diferencia más por el grado de interacción de la herramienta con el proyecto local que por los resultados obtenidos.

Claude Code no es solo para desarrolladores profesionales. Sin embargo, como puede realizar operaciones que afectan al sistema, tales como eliminar archivos, instalar dependencias o ejecutar scripts de compilación, cuanto menos experimentado sea el usuario, más recomendable es utilizar el modo Plan junto con un sistema de control de versiones.

Requisitos previos a la instalación

Prepara primero los siguientes elementos.

• Consulta en la documentación oficial los sistemas operativos y entornos de shell compatibles actualmente.
• Prepara una cuenta de Anthropic con acceso a Claude Code o un entorno de autenticación y facturación compatible.
• Si se trata de un proyecto existente, crea un repositorio Git y confirma los cambios o haz una copia de seguridad.
• Identifica los comandos de pruebas, compilación y lint del proyecto.
• Puedes usar un editor como VS Code, pero VS Code en sí no es un requisito de Claude Code.

En Windows, debes comprobar las condiciones para PowerShell, el símbolo del sistema o WSL indicadas en la documentación oficial. Si el equipo está administrado por una organización, comprueba primero los permisos de instalación, el proxy, el firewall y las políticas de tratamiento de datos.

Instalación y primera ejecución de Claude Code

1. Consultar el comando oficial de instalación

En la documentación oficial de configuración de Claude Code, selecciona el método de instalación más reciente correspondiente a tu sistema operativo. Como los métodos y comandos de instalación pueden cambiar, es preferible basarse en la documentación oficial en lugar de reutilizar directamente comandos de vídeos o blogs antiguos.

2. Abrir la carpeta del proyecto

Crea una carpeta nueva o desplázate a un repositorio existente. Si usas VS Code, puedes abrir la carpeta mediante File > Open Folder y después seleccionar Terminal > New Terminal.

cd path/to/project
claude

Al ejecutar claude, se mostrará el proceso de autenticación en el navegador si es necesario. Tras iniciar sesión, Claude Code analiza el proyecto tomando como referencia el directorio de trabajo actual. Por eso, es más seguro ejecutarlo desde la raíz del repositorio real que desde el directorio de inicio o una carpeta superior con un ámbito excesivamente amplio.

3. Empezar con una primera solicitud pequeña

En lugar de encargarle desde el principio la creación de toda una aplicación, divide el alcance de la siguiente manera.

1. Pídele que lea y resuma la estructura del proyecto.
2. Pídele que presente un plan de implementación y los archivos que se modificarán.
3. Pídele que implemente una sola función.
4. Pídele que ejecute pruebas o análisis estáticos.
5. Pídele que explique los cambios y los riesgos pendientes.

Ejemplo de solicitud:

Lee este repositorio y resume su estructura y cómo se ejecuta. No modifiques todavía
ningún archivo; propón únicamente un plan para añadir un formulario de inicio de sesión
y los archivos que habría que modificar.

Modos de permisos y configuración segura

Los textos que identifican los modos de permisos de Claude Code pueden variar según la versión y la pantalla de configuración. Los conceptos de modo más representativos utilizados en la configuración oficial son los siguientes.

Shift+Tab puede utilizarse para cambiar entre algunos estados de permisos disponibles en la interfaz interactiva. Sin embargo, no todas las configuraciones se recorren necesariamente solo con este atajo, por lo que debes consultar el estado mostrado en la pantalla actual y la documentación oficial sobre permisos.

Flujo recomendado para principiantes

1. Obtén un plan de implementación en el modo Plan.
2. Revisa los archivos que se modificarán y los comandos que se ejecutarán.
3. Realiza la implementación en el modo Default o Accept Edits.
4. Comprueba personalmente la instalación de paquetes, los cambios en bases de datos y los comandos de eliminación.
5. Revisa git diff y los resultados de las pruebas antes de confirmar los cambios.

Bypass Permissions no es simplemente un modo rápido y cómodo. Puede agravar los daños causados por comandos incorrectos, un acceso excesivo a archivos o la exposición de información confidencial, por lo que no debe utilizarse como opción predeterminada en un ordenador personal o un repositorio importante.

Selección de modelos y gestión de costes

En una sesión interactiva, puedes usar /model para consultar o cambiar los modelos disponibles en tu cuenta y entorno. Como los nombres, alias y disponibilidad de los modelos pueden variar según el momento y el método de autenticación, es preferible no automatizar presuponiendo una lista fija de modelos.

/model

Los principios generales de selección son los siguientes.

Opus, Sonnet y Haiku son nombres que distinguen familias de modelos, pero las versiones exactas de cada familia y su compatibilidad con Claude Code pueden cambiar continuamente. En algunos entornos se pueden usar alias como /model sonnet, pero lo más preciso es comprobar las opciones que aparecen en la sesión actual.

Métodos prácticos para reducir costes

• Ejecuta la herramienta desde el subdirectorio necesario para reducir la exploración de archivos innecesarios.
• Indica de una sola vez el objetivo, las restricciones y los criterios de finalización para reducir el trabajo repetido.
• En lugar de proporcionar registros completos de gran tamaño, incluye el contexto del error y el procedimiento para reproducirlo.
• Excluye rutas innecesarias, como archivos generados, resultados de compilación y conjuntos de datos grandes.
• Cuando terminen la exploración y el diseño, organiza la sesión en torno a una nueva unidad de trabajo.
• Para tareas sencillas, utiliza dentro de las opciones disponibles un modelo más rápido y económico.
• Si el uso se basa en API, consulta conjuntamente los comandos relacionados con los costes y la información de uso de Anthropic Console.

La estructura de costes varía según el método de inicio de sesión. Las cuentas con suscripción a Claude pueden estar sujetas a límites de uso según el plan, mientras que el uso mediante la API de Anthropic o proveedores de servicios en la nube puede facturarse por tokens. Por tanto, no debe suponerse que un modelo concreto sea siempre gratuito o que cueste siempre una cantidad fija.

Gestión de la ventana de contexto

La ventana de contexto es el conjunto de conversaciones, contenido de archivos, resultados de herramientas, instrucciones del proyecto y demás información que el modelo puede consultar al generar la respuesta actual. No equivale a una memoria permanente ni al simple número de caracteres de la conversación.

Comandos principales

No existe un criterio universal según el cual la calidad de las respuestas disminuya necesariamente cuando el contexto supera un porcentaje determinado. Claude Code también puede realizar una compactación automática, y la calidad depende no solo de la cantidad de información incluida, sino también de su relevancia, redundancia y posibles contradicciones.

Considera organizar el contexto si observas las siguientes señales.

• Omite repetidamente requisitos que ya se han modificado.
• Confunde un estado antiguo de los archivos con el estado actual.
• Mezcla las condiciones de funciones diferentes.
• Lee innecesariamente el mismo archivo una y otra vez.
• La conversación y la salida de las herramientas se han vuelto excesivamente extensas.

No es necesario ejecutar /clear obligatoriamente cada vez que se completa una función. En su lugar, puedes reducir la pérdida de información documentando las decisiones completadas, los elementos pendientes y los resultados de las pruebas en la documentación o el registro de trabajo del proyecto antes de pasar a una nueva sesión.

Gestión de las instrucciones del proyecto con CLAUDE.md

El nombre del archivo suele escribirse como CLAUDE.md, con letras mayúsculas. Este archivo no constituye la memoria permanente de Claude, sino un documento de instrucciones persistentes que Claude Code consulta dentro del proyecto. Si se incluye en el repositorio, permite compartir las instrucciones con el equipo, pero no debe contener información confidencial.

El comando /init permite analizar el proyecto y comenzar a crear un archivo CLAUDE.md inicial, cuyo resultado siempre debe ser revisado por una persona.

Contenido recomendable

• Objetivo y funciones principales del proyecto
• Lenguajes, frameworks y versiones del entorno de ejecución
• Función de los directorios y módulos importantes
• Comandos de instalación, servidor de desarrollo, pruebas, lint y compilación
• Estilo del código y reglas de nomenclatura
• Archivos que no deben modificarse o código generado
• Principios de seguridad y tratamiento de datos personales
• Criterios de finalización del trabajo y procedimientos de verificación

Ejemplo:

# Instrucciones del proyecto

## Stack
- Se utilizan TypeScript y Node.js.
- El gestor de paquetes es pnpm.

## Comandos
- Pruebas: `pnpm test`
- Lint: `pnpm lint`
- Compilación: `pnpm build`

## Reglas
- No leer ni confirmar `.env` ni credenciales reales.
- Presentar primero un plan antes de cambiar el formato de respuesta de una API pública.
- Añadir las pruebas correspondientes cuando se modifique una función.

CLAUDE.md no tiene un límite máximo oficial de 200 líneas. Sin embargo, unas instrucciones demasiado extensas consumen contexto y pueden generar conflictos entre reglas, por lo que resulta práctico mantenerlas breves y concretas. Las explicaciones detalladas del diseño deben separarse en otros documentos, indicando las rutas necesarias.

Procedimiento de trabajo recomendado

El procedimiento básico para mejorar a la vez la seguridad y la calidad de los resultados es el siguiente.

1. Comprueba que el estado de Git esté limpio y crea una copia de seguridad o una confirmación.
2. Ejecuta Claude Code desde la raíz del repositorio.
3. Revisa CLAUDE.md y la documentación existente.
4. En el modo Plan, solicita el objetivo, los archivos que se modificarán y el plan de pruebas.
5. Divide las tareas grandes en unidades pequeñas que puedan revisarse.
6. Implementa una unidad cada vez en el modo Default o Accept Edits.
7. Revisa personalmente los comandos de instalación, eliminación, despliegue y modificación de datos.
8. Comprueba las pruebas, el lint, la verificación de tipos y git diff.
9. Documenta el estado final y los problemas pendientes.
10. Si la siguiente tarea no está relacionada con la conversación anterior, inicia una nueva sesión con /clear.

Lista de comprobación de seguridad

• Evita que .env, las claves de API, los certificados y los datos de clientes queden expuestos en el prompt o el repositorio.
• No experimentes directamente en servidores y bases de datos de producción.
• Lee antes de ejecutar comandos del shell o scripts de instalación cuyo origen desconozcas.
• Revisa también las dependencias, las licencias, las vulnerabilidades de seguridad y las pruebas del código escrito por Claude.
• En tareas importantes, aplica el principio de privilegios mínimos y utiliza un entorno de desarrollo aislado.
• Comprueba mediante Git diff los cambios generados automáticamente y asegúrate de que una persona asuma la responsabilidad final.

Claude Code puede acortar considerablemente el proceso de desarrollo, pero no es un mecanismo automático que garantice la exactitud y la seguridad de los resultados. La forma más fiable de utilizarlo consiste en combinar instrucciones claras, permisos limitados, unidades pequeñas de cambio, pruebas automatizadas y revisión humana.