Claude Code: la guía completa para principiantes

Llevo varios meses usando Claude Code a diario. Servidores MCP, artículos en tres sitios, scripts de Python, flujos de trabajo de contenidos que van desde la investigación hasta la subida a WordPress. Nada ha cambiado tanto mi forma de trabajar desde que empecé con MS Excel hace 20 años. Lo que hay en el artículo de hoy es la mayor parte de lo que sé que sería útil para empezar tras todo ese uso diario: lo que funciona, lo que (¿nosotros?) hicimos espectacularmente mal y algunas cosas que ojalá alguien me hubiera dicho el primer día.

---

No es un chatbot

Yo le llamaba así la primera semana, de hecho, y estaba equivocado. Claude Code no es un chatbot que resulta ver tus archivos. Lee tu codebase por su cuenta, edita en varios archivos, ejecuta los comandos de terminal que necesita, gestiona git y habla con herramientas externas a través de MCP. Todo sin que nadie le enseñe cómo, y todavía meneo la cabeza a veces. Me costó una semana entera dejar de abrirle los archivos: los viejos hábitos son duros de morir, al parecer. Apúntalo a un problema y arranca: qué archivos abrir, qué hay que cambiar, qué comandos ejecutar, todo eso lo deduce solo. Sin canguelo, y eso me costó acostumbrarme.

Parece que distingo delgado, lo sé, pero la diferencia te golpea la primera vez que lo ves trabajar. La codificación normal con IA es un asunto de copiar y pegar: pegas código en la ventana del chat, recibes una sugerencia, la pegas en tu editor, compruebas si se rompe, vuelves a intentarlo. Dejé eso hace meses: copiar y pegar entre una ventana de chat y tu editor siempre significa que algo se pierde en la traducción.

Claude Code se salta todo eso. El martes pasado le pedí que arreglara los tests que fallaban en mi módulo de auth y leyó la estructura del proyecto, abrió seis archivos, hizo ediciones en todos, ejecutó la suite de tests para comprobar su propio trabajo y arregló los dos tests que inicialmente había hecho mal. Tiene acceso a disco, ya ves; así que arranca. Y hoy en día (Opus 4.6 / Sonnet 4.6), los errores son bastante raros. La pérdida de contexto, sí, sigue siendo un problema en hilos largos y comprimidos, pero vivimos con ello.

Programar una app simple de html/css lleva unos cuatro minutos, de principio a fin. Entiendo ahora por qué el equipo de Anthropic, según se dice, recortó la incorporación de nuevos devs de semanas a días: una vez que lo has visto trabajar un problema de punta a punta, volver a copiar y pegar resulta doloroso. ¡Pero es tan intuitivo!

¿Ya usas Claude Desktop para trabajo que no es de código? Misma inteligencia debajo, pero la interfaz es muy distinta. Sensiblemente más fino cuando hay código de por medio, eso sí. Puedes programar perfectamente en Claude Desktop, aunque el enfoque mental debe ser distinto. Yo ya no lo hago, pero así fue como empecé. Aprendes mucho sobre las limitaciones de hacer que la IA programe correctamente de esa manera, así que no lamento la experiencia en absoluto.

Y de todos modos; Claude Code en la GUI de Desktop está muy logrado y es un buen escalón entre terminal y escritorio. Merece una mirada si la terminal te parece un paso demasiado lejos ahora mismo.

Entonces, ¿qué es?

Es el agente de codificación de Anthropic, y se ejecuta en tu terminal, VS Code, JetBrains, la app de escritorio de Claude, a través de la web, o incluso Slack si es lo tuyo (no recomiendo Slack). Yo vivo sobre todo en la terminal, pero planifico con Desktop. Creo el repo, escribo las specs, diseño la API, tomo algunas decisiones técnicas sobre la arquitectura, traigo Gemini MCP y Context7 para una opinión y datos recientes de librerías. Cuando estamos listos creo el repo con Desktop Commander en Claude Desktop, lo ordeno bien con un CHANGELOG.md y demás, guardo los archivos spec en md y luego le pido a Claude que ejecute un plan de ejecución.

