Claude Code en VSCode: Guía Completa de Configuración y Uso

Disclaimer honesto: Yo uso PyCharm. Es mi IDE principal para Python. Pero sé que muchos de vosotros vivís en VSCode, y no voy a juzgar vuestras decisiones de vida. 😄

Este post es la adaptación del setup de Claude Code en PyCharm para desarrolladores de VSCode. Los conceptos son idénticos (mismo CLI, misma IA, mismo flujo de trabajo), solo cambia la integración con el editor.

¿Por qué escribo esto si uso PyCharm? Porque Claude Code es lo suficientemente bueno como para que no me importe en qué editor lo uses. Y porque tengo amigos que usan VSCode y se merecen también un tutorial decente. VSCode también merece existir (supongo). 🤷

Así que... llevas meses saltando entre VSCode y ChatGPT. Copias código, ajustas indentación, pierdes contexto, repites. El problema es que ChatGPT no ve tu codebase. No ejecuta tests, no refactoriza archivos, no entiende tu arquitectura.

Claude Code vive dentro de VSCode con acceso completo a tu proyecto. Lee archivos, ejecuta comandos, entiende dependencias. Al final de este post tendrás Claude Code configurado en VSCode y trabajando como tu copiloto más inteligente.

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

Antes del setup técnico, situemos Claude Code en el panorama de herramientas AI 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.

💡 Nota sobre herramientas: No hay "la mejor herramienta". Yo personalmente uso PyCharm (y Claude Code integrado ahí), pero Claude Code funciona igual de bien en VSCode. La elección de IDE es como la elección de editor de texto en los 90s: altamente personal y fuente de guerras santas innecesarias. Elige el que te haga feliz y enfócate en escribir buen código.

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ú: "Analiza cómo funciona el routing en este proyecto Next.js"

Claude Code:
- Lee app/[locale]/layout.tsx
- Sigue imports a i18n/routing.ts
- Revisa middleware.ts para locale detection
- Encuentra ejemplos en app/[locale]/blog/page.tsx
- Te da análisis completo del sistema de routing

ChatGPT: "No puedo ver tu código, pero Next.js App Router 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 para trabajo serio.

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

Instalación y Configuración en VSCode

El setup es directo. Tres pasos principales y listo.

Paso 1: Instalar Claude Code CLI

Primero necesitas el CLI global de Claude Code:

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

Esto instala la herramienta de línea de comandos que la extensión de VSCode utiliza internamente.

Verificación:

claude-code --version

Deberías ver algo como: @anthropic-ai/claude-code v1.x.x

Paso 2: Instalar la extensión de VSCode

1. Abre VSCode
2. Presiona Ctrl+Shift+X (Windows/Linux) o Cmd+Shift+X (Mac) para abrir Extensions
3. Busca "Claude Code" en el marketplace
4. Asegúrate de instalar la extensión oficial de Anthropic
5. Click en Install
6. VSCode puede solicitar reiniciar → Acepta

Alternativa por línea de comandos:

code --install-extension anthropic.claude-code

Paso 3: Autenticación

1. Abre la Command Palette: Ctrl+Shift+P (Windows/Linux) o Cmd+Shift+P (Mac)
2. Escribe: Claude Code: Sign In
3. Se abrirá tu navegador → Autoriza la conexión con tu cuenta Claude Pro
4. Vuelve a VSCode → Ya estás autenticado

Atajos de teclado útiles:

Paso 4: Verificación

Abre el panel de Claude Code (Ctrl+Shift+C / Cmd+Shift+C) y escribe:

Hola, ¿puedes confirmar que estás funcionando?

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

Troubleshooting común:

• Extensión no aparece → Verifica que tienes VSCode 1.80+. Actualiza si es necesario.
• Error de autenticación → Confirma que Claude Pro está activo en tu cuenta. Revisa en claude.ai.
• Chat no responde → Revisa tu conexión a internet. Verifica que el CLI está instalado (claude-code --version).
• "Command not found" → El CLI no está en PATH. Reinstala con npm install -g @anthropic-ai/claude-code.

Configuración adicional (opcional)

Settings.json personalización:

Abre Settings (Ctrl+, / Cmd+,) y busca "Claude Code" para configurar:

• Tema del chat: Light/Dark/Auto
• Shortcut personalizado: Reasigna Ctrl+Shift+C si lo usas para otra extensión
• Auto-save: Configurar si Claude debe guardar archivos automáticamente

Para WSL (Windows Subsystem for Linux):

Claude Code funciona en WSL sin configuración adicional. Solo asegúrate de instalar el CLI dentro del entorno WSL:

# Dentro de WSL
npm install -g @anthropic-ai/claude-code

Para Remote Development (SSH, Containers):

Claude Code soporta Remote Development de VSCode. La extensión debe estar instalada tanto en local como en el entorno remoto.

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 (Prettier, ESLint rules, etc.)
• Comandos comunes (cómo correr dev server, tests, build)
• Contexto importante (decisiones de arquitectura, por qué se hizo X así)

