🧠 CLAUDE.md — el cerebro del proyecto

O CLAUDE.md es un archivo Markdown que Claude Code lee automáticamente al inicio de cada sesión. Funciona como un system prompt persistente: todo lo que escribas allí influirá en cómo se comporta Claude dentro de tu proyecto. No es una sugerencia, es una instrucción. El modelo trata el contenido del CLAUDE.md como una directriz de alta prioridad.

Sin CLAUDE.md, Claude Code es genérico. No sabe que tu proyecto usa TypeScript, que prefieres tabs en lugar de spaces ni que hay una convención de nombres específica. Con CLAUDE.md, se convierte en especialista en tu proyecto desde el primer mensaje. La diferencia es drástica: en vez de preguntar "¿qué framework usas?", ya lo sabe y actúa en consecuencia.

El mecanismo es sencillo: cuando inicias una sesión con claude, el agente busca archivos CLAUDE.md en tu entorno, lee el contenido y lo inyecta como parte del system prompt. Esto sucede antes de que escribas cualquier cosa. Es como un briefing automático que el agente recibe cada mañana antes de empezar a trabajar.

Claude Code lee CLAUDE.md de tres lugares, en este orden: ~/.claude/CLAUDE.md (global, se aplica a todos los proyectos), ./CLAUDE.md (en la raíz del proyecto) y subdir/CLAUDE.md (en cualquier subcarpeta donde estés trabajando). Los tres se leen y concatenan para formar el contexto completo.

La cascada funciona por adición: el contenido de cada nivel se suma al anterior. El global define preferencias personales («nunca uses em dashes», «prefiere TypeScript»). El del proyecto define el stack y las convenciones. El de carpeta define reglas específicas de esa área del código. Los tres juntos forman el contexto completo que recibe el agente.

Esta jerarquía es poderosa porque permite separar responsabilidades. Defines tus preferencias personales una vez (global) y ya no tienes que repetirlas en cada proyecto. Cada proyecto define sus propias reglas sin interferir con los demás. Y las subcarpetas especiales (como src/api/) pueden tener reglas adicionales sin recargar el CLAUDE.md principal.

~/.claude/CLAUDE.md          ← global (todas as sessoes)
./CLAUDE.md                  ← projeto (raiz do repo)
./src/CLAUDE.md              ← pasta (regras do /src)
./src/api/CLAUDE.md          ← subpasta (regras do /api)

# Todos sao lidos e somados. Mais especifico refina o geral.

