CLAUDE.md: guía completa para Claude Code (2026)

CLAUDE.md es el archivo de instrucciones persistentes que Claude Code lee automáticamente al iniciarse en un proyecto. Funciona como un contexto siempre activo: todo lo que escribas en él estará disponible en cada conversación sin que tengas que repetirlo manualmente.

Cuando abres Claude Code en un directorio que contiene un archivo CLAUDE.md, su contenido se inyecta en el contexto del modelo antes de que escribas tu primer mensaje. No es un archivo de configuración técnico: es un documento en lenguaje natural donde describes cómo quieres que Claude trabaje en ese contexto específico.

La diferencia con un prompt de sistema genérico es que CLAUDE.md vive en el repositorio. Lo puedes versionar con Git, compartir con tu equipo, adaptar por rama o por subdirectorio. Es contexto como código.

Qué puede contener un CLAUDE.md

No hay un esquema fijo, pero los apartados más útiles en la práctica son:

• Stack tecnológico: lenguajes, frameworks, versiones relevantes
• Convenciones de código: estilo, naming, patrones prohibidos
• Arquitectura del proyecto: qué hace cada directorio, qué no tocar
• Flujos de trabajo: cómo correr tests, cómo hacer deploy, comandos frecuentes
• Restricciones explícitas: archivos que nunca deben modificarse, APIs externas a evitar
• Tono y formato de respuesta: si prefieres respuestas concisas, sin emojis, en un idioma concreto

Claude Code reconoce archivos CLAUDE.md en cuatro ubicaciones diferentes, con prioridades distintas. Entender la jerarquía te permite segmentar instrucciones: globales para todas tus sesiones, de proyecto para todo el repo, de módulo para subdirectorios concretos.

Cuando Claude Code carga el contexto, acumula todos los CLAUDE.md aplicables de forma aditiva, desde el global hasta el más específico. Si hay conflicto entre instrucciones, las más específicas (subdirectorio o local) prevalecen sobre las generales.

Cuándo usar cada ubicación

Un CLAUDE.md eficaz no es largo: es preciso. El objetivo es dar a Claude la información que necesita para tomar decisiones correctas sin pedírselas cada vez, usando el mínimo de tokens posibles.

Principios de escritura

Sé directo y concreto. Evita las justificaciones largas. Claude no necesita que le expliques por qué usas una convención; necesita saber cuál es. «Usa comillas dobles para strings en Python» es mejor que «En nuestro equipo hemos decidido, por razones de consistencia con el estilo PEP 8 y para facilitar la lectura, utilizar comillas dobles…»

Usa formato estructurado. Markdown con encabezados y listas funciona mejor que párrafos densos. Claude procesa instrucciones listadas de forma más fiable que instrucciones embebidas en prosa.

Prioriza lo que cambia el comportamiento por defecto. No escribas lo que Claude ya haría bien por sí solo. Escribe lo que necesitas que haga de forma diferente a su comportamiento predeterminado.

Anti-patrones comunes

Estructura recomendada

Esta estructura cubre los casos de uso más frecuentes sin exceder los 400-500 tokens:

# Contexto del proyecto
[1-2 frases: qué hace el proyecto, lenguaje principal, framework]

## Stack
- Lenguaje: TypeScript 5.3, strict mode
- Framework: Next.js 14 (App Router)
- Base de datos: PostgreSQL 15 con Prisma ORM
- Tests: Vitest + Testing Library

## Estructura de directorios
- `src/app/` — rutas y páginas (Next.js App Router)
- `src/components/` — componentes reutilizables
- `src/lib/` — utilidades y helpers
- `prisma/` — esquema y migraciones (NO modificar schema.prisma manualmente)

## Comandos frecuentes
- Tests: `npm run test`
- Dev: `npm run dev`
- Build: `npm run build`
- Migraciones: `npx prisma migrate dev`

## Convenciones
- Componentes: PascalCase, un componente por archivo
- Funciones: camelCase, arrow functions preferidas
- Imports: absolutos desde `@/` (configurado en tsconfig)
- Sin `any` explícito — usar `unknown` si no hay otro remedio

## Restricciones
- No tocar `src/lib/auth.ts` sin confirmación explícita
- No instalar dependencias nuevas sin preguntar primero
- Responde siempre en español

Los mejores CLAUDE.md son los que se leen en 30 segundos y cubren el 90% de las decisiones que Claude tomaría mal por defecto. Aquí tienes tres ejemplos reales de distintos contextos.

