Qué es CLAUDE.md y cómo escribir uno que de verdad funcione

Instalaste Claude Code. Ejecutaste algunos prompts. Los resultados fueron... pasables. Quizá te sugirió instalar un paquete que ya tienes. Quizá usó CommonJS cuando todo tu proyecto es ESM. Quizá escribió tests en Mocha cuando tú usas Vitest.

El problema no es Claude Code. El problema es que Claude Code no sabe nada sobre tu proyecto hasta que se lo dices.

Para eso sirve CLAUDE.md. Es un simple archivo markdown que vive en la raíz de tu repositorio y le da a Claude Code el contexto que necesita para trabajar de forma eficaz en tu base de código concreta. Piénsalo como documentación de incorporación (onboarding), no para un nuevo empleado, sino para una IA que puede leer toda tu base de código en segundos pero que aún necesita conocer las reglas no escritas.

Esta guía cubre todo: qué es CLAUDE.md, cómo estructurar uno que de verdad funcione, ejemplos reales para distintos tipos de proyecto, errores que debes evitar y cómo iterar sobre él con el tiempo.

Tabla de contenidos

• ¿Qué es CLAUDE.md?
• Por qué CLAUDE.md importa más de lo que crees
• Anatomía de un buen CLAUDE.md
• Ejemplos reales por tipo de proyecto
• Antipatrones: lo que no debes hacer
• Cómo iterar sobre tu CLAUDE.md
• Cómo ayuda SuperBuilder
• Preguntas frecuentes

¿Qué es CLAUDE.md?

CLAUDE.md es un archivo de configuración para Claude Code, el agente de programación con IA de Anthropic que se ejecuta en tu terminal. Cuando Claude Code inicia una sesión en un directorio, lee automáticamente el archivo CLAUDE.md de la raíz del proyecto para entender las convenciones, la arquitectura y las preferencias de tu base de código.

No es un formato de configuración rígido. No hay esquema, ni campos obligatorios, ni validación. Es markdown plano. Escribes cualquier contexto que ayude a un agente inteligente a trabajar de forma más eficaz en tu proyecto.

Aquí tienes un ejemplo mínimo:

# Project: Invoice API

Node.js REST API using Express + TypeScript + Prisma.

## Commands
- `npm run dev` -- start dev server on port 3001
- `npm test` -- run Vitest tests
- `npm run lint` -- ESLint + Prettier check

## Conventions
- All API routes go in `src/routes/`
- Business logic goes in `src/services/`, not in route handlers
- Use Zod for request validation
- Tests live next to source files (`*.test.ts`)

Eso son 12 líneas. Lleva dos minutos escribirlo. Y evita decenas de suposiciones equivocadas.

Dónde viven los archivos CLAUDE.md

Claude Code lee archivos CLAUDE.md desde varias ubicaciones, fusionadas por orden de precedencia:

1. ~/.claude/CLAUDE.md: preferencias globales que aplican a todos los proyectos (tu estilo de programación personal, herramientas preferidas)
2. CLAUDE.md en la raíz del proyecto: convenciones a nivel de proyecto compartidas por el equipo
3. CLAUDE.md en subdirectorios: instrucciones acotadas para partes específicas de un monorepo o base de código

Este enfoque por capas significa que puedes establecer valores por defecto globales y sobrescribirlos por proyecto o por directorio.

Por qué CLAUDE.md importa más de lo que crees

Claude Code es potente. Puede leer archivos, ejecutar comandos, editar código y llevar a cabo planes de varios pasos. Pero la potencia sin contexto da lugar a código de aspecto plausible que no da en el blanco.

Sin un CLAUDE.md, Claude Code:

• Adivinará tu stack. Puede sugerir jest cuando usas vitest, o axios cuando usas la API nativa fetch.
• Ignorará las convenciones del proyecto. ¿Tu equipo pone todas las consultas a la base de datos en una carpeta repositories/? Claude no lo sabe.
• Usará patrones equivocados. ¿Tu app de React usa exclusivamente server components? Claude podría poner "use client" por defecto en todo.
• Se saltará pasos de build. Si tu proyecto necesita npm run codegen antes de que pasen los tests, Claude no lo sabrá a menos que se lo digas.

