CLAUDE.md Profesional: El Archivo que Cambia Todo

Descripción

CLAUDE.md es un archivo Markdown que vive en la raíz de tu proyecto y le da a Claude Code contexto persistente sobre tu codebase. Es el archivo más importante que puedes crear cuando trabajas con Claude Code — la diferencia entre un agente que adivina y uno que sabe.

Cada vez que inicias una sesión, Claude Code lee CLAUDE.md automáticamente. No necesitas pedírselo, no necesitas mencionarlo, no necesitas copiarlo y pegarlo. Simplemente está ahí, en cada interacción, dándole a Claude el contexto que necesita para producir código que encaje con tu proyecto.

En esta cápsula vas a aprender qué incluir en CLAUDE.md, cómo estructurarlo para máxima efectividad, qué errores evitar, y vas a ver la diferencia dramática entre trabajar con un CLAUDE.md profesional vs trabajar sin uno. Al final, tendrás tu propio CLAUDE.md listo para usar.

Qué Es CLAUDE.md

Definición

CLAUDE.md es un archivo Markdown que:

• Ubicación: Raíz de tu proyecto (junto a package.json, requirements.txt, etc.)
• Nombre: Siempre CLAUDE.md (exactamente así, en mayúsculas)
• Formato: Markdown estándar (headers, listas, bloques de código)
• Propósito: Dar a Claude Code contexto persistente sobre el proyecto
• Cuándo se lee: Al inicio de cada sesión, automáticamente
• Tamaño ideal: Menos de 200 líneas

my-project/
├── CLAUDE.md          ← AQUÍ
├── package.json
├── src/
│   ├── index.ts
│   └── ...
├── tests/
└── ...

Cómo funciona

Cuando ejecutas claude en tu terminal, Claude Code hace lo siguiente antes de responder tu primer mensaje:

1. Busca CLAUDE.md en el directorio actual
2. Si existe, lo lee completamente
3. Lo incorpora como contexto de alta prioridad
4. Usa esa información en TODAS las respuestas de la sesión

┌─────────────────────────────────────────────────┐
│  Tu sesión de Claude Code                       │
│                                                 │
│  1. Claude lee CLAUDE.md (automático)           │
│  2. Tú envías: "Crea un endpoint"              │
│  3. Claude usa CLAUDE.md + tu mensaje           │
│     para generar código que encaje              │
│                                                 │
│  CLAUDE.md está presente en CADA interacción    │
│  No necesitas referenciarlo, siempre está ahí   │
└─────────────────────────────────────────────────┘

Lo que NO es CLAUDE.md

• ❌ No es un README (no es para humanos que visitan tu repo)
• ❌ No es documentación del proyecto (no explica cómo instalar o usar)
• ❌ No es un dump de toda tu codebase (no pegues archivos enteros)
• ❌ No es un prompt (no es un mensaje que le envías, es contexto pasivo)

CLAUDE.md es para Claude Code. Es la diferencia entre dar instrucciones en cada mensaje vs tener las reglas ya definidas.

Qué Incluir en CLAUDE.md

Las 6 secciones de un CLAUDE.md profesional

Un CLAUDE.md bien estructurado tiene estas secciones, en este orden:

1. Descripción del proyecto (1-2 frases)

# Proyecto: TaskFlow API

API REST para gestión de tareas con soporte de equipos,
prioridades, y notificaciones. Backend monolítico que
sirve al frontend React.

Sé conciso. Claude no necesita tu pitch deck — necesita saber qué hace el proyecto en una oración.

2. Tech stack (lenguajes, frameworks, versiones)

## Stack

- Runtime: Node.js 20 (LTS)
- Language: TypeScript 5.3 (strict mode)
- Framework: Express 4.18
- Database: PostgreSQL 16 (via Prisma 5.9)
- Testing: Vitest 1.2 + Supertest
- Auth: JWT (jsonwebtoken)
- Validation: Zod 3.22

Versiones importan. Claude puede generar código diferente para Prisma 4 vs Prisma 5, o Express 4 vs Express 5.

3. Arquitectura / estructura del proyecto

## Estructura

