Abrir un proyecto y pedir «continúa» deja varias preguntas sin responder: qué estaba pendiente, qué cambió desde la última sesión y qué decisiones siguen vigentes. Un archivo de instrucciones puede ayudar con la parte estable. La situación actual del repositorio exige una lectura nueva.
CLAUDE.md permite comunicar contexto e instrucciones a Claude Code. Su documentación de memoria e instrucciones distingue ese contenido, mantenido por personas, de la memoria automática que la herramienta puede conservar. Es una diferencia práctica: la memoria recoge contexto aprendido; las instrucciones expresan acuerdos del proyecto. Ninguna de las dos debe tratarse como una fotografía infalible de lo que hay hoy en los archivos.
Explicar el proyecto sin escribir una enciclopedia
La primera sección debería responder qué contiene el repositorio y dónde empezar a leer. Nombra sus componentes con palabras que el equipo reconozca. Si existe una guía de arquitectura, indica la ruta. Si el sistema funciona con PHP y no necesita compilar una aplicación JavaScript, dilo con claridad. Evitar una suposición equivocada al principio suele ser más útil que describir cada carpeta.
Después añade el procedimiento de comprobación. Conviene distinguir una prueba local de la verificación de un servicio publicado. «Validar el formulario» puede significar revisar el HTML, enviar datos ficticios en un entorno de pruebas o comprobar una entrega real. La guía debe explicar qué evidencia corresponde a cada caso, sin autorizar acciones externas por defecto.
No guardes credenciales, datos de clientes ni instrucciones para copiar información sensible a servicios externos. El documento debe poder compartirse con las personas que trabajan en el proyecto sin convertirse en otro archivo secreto. Los límites de acceso se resuelven además en la herramienta y el sistema; una frase escrita no reemplaza esos controles.
El caso de una actualización de catálogo
Pensemos en Distribuciones Ribera, una empresa ficticia. Su aplicación mantiene referencias, precios y fichas técnicas. La persona responsable quiere pedir una mejora visual del catálogo. Un CLAUDE.md útil explicaría dónde se definen las plantillas, dónde viven los datos y qué prueba permite comprobar una ficha. También señalaría que cambiar presentación no autoriza modificar precios ni condiciones comerciales.
El encargo concreto podría limitarse a una plantilla y a un archivo de estilos. Al recibirlo, Claude Code todavía debería inspeccionar esos archivos y su estado. Si encuentra una modificación ajena a medio hacer, el trabajo necesita reconciliación antes de sobrescribirla. Este ejemplo no describe una intervención ejecutada ni un resultado medido; muestra cómo separar acuerdos estables de decisiones de una tarea.
Tras terminar, la entrega debería nombrar los archivos cambiados, las comprobaciones realizadas y las reservas. «Todo correcto» ofrece poca ayuda a la siguiente persona. «La plantilla se abre con datos ficticios; falta comprobar el envío en el entorno autorizado» delimita lo que realmente se sabe.
Instrucciones, memoria y bitácora tienen funciones distintas
Usa las instrucciones para normas y rutas de referencia. Reserva una bitácora para el punto de reanudación: qué se hizo, qué queda y qué revisión identifica el trabajo. Deja que la memoria ayude a recuperar preferencias, pero contrasta cualquier dato que pueda cambiar. Un nombre de archivo recordado no demuestra que siga existiendo ni que su contenido esté actualizado.
Cuando una misma corrección se repite, decide si merece convertirse en una regla. Si fue una excepción de un encargo, conservarla como norma puede provocar errores nuevos. También conviene revisar las reglas cuando cambia el equipo o el procedimiento de publicación. El archivo debe describir la forma de trabajar actual, no una colección de incidentes pasados.
La documentación actual también contempla AGENTS.md desde Claude Code v2.1.277. Por defecto lo utiliza cuando no encuentra un CLAUDE.md o CLAUDE.local.md en el directorio de trabajo o sus superiores; la configuración puede cambiar qué archivos carga. Comprueba la versión, la configuración y los archivos realmente cargados antes de mantener instrucciones duplicadas. El nombre por sí solo no acredita que una aplicación las esté utilizando.
Comprobar que el contexto sirve
Empieza con una tarea pequeña y reversible. Pide que se identifiquen instrucciones y archivos relevantes, y comprueba que el plan respeta el alcance. Luego revisa el resultado real. Puedes apoyarte en un procedimiento de trabajo breve para mantener esa secuencia y en la guía de datos y permisos al usar IA para separar orientación de autorización. El archivo aporta continuidad cuando ayuda a decidir; pierde valor cuando nadie sabe qué parte sigue siendo cierta.
Fuente oficial revisada: 17 de noviembre de 2026. Guía documental con una empresa ficticia; no describe una sesión ejecutada ni resultados medidos.