Cómo le explico un proyecto a Claude Code

Cada mañana abría Claude Code y le contaba otra vez lo mismo: qué es el proyecto, dónde está cada cosa, qué no tiene que tocar. Como quien le explica la casa a un fontanero nuevo cada día, aunque el fontanero sea el mismo. Un día me cansé y decidí medirlo: una semana sin darle ningún contexto fijo y otra con un fichero de instrucciones escrito por mí. Aquí va lo que pasó.

La promesa la conoces: «con un buen prompt, la inteligencia artificial entiende tu proyecto». Hay vídeos enteros con plantillas mágicas, listas de palabras que hay que poner al principio y frases del tipo «actúa como un programador sénior con veinte años de experiencia».

Yo ya había escrito sobre cómo pedirle las cosas sin fórmulas, y allí contaba que lo que funciona es explicar bien la tarea, no recitar un conjuro. Pero con Claude Code el problema es otro. No se trata de una pregunta suelta, sino de un proyecto que dura semanas, con sus manías, sus nombres y sus zonas delicadas. Y cada sesión nueva empieza con la memoria en blanco.

El proyecto de la prueba fue la web de uno de mis blogs: las plantillas, un pequeño script que prepara los artículos para publicar y la configuración del servidor donde vive. Es mío, no de un cliente, y lo conozco bien, que era lo importante para poder juzgar lo que hacía el agente.

La primera semana, del 19 al 25 de octubre de 2026, trabajé como lo hace casi todo el mundo al principio: abría una sesión, explicaba lo que quería en ese momento y listo. Nada guardado de un día para otro. Fueron cinco sesiones, unas siete horas en total.

Apunté cada vez que tenía que repetir algo o corregir un error que venía de no saber cómo es el proyecto. El resultado fue este:

• Me preguntó cuatro veces en qué carpeta estaban las plantillas, aunque la respuesta era siempre la misma.
• Dos veces creó ficheros con nombres en inglés y guiones bajos, cuando en todo el proyecto uso español y guiones medios.
• Una vez intentó instalar una librería nueva para algo que ya hacía una que el proyecto tenía.
• Y una vez tocó la configuración del servidor para arreglar un problema de las plantillas, cuando esa configuración no se toca sin que yo lo diga.

En total, once correcciones que no tenían nada que ver con la tarea, sino con no conocer la casa. Calculo que se me fueron unos 70 minutos solo en explicar otra vez lo que ya había explicado.

Aquí no hay misterio ni mala voluntad. El modelo no recuerda las conversaciones anteriores: cada sesión es un folio en blanco. Lo que sabe del proyecto lo averigua leyendo ficheros al empezar, y lo que no está escrito en ningún sitio, como mis convenciones o las zonas prohibidas, no lo puede adivinar.

Además, lo que sí le cuentas en una sesión larga se va diluyendo. Es lo que ya me pasó con DeepSeek Harness: en sesiones largas empezaba a olvidar instrucciones del principio. Con Claude Code me pasa menos, pero pasa.

Así que el batacazo de la primera semana no fue un fallo del agente. Fue lo que se puede esperar de alguien listo que llega cada mañana sin saber nada de ti.

Claude Code lee al empezar un fichero llamado CLAUDE.md que se deja en la carpeta del proyecto. Es texto normal, en Markdown, y funciona como la nota que le dejas al compañero que te sustituye: qué es esto, cómo se trabaja aquí y qué no se toca. Hay una orden, /init, que te prepara un primer borrador leyendo el proyecto.

Lo generé con esa orden y el borrador me pareció correcto pero genérico: describía las carpetas y poco más. Lo reescribí yo en unos 40 minutos.

La segunda semana, del 26 de octubre al 1 de noviembre, repetí el mismo tipo de trabajo con el fichero ya en su sitio. También cinco sesiones, algo menos de siete horas.

Las correcciones de contexto bajaron de once a tres. Ninguna pregunta por la carpeta de las plantillas, ningún nombre en inglés y ninguna visita a la configuración del servidor. Las tres que quedaron fueron cosas que yo no había escrito: una sobre el formato de las fechas en los artículos y dos sobre cómo quiero que me enseñe los cambios antes de aplicarlos. Las añadí al fichero ese mismo día.

Después de la prueba, el mío tiene unas 60 líneas y siete apartados. Sin adornos:

1. Qué es el proyecto, en tres líneas. Para quién es y qué hace. Nada de historia.
2. Cómo está organizado. Las carpetas importantes y para qué sirve cada una.
3. Cómo se prueba. La orden que hay que ejecutar para comprobar que todo sigue funcionando. Esto es lo que más rinde, porque le permite verificar su propio trabajo en vez de decirme «hecho» a ciegas.
4. Convenciones. Idioma de los nombres, formato de fechas, estilo de los textos.
5. Lo que no se toca. La configuración del servidor, los ficheros con claves y la carpeta de artículos ya publicados.
6. Cómo quiero trabajar. Cambios pequeños, uno cada vez; enseñarme el plan antes de tocar más de dos ficheros; no instalar nada sin preguntar.
7. Errores conocidos. Cosas que ya han salido mal y cómo se evitan.

El apartado 5 no sustituye a los permisos. Una instrucción escrita es una petición, no una cerradura: el agente la respeta casi siempre, y «casi» es una palabra que no me gusta cuando hablamos de claves. Lo que de verdad no debe tocar se lo cierro también con la configuración de permisos, como cuento en Los problemas de trabajar con agentes.

Tan importante como lo anterior. Esto se queda fuera:

• Claves, contraseñas y direcciones de servidores. El fichero vive dentro del proyecto y viaja con él. Si algún día el proyecto acaba en un repositorio compartido, el fichero va detrás.
• Recetas de prompt. Nada de «eres un experto» ni de frases en mayúsculas. Probé a poner un par de ellas un día y no noté ninguna diferencia; las quité. Lo que ayuda es información concreta, no tono.
• Todo lo que se puede leer en el código. Si el agente lo va a encontrar abriendo un fichero, no hace falta copiarlo. Solo añade texto que leer y que mantener.
• Documentación larga. Si hay un manual, pongo dónde está y en qué casos leerlo, no el manual entero.

Esto encaja con lo que suele decirse de cómo hacer buenos prompts: lo que cuenta es el contexto que das, no la fórmula con la que lo envuelves. Lo que llaman prompt engineering se parece, en el día a día, más a escribir buenas notas de traspaso que a encontrar palabras mágicas.

El fichero no se escribe una vez y ya. Tengo tres costumbres:

• Cada corrección que repito dos veces, al fichero. Si le he tenido que decir lo mismo en dos sesiones distintas, eso es una línea nueva.
• Cuando algo cambia en el proyecto, el fichero cambia con él. Una carpeta que renombré a mitad de la segunda semana me demostró por qué: el agente siguió buscándola con el nombre viejo, porque así lo ponía mi fichero, y me hizo perder un cuarto de hora. Un fichero desactualizado es peor que no tenerlo, porque el agente se fía de él.
• Una revisión corta al mes. Quito lo que ya no aplica. Si crece sin control, deja de leerse, también por parte del agente.

A veces le pido al propio Claude Code que proponga cambios al fichero al terminar una sesión larga: «¿Qué has tenido que averiguar hoy que no estaba escrito?». Las propuestas son útiles una de cada dos veces; las reviso y copio solo las que me convencen. Lo que no hago es dejarle editarlo solo. Es mi fichero de reglas; si las reglas las escribe el que tiene que cumplirlas, mal vamos.

Esto es una comparación casera, con un solo proyecto y dos semanas. La segunda semana yo ya conocía mejor mis propias manías, y eso también cuenta. No es un experimento de laboratorio. Pero la diferencia fue lo bastante grande como para no tener dudas del sentido, aunque las cifras exactas cambien en otro proyecto.

Tampoco he probado a fondo los ficheros de instrucciones generales, los que valen para todos los proyectos a la vez. Tengo uno con cuatro líneas sobre el idioma y el estilo, y ahí lo dejo: no sé medir su efecto.

¿Hay algo de verdad en la promesa? Sí, pero en otra parte de donde la ponen. Un buen prompt ayuda en una tarea suelta. En un proyecto que dura semanas, lo que cambia el resultado es el contexto escrito y mantenido, no el truco de redacción.

¿Qué me costó? Unos 40 minutos escribir el fichero y unos 10 minutos a la semana mantenerlo. ¿Qué me ahorró? Unos 50 minutos de explicaciones en una semana de trabajo, y algo que no se mide igual de bien: la tranquilidad de no encontrarme la configuración del servidor tocada por sorpresa.

Si trabajas con Claude Code en algo que dura más de una tarde, empieza hoy tu fichero. Diez líneas bastan: qué es, cómo se prueba y qué no se toca. Luego crecerá solo, a base de correcciones. Si lo que estás haciendo es una aplicación entera, en Construir una aplicación con agentes se ve qué pasa cuando el contexto se queda corto.