Vídeo 3

Luego migro a Claude Code con el repo flamante listo para funcionar. Cambiar desde Desktop es completamente indoloro. Lectura de archivos, edición, bash, grep, búsqueda glob: elige las herramientas que necesita y las encadena sin esperar instrucciones. Dile "arregla los tests que fallan en auth" y encontrará los archivos de test, leerá el código fuente, averiguará qué está roto, lo arreglará y volverá a ejecutar la suite. Ejecutará toda la cadena, de principio a fin, sin canguelo. Cada llamada a herramienta recibe un aviso de permiso por defecto. Lo cual se hace viejo rápido: quiero decir rapidísimo, como quince avisos en dos minutos; pero hay reglas de auto-aprobación que puedes ajustar una vez que lo has visto trabajar lo suficiente como para confiar en el patrón. Yo sigo aprobando todo lo que toca git, tal es mi fe inquebrantable en mis herramientas.

Conviene decir, eso sí, que "lectura de archivos, edición, bash, grep, búsqueda glob" etc. todo es posible con Desktop Commander en Claude Desktop. Ninguno de los dos enfoques es equivocado, honestamente: elige el que te convenga. Salvo que planees una sesión nocturna de Claude para escribir tu próxima idea de mil millones de dólares. Ahí se pone técnico.

Obviamente; necesitarás una clave API de Anthropic o una suscripción a Claude para ejecutarlo. El uso de tokens varía muchísimo: una pregunta rápida puede consumir 10K tokens, un refactoring mayor puede quemar 500K. He escrito aparte sobre recortar tu factura de Claude Code con Converly LM si el coste te preocupa, y francamente probablemente debería.

converly-lm: permite a Claude Code decidir cuándo las tareas pueden delegarse de forma segura a tu red local (o a Ollama o LM Studio en la estación de trabajo). Es muy chulo. Estrellas bienvenidas.

Para empezar: la instalación

Toma un café: esto tarda de verdad unos dos minutos, y en esa estimación incluyo el rato que perdí trasteando con el tema de mi terminal. Necesitarás o bien una suscripción a Claude Pro (20 $/mes) o bien una clave API de Anthropic: no te deja pasar de la pantalla de inicio sin una de las dos.

Paso 1: Instalar Claude Code

macOS y Linux con una sola línea:

curl -fsSL https://claude.ai/install.sh | sh

Windows vía winget:

winget install Anthropic.Claude

Si ya tienes Node.js, npm funciona en cualquier plataforma también:

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

Paso 2: Lanzarlo y conectar tu cuenta

Abre una terminal en el directorio del proyecto en el que quieras trabajar y teclea:

claude

La primera vez te pide elegir un tema de color (modo oscuro, obviamente), iniciar sesión con tu cuenta de Anthropic y confiar en el directorio en el que estés. La configuración tarda 30 segundos, como mucho.

Paso 3: Verificar que funciona

Esta es la parte que me hizo jurar en voz alta la primera vez. Claude Code escanea el directorio, deduce lo que tienes y de repente estás hablando con algo que ya conoce tu proyecto. No se parece en nada a una ventana de chat en blanco: más bien como alguien que ya le ha echado un vistazo a tus archivos fuente y ha decidido, con acierto o no, cómo encaja tu proyecto.

Prueba una comprobación rápida:

claude -p "What files are in this directory and what do they do?"

Si obtienes una respuesta sensata que lista tus archivos de proyecto, estás listo. ¿Errores de autenticación? Comprueba el estado de tu suscripción en claude.ai/settings: normalmente es solo una sesión caducada.

Consejo para la primera sesión: haz preguntas antes de editar

