Sumit Pandey diseccionó un fenómeno difícil de ignorar: un único archivo CLAUDE.md del repositorio andrej-karpathy-skills reunió cerca de 91.000 estrellas en GitHub sin una sola línea de código — cuatro reglas de comportamiento destiladas de las observaciones de Karpathy. „Piensa antes de codificar“, „simplicidad primero“, „cambios quirúrgicos“, „ejecución guiada por objetivos“. Pandey hace un diagnóstico preciso y cierra con la frase que volvió ruidoso el artículo: «it is winning because it is not a layer. It is a contract». Yo mantengo un CLAUDE.md grande y por capas sobre un enrutamiento de contexto automático — y justo por eso quiero discutir esa tesis. No refutarla. Fijar la frontera más allá de la cual deja de sostenerse.
Mi tesis: tiene razón para la mediana, pero «contrato» y «capa» no son opuestos — son dos puntos de una misma escala
Pandey tiene razón en lo principal: para el usuario mediano un archivo plano de cuatro reglas no es simplicidad por pobreza, sino simplicidad ganada. La mayoría de los proyectos deberían empezar exactamente así. Pero yo giraría su metáfora. «Contrato» y «capa» no son opuestos entre los que haya que elegir. El archivo plano es un contrato exactamente mientras una sola hoja de reglas baste para expresar toda obligación. Las capas (mi enrutamiento de tres ejes es una historia ya publicada, y no la repito aquí) no son un abandono del contrato, sino complejidad ganada que se paga exactamente una vez: cuando adquieres un problema que el archivo plano es físicamente incapaz de escribir sin contradicción. Antes de ese momento, las capas son ruido. Después, el propio archivo plano se vuelve ruido, y sus reglas se pudren.
Dónde tiene razón: las cuatro reglas cierran una brecha real, y la viralidad es un voto por el problema
Lo más fuerte del artículo no son las reglas en sí, sino la honestidad sobre por qué hacen falta. Pandey describe sus propios fracasos literalmente: un agente le acopló inyección de dependencias y una clase con ocho métodos a una caché de tres líneas; otro agente, al arreglar el parseo de una fecha, «reformatted the entire file» y reescribió funciones no adyacentes. Reconozco cada línea — esto no es exótico, es el comportamiento por defecto. Las reglas son obvias para un ingeniero sénior y no lo son para el modelo; esa es exactamente la brecha que el archivo cierra. Y Pandey interpreta bien la viralidad: 91.000 estrellas son «not a vote on the file. It is a vote on the problem». Suposiciones silenciosas, sobrecomplejidad, expansión del alcance — los tres muros contra los que choca todo el que trabaja en serio con agentes. El archivo los nombra en lenguaje llano y se instala en treinta segundos. Estoy del todo de acuerdo: la barrera de entrada decide, y para la mayoría este es el primer y único paso correcto.
Dónde es incompleto: «mejora la distribución del comportamiento» es en sí mismo la línea de fractura
La frase más importante del artículo no es la ruidosa, sino la silenciosa en las salvedades: el archivo «improves the distribution of behavior. It does not guarantee specific behavior». Pandey la pone honestamente sobre la mesa y sigue adelante. Yo me detengo en ella, porque aquí corre la costura que decide qué se puede siquiera escribir en un CLAUDE.md.
Una instrucción en markdown es un sesgo probabilístico, no una garantía. Para preferencias blandas eso basta: estilo de nombres, elección de framework, política de pruebas, «no refactorices código vecino». Si el modelo viola el estilo una vez de cada veinte, sobreviviré — la revisión lo atrapará. Pero hay una clase de reglas para las que la «distribución mejorada» es un fracaso, no un éxito. El cumplimiento normativo y la seguridad de producción no pueden expresarse como preferencia. Un precedente que un prompt no puede escribir con honestidad: «para remotos de la forma github.com/OEM-WEB/*, los commits y los PR no deben contener el trailer Co-Authored-By: Claude». Un archivo de comportamiento plano puede pedirlo. No puede garantizarlo — porque una instrucción en prosa es por definición no vinculante, y el requisito legal de un cliente no se divide en «distribución mejorada».
De ahí mi línea dura en la autoría. Las preferencias blandas viven en markdown — ahí es donde corresponden, y el archivo plano basta allí para casi todos. El cumplimiento y la seguridad de producción los mecanizo: detección del remoto antes de un commit, una compuerta de aprobación nominal antes de acciones contra producción, inyección del contexto necesario mediante un hook al iniciar la sesión. No porque ame las capas — no las amo, cuestan mantenimiento. Sino porque un prompt es inaplicable por naturaleza, y la única forma de convertir «pedido» en «garantizado» es sacar la regla de la prosa hacia un mecanismo ejecutable. Este es exactamente el caso donde el «contrato-como-texto» de Pandey se rompe y debe ceder ante el «contrato-como-arnés».
Qué hacer al respecto: empieza plano, pon capas solo cuando la escala obligue
De aquí surge la regla con la que construiría un CLAUDE.md hoy — y casi siempre devuelve la respuesta «mantente plano».
Empieza con un archivo plano. Las cuatro reglas de Pandey más tus convenciones de proyecto — nombres, framework, pruebas. Eso es un contrato, y para un proyecto en una organización es autosuficiente. No construyas un enrutamiento que no tienes motivo para construir.
No pongas capas por gusto — ponlas ante una señal de alarma. Para que esto no sea una excusa, necesitas un umbral falsable. Mi disparador de capas se activa cuando se cumple al menos uno: (a) tienes dos o más organizaciones con reglas de cumplimiento en conflicto que el archivo plano no puede registrar sin autocontradicción; o (b) ha aparecido una regla que debe garantizarse, no pedirse — es decir, una violación cuesta no una revisión, sino un incidente. Hasta que se active uno de los umbrales, el archivo plano es estrictamente mejor. Las capas añadidas antes son complejidad que pagas sin el problema que ellas resuelven.
Separa lo que pides de lo que garantizas. Antes de añadir una línea al CLAUDE.md, pregunta: ¿es una preferencia o una obligación? Una preferencia va a markdown, y gracias a Pandey por mostrar lo poco que hace falta. Una obligación va de la prosa a un mecanismo: un hook, una compuerta, una verificación pre-commit. Si una regla importa exactamente tanto que la «distribución mejorada» no basta — entonces no pertenece a un archivo que solo mejora la distribución.
La conclusión es corta. Pandey tiene razón, y su acierto importa más de lo que sugiere el volumen de la tesis: casi todos necesitan un contrato plano, y casi todos lo sobrecomplican. Pero el archivo plano y el enrutamiento por capas no son bandos — son dos extremos de una misma escala de complejidad ganada. Empieza por la izquierda. Muévete a la derecha solo cuando tengas en la mano un problema de cumplimiento que una hoja de reglas no pueda expresar, o un requisito que no puedas dejar como una petición en prosa. Y entonces la lección honesta del artículo de Pandey no es «el contrato venció a las capas», sino «escribe en prosa todo lo que puedas pedir, y mecaniza todo lo que debas garantizar».