Domina CLAUDE.md — El Cerebro AI de Tu Proyecto

Referencias Oficiales: Overview · Memory & CLAUDE.md · Settings

Ruta del currículo

1. CLAUDE.md Mastery — memoria del repo, convenciones y arquitectura ← Estás aquí
2. Effective Prompting — comunicar tareas con claridad
3. MCP Power Tools — conectar herramientas y datos
4. Multi-Agent Workflows — delegar y paralelizar
5. Hooks Automation — guardrails automáticos en local
6. GitHub Actions Workflows — mover trabajo repetible a automatización de equipo

Documentación oficial usada en esta guía

• Qué hace CLAUDE.md y cómo funciona la memoria — Memory & CLAUDE.md files
• Settings y convenciones compartidas — Settings
• Modelo operativo general — Overview

Por Qué Importa CLAUDE.md

CLAUDE.md es el archivo más impactante que puedes crear para Claude Code. Se carga automáticamente en cada conversación, dando a Claude contexto persistente sobre tu proyecto.

Es la diferencia entre un contratista que lee el wiki de tu proyecto vs. uno que llega sin saber nada.

La Anatomía de un Buen CLAUDE.md

1. Contexto del Proyecto (Qué)

# MiProyecto
 
Dashboard de analíticas en tiempo real con Next.js 16 y PostgreSQL.
Monorepo con turborepo: apps/web, apps/api, packages/shared.

Sé factual. Claude puede leer tu código — no repitas lo obvio de package.json.

2. Convenciones (Cómo)

## Convenciones
- Nombres de archivo en kebab-case, componentes en PascalCase
- Todas las rutas API retornan `{ data, error }`
- Tests co-ubicados: `foo.ts` → `foo.test.ts`
- Commits siguen Conventional Commits

Aquí es donde más se suele invertir poco. Cada convención documentada evita que Claude adivine mal.

3. Decisiones de Arquitectura (Por Qué)

## Decisiones de Arquitectura
- Server Components por defecto, 'use client' solo para interactividad
- PostgreSQL sobre MongoDB — datos relacionales con joins complejos
- Sin ORM — SQL nativo con queries tipadas via pgtyped

El "por qué" evita que Claude sugiera alternativas que ya evaluaste y rechazaste.

4. Patrones Prohibidos (No Hacer)

## No Hacer
- No usar tipo `any` — usar `unknown` y estrechar
- No agregar barrel exports (re-exports en index.ts)
- No mockear la base de datos en tests — usar test containers

Las instrucciones negativas son poderosas. Claude respeta los límites explícitos.

Consejos Pro

Capas de CLAUDE.md

Claude Code soporta archivos CLAUDE.md en múltiples niveles:

• Raíz: Reglas globales del proyecto
• Subdirectorio: Contexto específico del dominio

project/
├── CLAUDE.md              # Convenciones globales
├── apps/
│   ├── web/CLAUDE.md      # Específico de frontend
│   └── api/CLAUDE.md      # Específico de backend

Mantenerlo Bajo 200 Líneas

Los archivos CLAUDE.md largos diluyen el contexto importante. Si necesitas más detalle, enlaza a documentos.

Ponlo en Control de Versiones

CLAUDE.md debe commitearse. Es un recurso compartido del equipo.

Errores Comunes

Patrones de Colaboración en Equipo

CLAUDE.md no es solo una herramienta de productividad personal — es infraestructura de equipo. Un CLAUDE.md bien mantenido alinea cómo todo el equipo usa la IA, de forma consistente.

Onboarding automatizado Cuando un nuevo compañero abre Claude Code el primer día, CLAUDE.md ya lleva el contexto del proyecto. Pasan menos tiempo preguntando "¿cómo está estructurado esto?" y más tiempo contribuyendo.

Salida de IA consistente en todo el equipo Sin CLAUDE.md, cada desarrollador obtiene código ligeramente diferente de Claude — uno usa tipos any, otro no. CLAUDE.md elimina esa divergencia haciendo las convenciones explícitas y compartidas.

Menos fricciones de "¿por qué Claude hizo esto?" en code review Si esa pregunta sigue apareciendo en revisiones de código, es una señal de que la convención relevante falta en CLAUDE.md. Agrégala cuando encuentres el hueco y la fricción en revisiones disminuirá con el tiempo.

Plantilla de Inicio

Si estás escribiendo tu primer CLAUDE.md, copia esto y adáptalo a tu proyecto:

# [Nombre del Proyecto]
 
[Descripción en una línea: qué hace, qué tecnologías usa]
 
## Convenciones
- [Regla de nombres de archivo, ej: kebab-case]
- [Estilo de código, ej: máx 20 líneas por función]
- [Regla de tests, ej: co-ubicar archivos de test con el fuente]
 
