Instalación y Configuración

La Guía Completa de Configuración de Claude Code (2026)

Charles Krzentowski24 de marzo de 20268 min read

Acabas de instalar Claude Code. Escribiste claude en tu terminal y... funciona. Puede leer tus archivos, ejecutar comandos, escribir código. Bastante genial.

Pero aquí está el asunto: estás dejando el 90% de su potencia sin usar.

En nuestro análisis de más de 800 configuraciones en jeanclaudecode.ai, la puntuación promedio es 3.2 de 10. La mayoría de la gente instala Claude Code, quizás escribe un par de líneas de instrucciones, y se detiene ahí. Diez minutos de configuración separan un chatbot básico de un verdadero compañero de programación.

Vamos a arreglarlo ahora mismo.

El archivo que lo cambia todo

Crea un archivo llamado CLAUDE.md en la raíz de tu proyecto. Eso es todo. Es lo más importante que harás hoy.

touch CLAUDE.md

CLAUDE.md es lo primero que Claude lee cuando inicias una sesión. Piénsalo como un documento de briefing — le estás diciendo a Claude con quién trabaja, cómo se ve el proyecto, y cuáles son las reglas.

Aquí tienes uno mínimo para empezar. Abre CLAUDE.md y pega esto:

# Mi Proyecto

## Stack Técnico
- Next.js 15, TypeScript, PostgreSQL

## Comandos
- `npm run dev` — servidor de desarrollo
- `npm run test` — ejecutar tests
- `npm run build` — build de producción

## Reglas
- Siempre ejecutar tests antes de decir que una tarea está terminada
- Nunca modificar archivos en src/legacy/

Cinco líneas de stack técnico. Tres comandos. Dos reglas. Es todo lo que necesitas para empezar.

Pruébalo ahora. Abre Claude Code y pregunta: "Lee mi CLAUDE.md y dime qué proyecto es este." Claude debería describir tu proyecto. Si lo hace, todo bien. Si no, verifica que el archivo está en la raíz del proyecto (no dentro de una subcarpeta).

Acabas de darle a Claude algo que el 68% de los setups no tiene: conocimiento básico del proyecto.

Subiendo de nivel: el CLAUDE.md de los mejores setups

Ese archivo mínimo funciona. Pero los setups que puntúan 7+ en nuestro análisis van más allá. Esto es lo que agregan — y por qué cada sección importa.

Sección de arquitectura (en el 78% de los mejores setups)

Claude no sabe dónde viven tus archivos. Sin un mapa, adivina — y adivina mal. Agrega esto:

## Arquitectura
- src/app/ — Páginas y rutas API del App Router
- src/lib/ — Utilidades compartidas y cliente de base de datos
- src/components/ — Componentes React (tests colocalizados)

Ahora cuando dices "crea una nueva ruta API", Claude la pone en src/app/api/ en lugar de inventar una ubicación aleatoria.

Sección de convenciones (65% de los mejores setups)

Tienes opiniones sobre cómo debe verse el código. Claude no las conoce si no se las dices:

## Convenciones
- Mensajes de commit imperativos, minúsculas, sin punto
- Un componente por archivo, solo exports nombrados
- Todas las rutas API validan entrada con esquemas zod

Sé específico. "Escribe código limpio" no le da nada a Claude. "Usa zod para toda validación de entrada API" le da una regla concreta que seguir.

Sección de problemas conocidos (solo 34% de los mejores setups — la mayor oportunidad perdida)

Esta es la sección que la mayoría salta, y es la que te ahorra más frustración:

## Problemas Conocidos
- El handler del webhook de Stripe necesita parsing de body `raw` — no usar el middleware express.json() en /api/webhooks/stripe
- Safari no soporta `structuredClone` en workers — usar el polyfill en src/lib/clone.ts
- El entorno de CI tiene 4 GB de RAM — los tests que excedan esto fallarán silenciosamente (OOM)

Cada vez que Claude comete un error que ya has visto, agrégalo aquí. Con el tiempo, esta sección se convierte en la más valiosa del archivo — un registro vivo de "no pises esta mina".