Ejemplo básico de CLAUDE.md:

# Mi Proyecto Next.js

## Estructura
- `app/` - Next.js 14 App Router
- `components/` - React components reutilizables
- `lib/` - Utilidades y helpers
- `public/` - Assets estáticos

## Stack Tecnológico
- Next.js 14 (App Router)
- TypeScript
- Tailwind CSS
- Prisma ORM
- PostgreSQL

## Convenciones
- TypeScript estricto (strict mode)
- ESLint + Prettier configurados
- Componentes funcionales con hooks
- Naming: PascalCase para componentes, camelCase para funciones
- Imports: Absolute paths con @/ alias

## Comandos importantes
- Dev server: `npm run dev`
- Build: `npm run build`
- Tests: `npm test`
- Lint: `npm run lint`
- Type check: `npm run type-check`

## Decisiones técnicas
- Server Components por defecto, Client Components solo cuando necesario
- Fetch data en Server Components, no en useEffect
- Prisma para queries, no raw SQL
- Tailwind para estilos, no CSS modules

Con esto en CLAUDE.md, nunca tendrás que decirle a Claude "usa TypeScript" o "los tests van con Vitest". 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-20

## Cambios Recientes
- Migrado de Pages Router a App Router (Next.js 14)
- Implementado autenticación con NextAuth.js
- Base de datos: Supabase (PostgreSQL)

## Known Issues
- El componente ImageUpload falla con archivos >5MB (WIP)
- Tests E2E con Playwright pendientes de configurar

## Next Steps
- Implementar dashboard de analytics
- Optimizar imágenes con next/image
- Añadir i18n con next-intl

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 un proyecto Next.js con TypeScript y Tailwind, y genera:

# Proyecto Next.js

## Stack
- Next.js 14
- TypeScript
- Tailwind CSS
- ...

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 sistema de autenticación, creamos 7 endpoints API, 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 para otro post) y skills instalados.

Comandos avanzados (mención rápida):

• /clear - Borra completamente la conversación actual
• Slash commands personalizados - Los puedes crear tú
• Skills - Sistema de agentes especializados (siguiente nivel)

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 Next.js bien estructurado.

Paso 1: Crear directorio y abrir en VSCode

mkdir mi-app-nextjs
cd mi-app-nextjs
code .

Paso 2: Inicializar con Claude Code

Abre el panel de Claude Code (Ctrl+Shift+C / Cmd+Shift+C):

Tú: /init

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

Paso 3: Personalizar instrucciones

Tú: Actualiza el CLAUDE.md con estas convenciones:
- Next.js 14 con App Router
- TypeScript estricto
- Tailwind CSS para estilos
- ESLint + Prettier configurados
- Componentes funcionales con hooks
- Imports absolutos con @/ alias
- Commits en inglés

Claude modifica el archivo según tus especificaciones.

Paso 4: Crear estructura del proyecto

Tú: Inicializa un proyecto Next.js con:
- App Router estructura
- TypeScript configurado
- Tailwind CSS instalado
- ESLint y Prettier configurados
- Estructura de carpetas: app/, components/, lib/, public/
- README.md con descripción del proyecto
- .gitignore optimizado para Next.js

Claude ejecuta comandos y crea la estructura:

mi-app-nextjs/
├── app/
│   ├── layout.tsx
│   ├── page.tsx
│   └── globals.css
├── components/
├── lib/
├── public/
├── .eslintrc.json
├── .prettierrc
├── next.config.js
├── tailwind.config.ts
├── tsconfig.json
├── package.json
├── README.md
├── .gitignore
└── CLAUDE.md

Paso 5: Verificar que todo funciona

Tú: Instala las dependencias y arranca el servidor de desarrollo

Claude ejecuta:

npm install
npm run dev

Y te confirma: "Servidor corriendo en http://localhost:3000"

Lo que acabas de aprender:

• Claude entiende instrucciones en lenguaje natural
• Puede ejecutar comandos npm/yarn automáticamente
• Crea múltiples archivos de una sola vez
• Lee y modifica archivos existentes
• Verifica que todo funciona correctamente

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 componente"

Tú: Lee components/Header.tsx y explícame cómo funciona el sistema de navegación

Claude:

1. Lee el archivo Header.tsx
2. Analiza el componente y sus props
3. Sigue imports a lib/navigation.ts
4. Te da explicación clara: "El Header usa un array de rutas definido en navigation.ts, mapea cada ruta a un Link de Next.js, aplica estilos activos con pathname comparison, y maneja mobile menu con estado local"
5. Identifica posibles mejoras: "Podrías mover el mobile menu state a un custom hook"

Caso 2: "Encuentra TODOs pendientes"

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

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