Con un CLAUDE.md bien escrito, Claude Code se convierte en un miembro del equipo que sí leyó la documentación de incorporación. Sigue tus patrones, usa tus librerías preferidas y entiende la arquitectura.

La diferencia es enorme. Los equipos que mantienen un buen CLAUDE.md reportan que Claude Code acierta a la primera entre 2 y 3 veces más a menudo en comparación con hacer prompts sin uno.

Anatomía de un buen CLAUDE.md

Tras revisar cientos de archivos CLAUDE.md de proyectos open source y de nuestros propios usuarios, emerge una estructura clara. Los mejores archivos comparten estas secciones:

1. Descripción del proyecto (2-3 líneas)

Indica qué es el proyecto y el stack tecnológico principal. Sé específico con las versiones cuando importe.

# SuperWidget

React 19 + TypeScript dashboard app. Vite 6 for builds, Tailwind CSS v4 for styling. 
Deployed on Vercel. Monorepo managed with Turborepo.

2. Comandos clave

Enumera los comandos que un desarrollador (o una IA) necesita para construir, testear, lintar y ejecutar el proyecto. Esta es la sección de mayor valor porque evita que Claude Code adivine.

## Commands
- `pnpm dev` -- start dev server
- `pnpm test` -- run all Vitest tests
- `pnpm test:e2e` -- Playwright end-to-end tests
- `pnpm lint` -- ESLint check
- `pnpm typecheck` -- TypeScript strict check
- `pnpm db:migrate` -- run Drizzle migrations
- `pnpm db:generate` -- regenerate Drizzle schema types

3. Arquitectura y disposición de archivos

Describe dónde vive cada cosa. Esto evita que Claude Code tenga que escanear todo tu árbol para entender la estructura.

## Architecture
- `src/app/` -- Next.js App Router pages and layouts
- `src/components/` -- Shared React components
- `src/lib/` -- Utility functions and shared logic
- `src/server/` -- Server-only code (API routes, DB queries)
- `src/server/routers/` -- tRPC router definitions
- `prisma/schema.prisma` -- Database schema (PostgreSQL)

4. Convenciones de código

Aquí es donde codificas las reglas no escritas. Las cosas que un nuevo miembro del equipo aprende en su primera semana.

## Conventions
- Use named exports, not default exports
- Prefer `interface` over `type` for object shapes
- Error handling: wrap async route handlers in `tryCatch()` from `src/lib/utils`
- All database access goes through `src/server/db/` -- never import Prisma client directly in components
- CSS: use Tailwind utility classes, no custom CSS files except `globals.css`
- Imports: use `@/` path alias (maps to `src/`)

5. Restricciones importantes

Cosas que Claude Code nunca debe hacer, o que siempre debe hacer.

## Important
- NEVER modify `src/generated/` -- these files are auto-generated by `pnpm db:generate`
- NEVER use `any` type -- use `unknown` and narrow with type guards
- Always add Zod validation for new API endpoints
- Run `pnpm typecheck` after making changes to verify no type errors
- This project uses strict TypeScript -- no implicit any, no unused variables

6. Patrones de testing

Si tu configuración de testing tiene convenciones específicas, déjalas claras.

## Testing
- Unit tests use Vitest with `@testing-library/react`
- Test files: `__tests__/ComponentName.test.tsx` (co-located)
- Mock API calls with MSW (Mock Service Worker), not jest.mock
- E2E tests in `tests/e2e/` using Playwright
- Run single test: `pnpm test -- --run src/path/to/test.test.ts`

Ejemplos reales por tipo de proyecto

La teoría está bien, pero necesitas algo que puedas copiar y adaptar. Aquí tienes cinco archivos CLAUDE.md para tipos de proyecto comunes, basados en patrones de proyectos del mundo real.

Ejemplo 1: App de React + TypeScript

# TaskFlow

React 19 + TypeScript task management app. Vite 6 for bundling, Zustand for state, 
React Query v5 for server state. Deployed on Vercel.

## Commands
- `npm run dev` -- start dev server (port 5173)
- `npm test` -- Vitest in watch mode
- `npm run test:run` -- single Vitest run (CI)
- `npm run build` -- production build
- `npm run lint` -- ESLint + Prettier

