Claude Code 101: Setup y Fundamentos en PyCharm

Llevas años usando ChatGPT en una pestaña del navegador mientras codeas. Copias código, pegas en tu IDE, ajustas indentación, repites. Es como usar una calculadora para hacer la contabilidad de una empresa... funciona, pero hay mejores herramientas.

El problema fundamental es que ChatGPT no ve tu código, no ejecuta comandos, no lee archivos. Es conversación en el vacío. Y GitHub Copilot, aunque integrado, se limita a autocompletado línea a línea.

Entra Claude Code: un asistente de IA que vive dentro de tu IDE con acceso completo a tu proyecto. Lee archivos, ejecuta comandos, entiende tu codebase. Al final de este post tendrás Claude Code configurado en PyCharm y entenderás cómo usarlo efectivamente.

¿Qué es Claude Code y dónde encaja en el ecosistema?

Antes de meternos en configuración, situemos Claude Code en el panorama actual de herramientas de IA para desarrollo.

Comparativa rápida de herramientas AI

Claude Code pertenece a la categoría de AI CLI tools con acceso total al código.

💡 Mi elección personal: No es "objetivamente mejor". Elegí Claude Code porque se integra en PyCharm (mi IDE principal), usa Claude Sonnet 4.5 (excelente para código en mi experiencia), tiene sistema de skills/agentes potente, y 200K tokens de contexto (~500 páginas).

Ventajas que comparten todas estas CLI tools:

• Acceso total a tu codebase
• Ejecutan comandos, leen/escriben archivos
• Conversación con contexto real del proyecto
• Workflow iterativo (no copy-paste constante)

Ejemplo rápido de lo que esto significa:

Tú: "Explícame cómo funciona la autenticación en este proyecto"

Claude Code:
- Lee src/auth/middleware.py
- Sigue imports a src/auth/jwt.py
- Revisa configuración en settings.py
- Encuentra tests en tests/test_auth.py
- Te da análisis completo del flujo de autenticación

ChatGPT: "No puedo ver tu código, pero típicamente la autenticación funciona así..."

Prerrequisitos

Checklist antes de empezar

⚠️ Claude Pro es obligatorio: La versión gratuita tiene límites muy restrictivos. Claude Code consume muchos tokens, y te quedarás sin acceso constantemente. No es viable en producción.

💰 Análisis de costos: $20/mes puede parecer caro, pero si ya pagas GitHub Copilot ($10/mes) + usas ChatGPT ocasionalmente, Claude Code puede reemplazar ambos. En mi caso, económicamente tiene sentido. Tu kilometraje puede variar.

Instalación y Configuración en PyCharm

El setup es directo. Cuatro pasos y listo.

Paso 0: Instalar Claude Code CLI (Prerequisito)

Antes de instalar el plugin en PyCharm, necesitas instalar el CLI de Claude Code globalmente:

npm install -g @anthropic-ai/claude-code

Esto instala la herramienta de línea de comandos que el plugin de PyCharm utiliza internamente.

Paso 1: Instalar el plugin

1. Abre PyCharm
2. Ve a Settings/Preferences → Plugins
3. Busca "Claude Code" (Asegurate que instalas el de Anthropic)
4. Click en Install
5. Reinicia PyCharm cuando te lo pida

Paso 2: Autenticación

1. Abre la ventana de Claude Code (panel lateral o Ctrl+Shift+C / Cmd+Shift+C)
2. Click en "Sign in"
3. Se abrirá tu navegador → Autoriza la conexión
4. Vuelve a PyCharm → Ya estás autenticado

Paso 3: Verificación

Escribe en el chat:

Hola, ¿puedes confirmar que estás funcionando?

Si Claude responde, estás listo. Si no:

Troubleshooting común:

• Plugin no aparece → Verifica que tienes PyCharm 2024.2+
• Error de autenticación → Confirma que Claude Pro está activo en tu cuenta
• Chat no responde → Revisa tu conexión a internet

Conceptos Fundamentales: Lo que necesitas saber

Antes de empezar a trabajar con Claude Code, hay tres conceptos clave que debes entender.

El contexto de 200K tokens: Tu memoria de trabajo

Claude Code puede mantener ~200,000 tokens de contexto en una conversación. Esto equivale aproximadamente a 500 páginas de código.

En la práctica significa que puedes tener:

• Múltiples archivos abiertos simultáneamente
• Historial completo de la conversación
• Outputs de comandos ejecutados
• Todo esto en la "memoria" de Claude durante la sesión

El problema: Eventualmente se llena. En proyectos grandes, más rápido de lo que esperas.

La solución: Comando /compact (lo veremos pronto).

Piensa en el contexto como la RAM de tu ordenador. Mucha capacidad, pero no infinita. Cuando se llena, Claude te avisará y necesitarás compactar.

CLAUDE.md: Las instrucciones de tu proyecto

Este es posiblemente el archivo más importante para trabajar efectivamente con Claude Code.

¿Qué es? Un archivo en la raíz de tu proyecto con instrucciones permanentes para Claude.

¿Para qué sirve? Claude lo lee automáticamente al inicio de cada conversación. Cualquier información que pongas ahí, Claude la conocerá sin que tengas que repetirla.

¿Qué poner?

• Estructura del proyecto
• Convenciones de código (PEP 8, tipo de docstrings, etc.)
• Comandos comunes (cómo correr tests, cómo hacer build)
• Contexto importante (decisiones de arquitectura, por qué se hizo X así)

Ejemplo básico de CLAUDE.md:

# Mi Proyecto de Análisis de Datos

## Estructura
- `src/` - Código fuente
- `tests/` - Tests con pytest
- `data/` - Datasets (no commiteados)
- `docs/` - Documentación

## Convenciones
- Python 3.12+
- PEP 8 estricto
- Type hints obligatorios en funciones públicas
- Docstrings en español
- Tests para toda función pública

## Comandos importantes
- Tests: `pytest tests/`
- Coverage: `pytest --cov=src tests/`
- Lint: `ruff check .`
- Format: `ruff format .`

## Decisiones técnicas
- Usamos pandas para manipulación de datos
- Preferimos polars para datasets grandes (>1GB)
- API REST con FastAPI (no Flask)

Con esto en CLAUDE.md, nunca tendrás que decirle a Claude "usa type hints" o "los tests van con pytest". Ya lo sabe.

CONTEXT.md: El estado actual (opcional pero útil)

Este es un documento vivo con el estado del proyecto. Especialmente útil en proyectos que evolucionan rápido.

¿Qué poner?

• Últimos cambios importantes
• Decisiones técnicas recientes
• Known issues que Claude debe conocer
• Next steps planificados

Cuándo usarlo:

• Trabajas en múltiples sesiones largas
• El proyecto cambia frecuentemente
• Colaboras con otras personas (humanos o IAs 🙃)

Ejemplo:

# Estado del Proyecto

> Última actualización: 2025-11-15

## Cambios Recientes
- Migrado de requests a httpx para async support
- Añadido rate limiting en API endpoints
- Tests de integración ahora usan pytest-asyncio

## Known Issues
- El script de scraping falla con PDFs >10MB (WIP)
- Tests de performance fallan en Windows (skip temporal)

## Next Steps
- Implementar caché con Redis
- Añadir documentación con Sphinx

No es obligatorio, pero hace la vida más fácil.

Comandos Básicos que Usarás Constantemente

Claude Code tiene varios comandos especiales. Estos son los esenciales:

/init - Inicializar proyecto

Cuándo usarlo: Primera vez que usas Claude Code en un proyecto.

Qué hace: Analiza tu proyecto (estructura, archivos, dependencias) y genera un CLAUDE.md básico automáticamente.

Ejemplo:

Tú: /init

Claude explora el directorio, detecta que es Python con pytest y FastAPI, y genera:

# Proyecto FastAPI

## Stack
- Python 3.12
- FastAPI
- pytest para tests
- ...

Luego editas y personalizas según necesites.

/compact - Compactar conversación

Cuándo usarlo: Cuando Claude te avisa que el contexto está casi lleno, o antes de empezar una tarea grande nueva.

Qué hace: Resume la conversación anterior y libera espacio de contexto. Mantiene lo importante, descarta lo redundante.

Tú: /compact

Claude: "He compactado la conversación. Resumen: implementamos autenticación JWT, creamos 5 endpoints, todos los tests pasan. Contexto liberado: 45%"

Tip: Úsalo proactivamente. No esperes a quedarte sin espacio.

/usage - Ver límites de API

Qué hace: Muestra cuántas requests te quedan según los límites de la API (horarios/diarios/semanales).

Tú: /usage

Claude: "Rate limits: 2% Current Session, 17% Current Week"