Esto es lo primero que habría hecho distinto: el primer día apunté Claude Code a mi repo content-machine y le pedí de inmediato que reescribiera un módulo de subida a WordPress. Hizo suposiciones sobre la estructura de directorios, se equivocó con la ruta de la plantilla y pasé cuarenta minutos deshaciendo el desastre. Diez minutos de preguntas sobre el codebase habrían sacado a la luz esa suposición errónea antes de que nada se reescribiera, pero por supuesto yo estaba demasiado impaciente para eso.

Boris Cherny, de Anthropic, machaca este punto en sus charlas: no empieces editando código, haz preguntas primero. "¿Qué hace este middleware?" o "Guíame por el enrutado". En unos treinta segundos sabrás si de verdad entiende tu proyecto o si está a punto de reescribir algo con confianza basándose en una suposición errónea. Cuarenta minutos que habría evitado con una conversación de dos minutos, y he cometido el mismo error probablemente una docena de veces desde entonces.

Un prompt común que uso es "familiarízate con este codebase y espera una tarea".

Primera sesión con un proyecto nuevo: Claude Code escanea el directorio, carga tu CLAUDE.md y responde preguntas sobre el codebase antes de que toques una sola línea de código.

Nadie me habló de claude init y perdí una semana escribiendo mi CLAUDE.md desde cero. Lo ejecutas y te pregunta por tu proyecto, escanea el codebase y genera un CLAUDE.md de inicio (más sobre esto en un momento). No esencial, pero mejor que quedarse mirando un archivo en blanco intentando recordar cuáles son tus convenciones.

Tus primeros cinco minutos

Se lo enseñé a un colega la semana pasada y sus palabras exactas fueron "eso no puede ser real". Elige cualquier carpeta vacía y ejecuta esto:

claude -p "Create a colour palette generator as a single HTML file
  with inline CSS and JS. Dark UI. Save to colour-palette.html"

Esa bandera -p significa "modo print": lee el prompt, hace el trabajo y se cierra. Sin sesión interactiva, sin ida y vuelta: solo hace la cosa y se cierra. Lo uso probablemente diez veces al día para tareas rápidas como esta.

Un prompt, un archivo. Claude Code construye la app entera —HTML, CSS, JavaScript— y la guarda en disco.

Unos treinta segundos después hay un archivo HTML funcionando en el directorio, lo que todavía me descoloca cada vez. Ábrelo en tu navegador:

La app terminada: interfaz oscura, cinco muestras de color armoniosas con códigos hex y RGB, clic para copiar. Construida en menos de un minuto sin escribir una línea de código.

Tema oscuro, armonía de color HSL, códigos hex con clic para copiar, layout responsive: 369 líneas de código funcionando de las que no escribí ni un solo carácter. Sin scaffolding, sin npm install, sin config de webpack, nada. Un prompt y una pestaña del navegador, y todavía me parece un poco de locura.

El clic se produjo en mí más o menos la tercera o cuarta vez que hice esto. Dejé de pensarlo como una herramienta de chat por entonces. Describe lo que quieres y aparece un archivo funcionando en disco. Parece una distinción menor —"generar código" frente a "construir la cosa"— pero recableó cómo pienso qué merece la pena automatizar.

Pruébalo con lo que te apetezca: un previsualizador de markdown, un dashboard simple, un playground de animaciones CSS. Cualquier cosa autocontenida en un único archivo HTML funciona estupendamente como primer test, y tendrás algo corriendo en tu navegador antes de haberte hecho el té.

Las funciones de las que dependo

No he mapeado ni de lejos cada función: dudo que nadie lo haya hecho, incluido el equipo que lo construyó, pero estas son las que suponen en torno al 90 % del valor que saco a esta cosa a diario.

CLAUDE.md: la memoria de tu proyecto

Un archivo CLAUDE.md en la raíz de tu proyecto le da a Claude contexto persistente que sobrevive entre sesiones: tus convenciones, la estructura del proyecto, las reglas de despliegue, las herramientas preferidas. Y pasé tres semanas —tres semanas enteras, como un disco rayado— dando el mismo speech cada sesión: "este repo gestiona tres sitios, las credenciales están en .secrets/wp-sites.json, usa siempre inglés británico". Lo mismo, cada mañana, primer mensaje. El clic se produjo un viernes por la mañana cuando por fin escribí un CLAUDE.md que cubría todo, quizá veinte minutos de trabajo real, y nunca más di ese speech. No ideal, haber perdido todo ese tiempo, pero al menos el arreglo fue trivial.