## Architecture
- `src/components/` -- UI components, grouped by feature
- `src/hooks/` -- custom React hooks
- `src/stores/` -- Zustand stores (one per domain: tasks, auth, ui)
- `src/api/` -- React Query hooks wrapping API calls
- `src/lib/` -- pure utility functions
- `src/types/` -- shared TypeScript interfaces

## Conventions
- Components: function declarations, not arrow functions
- State: Zustand for client state, React Query for server state. Never use useState for data from the API.
- Styling: Tailwind CSS utility classes. No CSS modules, no styled-components.
- Routing: React Router v7 with lazy-loaded routes in `src/routes.tsx`
- All API calls go through `src/api/client.ts` (configured Axios instance with auth interceptor)

## Important
- NEVER put business logic in components -- extract to hooks or stores
- All new components must have a corresponding `.test.tsx` file
- Use `cn()` utility from `src/lib/utils.ts` for conditional class merging

Ejemplo 2: API de Python (FastAPI)

# Nexus API

FastAPI backend for the Nexus platform. Python 3.12, async-first. 
PostgreSQL + SQLAlchemy 2.0 (async). Redis for caching.

## Commands
- `uv run fastapi dev` -- start dev server with hot reload
- `uv run pytest` -- run all tests
- `uv run pytest -x -k "test_name"` -- run single test, stop on failure
- `uv run ruff check .` -- lint
- `uv run ruff format .` -- format
- `uv run alembic upgrade head` -- run migrations
- `uv run alembic revision --autogenerate -m "description"` -- create migration

## Architecture
- `app/api/routes/` -- FastAPI routers (one file per resource)
- `app/models/` -- SQLAlchemy ORM models
- `app/schemas/` -- Pydantic request/response schemas
- `app/services/` -- business logic layer
- `app/repositories/` -- database query layer (no raw SQL in services)
- `app/core/` -- config, security, dependencies
- `tests/` -- mirrors `app/` structure, uses pytest-asyncio

## Conventions
- All endpoints return Pydantic models, never raw dicts
- Use dependency injection for DB sessions: `db: AsyncSession = Depends(get_db)`
- Repository pattern: services call repositories, never use `db.execute()` directly
- Error handling: raise `HTTPException` in routes only, use custom exceptions in services
- Naming: snake_case everywhere, plural resource names in URLs (`/api/v1/users`)

## Important
- NEVER use synchronous database calls -- everything is async
- NEVER commit `.env` -- use `.env.example` for documentation
- Run `ruff check` and `ruff format` before considering any change complete
- All new endpoints need tests in `tests/api/`

Ejemplo 3: Monorepo (Turborepo)

# CloudStack

Turborepo monorepo. pnpm workspaces.

## Packages
- `apps/web` -- Next.js 15 marketing site
- `apps/dashboard` -- Next.js 15 app (App Router, RSC-first)
- `apps/api` -- Hono.js API server on Cloudflare Workers
- `packages/ui` -- shared component library (React + Tailwind)
- `packages/db` -- Drizzle ORM schema + migrations (shared)
- `packages/auth` -- authentication utilities (shared)
- `packages/config-eslint` -- ESLint config
- `packages/config-ts` -- shared tsconfig bases

## Commands (from root)
- `pnpm dev` -- start all apps in parallel
- `pnpm build` -- build all packages and apps
- `pnpm lint` -- lint all packages
- `pnpm test` -- test all packages
- `pnpm dev --filter=dashboard` -- start only dashboard

## Conventions
- Import shared packages with `@cloudstack/ui`, `@cloudstack/db`, etc.
- New shared code goes in `packages/`, not duplicated across apps
- Each package has its own `tsconfig.json` extending `packages/config-ts`
- Database changes: modify `packages/db/schema.ts`, then `pnpm db:generate`

## Important
- NEVER install dependencies in the root -- always in the specific package
- NEVER import between apps directly -- extract shared code to a package
- When modifying `packages/ui`, verify both `apps/web` and `apps/dashboard` still build
- The `apps/api` package uses Hono, NOT Express or Fastify

Ejemplo 4: Herramienta CLI (Go)

# bolt CLI

Command-line tool for managing cloud deployments. Go 1.23, Cobra for commands, 
Bubble Tea for TUI components. Distributed as single binary.

