Universal Claude.md - Reducción de tokens de salida de Claude

 (github.com/drona23)
2 puntos por GN⁺ 29 일 전 | 1 comentarios | Compartir por WhatsApp
  • Un archivo de configuración que elimina introducciones, cierres y reformulaciones innecesarias del modelo Claude para reducir el desperdicio de tokens de salida
  • Al agregar CLAUDE.md en la raíz del proyecto, se aplica de inmediato sin modificar código y logra una reducción promedio del 63% en tokens
  • Simplifica las respuestas con 12 reglas, como salida solo ASCII, prohibido adivinar y limitar la respuesta al alcance solicitado
  • El ahorro de costos es grande en entornos de alta salida como pipelines de automatización, generación de código y loops de agentes, aunque puede ser ineficiente para consultas individuales
  • Publicado bajo licencia MIT, permite gestión de reglas basada en perfiles por equipo o tarea y aportes de la comunidad

Resumen del problema

  • En Claude Code, cada palabra generada implica un costo en tokens, y con la configuración predeterminada el usuario tiene poco control sobre el formato de respuesta
  • De forma predeterminada, se incluyen automáticamente introducciones corteses como “Sure!” o “Great question!”, cierres formales como “I hope this helps!”, reformulaciones de la pregunta y sugerencias innecesarias
  • Además, usa caracteres como em dash, comillas tipográficas y caracteres Unicode que pueden romper parsers, e incluye abstracción excesiva de código o expresiones de acuerdo incorrectas
  • Esto provoca desperdicio de tokens con casi ningún valor informativo real

Solución

  • Si agregas un archivo CLAUDE.md en la raíz del proyecto, Claude Code lo lee automáticamente y cambia de inmediato su comportamiento de salida
  • Funciona sin modificar código ni configuraciones adicionales, y reduce el uso de tokens de salida en aproximadamente un 63%
  • Ejemplo de estructura 
    your-project/
└── CLAUDE.md

Cuándo conviene aplicarlo y cuándo no

  • Casos favorables

    • Pipelines de automatización, loops de agentes y generación de código en tareas con mucho volumen de salida

      • Cuando en tareas repetitivas y estructuradas se va acumulando la verbosidad de las respuestas predeterminadas de Claude
      • En entornos de equipo donde se necesita un formato de salida consistente entre sesiones

  • Casos desfavorables

    • En consultas cortas individuales o uso puntual, CLAUDE.md ocupa tokens de entrada cada vez, por lo que puede incluso aumentar el costo
    • No ayuda a resolver problemas profundos como corrección de alucinaciones (hallucinations) o errores de arquitectura
    • En pipelines que abren una sesión nueva para cada tarea, desaparece el efecto de ahorro basado en sesiones persistentes
    • Para garantizar confiabilidad de parsers a gran escala, es más apropiado usar modo JSON o herramientas basadas en esquemas
    • En tareas exploratorias o centradas en discusión, puede sentirse restrictivo

  • Compromiso real

    • Como CLAUDE.md también consume tokens de entrada, solo hay beneficio neto cuando el volumen de salida es suficientemente alto
    • En usos de bajo volumen, el costo puede superar el ahorro

Resultados del benchmark

  • Prueba con los mismos 5 prompts
    Prueba Base Optimizado Reducción
    Explicación de async/await 180 palabras 65 palabras 64%
    Code review 120 palabras 30 palabras 75%
    Explicación de REST API 110 palabras 55 palabras 50%
    Corrección de alucinación 55 palabras 20 palabras 64%
    Total 465 palabras 170 palabras 63%
  • Ahorro de aproximadamente 295 palabras, sin pérdida de información
  • Aun así, esto es solo un indicador direccional; no se realizaron controles estadísticos ni experimentos repetidos
  • El ahorro neto solo ocurre en casos con mucho volumen de salida

  • Ejemplo de ahorro en uso a gran escala

    Uso Tokens ahorrados por día Ahorro mensual (según Sonnet)
    100 veces/día aprox. 9,600 aprox. $0.86
    1,000 veces/día aprox. 96,000 aprox. $8.64
    3 proyectos aprox. 288,000 aprox. $25.92

Ejemplo comparativo antes y después

  • Respuesta base de code review (120 palabras)

    • Incluye elogios, explicaciones y sugerencias extensas

  • Después de aplicar CLAUDE.md (30 palabras)

    • En formato como “Bug: <= causes an off-by-one error…”, transmite solo lo esencial y reduce 75% de los tokens

Qué se corrige