Cuatro niveles si te importa la jerarquía: global en tu directorio home, por proyecto, por subdirectorio y empresarial; aunque yo solo me molesto con los dos primeros. El de por proyecto hace la mayor parte del trabajo en mi configuración, y el global son solo un puñado de cosas que se aplican en todas partes: inglés británico, nunca auto-commitear, ese tipo de cosas.

Los archivos CLAUDE.md se escalonan hacia abajo: el global captura tus preferencias universales, el de proyecto gestiona los detalles y el de subdirectorio sobrescribe para los casos extremos.

Mi repo content-machine, por ejemplo: ese CLAUDE.md explica la configuración de publicación en tres sitios, mapea qué plantillas de prompt van con cada sitio y le dice dónde encontrar las credenciales de WordPress. Me llevó quizá veinte minutos escribirlo y me ha ahorrado probablemente cinco o seis horas de re-explicar el mismo contexto cada vez que abro una sesión nueva.

Descubrí la auto-memoria completamente por accidente. Mencioné "usa siempre bun en este proyecto" durante una sesión, de pasada: sin instrucciones, sin ceremonia, y simplemente siguió haciéndolo desde entonces. Abrí una sesión nueva a la mañana siguiente y ahí estaba, bun por todas partes, sin que yo tocara el CLAUDE.md de ese proyecto. Al parecer Claude Code mantiene sus propios archivos de memoria que captan este tipo de afirmaciones y las persisten. Una vez me di cuenta de que eso pasaba, empecé a ser más deliberado, dejando caer preferencias conversacionalmente y dejando que la auto-memoria las captara.

Plan Mode

Ojalá alguien me hubiera enseñado esto el primer día. Se llega con Shift + Tab: un par de toques y "Plan" aparece en la esquina, facilísimo. Sigue pudiendo leer archivos, buscar código, hacerte preguntas aclaratorias, pero físicamente no puede escribir, editar ni ejecutar nada hasta que vuelvas atrás. Básicamente un paso de pensamiento forzado antes de actuar, lo que suena obvio pero al parecer yo necesitaba un botón para eso.

Tardé un mes entero en probarlo, que visto atrás fue simplemente tonto. Lanzaba prompts vagos como "refactoriza el módulo de subida" y Claude cargaba adelante, reestructuraba tres archivos basándose en suposiciones que yo no había confirmado y pasaba una hora deshaciendo el desastre. Plan Mode evita eso. Describe lo que quieres, deja que Claude haga preguntas aclaratorias sobre enfoque y alcance, revisa el plan y solo entonces déjalo ejecutar.

Cualquier vez que toco más de dos archivos ahora, o retozo en código que no he escrito, o sinceramente cuando simplemente no estoy seguro de lo que quiero todavía: Plan Mode se activa primero. Sáltatelo para trabajos rápidos de un archivo: la bandera -p es mejor para esos, y ya lo hemos cubierto.

Subagentes

Descarté esto como un truco antes de haberlo probado, y eso duró unos cinco minutos. Dale a Claude Code algo propiamente complejo y lanzará subagentes: instancias separadas de Claude, cada una trabajando un ángulo distinto del mismo problema al mismo tiempo. El martes pasado —y lo recuerdo porque me acababa de derramar café en el teclado— vi a uno leyendo mi código de auth mientras otro desmontaba los modelos de base de datos y un tercero ejecutaba la suite de tests. El agente principal vigila a todos, junta los hallazgos y la coordinación es mejor que la que he visto en algunos equipos de dev reales.