📁 app/dashboard/page.tsx (3):
- Line 45: TODO: Añadir loading skeleton
- Line 78: TODO: Implementar error boundary
- Line 123: TODO: Optimizar query con pagination

📁 components/UserProfile.tsx (2):
- Line 34: TODO: Añadir avatar placeholder
- Line 89: TODO: Validar email format

📁 lib/api.ts (4):
- Line 12: TODO: Implementar retry logic
- Line 56: TODO: Añadir rate limiting
- Line 89: TODO: Cache responses
- Line 134: TODO: Error handling mejorado

Caso 3: "Refactoriza este componente"

Tú: El componente DashboardStats.tsx es muy largo (200 líneas).
Divídelo en componentes más pequeños y reutilizables.

Claude:

1. Lee DashboardStats.tsx
2. Identifica secciones separables (StatCard, ChartWidget, UserList)
3. Crea 3 componentes nuevos en components/dashboard/
4. Actualiza DashboardStats.tsx para usar los nuevos componentes
5. Verifica que los tipos TypeScript son correctos
6. Sugiere: "Los nuevos componentes son reutilizables, puedes usarlos en otras páginas del dashboard"

Caso 4: "Genera tests"

Tú: Crea tests con Vitest para lib/utils.ts.
Incluye casos normales y edge cases.

Claude:

1. Analiza el módulo utils.ts
2. Identifica las 5 funciones públicas
3. Genera tests para cada una:
   • Casos válidos (happy path)
   • Casos inválidos (errores esperados)
   • Edge cases (null, undefined, arrays vacíos)
4. Guarda en lib/tests/utils.test.ts
5. Ejecuta los tests para verificar: npm test

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 (incluido este mismo blog), 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 todo el sistema de autenticación". Divide en pasos:

1. "Instala y configura NextAuth.js con GitHub provider"
2. "Crea la ruta API /api/auth/[...nextauth]"
3. "Añade SessionProvider en layout.tsx"
4. "Crea componente LoginButton con useSession"

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 Server Components por defecto, Client Components solo cuando necesario"
• "Prisma para queries, no raw SQL"
• "Tailwind para estilos, no inline styles ni CSS modules"
• "Tests con Vitest, no Jest"

Aprovecha el contexto largo

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

Tú: Compara cómo manejamos errores en app/api/users/route.ts vs app/api/products/route.ts
y sugiere un enfoque consistente para todas las API routes

Claude lee ambos archivos, identifica inconsistencias, propone estándar, y puede aplicarlo a otros archivos.

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)
• Configuración de base de datos
• 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 sistema de comentarios, considera /clear y empezar conversación nueva. Reduce confusión y mejora resultados.

Integra con el terminal de VSCode

Claude Code puede ejecutar comandos, pero también puedes usar el terminal integrado de VSCode (`Ctrl+``) para:

• Monitorear el dev server
• Ver logs en tiempo real
• Ejecutar comandos manuales en paralelo

Workflow recomendado:

• Terminal 1: npm run dev (servidor siempre corriendo)
• Terminal 2: Comandos ad-hoc (git status, npm test)
• Claude Code: Desarrollo y refactoring

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 interactivo: Para debugging paso a paso, VSCode debugger con breakpoints es más efectivo.
• 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 símbolos en 100 archivos, VSCode refactoring tools (F2) son más seguros.
• Búsqueda simple: Si solo quieres buscar "import React", Ctrl+Shift+F es más rápido.
• Configuración de entornos complejos: Docker, Kubernetes, infraestructura... mejor usa herramientas especializadas.

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. ⚠️ Especialmente en TypeScript, a veces sugiere tipos que no existen o props que no están definidos.

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 VSCode (CLI + extensión)
• Conceptos clave: contexto de 200K tokens, 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 componente, 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é?

Este post forma parte de una serie sobre Claude Code. Si vienes desde PyCharm, el workflow es prácticamente idéntico (mismo CLI, mismos conceptos). Si quieres profundizar en personalización avanzada, skills y slash commands, revisa el próximo post de la serie.

También tengo un caso práctico real: construí una Pokédex en producción en 1 hora usando Claude Code. Es un ejemplo completo de cómo usar Claude Code en un proyecto Next.js real.

Si los agentes de IA te parecieron interesantes, Claude Code los integra directamente en tu workflow de desarrollo con el sistema de skills.

Recursos

Documentación Oficial

• Claude Code - Official Documentation
• Claude Code CLI - NPM Package
• Claude Code Extension - VSCode Marketplace

Artículos Relacionados

• Claude Code 101: Setup y Fundamentos en PyCharm - Mismo contenido pero para PyCharm
• Pokédex en Producción en 1 Hora con Claude Code - Caso práctico completo
• Claude Code: Personalización Avanzada del Workspace - Skills y slash commands
• Introducción a Agentes de IA: Del Concepto a la Práctica

Comunidad

• GitHub Discussions - Claude Code
• Discord - Anthropic Community

---

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