Un CLAUDE.md inflado es peor que no tener ninguno. El agente lo lee por encima y se come el contexto que te hace falta para la tarea real. Este es un prompt de copiar y pegar que hace que Claude Code descubra las convenciones leyendo el código, en vez de que se las dictes de memoria, y después escriba un archivo corto y con mucha señal, marcando todo lo que le quedó en duda para que lo revises rápido. Te llevas el prompt, las variables para adaptarlo, variantes para monorepos y archivos que ya existen, y los detalles que vuelven malo un buen borrador.
En resumen
- Haz que Claude descubra las convenciones leyendo el código, no a partir de tus suposiciones. Una muestra de archivos reales le gana a una regla que dictaste de memoria.
- Mantén el archivo corto, unas 40 líneas. Un CLAUDE.md de 300 líneas el agente lo lee por encima a mitad de sesión, y además te come el contexto que necesitas para la tarea en cada corrida.
- Las marcas DUDOSO son la clave. Convierten un borrador lleno de suposiciones en una revisión rápida en lugar de un acto de fe.
- Escribe las reglas como imperativos secos, no como prosa. El agente lee por encima, así que «Corre npm test antes de hacer commit» le gana a un párrafo sobre filosofía de testing.
- Vuélvelo a correr después de cambios estructurales grandes. Un CLAUDE.md desactualizado le enseña al agente la estructura equivocada, y lo hace con total confianza.
Si no tienes un CLAUDE.md, toda sesión de Claude Code empieza igual: el agente vuelve a deducir el comando de build, adivina la convención de nombres y cada tanto mete un componente nuevo en la carpeta equivocada. Un CLAUDE.md resuelve eso, pero solo si es corto y exacto. Uno inflado es peor que no tener ninguno, porque el agente lo lee por encima y ya gastaste presupuesto de contexto en puro ruido. Este prompt genera un archivo ajustado y con mucha señal: hace que Claude investigue el repo en vez de que dictes reglas de memoria, y marca todo lo que le quedó en duda para que la revisión sea una pasada rápida en vez de una lectura a fondo.
01 · El prompt
Córrelo en la raíz del repo, dentro de Claude Code y con acceso de lectura. Es deliberadamente insistente con eso de investigar en vez de adivinar. Ahí está justamente la gracia.
Explora este repositorio y redacta un CLAUDE.md para él. Primero investiga;
no asumas. Lee los archivos, no te guíes por lo que los repos "suelen"
hacer.
Descubre, leyendo el código y la config de verdad:
1. Comandos de build, test, lint y run. Lee los scripts de package.json,
Makefile, justfile, pyproject.toml y cualquier workflow de CI. Cita el
comando EXACTO, no uno genérico.
2. La estructura de carpetas y la regla de dónde va cada TIPO de código
nuevo (un componente / ruta / test / migración / util). Enuncia la
regla, con la ruta real.
3. Las convenciones de nombres que se usan de verdad. Revisa al menos 5
archivos por tipo (componentes, tests, utils) antes de enunciar una
regla. Si los archivos no coinciden entre sí, di qué convención domina
y anota la excepción.
4. El estilo de imports (relativo vs alias, ej. @/...), y cualquier alias
de rutas configurado en tsconfig/jsconfig/config del bundler.
5. De 1 a 3 detalles no obvios que puedas inferir del código: un archivo
generado que no se debe editar a mano, una env var que la app necesita
para arrancar, un test que requiere un servicio corriendo, un formatter
que reescribe el archivo al guardar.
Después escribe el CLAUDE.md como reglas imperativas y secas:
- Máx 40 líneas. Sin relleno, sin filosofía, sin repetir lo obvio.
- Una regla por línea. En imperativo ("Usa X", "Nunca Y", "Corre Z").
- Agrúpalas bajo encabezados cortos: Comandos / Estructura / Convenciones /
Detalles.
- Antepón "DUDOSO:" a cualquier regla que no hayas podido verificar en el
código, para que yo la confirme o la borre de una sola pasada.
- Cierra con el o los comandos exactos que hay que correr antes del commit.
No inventes reglas para rellenar. Si una sección no tiene nada real,
omítela.
Muéstrame el borrador; no escribas el archivo hasta que yo lo apruebe.
Las dos instrucciones que cargan con todo el peso son investiga, no asumas y el prefijo DUDOSO:. La primera evita que Claude escriba un archivo verosímil pero incorrecto, basado en cómo "suelen" verse los repos de TypeScript. La segunda convierte las suposiciones inevitables en un checklist que liquidas en segundos.
Consejo
Agrega "Muéstrame el borrador; no escribas el archivo hasta que yo lo apruebe", y cúmplelo. Revisar en el chat antes de que algo toque el disco es más rápido que leer un archivo al que ya le hiciste commit y después revertirlo, y mantiene un mal primer borrador fuera de tu historial de git.
02 · Adáptalo a tu repo
El prompt es agnóstico del stack a propósito, pero unos cuantos ajustes puntuales afinan el borrador. Acomoda a tu realidad la lista del bloque "Descubre" de la sección 01:
- Cambia los archivos de config por los tuyos. A un repo de Python le importan pyproject.toml, tox.ini y ruff. A uno de Go, el Makefile y go test ./.... A uno de Next.js, los scripts de package.json y next.config.js. Nombrar los archivos correctos evita que Claude se ponga a buscar a ciegas.
- Apúntale a los detalles que ya conoces. Si tu repo tiene una mina, un schema.ts generado que no se debe editar, un .env que el dev server necesita, una migración de Supabase que tiene que correr antes de los tests, agrega una línea: "Confirma si X es un detalle a cuidar". No le estás dictando la regla, le estás pidiendo a Claude que la verifique y la redacte.
- Ajusta el presupuesto de líneas a tu gusto. 40 líneas le quedan bien a una sola app. Un codebase más grande puede justificar 60, pero trata cada línea por encima de 40 como algo que el agente podría saltarse. Más no es más seguro.
Nota
El CLAUDE.md se carga en contexto al inicio de cada sesión, así que su longitud es un costo recurrente, no de una sola vez. Un archivo de 40 líneas que lees una vez te cuesta 40 líneas también en cada tarea futura. Esa asimetría es justo el motivo por el que "corto y exacto" le gana a "completo".
03 · Variables y placeholders
Si conviertes esto en un snippet reutilizable (un prompt guardado, un slash command, una plantilla de equipo), parametriza estos puntos. Los escribo aquí entre CORCHETES para que sean fáciles de buscar y reemplazar:
- [STACK] es el lenguaje/framework, que sirve para nombrar los archivos de config correctos: "Lee package.json y next.config.js" vs "Lee pyproject.toml y ruff.toml".
- [PRESUPUESTO_LINEAS] es el máximo de líneas. Por defecto, 40. Súbelo solo si tienes una razón.
- [DETALLES_CONOCIDOS] es una lista corta de minas que sospechas, para que Claude las confirme, o "ninguno, descúbrelos" si de verdad no sabes.
- [GATE_COMMIT] es qué significa "listo para hacer commit" aquí: los comandos exactos de test/lint/typecheck que tienen que pasar. Esto pasa a ser la línea de cierre del archivo.
- [TIPOS] son los tipos de código cuya ubicación importa en tu repo (componente / ruta / test / migración / edge function). Alimenta el ítem 2 de la sección 01.
Una variante ya rellenada para un repo de TypeScript + Next.js + Supabase, con los placeholders resueltos, podría empezar así:
Explora este repositorio y redacta un CLAUDE.md. Investiga, no asumas.
Stack: TypeScript, Next.js (App Router), Supabase, Tailwind.
Lee: scripts de package.json, next.config.js, tsconfig.json (alias de
rutas), supabase/ para las convenciones de migraciones, y cualquier
workflow de CI.
Confirma si estos son detalles a cuidar: lib/database.types.ts es generado
y no se debe editar a mano; el dev server necesita .env.local para arrancar.
Dónde va cada cosa nueva: ¿una ruta, un server action, un componente,
una migración?
Máx 40 líneas. Antepón DUDOSO: a lo que no hayas podido verificar.
Cierra con el gate exacto de pre-commit: typecheck + lint + test.
04 · Variantes
CLAUDE.md existente · audita en vez de reescribir
Si ya existe un CLAUDE.md, no lo borres de golpe. Pídele a Claude que lo ponga a tono con la realidad; así atrapas la desactualización silenciosa que se va acumulando tras los refactors.
Lee el CLAUDE.md existente y luego verifica cada regla contra el código
actual. Para cada regla, márcala: KEEP (sigue siendo cierta), STALE (ya no
coincide; di qué cambió), o DUDOSO (no se puede verificar). Propón una
versión recortada por debajo de 40 líneas que elimine las reglas STALE y
todo lo puramente decorativo. No agregues reglas nuevas a menos que haya un
detalle real sin documentar.
Monorepo · un archivo raíz, archivos por paquete bien delgados
En un monorepo, un solo CLAUDE.md gigante en la raíz es el peor caso: arrastra reglas de paquetes que ni siquiera estás tocando. Pon las reglas compartidas en la raíz y deja que cada paquete maneje lo suyo.
Esto es un monorepo (lee la config del workspace: pnpm-workspace.yaml /
turbo.json / nx.json). Redacta un CLAUDE.md RAÍZ solo con reglas ciertas
para TODOS los paquetes (el toolchain compartido, el gate de commit, la
estructura global). Luego, para el paquete en [RUTA], redacta un CLAUDE.md
CORTO a nivel de paquete solo con lo que difiera de la raíz. No repitas las
reglas de la raíz en el archivo del paquete. Mantén cada archivo por debajo
de 30 líneas.
Repo en solitario / etapa temprana · codifica la intención, no solo el estado actual
En un repo joven (la situación detrás de la mayoría de mis propios proyectos: Infuse, Agent Orchestra y Proyección empezaron así) las convenciones todavía no se ven del todo en el código, porque aún no hay mucho código. Dile a Claude que capture las decisiones que ya tomaste, marcadas con claridad como intención y no como hecho observado.
Este repo está en etapa temprana; puede que las convenciones todavía no
estén del todo establecidas en el código. Redacta el CLAUDE.md con lo que
SÍ es visible, y agrega un bloque corto "Convenciones previstas (confirmar)"
para las decisiones que el código todavía no impone. Mantén bien separadas
las reglas observadas de las previstas, para no confundir un deseo con un
hecho.
05 · Detalles a cuidar
El prompt es simple; los modos de falla son sutiles. Estos son los que te muerden.
-
El crecimiento del archivo es el enemigo de verdad. El error más común es dejar que el archivo crezca "para que esté completo". Un CLAUDE.md de 300 líneas el agente lo lee por encima y lo ignora a medias a mitad de sesión, y te cuesta ese contexto en cada tarea futura. Si no logras mantenerlo por debajo de ~40 líneas, esas reglas van en la documentación o en el código, no aquí.
-
Confiar en el borrador sin liquidar las marcas DUDOSO. Las marcas están ahí para resolverlas. Un "DUDOSO: los tests viven en tests" sin confirmar, que además resulta ser falso, es peor que no tener regla, porque ahora el agente va a meter los tests con total confianza en el lugar equivocado. Lee las marcas, confirma o borra, y solo entonces lo das por bueno.
-
Codificar cosas que cambian seguido. Números de versión, el nombre de la feature que estás armando ahora mismo, el TODO de hoy: se desactualizan en días y despistan al agente sin que te enteres. El CLAUDE.md es para convenciones estables, no para el estado actual. Si una línea va a ser falsa el mes que viene, déjala fuera.
-
Repetir lo que el agente ya puede ver. "Esto es un proyecto de TypeScript" y "usamos React" salen gratis, porque Claude lo lee de los archivos. Gasta el presupuesto de líneas en lo no obvio: el archivo generado que no se toca, la env var que hace falta para arrancar, el único test que necesita un servicio corriendo.
-
Olvidar volver a correrlo tras un refactor. Un CLAUDE.md que describía la estructura del trimestre pasado hoy le enseña al agente las carpetas equivocadas, y lo hace con total confianza. Después de cualquier cambio estructural grande, vuelve a correr la variante de auditoría de la sección 04. Trata el archivo como código que también se puede pudrir.
Atención
No dejes que Claude escriba el archivo antes de que hayas leído el borrador. Un CLAUDE.md con commit automático y sin revisar, con una regla incorrecta adentro, es el peor resultado posible: el agente trata su propia convención alucinada como verdad sagrada en cada sesión futura, hasta que alguien se da cuenta. Revisa primero, escribe después.
Un buen CLAUDE.md es chico, cierto y aburrido. Enuncia los comandos, la estructura y las dos o tres cosas que un recién llegado avispado entendería mal, y ahí se detiene. Corre este prompt, liquida las marcas DUDOSO, mantenlo por debajo de 40 líneas y vuélvelo a correr cuando el repo cambie de forma. Ese es todo el mantenimiento que pide, y vale la pena la primera vez que el agente acierta con tus convenciones sin que tengas que decírselas.
Puntos clave
- Haz que Claude investigue el código; una convención descubierta le gana a una dictada y saca a la luz esos detalles que ya olvidaste que sabías.
- Mantenlo por debajo de ~40 líneas. La longitud es un costo recurrente por sesión, así que corto y cierto le gana a largo y completo.
- Siempre liquida las marcas DUDOSO antes de fiarte del archivo: una regla incorrecta sin confirmar es peor que no tener regla.
- Gasta el presupuesto en lo no obvio: los comandos, la regla de estructura y las dos o tres minas, no en lo que el agente ya puede leer.
- Vuélvelo a correr después de cambios estructurales; un CLAUDE.md desactualizado le enseña al agente, con total confianza, el repo equivocado.
Preguntas frecuentes
¿Por qué hacer que Claude descubra las convenciones en vez de escribir yo mismo el CLAUDE.md?
Por dos razones. Primero, te vas a olvidar de cosas que ya tienes interiorizadas, como el archivo generado que por instinto nunca tocas o la env var que configuraste hace meses, y justamente esos son los detalles de más valor. Que Claude lea el código real los saca a la luz. Segundo, así el archivo se parece más a la realidad que a tu recuerdo de ella. Sigues en control liquidando las marcas DUDOSO, que es más rápido que escribir todo desde cero.
Cuarenta líneas se sienten muy poco. Mi repo tiene un montón de convenciones.
La longitud es un costo recurrente: el CLAUDE.md se carga al inicio de cada sesión, así que un archivo largo te pasa factura en cada tarea futura, no solo en la primera. Casi todo lo que parece imprescindible o es obvio a partir del código (Claude lo lee igual) o va en documentación de verdad, que el agente puede abrir cuando haga falta. Reserva las 40 líneas para los comandos, la regla de estructura y los dos o tres detalles no obvios. Si de verdad necesitas más, divídelo: un archivo raíz delgado más archivos por paquete en un monorepo.
¿Qué hago exactamente con las marcas DUDOSO?
Lee cada una y, o la confirmas (borras el prefijo), o borras la línea completa. Marcan reglas que Claude no pudo verificar a partir del código, así que son las únicas líneas que necesitan atención de verdad. El peligro está en dejar una regla DUDOSO sin confirmar en el archivo: si está mal, ahora el agente va a seguir con total confianza una convención inventada. Las marcas convierten la revisión en un checklist corto en vez de una relectura a fondo de todo.
¿Dónde debe ir el CLAUDE.md? ¿Y Claude Code lo toma solo?
Ponlo en la raíz del repo y haz commit, para que todo tu equipo (y los agentes de CI) reciban el mismo contexto. Claude Code lo carga en contexto al inicio de una sesión en ese directorio. En un monorepo también puedes poner un CLAUDE.md más delgado dentro de un paquete, para que sus reglas específicas apliquen cuando trabajas ahí, sin inflar el archivo raíz con reglas de paquetes que ni estás tocando.
¿Cada cuánto debería regenerarlo?
No con un calendario fijo, sino cuando algo lo dispare. Vuelve a correr la variante de auditoría después de cualquier cambio que mueva la estructura o el toolchain: una reorganización de carpetas, un cambio de Jest a Vitest, un nuevo alias de rutas, un script de build con otro nombre. Un CLAUDE.md desactualizado es peor que uno que no existe, porque le enseña al agente con total confianza la estructura vieja y equivocada. El trabajo diario de features no necesita refresco; un cambio estructural sí.
¿Puedo mantener mis reglas personales fuera del archivo compartido?
Sí, y deberías hacerlo. El CLAUDE.md que subes al repo es para las convenciones que todo el equipo comparte: comandos, estructura, detalles a cuidar. Las preferencias personales (respóndeme en español, pregúntame antes de hacer cambios destructivos) van en tu propia config global, no en el repo, para que no le impongas tu estilo a los compañeros ni ensucies la señal compartida. Que el archivo del repo hable solo del repo.
¿Prefieres que lo hagamos por ti?
Esto mismo lo construimos para negocios como el tuyo. La primera conversación es gratis y sin compromiso.
Escríbenos por WhatsAppPrimera conversación gratis. Te responde el fundador.
Recursos relacionados
Un system prompt de revisor de código estricto que sí puedes reutilizar
El modo de fallo típico de un revisor LLM es la cortesía: encuentra tres bugs reales y los sepulta bajo veinte notas de 'considera extraer una constante'. Este es un system prompt completo y listo para copiar que impone un contrato de severidad para que la señal quede siempre arriba, además de cómo adaptarlo, para qué sirve cada placeholder, las variantes que vale la pena conservar y las cláusulas que, sin que te des cuenta, deciden si confías en lo que te devuelve.
Un prompt para mensajes de commit que escribe el porqué, no el qué
La mayoría de los mensajes de commit solo repiten el diff, que es justo lo que git ya sabe. Este es un prompt para copiar y pegar que toma un diff en staging y lo convierte en un mensaje de Conventional Commit que explica la intención, se niega a mezclar cambios sin relación y es lo bastante mecánico para usarlo en cada commit. Te llevas la plantilla completa, las variables que puedes ajustar, cuatro variantes y las formas en que puede fallar para que estés pendiente.
Un generador de PRD que te entrevista primero
Un PRD escrito a partir de una idea de una sola línea es pura ficción con cara de seguridad: tapa cada hueco con una suposición que suena bien y te deja un documento que parece terminado. Esta plantilla se niega a escribir hasta poner nombre a lo que no sabes: te entrevista por las piezas que faltan, le pone tope a las preguntas para que no la abandones a mitad de camino, y te exige una línea de corte de v1 que dice exactamente qué sale primero. Cópiala, ajusta las variables y deja de revisar PRDs montados sobre supuestos que nunca hiciste.