CLAUDE.md: configura las instrucciones de Claude Code con un ejemplo

Claude Code puede explorar el código, pero algunas reglas de trabajo no aparecen en él: por qué no enviar correos a clientes desde pruebas, qué directorios se generan o qué comprobación confirma una corrección. Si lo explicas en cada tarea, escríbelo en CLAUDE.md.

CLAUDE.md es un archivo Markdown con instrucciones persistentes para Claude Code. Guarda comandos, restricciones importantes y criterios de verificación. Puedes empezar con un archivo en la raíz. La documentación de Anthropic explica ubicaciones y carga.

• documentación de Anthropic

El ejemplo es para un proyecto web pequeño. Adapta rutas y comandos: es una plantilla didáctica, no una configuración probada en tu aplicación.

Qué reglas merece la pena escribir

Imagina añadir un campo «Empresa» al formulario. Saber que usas TypeScript no basta: el agente necesita encontrar el formulario, entender dónde llegan los datos y probar sin contactar al equipo comercial real.

Una buena regla permite decidir:

La segunda columna no es universal. Si no existe TextField, cambia la regla; de lo contrario, la instrucción provocará errores.

Revisa tus comentarios recientes al agente. ¿Cuáles servirán otra vez? Una condición sobre un botón concreto pertenece a la tarea; una convención para todos los formularios, a las reglas del proyecto.

Dónde crear CLAUDE.md

Pon las reglas compartidas en `CLAUDE.md`, en la raíz. Las preferencias personales generales pueden estar en `~/.claude/CLAUDE.md`. Los archivos de subdirectorios se cargan cuando Claude lee archivos allí. Guía de contexto.

• Guía de contexto

Estructura inicial:

project/
├── CLAUDE.md
├── README.md
├── package.json
└── src/

Si ya existe, léelo primero. Duplicar reglas dificulta mantenerlas: puedes actualizar un comando en un archivo y olvidarlo en otro.

Comprueba el nombre exacto. Un editor que oculta extensiones puede crear `CLAUDE.md.txt` por accidente.

Obtener una primera versión

Ejecuta `/init` en Claude Code. Ayuda a preparar el archivo a partir del proyecto. Revisa el resultado: comandos existentes, rutas vigentes y restricciones correctas. Así lo aconseja Anthropic.

• Anthropic

Para ver una propuesta sin modificar archivos:

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 contrastable con el repositorio. Una presentación cuidada no demuestra exactitud: `npm test` no sirve si el script no existe.

Ejemplo para un proyecto web

Esta plantilla didáctica original describe un sitio ficticio con npm, TypeScript, diccionarios y pruebas del formulario configuradas por separado. Los nombres 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 y después si las verificaciones son posibles. La instrucción no crea un destino de pruebas inexistente: prepara el entorno o documenta otra comprobación disponible.

No necesitas todas las secciones. Una biblioteca puede priorizar API pública y compatibilidad; un sitio editorial, estructura de contenido, metadatos y enlaces internos.

Comprobar si ayuda

Separa dos cuestiones: si el archivo se cargó y si cambió el comportamiento.

Ejecuta `/context` y revisa Memory files. Después asigna una tarea pequeña con resultado claro. Anthropic recomienda esta comprobación de carga. Configurar CLAUDE.md.

• Configurar CLAUDE.md

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.

Revisa tres puntos:

1. ¿Usó el componente previsto y los diccionarios?
2. ¿Sigue funcionando el envío sin el campo opcional?
3. ¿Los resultados coinciden con la salida de las herramientas?

Si algo falla, busca la causa: regla ambigua, otro manejador parecido o pruebas incompletas. Añade una prohibición después de entender qué ocurrió.

Puedes registrar tarea, acción esperada, resultado y cambio de regla. Es un método propuesto, no un informe experimental. Un éxito no garantiza cumplimiento futuro.

Si Claude ignora CLAUDE.md

Confirma primero que se cargó y busca instrucciones del mismo tema en otros archivos. Los CLAUDE.md encontrados se combinan en el contexto; uno anidado no cancela automáticamente todos los anteriores. Orden de carga.

• Orden de carga

Revisa la redacción. «Prueba cuidadosamente» deja muchas opciones; indicar un comando tras modificar el manejador define una acción observable.

La instrucción también puede estar anticuada. Si cambian pruebas o directorios, revisa las reglas relacionadas. Es difícil seguir documentación de un proyecto que ya no existe.

Elimina repeticiones y deseos genéricos. Anthropic recomienda instrucciones breves y específicas, revisadas durante el trabajo. No hay una longitud universal que garantice su cumplimiento. Consejos de contenido.

• Consejos de contenido

Cuándo usar rules y Skills

Separa instrucciones por finalidad. `.claude/rules/` admite reglas temáticas, incluidas las vinculadas a rutas. Skills sirve para procedimientos repetibles que se necesitan según la situación. Reglas, Skills.

• Reglas
• Skills

Esto facilita mantener las instrucciones. Cambiar el proceso de versiones no obliga a editar cada escenario. Separar archivos no elimina por sí solo las contradicciones.

CLAUDE.md no sustituye los permisos

«No escribas a clientes reales» describe una regla útil, pero las restricciones técnicas se configuran aparte. Claude Code ofrece `/permissions` y reglas allow, ask, deny; CLAUDE.md no las cambia. Permisos.

• Permisos

Configura el entorno para dirigir los envíos al destino de pruebas. Así el destinatario correcto no depende solo de interpretar un párrafo.