--- title: "Qué poner en tu CLAUDE.md: buenas prácticas" excerpt: "Qué es el CLAUDE.md, dónde colocarlo, qué instrucciones incluir y cuáles dejar fuera, y las buenas prácticas que de verdad hacen que Claude Code te haga caso." date: "2026-06-29T11:00:00.000Z" category: "Inteligencia Artificial" tech_article: true author: name: "angel cruz" picture: "https://angelcruzdevcdn.nyc3.cdn.digitaloceanspaces.com/images/me/angel-cruz.png" ogImage: url: "/images/open-graph/og-image.png" seo_title: "CLAUDE.md: qué poner y buenas prácticas (Claude Code)" seo_description: "Qué es el CLAUDE.md, dónde va, qué instrucciones incluir y cuáles no, e importar AGENTS.md. Buenas prácticas para que Claude Code siga tus reglas." --- El **CLAUDE.md** es un archivo markdown donde escribes las instrucciones permanentes que quieres que Claude Code tenga presentes en tu proyecto: comandos de build, convenciones de código, arquitectura y reglas del tipo "siempre haz X". Claude lo lee al inicio de **cada** sesión, así dejas de repetir el mismo contexto una y otra vez. Un matiz importante que casi nadie menciona: el CLAUDE.md se carga como un mensaje del usuario, no como parte del system prompt. Es **guía, no configuración forzada**. Claude lo lee y trata de seguirlo, pero no es una garantía de cumplimiento estricto. Para algo que debe ejecutarse sí o sí (por ejemplo, antes de cada commit), eso va en un hook, no en el CLAUDE.md. ## Dónde va el CLAUDE.md Puede vivir en varias ubicaciones, cada una con un alcance distinto. Se cargan de más general a más específico, así que lo más cercano a tu proyecto se lee al final y tiene prioridad: | Alcance | Ubicación | Para qué | |---|---|---| | Usuario | `~/.claude/CLAUDE.md` | Tus preferencias personales en todos los proyectos | | Proyecto | `./CLAUDE.md` o `./.claude/CLAUDE.md` | Reglas del equipo, versionadas en git | | Local | `./CLAUDE.local.md` | Preferencias personales de ese proyecto (va al `.gitignore`) | Claude recorre el árbol de directorios hacia arriba desde donde lo ejecutas y concatena todos los CLAUDE.md que encuentra. Los CLAUDE.md de **subdirectorios** no se cargan al inicio: se incluyen cuando Claude lee archivos de esa carpeta. El del directorio raíz, además, sobrevive a un `/compact`: Claude lo vuelve a leer del disco. ## Qué poner (y qué dejar fuera) La regla mental es simple: **el CLAUDE.md es el lugar donde escribes lo que tendrías que volver a explicar.** Agrega algo cuando: - Claude comete el mismo error por segunda vez. - Una review detecta algo que Claude debería haber sabido de este código. - Tecleas la misma corrección que ya tecleaste la sesión pasada. - Un compañero nuevo necesitaría ese contexto para ser productivo. Buen contenido para un CLAUDE.md: - **Comandos** de build, test y lint del proyecto. - **Convenciones**: estilo de código, naming, estructura de carpetas. - **Arquitectura**: decisiones y dónde vive cada cosa. - **Reglas "siempre/nunca"** que aplican a todo el proyecto. Qué **no** poner ahí: - **Procedimientos de varios pasos** o flujos que solo usas a veces: eso va mejor en un skill, que se carga bajo demanda. - **Instrucciones que solo aplican a una parte del código**: usa reglas con scope por ruta en `.claude/rules/`, que solo se cargan cuando Claude toca archivos que coinciden con el patrón. ## Las buenas prácticas que de verdad importan El CLAUDE.md consume tokens de tu ventana de contexto en cada sesión, y la forma en que lo escribes afecta cuánto te hace caso. Tres reglas: **1. Mantenlo corto.** Apunta a menos de **200 líneas**. Cuanto más largo, más contexto consume y peor lo sigue. Si crece, mueve cosas a reglas con scope por ruta en lugar de acumular todo en un archivo. **2. Sé específico y verificable.** Las instrucciones concretas funcionan; las vagas no: - "Usa indentación de 2 espacios" en vez de "formatea bien el código". - "Corre `npm test` antes de commitear" en vez de "prueba tus cambios". - "Los handlers de API viven en `src/api/handlers/`" en vez de "mantén los archivos organizados". **3. Estructura y coherencia.** Usa encabezados y listas markdown para agrupar instrucciones: Claude escanea la estructura igual que tú. Y revisa que no haya reglas que se contradigan entre el CLAUDE.md raíz, los de subcarpetas y `.claude/rules/`. Si dos reglas chocan, Claude elige una al azar. Un extra útil: los comentarios HTML de bloque (``) se eliminan antes de inyectar el contenido en el contexto, así dejas notas para tu equipo sin gastar tokens. ## Importar otros archivos con @ (y el truco con AGENTS.md) Un CLAUDE.md puede importar otros archivos con la sintaxis `@ruta/al/archivo`. Se expanden y cargan en el contexto al inicio, junto al CLAUDE.md que los referencia. Aceptan rutas relativas y absolutas, y pueden importar a su vez otros archivos, con un máximo de **4 niveles** de profundidad. ```text Revisa @README para el overview del proyecto. # Instrucciones adicionales - flujo de git @docs/git-instructions.md ``` Aquí está el detalle que más vale la pena: **Claude Code lee `CLAUDE.md`, no `AGENTS.md`.** Si tu repo ya usa `AGENTS.md` para otros agentes (como hago en este sitio), no dupliques nada: crea un `CLAUDE.md` que lo importe y, debajo, agrega lo específico de Claude. ```markdown @AGENTS.md ## Claude Code Usa plan mode para cambios en `src/billing/`. ``` Así ambas herramientas leen las mismas instrucciones desde una sola fuente. ## CLAUDE.md, auto memory, skills y hooks: cuándo usar cada uno Es fácil meter todo en el CLAUDE.md. Mejor reparte: - **CLAUDE.md**: instrucciones que escribes tú y quieres en cada sesión. - **Auto memory**: notas que Claude escribe solo a partir de tus correcciones y preferencias (build commands, hallazgos de debugging). No la escribes tú. - **Skills**: flujos repetibles que se cargan solo cuando hacen falta. - **Hooks**: comandos que se ejecutan en momentos fijos del ciclo de vida, pase lo que pase. Para enforcement real (no solo guía). Y si lo que quieres es darle a Claude **herramientas nuevas** más allá de instrucciones, eso ya es terreno de los servidores MCP: lo explico paso a paso en [cómo crear un servidor MCP en TypeScript](/post/como-crear-un-servidor-mcp). ## Comandos útiles - **`/init`**: genera un CLAUDE.md inicial analizando tu código (comandos, tests, convenciones que detecta). Si ya existe uno, sugiere mejoras en vez de sobrescribir. Si tu repo ya tiene `AGENTS.md` (o `.cursorrules`), lo lee e incorpora lo relevante. - **`/memory`**: lista los CLAUDE.md y reglas cargados en la sesión y te deja abrirlos para editar. Si algo no aparece ahí, Claude no lo está viendo. ## Preguntas frecuentes ### ¿Dónde se guarda el CLAUDE.md? En el proyecto va en `./CLAUDE.md` o `./.claude/CLAUDE.md` (versionado en git). Tus preferencias personales para todos los proyectos van en `~/.claude/CLAUDE.md`, y las personales de un proyecto en `./CLAUDE.local.md` (añádelo al `.gitignore`). ### ¿CLAUDE.md o AGENTS.md? Claude Code lee `CLAUDE.md`, no `AGENTS.md`. Si ya usas `AGENTS.md`, crea un `CLAUDE.md` que lo importe con `@AGENTS.md` y agrega debajo lo específico de Claude. Así no duplicas instrucciones. ### ¿Qué tan largo debe ser? Menos de 200 líneas. Los archivos más largos consumen más contexto y reducen qué tanto Claude sigue las instrucciones. Si crece, parte el contenido en reglas con scope por ruta en `.claude/rules/`. ### ¿Por qué Claude no sigue mi CLAUDE.md? Porque es guía, no enforcement: se entrega como mensaje del usuario, no como system prompt. Verifica con `/memory` que el archivo se está cargando, haz las instrucciones más específicas y elimina reglas que se contradigan. Si algo debe ejecutarse siempre en un momento exacto, escríbelo como un hook. ### ¿Cómo creo uno rápido? Corre `/init` en tu proyecto: Claude analiza el código y genera un CLAUDE.md con comandos, tests y convenciones que detecta. Desde ahí lo refinas con lo que no podría adivinar solo. --- ## Sitemap Índice completo del sitio: [/sitemap.md](https://www.angelcruz.dev/sitemap.md) Canónico HTML: [https://www.angelcruz.dev/post/claude-md-buenas-practicas](https://www.angelcruz.dev/post/claude-md-buenas-practicas)