Pídele que "investigue el codebase y planifique un refactoring del módulo de pagos" y lanzará agentes exploradores para buscar partes distintas del código y luego juntará sus hallazgos en un plan coherente. Cada subagente obtiene su propia ventana de contexto aislada, así que miles de líneas de código buscado nunca ensucian tu conversación principal; y ese aislamiento importa más de lo que crees.

Los subagentes se ejecutan en paralelo, cada uno con su propia ventana de contexto. El agente principal coordina y fusiona los resultados.

Lo vi gestionar "actualiza todas las plantillas de producto para usar el nuevo esquema" lanzando un agente por cada tipo de plantilla, todos corriendo a la vez, y fusionó los resultados limpiamente. Me habría llevado una tarde entera; a él le llevó unos cuatro minutos.

Tres subagentes corriendo en paralelo: cada uno explorando una parte distinta del codebase, y luego el agente principal junta los hallazgos.

Algo que he aprendido por las malas sobre las ventanas de contexto: cada archivo que Claude lee, cada resultado de herramienta que vuelve, todo come una ventana de contexto finita. Al principio lo dejaba leer archivos enteros de 2.000 líneas, de arriba abajo, cuando nueve de cada diez veces solo necesitaba una única función enterrada por la línea 800. Hoy le digo exactamente qué rango de líneas leer, y para lo que sea de investigación uso subagentes precisamente para que su salida se quede en su propia ventana de contexto en vez de comerse la mía. La ventana de contexto se llena, Claude comprime tu conversación anterior para mantenerse dentro de los límites y de repente ha olvidado cosas que discutiste hace diez minutos. Completamente enloquecedor cuando llevas tres horas en un refactoring y necesita que le re-expliques algo que repasaste en los primeros diez minutos.

Hooks

Comandos de shell que se disparan antes o después de que Claude haga cualquier cosa. Se configuran en JSON, ligados a eventos como PreToolUse o PostToolUse. Yo tengo Prettier corriendo después de cada edición de archivo, una comprobación de lint antes de cualquier commit de git y uno que bloquea de plano las eliminaciones en mi directorio de configuración de producción. Ese último me ha salvado al menos dos veces, posiblemente tres.

Un ejemplo simple: formatear automáticamente con Prettier después de cualquier edición de archivo:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "npx prettier --write $FILE_PATH"
      }
    ]
  }
}

Lo listo son los códigos de salida. Devuelve 0 y las cosas continúan con normalidad, pero un código de retorno de 2 bloquea la acción completamente, parada muerta, y Claude recibe el mensaje de error que hayas escrito. Y se apilan: mi repo content-machine ejecuta dos hooks en cada edición, uno rápido que solo comprueba que la ruta del archivo no es un disparate y otro más lento que canaliza el diff de vuelta a Claude con el prompt "¿esta edición tiene sentido dado lo que la rodea?". Ese segundo hook ha bloqueado al menos tres reescrituras que habrían roto cosas en las que no había pensado.

Algo vergonzoso, esto: pasé semanas sin darle a Claude forma de comprobar su propia salida. Mi servidor MCP seguía fallando los builds tras las ediciones de Claude y yo ejecutaba npm run build manualmente, copiaba el error de TypeScript, lo pegaba de vuelta en el chat, haciendo esa misma danza tediosa una y otra vez. Al final cayó el clic: configuré un hook que ejecuta el build automáticamente tras las ediciones. Claude detecta el error, lo arregla, vuelve a compilar. Transformó todo ese flujo, honestamente: pasé de temer el paso del build a apenas pensarlo. Linters, ejecutores de tests, comprobadores de tipos: mismo principio. Dale una forma de enterarse cuando se equivoca y te sorprendería lo rápido que se pone a sí mismo en orden.

Integración MCP

MCP (Model Context Protocol) es cómo Claude Code se conecta a herramientas externas: bases de datos, APIs, scrapers web, motores de búsqueda, lo que cablees. Si has usado servidores MCP con Claude Desktop conoces el concepto. La diferencia aquí es la autonomía: en Claude Desktop orquestas tú cada llamada MCP, pero Claude Code gestiona todo eso solo, eligiendo la herramienta correcta, llamándola, leyendo el resultado, encadenando la siguiente llamada sin esperar a que le digas qué hacer después.

