CLAUDE.md es el archivo más subestimado de Claude Code. Es la diferencia entre un Claude que te pregunta todo y un Claude que ya sabe cómo trabajás, qué tecnologías usás, y qué reglas seguir.

Si usás Claude Code sin un CLAUDE.md bien armado, estás desperdiciando la mitad de su potencial. Cada sesión empieza de cero. Claude no sabe dónde están tus archivos, qué framework usás, ni cómo te gusta trabajar. Terminás repitiendo las mismas instrucciones una y otra vez.

Mi CLAUDE.md tiene más de 400 líneas. Es la pieza central de un sistema con 20 agentes, 12 MCPs conectados y 60+ skills. En esta guía te muestro exactamente cómo armarlo, con fragmentos reales de mi configuración y una plantilla que podés copiar y adaptar hoy.

Qué es CLAUDE.md

CLAUDE.md es un archivo Markdown que ponés en la raíz de tu proyecto. Claude Code lo lee automáticamente cada vez que iniciás una sesión. Todo lo que pongas ahí se convierte en contexto persistente: instrucciones, reglas, estructura del proyecto, comandos, convenciones.

Pensalo como la memoria de largo plazo de Claude para ese proyecto específico. Sin este archivo, Claude es un asistente genérico. Con él, es un asistente que conoce tu proyecto como si hubiera trabajado en él durante meses.

Lo más importante: CLAUDE.md no es código. Es contexto. No pongas funciones ni lógica ahí. Ponés instrucciones, referencias, reglas y estructura.

Dónde va y cómo lo lee Claude

CLAUDE.md funciona en tres niveles, y los tres se acumulan (no se sobreescriben):

Nivel usuario: `~/.claude/CLAUDE.md`

Aplica a todos tus proyectos. Acá ponés preferencias globales: idioma de respuesta, estilo de comunicación, convenciones que usás siempre.

# Configuracion Global

## Idioma
Responder siempre en español, sin excepciones.

## Como trabajar
- Directo al punto, sin relleno
- Explicar el POR QUÉ de cada decisión
- Presentar alternativas cuando hay más de un camino
- Confirmar antes de cambios grandes o irreversibles

## Git
- Conventional commits: feat:, fix:, docs:, chore:
- Nunca force push sin consultar

Nivel proyecto: `proyecto/CLAUDE.md`

El más importante. Aplica a todo lo que hagas dentro de ese proyecto. Acá va el grueso de la configuración: stack, comandos, estructura, reglas.

Nivel carpeta: `proyecto/subcarpeta/CLAUDE.md`

Aplica solo cuando Claude trabaja dentro de esa subcarpeta. Útil para monorepos o proyectos con contextos muy distintos por módulo.

Cómo se acumulan

Cuando iniciás Claude Code en un proyecto, lee los tres niveles en orden:

Usuario (~/.claude/CLAUDE.md) -- tus preferencias globales
Proyecto (proyecto/CLAUDE.md) -- el contexto del proyecto
Carpeta (proyecto/subcarpeta/CLAUDE.md) -- contexto específico si existe

Los tres se suman. Si tu archivo global dice "respondé en español" y el de proyecto dice "usá Tailwind v4", Claude respeta ambas instrucciones. No se pisan.

Las 7 secciones que todo CLAUDE.md necesita

Después de iterar mi archivo durante meses, llegué a una estructura que funciona consistentemente. Estas son las 7 secciones esenciales, con fragmentos reales de mi configuración.

1. Identificadores del proyecto

Lo primero que Claude necesita saber: qué es esto, dónde está, cómo se llama.

## Identificadores del Proyecto

| Recurso | Valor |
|---------|-------|
| Dominio | `nicolasfarchica.com` |
| Email | `hello@nicolasfarchica.com` |
| Directorio web | `website/` (Next.js 16, TypeScript, Tailwind v4) |
| GitHub | `github.com/nicolasfarchica/nicolasfarchica.com` (privado) |
| Git branch | `main` |
| Deploy | Vercel (root = `website/`) |

