CLAUDE.md Es el Nuevo .env — Y la Mayoría de Desarrolladores lo Tratan Como un README
Luego vi lo que Boris Cherny — el tipo que construyó Claude Code — pone en el suyo. Y lo que Trail of Bits usa en sus repos de auditorías de seguridad. Y lo que usan los equipos que ganan los hackathons de Anthropic para superar a ingenieros senior de verdad.
Mi CLAUDE.md ahora tiene más de 200 líneas. La calidad de mi output se fue por un precipicio. En la buena dirección.
TL;DR: Tu CLAUDE.md probablemente es un README glorificado. Debería tratarse como tu .env — sagrado, específico del proyecto, y nunca una ocurrencia tardía. Aquí te explico cómo reestructuré el mío en 4 repos de producción, qué patrones realmente cambiaron el comportamiento de Claude, y por qué la mayoría de hilos de "tips para CLAUDE.md" en X te están preparando para peor output.
Tu Presupuesto de Instrucciones Es Más Pequeño De Lo Que Piensas
Olvida qué poner en CLAUDE.md por un segundo. Hablemos de qué pasa cuando pones demasiado.
El análisis de HumanLayer (referenciando un paper de arxiv sobre límites de seguimiento de instrucciones) sugiere que los modelos de pensamiento de frontera pueden seguir de manera confiable aproximadamente 150–200 instrucciones. Su análisis del prompt del sistema de Claude Code contó ~50 instrucciones integradas antes de que tu CLAUDE.md siquiera se cargue.
Los números exactos son debatibles — pero la dirección no. En algún punto, agregar más reglas hace que Claude sea peor siguiendo todas ellas, no solo las nuevas.
El cumplimiento cae uniformemente.
El cumplimiento cae uniformemente. Las reglas que más te importan se ignoran al mismo ritmo que el relleno que olvidaste borrar.
Por eso cada línea importa. Y por eso los tweets virales que muestran archivos CLAUDE.md de 400 líneas que "hacen a Claude un ingeniero 10x" son activamente contraproducentes. Los autores tienen buenas intenciones — pero sus seguidores están llenando archivos con reglas que Claude silenciosamente deja de seguir después de las primeras cien.
El contexto es un presupuesto. Gástalo como dinero del alquiler, no como fichas de casino.
¿La peor parte? La mitad de lo que la mayoría pone en CLAUDE.md, Claude ya puede inferirlo. Tu stack tecnológico está en package.json. La configuración de TypeScript está en tsconfig.json. Las reglas del linter están en .eslintrc. Claude lee todo eso. Repetirlas quema slots de instrucciones en cosas que no cambian nada.
Una prueba para cada línea: "¿Eliminar esto haría que Claude cometa un error del que no puede recuperarse?" Si borras "usa TypeScript" y tu proyecto tiene un tsconfig.json — no pasa nada. Si borras "las queries de Convex no pueden llamar mutations, usa actions" — Claude genera código que pasa el type checker y explota en runtime.
Solo incluye lo que Claude no puede descifrar solo.
Qué Estaba Realmente Mal Con Mi Archivo de 47 Líneas
Mi viejo CLAUDE.md, parafraseado (porque no me voy a someter a la vergüenza de la versión real):
# Mi Proyecto SaaS
Stack: Next.js, Convex, Clerk, Supabase, Tailwind
Versión de Node: 20
Gestor de paquetes: pnpm
## Reglas
- Usa TypeScript
- Escribe tests
- No borres el archivo .env
Once líneas de "información" que Claude podría extraer de mi repo en 3 segundos. El resto eran lugares comunes. "Escribe código limpio." "Sigue las mejores prácticas." "Mantén los componentes pequeños." ¿Qué tan pequeños? ¿Pequeños como un componente de React o pequeños como un microservicio? Claude no lo sabe, así que adivina, y su adivinanza está mal como el 40% de las veces.
Estaba quemando mi presupuesto de instrucciones diciéndole a Claude cosas que ya sabía, y no diciéndole nada sobre las cosas que no podía saber — secuencias de workflow, pasos de verificación, la trampa de Convex deploy-before-build que me costó un domingo entero en febrero debuggeando una caída de producción que no debería haber pasado.
Ese domingo fue cuando reconstruí el archivo desde cero.
La Reestructuración: Qué Va Realmente
Revisé los hilos de Boris Cherny (él construyó Claude Code — sus tips tienen peso), el repo de configuración pública de Trail of Bits, la guía de Dometrain, y como 40 archivos CLAUDE.md reales en GitHub.
El patrón era consistente: los mejores archivos no son los más largos. Son los más específicos sobre modos de falla.
1. Comandos Que Incluyen Cómo Se Rompen
## Comandos
Ejecuta TODOS los comandos desde la raíz del proyecto a menos que se especifique lo contrario.
### Dev
- `pnpm dev` — inicia Next.js en :3000. El servidor dev de Convex debe estar corriendo por separado.
- `npx convex dev` — ejecutar en una SEGUNDA terminal. Fallará silenciosamente si CONVEX_DEPLOY_KEY falta en .env.local
### Test
- `pnpm vitest run src/path/to/file.test.ts` — ejecutar UN SOLO archivo de test. Nunca ejecutes la suite completa a menos que se pida explícitamente.
- Los tests de integración requieren una instancia dev de Convex corriendo.
### Deploy
- `pnpm build && npx convex deploy` — siempre hacer build PRIMERO. Convex deploy solo usará funciones obsoletas.
- Si el deploy se cuelga >30s, mátalo. Revisa `npx convex logs` para errores de validación de schema.
No solo qué escribir. Qué sale mal y cómo recuperarse. El tip central de Boris: siempre dale a Claude una forma de verificar su propio trabajo. Tests, diffs, logs. Sin verificación, obtienes vibes.
2. Decisiones de Arquitectura, No Descripciones de Arquitectura
Antes listaba mi estructura de archivos. Desperdicio de tokens — Claude lee tu árbol de archivos de todos modos.
Ahora documento el por qué detrás de decisiones que Claude no puede inferir:
## Decisiones de Arquitectura
- Auth: Clerk maneja toda la autenticación. NUNCA implementes lógica de auth personalizada.
- Base de datos: Convex para datos en tiempo real. Supabase para almacenamiento de blobs SOLAMENTE. NO uses Supabase para datos estructurados.
- Estado: No hay librería de estado del cliente. Las queries reactivas de Convex reemplazan useState para todos los datos del servidor.
- Estilos: Solo Tailwind. No CSS modules, no styled-components.
Cada línea elimina una categoría entera de errores.
Antes de que esta sección existiera, Claude periódicamente creaba tablas de Supabase para datos de usuario cuando Convex estaba ahí mismo. Pequeñas decisiones que se acumulaban en sesiones de refactoring que no había presupuestado.
3. El Loop de Auto-Mejora
Este podría ser el patrón de mayor apalancamiento en todo el archivo.
Después de que Claude comete un error, no solo lo arreglas. Le dices a Claude que agregue una nueva regla a CLAUDE.md para que nunca vuelva a cometer ese error:
"Arregla el bug donde importaste de @clerk/nextjs/server en un componente cliente.
Luego actualiza CLAUDE.md con una regla para que nunca vuelvas a hacer esto."
Mi CLAUDE.md ahora tiene una sección ## Reglas Aprendidas al final que está completamente escrita por Claude:
## Reglas Aprendidas (auto-generadas, revisar periódicamente)
- NUNCA importar de `@clerk/nextjs/server` en archivos bajo `src/app/(dashboard)/`
- Las funciones `query` de Convex no pueden llamar funciones `mutation`. Usa `action` para efectos secundarios.
- `useQuery` de convex/react retorna `undefined` durante la carga, no `null`. Maneja ambos.
- Las nuevas rutas API van en `src/app/api/` NO en `src/pages/api/` (solo App Router)
Con el tiempo, esta sección se convierte en la parte más valiosa del archivo. Un changelog vivo de cada error que Claude cometió en tu proyecto específico. Conocimiento que se acumula, no errores que se acumulan. Si esto te suena familiar — es la misma filosofía detrás de Prompt Contracts: restricciones estructuradas que se acumulan en lugar de decaer.
El truco: edita despiadadamente. Boris también advierte sobre esto.
Los archivos hinchados hacen que Claude ignore todo — incluyendo las reglas que más importan. Podo cada dos semanas. Las reglas redundantes se fusionan. Las obvias se cortan.
4. Guardias de Seguridad
OK esta sección existe porque me di cuenta una mañana de que tenía cero protección contra rm -rf en mi CLAUDE.md y había estado ejecutando Claude Code en mis repos de producción por meses. Genial. Genial genial genial. 😐
## Seguridad
- NUNCA ejecutar `rm -rf` o `rm -fr`. Usar comando `trash` en su lugar.
- NUNCA modificar .env, .env.local, o .env.production sin permiso explícito.
- NUNCA hacer push directamente a `main`. Siempre crear una rama de feature.
- NUNCA ejecutar `npx convex deploy --prod` a menos que diga explícitamente "deploy a producción."
Claude es un modelo probabilístico entrenado en internet. rm -rf node_modules aparece en diez mil millones de respuestas de Stack Overflow. Un contexto mal leído y tu directorio src/ se convierte en un recuerdo entrañable.
Tu .env protege tus secretos. Tu CLAUDE.md protege tu código fuente. Misma energía. Misma disciplina.
5. El Patrón Router
Para cualquier cosa más grande que un proyecto de fin de semana, un archivo no es suficiente. Pero un archivo hinchado es peor que ninguno. La solución: usa el CLAUDE.md raíz como tabla de contenidos.
# Raíz del Proyecto
Ver @docs/convex-conventions.md para patrones de base de datos
Ver @docs/api-patterns.md para convenciones de rutas API
Ver @docs/testing-guide.md para estructura de tests y comandos
Claude Code resuelve @path/to/import nativamente. El CLAUDE.md raíz se carga cada sesión. Los archivos importados se cargan bajo demanda. Tu raíz se mantiene bajo 100 líneas. Total de instrucciones cuando trabajas en cualquier zona dada: cómodamente bajo el techo de 150–200. (Y si te preguntas si algunas de esas definiciones de herramientas deberían ser CLIs en lugar de MCPs — menos herramientas en contexto significa menos instrucciones quemadas.)
Trail of Bits lleva esto más lejos con .claude/rules/ — archivos markdown con scope que se cargan automáticamente basados en la ruta del archivo:
---
paths: src/api/**/*.ts
---
# Reglas API
- Todos los endpoints deben incluir validación de input
- Usar formato estándar de respuesta de error
Reglas API para tu directorio API. Reglas de test para tu directorio de tests. Claude solo carga lo que es relevante. Mi SaaS tiene 3 zonas — sitio de marketing, dashboard, API — cada una con su propio archivo de reglas. El CLAUDE.md raíz nunca cruza las 100 líneas.
Mi Template Real
No una versión sanitizada. Este es el esqueleto real, comentarios incluidos:
# [Nombre del Proyecto]
## Contexto Crítico
[2-3 líneas máximo. Qué ES esto y la única cosa que Claude nunca debe entender mal]
## Comandos
[Comandos exactos con modos de falla. No una página de manual - una guía de supervivencia]
## Decisiones de Arquitectura
[Solo el POR QUÉ detrás de decisiones que Claude no puede inferir del código]
## Seguridad
[Límites duros. Sí, tengo una sección de Seguridad. Sí, aprendí por las malas.]
## Estilo
[SOLO lo que los linters no hacen cumplir. Si eslint lo atrapa, bórralo de aquí]
## Reglas Aprendidas
[Escrito por Claude. La mejor sección del archivo. Pódala o se come todo lo demás]
@docs/[area]-conventions.md
Siete secciones. No hay "resumen del proyecto" que parafrasee el README. No hay stack tecnológico que duplique package.json.
Claude Code también soporta Skills (.claude/skills/ — workflows bajo demanda que no se cargan cada sesión) y Auto Memory (~/.claude/projects/*/memory/ — notas que Claude escribe para sí mismo entre sesiones, opt in con CLAUDE_CODE_DISABLE_AUTO_MEMORY=0). Ambos reducen lo que necesitas en el archivo raíz. Pero CLAUDE.md es la base — hazlo bien primero.
El Verdadero Unlock
El cambio real no fue aprender qué poner en CLAUDE.md. Fue aprender qué quitar.
Borré la sección del stack tecnológico.
Borré las reglas de "estilo de código" que mi linter ya hace cumplir. Borré los lugares comunes vagos que no lograban exactamente nada. Lo que quedó fueron las cosas que evitan que Claude cometa errores que solo un humano que ha trabajado en este proyecto por meses sabría evitar.
El conocimiento institucional de tu proyecto, comprimido en la menor superficie posible. Leído cada sesión. Podado cada sprint.
Trátalo como tu .env. Cada línea se gana su lugar o se corta.
¿Tienes un patrón de CLAUDE.md que cambió tu workflow? ¿O una historia de guerra sobre una regla que desearías haber escrito antes? Estoy recolectando estas para un seguimiento. Suscríbete — el próximo es sobre convertir el loop de auto-mejora en un sistema que se acumule en todo tu stack.
Medium solo envía emails a suscriptores cuando publico — no spam, no digest. Un artículo llega a tu inbox, lo lees o no. Mejor que refrescar el feed.
Descubre cómo transformar tu CLAUDE.md de un README genérico a una guía de producción que realmente impulsa la calidad del código con inteligencia artificial.