Saltar al contenido
Lección 6 de 22

Dominar CLAUDE.md

16 min read

Qué es CLAUDE.md y Por Qué Importa

Cada vez que inicias una nueva conversación con Claude Code, lee un archivo especial en tu proyecto llamado CLAUDE.md. Este archivo contiene instrucciones persistentes que moldean cada respuesta que te da la IA. Piensa en él como la memoria institucional del proyecto — la sabiduría acumulada sobre cómo funciona tu proyecto, qué convenciones seguir y qué errores evitar.

Sin CLAUDE.md, cada conversación empieza desde cero. Tienes que volver a explicar tu stack tecnológico, recordarle a la IA tus convenciones de código y corregir los mismos errores una y otra vez. Con un CLAUDE.md bien elaborado, la IA ya sabe todo esto. Es la diferencia entre trabajar con un contratista nuevo cada día y trabajar con alguien que ha estado en tu equipo durante meses.

Una analogía útil: imagina que estás incorporando a un nuevo desarrollador. No lo apuntarías al código y le dirías "averígualo." Le darías documentación sobre la arquitectura del proyecto, los estándares de codificación, el proceso de despliegue y las decisiones que dieron forma al código. CLAUDE.md es ese documento de incorporación — excepto que el nuevo desarrollador lo lee al inicio de cada sesión.

El archivo vive en la raíz del directorio de tu proyecto y está escrito en Markdown. Claude Code lo detecta y lee automáticamente antes de procesar cualquiera de tus prompts. No se requiere sintaxis especial ni configuración — solo crea el archivo, escribe tus instrucciones, y toman efecto inmediatamente.

Anatomía de un Gran CLAUDE.md

Un gran CLAUDE.md está organizado en secciones claras, cada una con un propósito específico. Desglosemos las secciones esenciales y qué pertenece en cada una.

Descripción del Proyecto

Comienza con una breve descripción de qué es el proyecto y para quién es. Esto establece el modelo mental para todo lo que sigue.

# Project Overview

SaaSKit is a subscription management platform for small businesses.
Users can create accounts, manage their subscription plans, track
usage, and handle billing. The target audience is non-technical
small business owners, so the UI prioritizes simplicity over power-user features.

Esto puede parecer obvio, pero evita que la IA haga suposiciones incorrectas. Saber que la audiencia es "propietarios de pequeños negocios no técnicos" significa que la IA favorecerá diseños simples e intuitivos sobre dashboards sobrecargados de funciones.

Stack Tecnológico

Lista cada tecnología principal en tu proyecto. Sé específico con las versiones cuando sea importante.

# Tech Stack

- **Framework:** Next.js 14 with App Router (NOT Pages Router)
- **Language:** TypeScript (strict mode)
- **Styling:** Tailwind CSS v3 with custom design tokens in tailwind.config.ts
- **Database:** PostgreSQL via Supabase
- **ORM:** Drizzle ORM (NOT Prisma)
- **Auth:** NextAuth.js v5 with email + Google providers
- **Payments:** Stripe (Checkout + Customer Portal)
- **Email:** Resend with React Email templates
- **Deployment:** Vercel
- **Testing:** Vitest + Testing Library

Nota las aclaraciones "NOT Pages Router" y "NOT Prisma." Son críticas. Los modelos de IA tienen datos de entrenamiento de muchas épocas y proyectos. Sin dirección explícita, Claude podría generar código de Pages Router o sintaxis de Prisma porque son comunes en sus datos de entrenamiento. Las negaciones explícitas previenen esto.

Decisiones de Arquitectura

Documenta la estructura de tu proyecto y el razonamiento detrás de las decisiones clave.

# Architecture