## Commands
- `go build -o bolt ./cmd/bolt` -- build binary
- `go test ./...` -- run all tests
- `go test -v ./internal/deploy/...` -- test specific package
- `golangci-lint run` -- lint
- `goreleaser release --snapshot` -- test release build

## Architecture
- `cmd/bolt/` -- entrypoint, Cobra root command
- `cmd/bolt/commands/` -- one file per CLI command (deploy, logs, config, etc.)
- `internal/` -- core logic, not exported
- `internal/deploy/` -- deployment orchestration
- `internal/config/` -- YAML config file parsing
- `internal/api/` -- HTTP client for cloud API
- `pkg/` -- reusable packages safe for external import

## Conventions
- Errors: wrap with `fmt.Errorf("action: %w", err)` for context chains
- CLI output: use `internal/ui` package (wraps lipgloss styles), never raw fmt.Println for user-facing output
- Config: Viper for config file + env vars, Cobra for flags
- HTTP: standard library `net/http`, no third-party HTTP clients
- Tests: table-driven tests, use `testify/assert` for assertions

## Important
- NEVER use `os.Exit()` outside of `cmd/bolt/main.go`
- All user-facing strings must go through the `ui` package for consistent formatting
- Support both `--json` flag (machine output) and human-readable output for all commands
- Minimum Go version is 1.23 -- use range-over-func and other 1.23 features freely

Ejemplo 5: App móvil (React Native)

# FitTrack

React Native 0.76 fitness tracking app. Expo SDK 52, TypeScript.
iOS and Android. Expo Router for navigation.

## Commands
- `npx expo start` -- start Expo dev server
- `npx expo run:ios` -- run on iOS simulator
- `npx expo run:android` -- run on Android emulator
- `npm test` -- Jest + React Native Testing Library
- `npm run lint` -- ESLint
- `npm run typecheck` -- tsc --noEmit
- `eas build --profile preview` -- create preview build

## Architecture
- `app/` -- Expo Router file-based routes
- `app/(tabs)/` -- bottom tab navigator screens
- `app/(auth)/` -- authentication flow screens
- `components/` -- shared components
- `hooks/` -- custom hooks
- `stores/` -- Zustand stores
- `services/` -- API layer (wrapping fetch, auth headers)
- `constants/` -- theme colors, sizes, config values

## Conventions
- Navigation: Expo Router file-based routing. Never use React Navigation directly.
- Styling: StyleSheet.create, organized by component. No NativeWind in this project.
- Platform checks: use `Platform.select()` not `Platform.OS === 'ios'`
- Animations: Reanimated 3 for performance-critical, LayoutAnimation for simple cases
- Storage: MMKV for key-value, SQLite (expo-sqlite) for structured data

## Important
- NEVER use `AsyncStorage` -- we use MMKV for all local storage
- Test on BOTH iOS and Android before marking changes complete
- All health data access goes through `services/health.ts` (wraps HealthKit/Health Connect)
- Expo Config Plugin modifications go in `plugins/` directory

Antipatrones: lo que no debes hacer

Un CLAUDE.md malo puede ser peor que no tener ninguno, porque le da a Claude Code un contexto seguro pero equivocado. Aquí están los errores más comunes.

1. La novela (demasiado largo)

Si tu CLAUDE.md supera las 500 líneas, es demasiado largo. Claude Code procesa el archivo completo al inicio de cada sesión, y un archivo excesivamente largo diluye la información importante con ruido.

Mal:

## Complete API Reference
### GET /users
Returns a list of users. Supports pagination via `page` and `limit` query params...
[400 more lines of API documentation]

Mejor: enlaza a la documentación en su lugar.

## API
- API docs: `docs/api.md`
- OpenAPI spec: `api/openapi.yaml`
- All endpoints follow REST conventions documented in `docs/api-conventions.md`

2. La vaguedad ondeante (demasiado genérico)

Las instrucciones que podrían aplicar a cualquier proyecto son espacio desperdiciado.

Mal:

- Write clean code
- Follow best practices
- Add comments where needed
- Make sure tests pass

Mejor: sé específico para tu proyecto.

- Functions over 30 lines should be broken up
- No abbreviations in variable names (use `transaction`, not `txn`)
- JSDoc on all exported functions
- Tests must cover error paths, not just happy paths

3. La contradicción

Cuando tu CLAUDE.md dice una cosa pero tu base de código hace otra, Claude Code se confunde.

