Skip to main content

​
Respuesta rápida

CLAUDE.md es un archivo de instrucciones del proyecto que Claude Code puede cargar como contexto. Es adecuado para documentar la estructura del proyecto, los comandos, las convenciones de código, los requisitos de las pruebas, los límites de seguridad y las reglas de colaboración. No es un mecanismo de cumplimiento. Claude Code lo interpreta como una guía. Si una regla debe ejecutarse en un momento concreto, utiliza hooks o la configuración de herramientas en lugar de depender solo de CLAUDE.md. Un CLAUDE.md útil es breve, específico y está actualizado. Incluye en él los datos del proyecto que, de otro modo, repetirías en cada sesión.

​
Cuándo es importante

  • Claude Code pregunta repetidamente por la misma estructura o los mismos comandos
  • Tu equipo quiere compartir reglas de pruebas, estilo o seguridad
  • Quieres reducir el contexto repetido y el uso de tokens
  • Claude Code no aplica las convenciones específicas del repositorio
  • Quieres acelerar la incorporación de otros agentes o miembros del equipo

​
Conceptos clave

​
Contenido recomendado

Escribe CLAUDE.md como una guía breve del proyecto:
  • Qué es el proyecto y dónde están los directorios importantes
  • Comandos habituales de compilación, pruebas y formato
  • Límites de la arquitectura que deben respetarse antes de editar
  • Comprobaciones rápidas que deben ejecutarse antes de terminar
  • Secretos, logs o configuración privada que no deben exponerse
  • Convenciones de documentación, pruebas, nombres y gestión de errores
Evita los tutoriales extensos, los planes temporales y las notas de tareas puntuales. Si una regla solo se aplica a un área, limita su alcance. Si es obligatorio imponer un comportamiento, utiliza hooks.

​
Errores habituales

  • Tratar CLAUDE.md como un prompt del sistema o una capa estricta de permisos.
  • Hacerlo demasiado largo, lo que aumenta el coste del contexto y dificulta su aplicación.
  • Acumular indefinidamente notas antiguas de despliegue, TODO temporales y decisiones obsoletas.
  • Incluir API Keys, tokens, cookies o configuración privada en el archivo.
  • Mantener CLAUDE.md, AGENTS.md y Cursor Rules con instrucciones contradictorias.

​
Cómo interviene BetterToken

Si un proyecto utiliza BetterToken, CLAUDE.md puede recordar que Claude Code utiliza la dirección compatible con Anthropic https://www.bettertoken.ai, mientras que Codex y las herramientas externas utilizan la dirección compatible con OpenAI https://www.bettertoken.ai/v1. No incluyas API Keys reales en CLAUDE.md. Guárdalas en variables de entorno locales, archivos de configuración locales o un sistema protegido de secretos.

​
Documentación relacionada

​
Referencias