Claude Code se sitúa en el medio y llama a las herramientas MCP que necesita: búsqueda, scraping, LLM local, lo que hayas cableado.

Mi configuración: Google Search Console, Firecrawl para scraping web, generación de gráficos, análisis de voz y un LLM local corriendo en una segunda máquina. Claude Code elige las herramientas MCP que necesita para la tarea. La función MCP Tool Search, añadida recientemente, recortó mi uso de contexto de unos 77K tokens a 8,7K cargando solo las definiciones de herramientas relevantes. Diferencia enorme cuando tienes seis servidores MCP cargados con decenas de herramientas entre ellos, que es mi caso.

Listé todos los servidores MCP que uso de verdad en mi artículo sobre los mejores MCPs para Claude Desktop.

Una advertencia que ojalá hubiera seguido antes: si ejecutas servidores MCP ligeramente inestables —y algunos lo son, francamente— ten mucho cuidado con las llamadas paralelas a herramientas. Una herramienta MCP hace timeout en un lote paralelo y todas las demás llamadas de ese lote mueren con ella. Perdí casi un jueves por la tarde entero con esto antes de darme cuenta de qué pasaba. ¿Servidor MCP algo fiable? Ejecútalo secuencialmente, porque un timeout no vale perder el lote entero.

Comandos y skills personalizados

Nadie habla de estos y genuinamente no entiendo por qué. Los comandos personalizados son flujos de trabajo que tú mismo montas. Escribe un archivo markdown con frontmatter: qué herramientas están permitidas, qué hace el comando, déjalo en .claude/commands/ y se convierte en un comando slash. He construido un /review-pr que saca el diff, ejecuta mi suite de tests, comprueba problemas de seguridad y escribe un resumen que puedo pegar directamente en el PR. Construí otro para despliegues a staging que gestiona el build, los tests y el push en secuencia. Unos diez minutos para configurar cada uno y los uso casi a diario.

Están bajo control de versiones, lo que significa que todos en el equipo obtienen los mismos flujos de trabajo sin que nadie configure nada. Apenas nadie usa estos todavía. Una pena, la verdad: son una de las funciones más discretas que se acumulan una vez que has construido tres o cuatro.

Los skills son una incorporación más reciente que lleva esto más lejos. Paquetes de instrucciones y herramientas que Claude Code carga cuando los necesita: plugins, básicamente, que extienden lo que puede hacer para tareas específicas. Todavía es pronto para estos, y la mitad de la documentación es texto marcador la última vez que miré.

Componibilidad de la CLI

Filosofía Unix como Dios manda: mete cosas por la entrada, saca cosas estructuradas por la salida. Dale tus logs de error (cat error.log | claude -p "¿qué está causando estos fallos?"), ejecútalo sin interfaz en CI/CD, encadénalo en scripts de shell. La bandera -p es lo que lo hace funcionar: de repente Claude Code ya no es un chat, es una herramienta de línea de comandos que traga stdin y escupe JSON que puedes canalizar a la siguiente cosa.

Yo canalizo borradores de artículos a través de él con prompts de validación de voz y comprobación de hechos, tomo la salida JSON, la convierto en informes de calidad. Construí toda la pipeline en una tarde y probablemente ha cazado más errores de los que me gustaría admitir.

Poniéndolo en uso práctico: cómo lo uso cada día

Dejo fuera un montón —el SDK, la integración con GitHub, probablemente una docena de cosas que ni siquiera he probado todavía. Pero los tres flujos de abajo se comen en torno al 80 % de mi tiempo con esta cosa, así que son lo que de verdad te contaría de viva voz.