Por qué importa: Cuando le pedís a Claude que haga un deploy o un commit, ya sabe a qué repo, qué branch y qué plataforma apuntar. No te pregunta nada.

2. Tech stack

La lista explícita de tecnologías que usa el proyecto. No asumas que Claude las va a detectar leyendo el código -- decíselo directamente.

## Tech Stack

- **Framework:** Next.js 16.1.6 (App Router) + React 19 + TypeScript
- **Styling:** Tailwind CSS v4 + Motion (animaciones)
- **i18n:** next-intl v4 (ES only, `localePrefix: "never"`)
- **Forms:** React Hook Form + Zod v4
- **Email:** Resend (formulario contacto)
- **Fuentes:** Geist Sans (headings) + Source Serif 4 (body)
- **Analytics:** Google Analytics GA4 via `next/script`
- **Seguridad:** Rate limiting (5/min/IP), honeypot, CSP

Dato clave: Incluí las versiones específicas. "Tailwind" no es lo mismo que "Tailwind v4". "Zod" no es lo mismo que "Zod v4" (que usa error.issues en vez de error.errors). Estas diferencias hacen que Claude genere código correcto en el primer intento.

3. Comandos de desarrollo

Los comandos que Claude necesita para buildear, testear y deployar. Si no los ponés acá, Claude va a tener que buscarlos en el package.json o preguntarte.

## Comandos

```bash
# Website (Next.js)
npm run dev          # localhost:3000
npm run build        # Build de producción
npm run lint         # ESLint

# Videos (Remotion)
npm run studio       # Editor visual interactivo
npm run render:intro # Renderizar BrandIntro (1920x1080)


### 4. Estructura del proyecto

Un mapa de las carpetas clave. Claude puede explorar el filesystem por su cuenta, pero si le das el mapa de entrada se ahorra docenas de operaciones de lectura y va directo a donde necesita.

```markdown
## Estructura del Proyecto

proyecto/ ├── .claude/ │ ├── agents/ # 20 agentes organizados por area │ ├── shared/ # Comunicacion entre areas │ │ ├── decisions.md # Registro de decisiones │ │ └── handoffs/ # Entregas entre areas │ └── skills/ # Skills instaladas ├── website/ # App Next.js (se despliega en Vercel) │ ├── src/app/[locale]/ # Rutas con i18n │ ├── src/components/ # UI, layout, sections │ ├── src/messages/ # Traducciones (es.json) │ └── src/data/ # Configuración del sitio ├── videos/ # Remotion (generación de video) │ ├── src/compositions/ # Composiciones de video │ └── out/ # Videos renderizados └── assets/ # Screenshots, brand resources

5. Variables de entorno

Qué variables necesita el proyecto, sin exponer los valores reales. Claude sabe qué env vars buscar y para qué sirve cada una.

## Variables de Entorno

```env
NEXT_PUBLIC_GA_ID=G-XXXXXXXXXX   # Google Analytics GA4
RESEND_API_KEY=re_xxxxx          # Emails del formulario
CONTACT_EMAIL=hello@...          # Destino emails
GHL_CONTACT_WEBHOOK_URL=...     # Go High Level - contacto
GHL_NEWSLETTER_WEBHOOK_URL=...  # Go High Level - newsletter


**Importante:** Nunca pongas los valores reales en el CLAUDE.md. Usá placeholders. Los valores van en `.env.local` (que está en `.gitignore`).

### 6. Reglas del proyecto

Las convenciones que Claude tiene que respetar siempre. Esta sección es donde evitás el 90% de los problemas.

```markdown
## Reglas del Proyecto

1. Directorio web es `website/`, no la raíz -- Vercel root = `website/`
2. Solo español (ES). next-intl con `localePrefix: "never"`
3. Git: Push a `main` solo cuando se pida explícitamente
4. Siempre leer `.claude/product-marketing-context.md` antes de escribir copy
5. Next.js 16: Usar `proxy.ts` (no `middleware.ts`)
6. Nunca usar CSS transitions en Remotion, siempre `useCurrentFrame()`