Mal:

## Conventions
- Use Tailwind CSS for all styling

...pero la mitad de la base de código usa CSS Modules.

Mejor: reconoce la realidad.

## Conventions
- New components: use Tailwind CSS for styling
- Legacy components in `src/components/v1/` use CSS Modules -- migrate when touching these files

4. El artefacto obsoleto

Un CLAUDE.md escrito hace seis meses que hace referencia a paquetes ya eliminados, a comandos de build que cambiaron o a una arquitectura que fue reestructurada.

Solución: trata CLAUDE.md como documentación viva. Actualízalo cuando cambies tu stack o tus convenciones.

5. La inyección de prompt

Algunos desarrolladores intentan usar CLAUDE.md como un campo de pruebas de prompt engineering, llenándolo de instrucciones elaboradas al estilo system prompt.

Mal:

You are an expert senior principal staff engineer with 25 years of experience.
Always think step by step. Take a deep breath before coding. 
Rate your confidence from 1-10 before every answer.

Mejor: CLAUDE.md es para el contexto del proyecto, no para instrucciones de personalidad. Céntrate en hechos sobre tu base de código.

Cómo iterar sobre tu CLAUDE.md

Tu primer CLAUDE.md no será perfecto. Y está bien. Aquí tienes un proceso práctico para mejorarlo con el tiempo.

Empieza pequeño

Comienza con solo tres secciones: descripción del proyecto, comandos clave y convenciones. Eso cubre el 80% del valor. Siempre puedes añadir más después.

Vigila las correcciones repetidas

Cada vez que te descubras corrigiendo a Claude Code con el mismo comentario ("no, usamos pnpm, no npm" o "pon eso en la capa de servicios"), añádelo a tu CLAUDE.md. Esas correcciones son tu mejor fuente sobre qué incluir.

Revisa cada mes

Programa un recordatorio en el calendario. Lee tu CLAUDE.md una vez al mes. Elimina cualquier cosa obsoleta. Añade todo lo que hayas estado repitiéndole a Claude Code en los prompts.

Pide ayuda a Claude Code

Literalmente puedes pedirle a Claude Code que sugiera mejoras para tu CLAUDE.md:

Look at this codebase and suggest additions to CLAUDE.md based on 
patterns you observe in the code.

Claude Code escaneará tu proyecto y sugerirá convenciones que detecte: patrones de import, nomenclatura de archivos, estructuras de test y más. Es una forma excelente de capturar convenciones implícitas que quizá no se te ocurriría documentar.

Usa CLAUDE.md por directorio para proyectos grandes

Si tu proyecto tiene secciones distintas con convenciones diferentes (un frontend y un backend en el mismo repo, por ejemplo), usa archivos CLAUDE.md anidados:

project/
  CLAUDE.md              # Global: monorepo structure, shared commands
  frontend/
    CLAUDE.md            # Frontend-specific: React patterns, styling rules
  backend/
    CLAUDE.md            # Backend-specific: API patterns, DB conventions
  infrastructure/
    CLAUDE.md            # Infra-specific: Terraform conventions, naming

Cómo ayuda SuperBuilder

SuperBuilder es una app de escritorio construida sobre Claude Code que facilita la gestión de tu flujo de trabajo de programación con IA, incluido tu CLAUDE.md.

Editor visual de CLAUDE.md

En lugar de editar manualmente un archivo markdown, SuperBuilder ofrece un editor estructurado que organiza tu CLAUDE.md en secciones. Añade comandos, convenciones y notas de arquitectura mediante una interfaz limpia, y SuperBuilder genera el markdown con el formato correcto.

Sugerencias de plantilla

Cuando abres un nuevo proyecto en SuperBuilder, escanea tu package.json, pyproject.toml, go.mod u otros archivos de manifiesto y sugiere una plantilla de CLAUDE.md adaptada a tu stack. Un proyecto de React + Vite + Vitest recibe sugerencias distintas a las de un proyecto de Django + PostgreSQL.

Sistema de memoria

SuperBuilder mantiene una memoria persistente entre sesiones que funciona junto con CLAUDE.md. A medida que trabajas con Claude Code a través de SuperBuilder, recuerda correcciones y preferencias, construyendo un contexto que complementa tu archivo CLAUDE.md estático. Piensa en CLAUDE.md como la documentación del equipo y en la memoria de SuperBuilder como tus notas personales.