## Directory Structure
- `app/` — Next.js App Router pages and layouts
- `app/api/` — API route handlers
- `app/(auth)/` — Authentication pages (login, register, forgot-password)
- `app/(dashboard)/` — Protected dashboard pages
- `components/` — Reusable React components
- `components/ui/` — Base UI components (Button, Input, Modal, etc.)
- `components/features/` — Feature-specific components
- `lib/` — Utility functions, database queries, server-side logic
- `lib/db/` — Drizzle schema and database utilities
- `types/` — Shared TypeScript types and interfaces

## Key Patterns
- Server Components by default. Use "use client" only when needed for
  interactivity (event handlers, hooks, browser APIs).
- Data fetching happens in Server Components, never in client components.
- All forms use React Server Actions defined in `app/actions/`.
- Error boundaries at the route segment level using error.tsx files.
- Loading states using loading.tsx with skeleton components.

Esta sección es una de las partes de mayor valor de CLAUDE.md. Cuando la IA conoce la estructura de directorios y los patrones, coloca los archivos nuevos en el lugar correcto y sigue las convenciones establecidas automáticamente.

Estándares de Codificación

Define cómo debe escribirse el código en tu proyecto.

# Coding Standards

- Use `async/await` for all asynchronous code. Never use raw `.then()` chains.
- Destructure imports: `import { Button } from "@/components/ui/Button"`
- Use named exports, not default exports (except for Next.js pages).
- All components must have TypeScript props interfaces defined above the component.
- Use `cn()` utility (from lib/utils.ts) for conditional class names, not string concatenation.
- Error handling: wrap database calls in try/catch, return typed error objects, never throw in server actions.
- Prefer early returns over nested if/else blocks.
- Maximum file length: 200 lines. If a file exceeds this, extract components or utilities.

Límites y Reglas de "NO Hacer"

Esta sección previene que la IA haga cambios que rompan cosas o entren en conflicto con tus preferencias.

# Boundaries

- NEVER modify the database schema files without explicit approval.
- NEVER install new dependencies without asking first.
- NEVER use `any` type in TypeScript. Use `unknown` and type narrow instead.
- NEVER use inline styles. Always use Tailwind classes.
- NEVER create new API routes when a Server Action would work.
- Do NOT use the `pages/` directory — this project uses App Router exclusively.
- Do NOT use CSS modules, styled-components, or any CSS-in-JS library.
- Do NOT use relative imports for cross-directory references. Always use the `@/` path alias.

Estas reglas son barandillas. Previenen que la IA se desvíe a territorio que crearía deuda técnica o rompería las convenciones de tu proyecto.

Preferencias de Flujo de Trabajo

Dile a la IA cómo te gusta trabajar.

# Workflow

- Use conventional commits: feat:, fix:, refactor:, docs:, test:, chore:
- Run tests after every change: `npm run test`
- Before creating a PR, run `npm run lint && npm run typecheck && npm run test`
- Commit messages should be concise and in imperative mood: "add user dashboard" not "added user dashboard"
- Create small, focused commits — one feature or fix per commit
- Always review diffs before committing

Plantillas del Mundo Real

Veamos archivos CLAUDE.md completos para diferentes tipos de proyecto. Son puntos de partida que puedes adaptar para tus propios proyectos.

Plantilla: Aplicación SaaS con Next.js

# Project: CloudTrack — SaaS Analytics Platform

## Overview
CloudTrack is a web analytics platform for small e-commerce stores.
Users sign up, install a tracking script on their site, and view
visitor analytics in a dashboard. Freemium model with paid tiers.

## Tech Stack
- Next.js 14 (App Router, TypeScript strict)
- Tailwind CSS + shadcn/ui components
- PostgreSQL on Supabase (Drizzle ORM)
- NextAuth.js v5 (Google + email magic links)
- Stripe for billing (Checkout Sessions + Webhooks)
- Vercel for deployment
- Vitest + Playwright for testing

## Architecture
- app/(marketing)/ — Public pages (landing, pricing, docs)
- app/(dashboard)/ — Protected analytics dashboard
- app/api/track/ — Analytics event ingestion endpoint
- app/api/webhooks/ — Stripe and external webhooks
- components/charts/ — Chart components using Recharts
- lib/analytics/ — Query builders for analytics data
- lib/db/schema.ts — Single source of truth for database schema

