Dominar Claude Code Parte 3: Configuración del Proyecto

Esto es algo que confunde a casi todos los que empiezan con Claude Code: lo usan en un proyecto, obtienen resultados mediocres y asumen que simplemente no es tan bueno. Pero luego ven a otra persona obtener resultados increíbles en un código similar. ¿Cuál es la diferencia?

Configuración.

Una sesión de Claude Code bien configurada no solo entiende tu código—entiende tus patrones, tus convenciones, las preferencias de tu equipo. Sabe que usas Bun en vez de npm, que las rutas de API están en app/api/, y que tu equipo tiene opiniones firmes sobre el manejo de errores. Este capítulo te muestra cómo configurar todo eso.

CLAUDE.md: La Memoria de tu Proyecto

CLAUDE.md se carga automáticamente cuando Claude Code inicia. Piensa en él como el manual de instrucciones que le das a un nuevo desarrollador en su primer día—excepto que Claude lo lee en cada sesión.

Dónde Colocarlo

Claude Code usa un sistema jerárquico para cargar archivos CLAUDE.md:

Raíz del proyecto (lo más común):

Tu-proyecto/CLAUDE.md

Inclúyelo en git. Compártelo con tu equipo. Esto es lo que querrás el 90% del tiempo.

Ubicación alternativa:

Tu-proyecto/.claude/CLAUDE.md

Mismo efecto, pero mantiene la raíz de tu proyecto más limpia.

Global (aplica a todos los proyectos):

~/.claude/CLAUDE.md

Preferencias personales que te acompañan a todas partes. Ideal para cosas como "prefiero tabs sobre espacios" o "siempre usar TypeScript en modo strict."

Variante local (en gitignore):

Tu-proyecto/CLAUDE.local.md

Ajustes personales que no quieres commitear. Claves de API, configuraciones experimentales, o ese estilo de código controversial que tu equipo no comparte.

Soporte para Monorepos

Aquí es donde se pone inteligente. En un monorepo, podrías tener:

Monorepo/
├── CLAUDE.md              # Se carga para todo
├── apps/
│   ├── web/
│   │   └── CLAUDE.md      # Se carga al trabajar en web/
│   └── api/
│       └── CLAUDE.md      # Se carga al trabajar en api/
└── packages/
    └── shared/
        └── CLAUDE.md      # Se carga al trabajar en shared/

Cuando ejecutas claude desde monorepo/apps/web, se cargan tanto el CLAUDE.md de la raíz como el específico de web. Los archivos CLAUDE.md de subdirectorios se incorporan bajo demanda cuando trabajas con archivos en esos directorios.

Qué Poner en CLAUDE.md

Un buen CLAUDE.md responde tres preguntas:

QUÉ — ¿Qué es este proyecto? ¿Cuál es el stack tecnológico? ¿Cuál es la estructura de directorios?

POR QUÉ — ¿Cuál es el propósito? ¿Qué problema resuelve? ¿Cuáles son los conceptos clave del negocio?

CÓMO — ¿Cómo se trabaja en él? ¿Qué comandos ejecutan los tests? ¿Cuál es el proceso de despliegue? ¿Cómo se verifican los cambios?

Una Plantilla Práctica

# Nombre del Proyecto

Una frase: qué es esto y qué hace.

## Stack Tecnológico

- Next.js 14 (App Router)
- TypeScript (strict mode)
- Tailwind CSS
- Prisma + PostgreSQL
- Jest para testing

## Estructura de Directorios

Src/
├── app/           # Rutas de Next.js
├── components/    # Componentes UI reutilizables
├── lib/           # Utilidades y helpers
├── services/      # Lógica de negocio
└── types/         # Interfaces TypeScript

## Comandos

- `bun dev` - Iniciar servidor de desarrollo (puerto 3000)
- `bun test` - Ejecutar tests de Jest
- `bun lint` - Verificación de ESLint
- `bun build` - Build de producción
- `bunx prisma studio` - GUI de base de datos

## Convenciones de Código

- Usar alias de rutas (@/components, @/lib, @/services)
- Server components por defecto, 'use client' solo cuando sea necesario
- Todas las funciones deben tener parámetros y tipos de retorno tipados
- Mantener los métodos pequeños con responsabilidad única
- Tests colocados junto a los componentes (Component.test.tsx)