src/
├── server.ts → Entry point
├── routes/ → Definición de rutas por recurso
├── controllers/ → Lógica de request/response
├── services/ → Lógica de negocio (sin HTTP)
├── models/ → Types e interfaces
├── middleware/ → Auth, error handling, logging
├── validators/ → Schemas Zod por recurso
└── utils/ → Helpers compartidos

tests/
├── unit/ → Tests unitarios (mirror de src/)
└── integration/ → Tests de API con Supertest

Esto le dice a Claude DÓNDE poner los archivos que cree. Sin esto, adivina — y frecuentemente adivina mal.

4. Convenciones de código

## Convenciones

- Naming: camelCase para variables/funciones, PascalCase para tipos/clases
- Archivos: kebab-case (user-service.ts, no userService.ts)
- Imports: Paths relativos dentro de src/, nunca @ aliases
- Errors: Extienden AppError en src/middleware/error-handler.ts
- Async: Siempre async/await, nunca callbacks ni .then()
- Types: Interfaces para objetos, types para uniones/utilidades
- No usar `any` — usar `unknown` si el tipo no se conoce

5. Comandos

## Comandos

- Dev: `npm run dev` (nodemon + ts-node)
- Build: `npm run build` (tsc)
- Test all: `npm test` (vitest)
- Test file: `npm test -- path/to/file`
- Lint: `npm run lint` (eslint)
- Format: `npm run format` (prettier)
- Migrate: `npx prisma migrate dev`
- Seed: `npx prisma db seed`

Claude puede ejecutar estos comandos directamente. Si no los defines, tiene que adivinar o preguntarte.

6. Reglas y restricciones

## Reglas

- NO modificar src/legacy/ — código en proceso de deprecación
- NO instalar dependencias sin aprobación explícita
- Siempre ejecutar tests después de implementar cambios
- Commit messages en inglés, formato: "type: description"
- Los migrations son irreversibles — pedir confirmación antes de crear
- NO exponer errores internos al cliente — usar AppError siempre

Las reglas son quizás la sección más valiosa. Le dicen a Claude qué NO hacer — y prevenir errores es más importante que generarlos correctamente.

Qué NO Incluir

Lo que hace que CLAUDE.md sea malo:

1. Documentación extensa:

# MAL — no es un manual de usuario

## Instalación

1. Clona el repositorio
2. Ejecuta npm install
3. Crea un archivo .env con las siguientes variables:
   - DATABASE_URL: postgres://...
   - JWT_SECRET: your-secret-here
   - PORT: 3000
4. Ejecuta npx prisma migrate dev
5. Ejecuta npm run dev
   ...
   (50 líneas más de instalación)

Claude no necesita instrucciones de instalación — eso es para humanos en el README.

2. Archivos enteros pegados:

# MAL — no pegues archivos enteros

## Código del server

