{"id":1563,"date":"2026-10-29T09:45:13","date_gmt":"2026-10-29T08:45:13","guid":{"rendered":"https:\/\/vermiip.es\/blog\/?p=1563"},"modified":"2026-10-29T09:45:13","modified_gmt":"2026-10-29T08:45:13","slug":"como-crear-un-archivo-claude-md-para-tu-proyecto","status":"publish","type":"post","link":"https:\/\/vermiip.es\/blog\/como-crear-un-archivo-claude-md-para-tu-proyecto\/","title":{"rendered":"C\u00f3mo crear un archivo CLAUDE.md para tu proyecto"},"content":{"rendered":"

Si ya has dado tus primeros pasos con Claude Code, seguramente habr\u00e1s notado que el siguiente reto no es \u201chacer que funcione\u201d, sino hacer que funcione como t\u00fa quieres<\/strong>. Ah\u00ed es donde entra CLAUDE.md<\/strong>: un archivo de contexto pensado para centralizar instrucciones, decisiones t\u00e9cnicas y reglas de trabajo dentro de tu repositorio.<\/p>\n

En art\u00edculos anteriores ya vimos qu\u00e9 es CLAUDE.md y para qu\u00e9 sirve en Claude Code<\/a>, as\u00ed que aqu\u00ed vamos un paso m\u00e1s all\u00e1: c\u00f3mo crearlo bien, qu\u00e9 incluir y c\u00f3mo evitar que se convierta en un documento ca\u00f3tico e in\u00fatil.<\/p>\n

Por qu\u00e9 merece la pena crear este archivo<\/h2>\n

Un archivo CLAUDE.md bien estructurado reduce fricci\u00f3n. En la pr\u00e1ctica, ayuda a que la herramienta entienda mejor el proyecto, respete tus convenciones y no te haga perder tiempo repitiendo instrucciones en cada sesi\u00f3n.<\/p>\n

Piensa en \u00e9l como una combinaci\u00f3n de gu\u00eda de estilo, memoria operativa y manual de arranque r\u00e1pido. No sustituye a la documentaci\u00f3n formal del proyecto, pero s\u00ed complementa cosas como el README, los issues o la documentaci\u00f3n interna.<\/p>\n

Adem\u00e1s, cuando trabajas en equipo, este archivo aporta consistencia. Todos parten del mismo contexto y es m\u00e1s f\u00e1cil mantener criterios homog\u00e9neos en nombres de m\u00f3dulos, estructura del repositorio, flujo de pruebas o convenciones de commits.<\/p>\n

Qu\u00e9 debe contener un buen CLAUDE.md<\/h2>\n

No existe una \u00fanica plantilla universal. La clave est\u00e1 en incluir solo la informaci\u00f3n que realmente ayuda al asistente a tomar mejores decisiones dentro de tu proyecto. Si ya has le\u00eddo c\u00f3mo iniciar tu primer proyecto con Claude Code<\/a>, esta parte encaja especialmente bien con la fase de configuraci\u00f3n inicial.<\/p>\n

1. Descripci\u00f3n breve del proyecto<\/h3>\n

Empieza con unas l\u00edneas que expliquen qu\u00e9 hace la aplicaci\u00f3n, el stack principal y el objetivo del repositorio. No hace falta redactar un README completo; basta con dar contexto suficiente para entender si se trata de una API, una SPA, una librer\u00eda o una app full stack.<\/p>\n

2. Estructura del repositorio<\/h3>\n

Indica d\u00f3nde viven los componentes importantes: c\u00f3digo fuente, tests, configuraci\u00f3n, assets o scripts. Esto es \u00fatil para orientar a Claude cuando tenga que localizar una funcionalidad concreta o respetar una carpeta determinada.<\/p>\n

3. Convenciones de c\u00f3digo<\/h3>\n

Aqu\u00ed puedes documentar reglas como estilo de indentaci\u00f3n, nomenclatura de variables, patr\u00f3n de componentes, organizaci\u00f3n por dominio o preferencias de linting. Cuanto m\u00e1s claro sea este apartado, menos \u201csuposiciones\u201d har\u00e1 la herramienta.<\/p>\n

4. Comandos importantes del proyecto<\/h3>\n

Incluye los comandos m\u00e1s usados para instalar dependencias, ejecutar tests, lanzar el entorno de desarrollo o generar builds. Si trabajas con sistemas modernos de frontend o backend, este bloque ahorra mucho tiempo y reduce errores por ejecutar tareas equivocadas.<\/p>\n

5. Restricciones y buenas pr\u00e1cticas<\/h3>\n

Si hay carpetas sensibles, m\u00f3dulos que no deben tocarse o decisiones arquitect\u00f3nicas que deban respetarse, d\u00e9jalo por escrito. Por ejemplo: no modificar migraciones antiguas, no introducir nuevas dependencias sin validaci\u00f3n o no cambiar la API p\u00fablica sin aprobaci\u00f3n.<\/p>\n

Estructura recomendada para empezar<\/h2>\n

La mejor forma de crear un CLAUDE.md es empezar por lo esencial y ampliarlo con el tiempo. No intentes documentarlo todo desde el primer minuto. Un archivo demasiado largo suele perder utilidad porque nadie lo mantiene al d\u00eda.<\/p>\n

Una estructura b\u00e1sica podr\u00eda incluir estas secciones:<\/p>\n

# CLAUDE.md\n\n## descripci\u00f3n del proyecto\nBreve explicaci\u00f3n del objetivo del repositorio y tecnolog\u00eda principal.\n\n## estructura\n- src\/: c\u00f3digo principal\n- tests\/: pruebas autom\u00e1ticas\n- docs\/: documentaci\u00f3n adicional\n\n## comandos frecuentes\n- npm install\n- npm run dev\n- npm test\n\n## convenciones\n- Usar TypeScript en nuevos m\u00f3dulos\n- Mantener nombres descriptivos\n- Seguir el patr\u00f3n de arquitectura existente\n\n## notas importantes\n- No alterar la API p\u00fablica sin revisar compatibilidad\n- Revisar el lint antes de finalizar cambios\n<\/code><\/pre>\n
Este ejemplo es intencionalmente simple. La idea no es imponer una plantilla r\u00edgida, sino crear una base clara, legible y f\u00e1cil de extender. En proyectos m\u00e1s complejos, puedes a\u00f1adir secciones para entornos, variables, despliegue, revisi\u00f3n de pull requests o flujos de pruebas espec\u00edficos.<\/p>\n
D\u00f3nde colocar el archivo<\/h2>\n
En la mayor\u00eda de los casos, CLAUDE.md se coloca en la ra\u00edz del proyecto para que sea f\u00e1cil de encontrar y aplicar al contexto general del repositorio. Si el proyecto tiene varias partes independientes, tambi\u00e9n puede tener sentido usar archivos adicionales en subdirectorios, siempre que tu flujo de trabajo lo justifique.<\/p>\n
La regla pr\u00e1ctica es sencilla: el archivo debe estar donde aporte m\u00e1s claridad. Si lo escondes demasiado, pierde valor; si duplicas informaci\u00f3n sin control, acabar\u00e1 desactualizado.<\/p>\n
Si quieres entender mejor c\u00f3mo interact\u00faa este archivo con el proceso de arranque inicial, te recomendamos revisar tambi\u00e9n c\u00f3mo usar \/init para configurar un proyecto en Claude Code<\/a>, porque ambos enfoques se complementan muy bien.<\/p>\n
Qu\u00e9 errores evitar al crearlo<\/h2>\n
Escribir demasiado contexto irrelevante<\/h3>\n
Un error habitual es convertir CLAUDE.md en un volcado de documentaci\u00f3n general. Eso no ayuda al asistente ni al equipo. Mant\u00e9n el foco en lo que influye directamente en el desarrollo: estructura, normas, dependencias, comandos y restricciones.<\/p>\n
Copiar y pegar informaci\u00f3n obsoleta<\/h3>\n
Si el proyecto cambia, el archivo tambi\u00e9n debe cambiar. Una instrucci\u00f3n antigua puede ser peor que no tener ninguna, porque genera decisiones incorrectas. Revisa el contenido cada vez que actualices el stack o refactorices una parte importante.<\/p>\n
Mezclar documentaci\u00f3n p\u00fablica con instrucciones internas<\/h3>\n
El README explica el proyecto al mundo. CLAUDE.md explica c\u00f3mo trabajar bien dentro del proyecto. Aunque ambos puedan compartir algunas ideas, conviene no mezclar objetivos ni tono. As\u00ed se mantiene cada documento \u00fatil en su propio contexto.<\/p>\n
C\u00f3mo mantenerlo \u00fatil a largo plazo<\/h2>\n
La mejor estrategia es tratar CLAUDE.md como un archivo vivo. No hace falta revisarlo a diario, pero s\u00ed cada vez que cambien procesos importantes: nuevos scripts, nuevos est\u00e1ndares, nueva arquitectura o cambios en el flujo de pruebas.<\/p>\n
Tambi\u00e9n es buena idea pedir al equipo que lo use como referencia real. Si nadie lo consulta o nadie lo actualiza, acabar\u00e1 siendo ruido. En cambio, cuando se integra en el flujo de trabajo, se convierte en un peque\u00f1o multiplicador de productividad.<\/p>\n
En proyectos con mucha automatizaci\u00f3n, este archivo puede ser especialmente valioso para documentar c\u00f3mo debe actuar la IA ante tareas repetitivas: generaci\u00f3n de componentes, refactorizaciones, revisiones superficiales o ejecuci\u00f3n de tests. No reemplaza el criterio humano, pero s\u00ed lo apoya.<\/p>\n
Relaci\u00f3n con el resto del flujo de claude code<\/h2>\n
Crear CLAUDE.md no es un paso aislado. Forma parte de una cadena m\u00e1s amplia: instalar correctamente la herramienta, configurar el entorno, entender la terminal, trabajar con comandos y preparar el proyecto para que la IA tenga contexto suficiente.<\/p>\n
Si todav\u00eda est\u00e1s construyendo esa base, te vendr\u00e1 bien repasar c\u00f3mo configurar Claude Code y comenzar a programar<\/a> y c\u00f3mo usar Claude Code desde la terminal<\/a>. Son piezas que, combinadas con un buen CLAUDE.md, mejoran mucho la experiencia.<\/p>\n
En otras palabras: cuanto mejor sea tu documentaci\u00f3n operativa, menos depender\u00e1s de repetir instrucciones manuales y m\u00e1s fluido ser\u00e1 el trabajo asistido por IA.<\/p>\n
Conclusi\u00f3n<\/h2>\n
Crear un archivo CLAUDE.md no consiste en escribir mucho, sino en escribir bien. Debe ser breve, preciso y \u00fatil para que la herramienta entienda el proyecto, respete tus decisiones y te ayude a trabajar con menos fricci\u00f3n.<\/p>\n
Si lo preparas con criterio, este archivo se convierte en una base s\u00f3lida para escalar tu flujo de desarrollo con Claude Code. Y lo mejor es que no necesitas complicarlo: con unas pocas secciones bien pensadas puedes lograr una mejora notable desde el primer d\u00eda.<\/p>\n
Fuentes y lecturas recomendadas<\/h3>\n