Nro. Problema Forma de corrección
1 Introducción aduladora Prohibida - comenzar a responder desde la primera línea
2 Cierre vacío Prohibido - eliminar “I hope this helps!”
3 Reformulación de la pregunta Prohibida - ejecutar de inmediato
4 em dash, comillas tipográficas y Unicode Forzar salida solo ASCII
5 Frases como “As an AI...” Prohibidas
6 Descargos innecesarios Permitidos solo si hay un riesgo real de seguridad
7 Sugerencias fuera de lo pedido Prohibidas - hacer solo lo solicitado
8 Abstracción excesiva de código Permitir solo el código funcional más simple
9 Alucinaciones sobre hechos inciertos Indicar “no lo sé”, prohibido adivinar
10 Ignorar correcciones del usuario Las correcciones se fijan como hechos válidos en la sesión
11 Lectura duplicada de archivos Prohibido releer el mismo archivo
12 Ampliación del alcance Prohibido modificar código fuera de lo solicitado

Consejos de la comunidad

  • Lo más efectivo es escribir reglas ajustadas a patrones reales de fallo
    • Ejemplo: si Claude oculta errores de un pipeline -> agregar la regla “si falla una etapa, detenerse de inmediato y reportar el error completo y el traceback”

  • El archivo CLAUDE.md puede fusionarse jerárquicamente

    • Global (~/.claude/CLAUDE.md): reglas generales (tono, ASCII, etc.)
    • Raíz del proyecto: restricciones por proyecto (ej.: prohibido modificar /config)
    • Subdirectorios: reglas detalladas por tarea
    • Esto permite gestionar reglas de forma distribuida y evitar que el archivo crezca demasiado

Configuración de perfiles

  • Se puede elegir un nivel distinto de compresión según el tipo de proyecto
    Perfil Adecuado para
    CLAUDE.md Uso general
    profiles/CLAUDE.coding.md Desarrollo, code review y debugging
    profiles/CLAUDE.agents.md Automatización y sistemas multiagente
    profiles/CLAUDE.analysis.md Análisis de datos, research y reporting

Cómo usarlo

Reglas de override

  • Las instrucciones del usuario siempre tienen prioridad

    • Si el usuario indica explícitamente algo como “explícalo en detalle”, Claude lo sigue tal cual
    • CLAUDE.md no bloquea la intención del usuario

Cómo contribuir

  • Si detectas un comportamiento corregible, registra un Issue
    1. El comportamiento predeterminado problemático
    2. El prompt que lo provocó
    3. La regla de corrección propuesta
  • Las propuestas de la comunidad se reflejarán en la siguiente versión y se otorgará crédito a quienes contribuyan

Verificación y referencias

  • Los resultados completos del benchmark pueden consultarse en BENCHMARK.md
  • El proyecto fue creado a partir de casos reales de queja de la comunidad de Claude
  • Incluye múltiples fuentes de referencia relacionadas (GitHub Issues, The Register, DEV Community, Medium, Anthropic Docs, etc.)

Licencia

  • Licencia MIT, con libertad de uso, modificación y distribución

Lecturas relacionadas