Sección	Impacto	Presente en los mejores setups
Stack técnico	Medio	92%
Arquitectura / mapa de archivos	Alto	78%
Convenciones	Alto	65%
Comandos	Medio	71%
Reglas / restricciones explícitas	Muy alto	84%
Patrones de error / problemas conocidos	Alto	34%

Ahora los permisos (para que Claude deje de pedirte permiso para todo)

Por defecto, Claude pide permiso antes de ejecutar cualquier comando shell. Cada. Vez. Se vuelve tedioso rápido.

La solución: crear un archivo de configuración que le diga a Claude qué puede hacer sin preguntar.

mkdir -p .claude

Ahora crea .claude/settings.json:

{
  "permissions": {
    "allow": [
      "Bash(npm run test*)",
      "Bash(npm run build)",
      "Bash(npm run lint*)",
      "Bash(git status)",
      "Bash(git diff*)",
      "Bash(git log*)",
      "Bash(git add *)",
      "Bash(git commit *)",
      "Read",
      "Glob",
      "Grep"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force*)",
      "Bash(git reset --hard*)"
    ]
  }
}

La lista allow dice "adelante, no preguntes." La lista deny dice "nunca hagas esto, aunque te lo diga por error."

Importante: Nunca pongas "Bash(*)" en la lista allow. Eso le da a Claude acceso total al shell sin barreras. Sé específico sobre lo que se permite.

Prueba Claude Code ahora. Pídele que verifique el git status o ejecute los tests. ¿Notas cómo simplemente... lo hace? Sin popup de permiso. Ese flujo es lo que separa los setups que la gente abandona de los que realmente usan cada día.

Agrega rules que se activan automáticamente

Quizás te preguntas: "¿Debería poner todas mis convenciones de código en CLAUDE.md?" Podrías. Pero hay una forma más inteligente.

Las rules son archivos markdown que se activan según los archivos en los que Claude está trabajando. Cuando Claude edita un .tsx, carga tus reglas de frontend. Cuando toca un archivo de migración, carga tus reglas de base de datos. Cuando trabaja en CSS, no pierde tiempo leyendo tus convenciones de SQL.

Crea el directorio de rules:

mkdir -p .claude/rules

Aquí hay una regla de frontend. Guárdala como .claude/rules/frontend.md:

---
globs: ["*.tsx", "*.jsx", "*.css"]
---

- Usar exports nombrados, no exports por defecto
- Cada componente debe tener un archivo .test.tsx correspondiente
- Solo CSS modules — sin estilos inline excepto para valores dinámicos
- Todas las imágenes necesitan texto alt (requisito de accesibilidad)

Y una regla de base de datos — guarda como .claude/rules/database.md:

---
globs: ["*.sql", "**/migrations/**", "**/prisma/**"]
---

- Nunca modificar archivos de migración existentes
- Todas las consultas deben usar entradas parametrizadas — nunca concatenación de strings
- Incluir lógica de rollback en cada migración

La línea globs arriba es el disparador. Cuando Claude lee o edita cualquier archivo que coincida con ese patrón, la rule se carga automáticamente. Cero tokens desperdiciados cuando no es relevante.

Mira lo que has construido

Así debería verse tu proyecto ahora:

tu-proyecto/
├── CLAUDE.md                          # Tu briefing de proyecto
├── .claude/
│   ├── settings.json                  # Permisos (committed, compartido con el equipo)
│   └── rules/
│       ├── frontend.md                # Se activa para .tsx, .jsx, .css
│       └── database.md                # Se activa para .sql, migraciones
├── .gitignore
└── src/
    └── ...

Una cosa más — agrega esta línea a tu .gitignore:

# Configuración local de Claude Code
.claude/settings.local.json

El archivo settings.local.json es para preferencias personales (como tu modelo preferido). No debería estar en control de versiones. ¿El settings.json normal? Hazle commit — es configuración compartida del equipo.

Verifica que todo funciona

Abre Claude Code y prueba esto:

> Lee mi CLAUDE.md y dime qué proyecto es este. ¿Qué rules ves?

Claude debería describir tu proyecto, listar las rules encontradas en .claude/rules/, y confirmar los permisos de settings.json. Si puede, listo. Si falta algo, verifica que tus archivos están en las ubicaciones correctas.