## Arquitectura
- [Decisión técnica clave y por qué]
- [Alternativas consideradas y rechazadas]
 
## No Hacer
- [Patrón prohibido 1]
- [Patrón prohibido 2]
 
## Comandos Frecuentes
- Test: `npm test`
- Build: `npm run build`
- Lint: `npm run lint`

Patrones Avanzados

Instrucciones Condicionales

Puedes aplicar reglas diferentes según el tipo de archivo que se está editando:

## Reglas por Contexto
- Al editar archivos de frontend: solo clases Tailwind CSS, sin estilos inline
- Al editar rutas de API: siempre incluir manejo de errores, retornar respuestas tipadas
- Al editar archivos de test: usar patrón describe/it, nombres de test descriptivos

Claude conoce la ruta del archivo en el que está trabajando, así que instrucciones condicionales como estas funcionan de forma natural.

Patrón de Referencia a Documentos Externos

No intentes poner todo en CLAUDE.md. Mantenlo liviano referenciando archivos separados para los detalles:

## Documentos de Referencia
- Principios de diseño de API: ver `docs/api-style.md`
- Esquema de base de datos: ver `docs/schema.md`
- Procedimiento de despliegue: ver `docs/deploy.md`

Claude lee esos archivos solo cuando son relevantes. Esto mantiene CLAUDE.md corto mientras el contexto detallado siempre es accesible.

Cómo Evolucionar tu CLAUDE.md con el Tiempo

No necesita ser perfecto desde el principio. Empezar pequeño es el enfoque correcto:

1. Empeza mínimo: Comienza con 5–10 líneas — una descripción de una frase y 2–3 convenciones clave
2. Agrega reglas cuando Claude se equivoca: Cuando Claude genera algo inesperado, agrega la convención que falta en ese momento
3. Revisión mensual: Una vez al mes, revisa reglas que ya son obvias o ya no son válidas — elimínalas
4. El test "¿por qué hizo Claude esto?": Si no puedes explicar el razonamiento de Claude, ese razonamiento pertenece a CLAUDE.md

El Directorio .claude/ (Para Ir Más Lejos)

Más allá de CLAUDE.md, todo el directorio .claude/ es el espacio de configuración de IA de tu proyecto:

• .claude/settings.json — configuración compartida del proyecto, commiteada en control de versiones
• .claude/settings.local.json — configuración personal y claves API (agregar a .gitignore)
• .claude/commands/ — define comandos slash personalizados para tu equipo

Por ejemplo, crea .claude/commands/review.md y cada miembro del equipo puede ejecutar /review para activar el mismo flujo de revisión de código. Si CLAUDE.md define "qué debe saber Claude", .claude/ define "cómo debe comportarse Claude".

Jerarquía de Configuración (Settings Hierarchy)

Claude Code tiene un sistema de prioridad de configuración de cuatro niveles. Los niveles superiores sobrescriben a los inferiores:

Así es como un equipo real podría usar cada nivel:

// Enterprise Policy — configurado por admins, no se puede sobrescribir
{
  "disallowedTools": ["Bash"],        // Bloquear ejecución de Bash por seguridad
  "blockedCommands": ["rm -rf"]       // Bloquear comandos peligrosos
}
 
// User Settings (~/.claude/settings.json) — preferencias personales globales
{
  "preferredModel": "sonnet",         // Modelo preferido por defecto
  "mcpServers": {
    "my-notes": { "command": "notes-mcp" }  // Servidor MCP personal
  }
}
 
// Project Settings (.claude/settings.json) — compartido, rastreado en git
{
  "allowedTools": ["Read", "Write", "Edit", "Bash"],
  "hooks": {
    "PreToolUse": [{ "matcher": "Write", "command": "lint-check.sh" }]
  }
}
 
// Local Settings (.claude/settings.local.json) — personal, gitignored
{
  "env": {
    "API_KEY": "sk-local-dev-key-..."   // Clave API personal
  }
}

La conclusión clave: pon las reglas de equipo en Project Settings y el entorno personal en Local Settings. Si tu organización tiene Enterprise Policy, las configuraciones de seguridad no pueden ser eludidas por individuos.

Comandos Slash Personalizados (Deep Dive)

El directorio .claude/commands/ te permite crear comandos slash específicos para tu equipo. El proceso es directo:

1. Crea un archivo markdown en .claude/commands/
2. El nombre del archivo se convierte en el nombre del comando (ej: review.md → /project:review)
3. El contenido del archivo se convierte en la plantilla de prompt enviada a Claude
4. Usa el placeholder $ARGUMENTS para aceptar entrada del usuario

Ejemplo 1: Code Review

<!-- .claude/commands/review.md -->
Review the following file against our team code standards: $ARGUMENTS
 