El formato es Markdown puro. Usa encabezados (## Stack, ## Convencoes), listas con viñetas y bloques de código para los ejemplos. El tono ideal es imperativo y concreto: «Siempre usa async/await» funciona mejor que «sería bueno considerar usar async/await cuando sea posible». El modelo obedece instrucciones directas con mucha más consistencia que sugerencias vagas.

Algunas convenciones que funcionan bien: agrupar por sección (Stack, Convenciones, Prohibiciones), usar negrita para destacar, incluir ejemplos de código cuando la regla sea técnica y mantener el archivo entre 50 y 200 líneas. Además, el beneficio disminuye y gastas contexto innecesariamente. Cada línea del CLAUDE.md consume tokens de la ventana de contexto.

Evita redundancias con lo que el modelo ya sabe. No hace falta decir "escribe código legible" o "usa buenas prácticas". Claude ya lo hace de forma predeterminada. El CLAUDE.md debe contener lo que diferente en este proyecto o en tu forma de trabajar. Si el patrón funciona, no gastes líneas en él.

# Projeto XYZ

## Stack
- Next.js 14 (App Router)
- TypeScript strict
- Tailwind CSS
- Prisma ORM + PostgreSQL

## Convencoes
- Arquivos: kebab-case (user-profile.ts)
- Componentes: PascalCase (UserProfile.tsx)
- NUNCA usar `any`. Sempre tipar explicitamente.

## Proibicoes
- NUNCA deletar arquivos sem confirmar
- NUNCA commitar .env ou secrets
- NUNCA usar console.log em producao

Los tipos de instrucciones que más influyen son: stack y tecnologías ("este proyecto usa Next.js 14 con App Router"), convenciones de código ("nombres de archivo en kebab-case"), prohibiciones explícitas ("NUNCA elimines archivos sin confirmar"), y estándares del proyecto ("usa el pattern de service layer en src/services/").

Las prohibiciones en mayúsculas (NUNCA, SIEMPRE) se respetan con más consistencia. Esto no es superstición: el modelo da más peso a los tokens enfáticos. Úsalas con moderación para que no se conviertan en ruido, pero no dudes en usarlas cuando la regla sea crítica. Un «NUNCA uses sudo» bien ubicado puede prevenir accidentes graves.

Otra categoría poderosa: instrucciones de workflow. "Siempre ejecuta pruebas antes de hacer commit", "pide confirmación antes de eliminar", "usa git commit con mensajes en portugués". Estas instrucciones moldean cómo trabaja el agente, no solo lo que produce. Transforman a Claude de una herramienta pasiva en un colega de trabajo disciplinado.

## Stack
- Next.js 14 (App Router)
- TypeScript strict
- Tailwind CSS
- Prisma ORM + PostgreSQL

## Convencoes
- Arquivos: kebab-case (user-profile.ts)
- Componentes: PascalCase (UserProfile.tsx)
- NUNCA usar any. Sempre tipar explicitamente.
- Testes: colocar em __tests__/ ao lado do arquivo.

## Padroes
- API routes usam o pattern em src/app/api/[resource]/route.ts
- Validacao com Zod em todo input de API

## Workflow
- Sempre rode npm test antes de commitar
- Commit messages em portugues, imperativo

Los buenos ejemplos de CLAUDE.md comparten algunas características: son cortos (rara vez superan las 150 líneas), se centran en lo que es diferente en ese proyecto (no repiten conocimientos genéricos) e incluyen al menos una sección de prohibiciones explícitas. Estudiar ejemplos reales es el atajo más rápido para escribir un CLAUDE.md eficaz.

Un antipatrón común es el CLAUDE.md que intenta enseñarle programación al modelo ("usa buenas prácticas de código"). Claude ya conoce las buenas prácticas. Lo que necesita saber es cuáles son las tus prácticas específicas. Otro antipatrón: copiar toda la documentación del framework. El modelo ya conoce React, Next.js, etc. Di qué versión usas y cómo la usas, no qué es.

Un excelente ejemplo es el CLAUDE.md del propio repositorio de Claude Code de Anthropic. Es conciso, se centra en convenciones internas (cómo ejecutar pruebas, cómo hacer commits, qué patrones de arquitectura seguir) y tiene prohibiciones claras. Otro buen ejemplo: proyectos populares de código abierto que adoptaron esta práctica y publican sus CLAUDE.md en GitHub.

El CLAUDE.md debe ir en el git, junto con el código. Esto garantiza que cualquier persona (o agente) que clone el repo reciba el contexto automáticamente. Trátalo como un archivo de configuración: versionado, revisado y actualizado junto con el proyecto. Los pull requests que cambien el stack o las convenciones deben incluir la actualización correspondiente en CLAUDE.md.

Una rutina saludable: revisa el CLAUDE.md una vez al mes o cuando cambie algo importante en el proyecto (nueva lib, nuevo estándar, nuevo integrante del equipo). Entre revisiones, usa /memory para agregar notas rápidas que persisten sin editar el archivo directamente. /memory es el atajo; CLAUDE.md es la fuente canónica.

Un CLAUDE.md desactualizado es peor que no tener ninguno, porque el agente seguirá instrucciones incorrectas con confianza. Si eliminaste una biblioteca del proyecto pero CLAUDE.md todavía dice "usa la biblioteca X", Claude intentará usarla y fallará. Si cambiaste de ORM, actualiza CLAUDE.md. Si cambiaste las convenciones de nomenclatura, actualízalo. La regla es simple: si cambió en el código, cámbialo en CLAUDE.md.

Manutencao do CLAUDE.md:
[ ] Commitar no git junto com o codigo
[ ] Revisar mensalmente ou ao mudar stack
[ ] Remover instrucoes obsoletas imediatamente
[ ] Usar /memory pra notas rapidas entre revisoes
[ ] Incluir atualizacao em PRs que mudam convencoes
[ ] Manter entre 50-200 linhas (nao deixar inchar)