Producción de contenidos: este artículo es de hecho la salida de ese flujo. Tres sitios, un repo. Claude Code lee mi CLAUDE.md, elige la plantilla de prompt correcta para converly.es, ejecuta la investigación vía herramientas MCP (Firecrawl para scraping, datos de Search Console, análisis SERP), produce un borrador y yo ejecuto comprobaciones de voz y detección de IA sobre la salida. De investigación a subida a WordPress en una sesión, aunque "una sesión" a veces significa tres horas de ida y vuelta cuando la puntuación de detección de IA no baja. La pipeline completa está en mi artículo sobre content marketing con IA si quieres los detalles escabrosos.

Construir servidores MCP. Mi herramienta de análisis de voz es un servidor MCP en TypeScript, unas 1.500 líneas en una docena de archivos. Cuando lo actualizo describo lo que quiero cambiar y Claude Code gestiona el resto: lee los tipos existentes, actualiza los handlers y analizadores, edita el archivo index para que cuadre, ejecuta el build. Si el build falla —y suele fallar al primer intento, algo de mi tsconfig que lo tropieza— lee el error de TypeScript, arregla la línea conflictiva y recompila. Todo eso antes de que mi tetera hierva, lo que todavía me asombra.

Preguntas y respuestas sobre el codebase: honestamente mi caso de uso favorito, y no creo que suficiente gente lo conozca. Tomé un proyecto de contrato en febrero sin documentación —ni un solo README, nada— y le pedí a Claude Code que me guiara por el flujo de auth. Lo tuve mapeado en unos dos minutos, incluido un middleware que habría pasado por alto por completo por mi cuenta. Boris Cherny, de Anthropic, insiste en empezar con Q&A en sus charlas y tiene toda la razón: es probablemente la mejor manera de ponerse cómodo con cómo Claude Code aborda un problema.

Ejemplo real: revisar un servidor MCP

Para mostrarte qué aspecto tienen las Q&A sobre un codebase en la práctica, apunté Claude Code a uno de mis servidores MCP: la integración de Gemini, unas 5.000 líneas de TypeScript en trece herramientas — y le pedí una revisión de arquitectura. Un comando:

cd gemini-mcp
claude -p "Review the architecture of this MCP server. What patterns
  does it use, what's done well, and what could be improved? Focus on
  src/index.ts, the tool registration, and error handling."

Sin configuración, sin contexto, sin "así es como está estructurado el proyecto". Claude Code lo dedujo todo por su cuenta.

Una revisión de arquitectura de código de producción que de verdad mantengo. Claude Code identificó el patrón de inyección de dependencias, la jerarquía de errores y cuatro cosas concretas que merece la pena mejorar: todo sin que se le dijera cómo estaba estructurado el proyecto.

No es un ejemplo de juguete: este es el servidor MCP que publico y mantengo, el que alimenta mi integración de Gemini. Encontró el patrón de inyección de dependencias vía ToolContext, la validación de esquema Zod en cada herramienta, el patrón fábrica para servicios y la jerarquía de errores personalizada. Más útilmente, marcó cuatro problemas concretos: matching de errores basado en strings en vez de errores tipados, ausencia de timeouts de petición, registro imperativo de herramientas sin carga dinámica y pérdida de contexto asíncrono en el logger.

Naturalmente no me lo creí a ciegas: abrí cada archivo fuente que mencionó y comprobé línea por línea. ¿El asunto del matching de strings? Lo conocía desde hacía semanas: lo tenía en una nota adhesiva en el monitor, de hecho, y seguía ignorándolo. Lo del timeout era un riesgo de producción de verdad que había pasado por alto completamente.

A esto me refiero cuando digo "haz preguntas antes de editar". Treinta segundos de revisión sacaron a la luz problemas que me habrían llevado una hora de lectura de código fuente para catalogar manualmente. Y como lo ejecuté con -p y sin permisos de escritura, no pudo cambiar nada: análisis puramente de solo lectura. Si heredas un codebase, te incorporas a un proyecto nuevo o simplemente no has mirado tu propio código en un tiempo, esta es la forma más rápida de orientarte.

Dónde se queda corto

