El CLAUDE.md es el archivo más importante de tu proyecto cuando usas Claude Code. Aprende cómo escribirlo para que Claude sea un senior developer que ya conoce tu codebase.
Equipo Claude IA Code Español
NaN de agosto de 2026
Cada vez que inicias una sesión con Claude Code, lo primero que hace es leer el archivo CLAUDE.md en la raíz de tu proyecto. Este archivo es básicamente el "manual de onboarding" que le das al agente para que entienda tu proyecto sin necesidad de explorar todo desde cero.
Sin un CLAUDE.md bien escrito, Claude Code tiene que inferir las convenciones de tu proyecto explorando archivos. Con uno bueno, arranca como un senior developer que ya lleva semanas trabajando contigo.
Un CLAUDE.md malo:
# Mi Proyecto
Este es un proyecto de Next.js con TypeScript.Un CLAUDE.md excelente incluye todo lo que un nuevo desarrollador necesitaría saber en su primer día:
Lo primero y más importante. Claude Code los usará constantemente para correr tests, hacer builds y verificar que nada está roto después de cada cambio:
## Comandos
- `npm run dev` — Inicia el servidor de desarrollo en localhost:3000
- `npm run build` — Build de producción (TypeScript + Next.js)
- `npm test` — Ejecuta los tests con Vitest
- `npm run lint` — ESLint + TypeScript check
- `npm run db:push` — Sincroniza el schema de Prisma con la base de datosExplica cómo está organizado el código y qué patrones usar. Sé específico:
## Arquitectura
- Server Components por defecto en /app. Solo 'use client' cuando hay estado o eventos
- Los datos se obtienen en page.tsx (Server Component) y se pasan como props
- Alias @/ apunta a src/. Nunca uses rutas relativas con ../../../
- Los componentes de UI van en src/components/ui/, los de negocio en src/components/
## Convenciones de naming
- Componentes: PascalCase (UserCard.tsx)
- Hooks: camelCase con prefijo use (useUserSession.ts)
- Páginas de API: kebab-case (user-profile/route.ts)
- Variables y funciones: camelCaseEsta sección es crítica. Le dice a Claude Code qué caminos no tomar:
## NO hacer
- No instalar nuevas dependencias sin preguntar primero
- No modificar src/lib/db.ts (lógica de conexión crítica)
- No usar console.log en producción, usar el logger de src/lib/logger.ts
- No crear archivos CSS separados, todo va con TailwindCuanto más entienda Claude Code del dominio, mejores decisiones tomará:
## Contexto del negocio
SaaS de gestión de facturas para PYMEs españolas.
- Los usuarios tienen roles: admin, accountant, viewer
- Las facturas tienen estados: draft, sent, paid, cancelled
- IMPORTANTE: Los importes siempre se almacenan en céntimos (integer) para evitar errores de coma flotanteActualízalo cuando añadas nuevas convenciones, cambies dependencias importantes o descubras que Claude Code comete el mismo error repetidamente. Si lo hace dos veces, añade esa corrección al CLAUDE.md.
Irónicamente, puedes pedirle a Claude Code que genere su propio CLAUDE.md. En nuestra sección de Prompts tenemos uno específico para esto: "Generador de CLAUDE.md perfecto". Úsalo en un proyecto existente y obtendrás un archivo personalizado en minutos.
Los desarrolladores que usan Claude Code como editor principal no lo usan igual que los demás. Estos son los 10 workflows que marcan la diferencia entre usarlo bien y usarlo extraordinariamente.
La guía definitiva de instalación y configuración de Claude Code. Desde cero hasta tu primera sesión productiva, con todos los atajos y configuraciones que los usuarios avanzados usan.