$ man how-to/how-to-write-claude-md

CLAUDE.md es un archivo Markdown plano que Claude Code lee al inicio de cada sesion. Es el documento de onboarding para tu compañero de equipo AI. Todo en este archivo se convierte en parte de la ventana de contexto - Claude lo ve antes de que escribas tu primer mensaje. Sin un CLAUDE.md, Claude Code opera de forma generica. No conoce la estructura de tu proyecto, tus convenciones de codigo, tus comandos de build ni tu proceso de despliegue. Con un CLAUDE.md, opera como un compañero de equipo que ha leido toda tu documentacion. El archivo vive en la raiz de tu repositorio. Se versiona con tu codigo. Cuando el proyecto evoluciona, el CLAUDE.md evoluciona con el. Cuando un nuevo desarrollador se une, obtiene Claude Code preconfigurado para tu proyecto automaticamente.

PATTERN

Claude Code carga CLAUDE.md desde multiples ubicaciones, fusionandolos en orden: 1. ~/.claude/CLAUDE.md - Configuracion global. Aplica a cada proyecto. Pon tus preferencias personales aqui: configuracion del editor, estilo de commits, preferencias de comunicacion. 2. /project-root/CLAUDE.md - Configuracion del proyecto. Aplica a este repositorio. Pon instrucciones especificas del proyecto aqui: comandos de build, estandares de codigo, resumen de arquitectura. 3. /project-root/src/CLAUDE.md - Configuracion de directorio. Aplica cuando se trabaja en el directorio src/. Pon instrucciones especificas del modulo aqui: convenciones de API para el modulo de API, patrones de componentes para el modulo de UI. Cada nivel agrega al contexto. Global mas proyecto mas directorio. Usa esto para evitar repeticion: global maneja tu estilo personal, proyecto maneja el codebase, directorio maneja el modulo. Para monorepos: pon convenciones compartidas en el CLAUDE.md raiz. Pon instrucciones especificas de la app en el directorio de cada app. Por ejemplo, website/apps/dashboard/CLAUDE.md podria decir "esta app usa Tailwind CSS y componentes shadcn/ui" mientras el CLAUDE.md raiz cubre la configuracion compartida de TypeScript.

PATTERN

Los archivos CLAUDE.md mas efectivos cubren seis areas: 1. Comandos de build y test. Los comandos exactos para compilar, testear, lintear y desplegar. No "ejecuta los tests" sino "npm run test" o "pytest -x tests/". Claude Code los usa directamente. 2. Estructura del proyecto. Un mapa breve del codebase. Donde vive el codigo fuente, donde van los tests, donde estan los archivos de configuracion. Dos a cinco lineas, no un arbol de directorio entero. 3. Convenciones de codigo. Indentacion, patrones de nombres, orden de importaciones, nombres de archivos. Especificas y verificables: "usa indentacion de 2 espacios" no "formatea el codigo bien." 4. Reglas de seguridad. Que nunca hacer. "Nunca hagas commit de archivos .env." "Nunca hagas push a main sin que pasen los tests." "Nunca elimines archivos de migracion." Estas son barreras que previenen errores costosos. 5. Instrucciones de flujo de trabajo. Como quieres que Claude Code opere. "Ejecuta tests antes de marcar una tarea como completa." "Escribe un context handoff al final de cada sesion." "Entra en modo plan para tareas con 3+ pasos." 6. Referencias clave. Apuntadores a documentos importantes. "Ver docs/ARCHITECTURE.md para el diseño del sistema." "Ver .cursor/rules/ para reglas por patron de archivos." Apuntadores, no copias - esto mantiene el CLAUDE.md liviano.

ANTI-PATTERN

Errores comunes que empeoran los archivos CLAUDE.md: No pegues bloques de codigo grandes. Se vuelven obsoletos cuando el codigo cambia. Apunta al archivo en su lugar: "ver src/lib/auth.ts para el patron de autenticacion." No excedas 200 lineas. Cada linea consume tokens de contexto. Un CLAUDE.md de 500 lineas consume el espacio disponible para codigo real y conversacion. Si necesitas mas detalle, usa la sintaxis @import para cargar archivos bajo demanda. No escribas instrucciones vagas. "Escribe buen codigo" y "sigue las mejores practicas" no tienen significado para una AI. Se interpretan diferente en cada sesion. "Usa retornos tempranos en lugar de if-else anidados" es especifico y consistente. No dupliques documentacion. Si tienes un CONTRIBUTING.md, apunta a el. No copies su contenido en CLAUDE.md. Una sola fuente de verdad. No incluyas secretos o variables de entorno. CLAUDE.md se versiona. Si tu build necesita claves de API, di "configura OPENAI_API_KEY en .env" no el valor real de la clave.

CODE

CLAUDE.md soporta importar otros archivos con la sintaxis @path/to/file. Los archivos importados se expanden inline cuando Claude Code carga el contexto. Usa importaciones para: - Documentos de arquitectura: @docs/ARCHITECTURE.md - Convenciones del equipo: @docs/CONVENTIONS.md - Documentacion de API: @docs/API.md Esto mantiene el CLAUDE.md raiz liviano (menos de 200 lineas) mientras le da a Claude acceso a referencias detalladas cuando las necesita. Los archivos importados solo se cargan cuando el CLAUDE.md se procesa, asi que no consumen tokens hasta que una sesion comienza. Un patron que funciona: mantén el CLAUDE.md como la tabla de contenidos y usa importaciones para los capitulos. El CLAUDE.md dice "Para instrucciones de despliegue, ver @docs/DEPLOY.md." Claude ve el documento completo de despliegue cuando lo necesita.

PRO TIP

El camino mas rapido: abre Claude Code en tu proyecto y ejecuta /init. Genera un CLAUDE.md inicial basado en la estructura de tu proyecto, package.json y archivos de configuracion existentes. Revisalo, recorta lo generico y agrega tus instrucciones especificas del proyecto. Si quieres empezar desde cero, crea un CLAUDE.md en la raiz de tu proyecto con estas tres secciones: ## Comandos de Build npm install npm run dev npm run test npm run build ## Estructura del Proyecto - src/ - Codigo fuente de la aplicacion - tests/ - Archivos de test - docs/ - Documentacion ## Reglas - Ejecutar tests antes de hacer commit - Usar TypeScript modo estricto - Nunca hacer commit de archivos .env Eso es suficiente para hacer Claude Code significativamente mas util. Puedes expandirlo con el tiempo a medida que notas patrones - cada vez que Claude Code hace algo mal, agrega una regla. Cada vez que re-explicas algo, agregalo al archivo. El CLAUDE.md se sazona con el uso, como un sarten de hierro fundido.