Ejemplo 1 — Proyecto individual (developer solo)

Para un proyecto personal de un solo desarrollador, el CLAUDE.md puede ser más informal y directo. El objetivo es eliminar las correcciones repetitivas:

# api-personal — REST API en Node.js
API REST para gestión de tareas personales. Node.js 20, Express 4, MongoDB con Mongoose.

## Lo que uso
- Node 20 + Express 4.18
- MongoDB Atlas con Mongoose 7
- Jest para tests (carpeta `__tests__`)
- ESLint + Prettier (config en `.eslintrc`)

## Cómo trabajo
- Commits en convencional commits: `feat:`, `fix:`, `refactor:`...
- Los errores van siempre a `next(err)` — no try/catch inline
- Variables de entorno en `.env.local` (nunca hardcodeadas)

## Restricciones personales
- Sin dependencias nuevas sin que yo lo pida
- No uses async/await en middleware de Express — usa callbacks
- Responde en español, conciso, sin explicar lo obvio

Ejemplo 2 — Proyecto de equipo

Cuando el CLAUDE.md lo comparte un equipo, necesita cubrir convenciones que no son obvias para alguien nuevo, incluyendo a Claude:

# plataforma-saas — SaaS B2B (equipo de 4)
Plataforma de gestión de proyectos para PYMEs. React 18 + FastAPI 0.110 + PostgreSQL 15.

## Stack completo
- Frontend: React 18, TypeScript, TailwindCSS 3, Zustand para estado global
- Backend: Python 3.12, FastAPI, SQLAlchemy 2, Alembic para migraciones
- Infra: Docker Compose en local, AWS ECS en producción
- CI/CD: GitHub Actions (ver `.github/workflows/`)

## Arquitectura — qué hay en cada sitio
- `frontend/src/features/` — módulos por dominio (auth, projects, billing)
- `backend/app/routers/` — endpoints REST organizados por recurso
- `backend/app/services/` — lógica de negocio (nunca en routers)
- `backend/app/models/` — modelos SQLAlchemy (schema fuente de verdad)

## Convenciones del equipo
- PRs: máximo 400 líneas de diff, siempre con tests
- Migraciones: NUNCA editar una migración ya aplicada — crear nueva
- API versioning: prefijo `/api/v1/` para todos los endpoints
- Logs: usar `structlog` en backend, no print()

## No tocar sin revisión del equipo
- `backend/app/core/security.py`
- `frontend/src/lib/auth/`
- Cualquier archivo en `infra/terraform/`

## Entorno local
- Iniciar: `docker compose up -d`
- Tests backend: `pytest -x --tb=short`
- Tests frontend: `npm run test:watch`

Cuando usas Claude Code con subagentes —instancias de Claude lanzadas por un agente orquestador para ejecutar tareas en paralelo— CLAUDE.md deja de ser un archivo de preferencias personales y se convierte en el único canal de instrucciones persistentes que todas las instancias comparten. Gestionar bien este aspecto es lo que separa una arquitectura multi-agente funcional de un caos de tokens.

Cómo hereda el CLAUDE.md cada subagente

En Claude Code, cuando el orquestador —el agente principal que coordina el trabajo— lanza un subagente usando la herramienta Agent, ese subagente no hereda automáticamente el contexto conversacional del orquestador. Lo que sí hereda es el acceso al sistema de archivos: si hay un CLAUDE.md en el directorio de trabajo, el subagente lo leerá.

Esto tiene una implicación directa: el CLAUDE.md del proyecto es el único canal de instrucciones persistentes que comparten orquestador y subagentes de forma garantizada.

Cada subagente leerá el CLAUDE.md de su directorio de trabajo al inicializarse. Si todos operan en el mismo directorio raíz del proyecto, los tres tendrán acceso a las mismas instrucciones base.

CLAUDE.md como memoria compartida del equipo

3 agentes que leen un CLAUDE.md claro consumen menos tokens totales que 3 agentes explorando el repositorio de forma independiente. Sin un CLAUDE.md bien escrito, cada subagente ejecuta ls, cat package.json, cat README.md y una docena de herramientas de exploración antes de hacer cualquier trabajo real.

CLAUDE.md mínimo diseñado para un subagente especializado

Si usas subdirectorios con CLAUDE.md específicos, puedes orientar a cada subagente con instrucciones que solo aplican a su dominio. Este es un ejemplo de CLAUDE.md para un subagente de análisis de código:

# Subagente: Análisis de código
Eres un subagente especializado en revisar código. Tu tarea es analizar
y reportar, no modificar archivos directamente.

## Tu rol en este equipo
- Lee los archivos que el orquestador te indique
- Devuelve un informe estructurado (JSON o Markdown según se te pida)
- No escribas archivos a menos que el orquestador lo solicite explícitamente
- No lances otros subagentes

## Qué analizar
- Complejidad ciclomática de funciones
- Dependencias circulares entre módulos
- Código duplicado evidente (bloques >10 líneas)
- Violaciones de las convenciones del proyecto (ver CLAUDE.md raíz)

## Formato de salida
Devuelve siempre un objeto JSON con esta estructura:
`{ "issues": [], "summary": "", "severity": "low|medium|high" }`

## Restricciones
- Solo tienes acceso de lectura al sistema de archivos
- Si necesitas más contexto, devuelve un needs_clarification en lugar de asumir

Estrategia de CLAUDE.md en dos niveles para Agent Teams

La arquitectura más limpia para equipos de agentes usa dos capas de CLAUDE.md:

Si Claude Code no sigue lo que escribiste en CLAUDE.md, el problema casi siempre tiene una causa concreta y una solución directa. Estas son las situaciones más frecuentes.

Cómo verificar qué CLAUDE.md está cargando

Pregúntale directamente a Claude que liste las instrucciones activas: «¿Qué instrucciones tienes en tu CLAUDE.md para este proyecto?». Si responde con instrucciones desactualizadas o no reconoce el archivo, confirma que estás en el directorio correcto y que el archivo tiene el nombre exacto CLAUDE.md (mayúsculas, sin extensión adicional).

¿Cuánto afecta CLAUDE.md al consumo de tokens?

El contenido de CLAUDE.md se añade al contexto en cada mensaje. Un CLAUDE.md de 300 palabras (~400 tokens) suma ese coste en cada turno de la conversación. Mantén tu CLAUDE.md bajo las 500 palabras salvo que haya una razón clara para más. El rendimiento adicional que obtienes de instrucciones claras compensa con creces el coste en tokens.

¿Puedo usar CLAUDE.md con la API de Anthropic, no solo con Claude Code?

El archivo CLAUDE.md es específico de Claude Code como herramienta CLI. A través de la API directa de Anthropic no existe un mecanismo nativo equivalente; tendrías que implementar tú mismo la lógica de leer el archivo e inyectarlo como system prompt. Dicho esto, el patrón de «instrucciones persistentes en system prompt» es perfectamente válido en la API — CLAUDE.md es la implementación que Claude Code hace de ese patrón.

¿El CLAUDE.md reemplaza a los prompts de sistema?

No. Son capas complementarias. En Claude Code, el CLAUDE.md actúa como un system prompt adicional de nivel de proyecto. Si construyes tus propias herramientas sobre la API de Claude, seguirás usando system prompts directamente. CLAUDE.md es la solución de Anthropic para hacer ese system prompt configurable, versionable y específico por proyecto sin tocar código.

¿Qué pasa si el CLAUDE.md tiene errores gramaticales o está escrito de forma imperfecta?

Claude tolera bien el lenguaje natural imperfecto. Un CLAUDE.md con alguna errata seguirá siendo efectivo si la intención es clara. Lo que sí importa es la precisión semántica: una instrucción ambigua produce comportamiento impredecible. La gramática perfecta es secundaria; la claridad de intención es primaria.

¿Puedo tener diferentes CLAUDE.md para diferentes ramas de Git?

Sí, y es un patrón útil en algunos escenarios. Como CLAUDE.md es un archivo del repositorio, al hacer checkout de una rama diferente, Claude Code lee el CLAUDE.md de esa rama. Puedes tener, por ejemplo, instrucciones específicas para feature/migration-v2 que indican cuáles son las convenciones nuevas vs. las antiguas.

¿Existe un tamaño máximo recomendado para CLAUDE.md?

Anthropic no impone un límite técnico más allá del tamaño máximo del contexto del modelo, pero la recomendación práctica es no superar las 500-800 palabras para un CLAUDE.md de proyecto. Por encima de eso, los rendimientos son decrecientes: el modelo procesa más tokens en cada mensaje y la probabilidad de que partes del documento se pierdan aumenta. Si necesitas documentar más, usa referencias a archivos externos: «La guía de estilo completa está en docs/style-guide.md«.