Andrej Karpathy publicó hace meses su CLAUDE.md y se hizo viral. La gente lo copió tal cual al global. Yo incluido.
Llevo meses haciéndolo mal. Hace unos días lo tiré entero y lo reescribí desde cero. Esta edición es lo que descubrí, con los tres archivos listos para copiar.
Empecemos por el error que casi nadie ve.
El global no es un cajón de sastre, es un peaje
Tu ~/.claude/CLAUDE.md global se carga al inicio de todas las sesiones de Claude Code. Cuando preguntas algo conceptual. Cuando arreglas un typo. Cuando haces tareas de gestión que no tocan código.
Cada línea que metes ahí ocupa contexto en sesiones donde no aporta nada. No es un archivo de "ajustes" que se consulta cuando hace falta. Es un peaje que pagas en cada arranque, independientemente de si esa instrucción es relevante para lo que estás haciendo.
El frame mental correcto no es organizativo, es presupuestario. La pregunta no es "¿dónde guardo esta regla?" sino "¿merece esta regla ocupar contexto en TODA sesión?".
Lo que Anthropic diseñó para esto: Skills
La alternativa oficial son las Skills, que siguen el estándar abierto Agent Skills. La diferencia con el global es el mecanismo de carga.
Según la documentación de Anthropic, una skill se compone de un SKILL.md con frontmatter YAML (name y description) más un cuerpo de instrucciones. Al inicio de la sesión, Claude solo lee el name y la description de cada skill disponible. El cuerpo completo no entra en contexto hasta que una tarea coincide con esa descripción. Es lo que Anthropic llama progressive disclosure: el contexto se carga por capas, solo cuando es relevante.
Eso cambia la economía del contexto. El cuerpo de una skill de deployment de 200 líneas no ocupa nada mientras estás depurando un script de Python. Solo entra en juego cuando Claude detecta, por la description, que la tarea encaja.
La documentación oficial recomienda mantener el cuerpo del SKILL.md por debajo de unas 500 líneas (o 1.500-2.000 palabras). Si crece más, la recomendación es partirlo en archivos de referencia que se cargan bajo demanda. Para el global no hay un número mágico publicado, pero el principio es el mismo: cuanto más corto, mejor adherencia. Los archivos largos diluyen las instrucciones y aumentan la probabilidad de que Claude ignore reglas que para ti son obligatorias.
El matiz honesto: las skills no siempre se activan
Aquí va lo que casi nadie te cuenta cuando te vende skills como solución mágica.
El disparador de una skill es la description. Y ese matcher es difuso. En las evals que publicó Vercel sobre agentes, las skills no se invocaron en el 56% de los casos de prueba, sin producir mejora sobre la baseline en esos casos. No porque las skills sean malas, sino porque el modelo no siempre reconoce que la tarea encaja con la descripción.
Implicación práctica: la description no es metadata decorativa, es el componente más importante de la skill. Tienes que escribirla pensando en qué palabras y qué intenciones van a aparecer en tus peticiones reales. Una descripción vaga es una skill que duerme cuando la necesitas.
Y para reglas que NO te puedes permitir que el modelo se salte —por ejemplo, "pregunta antes de cualquier git push"— la skill no es el sitio. Eso va en el global, porque el global siempre se carga. El reparto correcto no es "todo a skills", es "lo crítico-y-siempre al global, lo condicional a skills".
Mi global, entero (esto es todo)
Treinta líneas. Solo lo que aplica a toda sesión sin excepción:
# Preferencias globales
## Idioma
Responde siempre en español.
## Interacción
- Ante ambigüedad: pregunta antes de implementar. El coste de una
clarificación es menor que el de rehacer trabajo en la dirección
equivocada.
- Estilo balanceado: contexto cuando aporta, conciso cuando no.
- Sin postambles ("¿quieres que amplíe?", "espero que esto ayude").
- Sin sycophancy ("buena pregunta", "excelente idea").
## Código
- Respeta las convenciones del repo. No impongas las tuyas.
- Si tocas lógica no trivial, escribe tests sin que te lo pida.
- Antes de añadir una dependencia nueva, avísame y espera confirmación.
## Operaciones que requieren mi permiso explícito
Pregunta antes de ejecutar, aunque parezcan el paso obvio:
- `git push` y `git commit` — sin commits automáticos
- Deploys a cualquier entorno
- `rm`, `drop`, `sudo`, force-anythingFíjate en lo que NO está aquí: mi stack, las convenciones de proyectos concretos, cómo desplegar nada. Eso vive en skills condicionales o en el CLAUDE.md de cada repo.
Los otros dos archivos —la skill karpathy-guidelines (los 4 principios de Karpathy convertidos en skill condicional) y la skill foragustin (documentación de proyecto bajo demanda)— son más largos y los he dejado completos, listos para copiar, en un gist:
Qué NO meter nunca en el global
La regla de oro: si algo solo aplica a cierto tipo de tarea, proyecto o momento, no merece estar en el global. Lista de lo que veo metido ahí constantemente y dónde va mejor:
Convenciones de un proyecto concreto → al
CLAUDE.mddel repo, no al globalTu stack técnico personal → skill condicional
Workflows de deployment → skill bajo demanda
Estilo de redacción para newsletter, X, etc → skill condicional
Cualquier "acuérdate siempre de..." que solo aplica en un tipo de tarea → skill
Credenciales, tokens, claves → nunca, en ningún archivo de configuración
El anti-patrón que me costó semanas detectar
Mi caso real: tenía las instrucciones de mi skill de documentación metidas en el global. El síntoma fue sutil — Claude me proponía crear un archivo de documentación en cada repo nuevo, incluso cuando estaba arreglando un bug puntual que no tenía nada que ver. La sugerencia en momentos donde nadie había pedido docs.
Tardé semanas en conectar los puntos, porque cada interrupción individual parecía menor. El problema no era la instrucción en sí, era que estaba en el sitio equivocado: cargada siempre, disparándose cuando no tocaba. Moverla a una skill con una description que dice explícitamente "NO activar proactivamente" lo resolvió.
La señal para detectarlo antes: si Claude hace algo "razonable pero no pedido" de forma recurrente, probablemente tienes una instrucción en el global que debería ser condicional.
Mi opinión: la mayoría de builders están optimizando prompts y probando modelos, pero descuidan la arquitectura de instrucciones. No es un ejercicio de limpieza. Es una decisión de fiabilidad: dónde vive cada regla determina si el modelo la respeta cuando importa.
Build Log
TusPorras (Web/App Store / Play Console)
Seguimos centrados en los últimos detalles e implementaciones que nos proponen nuestros usuarios para TusPorras, el Mundial de 2026 está a menos de 10 días para comenzar.
Herramienta de la semana
Self-Hosted Sandboxes + MCP Tunnels (Claude Managed Agents) — Anthropic presentó en su conferencia de Londres dos features para ejecutar agentes con el cómputo y el acceso a datos dentro del perímetro del cliente.
Con los self-hosted sandboxes (beta pública), la ejecución de herramientas ocurre en tu infraestructura o en un proveedor gestionado (Cloudflare, Daytona, Modal, Vercel), mientras el agent loop —orquestación, gestión de contexto, recuperación de errores— sigue en Anthropic. Con los MCP tunnels (research preview, requiere solicitar acceso), un gateway ligero abre una única conexión saliente cifrada hacia servidores MCP en tu red privada, sin abrir puertos de entrada.
Veredicto: lo estoy mirando para mi stack GEO. Resuelve justo el dilema que me frena —dejar que un agente acceda a la base de datos sin exponer la red— pero ojo con el matiz: no es Claude on-premise total. La lógica de orquestación sigue fluyendo por Anthropic. Útil si tu compliance exige que los datos no salgan del perímetro; insuficiente si buscas aislamiento absoluto.
Dónde vive cada regla no es limpieza, es arquitectura: determina si tus agentes respetan las instrucciones críticas cuando la ventana de contexto se llena de ruido.
¿Cuántas líneas tiene tu CLAUDE.md global ahora mismo? Ábrelo y cuenta cuántas aplican a TODA sesión sin excepción. Respóndeme a este email con el número — te digo qué moverías a skills.
P.S. — Si te ha servido, pásaselo a ese colega que todavía tiene un archivo de configuración de 800 líneas.