## Standards
- Server Components by default, "use client" only for interactive elements
- All data fetching in server components using functions from lib/
- Forms use Server Actions in app/actions/
- Use cn() for conditional Tailwind classes
- Named exports everywhere except page.tsx files
- No any types — use unknown + type narrowing

## Do NOT
- Never modify lib/db/schema.ts without asking
- Never install new packages without approval
- Never use CSS modules or styled-components
- Never expose server-only code to client components
- Never store sensitive data in localStorage

## Workflow
- Conventional commits (feat:, fix:, etc.)
- Run `npm run check` before every commit (lint + typecheck + test)

Plantilla: Landing Page / Sitio de Marketing

# Project: LaunchPage — Product Landing Site

## Overview
A single-page marketing site for a mobile app launch. Goal: collect
email signups for the waitlist. Target: non-technical users.
Must be fast, beautiful, and work perfectly on mobile.

## Tech Stack
- Next.js 14 (App Router, TypeScript)
- Tailwind CSS with custom theme in tailwind.config.ts
- Framer Motion for animations
- Resend for waitlist email confirmation
- Vercel deployment
- No database — waitlist emails stored via Resend audience

## Architecture
- app/page.tsx — Single landing page with all sections
- components/sections/ — Hero, Features, Testimonials, Pricing, CTA, Footer
- components/ui/ — Button, Input, Badge, Card
- app/actions/waitlist.ts — Server Action for email signup
- public/ — Images, app screenshots, social previews

## Design
- Color palette: defined in tailwind.config.ts (do not deviate)
- Font: Inter for body, Cal Sans for headings (loaded via next/font)
- Animations: subtle, fast (200-300ms), triggered on scroll using
  Framer Motion InView
- Mobile-first: design for 375px width first, then scale up

