El mejor setup de Claude Code para 2026 (guía 30 min)

Todos los setups de Claude Code que he revisado caen en uno de dos modos de fallo. El primero es el básico por defecto: sin CLAUDE.md, sin skills, confirmaciones de permisos en cada comando, y el usuario preguntándose por qué Claude olvida constantemente cómo se compila su proyecto. El segundo es la máquina sobreconfigurada: 40 skills, 9 servidores MCP, un CLAUDE.md del largo de una tesis, y una ventana de contexto medio consumida antes del primer prompt.

El buen setup está entre ambos extremos, y toma unos 30 minutos construirlo si haces las capas en el orden correcto de dependencias. Ese orden importa. Las skills asumen una instalación funcionando. Las decisiones de permisos dependen de qué servidores MCP uses. La separación por proyecto solo tiene sentido una vez que sabes qué estás separando. Esta es la guía que le damos a los nuevos compañeros de SkillProof el primer día, con las partes que hicimos mal en seis meses ya eliminadas.

Capa 1: instalación y autenticación, cinco minutos

Probablemente ya hiciste esto, así que seré breve.

npm install -g @anthropic-ai/claude-code
cd your-project
claude

En el primer arranque, /login te guía por la autenticación. Tienes dos caminos de facturación: una suscripción Claude (Pro o Max) o una API key con facturación por token. Si programas con Claude a diario, la suscripción casi siempre sale más barata; la facturación por API en sesiones agénticas intensas se acumula más rápido de lo que la gente espera. Si trabajas en equipo, revisa si tu organización tiene un asiento de Claude for Work antes de quemar una API key personal.

Verifica con algo trivial ("¿qué hace este repo?") y confirma que Claude puede leer tus archivos. Eso es toda la capa. Todo lo de abajo es donde los setups realmente divergen.

Capa 2: un CLAUDE.md que se gane sus tokens

CLAUDE.md es un archivo markdown que Claude lee en el contexto al inicio de cada sesión en ese proyecto. Cada sesión, sea o no relevante el contenido. Ese comportamiento de carga dicta todo lo que debería ir ahí.

Qué pertenece: hechos que aplican a casi todas las sesiones. Comandos de build y test. La versión de dos frases de tu arquitectura. Convenciones que Claude sigue equivocando si no se le dicen (tu orden de imports, tu formato de commits). Dónde están enterrados los cuerpos: el módulo obsoleto que nadie debería tocar, el archivo de config que parece no usarse pero sí se usa.

Qué no pertenece: conocimiento procedimental que necesitas ocasionalmente. Cómo escribir una migración de base de datos. Tu checklist de release. El estilo de la casa para emails a clientes. Cada uno de esos aplica a quizás el 5% de las sesiones, y en CLAUDE.md los pagas también en el otro 95%. Ese material quiere ser una skill (la siguiente capa), que carga solo cuando se activa.

Nuestra regla general tras probar esto en nuestro propio repo: si tu CLAUDE.md pasa de 60 líneas, algo ahí debería salir. El nuestro empezó en 400 líneas porque lo tratamos como documentación. Claude lo seguía peor, no mejor, porque la señal se ahogaba. La versión comprimida, unas 50 líneas de comandos y restricciones duras, se obedece casi siempre.

Escribe el primer borrador en diez minutos y para ahí. Lo refinarás durante semanas a medida que detectes a Claude repitiendo errores; ese bucle iterativo es el método real. El tratamiento completo, incluyendo los antipatrones que vemos en los archivos que nos envían los lectores, está en nuestra guía de CLAUDE.md.

Capa 3: skills, la capa que más gente se salta

Esta es la capa que separa un setup de una simple instalación, y es la que casi nadie toca. Una skill es una carpeta con un archivo SKILL.md que le enseña a Claude una forma de trabajar. Cuesta unos 100 tokens de metadata mientras está inactiva y carga sus instrucciones completas solo cuando una tarea coincide con su descripción. Instalada una vez, aplica para siempre, en cada sesión.

La gente se salta esta capa por una razón racional: cerca de la mitad de las skills comunitarias en GitHub fallan en la primera instalación. Lo sabemos porque instalarlas y testearlas es todo nuestro negocio. Cada skill del catálogo de SkillProof pasa por una instalación en máquina limpia y verificación de disparo, luego tareas reales corren contra una línea base sin skill, antes de recibir un veredicto. De las 73 skills que hemos catalogado hasta ahora, 35 pasaron.