Integración con el modo Debug

Cuando Claude Code depura un problema, SuperBuilder registra hipótesis, resultados de pruebas y hallazgos. Este contexto de depuración funciona con tu CLAUDE.md: la arquitectura y las convenciones que documentas ayudan a Claude Code a formar mejores hipótesis sobre dónde pueden estar los bugs.

Poniéndolo todo junto

Aquí tienes una lista de verificación para escribir tu CLAUDE.md hoy:

1. Indica tu stack en 2-3 líneas al principio (framework, lenguaje, librerías clave)
2. Enumera cada comando que un desarrollador necesita (dev, test, lint, build, migrate)
3. Mapea tu estructura de archivos: ¿dónde viven los componentes, servicios, tests y configuraciones?
4. Anota tus convenciones: las reglas no escritas que sigue tu equipo
5. Añade restricciones: cosas que Claude Code nunca debe hacer en tu proyecto
6. Mantenlo por debajo de 200 líneas para la mayoría de proyectos (500 como máximo para monorepos grandes)
7. Súbelo al control de versiones para que todo el equipo se beneficie
8. Revísalo cada mes y actualízalo cuando cambien tu stack o tus patrones

Los mejores archivos CLAUDE.md no son obras de arte. Son prácticos, específicos y actuales. Llevan 15 minutos escribirlos y ahorran horas de corregir código generado por IA que no encaja con tu proyecto.

Si usas Claude Code sin un CLAUDE.md, lo estás usando a una fracción de su potencial. Escribe uno hoy. Empieza pequeño, itera y observa cómo la calidad del código generado por IA en tu proyecto da un salto enorme.

Preguntas frecuentes

¿Qué longitud debería tener un CLAUDE.md?

Para la mayoría de proyectos, 50-200 líneas es lo ideal. Los monorepos podrían estirarse hasta 300-500 líneas. Si superas las 500 líneas, probablemente estés incluyendo información que pertenece a archivos de documentación separados.

¿Debería subir CLAUDE.md al control de versiones?

Sí. El CLAUDE.md a nivel de proyecto debería estar en tu repo para que cada miembro del equipo y cada entorno de CI se beneficie de él. Tu ~/.claude/CLAUDE.md personal permanece local.

¿Funciona CLAUDE.md con otras herramientas de IA?

CLAUDE.md es específico de Claude Code (y de herramientas construidas sobre él, como SuperBuilder). Sin embargo, existen convenciones similares para otras herramientas: Cursor usa .cursorrules, GitHub Copilot usa .github/copilot-instructions.md. El contenido suele ser transferible aunque el formato del archivo difiera.

¿Puedo tener varios archivos CLAUDE.md?

Sí. Claude Code lee archivos CLAUDE.md desde tu directorio home, la raíz del proyecto y cualquier subdirectorio en el que estés trabajando. Se fusionan entre sí, dando precedencia a los archivos más específicos.

¿Qué pasa si mi CLAUDE.md contradice el código?

Claude Code generalmente seguirá las instrucciones de tu CLAUDE.md, pero también lee tu código real. Si hay una contradicción, puede confundirse o pedir aclaraciones. La solución es mantener tu CLAUDE.md sincronizado con la realidad: documenta lo que existe y anota los cambios planeados por separado.

¿Debería incluir claves de API o secretos en CLAUDE.md?

Nunca. CLAUDE.md se sube al control de versiones y no debe contener secretos. Usa nombres de variables de entorno en su lugar: "Configura DATABASE_URL en .env para el desarrollo local."

¿En qué se diferencia CLAUDE.md de un README?

Un README es para desarrolladores humanos y suele cubrir instalación, uso y pautas de contribución. CLAUDE.md está optimizado para el consumo por IA: se centra en convenciones, restricciones y patrones que un agente de IA necesita para generar código correcto. Hay cierto solapamiento, pero las audiencias y los objetivos difieren.

¿Quieres sacarle más partido a Claude Code? SuperBuilder te ofrece una interfaz visual para gestionar CLAUDE.md, memoria persistente entre sesiones y potentes herramientas de depuración. Descárgalo gratis en superbuilder.sh.