También puedes evaluar tu setup con nuestro analizador — revisa las cuatro capas (CLAUDE.md, settings, rules, estructura de directorios) y te dice exactamente qué funciona y qué falta.

Los errores que hunden los setups

Después de revisar cientos de setups, estos son los patrones que consistentemente puntúan bajo:

Instrucciones vagas. "Escribe código limpio" y "sigue las buenas prácticas" no le dan a Claude información útil. Compara: "valida las entradas correctamente" (inútil) vs "Usa zod para toda validación de entrada API" (accionable).

Sin lista de permisos. Cada llamada de herramienta requiere aprobación manual, el desarrollador se frustra, abandona Claude Code, y concluye que no es productivo. Cinco minutos de settings.json previenen esto por completo.

Todo metido en CLAUDE.md. Tus convenciones de base de datos no importan cuando Claude está editando CSS. Mueve instrucciones específicas de archivos a archivos rules — mantienen el contexto enfocado y ahorran tokens.

Sin sección de arquitectura. Sin un mapa de archivos, Claude pone archivos en los directorios equivocados, usa rutas de importación incorrectas, y genera código que no encaja en tu proyecto. Una sección de arquitectura de 5 líneas previene esto.

Sin .gitignore para configuraciones locales. Los miembros del equipo sobrescriben las preferencias de otros, o peor, las claves API terminan en control de versiones.

¿Qué sigue?

Tienes una base sólida. Tu CLAUDE.md le dice a Claude sobre tu proyecto, tus settings lo mantienen productivo, y tus rules lo mantienen en el camino correcto.

¿Listo para más? Aquí es donde ir:

Automatiza lo aburrido — hooks que formatean código automáticamente, skills que ejecutan workflows multi-paso con un comando slash, y cuándo usar cada uno
Conecta Claude a tus herramientas — servidores MCP que permiten a Claude consultar tu base de datos, buscar tus issues de GitHub, y obtener errores de Sentry directamente
Controla tu factura — números reales de costos, el truco de /compact, y cuándo Opus vale el premium

Preguntas frecuentes

¿Dónde debe ir CLAUDE.md — en la raíz del proyecto o el directorio .claude?

En la raíz del proyecto. Claude Code busca CLAUDE.md en la raíz de tu directorio de trabajo primero. También puedes crear ~/.claude/CLAUDE.md para instrucciones globales que apliquen a todos tus proyectos. Si ambos existen, ambos se cargan — global primero, luego específico del proyecto.

¿Todo el equipo puede compartir un CLAUDE.md?

Sí, y deberían. CLAUDE.md pertenece a tu repositorio. Es contexto compartido — arquitectura del proyecto, convenciones, comandos. Para preferencias personales (como qué modelo prefieres o aliases personalizados), usa .claude/settings.local.json que queda gitignored.

¿Qué tan largo debe ser CLAUDE.md?

Los mejores setups que hemos analizado tienen entre 100 y 500 líneas. Menos de 100 significa que probablemente te falta contexto crítico (arquitectura, convenciones, problemas conocidos). Más de 500 significa que probablemente incluyes cosas que deberían estar en archivos rules. El objetivo son instrucciones enfocadas y de alta señal.

¿Claude Code funciona sin nada de este setup?

Técnicamente sí, pero mal. Sin CLAUDE.md, Claude no tiene conocimiento de la estructura de tu proyecto, convenciones, ni restricciones. Aún genera código, pero pone archivos en lugares equivocados, usa patrones incorrectos, e ignora las reglas específicas de tu proyecto. Nuestros datos muestran que los setups sin configurar promedian 1.8/10. El setup no es opcional si quieres ganancias reales de productividad.

¿Con qué frecuencia debo actualizar CLAUDE.md?

Cuando tu proyecto cambie: nuevas convenciones, nuevas herramientas, nuevos problemas conocidos. Una buena práctica es agregar una entrada en "Problemas Conocidos" cada vez que Claude cometa un error que no debería repetirse. Con el tiempo, CLAUDE.md se convierte en un documento vivo que previene que los mismos errores recurran — y ese es uno de los usos más valiosos del archivo.

FAQ