## Notas Importantes

- Nunca commitear archivos .env
- Ejecutar `bunx prisma generate` después de cambios en el schema
- Las rutas API usan Zod para validación en tiempo de ejecución
- La autenticación usa NextAuth con estrategia JWT

Ejemplos Específicos por Framework

Next.js App Router:

## Convenciones Next.js

- Server Components por defecto
- Usar 'use client' solo para useState, useEffect, event handlers
- Obtención de datos: llamadas directas a BD en Server Components, SWR en Client
- Rutas API: app/api/[route]/route.ts
- Nombres de archivos: PascalCase para componentes, camelCase para utilidades

Python FastAPI:

## Convenciones FastAPI

- Type hints en todas las funciones
- Async/await para operaciones de I/O
- Modelos Pydantic v2 para validación de request/response
- Inyección de dependencias para servicios
- Alembic para migraciones: `alembic upgrade head`

Go:

## Convenciones Go

- Layout estándar del proyecto (cmd/, internal/, pkg/)
- Usar interfaces para testabilidad
- Wrapping de errores con fmt.Errorf y %w
- Tests en el mismo paquete con sufijo _test.go
- Ejecutar `go test ./...` antes de los commits

El Sistema de Imports

Los archivos CLAUDE.md pueden importar otros archivos usando la sintaxis @ruta/al/archivo. Esto mantiene tu archivo principal ligero mientras proporciona contexto completo.

# Descripción del Proyecto

Ver @README.md para la descripción detallada del proyecto.
Ver @docs/api-patterns.md para las convenciones de API.
Ver @docs/testing-guide.md para los requisitos de testing.

## Referencia Rápida

@package.json muestra los scripts npm disponibles.

Cómo funcionan los imports:

