CLAUDE.md: configura las instrucciones de Claude Code con un ejemplo
Neaptide · 20 de septiembre de 2026 · 8 min de lectura · Actualizado: 3 de octubre de 2026
Crea un CLAUDE.md útil con comandos, criterios de verificación y una plantilla. Comprueba su carga y resuelve instrucciones ignoradas.
En este artículo
Claude Code puede leer tu código, pero hay reglas de trabajo que no están escritas en él: por qué el entorno de pruebas no debe enviar correos a clientes, qué directorios se generan solos o qué comprobación confirma que una corrección funciona. Si te ves explicándolo en cada tarea nueva, escríbelo en CLAUDE.md.
CLAUDE.md es un archivo Markdown con instrucciones persistentes para Claude Code. En él se guardan los comandos del proyecto, las restricciones importantes y los criterios de verificación. Para empezar basta un archivo en la raíz del repositorio. La documentación de Anthropic explica dónde pueden estar estos archivos y cómo se cargan.
El ejemplo de más abajo es un proyecto web pequeño. Cambia sus rutas y comandos por los tuyos: es una plantilla para aprender y nadie la ha probado en tu aplicación.
Qué reglas merece la pena escribir
Imagina que hay que añadir un campo «Empresa» a un formulario de solicitud. Con saber que el proyecto usa TypeScript, el agente no llega lejos. Tiene que encontrar el formulario, entender adónde van los datos y probar el envío sin que la solicitud le llegue al equipo comercial de verdad.
Una buena regla ayuda a tomar una decisión concreta:
| Demasiado general | Aplicable |
|---|---|
| Escribe código de calidad | Comprueba valor vacío, email inválido y envío correcto |
| Respeta el diseño | Usa TextField y sus estados de error existentes |
| No rompas el proyecto | Tras modificar el manejador, ejecuta sus pruebas y comprueba tipos |
| Considera los idiomas | Guarda etiquetas y errores en diccionarios, no en componentes |
| Comprueba el resultado | Separa comprobaciones realizadas y no disponibles |
La columna de la derecha no vale para cualquier repositorio. Sirve porque se ajusta a este proyecto. Si en el tuyo no existe TextField, reescribe la regla, o será la propia instrucción la que provoque errores.
Repasa las correcciones que le has hecho últimamente al agente. ¿Cuáles volverán a hacer falta? Una condición sobre un botón concreto se queda en la tarea. Una convención para todos los formularios va a las reglas del proyecto.
Dónde crear CLAUDE.md
Pon las reglas compartidas del equipo en `CLAUDE.md`, en la raíz del proyecto. Tus preferencias personales, las que valen para cualquier proyecto, pueden ir en `~/.claude/CLAUDE.md`. Los archivos de los subdirectorios se cargan cuando Claude lee archivos de esos directorios.
Una estructura sencilla para empezar:
project/
├── CLAUDE.md
├── README.md
├── package.json
└── src/Si el archivo ya existe, léelo antes de nada. Dos juegos de reglas parecidas se mantienen mal: actualizas el comando de pruebas en uno y te olvidas del otro.
Comprueba también el nombre exacto. Un editor que oculta las extensiones puede dejarte un `CLAUDE.md.txt` sin que te des cuenta.
Obtener una primera versión
Ejecuta `/init` en una sesión abierta de Claude Code. El comando prepara un primer CLAUDE.md a partir del proyecto. Revisa lo que genera: los comandos tienen que existir, las rutas estar al día y las restricciones corresponder a tu forma de trabajar. Así lo aconseja Anthropic.
Para ver una propuesta antes de tocar ningún archivo, pide:
Examina README, los scripts de package.json y la estructura. Propón un CLAUDE.md con comandos de inicio y comprobación, límites importantes y particularidades que no puedan deducirse con certeza. Presenta las incógnitas como preguntas. Todavía no crees ni modifiques archivos.Obtendrás un texto que puedes contrastar con el repositorio. No lo aceptes porque tenga buen aspecto. `npm test` no sirve de nada si el proyecto no tiene ese script.
Ejemplo para un proyecto web
Esta plantilla la hemos escrito para la guía. Describe un sitio de servicios ficticio con npm, TypeScript, diccionarios de traducción y pruebas del formulario configuradas aparte. Los nombres de comandos y directorios solo ilustran la estructura; sustitúyelos por los reales.
# Proyecto
Sitio de servicios con formulario de contacto, en ruso e inglés.
Recorrido principal: elegir un servicio y enviar una solicitud.
## Dónde está el código
- src/components/forms/ — campos y formularios.
- src/server/leads/ — procesamiento de solicitudes.
- src/i18n/ — diccionarios de interfaz.
- tests/leads/ — pruebas de procesamiento.
## Comandos
- npm run dev — inicio local.
- npm run typecheck — comprobación de tipos.
- npm run test:leads — pruebas de solicitudes.
- npm run build — compilación.
## Reglas de cambios
- Reutiliza los componentes de formulario y manejadores de errores.
- Guarda el texto en los diccionarios de ambos idiomas.
- No añadas dependencias si bastan las herramientas del proyecto.
- Conserva los cambios sin terminar de otras personas.
## Verificación
- Comprueba campos obligatorios, email inválido y envío correcto
a un destino de pruebas cuando cambie la solicitud.
- Ejecuta npm run typecheck para cambios TypeScript.
- Ejecuta npm run test:leads para cambios de procesamiento.
- Revisa la pantalla afectada en el navegador tras cambios de interfaz.
- Si una prueba no está disponible, explica la causa y la incertidumbre.
## Entorno
- Usa solo el destino de pruebas para comprobar envíos.
- Los nombres de variables necesarias están en .env.example.
- No copies secretos en código, informes ni documentación.
## Informe
Describe brevemente cambios, comprobaciones y problemas pendientes.
Separa resultados de pruebas y suposiciones sobre la aplicación.Comprueba primero los comandos. Después asegúrate de que las verificaciones se pueden hacer de verdad. Una instrucción no crea un destino de pruebas que no existe: prepara el entorno de pruebas o documenta otra comprobación que sí esté disponible.
No necesitas todas las secciones. A una biblioteca le importan más la API pública y la compatibilidad. A un sitio de artículos, la estructura del contenido, los metadatos y los enlaces internos.
Comprobar si ayuda
Aquí hay dos preguntas distintas: si el archivo se cargó y si cambió el comportamiento del agente.
Ejecuta `/context` y busca tu archivo en Memory files. Después encarga una tarea pequeña con un resultado claro. Anthropic recomienda expresamente esta forma de comprobar la carga.
Para el sitio del ejemplo:
Añade un campo opcional «Empresa». Antes de modificar, localiza el componente existente y el manejador de envío. Después comprueba el envío con empresa y sin ella. Enumera solo las comprobaciones realizadas.
Luego fíjate en tres cosas:
- ¿Usó el componente previsto y los diccionarios?
- ¿Sigue funcionando el envío sin el campo opcional?
- ¿Los resultados coinciden con la salida de las herramientas?
Si alguna falla, busca la causa. Puede que la regla sea ambigua. Puede que haya otro manejador parecido en el código. Puede que las pruebas no cubran ese caso. Añade una prohibición solo cuando entiendas qué ha pasado.
Lleva un registro breve: la tarea, la acción que esperabas, el resultado real y la regla que cambiaste. Es un método que proponemos nosotros; aquí no informamos de ningún experimento. Que salga bien una vez no demuestra que la regla se vaya a cumplir siempre.
Si Claude ignora CLAUDE.md
Confirma primero que se cargó el archivo que querías. Después busca instrucciones sobre el mismo tema en otros archivos del proyecto. Según la documentación, todos los CLAUDE.md que Claude encuentra se combinan en el contexto, de modo que uno anidado no cancela automáticamente las reglas de más arriba.
Mira después la redacción. «Prueba con cuidado» le deja al agente demasiadas opciones. «Ejecuta este comando después de modificar el manejador de solicitudes» nombra una acción cuyo resultado se puede ver.
También puede que la instrucción esté anticuada. Cuando se muevan las pruebas o cambie la estructura de directorios, repasa las reglas que dependen de ellas. Poco puede hacer el agente con la documentación de un proyecto que ya no existe.
Por último, quita las repeticiones y los deseos genéricos. Anthropic recomienda instrucciones breves, propias del proyecto, y revisarlas sobre la marcha. Ninguna longitud de archivo garantiza que se cumplan.
Cuándo usar rules y Skills
Cuando el proyecto crezca, separa las instrucciones según para qué sirven. `.claude/rules/` admite reglas temáticas, incluidas las ligadas a rutas concretas. Los skills sirven para procedimientos repetibles que solo hacen falta en ciertas situaciones.
| Contenido | Ubicación |
|---|---|
| Comandos principales y verificación general | CLAUDE.md |
| Validación de todos los formularios | Regla temática |
| Preparación de una versión | Skill |
| Añadir hoy el campo Empresa | Tarea actual |
Así las instrucciones se mantienen mejor: si cambia el proceso de publicación de versiones, no tienes que editar cada escenario. Eso sí, repartirlas en archivos no las vuelve más precisas. Las contradicciones hay que resolverlas en el contenido.
CLAUDE.md no sustituye los permisos
«No escribas a clientes reales» describe bien una forma de trabajar. Las restricciones técnicas de acceso se configuran aparte. Claude Code tiene `/permissions` y reglas allow, ask y deny, y nada de lo que pongas en CLAUDE.md las cambia.
En el ejemplo del formulario, configura el entorno de pruebas para que los envíos vayan físicamente a un destino de pruebas. Así el destinatario correcto deja de depender de cómo interprete el agente un párrafo.