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

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, cada sesión arranca con menos contexto. Claude no sabe dónde están tus archivos, qué framework usás ni qué restricciones tiene el proyecto. Terminás repitiendo instrucciones.

Mi CLAUDE.md fue una pieza central tanto en una arquitectura multiagente que retiré como en el flujo directo que sobrevivió. En esta guía te muestro cómo estructurarlo y qué no conviene cargar ahí.

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, llegué a una estructura que funciona de forma consistente. 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). Las versiones documentan las APIs esperadas por el proyecto. El resultado generado todavía requiere verificación.

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 un mapa de entrada puede orientarlo hacia las rutas relevantes sin convertir esa ayuda en una promesa de ahorro.

```markdown
## Estructura del Proyecto

proyecto/ ├── .claude/ │ ├── skills/ # Procedimientos específicos del proyecto │ ├── rules/ # Reglas acotadas por ruta │ └── product-marketing-context.md ├── 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 └── content/ # Fuentes editoriales y activos

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


**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 evita errores previsibles y decisiones inconsistentes.

```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. El contenido debe verificarse contra el estado real del proyecto; el siguiente bloque es solo ilustrativo.

## Estado Actual (ejemplo)

### Hecho
- [x] <entregable verificado>
- [x] <guardrail verificado>

### Pendiente
- [ ] <próximo cambio aprobado>
- [ ] <integración pendiente de verificar>

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.

Qué aprendí al simplificar mi CLAUDE.md

Mi archivo llegó a acumular detalles de una organización multiagente que después retiré. La longitud no era una prueba de calidad: parte de ese contenido existía para sostener una complejidad que no tenía uso real suficiente.

Sección de capacidades operativas

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

## Qué Puedo Hacer (Capacidades Operativas)

| Pedido | Qué hago | Mecanismo |
|--------|----------|-----------|
| "Escribí un artículo de blog" | Draft + evidencia + revisión | skill editorial |
| "Cómo va el SEO?" | Consulto queries y páginas | MCP de Search Console |
| "Revisá este cambio" | Comparo diff, reglas y objetivo | trabajo directo o skill de review |
| "Actualizá el diseño" | Edito la fuente canónica y regenero | guardrail del proyecto |

Esto elimina la ambiguedad. Cuando digo "cómo va el SEO", Claude no necesita adivinar qué fuente consultar ni qué permisos tiene.

Tabla de MCPs conectados

No hace falta convertir la cantidad de conexiones en un proof point. Conviene documentar solo la necesidad, el alcance y los permisos de cada integración.

## MCPs disponibles

| Conexión | Se habilita cuando | Límite principal |
|----------|--------------------|------------------|
| Documentación | Hace falta verificar una API vigente | Solo lectura |
| Search Console | La tarea requiere datos de búsqueda | Propiedad autorizada |
| Analytics | La tarea requiere métricas del sitio | Consultas acotadas |
| Browser | Se necesita inspección visual | Sin mutaciones sin aprobación |

Tabla de servicios externos

## Servicios externos (ejemplo; verificar antes de usar)

| Servicio | Estado documentado | Detalle a registrar |
|----------|--------------------|---------------------|
| Vercel | Verificar | Proyecto, alcance y permisos |
| Google Analytics GA4 | Verificar | Propiedad y acceso autorizado |
| Google Search Console | Verificar | Propiedad y acceso autorizado |
| Resend | Verificar | Cuenta, remitente y permisos |

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 y sistemas multiagente

Si usás subagentes en Claude Code, CLAUDE.md puede aportar una base compartida. Pero que esa capacidad exista no significa que necesites una organización permanente de agentes.

En este proyecto construí un orquestador con roles, handoffs y reglas de comunicación. Unos meses después lo eliminé porque no tenía uso real suficiente para justificar su coordinación.

La retrospectiva del orquestador retirado explica por qué esa configuración no justificó su complejidad y qué criterios sobrevivieron.

Cómo evaluar el contexto compartido

Antes de delegar una tarea, el agente o subagente necesita:

El CLAUDE.md del proyecto, si sus reglas aplican.
Las instrucciones específicas del trabajo.
El contexto de dominio estrictamente necesario.

El objetivo no es cargar todo. Es entregar suficiente contexto para actuar sin trasladar ruido ni asumir información que el ejecutor no recibió.

La arquitectura no debe dominar el CLAUDE.md

Si existe una arquitectura de agentes vigente, documentá solo el mapa y las reglas que todos deben conocer. Los detalles de cada rol pertenecen a archivos específicos.

## Delegación

- Trabajo directo por defecto
- Skill para procedimientos repetibles
- Subagente solo cuando aporta aislamiento o paralelismo real
- Orquestador solo ante coordinación recurrente y medible

Esto evita que un diseño hipotético se convierta en una obligación operativa.

Comunicación entre áreas

Si un sistema realmente necesita handoffs, las reglas deben ser explícitas y trazables:

### Comunicación
- Definir quién entrega y quién recibe
- Evitar ciclos de delegación
- Acotar la profundidad
- Registrar decisiones que cambian el trabajo futuro

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 y voz de marca.
Las tareas de marketing lo leen cuando corresponde.)

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):

- Search Console: SEO, queries, indexación
- Google Analytics: tráfico y eventos
- Browser: inspección visual y pruebas

Tabla (mucho mejor):

| Conexión | Función |
|----------|---------|
| Search Console | SEO: queries, indexación |
| Google Analytics | Analytics: tráfico, eventos |
| Browser | Inspección visual y pruebas |

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.

La revisión puede ser manual o apoyarse en un guardrail, pero siempre debe contrastarse con evidencia actual. Un archivo de instrucciones no puede convertirse en fuente de verdad si nadie corrige lo que envejece.

Rutas de trabajo rápidas

Esta sección puede indicar el flujo para cada tipo de tarea sin imponer una organización de agentes:

### Rutas de Trabajo Rápidas

"Necesito investigar X"       -> fuentes primarias -> síntesis
"Necesito un artículo blog"   -> skill editorial -> draft -> aprobación
"Necesito auditar SEO"        -> Search Console + Analytics -> reporte
"Necesito cambiar código"     -> contexto local -> edición -> verificación

Cuando digo "necesito un artículo de blog", Claude ya sabe la secuencia y, sobre todo, sabe que un borrador no autoriza publicación, commit ni deploy.

Errores comunes (y cómo evitarlos)

1. CLAUDE.md sin estructura

El error más frecuente. Un archivo largo sin headings, sin secciones y 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 ya está 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 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 crece y todo queda al mismo nivel de importancia, Claude va a tener problemas para priorizar. Las secciones críticas se diluyen entre el ruido.

Solución: Poné las secciones más importantes arriba. Identificadores, stack y reglas primero. Estado actual y detalles avanzados después.

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 secciones esenciales. A partir de acá, agregá lo que necesites: tablas de servicios, referencias de arquitectura o rutas de trabajo.

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

La plantilla starter es suficiente para comenzar. Si el setup crece — más servicios, más contextos o más restricciones — el CLAUDE.md puede evolucionar.

Mi recomendación basada en la experiencia:

- **Proyecto simple:** plantilla básica con stack, comandos y reglas.
- **Proyecto medio:** secciones de servicios externos y protocolos de desarrollo.
- **Proyecto complejo:** capacidades operativas, referencias de arquitectura y rutas de trabajo, sin convertir el archivo en una wiki.

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, evaluá si corresponde agregarlo al CLAUDE.md o a una capa más específica.

---

**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 revisar qué contexto necesita tu proyecto y qué conviene sacar, [hablemos de tu proceso](/contact).