Tip: Escribí las reglas en negativo cuando sea necesario. "NO usar middleware.ts" es más claro que "preferir proxy.ts". Claude responde mejor a instrucciones explícitas sobre qué no hacer.

7. Estado actual

Qué está hecho y qué está pendiente. Esta sección es la que más se olvida de actualizar, y es de las más valiosas.

## Estado Actual

### Hecho
- [x] Website live (19 páginas, 3 APIs, 21 artículos blog)
- [x] 12 MCPs conectados
- [x] 20 agentes en 8 áreas de negocio
- [x] Pipeline CRM con 7 stages

### Pendiente
- [ ] Reconectar Vercel Git integration
- [ ] GHL + Stripe para pagos
- [ ] Activar rutina diaria (daily brief + contenido)

Por qué importa: Cuando le pedís a Claude "qué me falta hacer", puede responder con información actualizada en vez de adivinar. Y cuando le pedís que trabaje en algo, no intenta recrear algo que ya existe.

Ejemplo real: mi CLAUDE.md de 400+ líneas

Mi archivo va mucho más allá de las 7 secciones básicas. Te muestro las secciones adicionales que lo hacen realmente poderoso.

Sección de capacidades operativas

Esta tabla le dice a Claude exactamente qué puede hacer y con qué herramientas:

## Qué Puedo Hacer (Capacidades Operativas)

| Pedido | Qué hago | Herramientas |
|--------|----------|--------------|
| "Diseñá arquitectura de agentes" | Defino áreas, jefes, sub-agentes, handoffs | agents/ |
| "Configurá un MCP" | Setup completo: server, tools, testing | ops-lead → .mcp.json |
| "Escribí un artículo de blog" | MDX + SEO + schema markup | content-lead → copywriter |
| "Cómo va el SEO?" | Reporte: queries, clicks, posiciones | GSC MCP (15+ tools) |
| "Creá un workflow" | Diseño + creo + valido en n8n | n8n MCP (16 tools) |

Esto elimina la ambiguedad. Cuando digo "cómo va el SEO", Claude no me pregunta qué herramienta usar ni qué métricas quiero. Ya lo sabe.

Tabla de MCPs conectados

## MCPs Conectados (12)

| MCP | Tools | Función principal |
|-----|-------|-------------------|
| Go High Level | 36 | CRM: contactos, pipeline, calendario |
| Google Search Console | 15+ | SEO: queries, indexación, sitemaps |
| Google Analytics (GA4) | 10+ | Analytics: tráfico, conversiones |
| Meta (IG/Threads) | 57 | Social: publicar, insights, DMs |
| GitHub | 20 | Code: repos, issues, PRs |
| n8n | 16 | Automation: workflows CRUD |
| Vercel | 18 | Deploy: deployments, logs |
| Playwright | 20 | Testing: browser automation, E2E |

Tabla de servicios externos

## Servicios Externos Conectados

| Servicio | Estado | Detalle |
|----------|--------|---------|
| Vercel | Activo | Deploy + DNS |
| Google Analytics GA4 | Activo | Property 524865226 |
| Google Search Console | Activo | sc-domain:nicolasfarchica.com |
| Go High Level | Activo | 6 workflows, pipeline 7 stages |
| Resend | Activo | Emails del formulario de contacto |

El patrón es claro: tablas para información densa. Son más fáciles de escanear que listas, tanto para vos como para Claude.

CLAUDE.md para sistemas multi-agente

Si usás sub-agentes en Claude Code (con Task o Agent Teams), el CLAUDE.md se vuelve todavía más importante. Es la fuente de verdad que todos los agentes comparten.

En mi sistema, tengo 20 agentes organizados en 8 áreas de negocio. Cada agente tiene su propio archivo de instrucciones en .claude/agents/, pero todos leen el CLAUDE.md del proyecto como contexto base.