Quema de tokens. Oh, la quema de tokens. El mes pasado ejecuté una sesión de refactoring en mi módulo de subida a WordPress que de algún modo se comió nueve dólares en una sola conversación, lo que solo noté porque había empezado a comprobar el panel de uso tras un susto anterior. Ejecutar un LLM local en una segunda máquina y delegarle el trabajo sucio ha reducido a la mitad lo que gasto.

Fatiga de permisos. El modo por defecto significa que Claude pregunta antes de casi cada acción: leer este archivo, editar aquel, ejecutar este comando; y tras el decimoquinto aviso en dos minutos te empiezas a preguntar si hay una forma mejor. Las reglas de auto-permitir existen, pero ajustar el equilibrio correcto requiere ensayo y error genuino. Demasiado permisivo y darás luz verde a algo destructivo, demasiado restrictivo y estás machacando "permitir" cada tres segundos.

Cada llamada a herramienta recibe uno de estos avisos por defecto. El atajo "(presiona 'a' para permitir siempre)" es tu amigo una vez que confías en el patrón.

Errores confiados. Se equivoca, y lo que de verdad me saca de quicio es lo seguro que se mantiene mientras lo hace. Lo he visto refactorizar código que rompía un caso extremo sutil, sugerir enfoques que funcionan para el camino feliz pero colapsan bajo carga. Todavía tienes que revisar todo lo que produce: el mejor modelo mental que he encontrado es un desarrollador junior muy capaz, brillante siguiendo instrucciones, inútil sabiendo cuándo parar.

Servidores MCP inestables. Algunos son sólidos como una roca. Otros hacen timeout, lanzan errores o cascadan fallos cuando se los llama en paralelo. No es culpa de Claude Code, concedido, pero es tu dolor de cabeza cuando un timeout mata un lote entero de llamadas a herramientas.

Cosas que ojalá hubiera sabido desde el principio

CLAUDE.md el primer día: o ejecuta claude init y deja que genere uno. Perdí tres semanas re-explicando mi configuración de proyecto cada mañana antes de hacer esto por fin. Tres semanas. Del mismo speech. Cada mañana.

Haz preguntas antes de editar nada: "Guíame por el flujo de auth" no cuesta nada y caza las suposiciones erróneas antes de que se conviertan en una bola de nieve y un desastre. He aprendido esta lección probablemente una docena de veces y probablemente la aprenderé de nuevo el próximo martes.

Plan Mode para cambios de varios archivos: cinco minutos de planificación ahorran una hora de deshacer, y lo digo como alguien que aprendió esto por las malas a lo largo de unas cuatro semanas de limpieza innecesaria.

Cablea tu ejecutor de tests como un hook: pasé semanas dejando que Claude rompiera builds porque no le había dado forma de comprobar su propio trabajo. Vergonzoso visto atrás, trivial de arreglar.

Commitea antes de cada edición de Claude: las regresiones ocurren más de lo que crees. Tres segundos de un git commit te compran un punto de reversión, y te lo agradecerás cuando algo sutil se rompa en la línea 847.

Vigila tu ventana de contexto: dile a Claude qué rangos de líneas leer en vez de dejarle aspirar archivos enteros. Los subagentes ayudan aquí también: sus hallazgos se quedan en su propio contexto, no en el tuyo.

Usa -p para trabajos rápidos: honestamente así es como uso Claude Code más de la mitad del tiempo ahora. Un prompt, un resultado, sin sobrecarga de sesión, de vuelta a lo que fuera que estaba haciendo.

---

Quince y pico años escribiendo código, y he abandonado más herramientas de productividad de las que puedo contar. La mayoría duraron una semana antes de volver discretamente a hacer las cosas a la antigua. Claude Code aguantó. Si estás empezando, la instalación tarda dos minutos, el CLAUDE.md veinte, y la primera vez que lo ves encadenar seis llamadas a herramientas para arreglar un bug que llevas mirando una hora, entenderás por qué sigo dándole vueltas a esto.