Checklist:
- Type safety: check for `any` usage
- Error handling: all async functions have try/catch
- Tests: new functions have corresponding tests
- Naming: kebab-case filenames, PascalCase components
 
Suggest fix code for each issue found.

Uso: /project:review src/api/users.ts

Ejemplo 2: Checklist de Migración de Base de Datos

<!-- .claude/commands/migrate.md -->
Review the following database migration: $ARGUMENTS
 
Verify:
- Is the migration reversible?
- Are lock times minimized for large tables?
- Are index additions using CONCURRENTLY?
- Is backward compatibility with existing data maintained?

Ejemplo 3: Verificación Pre-Despliegue

<!-- .claude/commands/deploy-check.md -->
Run pre-deployment verification:
 
1. Verify build succeeds (`npm run build`)
2. Verify tests pass (`npm test`)
3. Check for missing env vars against `.env.example`
4. Check for pending migrations
5. Verify CHANGELOG.md is updated

Uso: /project:deploy-check

Commitea tus comandos personalizados en git. Todo el equipo tendrá acceso a los mismos flujos de trabajo.

Tips de Rendimiento para CLAUDE.md

Cada línea en CLAUDE.md consume tokens de contexto en cada conversación. Aquí te explicamos cómo gestionarlo eficientemente:

Ocultar Metadatos con Comentarios HTML

Los comentarios HTML (<!-- -->) se ocultan de la inyección automática de Claude Code pero siguen siendo visibles con la herramienta Read:

# MyProject
 
<!-- version: 2.1.0 -->
<!-- last-review: 2026-03-15 -->
<!-- agent-count: 12 -->
 
Dashboard de analíticas en tiempo real con Next.js 16.

Usa comentarios HTML para metadatos, checksums y tags de validación para ahorrar tokens.

Separar Documentos de Referencia

No pongas todo en CLAUDE.md. Mueve el contenido detallado a archivos separados y referéncialos:

## API Design
Follow our API style guide: see `docs/api-style.md`

Claude lee los archivos referenciados cuando se vuelven relevantes. Esto mantiene CLAUDE.md liviano mientras el contexto detallado sigue siendo accesible.

Conciencia del Presupuesto de Tokens

Reglas prácticas:

• Apunta a menos de 200 líneas — más allá de esto, empieza la dilución de contexto
• No repitas lo que ya está en package.json o tsconfig.json
• Revisa CLAUDE.md regularmente y elimina reglas que ya no sean necesarias
• Mantén solo instrucciones accionables — mueve las explicaciones de fondo a documentos separados

Estrategia CLAUDE.md para Monorepos

En un monorepo, una jerarquía de CLAUDE.md de tres niveles funciona de manera poderosa:

monorepo/
├── CLAUDE.md                    # Nivel 1: Convenciones de toda la org
├── apps/
│   ├── web/
│   │   └── CLAUDE.md            # Nivel 2: Reglas de frontend
│   ├── api/
│   │   └── CLAUDE.md            # Nivel 2: Reglas de backend
│   └── mobile/
│       └── CLAUDE.md            # Nivel 2: Reglas de móvil
└── packages/
    ├── shared/
    │   └── CLAUDE.md            # Nivel 3: Reglas del paquete compartido
    └── ui/
        └── CLAUDE.md            # Nivel 3: Reglas del paquete UI

Nivel 1: CLAUDE.md Raíz (Toda la Org)

# MyCompany Monorepo
 
Turborepo monorepo. All packages use TypeScript strict mode.
 
## Shared Conventions
- Conventional Commits required
- PRs must include tests
- Shared types defined in `packages/shared/types/`

Nivel 2: CLAUDE.md de Aplicación

# apps/web
 
Next.js 16 frontend. Uses App Router.
 
## Rules
- Server Components by default, 'use client' only for interactivity
- Styles: Tailwind CSS only
- Deployment: Vercel (preview branches auto-deploy)

Nivel 3: CLAUDE.md de Paquete

# packages/shared
 
Shared utilities and types used across multiple apps.
 
## API Contract
- All exports must have JSDoc documentation
- Breaking changes require major version bump
- Apps consuming this package: web, api, mobile

Tip clave: Los archivos CLAUDE.md de subdirectorios solo se cargan cuando Claude trabaja en ese directorio. Pon reglas específicas del dominio en los niveles 2 y 3, y mantén las convenciones compartidas en la raíz.

Comparación con GPT Codex

GPT Codex usa AGENTS.md y codex.md para propósitos similares, con diferencias clave:

• Codex lee las instrucciones una vez al inicio de la tarea (sin recarga en vivo)
• Codex corre en sandbox — las convenciones de rutas de archivo importan más
• Ver la Guía de Instrucciones de Codex para detalles