Cómo funciona en la práctica

Cuando el orquestador delega una tarea a content-lead, ese agente lee:

El CLAUDE.md del proyecto (sabe el stack, las reglas, el estado actual)
Su archivo de agente en .claude/agents/content-lead.md (sabe su rol y responsabilidades)
El contexto de marketing en .claude/product-marketing-context.md (sabe cómo hablar)

Resultado: el agente puede escribir un artículo de blog que respeta el stack técnico (MDX, Next.js), sigue las convenciones de Git, y usa la voz de marca correcta. Sin que yo le explique nada.

La arquitectura en el CLAUDE.md

Documentar la arquitectura de agentes directamente en el CLAUDE.md es clave para que Claude entienda el sistema completo:

## Arquitectura de Agentes

                    ORQUESTADOR (delegate-first)
                              |
    +---------+---------+---------+---------+
    |         |         |         |         |
 PRODUCTO  CONTENIDO  CRECIMIENTO  OPS  INTELIGENCIA
    |         |         |         |
 frontend   copywriter  seo      ghl
 backend    linkedin    cro      automation
 video      email

Esto le dice a Claude quién se encarga de qué, y evita que un agente de contenido intente hacer deploy o que un agente de operaciones escriba copy.

Comunicación entre áreas

Las reglas de comunicación van en el CLAUDE.md para que todos los agentes las respeten:

### Comunicación entre áreas
- Handoffs: `.claude/shared/handoffs/[origen]-[destino].md`
- Decisiones: `.claude/shared/decisions.md`
- No-callback rule: si Área A llama a Área B, B NO puede llamar de vuelta a A
- Max depth 3: cadenas de consultas entre áreas no superan 3 niveles

Trucos avanzados

Después de meses iterando mi CLAUDE.md, estos son los patrones que más impacto tienen.

Referenciar archivos externos

No metas todo en el CLAUDE.md. Usá referencias a archivos que Claude puede leer cuando los necesite:

**Contexto de marketing completo:** `.claude/product-marketing-context.md`
(Este archivo contiene público objetivo, diferenciación, objeciones, voz de marca.
Todas las skills de marketing lo leen automáticamente.)

Esto mantiene el CLAUDE.md enfocado en estructura y reglas, mientras el contenido detallado vive en sus propios archivos. Claude los lee bajo demanda, no los carga siempre.

Usar tablas para información densa

Las tablas son más eficientes que las listas cuando tenés información con múltiples dimensiones. Compará:

Lista (difícil de escanear):

- Go High Level: 36 tools, CRM, contactos, pipeline
- Google Search Console: 15+ tools, SEO, queries
- Google Analytics: 10+ tools, Analytics, tráfico

Tabla (mucho mejor):

| MCP | Tools | Función |
|-----|-------|---------|
| Go High Level | 36 | CRM: contactos, pipeline |
| Google Search Console | 15+ | SEO: queries, indexación |
| Google Analytics | 10+ | Analytics: tráfico |

CLAUDE.md por subcarpeta para contextos distintos

Si tenés un monorepo o un proyecto con módulos muy diferentes, podés tener un CLAUDE.md en cada subcarpeta:

proyecto/
├── CLAUDE.md              # Reglas generales del proyecto
├── website/
│   └── CLAUDE.md          # Reglas específicas de Next.js
├── videos/
│   └── CLAUDE.md          # Reglas específicas de Remotion
└── api/
    └── CLAUDE.md          # Reglas específicas del backend

Cada archivo agrega contexto cuando Claude trabaja en esa carpeta. El de videos/ puede decir "nunca usar CSS transitions, siempre useCurrentFrame()" sin contaminar el contexto del website.

Mantener el estado actual actualizado

El estado actual es la sección que más valor pierde si no la actualizás. Mi recomendación: actualizalo cada vez que terminás una sesión de trabajo significativa.