No confundir con: El contexto de conversación (ese lo gestiona Claude automáticamente y te avisa cuando se llena).

/help - Explorar comandos

Cuándo usarlo: Para descubrir qué más puedes hacer.

Tú: /help

Claude te muestra todos los comandos disponibles, incluyendo slash commands personalizados (tema del próximo post) y skills instalados (Spoiler Alert: gamechanger).

Comandos avanzados (mención rápida):

• /clear - Borra completamente la conversación actual
• Slash commands personalizados - Los puedes crear tú (siguiente post de la serie)

Tu Primera Interacción: Configurando un Proyecto Desde Cero

Y hasta aquí la teoría. Vamos al barro.

Escenario: Tienes un directorio vacío y quieres crear un proyecto Python bien estructurado.

Paso 1: Inicializar

Tú: /init

Claude analiza el directorio (vacío) y crea un CLAUDE.md básico.

Paso 2: Personalizar instrucciones

Tú: Actualiza el CLAUDE.md con estas convenciones:
- Python 3.12+
- pytest para tests
- ruff para linting y formatting
- type hints obligatorios
- docstrings en español
- commits en inglés

Claude modifica el archivo según tus especificaciones.

Paso 3: Crear estructura

Tú: Crea la estructura de directorios estándar para un proyecto Python:
- src/ para código fuente
- tests/ para tests
- docs/ para documentación
- README.md con descripción básica del proyecto
- requirements.txt vacío
- .gitignore optimizado para Python
- pyproject.toml con configuración de ruff

Claude crea todos los archivos y directorios.

Paso 4: Verificar

Tú: Muéstrame la estructura que creaste

Claude te muestra:

mi-proyecto/
├── src/
├── tests/
├── docs/
├── README.md
├── requirements.txt
├── .gitignore
├── pyproject.toml
└── CLAUDE.md

Lo que acabas de aprender:

• Claude entiende instrucciones en lenguaje natural
• Puede crear múltiples archivos de una sola vez
• Lee y modifica archivos existentes
• No necesitas saber comandos bash específicos (aunque puede ejecutarlos si se lo pides)

Casos de Uso Comunes (Sin Agentes Todavía)

Aquí es donde Claude Code brilla. Ejemplos del día a día:

Caso 1: "Explícame este código"

Tú: Lee src/parser.py y explícame qué hace la función parse_csv_with_schema()

Claude:

1. Lee el archivo
2. Analiza la función y sus dependencias
3. Te da explicación clara: "Esta función toma un CSV y un schema Pydantic, valida cada fila, maneja errores de parsing, y devuelve list de objetos validados o errores detallados"
4. Identifica posibles mejoras: "Podrías añadir streaming para CSVs grandes"

Caso 2: "Encuentra TODOs pendientes"

Tú: Busca todos los TODOs en el proyecto y organízalos por prioridad

Claude usa Grep internamente (tú no lo ves), encuentra 12 TODOs, y te da:

🔴 Alta prioridad (3):
- src/auth.py:45 - TODO: Implementar refresh token rotation
- src/api/users.py:123 - TODO: Añadir rate limiting aquí
- tests/test_payments.py:67 - TODO: Test de timeout pendiente

🟡 Media prioridad (5):
- ...

🟢 Baja prioridad (4):
- ...

Caso 3: "Refactoriza esta función"

Tú: La función calculate_user_metrics() en src/analytics.py es muy larga (150 líneas).
Divídela en funciones más pequeñas manteniendo la misma funcionalidad.

Claude:

1. Lee la función
2. Identifica responsabilidades distintas (cálculo de engagement, análisis de retención, scoring)
3. Crea 4 funciones separadas con responsabilidad única
4. Actualiza tests para cubrir las nuevas funciones
5. Verifica que los tests pasen

Caso 4: "Genera tests"

Tú: Crea tests con pytest para src/utils/validators.py.
Incluye casos normales y edge cases.

Claude:

1. Analiza el módulo validators.py
2. Identifica las 6 funciones públicas
3. Genera tests para cada una:
   • Casos válidos (happy path)
   • Casos inválidos (errores esperados)
   • Edge cases (None, strings vacíos, valores extremos)
4. Guarda en tests/test_validators.py
5. Ejecuta los tests para verificar