1 comentarios

 
GN⁺ 29 일 전
Comentarios de Hacker News

  • Creo que el benchmark aquí está sesgado hacia tareas descriptivas únicas y no es adecuado para bucles de agente como la generación de código
    Me pregunto si, cuando un proyecto está en marcha, las explicaciones verbosas de Claude ayudan más bien a mantener la coherencia y el enfoque de la sesión
    La regla de “no repetir contexto redundante” está bien, pero yo más bien creo que ayuda usar más tokens de razonamiento orientados a objetivos
    Aún faltan datos para saber si este enfoque realmente funciona en coding agéntico

    • Yo hice una skill llamada /handoff para que genere automáticamente un reporte en Markdown antes de que la sesión llegue al límite de compresión
      Ese archivo sirve como registro permanente de la sesión y como una especie de “reporte diario”, así que luego es fácil consultarlo o compartirlo con el manager
      Para mantener la coherencia a largo plazo, creo que este tipo de documentación resumida funciona mejor
      Dejé la instalación aquí
    • Gracias a la regla de “no expliques qué vas a hacer, simplemente hazlo”, pude notar de inmediato cuando Claude iba en la dirección equivocada y corregir el prompt
    • No entiendo por qué la gente no pone en CLAUDE.md reglas para bloquear el lenguaje innecesario
      Según investigaciones recientes, la ruta de razonamiento redundante (self-consistency) y el model ensembling ayudan a mejorar el rendimiento
    • El escalado del tiempo de razonamiento también importa. Usar más tokens al buscar una respuesta puede mejorar la calidad
      Obsesionarse con la longitud mínima va en contra del objetivo de entrenamiento por RL
    • Corrí pruebas de coding con varias configuraciones y, en general, este enfoque dio peor rendimiento en 30 corridas
      El código de prueba está aquí

  • El planning mode de Claude Code no funciona bien, así que soy escéptico con este enfoque basado en archivos .md
    En mi opinión, planning mode debería ser simplemente una función para desactivar la escritura de archivos

  • La regla de “la respuesta siempre en la primera línea, el razonamiento después” ignora la naturaleza autorregresiva de los LLM
    Si fijas primero la respuesta, existe un alto riesgo de que el razonamiento posterior caiga en sesgo de confirmación

    • La idea de este enfoque es buena, pero creo que la implementación está mal
      Un método de compresión del razonamiento como el del paper Compressed Chain of Thought (CCoT) es más eficiente
      Hay una pequeña pérdida de calidad, pero ofrece ventajas en velocidad y costo (paper)
    • En sesiones importantes agrego prompts de segunda revisión como “sanity check” para volver a examinar el plan inicial
    • Un reasoning LLM puede generar internamente miles de tokens de razonamiento antes de escribir la respuesta
      O sea, la regla de “respuesta primero” solo cambia el orden de salida, no el orden real del razonamiento
    • Claude Code no tiene una opción de “no thinking”; como mínimo, el modo por defecto es low thinking

  • Este benchmark no tiene sentido porque compara solo la cantidad de tokens de salida sin considerar la precisión
    También sería fácil subir la puntuación con un prompt como “responde siempre con una sola palabra”
    Reglas como “si el usuario señala un error factual, acéptalo siempre” son peligrosas

    • Se habla de “¿volvió el prompt engineering?”, pero en los últimos 1 o 2 años los meta-prompts no han mostrado grandes mejoras
    • Reglas del tipo “no cometas errores” no son realistas

  • Creo que este tipo de soluciones universales pierde atractivo rápido o termina absorbido por CC
    Cambiar de workflow a cada rato es demasiado cansado
    Por ahora, la configuración por defecto de Claude Code es la más estable

    • Pienso algo parecido. Siento que mantener una configuración vanilla es mejor a largo plazo
      Me gustan las Skills, pero casi no uso MCP ni worktree
    • Dentro de Anthropic ya deben estar optimizando esto con dogfooding interno, así que es muy probable que la configuración por defecto sea la más eficiente
      Basta con tratar CLAUDE.md como una nota borrador para un colega inteligente y ya funciona bastante bien
    • Estoy de acuerdo con eso de que “al final se integrará en CC”
      Si Anthropic no lo incluyó directamente, probablemente es porque la mejora de rendimiento no está demostrada
    • Estas “capas para mejorar Claude” terminan causando inestabilidad en el workflow
      Aunque sirvan por un rato, rápido se absorben en la funcionalidad base o desaparecen
    • El propio Claude también sigue actualizando sus funciones de optimización para md
      Por eso, incluso si usas scripts experimentales de este tipo, puedes mantenerte al día actualizando seguido los archivos md

  • A la pregunta de “si el archivo se carga en el contexto con cada mensaje, ¿no es un desperdicio de tokens?”,
    creo que la función de personalización de Claude ya cumple ese papel
    Para mí, la brevedad solo tiene sentido cuando mejora la calidad
    También me parecieron interesantes algunas herramientas relacionadas que vi en Reddit:
    Headroom comprime el contexto un 34%,
    RTK comprime la salida del CLI entre 60% y 90%,
    y MemStack ofrece memoria persistente para evitar releer archivos innecesariamente

  • Siento que estos intentos más bien vienen de malentender los principios básicos de los LLM
    “Respuesta primero, razonamiento después” ignora la arquitectura autorregresiva de los transformers
    Como el entrenamiento con RL ya ajusta la longitud óptima y la calidad, meter demasiadas modificaciones puede llevar a una caída de rendimiento

    • Si fuerzas respuestas más cortas, baja la calidad y coherencia del razonamiento y sube la probabilidad de alucinación
      El modelo está entrenado para hacer razonamiento de múltiples pasos principalmente en inglés
    • La regla de “respuesta primero” no cambia el orden real del razonamiento. El modelo ya pensó internamente antes de producir la respuesta
    • No creo que el autor desconozca los transformers; más bien parece que intentó un hack simple para reducir costos de tokens
      Es un enfoque experimental que prioriza eficiencia sobre calidad
    • La mayoría de las API ya ofrecen opciones para controlar la longitud del COT. Me parece mejor usar esos ajustes que este tipo de atajos
    • Al final, creo que las herramientas hechas por Anthropic son las más confiables.
      Por eso yo solo uso herramientas 1st-party en lugar de terceros como OpenCode

  • Como se ve en un video de Karpathy, mientras más tokens usa el modelo, más tiende a subir la precisión
    Este enfoque podría incluso empeorar el modelo

    • Aun así, si aquí el objetivo es reducir salida de poco valor (por ejemplo, frases aduladoras o ruido de formato), podría tener sentido
      Pero si se le hace responder de inmediato sin razonar, existe el riesgo de sesgo de fijación temprana
    • La salida redundante también sirve para reforzar la dirección, así que eliminarla puede aumentar la ambigüedad

  • No entiendo por qué este tipo de proyectos sin sentido se vuelve tendencia en HN
    Las herramientas que de verdad reducen el uso de tokens son claude-mem y lumen

    • La razón es simple. El algoritmo de tendencias de HN está optimizado para participación, no para precisión

  • Antes investigábamos nuevos algoritmos de hash, cifrado y compresión
    Ahora es irónico que estemos investigando cómo decirle a una IA que se calle