• Las rutas relativas se resuelven desde la ubicación del archivo CLAUDE.md
• Los imports pueden ser recursivos (hasta 5 niveles de profundidad)
• Los bloques de código se excluyen (los imports dentro de ``` no se evalúan)
• Los imports posteriores tienen precedencia sobre los anteriores

Organización con directorio de reglas:

Para proyectos más grandes, puedes dividir las instrucciones en múltiples archivos:

.claude/
├── CLAUDE.md           # Archivo principal
└── rules/
    ├── coding-style.md
    ├── testing.md
    ├── security.md
    └── deployment.md

Todos los archivos .md en .claude/rules/ se cargan automáticamente como memoria del proyecto.

El Atajo con la Tecla

Aquí va un tip de productividad que la mayoría pasa por alto: durante cualquier sesión de Claude Code, presiona # para añadir instrucciones a tu CLAUDE.md sobre la marcha.

¿Te encontraste repitiendo la misma instrucción? Presiona # y añádela permanentemente. Claude la recordará la próxima vez.

Settings.json: Permisos y Automatización

Más allá de CLAUDE.md, puedes configurar el comportamiento de Claude con archivos de configuración.

Ubicaciones de Archivos

~/.claude/settings.json           # Global (todos los proyectos)
.claude/settings.json             # Proyecto (commiteado a git)
.claude/settings.local.json       # Local (en gitignore)

Las configuraciones se combinan en orden de precedencia: local > proyecto > global.

Configuración de Permisos

Controla lo que Claude puede hacer sin preguntar:

{
  "permissions": {
    "allow": [
      "Read(./src/**)",
      "Read(./tests/**)",
      "Bash(git status)",
      "Bash(git diff)",
      "Bash(bun test:*)",
      "Bash(bun lint)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Bash(rm *)",
      "Bash(git push *)"
    ]
  }
}

Cómo se evalúan las reglas:

1. Las reglas de denegación se verifican primero (bloquean sin importar otras reglas)
2. Las reglas de permiso se verifican después (permiten si coinciden)
3. Todo lo demás solicita aprobación

La lista de denegación es tu límite de seguridad. Los archivos que coinciden con patrones de denegación se vuelven completamente invisibles para Claude—ni siquiera puede ver que existen.

Hooks: Acciones Automatizadas

Los hooks ejecutan comandos en puntos específicos del ciclo de vida de Claude:

PreToolUse — Antes de que Claude use una herramienta (puede bloquear la acción)

PostToolUse — Después de que una herramienta se completa (ideal para formateadores)

SessionStart — Cuando una sesión comienza (configurar el entorno)

Notification — Cuando Claude envía notificaciones

Stop — Cuando Claude termina de responder

Ejemplo: Auto-formatear archivos Python después de ediciones:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "if [[ \"$CLAUDE_FILE_PATH\" == *.py ]]; then black \"$CLAUDE_FILE_PATH\"; fi"
          }
        ]
      }
    ]
  }
}

Ejemplo: Prevenir modificaciones a configs de producción:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write(./config/production.*)",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Blocked: Cannot modify production config' && exit 1"
          }
        ]
      }
    ]
  }
}

Tip: También puedes configurar hooks de forma interactiva usando el comando /hooks durante una sesión.

Configuración de Equipo

Para equipos, esto es lo que debes commitear vs. poner en gitignore:

Commitea estos (compartidos con el equipo):

• CLAUDE.md — Instrucciones del proyecto que todos deben seguir
• .claude/settings.json — Permisos y hooks compartidos
• .claude/rules/ — Archivos de instrucciones organizados
• .claude/commands/ — Comandos slash del equipo (cubierto en la Parte 4)

Pon en gitignore estos (personales):

• CLAUDE.local.md — Tus preferencias personales
• .claude/settings.local.json — Tus overrides locales

Esto permite que los equipos apliquen estándares mientras los individuos pueden personalizar su experiencia.

Buenas Prácticas que Realmente Importan

Mantenlo Ligero

La investigación sugiere que los LLMs de frontera pueden seguir de manera confiable alrededor de 150-200 instrucciones. Más allá de eso, la adherencia cae. Los modelos más pequeños manejan aún menos.

No hagas esto:

## Directrices Generales
- Escribe código limpio
- Sigue las mejores prácticas
- Usa nombres de variables significativos
- Mantén las funciones pequeñas

Claude ya sabe estas cosas. Estás desperdiciando espacio de instrucciones valioso en consejos genéricos.

Haz esto en su lugar:

## Reglas Específicas del Proyecto
- Las respuestas de error usan la clase ApiError de @/lib/errors
- Todas las fechas se almacenan en UTC, se muestran en la zona horaria del usuario
- Los feature flags se verifican via @/lib/features.isEnabled()
- Formato de log: [LEVEL] [SERVICE] [REQUEST_ID] message

Solo incluye lo que es único de tu proyecto.

Itera Como un Prompt

Tu CLAUDE.md es parte del prompt de Claude. Trátalo como tal.

• Prueba si las instrucciones realmente cambian el comportamiento
• Añade énfasis para reglas críticas: "IMPORTANTE:" o "DEBES"
• Elimina instrucciones que no se están siguiendo
• Pásalo por el mejorador de prompts de Claude ocasionalmente

En Anthropic, afinan los archivos CLAUDE.md de la misma forma que afinan los prompts—iteración continua basada en lo que realmente funciona.

Usa /init Como Punto de Partida

Ejecutar /init genera un CLAUDE.md analizando tu proyecto. Pero es un punto de partida, no un producto terminado.

La versión auto-generada captura patrones obvios (stack tecnológico, estructura de directorios, comandos comunes) pero se pierde el conocimiento tribal de tu equipo. Revisa lo que Claude produce y añade lo que más importa sobre cómo realmente trabajas.

Ejecuta /init de nuevo después de features importantes o refactorizaciones para capturar nuevos patrones.

Probando tu Configuración

Después de configurar tu CLAUDE.md, verifica que funcionó:

Claude

Luego pregunta:

Resume la configuración y convenciones del proyecto que entiendes.
¿Cuál es el stack tecnológico? ¿Qué comandos deberías usar para testing?

Si Claude se pierde algo importante, tu CLAUDE.md necesita trabajo.

Qué Sigue

Ahora sabes cómo configurar Claude Code para tu proyecto específico. Pero la configuración solo llega hasta cierto punto—el verdadero poder viene de extender Claude con comandos personalizados.

En la Parte 4: Comandos Personalizados, construiremos comandos slash que codifican tus flujos de trabajo en acciones reutilizables. Piensa en ello como enseñarle a Claude los atajos de tu equipo.