## Do NOT
- No JavaScript-heavy features that hurt Lighthouse scores
- No cookie banners (we don't use cookies)
- No external scripts except the analytics pixel in layout.tsx
- Don't add new pages without asking — this is intentionally a single-page site

## Performance
- Target: Lighthouse 95+ on all metrics
- All images use next/image with proper width/height
- Lazy load everything below the fold

Plantilla: Servicio de API REST

# Project: OrderAPI — Order Management REST API

## Overview
A REST API that handles order processing for an e-commerce platform.
Consumed by a separate React frontend and a mobile app.
Must be reliable, well-documented, and handle high traffic.

## Tech Stack
- Node.js with Express.js (TypeScript strict)
- PostgreSQL (Drizzle ORM)
- Redis for caching and rate limiting
- Zod for request validation
- JWT authentication
- Docker for local development
- Jest for testing

## Architecture
- src/routes/ — Route definitions grouped by resource
- src/controllers/ — Request handlers (thin — call services)
- src/services/ — Business logic (where the real work happens)
- src/middleware/ — Auth, validation, error handling, rate limiting
- src/db/ — Schema, migrations, query utilities
- src/types/ — Shared TypeScript interfaces

## Standards
- Every endpoint must have Zod validation on request body/params/query
- Controllers are thin: validate input, call service, return response
- Services contain all business logic and database calls
- Return consistent error format: { error: string, code: string, status: number }
- All database queries go through the service layer, never in controllers
- Use transactions for multi-step operations

## Do NOT
- Never return raw database errors to the client
- Never skip input validation
- Never use raw SQL — always use Drizzle query builder
- Never store passwords in plain text (use bcrypt)

Plantilla: Herramienta CLI

# Project: Deployer — CLI Deployment Tool

## Overview
A command-line tool that simplifies deploying Node.js apps to various
cloud providers. Users run `deployer init` to configure, then
`deployer deploy` to ship.

## Tech Stack
- Node.js (TypeScript strict)
- Commander.js for CLI argument parsing
- Inquirer.js for interactive prompts
- chalk for colored terminal output
- ora for spinners and loading indicators
- conf for persistent configuration

## Architecture
- src/commands/ — One file per CLI command (init, deploy, status, logs)
- src/providers/ — Cloud provider adapters (vercel, aws, railway)
- src/utils/ — Shared utilities (logging, config, API clients)
- src/types/ — TypeScript interfaces

## Standards
- Every command must show a help message with --help
- Use spinners for any operation longer than 1 second
- Color coding: green for success, red for errors, yellow for warnings
- All errors must show a clear message AND a suggested fix
- Config stored in ~/.deployer/config.json

## Do NOT
- Never store credentials in the config file — use env vars or OS keychain
- Never run destructive operations without confirmation prompt
- Never swallow errors silently — always log them

Cómo Evoluciona CLAUDE.md

Tu CLAUDE.md no debería ser un documento estático. Crece y mejora a medida que tu proyecto evoluciona. Este es el ciclo de vida:

Empieza con lo mínimo. Cuando comienzas un proyecto, tu CLAUDE.md podría tener solo la descripción del proyecto y el stack tecnológico. Eso es suficiente para empezar.

Agrega reglas cuando notes correcciones repetidas. Si te encuentras diciéndole a la IA "no uses default exports" por tercera vez, esa es una regla que pertenece en CLAUDE.md. Cada corrección repetida es una señal de que falta una regla.

Elimina reglas que sean demasiado restrictivas. Si una regla está forzando a la IA a escribir código torpe o constantemente la estás anulando, la regla podría estar mal. Elimínala o suavízala.

Versiona con git. Tu CLAUDE.md es código. Rastréalo en control de versiones para que puedas ver cómo cambia con el tiempo y revertir si un cambio causa problemas.

Revísalo periódicamente. Una vez al mes, lee tu CLAUDE.md y pregúntate: ¿Esto sigue siendo preciso? ¿Hay patrones nuevos que hemos establecido y no están documentados? ¿Alguna regla está desactualizada?

Los mejores archivos CLAUDE.md son documentos vivos que reflejan el estado actual del proyecto y las preferencias del equipo. Crecen orgánicamente a partir de la experiencia real en lugar de ser escritos como un documento aspiracional el primer día.

Archivos CLAUDE.md Anidados

Claude Code soporta múltiples archivos CLAUDE.md en diferentes niveles de tu proyecto. El archivo de la raíz aplica a todo, mientras que los archivos a nivel de directorio agregan contexto para áreas específicas.

El CLAUDE.md de la raíz es el predeterminado para todo el proyecto:

project/
  CLAUDE.md           <-- Reglas de todo el proyecto
  src/
    components/
      CLAUDE.md       <-- Reglas específicas de componentes
    api/
      CLAUDE.md       <-- Reglas específicas de API

Por ejemplo, tu CLAUDE.md raíz podría decir "use Tailwind CSS for all styling," mientras que un src/api/CLAUDE.md podría agregar:

# API Directory Rules

- Every route handler must validate the request body with Zod.
- Return standard error responses using the errorResponse() helper from lib/errors.ts.
- Log all errors using the logger from lib/logger.ts.
- Rate limiting is applied globally in middleware — don't add per-route rate limiting.

Y un src/components/CLAUDE.md podría agregar:

# Component Rules

- All components in ui/ are generic, reusable building blocks. They should
  not import from features/ or contain business logic.
- All components in features/ are specific to a feature and can import from ui/.
- Every component must accept a className prop for style overrides.
- Use forwardRef for all components that render native HTML elements.

Este enfoque por capas te permite ser específico sin abarrotar el archivo raíz. La IA lee todos los archivos CLAUDE.md aplicables desde la raíz hasta el directorio de trabajo actual, aplicándolos en orden.

Errores Comunes

Incluso los desarrolladores experimentados cometen errores con su CLAUDE.md. Estos son los más comunes y cómo evitarlos.

Demasiado Genérico

# Mal Ejemplo
Write clean code. Follow best practices. Use good naming conventions.

Esto no dice nada útil. ¿Qué significa "limpio" en tu proyecto? ¿Cuáles son las buenas prácticas que sigues? ¿Qué convención de nombres usas — camelCase, PascalCase, kebab-case? Si una regla no cambia el comportamiento de la IA de manera concreta, no pertenece en CLAUDE.md.

Demasiado Restrictivo

# Mal Ejemplo
- NEVER use ternary operators
- NEVER use arrow functions for component definitions
- NEVER use spread operators
- ALWAYS write explicit return types for every function
- ALWAYS add JSDoc comments to every function

Si la IA no puede usar patrones comunes de JavaScript, escribirá código verboso y torpe. Las restricciones deben prevenir problemas reales, no imponer preferencias estilísticas que no impactan la calidad.

Información Desactualizada

# Mal Ejemplo (el proyecto migró de Pages Router hace meses)
Use the Pages Router with getServerSideProps for all data fetching.

Un CLAUDE.md desactualizado es peor que no tener CLAUDE.md porque dirige activamente a la IA en la dirección equivocada. Cuando hagas cambios arquitectónicos, actualiza CLAUDE.md inmediatamente.

Demasiado Largo

Un CLAUDE.md de 2,000 líneas diluye las reglas importantes con ruido. Los modelos de IA tienen capacidad de atención limitada — cuanto más texto necesiten procesar, menos probable es que sigan cada instrucción. Apunta a 100-300 líneas de contenido de alto valor. Si necesitas más, usa archivos CLAUDE.md anidados para distribuir la información.

El Efecto Multiplicador

He aquí por qué CLAUDE.md merece tu atención: tiene retornos compuestos.

Considera un proyecto donde interactúas con Claude Code 20 veces al día. Sin CLAUDE.md, quizás 5 de esas interacciones requieren correcciones sobre convenciones de código, elecciones de stack tecnológico o estructura del proyecto. Cada corrección toma 2-3 minutos, incluyendo el prompt de seguimiento y la espera del resultado revisado. Eso son 10-15 minutos al día gastados en correcciones que CLAUDE.md habría prevenido.

A lo largo de un mes de días laborales, eso son 3-5 horas de tiempo perdido. A lo largo de la vida de un proyecto, son días o semanas.

Pero el beneficio va más allá del ahorro de tiempo. Con un CLAUDE.md bien configurado:

  • La consistencia mejora. Cada pieza de código generado sigue los mismos patrones, haciendo el código más fácil de entender y mantener.
  • La incorporación se acelera. Si otra persona (o tu yo del futuro) comienza a trabajar en el proyecto, el CLAUDE.md los pone al día inmediatamente.
  • La calidad aumenta. Cuando la IA conoce tus patrones de manejo de errores, requisitos de seguridad y expectativas de testing, los incluye por defecto en lugar de solo cuando se le recuerda.
  • La creatividad se expande. Cuando no gastas energía mental corrigiendo convenciones, puedes enfocarte en las decisiones creativas — las funcionalidades, la UX, el producto.

Cada minuto invertido en CLAUDE.md ahorra horas de correcciones repetidas durante la vida del proyecto. Es la actividad de mayor apalancamiento en el vibe coding.

Lo Que Sigue

Con habilidades sólidas de prompting y un CLAUDE.md bien configurado, estás produciendo código más rápido que nunca. Pero la velocidad crea un nuevo riesgo: ¿qué pasa cuando algo sale mal y quieres deshacerlo?

En la próxima lección, cubriremos flujos de trabajo de Git para vibe coders — la red de seguridad que te permite experimentar sin miedo, recuperarte de errores al instante y gestionar tu proyecto como un desarrollador profesional. Git es la herramienta que hace seguro el desarrollo asistido por IA.