Comprender la estructura de carpetas .claude/ para la configuración de Claude Code

Carpetas de configuración de proyecto y global

Hay dos directorios .claude: uno en la raíz de tu proyecto para configuración del equipo que se sube a git, y otro en tu directorio personal (~/.claude/) para preferencias personales y estado local de la máquina como el historial de sesiones.

CLAUDE.md: El manual de instrucciones

CLAUDE.md se carga en el mensaje del sistema de Claude al inicio de cada sesión y se sigue durante toda la conversación. Puedes tener CLAUDE.md en la raíz del proyecto, en ~/.claude/ para preferencias globales, o en subdirectorios para reglas específicas de carpeta.

El contenido efectivo de CLAUDE.md incluye:

• Comandos de compilación, prueba y verificación (npm run test, make build, etc.)
• Decisiones arquitectónicas clave
• Problemas no obvios
• Convenciones de importación, patrones de nomenclatura, estilos de manejo de errores
• Estructura de archivos y carpetas para los módulos principales

Mantén CLAUDE.md en menos de 200 líneas. Los archivos más largos comienzan a consumir demasiado contexto y la adherencia de Claude a las instrucciones disminuye.

Ejemplo de estructura de CLAUDE.md

# Proyecto: Acme API

Comandos
npm run dev # Iniciar servidor de desarrollo
npm run test # Ejecutar pruebas (Jest)
npm run lint # Verificación ESLint + Prettier
npm run build # Compilación de producción

Arquitectura

• API REST Express, Node 20
• PostgreSQL a través de Prisma ORM
• Todos los manejadores están en src/handlers/
• Tipos compartidos en src/types/

Convenciones

• Usa zod para validación de solicitudes en cada manejador
• La forma de retorno siempre es { data, error }
• Nunca expongas trazas de pila al cliente
• Usa el módulo de registro, no console.log

Ten cuidado con

• Las pruebas usan una base de datos local real, no simulaciones. Ejecuta npm run db:test:reset primero
• TypeScript estricto: sin importaciones no utilizadas, nunca

  Anulaciones personales con CLAUDE.local.md

  Crea CLAUDE.local.md en la raíz de tu proyecto para preferencias personales que no apliquen a todo el equipo. Claude lo lee junto con el CLAUDE.md principal, y se ignora automáticamente en git para que los ajustes personales nunca lleguen al repositorio.

  Instrucciones modulares con la carpeta rules/

  Para equipos más grandes, la carpeta rules/ proporciona instrucciones modulares que escalan mejor que un solo archivo CLAUDE.md grande.

  📖 Read the full source: HN AI Agents