Parece increible, pero en muy poco tiempo el mundo del desarrollo de software, en particular las actividades que tienen que ver con la programción, han cambiado radicalmente. Platicaba con un colega la forma de trabajo tan diferente que tenemos con respecto a lo que hacíamos hace tan solo un año. En la plática nos dimos cuenta de que no todo el mundo entiende aún bien los conceptos base más imporatentes del uso de agentes para el desarrollo, así que creo que este es el mejor lugar para comenzar a explicarlo. Sé que existen decenas de agentes, tecnologías, modelos, servicios, etc. Esta serie de artículos estarán basados en Claude Code, que es lo que uso en mi día a día y con lo que estoy más familiarizado, pero muchos conceptos son similares o compartidos por otras tecnologías.
Con este artículo inicio una nueva serie dedicada a las herramientas de desarrollo asistido por inteligencia artificial que están cambiando la forma en que escribimos, revisamos y mantenemos código. No hablaremos de plugins de autocompletado ni de ventanas de chat: hablaremos de agentes que pueden leer directamente el código de tu proyecto, desde tu workspace o desde tu repositorio, entender tu arquitectura (usando reglas, limitacione y estándares difinidas por ti miso), ejecutar comandos y proponerte cambios completos antes de que tú hayas terminado tu café.
En esta primera entrega explico qué es Claude Code, por qué es diferente a lo que probablemente ya conoces, cómo instalarlo, y los conceptos fundamentales que necesitas entender para usarlo bien: el contexto, la memoria y los permisos. En artículos posteriores profundizaremos en flujos de trabajo reales, integración con CI/CD y cómo sacarle provecho en proyectos Java.
Sin más preámbulos, vamos al tema.
Contenido
- ¿Qué es Claude Code y por qué debería importarte?
- La diferencia con los asistentes de chat tradicionales
- Instalación y configuración inicial
- Primeros pasos: los comandos esenciales
- El contexto: la memoria de trabajo del agente
- Ejemplo práctico: analizar y refactorizar código Java
- Modos de operación: interactivo vs. no-interactivo
- Memoria persistente: CLAUDE.md y Auto Memory
- Permisos: qué puede hacer el agente y qué no
- Conclusión y siguientes pasos
¿Qué es Claude Code y por qué debería importarte
Antes de entrar en los detalles técnicos, déjame hacerte una pregunta. ¿Cuántas veces al día abres un chat con una IA, le pegas un fragmento de código y esperas que te ayude a entender un error, sin que realmente pueda ver el resto de tu proyecto, los imports que tienes en la clase, el paquete en el que se encuentra, o el stack trace completo de tu aplicación? Lo que obtienes es ayuda sin contexto.
Claude Code es la respuesta de Anthropic a ese problema. Es una herramienta de línea de comandos que instala un agente de IA directamente en tu entorno de trabajo. Ese agente puede:
- Leer y navegar tu repositorio completo de forma autónoma
- Ejecutar comandos de shell, compilaciones y pruebas
- Editar archivos, crear nuevos y hacer commits a Git
- Buscar en la web cuando necesita información que no tiene
- Mantener una conversación contigo mientras trabaja
Dicho de otra forma: no es un asistente al que le preguntas cosas, es un colaborador que trabaja junto a ti dentro de tu proyecto.
Claude Code no reemplaza al developer; actúa como un developer júnior muy capaz que entiende el contexto completo de tu proyecto y puede ejecutar tareas por su cuenta, pero que sigue necesitando tu dirección y revisión.La diferencia con los asistentes de chat tradicionales
Para entender exactamente qué hace diferente a Claude Code, vale la pena hacer una comparación directa.
| Característica | Chat de IA (e.g. Claude.ai) | Claude Code (agente en terminal) |
|---|---|---|
| Contexto del proyecto | Solo lo que tú pegas en el chat | Acceso completo al repositorio |
| Ejecución de comandos | No | Sí (compilar, probar, buscar en archivos, etc.) |
| Modificación de archivos | Te muestra el código; tú lo copias | Edita directamente (con tu aprobación) |
| Integración con Git | No | Puede hacer commits, crear ramas, leer el historial |
| Modo de trabajo | Reactivo (responde preguntas) | Agéntico (planifica y ejecuta tareas completas) |
El cambio de paradigma es importante. Cuando trabajas con un chat, tú eres el intermediario: entiendes el contexto, lo reduces a un fragmento de código o descripción, se lo pegas a la IA, y luego tienes que integrar manualmente la respuesta en tu proyecto. Con Claude Code, ese ciclo se rompe.
Instalación y configuración inicial
Requisitos previos
Una aclaración importante antes de instalar: el método de instalación vía npm que verás en muchas guías antiguas está oficialmente deprecado por Anthropic. Hoy existe un instalador nativo que no requiere Node.js y que además se actualiza automáticamente en segundo plano. Es el método recomendado y el que usaremos aquí.
Lo único que necesitas es una cuenta de Anthropic con plan de pago (Claude Pro, Max, Teams o Enterprise). El plan gratuito de Claude.ai no incluye acceso a Claude Code. Si prefieres facturación por uso vía API, también puedes configurarlo con una clave de la Consola de Anthropic.
Instalación nativa (recomendada)
En macOS y Linux, un solo comando es suficiente:
curl -fsSL https://claude.ai/install.sh | bashEn Windows, ejecuta esto en PowerShell:
irm https://claude.ai/install.ps1 | iexTambién puedes instalarlo vía Homebrew en macOS:
brew install --cask claude-codeDespués de la instalación, abre una terminal nueva en el directorio raíz de tu proyecto y ejecuta:
claudeEn tu primera ejecución, Claude Code abrirá el navegador para que inicies sesión con tu cuenta de Anthropic. Una vez autenticado, verás el prompt interactivo del agente listo para recibir tareas.
brew upgrade claude-code periódicamente para mantenerte actualizado. El instalador nativo (curl o PowerShell) sí se actualiza en segundo plano sin que tengas que hacer nada.
Primeros pasos: los comandos esenciales
Claude Code funciona en modo conversacional: escribes una tarea en lenguaje natural y el agente la ejecuta. Pero también tiene una serie de comandos con barra (/comando) que conviene conocer desde el principio.
| Comando | Descripción |
|---|---|
/help |
Muestra la lista de todos los comandos disponibles |
/clear |
Limpia el historial de la conversación actual (libera contexto por completo) |
/compact |
Resume la conversación para reducir el uso de tokens sin perder el hilo |
/cost |
Muestra el costo estimado y el uso de tokens de la sesión actual |
/init |
Analiza tu proyecto y genera un CLAUDE.md inicial con contexto |
/memory |
Abre el panel de memoria para ver y editar los archivos de instrucciones |
/permissions |
Muestra y administra las reglas de permisos activas |
/doctor |
Diagnostica problemas de configuración del entorno |
/bug |
Reporta un problema a Anthropic directamente desde la sesión |
/exit |
Termina la sesión |
Las tareas en lenguaje natural que puedes pedirle al agente son prácticamente ilimitadas. Algunos ejemplos representativos:
# Analizar el código
> Explícame cómo funciona el módulo de autenticación en este proyecto
# Encontrar bugs
> Hay un NullPointerException en el servicio de pagos. Encuéntralo y corrígelo
# Refactorizar
> Refactoriza la clase OrderService para que use el patrón Strategy
# Escribir tests
> Escribe pruebas unitarias para el repositorio de usuarios con JUnit 5 y Mockito
# Documentar
> Agrega Javadoc a todos los métodos públicos de la clase PaymentGatewayEl contexto: la memoria de trabajo del agente
Para entender bien cómo funciona Claude Code, necesitas entender qué es el contexto. Es uno de esos conceptos que la mayoría de las guías asumen que ya conoces, pero que en realidad marca la diferencia entre usar la herramienta bien o pelearte con ella constantemente.
¿Qué es la ventana de contexto?
Imagina que el agente tiene una pizarra de trabajo. En esa pizarra caben aproximadamente 200,000 tokens (hablaré más de los tokens en una de las siguientes entradas de la serie), que viene a ser el equivalente a unos 150,000 palabras de texto. Todo lo que el agente puede "ver" en un momento dado cabe en esa pizarra: la conversación completa, el contenido de los archivos que ha leído, la salida de los comandos que ejecutó, y las instrucciones del sistema.
Cuando esa pizarra se llena, las cosas más antiguas empiezan a desaparecer para hacer espacio a las nuevas. El agente no "recuerda" lo que se borró a menos que lo hayas persistido en algún lado. Esto tiene implicaciones prácticas muy concretas:
- En sesiones largas, el agente puede "olvidar" decisiones que tomaron juntos al inicio o incluso mezclar ideas.
- Leer archivos grandes consume contexto rápidamente.
- Cada resultado de comando ejecutado también ocupa espacio.
- Las palabras o frases innecesarias de agradecimiento o saludo consumen contexto; también hablaré de esto en una siguiente entrada de la serie.
Gestionando el contexto en la práctica
Hay tres comandos clave para manejar el contexto de forma proactiva durante una sesión larga:
# Ver cuántos tokens llevas usando en la sesión
/cost
# Si el contexto crece demasiado, "compactar" la conversación:
# el agente resume lo que se ha hecho y libera espacio sin perder el hilo
/compact
# Si vas a cambiar de tema completamente, limpiar el contexto desde cero
/clear
Una buena práctica es ejecutar /compact cada 30-45 minutos en sesiones largas, o cada vez que terminas una tarea grande y empiezas una diferente. Piénsalo como el git commit de tu sesión de trabajo: un punto de consolidación antes de continuar.
CLAUDE.md. Así, si tienes que empezar una sesión nueva más tarde, ese contexto estará disponible automáticamente.
Contexto del repositorio vs. contexto de la sesión
Vale la pena distinguir entre dos tipos de contexto que Claude Code maneja:
- Contexto del repositorio: Los archivos de tu proyecto. El agente los lee bajo demanda, no todos de golpe. Cuando le pides que analice una clase, navega el árbol de archivos y lee lo relevante.
- Contexto de la sesión: La conversación activa y todo lo que se ha intercambiado en ella. Esto sí tiene un límite y se acumula con el tiempo.
Ejemplo práctico: analizar y refactorizar código
Para hacer esto concreto, veamos un ejemplo real. Supón que tienes la siguiente clase Java en tu proyecto:
public class OrderProcessor {
public void process(Order order) {
if (order.getType().equals("ONLINE")) {
System.out.println("Procesando pedido online: " + order.getId());
sendEmail(order.getCustomerEmail(), "Tu pedido está en camino");
updateInventory(order.getItems());
} else if (order.getType().equals("IN_STORE")) {
System.out.println("Procesando pedido en tienda: " + order.getId());
printReceipt(order);
updateInventory(order.getItems());
} else if (order.getType().equals("SUBSCRIPTION")) {
System.out.println("Procesando suscripción: " + order.getId());
scheduleRecurringPayment(order);
sendEmail(order.getCustomerEmail(), "Tu suscripción ha sido activada");
}
}
}
Le dices a Claude Code:
> La clase OrderProcessor tiene un if-else gigante que viola el principio Open/Closed.
Refactorízala usando el patrón Strategy. Crea las clases necesarias y actualiza
los tests existentes para que sigan pasando.El agente va a:
- Leer
OrderProcessor.javay los archivos de test relacionados - Proponerte una estructura: una interfaz
OrderStrategyy tres implementaciones - Pedirte confirmación antes de hacer cambios en disco
- Crear los archivos, modificar los existentes y ejecutar los tests para verificar que todo sigue verde
Modos de operación: interactivo vs. no-interactivo
Además del modo interactivo (el REPL conversacional), Claude Code se puede invocar directamente desde la línea de comandos para tareas específicas, lo que lo hace integrable en scripts y pipelines de CI/CD.
Modo no-interactivo (headless)
Con la flag -p puedes pasarle una tarea directamente sin abrir la sesión interactiva:
claude -p "Revisa todos los archivos Java en src/main y lista cualquier violación al principio DRY"Con --output-format json obtienes la respuesta en formato estructurado, útil para procesar la salida en otro script:
claude -p "Lista los métodos públicos de la clase UserService" --output-format jsonMemoria persistente: CLAUDE.md y Auto Memory
Ahora llegamos a uno de los temas más importantes y, en mi opinión, más subestimados de Claude Code. Recuerda lo que dijimos sobre el contexto: cada sesión empieza desde cero. El agente no recuerda nada de la sesión anterior a menos que uses uno de los dos mecanismos de memoria persistente que tiene disponibles.
El archivo CLAUDE.md
CLAUDE.md es un archivo Markdown que Claude Code lee automáticamente al inicio de cada sesión y carga en el contexto. Es, en esencia, el brief que le darías a un developer nuevo que se incorpora a tu equipo. Aquí pones las cosas que no quieres tener que repetirle al agente cada vez que empiezas a trabajar.
Puedes generar un borrador inicial con:
claude /initEsto hace que el agente analice tu proyecto y genere un CLAUDE.md con lo que encontró. Después lo editas a tu gusto. Un ejemplo para un proyecto Java con Spring Boot:
# CLAUDE.md – Instrucciones para Claude Code
## Descripción del proyecto
API REST de gestión de inventarios con Spring Boot 3.2 y Java 21.
Base de datos: PostgreSQL 15. ORM: Spring Data JPA.
## Convenciones de código
- Seguimos los Google Java Style Guidelines
- Los nombres de paquetes siguen la estructura: com.miempresa.inventario.[modulo]
- Todos los servicios deben tener su interfaz correspondiente
- Los DTOs van en el paquete `.dto` de cada módulo
- No uses @Autowired en campos, usa inyección por constructor
## Comandos útiles
- Compilar: `mvn clean compile`
- Tests: `mvn test`
- Ejecutar en local: `mvn spring-boot:run -Dspring-boot.run.profiles=local`
## Restricciones importantes
- No modifiques los archivos de migración de Flyway existentes
- No hagas commits directos a `main`, siempre crea una ramaJerarquía de archivos CLAUDE.md
Claude Code carga los archivos CLAUDE.md en cascada según su ubicación, de mayor a menor especificidad:
| Ubicación | Alcance | Uso típico |
|---|---|---|
~/.claude/CLAUDE.md |
Global (todos tus proyectos) | Preferencias personales de estilo, idioma preferido, commits |
/raiz-proyecto/CLAUDE.md |
Proyecto | Arquitectura, convenciones del equipo, comandos de build |
/raiz-proyecto/CLAUDE.local.md |
Proyecto (local, ignorado por Git) | Configuraciones tuyas que no deben compartirse con el equipo |
/subdirectorio/CLAUDE.md |
Directorio específico | Reglas específicas para un módulo o submódulo |
Todos los niveles se cargan simultáneamente; las reglas más específicas (de nivel más bajo en la jerarquía) tienen prioridad cuando hay conflicto.
Buenas prácticas para el CLAUDE.md
La documentación oficial y la experiencia práctica de la comunidad coinciden en un punto: menos es más. Un CLAUDE.md de 500 líneas no solo consume una fracción significativa de tu ventana de contexto, sino que con tanto ruido el agente empieza a ignorar instrucciones.
- Apunta a un archivo de entre 30 y 150 líneas como máximo
- Usa listas cortas, no párrafos largos — las instrucciones en bullet point se siguen con más consistencia
- Sé específico y verificable: "usa 2 espacios de indentación" en vez de "formatea el código bien"
- Si tienes reglas extensas para módulos específicos, usa la jerarquía de subdirectorios en vez de meter todo en un solo archivo
Auto Memory
Además del CLAUDE.md que tú escribes, Claude Code tiene desde la versión 2.1.59 un sistema llamado Auto Memory: el agente va tomando notas por su cuenta conforme trabaja contigo, y las guarda en ~/.claude/projects/.
¿Qué guarda? Cosas prácticas: comandos de build que descubrió, patrones de arquitectura que notó, preferencias que demostró a través de correcciones, notas de debugging. No guarda algo en cada sesión, sino cuando decide que la información sería útil en conversaciones futuras.
# Ver qué ha guardado Auto Memory en el proyecto actual
/memory
# Selecciona "auto memory folder" para navegar los archivos
Puedes editar, borrar o agregar notas manualmente a esos archivos, ya que son Markdown plano. Auto Memory está activado por defecto, pero puedes desactivarlo desde el panel /memory.
Permisos: qué puede hacer el agente y qué no
Aquí llegamos al tema que más incomoda a la gente cuando empieza a usar Claude Code: darle acceso a una IA para que ejecute comandos y modifique archivos en tu máquina. La pregunta natural es: ¿cómo controlo lo que puede hacer?
La respuesta corta es que Claude Code tiene un sistema de permisos por capas bastante granular. La respuesta larga empieza por entender cómo funciona el modo por defecto.
Comportamiento por defecto
En el modo estándar, el agente te pide confirmación antes de hacer cualquier cosa potencialmente destructiva: escribir en un archivo, ejecutar un comando de shell, hacer una petición a una URL externa. Cuando te hace esa pregunta, tienes tres opciones:
- Permitir una vez: Aprueba esta acción específica en este momento
- Permitir siempre: Agrega esta acción a la lista de permitidas permanentemente
- Denegar: Bloquea la acción
Modos de permisos
Más allá de aprobar o denegar caso por caso, puedes cambiar el modo de permisos global para toda la sesión. Puedes hacerlo con Shift+Tab durante una sesión interactiva, o configurar el modo por defecto en el archivo de settings.
| Modo | Comportamiento | Cuándo usarlo |
|---|---|---|
| Normal (por defecto) | Pide confirmación antes de acciones que modifican el sistema | Trabajo diario estándar |
| acceptEdits | Aprueba automáticamente ediciones de archivos, sigue pidiendo confirmación para Bash | Cuando confías en las ediciones del agente y quieres más fluidez |
| Plan | Solo lee, no modifica nada. El agente propone cambios pero no los ejecuta | Code reviews, auditorías, cuando quieres ver el plan antes de aprobar |
| bypassPermissions | Sin confirmaciones. Ejecuta todo sin preguntar | Solo en contenedores aislados / CI-CD automatizado |
--dangerously-skip-permissions existe por una razón — el nombre ya te lo dice. Úsala únicamente en entornos completamente aislados como contenedores Docker o VMs efímeras en un pipeline de CI/CD, nunca en tu máquina local con un repositorio de producción.
Reglas de allow/deny en settings.json
Para un control más fino sin recurrir al bypass total, puedes definir reglas de permisos en el archivo de configuración. Esto te permite decirle al agente "estos comandos siempre están permitidos, estos nunca":
// .claude/settings.json (aplica solo a este proyecto)
{
"permissions": {
"allow": [
"Bash(mvn test)",
"Bash(mvn clean compile)",
"Bash(git status)",
"Bash(git diff *)",
"Bash(git commit *)"
],
"deny": [
"Bash(git push *)",
"Bash(rm -rf *)",
"Bash(mvn deploy *)"
]
}
}
Las reglas se evalúan en orden de prioridad: primero deny, luego ask, luego allow. Un deny siempre gana, sin importar qué otras reglas existan. El wildcad * funciona como glob: Bash(git commit *) permite cualquier commit, pero no permite git push.
Para ver las reglas activas en cualquier momento:
/permissionsTres niveles de configuración de permisos
Igual que con los archivos CLAUDE.md, los permisos también tienen una jerarquía de alcance:
~/.claude/settings.json— Reglas globales para todos tus proyectos.claude/settings.json— Reglas del proyecto (se versiona con Git).claude/settings.local.json— Reglas locales del proyecto (ignoradas por Git)
Si eres parte de un equipo, el archivo de proyecto .claude/settings.json es el lugar adecuado para establecer las reglas que todos deben tener, como bloquear push directos a main o impedir que el agente ejecute scripts de deployment desde la máquina local.
Conclusión y siguientes pasos
Cubrimos bastante en este artículo. Claude Code no es solo un asistente de código más rápido, es un cambio en cómo te relacionas con tu propio proyecto: ahora hay un agente que puede navegar esa base de código, planificar tareas, ejecutarlas y aprender de las correcciones que le haces, todo dentro de un marco de control que tú defines.
Los tres conceptos que, en mi experiencia, marcan la diferencia entre usarlo bien y usarlo a medias son precisamente los que vimos hoy:
- El contexto es la memoria de trabajo del agente. Saberlo gestionar con
/compacty/clearevita que las sesiones largas se degraden - La memoria persistente (CLAUDE.md + Auto Memory) es lo que hace que el agente mejore con el tiempo en tu proyecto específico. Sin ella, cada sesión empieza de cero
- Los permisos son tu seguro. Configúralos desde el principio en tu
settings.jsonantes de empezar a usarlo en proyectos serios
En los siguientes artículos de esta serie exploraremos:
- Flujos de trabajo avanzados: code reviews, análisis de arquitectura y generación de documentación
- Integración con proyectos Java/Spring: patrones específicos para Maven y Gradle
- Claude Code en CI/CD: automatizar análisis de calidad en tus pipelines
- MCP (Model Context Protocol): conectar Claude Code a bases de datos, APIs y otras herramientas externas
Espero que este tutorial les sea de utilidad. Si tienen alguna duda, sugerencia, comentario o aclaración, pueden dejarla en la sección de comentarios o enviar un correo a programadorjavablog@gmail.com (pueden agregarme al chat de gmail).
© javatutoriales.com – Serie: Desarrollo Asistido por IA