Nota importante: En todos estos casos, Claude usa "tools" por debajo (Read para leer archivos, Write para escribir, Grep para buscar, Bash para ejecutar comandos). Pero tú simplemente hablas en lenguaje natural. No necesitas saber qué tool está usando.

Tips y Mejores Prácticas

Después de usar Claude Code en proyectos reales, estos son los tips que más me han ayudado:

Escribe prompts claros y específicos

Cuanto más contexto des, mejores resultados.

Itera en pasos pequeños

No pidas "implementa toda la autenticación". Divide en pasos:

1. "Crea el modelo User con campos básicos"
2. "Añade endpoint de registro con validación"
3. "Implementa generación de JWT"
4. "Añade middleware de autenticación"

Valida cada paso antes de continuar. Claude aprende del feedback que le das.

Usa CLAUDE.md estratégicamente

Documenta convenciones que no quieres repetir:

• "Siempre usa async/await, nunca sync"
• "Los errores van con raise, no con return None"
• "Tests deben ser independientes (no shared state)"

Aprovecha el contexto largo

Puedes tener 10-15 archivos "en mente" simultáneamente:

Tú: Compara cómo manejamos errores en src/api/users.py vs src/api/products.py
y sugiere un enfoque consistente para todo el proyecto

Claude lee ambos archivos, identifica inconsistencias, propone estándar.

Revisa siempre los cambios

Claude es muy bueno, pero no perfecto. Especialmente en:

• Lógica crítica de negocio
• Código de seguridad (autenticación, autorización)
• Queries de base de datos complejas
• Decisiones de arquitectura

Lee el código generado. Entiéndelo. No aceptes ciegamente.

Mantén conversaciones enfocadas

Una conversación = un objetivo claro.

Si estás trabajando en autenticación y de repente quieres implementar un dashboard, considera /clear y empezar conversación nueva. Reduce confusión y mejora resultados.

Limitaciones y Cuándo NO Usar Claude Code

Expectativas realistas. Claude Code es potente, pero no mágico.

Claude Code NO es ideal para:

• Debugging de infraestructura: Problemas de Docker, Kubernetes, networking complejo... mejor usa herramientas especializadas.
• Acceso a bases de datos externas: Claude solo lee archivos locales. No puede conectarse a tu PostgreSQL en producción.
• Refactoring masivo automático: Para renombrar 500 archivos, PyCharm refactoring tools son más seguros.
• Búsqueda simple: Si solo quieres buscar "import requests", Ctrl+F es más rápido.

Cuándo usar otras herramientas:

Y sí, Claude puede alucinar soluciones que suenan perfectas pero no funcionan. No es frecuente, pero pasa. ⚠️ Por eso: revisa siempre el código. ⚠️

La regla de oro: Claude Code es un copiloto, no un piloto automático. Tú sigues siendo el responsable del código que produces.

Conclusión y Próximos Pasos

Has aprendido:

• Qué es Claude Code y cómo se diferencia de Copilot/ChatGPT
• Cómo instalarlo y configurarlo en PyCharm
• Conceptos clave: contexto, CLAUDE.md, CONTEXT.md
• Comandos esenciales: /init, /compact, /usage, /help
• Casos de uso prácticos para tu día a día
• Mejores prácticas y limitaciones realistas

¿Qué hacer ahora?

1. Practica con un proyecto personal - Empieza con algo pequeño. Crea un script, pídele a Claude que lo mejore.
2. Crea tu CLAUDE.md - Documenta tu proyecto. Vale la pena el tiempo inicial.
3. Explora con /help - Descubre qué más puedes hacer.

¿Y ahora qué?

En el próximo post de esta serie, vamos a crear un proyecto completo desde cero usando Claude Code: un wrapper de Python para la API de PokeAPI. Aprenderás a usar skills personalizados, slash commands, y tu primer agente especializado (el Task tool).

Pasaremos de "hola Claude" a "Claude, crea una librería funcional con tests y documentación".

Si los agentes de IA te parecieron interesantes, espera a ver cómo Claude Code los integra directamente en tu workflow de desarrollo.

Recursos

Documentación Oficial

• Claude Code - JetBrains IDEs
• Claude Code Plugin - JetBrains Marketplace

Artículos Relacionados

• Introducción a Agentes de IA: Del Concepto a la Práctica
• Construyendo Sistemas RAG con LangChain

Comunidad

• GitHub Discussions - Claude Code

---

¿Tienes preguntas sobre Claude Code? Contáctame o conectemos en LinkedIn.