Blueprint.md
Claude Code empieza perfecto y a las tres horas rompe lo que ya servía. No es que se canse: cada sesión arranca con la ventana de contexto en blanco. La solución es un archivo de seis secciones en la raíz de tu proyecto que se carga solo al arrancar y se reescribe solo al cerrar.
De qué va
Escribirlo a mano cada noche no es el punto. El punto son las tres piezas que lo vuelven automático.
La línea @blueprint.md dentro de tu CLAUDE.md hace que el archivo se expanda y entre en contexto al arrancar cada sesión, sin que se lo pidas. El bloque de reglas le dice en qué cinco momentos volver a escribirlo. Y el comando /blueprint está para cuando la regla no basta. La sección 5 del archivo, los intentos fallidos con su fecha y su motivo, es la que evita que mañana te estrelles contra la misma pared que hoy.
Y la sección que casi nadie escribe: la poda, porque un documento que solo crece es el mismo problema con otro nombre. Si lo que buscas es diseñar un proyecto que todavía no existe, esa es otra herramienta y otra guía: aquí no se diseña nada, se guarda dónde te quedaste.
Las nueve secciones
Empieza perfecto y a las tres horas rompe lo que ya servía
Qué se pierde de verdad al cerrar la conversación, y por qué el resumen no lo recupera.
Seis secciones, y la quinta es el oro
Los seis encabezados literales, qué va en cada uno y qué nunca va.
El prompt que lo escribe antes de que cierres
Tres pasos que ya funcionan sin configurar nada. Todo lo demás existe para quitártelos.
Mencionar un archivo no lo carga. La arroba sí
La diferencia entre «lee esto» y «esto ya está leído», y cómo se comprueba.
Cinco momentos en los que lo vuelve a escribir sin que se lo pidas
El bloque de reglas para tu CLAUDE.md, con el aviso honesto de hasta dónde llega.
/blueprint, para cuando la regla no basta
El SKILL.md completo, con frontmatter de dos campos y nada inventado.
Un documento que solo crece es el mismo problema con otro nombre
El techo de 120 líneas, las cuotas por sección y las cinco reglas de retiro.
Blueprint, /compact, la memoria automática y la skill handoff
Siete preguntas de frente. No compiten: se reparten el trabajo.
Cuatro cosas que puedes abrir y ver
Las cuatro señales de que el archivo está vivo y los tres modos de falla.
Ficha
Antes de empezar
- Nivel
- Intermedio — no se escribe código, pero sí se tocan dos archivos de tu proyecto. Los dos vienen con su prompt para que Claude los deje puestos por ti.
- Qué necesitas
- Claude Code instalado y un proyecto en el que ya estés trabajando. Si ese proyecto todavía no tiene CLAUDE.md, la sección 04 hace que Claude lo cree.
- Qué NO necesitas
- Instalar nada extra, pagar nada ni saber git. El blueprint es un archivo de texto y las tres piezas son configuración que ya trae Claude Code.
- Cuánto toma
- Unos 15 minutos montarlo la primera vez. Después son treinta segundos al cerrar cada sesión, y de eso se encarga la regla.
- Qué te llevas
- Un archivo de menos de 120 líneas que tu próxima sesión ya tiene leído al arrancar, con los callejones sin salida escritos para no volver a entrar en ellos.
- Verificado
- 21 de septiembre de 2026, contra la documentación oficial de Claude Code.
01 · El síntoma
Empieza perfecto y a las tres horas rompe lo que ya servía
La escena es siempre la misma. Arrancas el día, le explicas el proyecto, trabajan bien un par de horas. Y en algún momento propone deshacer algo que ya estaba resuelto, o toca un archivo que nadie le pidió, o vuelve a sugerir exactamente lo que probaron en la mañana y no sirvió.
No es que se canse ni que se ponga tonto a media tarde. Es que cada sesión nueva arranca con la ventana de contexto en blanco: lo que acordaron ayer no existe para él hasta que alguien se lo vuelva a contar. Y contarlo otra vez, a mano, toma veinte minutos y siempre se te olvida la mitad.
El resumen automático tampoco te salva, porque se arma adivinando qué fue importante. Arrastra los callejones sin salida como si siguieran vivos y tira lo que sí servía. Un resumen es una opinión sobre la conversación; lo que hace falta mañana es un dato.
Mañana sin archivo
Abres la carpeta, escribes «seguimos con lo de ayer» y te pasas veinte minutos contando la historia. Lo que se te olvide contarle, él no lo pregunta: lo supone.
Mañana con archivo
Abres la carpeta y el objetivo, el punto exacto donde quedó y los archivos en juego ya están adentro. Empiezas por el siguiente paso, no por el resumen.
Mañana sin archivo
Propone la solución que ayer probaron dos horas y no funcionó, con el mismo entusiasmo de la primera vez. Y como suena razonable, tú tardas en acordarte de que ya la probaron.
Mañana con archivo
Esa solución está escrita con su fecha y su motivo. Si la vuelve a proponer, le enseñas la línea y se acabó la discusión en diez segundos.
Mañana sin archivo
Toca de paso un archivo que ya estaba bien, porque no sabe que ya estaba bien. Te enteras dos horas después, cuando algo que funcionaba dejó de funcionar.
Mañana con archivo
Hay una lista corta de los archivos que están en juego esta semana. Lo que no aparece en esa lista no se toca sin preguntar.
Lo que se pierde no es el código
El código sigue ahí cuando vuelves: está en el disco y no se va a ningún lado. Lo que se pierde es el alrededor — por qué se hizo así, qué se descartó y a cambio de qué, qué se intentó primero y por qué no sirvió. Eso nunca estuvo en un archivo: estaba en la conversación. Y la conversación se cierra.
Hay una diferencia con la guía vecina que vale la pena decir en voz alta, porque parece una contradicción y no lo es.
El prompt de compactar con foco de cuando Claude se vuelve tonto a media sesión le dice al modelo, con todas sus letras, que puede resumir «exploraciones, intentos fallidos y detalles que ya no importan». Ahí los tira a propósito, y está bien que los tire: dentro de la misma sesión ese material ya cumplió y lo único que hace es comerse la ventana. Aquí el problema es otro —no hoy, mañana— y por eso los intentos fallidos son justo lo único que no se tira nunca.
Así que lo que sigue no es un resumen de la conversación. Es un archivo del proyecto, con seis secciones fijas, que se lee en treinta segundos, se abre cuando quieras y no depende de que nadie se acuerde de nada.
02 · El archivo
Seis secciones, y la quinta es el oro
El archivo se llama blueprint.md y vive en la raíz del proyecto, junto al CLAUDE.md. Son seis encabezados, siempre los mismos y siempre en el mismo orden. Los nombres no se cambian: el bloque de reglas y el comando que vienen más adelante los usan para saber dónde escribir cada cosa.
Las primeras cuatro secciones las tiene cualquier documento de traspaso. La quinta es la que casi nadie escribe y es la única que te ahorra un día entero: lo que ya se intentó y no funcionó, con su fecha y su motivo.
blueprint.md — el esqueleto completo
# Blueprint — <nombre del proyecto> <!-- Actualizado: AAAA-MM-DD HH:MM --> ## 1. Qué quiero lograr ## 2. En qué punto está ## 3. Archivos en juego ## 4. Cambios hechos ## 5. Intentos fallidos — no repetir ## 6. Siguientes pasos
1. Qué quiero lograr
- Qué va
- El resultado que buscas, en una o dos frases y en tus palabras.
- Qué nunca va
- El plan técnico. El plan cambia cada semana; el objetivo casi nunca.
2. En qué punto está
- Qué va
- Dónde quedó todo hoy: qué corre, qué está a medias, qué falta probar.
- Qué nunca va
- El relato de cómo llegaste ahí. Es un estado, no un historial.
3. Archivos en juego
- Qué va
- Las rutas que estás tocando, con una línea diciendo para qué sirve cada una.
- Qué nunca va
- El árbol del proyecto entero. Eso ya lo puede ver él solo.
4. Cambios hechos
- Qué va
- Lo que quedó y todavía no está commiteado, o lo que cambió una decisión anterior.
- Qué nunca va
- Lo que el historial de git ya cuenta mejor y más completo que tú.
5. Intentos fallidos — no repetir
- Qué va
- Qué probaste, qué buscabas y por qué falló. Con fecha, una línea por intento.
- Qué nunca va
- «No funcionó» a secas. Sin el motivo no evita nada, y ocupa igual.
6. Siguientes pasos
- Qué va
- Máximo cinco, y cada uno nombra un archivo concreto.
- Qué nunca va
- Ideas para algún día. Eso es otra lista y otro archivo.
| Sección | Qué va | Qué nunca va |
|---|---|---|
| 1. Qué quiero lograr | El resultado que buscas, en una o dos frases y en tus palabras. | El plan técnico. El plan cambia cada semana; el objetivo casi nunca. |
| 2. En qué punto está | Dónde quedó todo hoy: qué corre, qué está a medias, qué falta probar. | El relato de cómo llegaste ahí. Es un estado, no un historial. |
| 3. Archivos en juego | Las rutas que estás tocando, con una línea diciendo para qué sirve cada una. | El árbol del proyecto entero. Eso ya lo puede ver él solo. |
| 4. Cambios hechos | Lo que quedó y todavía no está commiteado, o lo que cambió una decisión anterior. | Lo que el historial de git ya cuenta mejor y más completo que tú. |
| 5. Intentos fallidos — no repetir | Qué probaste, qué buscabas y por qué falló. Con fecha, una línea por intento. | «No funcionó» a secas. Sin el motivo no evita nada, y ocupa igual. |
| 6. Siguientes pasos | Máximo cinco, y cada uno nombra un archivo concreto. | Ideas para algún día. Eso es otra lista y otro archivo. |
La línea de la sección 5, exacta
Cada intento fallido es una línea con guion y la fecha entre corchetes, no un encabezado. Tiene tres partes y las tres hacen falta: qué probaste, qué buscabas con eso, y qué pasó exactamente.
El formato, y un ejemplo real
- [AAAA-MM-DD] Probé <qué> para <qué buscaba> → falló porque <qué pasó>. No repetir. - [2026-09-18] Probé mover la validación al middleware para que corriera antes del render → falló porque ahí no hay acceso a la sesión. No repetir.
El motivo es la mitad que sirve. Una línea que dice «probamos el middleware y no jaló» no evita nada: el mes que entra alguien lo vuelve a intentar convencido de que esta vez sí. La que dice por qué falló cierra la puerta.
La línea de arriba no es decorado
La fecha y la hora de «Actualizado» son la primera de las cuatro señales con las que vas a saber si el archivo sigue vivo o ya se murió. Un blueprint que dice que se tocó hace tres semanas, en un proyecto donde trabajaste ayer, te está diciendo que nadie lo está manteniendo — y que lo que dice adentro ya no es cierto.
La plantilla, ya envuelta en un prompt
Pégaselo a Claude Code dentro de la carpeta de tu proyecto. Crea el archivo con los seis encabezados y llena solo lo que ya pueda ver.
Crea un archivo llamado blueprint.md en la raíz de este proyecto, con exactamente estos seis encabezados y en este orden:
# Blueprint — <el nombre de este proyecto>
<!-- Actualizado: AAAA-MM-DD HH:MM -->
## 1. Qué quiero lograr
## 2. En qué punto está
## 3. Archivos en juego
## 4. Cambios hechos
## 5. Intentos fallidos — no repetir
## 6. Siguientes pasos
Reglas para llenarlo:
- Llena nada más lo que ya puedas ver del proyecto. Lo que no sepas, déjalo vacío: prefiero un hueco a una suposición tuya.
- La sección 2 se escribe como un estado ("el login ya corre, falta el correo de confirmación"), no como el relato de cómo llegamos ahí.
- En la 3 va una línea por archivo: la ruta y para qué sirve. No pegues código.
- En la 5, cada línea va así, con guion y la fecha entre corchetes:
- [AAAA-MM-DD] Probé <qué> para <qué buscaba> → falló porque <qué pasó>. No repetir.
- En la 6, máximo cinco pasos, y cada uno nombra un archivo.
- Pon la fecha y la hora de hoy en la línea Actualizado.
Cuando termines, enséñame el archivo completo y dime cuántas líneas quedó.Esto no es The Architect
Si ya conoces The Architect, ojo con la palabra: allá y aquí no significan lo mismo. Allá el plano tiene veinte secciones y se escribe antes de que el proyecto exista, para que otro Claude lo construya sin preguntarte nada. Este tiene seis, se escribe después de una sesión de trabajo y solo le sirve a tu siguiente sesión. Uno diseña lo que todavía no existe; el otro guarda dónde te quedaste. Los dos pueden vivir en la misma carpeta sin estorbarse.
Si lo que necesitas es lo primero, diseñar un proyecto que todavía no existe es esa guía y no esta. Vuelve aquí cuando ya estés construyéndolo.
03 · A mano, hoy
El prompt que lo escribe antes de que cierres
Antes de automatizar nada, el ritual completo son tres pasos y ya funciona hoy, sin configurar absolutamente nada. Si solo vas a hacer una cosa de esta guía, haz esta: el archivo escrito a mano ya te ahorra los veinte minutos de mañana.
Se lo pides antes de irte
Cuando ya no vas a seguir hoy, antes de cerrar la terminal, le pides que escriba el blueprint. Toma medio minuto y es lo único que hay que acordarse de hacer.
Limpias la conversación
Con /clear o abriendo una conversación nueva. El archivo ya está en el disco: no se va con la conversación, y es justo eso lo que lo hace servir.
Mañana le dices que lo lea y siga
Una frase. Lee el archivo, te repite lo que entendió y espera. No arranca a escribir código hasta que tú le digas por dónde, y ese detalle evita la mitad de los destrozos.
El prompt de cierre
Guarda dónde nos quedamos
Pídelo antes de cerrar. Reescribe el archivo entero, y la sección 5 la llena con lo que hoy no funcionó.
Vamos a cerrar por hoy. Antes de que me vaya, escribe o actualiza blueprint.md en la raíz del proyecto con el estado de esta sesión. Si ya existe, léelo completo y reescríbelo entero: no agregues al final. Lo que va en cada sección: 1. Qué quiero lograr — el objetivo en una o dos frases. Si no cambió hoy, déjalo igual. 2. En qué punto está — dónde quedó todo: qué corre, qué está a medias, qué falta probar. 3. Archivos en juego — los que tocamos hoy y los que vamos a tocar mañana, con una línea cada uno. 4. Cambios hechos — solo lo que todavía no está commiteado, o lo que cambió una decisión anterior. 5. Intentos fallidos — no repetir — todo lo que probamos hoy y no funcionó, con esta forma: - [la fecha de hoy] Probé <qué> para <qué buscaba> → falló porque <qué pasó>. No repetir. Esta es la sección que importa. Si algo falló y no lo escribes, mañana lo volvemos a intentar. 6. Siguientes pasos — máximo cinco, cada uno nombrando un archivo. Actualiza la línea Actualizado con la fecha y la hora de ahora. Al final dime en una sola línea qué cambiaste y cuántas líneas quedó el archivo.
Cerrar la conversación sin cerrar el proyecto
/clearBorra el contexto de la sesión y te deja la carpeta exactamente igual. El blueprint no se va con él: está en el disco, como cualquier otro archivo del proyecto. Si prefieres, abrir una conversación nueva hace lo mismo.
El de mañana
Lee el archivo y espérame
La primera frase del día siguiente. La parte importante es la última línea: que lea, resuma y no toque nada.
Lee blueprint.md, que está en la raíz de este proyecto, y no hagas nada más todavía. Cuando lo tengas, dime en cinco líneas: - cuál es el objetivo - en qué punto quedamos - qué archivos están en juego - qué NO hay que volver a intentar, y por qué falló - cuál es el siguiente paso Después espera. No escribas ni una línea de código hasta que yo te diga por dónde arrancamos.
Los tres pasos van a dejar de ser tuyos
Esto ya sirve tal cual. El problema es que depende de que te acuerdes, y el día que llevas seis horas trabajando y te cae una junta, no te acuerdas. Lo que sigue en esta guía es quitarte los pasos de encima: la sección 04 se lleva el paso 3 —el archivo entra solo al arrancar, sin que se lo pidas— y la sección 05 se lleva el paso 1, que es el que de verdad se olvida.
04 · Se carga solo
Mencionar un archivo no lo carga. La arroba sí
Mencionar un archivo en el CLAUDE.md no lo carga: deja la instrucción de abrirlo, que a veces se cumple y a veces no. La arroba sí lo carga. Escribir «lee blueprint.md antes de empezar» y escribir la arroba delante del nombre no son dos formas de decir lo mismo.
Un CLAUDE.md puede importar otros archivos con la arroba, y los importados se expanden y entran en contexto al arrancar, junto al CLAUDE.md que los referencia. Es la diferencia entre «lee esto» y «esto ya está leído».
La sintaxis en sí —cómo se escriben las rutas, hasta dónde encadena— ya está contada en cómo se estructura un CLAUDE.md, así que aquí no se repite. Lo que cambia es el uso: casi todo el mundo importa reglas, que casi nunca cambian. Importar un archivo de estado, que se reescribe cada sesión, es lo que vuelve el arranque distinto.
Tres detalles que muerden
- El lector se salta el código. Si escribes la línea del import entre comillas invertidas o adentro de un bloque de código, se queda como texto y no importa nada. Pasa más de lo que parece, porque la gente la pone dentro de un ejemplo.
- Si el import apunta a un archivo que queda fuera de la carpeta de trabajo, Claude te pide aprobación la primera vez. Si dices que no —o si no estabas mirando—, el archivo simplemente no entra, y después nadie te avisa.
- La cadena tiene un límite de cuatro saltos: un archivo que importa a otro que importa a otro. Para lo de aquí sobra, porque el blueprint lo importa tu CLAUDE.md directo, sin escalas.
Déjalo importado, pero enséñame dónde
No dicta la ruta: primero busca cuál CLAUDE.md se carga de verdad en tu proyecto, lo dice, y después escribe el import relativo a ese archivo.
Quiero que blueprint.md entre en contexto solo, cada vez que arranque una sesión en este proyecto. Hazlo en este orden: 1. Busca cuál es el CLAUDE.md que de verdad se carga aquí. Puede haber más de uno: el de esta carpeta, el de una carpeta de arriba, el de mi usuario. Dime cuál encontraste y en qué ruta está, antes de tocar nada. 2. Si en este proyecto no hay ninguno, créalo en la raíz. 3. Agrégale la línea de import de blueprint.md, en su propia línea y FUERA de cualquier bloque de código o comillas invertidas. La ruta va relativa a ESE archivo, no a la raíz del proyecto ni a donde yo esté parado. Si blueprint.md todavía no existe, créalo con los seis encabezados vacíos. 4. Enséñame las líneas que quedaron, con la de antes y la de después, para que yo vea dónde cayó. 5. Dime qué tengo que buscar exactamente en la lista de Memory files cuando corra /context, para confirmar que sí cargó. Si la línea ya estaba puesta, no la dupliques: dímelo y pasa al punto 5.
La comprobación es una sola y no admite interpretación: corre /context y busca blueprint.md en la lista de Memory files. Si no aparece ahí, el import no está funcionando, por más bien que se vea la línea en el archivo.
Ver qué se cargó de verdad al arrancar
/contextAbrir el CLAUDE.md sin buscarlo en el explorador
/memory/context · lo que tienes que ver bajo Memory files
Memory files CLAUDE.md el del proyecto blueprint.md importado desde CLAUDE.md
La forma exacta de la lista depende de tu instalación y de cuántos archivos de memoria tengas. Lo que no cambia es que blueprint.md tiene que salir ahí. Si sale el CLAUDE.md pero no el blueprint, el import está adentro de un bloque de código o la ruta está mal.
Lo que esto cuesta, dicho de una vez
El archivo importado ocupa contexto en cada arranque, hayas avanzado ayer o no. Un blueprint de 400 líneas te cobra 400 líneas todos los días, y encima le quita espacio a lo que sí vas a hacer hoy. Por eso vive aparte del CLAUDE.md en vez de estar pegado adentro, y por eso la sección 07 de esta guía es sobre qué se le borra. Esa sección es la factura de esta.
Y si lo que quieres es que varios agentes compartan notas, en vez de que tu próxima sesión retome una tarea, eso es otra cosa y tiene su propia guía: el cuaderno compartido de memory-palace. Ahí los archivos no se cargan al arrancar: se abren cuando hacen falta, y por eso allá el tamaño no se paga igual que aquí.
05 · Se reescribe solo
Cinco momentos en los que lo vuelve a escribir sin que se lo pidas
El archivo ya entra solo al arrancar. Falta la otra mitad: que se actualice solo al cerrar, sin que tú te acuerdes. Eso se consigue con un bloque de reglas dentro de tu CLAUDE.md que dice cuándo hay que reescribirlo. Son cinco momentos, y están puestos en ese orden por algo: el segundo es el que de verdad cambia tu semana.
Cuando cerramos
Cuando escribas /clear, o le digas que cerramos, o que se ven mañana. Es el disparador que más se usa y el que hace que el archivo esté al día cuando vuelvas a abrir.
Cuando algo no funciona
Cuando algo que intentaron no sirva, esa línea entra a la sección 5 en el momento, no al final del día. Al final del día ya no te acuerdas del motivo, y el motivo es la mitad que evita el segundo intento.
Cuando terminan un paso
Cuando terminen un paso de la sección 6, sale de la 6. Y no entra a la 4 si ya quedó commiteado: para eso está el historial de git, que lo cuenta mejor.
Cuando cambia el objetivo
Cuando cambie el objetivo de la sección 1, el archivo no se edita: se archiva completo y nace uno nuevo. Un blueprint con dos objetivos encimados no sirve para ninguno de los dos.
Cuando llevas rato sin tocarlo
Cuando lleven más de una hora de trabajo sin haberlo tocado. Es la red debajo de los otros cuatro: si ninguno se disparó y ya pasó una hora, algo se les fue.
El bloque de reglas, para pegar en tu CLAUDE.md
Cópialo y pégalo al final de tu CLAUDE.md, tal cual. Si prefieres no abrir el archivo, usa el de abajo.
## blueprint.md — cuándo se reescribe En la raíz de este proyecto vive blueprint.md: el estado de la tarea en curso, en seis secciones numeradas. Reescríbelo entero —nunca agregues al final— en estos cinco momentos: 1. Cuando escriba /clear, o te diga que cerramos, o que nos vemos mañana. 2. Cuando algo que intentamos no funcione. Esa línea entra a la sección 5 en el momento, no al final del día, con esta forma: - [AAAA-MM-DD] Probé <qué> para <qué buscaba> → falló porque <qué pasó>. No repetir. 3. Cuando terminemos un paso de la sección 6: sale de la 6. Y no entra a la 4 si ya quedó commiteado, que para eso está git. 4. Cuando cambie el objetivo de la sección 1: el archivo no se edita. Se archiva completo en docs/blueprint-archivo.md y nace uno nuevo. 5. Cuando llevemos más de una hora de trabajo sin haberlo tocado. Cada vez que lo escribas, actualiza la línea Actualizado con la fecha y la hora, y déjalo por debajo de 120 líneas. Si se pasa, poda la sección 4 primero y la 5 al final.
Instálamelo tú
Para quien no quiere tocar archivos: localiza el CLAUDE.md correcto, le agrega la sección, enseña solo lo que agregó y dice cuántas líneas quedó.
Quiero que mantengas blueprint.md solo, sin que yo te lo pida cada vez. 1. Localiza el CLAUDE.md que de verdad se carga en este proyecto y dime cuál es antes de tocar nada. Si no hay ninguno, créalo en la raíz. 2. Agrégale al final una sección nueva titulada "blueprint.md — cuándo se reescribe", que diga que tienes que reescribir el archivo entero en estos cinco momentos, sin quitar ni agregar ninguno: - cuando yo escriba /clear, diga que cerramos o que nos vemos mañana; - cuando algo que intentamos no funcione, y esa línea entra a la sección 5 en el momento, con la fecha y el motivo; - cuando terminemos un paso de la sección 6, que sale de la 6 y no entra a la 4 si ya quedó commiteado; - cuando cambie el objetivo de la sección 1, que no se edita: se archiva completo y nace uno nuevo; - cuando llevemos más de una hora de trabajo sin haberlo tocado. Agrega también que cada reescritura actualiza la línea Actualizado y deja el archivo por debajo de 120 líneas, podando la sección 4 primero y la 5 al final. 3. No toques ninguna otra parte del CLAUDE.md. Enséñame nada más lo que agregaste. 4. Dime cuántas líneas quedó el CLAUDE.md en total. Si se pasó de 200, dime qué otra cosa de ahí adentro te parece que sobra.
Lo que esta regla no te puede prometer
El CLAUDE.md es contexto, no configuración obligatoria. Lo que escribes ahí entra a la conversación como instrucciones muy bien puestas, no como un interruptor del programa: la regla se cumple la mayoría de las veces, no siempre. Y de lo primero que se afloja es cuando la sesión va larga y llena, que es justo cuando más falta hace. Por eso existe la sección siguiente — el comando no depende de que se acuerde.
En la práctica, con las dos piezas puestas, el archivo se mantiene solo la mayor parte del tiempo y tú nada más lo revisas de vez en cuando. Cómo revisarlo en treinta segundos está en la última sección.
06 · A demanda
/blueprint, para cuando la regla no basta
La regla de la sección anterior funciona casi siempre. El comando es para el casi: lo escribes tú, en el momento que quieras, y no depende de que nadie se acuerde. Escribes /blueprint y el archivo queda actualizado.
Hoy la forma recomendada de crear un comando propio es una habilidad: un archivo SKILL.md dentro de .claude/skills/blueprint/. Los comandos personalizados se fusionaron con las habilidades. El camino viejo, .claude/commands/blueprint.md, sigue funcionando, y los dos crean /blueprint — pero no pongas los dos, porque entonces hay dos versiones peleándose.
Dónde va el archivo
tu-proyecto/
CLAUDE.md ← aquí va el import y el bloque de reglas
blueprint.md ← el archivo de estado
.claude/
skills/
blueprint/
SKILL.md ← esto es lo que crea /blueprintEl frontmatter va con dos campos y nada más
name y description. Vas a ver por ahí otros campos —argument-hint, allowed-tools, disable-model-invocation— y se ven útiles, pero están documentados para los comandos, no para el SKILL.md. Agregarlos aquí por deducción es la forma más rápida de que el archivo no cargue y de que te pases la tarde buscando por qué. Si el bloque de abajo te parece corto de más arriba, está bien así.
La descripción es lo que decide cuándo se dispara
La segunda línea del frontmatter no es un resumen para que se vea bonito: es lo que Claude lee para decidir si esta habilidad aplica. Por eso la del bloque de abajo nombra las frases que tú vas a escribir de verdad —cerramos, guarda dónde nos quedamos, esto no funcionó— y no solo el nombre del comando.
SKILL.md — el archivo completo
Cópialo entero, con el frontmatter y todo. Trae las seis secciones, el formato de la línea 5, las cuotas y las reglas de retiro.
--- name: blueprint description: Escribe o actualiza blueprint.md en la raíz del proyecto con el estado de la tarea en curso — objetivo, punto actual, archivos en juego, cambios hechos, intentos fallidos y siguientes pasos. Úsala cuando el usuario escriba /blueprint, cuando cierren la sesión, cuando algo que intentaron no funcione, o cuando pida guardar dónde se quedaron. --- # blueprint Mantiene un solo archivo, blueprint.md, en la raíz del proyecto. Es el estado de UNA tarea en curso: existe para que la siguiente sesión empiece donde terminó esta, y se tira cuando la tarea termina. No es un historial del proyecto ni un diario. ## Qué hacer cuando se te invoca 1. Si blueprint.md no existe, créalo con los seis encabezados de abajo, exactamente así. 2. Si ya existe, léelo completo antes de tocarlo y reescríbelo entero. Nunca agregues al final. 3. Pon la fecha y la hora locales en la línea Actualizado. 4. Aplica las cuotas y las reglas de retiro ANTES de guardar, no después. 5. Al terminar, dime en una línea qué cambió y cuántas líneas quedó el archivo. ## La estructura, literal # Blueprint — <nombre del proyecto> <!-- Actualizado: AAAA-MM-DD HH:MM --> ## 1. Qué quiero lograr ## 2. En qué punto está ## 3. Archivos en juego ## 4. Cambios hechos ## 5. Intentos fallidos — no repetir ## 6. Siguientes pasos Los seis encabezados no se renombran, no se reordenan y no se agregan otros. Otras piezas del proyecto los usan como anclas. ## Qué va en cada sección 1. Qué quiero lograr — el resultado en una o dos frases, en las palabras del usuario. No el plan técnico: el plan cambia, el objetivo casi no. 2. En qué punto está — dónde quedó todo hoy: qué corre, qué está a medias, qué falta probar. Es un estado, no un historial. Se reescribe entera cada vez. 3. Archivos en juego — las rutas que se están tocando, una línea por archivo diciendo para qué sirve. No el árbol del proyecto. 4. Cambios hechos — lo que quedó y todavía no está commiteado, o lo que cambia una decisión anterior. Lo que git log ya cuenta, no. 5. Intentos fallidos — no repetir — lo que se probó y no funcionó, con su motivo. Ver el formato. 6. Siguientes pasos — máximo cinco, y cada uno nombra un archivo concreto. ## El formato de la sección 5 Cada línea, sin excepción y sin encabezados dentro: - [AAAA-MM-DD] Probé <qué> para <qué buscaba> → falló porque <qué pasó>. No repetir. Una línea sin el motivo no sirve: es lo único que evita el segundo intento. Si no sabes por qué falló, escríbelo igual y di que el motivo no quedó claro — eso también es información. ## Cuotas por sección - Sección 1: 5 líneas. Se reescribe entera, nunca acumula. - Sección 2: 5 líneas. Se reescribe entera. - Sección 3: 10 líneas. Solo los archivos que se siguen tocando. - Sección 4: 20 líneas. Es lo primero que se poda. - Sección 5: 30 líneas. Es lo último que se poda. - Sección 6: 10 líneas, máximo 5 pasos. El archivo entero se queda por debajo de 120 líneas. Si al guardar se pasa, poda en este orden: sección 4, luego 3, luego 6, luego 2, luego 1, y solo al final la 5. ## Reglas de retiro 1. Un cambio sale de la sección 4 en cuanto queda commiteado. Si git log ya lo cuenta, el blueprint no. 2. Un paso terminado se borra de la sección 6. No se marca como hecho ni se le pone palomita. 3. Un archivo sale de la sección 3 cuando lleva dos sesiones sin abrirse. 4. Un intento fallido se retira por dos razones, y la antigüedad no es una: o el archivo o la función contra la que se estrelló ya no existe, o alguien lo volvió a intentar y esta vez sí funcionó. En el segundo caso se reescribe como línea de la sección 4, o sube a la 1 si cambió una decisión. 5. Si cambia el objetivo de la sección 1, el archivo no se edita: se archiva completo y nace uno nuevo. Todo lo que se retira se mueve a docs/blueprint-archivo.md, al final, bajo un encabezado con la fecha. Ese archivo no se importa desde CLAUDE.md y no tiene tope de tamaño: se abre a mano cuando alguien pregunta si algo ya se intentó. ## Lo que no se hace - No inventes contenido para llenar una sección. Si la 5 está vacía porque no falló nada, déjala vacía con una línea que lo diga. - No copies fragmentos de código al blueprint. Van las rutas, no el contenido. - No borres una línea de la sección 5 por vieja. - No toques CLAUDE.md desde aquí. Este comando escribe blueprint.md y docs/blueprint-archivo.md, y nada más.
Créamelo tú
Si no quieres crear carpetas a mano: pega esto y, abajo, el bloque de arriba. Te dice dónde quedó y si ya había otra versión.
Créame el comando /blueprint en este proyecto. 1. Crea la carpeta .claude/skills/blueprint/ si todavía no existe. 2. Adentro crea el archivo SKILL.md con exactamente el contenido que va después de la línea de guiones de abajo. Cópialo tal cual: el frontmatter lleva solo dos campos, name y description, y no le agregues ninguno más aunque se te ocurra alguno útil. 3. Cuando lo guardes, dime la ruta completa del archivo y confírmame que el frontmatter quedó con esos dos campos y nada más. 4. Dime también si en este proyecto ya existe .claude/commands/blueprint.md, porque los dos crean /blueprint y no quiero dos versiones peleándose. 5. Al final dime cómo compruebo que ya está disponible. --- <pega aquí el bloque SKILL.md de esta sección>
Y a partir de ahí, en cualquier momento
/blueprintUn hook no puede escribir esto por ti
La pregunta obvia al llegar aquí es si un hook puede hacerlo solo al cerrar. Hoy no: los hooks de tipo prompt son una evaluación de un turno que devuelve su decisión en JSON y no tienen herramientas, y los de tipo agent son experimentales, y lo que está documentado de ellos es que usan Read, Grep y Glob para verificar condiciones y devolver una decisión. Verificar no es escribir.
Con las tres piezas puestas el archivo tiene tres caminos para mantenerse al día: entra solo, se reescribe solo y se puede forzar. Lo que sigue es el problema que acabamos de crear entre las tres, y que casi nadie cuenta.
07 · La poda
Un documento que solo crece es el mismo problema con otro nombre
El techo que viene es criterio mío, no documentación, y conviene decir de dónde sale. La documentación pide apuntar a menos de 200 líneas por CLAUDE.md, y dice que lo importado entra al contexto al arrancar igual que el archivo que lo importa — por qué un CLAUDE.md largo se obedece menos está contado en su propia guía. De ahí sale el reparto: 120 líneas para el blueprint y unas 80 para el CLAUDE.md. Los dos juntos caben en el presupuesto, y ninguno de los dos aplasta al otro.
Acabas de montar un archivo que entra solo cada vez que arrancas y que se reescribe solo cada vez que cierras. Eso tiene una consecuencia que casi ninguna guía menciona: el archivo crece todos los días, avances o no. A la tercera semana son doscientas líneas de las cuales ciento cincuenta ya no son ciertas, y las estás pagando en cada arranque.
Techo duro: 120 líneas
Cuando el archivo se pasa de 120 líneas, no se sube el techo: se poda. Y podar no es resumir ni reescribir más bonito — es retirar líneas y moverlas a otro lado. Si al terminar de podar el archivo no tiene menos líneas que cuando empezaste, no podaste.
La cuota de cada sección
Las cuotas no están repartidas parejo, y ahí está el argumento de todo el archivo: la sección 5 se lleva la cuota más grande y es la última en podarse; la 4, que es la que más rápido engorda, es la primera que se retira.
1. Qué quiero lograr
- Cuota
- 5 líneas
- Cómo se comporta
- Se reescribe entera cada vez. Nunca acumula: si cambió, sustituye; no se agrega abajo.
2. En qué punto está
- Cuota
- 5 líneas
- Cómo se comporta
- Se reescribe entera. Es un estado, no un historial — lo de ayer se borra, no se apila.
3. Archivos en juego
- Cuota
- 10 líneas
- Cómo se comporta
- Solo los que sigues tocando. Un archivo que llevas dos sesiones sin abrir ya no está en juego.
4. Cambios hechos
- Cuota
- 20 líneas
- Cómo se comporta
- Lo primero que se poda. Casi todo lo que hay aquí ya lo cuenta el historial de git.
5. Intentos fallidos
- Cuota
- 30 líneas
- Cómo se comporta
- La cuota más grande y lo último que se poda. Es la razón de ser del archivo.
6. Siguientes pasos
- Cuota
- 10 líneas
- Cómo se comporta
- Máximo cinco pasos. Si hay ocho, dos de ellos son deseos y tres son del mes que entra.
| Sección | Cuota | Cómo se comporta |
|---|---|---|
| 1. Qué quiero lograr | 5 líneas | Se reescribe entera cada vez. Nunca acumula: si cambió, sustituye; no se agrega abajo. |
| 2. En qué punto está | 5 líneas | Se reescribe entera. Es un estado, no un historial — lo de ayer se borra, no se apila. |
| 3. Archivos en juego | 10 líneas | Solo los que sigues tocando. Un archivo que llevas dos sesiones sin abrir ya no está en juego. |
| 4. Cambios hechos | 20 líneas | Lo primero que se poda. Casi todo lo que hay aquí ya lo cuenta el historial de git. |
| 5. Intentos fallidos | 30 líneas | La cuota más grande y lo último que se poda. Es la razón de ser del archivo. |
| 6. Siguientes pasos | 10 líneas | Máximo cinco pasos. Si hay ocho, dos de ellos son deseos y tres son del mes que entra. |
Se borra sin pensarlo
En cuanto lo veas
- Cualquier línea de la sección 4 cuyo cambio ya quedó commiteado. El historial de git lo cuenta mejor, con fecha y autor.
- Los pasos terminados de la sección 6. Se borran, no se marcan: una palomita ocupa la misma línea que el paso.
- Los archivos de la sección 3 que llevas dos sesiones sin abrir.
- Cualquier fragmento de código pegado dentro del blueprint. Aquí van las rutas, no el contenido.
- La sección 2 completa, cada vez que la vuelvas a escribir. Es un estado: lo de ayer no se apila abajo.
No se borra por viejo
Aunque lleve meses ahí
- Una línea de la sección 5 cuyo archivo y cuya función siguen existiendo. Vieja o no, esa pared sigue de pie.
- La decisión de la sección 1, mientras el objetivo no haya cambiado. Si cambió, no se edita: se archiva.
- Un intento fallido que se repitió dos veces. Ese merece estar hasta arriba de la sección 5, no abajo.
- El motivo de un intento fallido, aunque para ganar líneas sea tentador dejar solo el qué. Sin motivo la línea no evita nada.
Las cinco reglas de retiro
- Un cambio sale de la sección 4 en cuanto queda commiteado. Si el historial de git ya lo cuenta, el blueprint no.
- Un paso terminado se borra de la sección 6, no se marca como hecho. Nada de palomitas: la lista es de lo que falta.
- Un archivo sale de la sección 3 cuando llevas dos sesiones sin abrirlo. Si vuelve, se vuelve a poner en una línea.
- Un intento fallido se retira por dos razones, y la antigüedad no es una: o el archivo o la función contra la que se estrelló ya no existe, o alguien lo volvió a intentar y esta vez sí funcionó. En ese segundo caso no se borra — se reescribe como línea de la sección 4, o sube a la 1 si cambió una decisión.
- Si cambia el objetivo de la sección 1, el blueprint no se edita: se archiva completo y nace uno nuevo. Dos objetivos encimados en un archivo no sirven para ninguno.
Sección 4, sin podar
Dieciocho líneas contando, una por una, cada archivo que se tocó en las últimas dos semanas, con el detalle de qué se le cambió. Todas commiteadas. El historial de git dice lo mismo, con fecha, autor y el cambio exacto.
Sección 4, podada
Dos líneas: el cambio de la base de datos que todavía no está commiteado, y la decisión de dejar los correos en cola en vez de mandarlos al momento, porque esa sí cambió algo de la sección 1.
Sección 4, sin podar
Sección 6 con nueve pasos, tres de ellos ya hechos y marcados con una palomita, y dos que dicen «revisar el rendimiento» sin nombrar un archivo.
Sección 4, podada
Cuatro pasos. Los hechos se borraron —no se marcaron—, y los dos vagos se convirtieron en uno concreto que nombra el archivo donde empieza.
Lo podado no se tira: se muda
Todo lo que sale del blueprint se va al final de docs/blueprint-archivo.md, bajo un encabezado con la fecha del día que podaste. Ese archivo no se importa desde el CLAUDE.md, así que no cuesta contexto y no tiene tope de tamaño. Se abre a mano el día que alguien pregunta si esto ya lo intentamos, y ese día vale lo que pesa.
Es la misma idea de siempre: lo que se consulta de vez en cuando se guarda barato, y lo que se lee en cada arranque se paga caro. La poda no es ordenar por gusto — es mover líneas de la columna cara a la barata.
Pódalo, y enséñame la cuenta
Hoy solo se retira: el prompt tiene prohibido agregar. Cuenta antes, cuenta después, y mueve lo podado al archivo de archivo.
Poda blueprint.md. Hoy solo se retira: no le agregues nada. 1. Cuenta cuántas líneas tiene el archivo y cuántas tiene cada una de las seis secciones. Enséñame la cuenta antes de tocar nada. 2. Aplica estas cuotas: sección 1, cinco líneas; sección 2, cinco; sección 3, diez; sección 4, veinte; sección 5, treinta; sección 6, diez y máximo cinco pasos. 3. Para decidir qué sale, usa estas reglas y ninguna otra: - De la 4 sale todo lo que ya quedó commiteado. Revisa git log para confirmarlo, no lo supongas. - De la 6 se BORRAN los pasos terminados. No los marques como hechos ni les pongas palomita. - De la 3 sale todo archivo que llevemos dos sesiones sin abrir. - De la 5 solo sale una línea por dos razones: o el archivo o la función contra la que se estrelló ya no existe, o alguien lo volvió a intentar y esta vez sí funcionó. Que sea vieja NO es razón. 4. Todo lo que retires se mueve al final de docs/blueprint-archivo.md, bajo un encabezado con la fecha de hoy. Créalo si no existe. Ese archivo no se importa desde ningún lado. 5. Enséñame el antes y el después: cuántas líneas tenía, cuántas quedó, y qué se movió. Si después de todo eso el archivo sigue arriba de 120 líneas, dímelo y dime qué te parece que sobra. No decidas tú borrar de la sección 5.
Cambió el objetivo: archívalo y empieza uno nuevo
El quinto disparador de la sección 05, hecho prompt. No edita el viejo: lo archiva completo y rescata solo los intentos fallidos que siguen siendo verdad.
Cambió el objetivo de este proyecto. El blueprint de ahora ya no sirve y no quiero que lo edites. 1. Mueve blueprint.md completo al final de docs/blueprint-archivo.md, bajo un encabezado con la fecha de hoy y una línea que diga cuál era el objetivo viejo. Crea ese archivo si no existe. 2. Crea un blueprint.md nuevo con los seis encabezados, vacío. 3. Del viejo, trae al nuevo SOLO las líneas de la sección 5 que sigan siendo verdad con el objetivo nuevo: las que se estrellaron contra un archivo o una función que todavía existen. Enséñame cuáles trajiste y cuáles dejaste atrás, con el motivo de cada una. 4. La sección 1 la lleno yo. Déjala con una sola línea que diga: pendiente. En docs/blueprint-archivo.md nunca se borra nada. Ahí solo se agrega.
Aquí se mueve, allá se tacha, y las dos están bien
Si ya leíste la guía del cuaderno compartido, ahí lo obsoleto se tacha y se queda en su lugar. No es una contradicción con esto: allá varios agentes leen el mismo cuaderno con su herramienta de lectura, y una línea tachada no cuesta nada hasta que alguien abre el archivo. Aquí el blueprint se carga solo en cada arranque, así que cada línea se cobra todos los días, esté tachada o no. Mismo problema, costo distinto, solución distinta.
Si trabajas con varios agentes sobre el mismo proyecto, el cuaderno de memory-palace y este archivo se llevan bien: el cuaderno guarda lo que el equipo sabe, el blueprint guarda dónde quedó la tarea de hoy.
Con la poda puesta, el archivo deja de crecer y se queda del tamaño de una tarea. Que es lo que es: el estado de una tarea que se va a terminar y después se tira.
08 · Contra qué compite
Blueprint, /compact, la memoria automática y la skill handoff
Las cuatro sirven para que no se pierda lo que ya sabías, y por eso se confunden. Pero guardan cosas distintas, en lugares distintos, decididas por gente distinta. No compiten: se reparten el trabajo, y saber cuál es cuál te ahorra montar la de al lado por equivocación.
Quién decide qué se guarda
- blueprint.md
- Tú, en seis secciones fijas que siempre son las mismas
- /compact
- El modelo, resumiendo la conversación como le parece
- auto memory
- El modelo, cuando le parece que algo vale la pena recordar
- skill handoff
- El modelo, con lo que llevaba la conversación
Dónde vive el archivo
- blueprint.md
- blueprint.md, en la raíz de tu proyecto
- /compact
- En ninguno: reemplaza la conversación y ya
- auto memory
- En ~/.claude/projects/<proyecto>/memory/, fuera de tu proyecto
- skill handoff
- En el directorio temporal del sistema
Viaja a git
- blueprint.md
- Sí, si lo commiteas — y entonces lo ve todo el equipo
- /compact
- No
- auto memory
- No: es de esa máquina, no se comparte entre máquinas ni con la nube
- skill handoff
- No: el temporal se limpia solo
Se carga solo al arrancar
- blueprint.md
- Sí, si lo importas con la arroba desde tu CLAUDE.md
- /compact
- No aplica: vive dentro de la misma sesión
- auto memory
- Sí, está encendida por defecto — pero no se carga en los subagentes
- skill handoff
- No: se lo pasas tú al siguiente agente
Guarda los intentos fallidos
- blueprint.md
- Sí. Es la sección 5 y es la razón de ser del archivo
- /compact
- No: los resume o los tira, y suele tirarlos
- auto memory
- A veces, si le pareció una lección que vale para siempre
- skill handoff
- Lo que quepa en el traspaso, contado como resumen
Para qué es de verdad
- blueprint.md
- Que tu próxima sesión empiece donde terminó esta
- /compact
- Que la sesión de hoy no se quede sin ventana a media tarde
- auto memory
- Notas que Claude se escribe a sí mismo sobre cómo trabajas
- skill handoff
- Pasarle el hilo a otro agente de un jalón
Lo puedes leer tú
- blueprint.md
- Sí: es un archivo de texto y lo abres cuando quieras
- /compact
- Lo ves pasar una vez y se acabó
- auto memory
- Sí, pero está fuera de tu proyecto y es de esa computadora
- skill handoff
- Sí, mientras el temporal no se haya limpiado
| La pregunta | blueprint.md | /compact | auto memory | skill handoff |
|---|---|---|---|---|
| Quién decide qué se guarda | Tú, en seis secciones fijas que siempre son las mismas | El modelo, resumiendo la conversación como le parece | El modelo, cuando le parece que algo vale la pena recordar | El modelo, con lo que llevaba la conversación |
| Dónde vive el archivo | blueprint.md, en la raíz de tu proyecto | En ninguno: reemplaza la conversación y ya | En ~/.claude/projects/<proyecto>/memory/, fuera de tu proyecto | En el directorio temporal del sistema |
| Viaja a git | Sí, si lo commiteas — y entonces lo ve todo el equipo | No | No: es de esa máquina, no se comparte entre máquinas ni con la nube | No: el temporal se limpia solo |
| Se carga solo al arrancar | Sí, si lo importas con la arroba desde tu CLAUDE.md | No aplica: vive dentro de la misma sesión | Sí, está encendida por defecto — pero no se carga en los subagentes | No: se lo pasas tú al siguiente agente |
| Guarda los intentos fallidos | Sí. Es la sección 5 y es la razón de ser del archivo | No: los resume o los tira, y suele tirarlos | A veces, si le pareció una lección que vale para siempre | Lo que quepa en el traspaso, contado como resumen |
| Para qué es de verdad | Que tu próxima sesión empiece donde terminó esta | Que la sesión de hoy no se quede sin ventana a media tarde | Notas que Claude se escribe a sí mismo sobre cómo trabajas | Pasarle el hilo a otro agente de un jalón |
| Lo puedes leer tú | Sí: es un archivo de texto y lo abres cuando quieras | Lo ves pasar una vez y se acabó | Sí, pero está fuera de tu proyecto y es de esa computadora | Sí, mientras el temporal no se haya limpiado |
La fila que decide cuál usas
Es la primera. En tres de las cuatro columnas quien decide qué se guarda es el modelo; en una eres tú, y las secciones son siempre las mismas. Eso es todo lo que hace distinto al blueprint: no es más listo, es predecible. Sabes qué vas a encontrar en la sección 5 antes de abrirla, y por eso puedes confiar en que lo que no está ahí, no pasó.
Sobre handoff, en concreto
Es una habilidad de Matt Pocock que resume la conversación en un documento de traspaso para que otro agente la retome. Lleva 843.8K instalaciones y sus tres auditorías salen en Pass, que no es poca cosa. Guarda el documento en el directorio temporal del sistema, y ahí está la diferencia entera: sirve para un traspaso de un jalón, no para volver el martes que entra.
Instalar handoff, si el traspaso es lo que necesitas
npx skills add https://github.com/mattpocock/skills --skill handoffEl repo de donde sale, y lo demás que trae, está en la guía de las skills de Matt Pocock.
Y si lo que quieres es no montar nada y que una herramienta ya hecha se encargue de la memoria, las que existen están comparadas aquí. Esta guía va por el otro camino: un archivo tuyo, que puedes abrir y corregir.
09 · Cómo sabes que sirve
Cuatro cosas que puedes abrir y ver
Un blueprint puede estar puesto y aun así estar muerto: el import funciona, la regla está escrita, y el archivo lleva tres semanas diciendo lo mismo. Las cuatro señales se contestan abriéndolo, en menos de un minuto y sin preguntarle nada a nadie.
- La línea Actualizado tiene la fecha de hoy, o la del último día que trabajaste. Si dice hace dos semanas y tú trabajaste ayer, lo de adentro ya no es cierto.
- La sección 5 no está vacía. Un blueprint sin intentos fallidos es un blueprint que nadie está usando para lo que sirve.
- La sección 6 tiene menos de cinco pasos y cada uno nombra un archivo. «Mejorar el rendimiento» no es un paso; es un deseo.
- El archivo entero está por debajo de 120 líneas. Si se pasó, no es que hayas avanzado mucho: es que nadie podó.
La revisión de treinta segundos
Cuatro preguntas que se contestan con números, y un diagnóstico al final. Córrela cada par de semanas, o cuando sientas que el archivo ya no te está sirviendo.
Revisa blueprint.md y dime si sigue vivo. Contéstame estas cuatro cosas, una por línea, y no me des consejos hasta el final: 1. Qué fecha tiene la línea Actualizado, y cuántos días pasaron desde entonces. 2. Cuántas líneas tiene la sección 5. Si está vacía, dilo tal cual. 3. Cuántos pasos tiene la sección 6, y cuáles de ellos NO nombran un archivo. 4. Cuántas líneas tiene el archivo entero. Después dime, en una sola frase, cuál de estas tres cosas le está pasando, si le pasa alguna: que el import apunte al CLAUDE.md equivocado y por eso nadie lo esté actualizando, que se haya vuelto un diario en vez de un estado, o que nunca lo hayan podado. Y dime la línea exacta que lo arregla.
Los tres modos de falla, y la línea que arregla cada uno
El import apunta al CLAUDE.md equivocado
Síntoma: el archivo existe, se ve bien y nadie lo actualiza nunca. Al arrancar, Claude sigue preguntándote de qué va el proyecto. Pasa cuando el import quedó en un CLAUDE.md que no es el que se carga en esta carpeta, o cuando la línea terminó adentro de un bloque de código.
Arreglo: corre /context y busca blueprint.md en la lista de Memory files. Si no está, pégale a Claude el prompt de la sección 04 otra vez y esta vez pídele que te diga en qué ruta quedó.
El blueprint se volvió un diario
Síntoma: la sección 2 tiene párrafos que empiezan con «después probamos» y la 4 cuenta las últimas tres semanas en orden cronológico. El archivo se lee como un relato y ya nadie lo abre porque da flojera.
Arreglo: la 2 se reescribe entera cada vez, no se le agrega abajo. Dile que la vuelva a escribir en cinco líneas contestando solo qué corre, qué está a medias y qué falta probar.
Nadie podó nunca
Síntoma: 250 líneas, la sección 4 con todo lo commiteado desde el primer día, y pasos de la 6 marcados con palomita en vez de borrados. Y como entra en cada arranque, lo estás pagando completo todos los días.
Arreglo: el prompt de poda de la sección 07. Una vez, y después cada vez que el archivo se pase de 120 líneas. No es mantenimiento: es lo que evita que la solución se vuelva el problema.
Y cuando la tarea termine, el archivo se tira. No es documentación del proyecto ni memoria de largo plazo: es el estado de algo que se va a acabar. Si al terminar te quedaste con una lección que vale para el siguiente proyecto, esa no vive aquí — vive en otro lado, y tiene su propia guía.
Guía de la bóveda
Esta guía es una de las gratuitas de la bóveda.
Si te llevas una sola cosa
Lo que se pierde al cerrar la terminal no es el código: es por qué se hizo así y qué ya se intentó. Un archivo de seis secciones en la raíz de tu proyecto lo guarda, y con la arroba en tu CLAUDE.md entra solo cada vez que arrancas. La sección 5 —lo que falló, con su fecha y su motivo— es la que paga el montaje completo. Y si no lo podas, en tres semanas es el mismo problema con otro nombre.
Dónde sigue cada tema
The Architect
La otra cosa que se llama blueprint, y no es esta. Allá el plano tiene veinte secciones y se escribe antes de que el proyecto exista, para que otro Claude lo construya. Uno diseña lo que no existe; este guarda dónde te quedaste.
Cuando Claude se vuelve tonto a media sesión
El problema de hoy, no el de mañana: qué hacer cuando la sesión se llena y empieza a olvidar a media tarde. De ahí sale /compact, /clear y el prompt de compactar con foco que esta guía cita.
El cuaderno compartido de memory-palace
Cuando son varios agentes leyendo las mismas notas. Ahí lo obsoleto se tacha y se queda, porque no cuesta contexto hasta que alguien abre el archivo. Aquí se mueve a otro lado, porque este se carga solo en cada arranque.
Cómo se estructura un CLAUDE.md
La sintaxis de la arroba, las rutas y hasta dónde encadena un import. Esta guía la usa en una línea y se va al uso; la explicación completa vive allá.
La habilidad /aprende
El corte es de duración: /aprende guarda lecciones que valen para siempre, el blueprint guarda el estado de una tarea que se va a terminar y después se tira. Las dos pueden estar puestas en el mismo proyecto.
Memoria para Claude Code, sin montar nada
El otro camino: instalar una herramienta ya hecha y olvidarte. Esta guía va por el de un archivo tuyo, que puedes abrir y corregir. Allá están comparadas las que existen.
Lo nuevo sale primero en Instagram
Ahí aviso cuando entra una guía nueva a la bóveda y cuando algo de esto cambia.
@soyenriquerocha
Qué está verificado y qué es criterio
Lo que esta página dice del comportamiento de Claude Code —que un CLAUDE.md puede importar otros archivos con la arroba y que los importados entran al contexto al arrancar, que el objetivo es quedarse por debajo de 200 líneas, que /context enseña los archivos de memoria cargados, dónde vive la memoria automática y qué pueden hacer los hooks— se contrastó contra la documentación oficial de Claude Code el 21 de septiembre de 2026. El techo de 120 líneas, las cuotas por sección y las cinco reglas de retiro no son documentación: son criterio de la casa, y están puestos así para que los dos archivos quepan en ese presupuesto. Si alguno de los dos cambia, cambia la sección 07 y no el resto.