Un truco que uso: tengo un agente (improver) cuya tarea incluye verificar que el estado actual del CLAUDE.md refleje la realidad del proyecto. Si detecta inconsistencias, las reporta.

Rutas de trabajo rápidas

Esta es una de mis secciones favoritas. Le dice a Claude el flujo completo para cada tipo de tarea:

### Rutas de Trabajo Rápidas

"Necesito investigar X"          -> intel-lead -> WebSearch -> KB
"Necesito un post LinkedIn"      -> content-lead -> copywriter -> publicar
"Necesito un artículo blog"      -> content-lead -> MDX -> deploy -> indexar
"Necesito auditar SEO"           -> growth-lead -> seo-specialist -> GSC + GA4
"Necesito automatizar X"         -> ops-lead -> automation-builder -> n8n

Cuando le digo "necesito un artículo de blog", Claude ya sabe la cadena completa: qué agente coordina, qué formato usa, y los pasos hasta que está publicado e indexado.

Errores comunes (y cómo evitarlos)

1. CLAUDE.md sin estructura

El error más frecuente. Un archivo de 200 líneas sin headings, sin secciones, sin tablas. Claude puede leerlo, pero le cuesta priorizar qué es importante.

Solución: Usá headings claros (##), separadores (---), y tablas para datos densos. Claude procesa mejor la información estructurada.

2. No actualizar el estado actual

Tu CLAUDE.md dice "pendiente: configurar analytics" pero el analytics lleva tres semanas funcionando. Claude asume que todavía no está hecho e intenta configurarlo de nuevo, o te pregunta si querés hacerlo.

Solución: Actualizá la sección de estado cada vez que completás algo significativo. Mové items de "pendiente" a "hecho". Si usás checkboxes (- [x] / - [ ]), es rápido.

3. Poner código en vez de instrucciones

CLAUDE.md no es un archivo de código. No pongas funciones, componentes, ni lógica de negocio ahí. Es para contexto: qué herramientas usar, dónde están las cosas, qué reglas seguir.

Solución: Si necesitás que Claude conozca un patrón de código, ponelo en un archivo separado y referenciaalo: "ver src/lib/patterns.ts para el patrón de rate limiting".

4. No documentar las reglas de Git y deploy

"Claude me hizo push a main sin preguntar." Esto pasa cuando no le decís explícitamente que no lo haga.

Solución: Sé explícito:

## Reglas de Git
- Push a `main` SOLO cuando se pida explícitamente
- Conventional commits: feat:, fix:, docs:, chore:
- Nunca force push sin consultar

5. Duplicar información que ya está en el código

Si tu package.json ya tiene los scripts, no necesitás copiar todos los 30 scripts en el CLAUDE.md. Solo documentá los que usás frecuentemente y los que tienen alguna particularidad.

Solución: Documentá lo que Claude necesita para trabajar rápido, no todo lo que existe. Un CLAUDE.md efectivo es una guía curada, no un dump de documentación.

6. Archivo demasiado largo sin jerarquía

Si tu CLAUDE.md tiene 500 líneas y todo está al mismo nivel de importancia, Claude va a tener problemas priorizando. Las secciones que más importan (reglas, stack, comandos) se diluyen entre el ruido.

Solución: Poné las secciones más críticas arriba. Identificadores, stack y reglas primero. Estado actual, arquitectura de agentes y detalles avanzados después. Claude lee de arriba hacia abajo, y las primeras secciones tienen más peso.

7. No versionar el CLAUDE.md

Tu CLAUDE.md debería estar en Git, junto con el resto del proyecto. Si trabajás en equipo (o con agentes), todos necesitan la misma fuente de verdad.

Solución: Commiteá el CLAUDE.md como cualquier otro archivo del proyecto. Solo asegurate de no incluir secrets (API keys, tokens). Esos van en .env.local.

Plantilla starter: tu primer CLAUDE.md

Copiá esta plantilla, pegala en la raíz de tu proyecto como CLAUDE.md, y completá cada sección:

# CLAUDE.md - [Nombre del Proyecto]

## Proyecto

| Recurso | Valor |
|---------|-------|
| Nombre | [nombre] |
| Directorio | [ruta local] |
| Repositorio | [URL de GitHub] |
| Branch principal | `main` |
| Deploy | [plataforma y método] |

---

## Qué es

[Una línea describiendo el proyecto, su propósito y público objetivo.]

---

## Tech Stack

- **Framework:** [framework + versión]
- **Lenguaje:** [lenguaje + versión]
- **Styling:** [librería CSS]
- **Base de datos:** [si aplica]
- **Auth:** [si aplica]
- **Deploy:** [plataforma]

---

## Comandos

```bash
npm run dev          # Desarrollo local
npm run build        # Build de producción
npm run test         # Tests
npm run lint         # Linter

Estructura

proyecto/
├── src/
│   ├── app/          # [descripción]
│   ├── components/   # [descripción]
│   ├── lib/          # [descripción]
│   └── data/         # [descripción]
├── public/           # Assets estáticos
└── tests/            # Tests

Variables de Entorno

DATABASE_URL=...         # Base de datos
API_KEY=...              # API externa
NEXT_PUBLIC_URL=...      # URL pública

Reglas

Git: Conventional commits. Push a main solo cuando se pida
Código: [convenciones de código que uses]
Deploy: [proceso de deploy]
[Regla específica de tu proyecto]

Estado Actual

Hecho

Setup inicial
[feature completada]

Pendiente

[próximo paso]
[feature pendiente]


Esta plantilla cubre las 7 secciones esenciales. A partir de acá, agregá lo que necesites: tablas de servicios, arquitectura de agentes, rutas de trabajo, lo que tu proyecto demande.

## Cuándo escalar más allá de lo básico

La plantilla starter es suficiente para el 80% de los proyectos. Pero si tu setup crece -- más servicios, más agentes, más complejidad -- necesitás escalar el CLAUDE.md.

Mi recomendación basada en la experiencia:

- **Proyecto simple** (1 framework, sin integraciones): La plantilla starter. 50-100 líneas.
- **Proyecto medio** (múltiples APIs, CI/CD, testing): Agregá secciones de servicios externos y protocolos de desarrollo. 100-200 líneas.
- **Proyecto complejo** (multi-agente, múltiples MCPs, flujos de trabajo): El modelo completo con capacidades operativas, arquitectura de agentes, y rutas de trabajo. 200-400+ líneas.

El principio es simple: **documentá lo que Claude necesita para trabajar sin preguntarte**. Ni más, ni menos.

## Conclusión

CLAUDE.md no es un archivo de configuración más. Es la interfaz entre tu conocimiento del proyecto y la capacidad de Claude para actuar sobre él. Un CLAUDE.md bien armado transforma a Claude de un asistente genérico que te pregunta todo a un colaborador que conoce tu stack, tus reglas, tu estructura y tus prioridades.

Empezá con la plantilla starter. Iterá. Cada vez que Claude te pregunta algo que debería saber, agregalo al CLAUDE.md. En pocas semanas vas a tener un archivo que hace que cada sesión sea productiva desde el minuto uno.

---

**Artículos relacionados:**

- [Cómo Uso Claude Code para mi Consultoría de IA](/blog/como-uso-claude-code-consultoria)
- [Subagentes en Claude Code: Guía Completa](/blog/subagentes-claude-code-guia-completa)
- [7 Funciones Ocultas de Claude Code](/blog/funciones-claude-code-ocultas)
- [Claude Code en 2026: Todas las Novedades](/blog/claude-code-novedades-2026)

---

Si querés que te ayude a diseñar el CLAUDE.md perfecto para tu proyecto, [agendá una llamada introductoria](/agendar) y lo armamos juntos.

CLAUDE.md: El Archivo Más Importante de tu Proyecto con Claude Code (Guía Definitiva)