Por qué esta guía existe
Llevo meses usando Claude Code para todo. Para escribir esta landing. Para hacer scripts. Para investigar. Para mover proyectos.
La mayoría de tutoriales que encontré tratan a Claude Code como un chatbot con esteroides. No lo es. Es un agente que tiene acceso a tu computadora. Esa diferencia lo cambia todo.
Esta guía va al grano. Cero teoría, cero relleno. Te llevo desde "lo acabo de instalar" hasta "lo uso con proceso de equipo".
1 · Claude Code no es un chatbot
Es un agente con acceso a tu máquina. Hace tres cosas que un chat no hace:
Lee, crea, modifica y borra archivos
Le dices "crea una carpeta landing/ con un Vue básico" y lo hace. No te muestra el código para que tú lo copies. Lo escribe directo en tu disco.
Ejecuta comandos en tu terminal
npm install, git commit, mv, curl. Lo que tú escribirías a mano, él lo lanza. Con permiso o sin permiso (eso lo decides tú al configurar).
Abre el navegador y extrae información
Con MCP de Chrome DevTools entra a una web, toma screenshot, extrae datos. Te lo trae a la conversación.
Entender esto es el 80% del trabajo. Si lo tratas como un chat, vas a frustrarte. Si lo tratas como un junior que sabe pegado y obedece bien, le sacas el jugo.
Dónde lo uso yo
Te ahorro la decisión: VS Code con la terminal integrada. Ahí adentro corro Claude Code directo y tengo el editor al lado para ver lo que está pasando con mis ojos.
Modo pasivo
- Botones que esconden lo que pasa
- Tú interpretas lo que la UI muestra
- Difícil ver el flujo real de comandos
- Limitado a lo que el plugin expone
Cómo lo uso yo
¿Necesitas Warp, iTerm2, o un terminal especial? No. El que viene con tu sistema operativo está bien. La diferencia la hace tu cabeza, no la app.
Instalación y configuración mínima
Después de instalar Claude Code, agrega esto a tu ~/.zshrc:
# ── Claude Code ─────────────────
alias claude='claude --dangerously-skip-permissions'
# ── shortcuts ────────────────────
alias cc='claude'
alias ccr='claude --resume'
Aplica los cambios:
source ~/.zshrc
Cuánto cuesta
Pro / mes
Para empezar y aprender
Max 5x / mes
El sweet spot para la mayoría
Max 20x / mes
Múltiples proyectos paralelos
Si hicieras estas mismas tareas vía API directa, sale fácil $500 USD/mes. La suscripción Max es 5× más barata que pagar por token. Y como Anthropic la subsidia, mientras dure, hay que aprovecharla.
2 · CLAUDE.md, tu memoria entre sesiones
Cada sesión nueva de Claude Code arranca en blanco. No sabe nada de tu proyecto, tus reglas, tus preferencias. Tiene que descubrirlo escaneando archivos.
Esto cuesta tokens. Muchos.
- Escanea 47 archivos al abrir
- Gasta 33.000 tokens solo en leer
- Aún no ha respondido tu primera pregunta
- Repite esto cada sesión nueva
Cómo lo creas
Dentro del proyecto, en una sesión de Claude Code:
❯ /init ⠋ Analizando estructura del proyecto... ✓ Created: CLAUDE.md (86 líneas)
Claude lee tu repo, identifica el stack, las carpetas clave, y escribe la primera versión. La revisas y la ajustas a mano.
Qué debe contener
Solo lo que el agente necesita en CADA sesión. Nada más.
Estructura mínima que funciona:
# Mi Proyecto
## Qué es
[Una frase. La que le dirías a un amigo.]
## Stack
- Frontend: Nuxt 4 + Tailwind v4
- Hosting: Cloudflare Pages
- Lenguaje: TypeScript
## Reglas duras
- Conventional Commits siempre
- Nunca `--no-verify` ni `--force`
- Secretos en macOS Keychain, no en .env
## Estructura
├── app/ ← código fuente
├── content/ ← markdown
├── public/ ← assets
└── nuxt.config.ts
Las 3 reglas de oro del contexto
CLAUDE.md por debajo de 500 líneas
Si crece más, parte el contenido. Información de proyecto en CLAUDE.md, información de tarea en el mensaje de inicio.
1 tarea = 1 sesión
Cuando termines una tarea, escribe /clear y arranca otra. No reutilices la misma sesión para 5 cosas distintas. El contexto se contamina.
Herramientas por proyecto, no globalmente
Solo lo que usas en todo va a --scope user. El resto va a --scope project. Tener 20 MCPs globales infla cada sesión sin que te des cuenta.
3 · MCP, Skills y Subagentes
Tres palabras que confunden. Las pongo en orden cronológico para que las entiendas de una.
MCP: dale superpoderes al agente
MCP es un catálogo de acciones que Claude puede ejecutar. Ejemplo: el MCP de Chrome DevTools le permite abrir pestañas, tomar screenshots, inspeccionar elementos.
Instalarlo es directo:
# Global (solo si lo usas SIEMPRE):
claude mcp add chrome-devtools \
--scope user \
npx @anthropic/chrome-devtools-mcp
# Por proyecto (lo normal):
claude mcp add supabase \
--scope project \
npx supabase-mcp
# Verificar:
/mcp
Skills: la evolución de los MCP
Un Skill es una carpeta con instrucciones y helpers. Solo el header (nombre + descripción de una línea) vive en contexto. El resto se carga cuando lo necesitas.
Modelo viejo
- Todos los endpoints cargados desde el inicio
- Escenarios fijos, no editables
- Difícil de combinar varios
- ~5.000 a 11.000 tokens por MCP
Modelo nuevo
Caso real: para crear esta landing, Claude cargó 2 skills (ui-ux-pro-max + chrome-devtools) que sumaron ~300 tokens en contexto. La misma capacidad como MCP habría gastado 11.000+ tokens. 30× menos.
Dónde conseguir skills
Hay marketplaces públicos con cientos de skills disponibles. Funcionan, pero tienen dos problemas para quien arranca:
- Muchos están escritos para gente técnica que sabe leer markdown crudo y entender qué hace cada bloque.
- No vienen revisados. Cualquiera publica una skill. Y como una skill es código + instrucciones que tu agente va a ejecutar en tu máquina, eso importa.
Lo que estamos haciendo en santa-ia:
Aquí en la biblioteca vamos a ir publicando las skills que yo uso, revisadas, probadas, y con su modo de uso explicado en español para personas que no son ingenieras. No te paso un link al markdown crudo. Te traduzco qué hace, cuándo la usas, qué cosas evita que tengas que pensar.
Vuelve a esta biblioteca seguido. Cada semana va a haber una skill nueva con su guía propia.
Subagentes: trabajo en paralelo
El problema base: una sola sesión de Claude tiene contexto finito. Si le pides 3 cosas grandes seguidas, se le llena la cabeza y empieza a olvidar.
La solución: subagentes. Cada uno tiene su propia ventana de contexto, corren en paralelo, te devuelven el resultado sin contaminar la sesión principal.
- Landing v1: 5 min · 100K tokens
- Landing v2: 5 min · 100K tokens
- Landing v3: 5 min · 100K tokens
- Total: 15 min · 300K en contexto principal
- Sesión desbordada ☠
Dos formas de lanzar subagentes
Al vuelo, en cualquier sesión: le dices a Claude "lanza 3 subagentes en paralelo, cada uno hace una versión distinta del componente X". Y los lanza.
Pre-definidos, en archivos dentro de .claude/agents/. Cada uno con su nombre, modelo y skills asignados. Cuando un agente está documentado, sabes qué hace y lo invocas por nombre.
Si quieres empezar tú: archivo .claude/agents/mi-primer-agente.md con frontmatter name, model, skills. La primera vez son 5 minutos de prueba y error.
4 · Manejo de contexto
El contexto es el "espacio mental" del agente en una sesión. Tiene un techo. Cuando se acerca, el agente empieza a olvidar y a inventar.
Mira tu status line. Tiene que verse algo así:
❯ ~/santa-ia · opus-4 · 1M ctx · 67% ■■■■■■░░
Ese 67% es lo que llevas usado. Tradúcelo así:
El agente está fresco. Respuestas precisas.
Empieza a olvidar detalles. Refresca con un /clear pronto.
Respuestas inconsistentes. Cierra la tarea, abre sesión nueva.
Pérdida contextual severa. Vas a recibir alucinaciones.
Regla operativa
Cuando ves 70%, cierra lo que estás haciendo, ejecuta /clear y abre sesión nueva. No te aferres a una sesión larga por sentimentalismo. El agente no se acuerda de ti igual.
Tres comandos que te salvan la sesión
/clear · arrancar de cero
Borra toda la memoria de la sesión actual. Útil cuando terminaste una tarea y vas a empezar otra distinta. Es el que más uso. Ahorra tokens y evita contaminación entre temas que no tienen relación.
/compact · resumir lo importante
En vez de borrar todo, Claude hace un resumen condensado de la conversación hasta ahora y arranca con ese resumen. Útil cuando llevabas un hilo largo que necesitas mantener pero el contexto se te está llenando. Pierdes detalle, mantienes la dirección.
/rewind · volver atrás
Te deja regresar a un punto anterior de la conversación. Si Claude tomó un camino que no querías o rompió algo, devuelves la sesión al momento antes del error sin perder lo bueno que pasó antes. Como Ctrl+Z pero para tu chat completo.
5 · Sacar tu código al mundo
Hay dos perfiles claros acá. No uso las etiquetas "vibe coder vs developer pro" porque me suenan despectivas. Lo digo más directo:
- Tu app solo corre en
localhost:3000 - Cuando cierras la terminal, se cae
- No la puedes compartir con nadie
- Si pierdes el disco, perdiste el proyecto
Cómo publico yo: Cloudflare Pages
Esta landing que estás leyendo vive en Cloudflare Pages. Free tier, deploy automático con cada push a la rama, dominio propio en minutos. Para sitios estáticos (Nuxt SSG, Vue puro, Astro) es lo más rápido y gratis que conozco.
- Login en dash.cloudflare.com → Workers & Pages
- Create application → Pages → Connect to Git
- Selecciona el repo (GitHub o GitLab)
- Build command: npm run generate
- Output directory: .output/public
- Deploy
En 60 segundos tu URL .pages.dev está viva.
Otras opciones según el caso:
- Vercel → más rápido si tu stack es Next.js. Misma idea, otro proveedor.
- Railway / Render → cuando tienes backend Python con base de datos. Vercel no sirve para FastAPI.
- Self-hosted (Docker en VPS) → cuando necesitas control total.
Git: el cinturón de seguridad
Si vas a publicar algo, siempre con Git. Te salva de los borrones a mitad de noche, te deja volver atrás, te deja experimentar sin miedo.
Lo mínimo:
git init
git add app/ content/ public/
git commit -m "feat: primera versión de la landing"
# Para experimentar sin romper:
git checkout -b feature/diseno-v2
Git Worktree: dos Claudes a la vez
Mi truco favorito. Te deja tener dos versiones del mismo proyecto en carpetas físicas distintas:
git worktree add ./worktrees/v2 feature/landing-v2
git worktree add ./worktrees/v3 feature/landing-v3
Ahora abres dos terminales:
~/worktrees/v2 ❯ claude
~/worktrees/v3 ❯ claude
Dos Claudes trabajando en paralelo, en versiones distintas, sin tropezarse. Cuando te decides por una, mergeas y borras la otra.
Secretos: nunca en código
Tres reglas duras que aplico en todo proyecto:
Nada de API keys en .env del repo
Si commiteas un .env aunque sea una vez, la llave queda en el historial de git para siempre. Aunque la borres después, sigue ahí. Mejor: ni los archivos .env viven en mi máquina local con valores reales.
Local: todo en el gestor de claves del sistema
- macOS: Keychain (mi caso). Convención de naming:
[servicio]-[contexto]. Ej:gitlab-terracomerce,santaia:gemini-key,santaia:elevenlabs-key. - Windows: Credential Manager con la misma idea (
cmdkeyen CLI). - Linux:
secret-tool(libsecret) o KWallet.
El código consulta el gestor en runtime. La llave nunca toca el disco como texto plano.
Producción: variables del proveedor
GitHub Actions Secrets, Cloudflare Pages env vars, Railway secrets. Las inyecta el CI/CD. Tu máquina personal jamás conoce las llaves de producción.
Mi regla personal: llaves de producción en mi máquina local no es pregunta de "si" se filtran. Es pregunta de "cuándo". Por eso vivo todo en macOS Keychain.
6 · El proceso vence al modelo
Esto es lo que más cuesta entender. Y es lo que más rinde cuando lo agarras.
El DORA Report 2025 dijo algo claro: los equipos fuertes con IA se hacen más fuertes. Los débiles descubren más problemas. El ROI no viene de la herramienta. Viene del proceso.
Caos rápido sigue siendo caos.
El pipeline mínimo
Planificación
El agente propone cómo atacar la tarea. No escribe código todavía.
Revisión del plan
Tú lees el plan, lo ajustas, agregas restricciones. Acá decides si vale la pena.
Descomposición
El plan se parte en tareas ejecutables. Cada una con su entregable claro.
Implementación vía subagentes
Las tareas corren aisladas y paralelizadas. Cada subagente entrega lo suyo.
Code review
Revisión explícita antes de merge. Otro pase del agente o tú a mano.
El mismo modelo, dos resultados
Petición: "Constrúyeme una app"
Resultado:
- 300K tokens después...
- Contexto desbordado ✗
- Código no compila ✗
- Tests no existen ✗
- A empezar de cero ✗
Petición: plan → revisar → partir → ejecutar → review
Resultado:
- 9 tareas completadas
- 9% de contexto usado
- Tests pasando ✓
- Commit listo ✓
Misma versión de Claude. Mismo prompt original. La diferencia fue el proceso.
7 · El kit que yo sí uso
Cada herramienta de esta lista se ganó su puesto porque la investigué, la probé, y me ahorra tiempo real cada semana. No son las "top 10" recopiladas de internet. Son las que yo abro casi todos los días en mi Claude Code.
humanizer (skill propio)
Detecta 29 patrones de prosa generada por IA (em-dashes, "desbloquea", "potencia", construcciones tipo "no solo X sino también Y"). Lo corre antes de publicar cualquier copy. Sin esto, todo lo que escribo suena a marketing genérico. Con esto, suena a mí.
ui-ux-pro-max (skill)
67 estilos visuales, 161 paletas curadas, 57 pares tipográficos. Cuando le digo "hazme una landing bonita", esto se encarga del criterio. Esta página está construida con esa skill guiando cada decisión.
chrome-devtools MCP
Automatización del browser. Toma screenshots, llena formularios, ejecuta JavaScript en la página, lee el DOM. Lo uso para validar que lo que Claude genera se ve bien antes de declarar la tarea cerrada.
start-project (skill propio)
Mi punto de partida en cada proyecto nuevo. Lee mi knowledge base, crea estructura estándar (Python + SQLite + Vue 3 + Tailwind), registra el proyecto en JARVIS. 3 minutos en vez de 30.
context-engineering + sequential-thinking
Dos skills para problemas duros. La primera ayuda a estructurar contextos complejos. La segunda obliga al agente a razonar paso a paso antes de actuar. Cuando algo se atraganta, las invoco.
code-review (skill)
Antes de cerrar una tarea grande, le pido que se revise él mismo. Encuentra bugs, lógica frágil, problemas de seguridad. Un segundo par de ojos que no cobra.
/commit (mi slash command)
Mi propio comando para commits. Conventional Commits, sin --no-verify, sin --force, sin atribución de IA en el mensaje. Aplica reglas duras automáticamente. Después de probarlo, no quieres commits sin él.
8 · Tu ruta de 0 a avanzado
Esto no se aprende todo en un día. La progresión sana se ve así:
Cierre
Si llegaste hasta acá, ya sabes más que el 90% de gente que dice usar Claude Code. Lo que sigue no es leer otra guía. Es abrir tu próximo proyecto y aplicar una sola cosa de las que viste.
Mi recomendación: empieza por CLAUDE.md. Es lo de menor esfuerzo y mayor retorno. Tres minutos de inversión y todas tus sesiones siguientes te lo agradecen.
¿Lo aplicaste y te funcionó? ¿Te trabaste en algo? Cuéntame en @santaia.lab. Las dudas reales son el material del próximo artículo.