\```typescript
// 200 líneas de server.ts copiadas aquí
\```

Claude puede leer server.ts directamente del disco. No desperdicies espacio en CLAUDE.md repitiendo lo que ya existe en el filesystem.

3. Información obvia:

# MAL — Claude ya sabe esto

## Qué es TypeScript

TypeScript es un superconjunto de JavaScript que agrega tipos estáticos...

## Cómo funciona Express

Express es un framework web para Node.js que permite crear servidores HTTP...

Claude fue entrenado con todo el conocimiento público sobre TypeScript y Express. No necesita que se lo expliques.

4. Contenido contradictorio:

# MAL — se contradice

## Convenciones

- Usar camelCase para nombres de archivos
  ...

## Estructura

src/user-service.ts ← kebab-case contradice la regla anterior

Contradicciones confunden a Claude. Revisa tu CLAUDE.md por coherencia.

Tamaño: La Regla de las 200 Líneas

Por qué menos de 200 líneas

CLAUDE.md se lee en cada interacción. Cada token de CLAUDE.md ocupa espacio en el context window de Claude Code. Un CLAUDE.md de 500 líneas consume ~5,000-8,000 tokens que podrían usarse para tu conversación, archivos leídos, o output de comandos.

CLAUDE.md de 50 líneas  → ~500 tokens   → impacto mínimo
CLAUDE.md de 200 líneas → ~2,000 tokens → balance ideal
CLAUDE.md de 500 líneas → ~5,000 tokens → desperdicio significativo
CLAUDE.md de 1000 líneas → ~10,000 tokens → impacto severo en contexto

La regla práctica

• Ideal: 80-150 líneas
• Máximo recomendado: 200 líneas
• Si supera 200: Revisa qué puedes eliminar, resumir, o mover a subdirectorios

Cómo reducir

Si tu CLAUDE.md es demasiado largo:

1. Elimina lo obvio — Claude sabe qué es React, no se lo expliques
2. Combina reglas relacionadas — en vez de 5 reglas de naming, resume en 1-2
3. Usa @path imports — referencia archivos externos en vez de copiar contenido
4. Mueve reglas a .claude/rules/ — instrucciones modulares que cargan bajo demanda
5. Quita documentación — si es para humanos, va en README, no en CLAUDE.md
6. Sé conciso — "TypeScript strict, no any" es mejor que un párrafo explicando por qué

Crear tu Primer CLAUDE.md con /init

No tienes que escribir CLAUDE.md desde cero. Claude Code puede generarlo automáticamente:

cd your-project
claude
> /init

Claude analiza tu codebase y genera un CLAUDE.md con:

• Comandos de build y test que descubre
• Estructura del proyecto
• Convenciones que detecta

Si ya existe un CLAUDE.md, /init sugiere mejoras en vez de sobreescribirlo.

Úsalo como punto de partida. Después refina manualmente con instrucciones que Claude no puede descubrir por sí solo: decisiones de arquitectura, reglas de negocio, y preferencias del equipo.

Imports con @path

CLAUDE.md puede importar archivos adicionales usando la sintaxis @path:

# Mi Proyecto

Ver @README para overview del proyecto y @package.json para comandos npm.

## Instrucciones adicionales

- Git workflow: @docs/git-instructions.md
- API guidelines: @docs/api-design.md

Los imports funcionan con paths relativos (relativo al archivo que los contiene) y absolutos. Los archivos importados se expanden y cargan en contexto al inicio de la sesión, igual que el contenido inline de CLAUDE.md.

Cuándo usar imports

¿El contenido cambia frecuentemente y es mantenido por otro archivo?
→ Usa @path (ej: @README, @package.json)

¿El contenido es estable e instrucciones para Claude?
→ Ponlo directamente en CLAUDE.md

¿El contenido es demasiado largo para CLAUDE.md?
→ Muévelo a un archivo separado y usa @path

Imports personales

Para instrucciones personales que no van en el repo (tu configuración de IDE, tus shortcuts), puedes usar un import desde tu home directory en CLAUDE.local.md:

# Preferencias personales

- @~/.claude/my-project-instructions.md

Reglas Organizadas con .claude/rules/

Para proyectos grandes, puedes organizar instrucciones en archivos separados dentro de .claude/rules/. Cada archivo cubre un tema específico:

my-project/
├── .claude/
│   ├── CLAUDE.md           # Instrucciones principales del proyecto
│   └── rules/
│       ├── code-style.md   # Estilo de código
│       ├── testing.md      # Convenciones de testing
│       └── security.md     # Requisitos de seguridad

Reglas con scope por path

Las reglas pueden ser condicionales — solo aplican cuando Claude trabaja con archivos que matchean un patrón:

---
paths:
  - "src/api/**/*.ts"
---

# API Development Rules

- Todos los endpoints deben incluir validación de input
- Usar el formato estándar de error response
- Incluir comentarios de documentación OpenAPI

Esta regla solo se carga cuando Claude lee archivos en src/api/. Las reglas sin paths frontmatter se cargan siempre.

Reglas vs CLAUDE.md vs Skills

CLAUDE.md        → Instrucciones generales del proyecto (siempre cargadas)
.claude/rules/   → Instrucciones modulares (cargadas siempre o por path)
Skills           → Workflows invocados bajo demanda (/my-skill)

Las reglas son ideales para equipos grandes donde diferentes subdirectorios tienen diferentes convenciones.

3 Ejemplos Comparativos

Ejemplo 1: CLAUDE.md de principiante (demasiado corto)

# Mi Proyecto

Es una API en Node.js.

Problemas:

• Claude no sabe qué framework (Express? Fastify? Hono?)
• No sabe la estructura de archivos
• No conoce convenciones
• No sabe qué comandos usar
• No sabe qué evitar

Resultado: Claude adivina todo. A veces acierta, muchas veces no.

Ejemplo 2: CLAUDE.md profesional (balance correcto)

# TaskFlow API

API REST para gestión de tareas con equipos y notificaciones.

## Stack

- Node.js 20, TypeScript 5.3 (strict)
- Express 4.18, Prisma 5.9 (PostgreSQL 16)
- Vitest + Supertest para testing
- Zod para validación, JWT para auth

## Estructura

src/
├── server.ts → Entry point
├── routes/ → Rutas por recurso
├── controllers/ → Request/response logic
├── services/ → Business logic
├── middleware/ → Auth, errors, logging
├── validators/ → Zod schemas
└── utils/ → Helpers

tests/unit/ → Mirror de src/
tests/integration/ → Tests de API

## Convenciones

- camelCase para variables, PascalCase para tipos
- Archivos en kebab-case: user-service.ts
- Async/await siempre, nunca callbacks
- Errors extienden AppError (src/middleware/error-handler.ts)
- No usar `any`, usar `unknown`
- Imports relativos, no aliases

## Comandos

- Dev: `npm run dev`
- Test: `npm test`
- Test file: `npm test -- path/to/file`
- Lint: `npm run lint`
- Build: `npm run build`
- Migrate: `npx prisma migrate dev`

## Reglas

- NO modificar src/legacy/
- NO instalar deps sin aprobación
- Ejecutar tests después de cada cambio
- Commits en inglés: "type: description"
- No exponer errores internos al cliente

~55 líneas. Conciso, completo, y profesional. Claude sabe exactamente qué hacer.

Ejemplo 3: CLAUDE.md inflado (demasiado largo)

# TaskFlow API

## Descripción completa del proyecto

TaskFlow es una aplicación de gestión de tareas diseñada para
equipos de desarrollo de software. Permite crear proyectos,
asignar tareas a miembros del equipo, establecer prioridades
y fechas límite, y recibir notificaciones...
(20 líneas más de descripción)

## Historia del proyecto

El proyecto empezó en enero 2025 como un side project...
(10 líneas de historia)

## Stack tecnológico detallado

### Node.js

Usamos Node.js versión 20 LTS porque...
(explicación de por qué Node.js)

### TypeScript

TypeScript nos da type safety y...
(explicación de por qué TypeScript)

### Express

Express es nuestro framework web porque...
(explicación de por qué Express)

### Base de datos

Usamos PostgreSQL 16 con Prisma como ORM.
Prisma nos permite definir el schema en un archivo
y generar migrations automáticamente...
(explicación completa de Prisma)

## Guía de instalación

1. Clona el repositorio
2. Instala las dependencias: npm install
3. Configura las variables de entorno:
   - DATABASE_URL=postgres://user:pass@localhost:5432/taskflow
   - JWT_SECRET=your-secret-here
   - PORT=3000
   - REDIS_URL=redis://localhost:6379
     ...
     (30 líneas más de setup)

## API Endpoints

### GET /api/users

Returns a list of users...

### POST /api/users

Creates a new user...
(documentación completa de 15 endpoints)

## Decisiones de arquitectura

### Por qué monolito y no microservicios

Decidimos usar un monolito porque...
(20 líneas de justificación arquitectural)

...

~400+ líneas. La mayoría es ruido. Claude no necesita saber la historia del proyecto ni por qué eligieron Node.js.

Problemas:

• Desperdicia ~4,000+ tokens del context window en cada interacción
• La información importante se pierde entre el ruido
• Claude tiene que filtrar para encontrar lo relevante
• El documento se vuelve difícil de mantener actualizado

Comparación: Con vs Sin CLAUDE.md

Escenario: "Crea un endpoint para buscar productos"

Sin CLAUDE.md:

Tú: "Crea un endpoint para buscar productos por nombre"

Claude: [no sabe el framework]
→ "¿Usas Express, Fastify, o algún otro framework?"

Tú: "Express"

Claude: [no sabe la estructura]
→ Crea el archivo en routes/products.js (JavaScript, no TypeScript)
→ Usa module.exports (CommonJS, no ESM)
→ Mezcla la lógica del endpoint con la validación
→ No usa Zod porque no sabe que lo tienes
→ Usa console.log para logging
→ No maneja errores con AppError

Resultado: 3-4 mensajes extra para corregir, código que no encaja

Con CLAUDE.md profesional:

Tú: "Crea un endpoint para buscar productos por nombre"

Claude: [lee CLAUDE.md automáticamente]
→ Crea src/routes/product.routes.ts (TypeScript, estructura correcta)
→ Crea src/controllers/product.controller.ts (separación correcta)
→ Crea src/services/product.service.ts (business logic separada)
→ Crea src/validators/product.validator.ts (Zod schema)
→ Usa async/await, AppError, camelCase
→ Sigue el pattern de los otros endpoints

Resultado: Código correcto en el primer intento

Impacto cuantificable

Estructura: Mejores Prácticas

Usa headers Markdown

# Proyecto

## Stack

## Estructura

## Convenciones

## Comandos

## Reglas

Los headers ayudan a Claude a navegar el documento y encontrar la información relevante rápidamente.

Sé específico, no genérico

# MAL — genérico

## Convenciones

- Usa buenas prácticas de código
- Escribe código limpio
- Sigue los estándares

# BIEN — específico

## Convenciones

- camelCase para variables, PascalCase para tipos
- Archivos en kebab-case
- No usar any, usar unknown
- Errors extienden AppError

Usa listas, no párrafos

# MAL — párrafo denso

Las convenciones del proyecto incluyen usar camelCase para
variables y funciones, PascalCase para tipos y clases,
archivos en kebab-case, imports relativos sin aliases,
async/await en vez de callbacks...

# BIEN — lista escaneable

## Convenciones

- camelCase para variables/funciones
- PascalCase para tipos/clases
- Archivos en kebab-case
- Imports relativos, no aliases
- Async/await, nunca callbacks

Comandos en formato ejecutable

# MAL — ambiguo

Para correr los tests, usa el comando de vitest con las opciones apropiadas.

# BIEN — copiar y pegar

- Test: `npm test`
- Test file: `npm test -- src/services/user.test.ts`
- Test watch: `npm test -- --watch`

Claude puede ejecutar el comando directamente si está en formato de código.

Patterns Comunes

Pattern 1: La sección de "Reglas"

Las reglas son la sección más valiosa porque previenen errores:

## Reglas

- NO modificar archivos en src/generated/ — son auto-generados
- NO hacer console.log en producción — usar el logger
- NO commitear archivos .env
- Siempre incluir tests para código nuevo
- Siempre ejecutar lint antes de commit
- Los PRs requieren al menos 1 archivo de test nuevo o modificado

Pattern 2: La sección de "Comandos"

Claude Code ejecuta comandos en tu terminal. Dale los comandos exactos:

## Comandos frecuentes

- `npm run dev` — servidor de desarrollo
- `npm test` — ejecutar toda la suite de tests
- `npm test -- --grep "auth"` — ejecutar solo tests de auth
- `npm run lint:fix` — auto-fix de linting
- `npx prisma studio` — UI para explorar la base de datos
- `docker compose up -d` — levantar servicios locales

Pattern 3: Warnings explícitos

## ⚠️ Cuidado

- La tabla `payments` tiene un trigger que envía emails.
  NO insertar datos de prueba directamente en esa tabla.
- El endpoint POST /api/deploy ejecuta un deploy real.
  NO usarlo en desarrollo.
- Los migrations de Prisma son irreversibles en producción.
  Siempre revisar antes de ejecutar `prisma migrate deploy`.

Los warnings evitan desastres. Un solo warning bien escrito puede ahorrar horas de debug.

Pitfalls y Edge Cases

Pitfall 1: CLAUDE.md demasiado largo

El error: Poner toda la documentación del proyecto en CLAUDE.md.

El impacto: Claude lee ~10,000 tokens de ruido en cada interacción. Las respuestas son más lentas, el contexto se llena más rápido, y la información importante se diluye.

La solución: Menos de 200 líneas. Si necesitas más, usa CLAUDE.md en subdirectorios para separar por área.

Pitfall 2: CLAUDE.md demasiado vago

El error:

## Stack

- JavaScript y algunas librerías

El impacto: Claude no sabe si es JavaScript o TypeScript, qué versión de Node, ni qué librerías.

La solución:

## Stack

- Node.js 20, TypeScript 5.3 (strict mode)
- Express 4.18, Prisma 5.9 (PostgreSQL 16)
- Vitest 1.2, Zod 3.22

Pitfall 3: No actualizar CLAUDE.md

El error: Crear CLAUDE.md al inicio del proyecto y nunca actualizarlo. El stack cambia, las convenciones evolucionan, pero CLAUDE.md sigue igual.

El impacto: Claude genera código con patterns obsoletos porque CLAUDE.md dice algo que ya no es cierto.

La solución: Revisa CLAUDE.md cuando hagas cambios significativos: nuevo framework, nueva convención, nueva estructura de carpetas. Incluso puedes pedirle a Claude Code que lo actualice:

Tú: "Revisa CLAUDE.md y actualízalo basándote en el estado actual
     del proyecto. ¿Hay algo desactualizado?"

Pitfall 4: Reglas contradictorias

El error:

## Convenciones

- Usar camelCase para todo

## Estructura

src/user_service.ts ← snake_case contradice la regla

El impacto: Claude no sabe qué convención seguir. A veces usa una, a veces otra.

La solución: Revisa coherencia entre secciones. Usa CLAUDE.md como fuente de verdad — si algo contradice a CLAUDE.md, el archivo real es lo que debe corregirse.

Pitfall 5: Incluir secrets o datos sensibles

El error:

## Configuración

DATABASE_URL=postgres://admin:password123@prod.db.example.com/myapp
API_KEY=sk-live-xxxxxxxxxxxxxxxxxxxxx

El impacto: Si CLAUDE.md se commitea al repo (y debería commitearse), los secrets quedan expuestos.

La solución: Nunca pongas valores reales de secrets en CLAUDE.md. Referencia variables de entorno:

## Configuración

- Requiere .env con DATABASE_URL, JWT_SECRET, STRIPE_KEY
- Template en .env.example

Ejemplo Completo Integrado

CLAUDE.md profesional para un proyecto real

Este es un CLAUDE.md completo y listo para usar. ~100 líneas, cubre todo lo necesario:

# E-Commerce API

API REST para tienda online. Maneja productos, órdenes, usuarios, y pagos.

## Stack

- Python 3.12, FastAPI 0.109
- PostgreSQL 16 (SQLAlchemy 2.0 + Alembic)
- Redis 7 (caché y sessions)
- Pytest + httpx para testing
- Pydantic v2 para validación
- Stripe para pagos

## Estructura

src/
├── main.py → Entry point, FastAPI app
├── routers/ → Endpoints por recurso
│ ├── products.py
│ ├── orders.py
│ ├── users.py
│ └── payments.py
├── services/ → Lógica de negocio
├── models/ → SQLAlchemy models
├── schemas/ → Pydantic schemas (request/response)
├── dependencies/ → FastAPI dependencies (auth, db session)
├── middleware/ → CORS, logging, error handling
└── utils/ → Helpers (pagination, slugify, etc.)

tests/
├── conftest.py → Fixtures compartidas
├── unit/ → Tests de services (sin DB)
└── integration/ → Tests de API (con DB test)

## Convenciones

- snake_case para todo (variables, funciones, archivos, endpoints)
- Type hints obligatorias en funciones públicas
- Docstrings en funciones de service layer
- Schemas Pydantic: NameCreate, NameUpdate, NameResponse
- Routers: cada recurso en su archivo, prefijo /api/v1/
- Imports absolutos: from src.services.product import ProductService
- No usar print() — usar loguru

## Comandos

- Dev: `uvicorn src.main:app --reload`
- Test all: `pytest`
- Test file: `pytest tests/unit/test_products.py`
- Test verbose: `pytest -v --tb=short`
- Lint: `ruff check src/`
- Format: `ruff format src/`
- Migrate: `alembic upgrade head`
- New migration: `alembic revision --autogenerate -m "description"`

## Reglas

- NO modificar alembic/versions/ manualmente — usar autogenerate
- NO hacer queries SQL directas — usar SQLAlchemy
- Siempre ejecutar tests después de cambios en services/
- Los endpoints siempre retornan un schema Pydantic, nunca dicts crudos
- Errores HTTP usan HTTPException con detail descriptivo
- No instalar dependencias sin aprobación
- Las migraciones requieren revisión antes de ejecutar

## Patterns actuales

- Paginación: CursorPagination en src/utils/pagination.py
- Auth: JWT con dependency get_current_user
- Caché: decorador @cached(ttl=300) para queries frecuentes
- Background tasks: FastAPI BackgroundTasks para emails y notificaciones

Ejercicios Prácticos

Ejercicio 1: Crea tu CLAUDE.md

Abre tu proyecto (o el de práctica) y crea un CLAUDE.md profesional. Incluye las 6 secciones:

1. Descripción del proyecto (1-2 frases)
2. Stack (con versiones)
3. Estructura de archivos
4. Convenciones de código
5. Comandos
6. Reglas

Apunta a 60-120 líneas. Menos de 200.

# Mi Proyecto

[Descripción de 1-2 frases]

## Stack

- [Lenguaje y versión]
- [Framework y versión]
- [Base de datos]
- [Testing framework]

## Estructura

[Estructura real de tu proyecto]

## Convenciones

- [3-5 reglas de naming/formatting]

## Comandos

- Dev: `[command]`
- Test: `[command]`
- Build: `[command]`

## Reglas

- [2-3 cosas que NO hacer]

Ejercicio 2: Revisa y mejora un CLAUDE.md malo

Analiza este CLAUDE.md y corrígelo. Identifica todos los problemas:

# My App

This is a web application built with modern technologies.
It uses JavaScript and some libraries for the frontend and backend.

## How to Install

1. Clone the repo
2. Run npm install
3. Create .env file with DATABASE_URL=postgres://admin:pass123@localhost/mydb
4. Run npm start

## About the Code

The code follows best practices and clean code principles.
We use functional programming when possible.
Variables should have meaningful names.

## Important

- Don't break anything
- Write good code
- Follow the patterns

# TaskApp

Aplicación web de gestión de tareas con autenticación.

## Stack

- Node.js 20, TypeScript 5.3
- Next.js 14 (App Router)
- PostgreSQL 16 (Prisma 5.9)
- Vitest para testing

## Estructura

src/app/ → Pages y layouts (App Router)
src/components/ → Componentes React reutilizables
src/lib/ → Utilidades y configuración
src/server/ → Server actions y API
prisma/ → Schema y migrations

## Convenciones

- camelCase para variables, PascalCase para componentes
- Archivos de componentes: PascalCase (Button.tsx)
- Server Components por defecto, "use client" solo cuando necesario
- Functional programming: map/filter/reduce, no loops imperativos

## Comandos

- Dev: `npm run dev`
- Build: `npm run build`
- Test: `npm test`
- Lint: `npm run lint`
- Migrate: `npx prisma migrate dev`

## Reglas

- NO usar `any` en TypeScript
- NO hacer fetch en Server Components — usar server actions
- NO commitear .env (usar .env.example como template)
- Ejecutar tests antes de commit

Ejercicio 3: Compara outputs con y sin CLAUDE.md

1. Sin CLAUDE.md: Renombra temporalmente tu CLAUDE.md a CLAUDE.md.bak. Abre Claude Code y pide: "Crea una función utilitaria para formatear fechas en el proyecto."
2. Con CLAUDE.md: Restaura CLAUDE.md (mv CLAUDE.md.bak CLAUDE.md). En una nueva sesión, pide exactamente lo mismo.
3. Compara: ubicación del archivo, estilo del código, imports, naming, manejo de errores.

Ejercicio 4: Optimiza un CLAUDE.md de 300 líneas

Toma este CLAUDE.md (o el tuyo si es largo) y redúcelo a menos de 200 líneas sin perder información esencial.

Técnicas a aplicar:

1. Elimina explicaciones de tecnologías que Claude ya conoce
2. Combina reglas similares en una sola línea
3. Mueve detalles de testing a /tests/CLAUDE.md
4. Quita la sección de instalación
5. Reemplaza párrafos con listas

# ANTES (10 líneas)

## TypeScript

TypeScript es un lenguaje que agrega tipos estáticos a JavaScript.
Usamos strict mode para mayor seguridad de tipos.
El compilador se configura en tsconfig.json.
...

# DESPUÉS (1 línea)

- Language: TypeScript 5.3 (strict mode)

# ANTES (5 líneas)

- Variables en camelCase
- Funciones en camelCase
- Clases en PascalCase
- Interfaces en PascalCase
- Archivos en kebab-case

# DESPUÉS (2 líneas)

- camelCase: variables, funciones. PascalCase: clases, interfaces
- Archivos: kebab-case (user-service.ts)

# ANTES en CLAUDE.md raíz (20 líneas de reglas de testing)

## Testing

- Usar describe/it pattern
- Mocks con vi.mock()
- Fixtures en conftest.py
  ...

# DESPUÉS en tests/CLAUDE.md (20 líneas)

# Y en CLAUDE.md raíz (1 línea)

- Test: `npm test` (ver tests/CLAUDE.md para convenciones)

Ejercicio 5: Pídele a Claude que revise tu CLAUDE.md

Abre Claude Code con tu CLAUDE.md ya creado y pide:

Revisa CLAUDE.md. ¿Hay algo contradictorio, redundante, o que falte?
Dame sugerencias específicas de mejora.

Evalúa las sugerencias de Claude y aplica las que tengan sentido.

Ejercicio 6: CLAUDE.md para un proyecto desde cero

Inicia un proyecto nuevo (puede ser mínimo) y crea CLAUDE.md antes de escribir código. Luego pide a Claude Code que cree la estructura inicial del proyecto basándose solo en CLAUDE.md.

Tú: "Basándote en CLAUDE.md, crea la estructura inicial del proyecto:
     carpetas, archivos base, y configuración."

Resumen

• CLAUDE.md es un archivo Markdown en la raíz de tu proyecto que da contexto persistente a Claude Code.
• Se lee automáticamente al inicio de cada sesión. No necesitas mencionarlo.
• 6 secciones esenciales: Descripción, Stack, Estructura, Convenciones, Comandos, Reglas.
• Menos de 200 líneas. Cada línea consume tokens del context window. Sé conciso.
• No incluyas: Documentación extensa, archivos enteros, explicaciones de tecnologías conocidas, secrets.
• La sección de Reglas es la más valiosa — prevenir errores es más valioso que generar código correcto.
• Sin CLAUDE.md → Claude adivina. Con CLAUDE.md → Claude sabe.
• Mantenlo actualizado. Un CLAUDE.md desactualizado es peor que no tener uno.
• Sé específico, no genérico. "camelCase para variables" es útil. "Escribe código limpio" no lo es.
• Sobrevive a /compact y /clear. Es tu contexto a prueba de todo.

Siguiente cápsula: 03 - Jerarquía de 6 niveles de memoria — cómo Claude Code combina múltiples fuentes de contexto y cuál tiene prioridad.

Recursos Adicionales

1. Claude Code Memory — Anthropic Docs — Documentación oficial de CLAUDE.md, estructura, y mejores prácticas
2. Claude Code Best Practices — Recomendaciones oficiales de Anthropic para context management
3. Claude Code Settings — Configuración de scopes y relación con CLAUDE.md
4. Claude Code CLI Reference — Referencia de comandos para gestionar memoria
5. Claude Code Overview — Arquitectura general y cómo CLAUDE.md se integra
6. Markdown Guide — Referencia de sintaxis Markdown para estructurar CLAUDE.md