Para un setup de desarrollador, estas son las cinco para instalar primero, con puntajes de nuestras pruebas:

1. Test-Driven Development, 9.6. Fuerza un ciclo estricto red-green-refactor: test que falla primero, implementación mínima, luego limpieza. En nuestra sesión de tres features nunca se saltó el ciclo, ni cuando intentamos convencerlo de saltárselo.
2. Systematic Debugging, 9.6. Reemplaza los arreglos por prueba y error con un bucle de hipótesis-prueba-verificación. Encontró la causa raíz de una condición de carrera que Claude había "arreglado" previamente tres veces adivinando.
3. Frontend Design, 9.6. La mayor brecha antes/después que hemos medido en cualquier skill. El mismo brief de landing page, ejecutado dos veces: la línea base produjo el look de gradiente neón con todo centrado, la versión con skill tenía una escala tipográfica real y una paleta que parecía elegida.
4. Memory Management, 9.2. Le da a Claude memoria persistente entre sesiones. Durante una semana de pruebas recordó de forma fiable decisiones y preferencias del proyecto, y el recall se mantuvo preciso a medida que crecía el almacén.
5. Webapp Testing, 8.8. Claude maneja tu app en un navegador real vía Playwright y reporta qué se rompe. Detectó una regresión que nuestros tests unitarios no vieron.

Las dos primeras vienen de la colección Superpowers de Jesse Vincent (/plugin marketplace add obra/superpowers-marketplace, luego /plugin install superpowers). Frontend Design viene en el repo oficial de skills de Anthropic y se copia directo a ~/.claude/skills/. Los pasos exactos, incluyendo los modos de fallo que se comen la primera hora de la gente, están en la guía de instalación. Después de instalar, reinicia Claude Code y prueba cada disparador pidiendo el trabajo sin nombrar la skill. Si nada cambia visiblemente, la skill no se está activando, y una skill instalada que nunca se activa es solo una carpeta.

Si tu trabajo va en otra dirección, nuestra lista de mejores skills de programación clasifica toda la categoría, actualizada según llegan nuevas pruebas.

Capa 4: servidores MCP, solo los que vas a usar

Los servidores MCP conectan a Claude con cosas fuera del repo: tu base de datos, tu tracker de issues, un navegador en vivo. Son poderosos y son la línea más cara de tu presupuesto de contexto. Cada servidor conectado inyecta sus definiciones de herramientas en cada sesión, se use o no, y un solo servidor hablador puede costar más tokens fijos que 50 skills instaladas juntas. Medimos esto en la guía de costo de tokens, y los números cambiaron cómo configuramos nuestras propias máquinas.

Así que la barra para un servidor MCP debería ser alta: se gana un lugar solo si Claude necesita alcanzar algo que de otra forma no puede. Tres suelen sobrevivir esa prueba para desarrolladores:

Un servidor de base de datos (Postgres o lo que uses). Que Claude escriba queries contra tu esquema real en vez de uno adivinado es un producto distinto. Esta es la conexión MCP de mayor valor para la mayoría de los equipos.

Automatización de navegador (Playwright MCP), si haces UI y no usas el setup propio de la skill Webapp Testing. Ver la página renderizada le gana a inferirla desde JSX siempre.

Tu tracker de issues, pero solo si de verdad trabajas ticket a ticket dentro de Claude Code. Si miras Linear dos veces al día, el navegador basta y los tokens no valen la pena.

Nota lo que falta: el servidor MCP de GitHub. El CLI gh hace todo lo que él hace, Claude ya sabe usarlo, y no cuesta contexto fijo. Este patrón de sustitución se generaliza. Antes de agregar cualquier servidor, pregúntate si una herramienta CLI que Claude puede invocar te da el mismo alcance gratis. Y si estás decidiendo si un problema necesita MCP o solo una skill, la regla de decisión está en skills vs MCP: las skills cambian lo que Claude sabe hacer, MCP cambia lo que puede tocar.

Capa 5: permisos y ajustes de seguridad que vale la pena cambiar

La experiencia de permisos por defecto es una confirmación para casi cada comando, lo cual entrena a la gente a hacer clic en permitir por reflejo. Ese es el peor resultado posible: toda la fricción, ninguna de la seguridad. Dos cambios lo arreglan.

Primero, agrega a la lista blanca los comandos que aprobarías igual. En .claude/settings.json:

{
  "permissions": {
    "allow": [
      "Bash(npm test:*)",
      "Bash(npm run lint:*)",
      "Bash(git status)",
      "Bash(git diff:*)",
      "Bash(git log:*)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  }
}

Segundo, fíjate en el bloque deny, porque es la mitad que la gente se salta. Claude no tiene nada que hacer leyendo tu .env, y una regla deny hace de eso una propiedad del sistema en vez de una esperanza. Si corres servidores MCP o skills de terceros, esto importa más, porque una instrucción maliciosa no puede exfiltrar lo que el harness no lee. Nuestra guía de seguridad cubre el lado de la auditoría.

Sobre --dangerously-skip-permissions: el nombre de la bandera es honesto. Dentro de un contenedor desechable sin credenciales, es una buena forma de correr trabajos largos desatendidos. En tu laptop, con tus llaves SSH y tus sesiones de navegador logueadas, es cómo terminas siendo protagonista de un postmortem. La usamos en sandboxes de CI y en ningún otro lado.

Por proyecto vs global: dónde vive cada pieza

Todo lo anterior existe en dos niveles, y mezclarlos es el desorden de configuración más común que vemos. La separación:

Pieza	Global (~/.claude/)	Por proyecto (.claude/ en el repo)
CLAUDE.md	Tu estilo personal: largo de respuesta, idiomas, manías	Comandos de build, arquitectura, convenciones del proyecto (commitéalo)
Skills	Todo lo general: debugging, TDD, escritura	Solo flujos de trabajo específicos del equipo
Settings	Tu lista blanca personal	Lista blanca y reglas deny del equipo (commitéalo)
settings.local.json	—	Tus overrides solo de tu máquina (ponlo en gitignore)
Servidores MCP	Servidores que usas en todas partes	El .mcp.json del proyecto, así el equipo comparte las mismas conexiones

El principio: lo que un compañero necesitaría va en el repo, lo que es sobre ti va global. El beneficio aparece cuando alguien nuevo clona el proyecto y Claude ya conoce los comandos de build y las convenciones, con la conexión a la base de datos lista. Su capa 2 y media capa 4 vienen gratis.

Mi setup después de seis meses

Lo que realmente sobrevive en mi máquina, para calibrar: un CLAUDE.md de proyecto de 54 líneas, nueve skills, dos servidores MCP (Postgres y Playwright), y el bloque de permisos de arriba. Las sesiones de setup se sienten idénticas a hace seis meses; la diferencia es todo lo que borré.

Las eliminaciones me enseñaron más que las adiciones:

Eliminé el servidor MCP de GitHub. Lo mantuve cuatro meses por inercia. Sus definiciones de herramientas costaban miles de tokens fijos por sesión y gh hacía el mismo trabajo. Nada empeoró. Esta sola eliminación pagó el tiempo de escribir este artículo.

Eliminé un servidor MCP de memoria a favor de la skill Memory Management. El servidor era otro proceso que cuidar y otra autenticación que mantener. La skill hace el trabajo en archivos planos que puedo leer y editar yo mismo. Cuando la memoria falla, abro el markdown y lo arreglo, algo que nunca pude hacer con un almacén opaco.

Recorté CLAUDE.md de 400 líneas a 54. La versión larga se leía como buena documentación y funcionaba como ruido. El cumplimiento de las reglas que importaban subió cuando se borraron las que no importaban. Ahora trato cada línea como renta.

Desinstalé 19 de 28 skills. La mayoría eran instalaciones de "podría ser útil" que nunca se activaron en trabajo real. La carga diferida hace que cuesten poco, pero descripciones superpuestas causaron dos conflictos de disparo reales, y la auditoría que los encontró fue tediosa. Nueve skills que se activan cada semana le ganan a 28 que en su mayoría no lo hacen.

Revertí una regla ciega de allow Bash(*). La agregué durante una semana de entrega y la mantuve demasiado tiempo. El día que Claude corrió con confianza una migración destructiva contra una base de datos de desarrollo que resultó ser menos desechable de lo etiquetado, volví a poner las confirmaciones para cualquier cosa que escriba.

El patrón en las cinco: nunca me arrepentí de una eliminación. Con frecuencia me arrepentí de adiciones.

Errores comunes de la primera semana

Cinco cosas que casi todos hacen en la primera semana, para que te las saltes:

1. Escribir el CLAUDE.md de 500 líneas el primer día. Todavía no sabes qué se equivoca Claude en tu repo. Empieza con 15 líneas y hazlo crecer desde fallos observados.
2. Instalar cada servidor MCP interesante. Cada uno grava cada sesión. Empieza con cero y agrega uno cuando choques con un muro que resuelve.
3. Correr --dangerously-skip-permissions en tu máquina principal porque las confirmaciones te molestaban. Pon en lista blanca los comandos seguros en su lugar; elimina el 90% de las confirmaciones sin la exposición.
4. Instalar skills y nunca verificar que se activan. La mitad del valor de una skill muere en un campo de descripción vago. Prueba cada una con una petición natural, sin nombrar la skill.
5. Mantener la config fuera del repo. Si el CLAUDE.md y settings.json de tu proyecto no están commiteados, cada compañero reconstruye tu setup mal, de memoria.

Mantenimiento: qué revisar después de cada release de Claude

Un setup afinado para una versión del modelo se desactualiza en la siguiente. Después de cada release importante de Claude, dedica 20 minutos a cuatro revisiones.

Relee tu CLAUDE.md y borra las reglas que el nuevo modelo ya no necesita. Las actualizaciones de modelo suelen volver obsoletas instrucciones; esa regla de "siempre corre el linter" que escribiste hace un año puede ser ahora comportamiento por defecto que estás pagando tokens por repetir.

Vuelve a probar los disparadores de tus skills. El matching de disparadores es comportamiento del modelo, no coincidencia de palabras clave, así que una descripción que se activaba de forma confiable en un modelo puede quedar en silencio en el siguiente. Nuestro catálogo vuelve a probar las skills top después de releases importantes, y las páginas de cada skill llevan el veredicto vigente.

Vuelve a medir tu sobrecarga de contexto. Los releases nuevos a veces cambian cómo se cuentan o se cachean las definiciones de herramientas MCP. Las herramientas de eficiencia en nuestra lista de skills de eficiencia es donde mandamos a la gente que quiere auditar qué está quemando realmente su presupuesto; varias skills de esa categoría existen precisamente para esta revisión.

Y revisa el changelog en busca de cambios en el modelo de permisos antes de que el settings de tu equipo signifique en silencio algo distinto. Esto toma cinco minutos y nos ha salvado dos veces.

Preguntas frecuentes

¿Es realista lo de 30 minutos, en serio?

Para las capas 1 a 5 tal como están escritas, sí, lo hemos cronometrado con nuevas contrataciones. Lo que toma más tiempo es el ajuste fino: tu CLAUDE.md alcanza su forma estable tras dos o tres semanas detectando los errores repetidos de Claude. Presupuesta 30 minutos para la construcción y espera unos minutos de ajuste por día durante la primera quincena.

¿Necesito servidores MCP siquiera?

Muchos setups sólidos corren con cero. Si tu trabajo vive en el repo (código, tests, docs), skills más herramientas CLI lo cubren. MCP se gana su costo cuando Claude necesita acceso en vivo a algo externo, y una base de datos es el caso genuino más común. Si tienes dudas, empieza sin él y agrega el servidor la primera vez que sientas el muro.

¿CLAUDE.md debería ser global o por proyecto?

Ambos, llevando cosas distintas. El global (~/.claude/CLAUDE.md) lleva tus preferencias personales y aplica en todas partes. El de proyecto lleva comandos de build y convenciones, y pertenece a git para que todo el equipo lo comparta. El error es poner hechos del proyecto en el archivo global, donde contaminan las sesiones de todos los demás proyectos.

¿Cuántas skills son demasiadas?

En tokens, el techo es alto: incluso 50 skills cuestan solo unos miles de tokens de metadata fija. El techo práctico es más bajo porque skills con descripciones superpuestas empiezan a competir por los mismos disparadores. Nosotros corremos nueve. Pasadas las 15 más o menos, deberías estar podando lo que no se ha activado en un mes en vez de agregar.

¿Puedo saltarme la capa de permisos si trabajo en un sandbox?

Si el sandbox es genuinamente desechable, sin credenciales, sin volúmenes montados que te importen, entonces sí, y --dangerously-skip-permissions existe exactamente para eso. La capa importa en máquinas con secretos reales. El "sandbox" de la mayoría de la gente es una laptop con sus llaves de AWS de producción en un dotfile, lo cual no es un sandbox.