Sysls advierte: Sobrecargar a Claude y Codex con contexto puede reducir el rendimiento

Autor: sysls

Compilado por Deep潮 TechFlow

Guía de Shenchao: El desarrollador y blogger sysls, con 2,6 millones de seguidores, escribió un artículo extenso y práctico que ha sido compartido por 827 personas y recibido 7.000 me gusta. Su núcleo es una sola frase: tus plugins, sistemas de memoria y diversos harnesses probablemente te están haciendo más daño que bien. Este artículo no trata de teorías generales, sino de principios operativos extraídos directamente de proyectos reales en producción: desde cómo controlar el contexto y manejar la tendencia de la IA a complacer, hasta cómo definir condiciones de finalización de tareas. Es el artículo más claro que se ha visto hasta ahora sobre la práctica de ingeniería con Claude/Codex.

El texto completo es:

Eres un desarrollador que usa Claude y Codex CLI todos los días, y cada día te preguntas si realmente has aprovechado al máximo sus capacidades. A veces ves que hace cosas absurdamente tontas, y no entiendes por qué algunas personas parecen estar construyendo cohetes con IA, mientras tú ni siquiera logras apilar dos piedras correctamente.

¿Piensas que es un problema de tu harness, del plugin, de la terminal, o algo así? Usaste beads, opencode, zep, y tu archivo CLAUDE.md tiene 26,000 líneas. Pero sin importar cuánto lo intentes, no entiendes por qué te alejas cada vez más del cielo, mientras otros se divierten con los ángeles.

This is the article you've been waiting for.

Además, no tengo intereses relacionados. Digo que CLAUDE.md también incluye AGENT.md, y que Claude también incluye Codex; uso ambos ampliamente.

En los últimos meses, he observado algo interesante: casi nadie sabe realmente cómo maximizar el potencial de los agentes.

Parece que un pequeño grupo puede hacer que los agentes construyan todo el mundo, mientras que los demás giran en un mar de herramientas, padeciendo síndrome de elección: creyendo que encontrar la combinación correcta de paquetes, habilidades o harness desbloqueará la AGI.

Hoy, quiero romper todo esto y dejarte una frase simple y honesta, y desde allí partiremos. No necesitas el último harness de agente, no necesitas instalar un millón de paquetes, y definitivamente no necesitas leer un millón de artículos para mantenerte competitivo. De hecho, tu pasión probablemente te hace más daño que bien.

No estoy aquí de turista: empecé a usarlo desde que los agentes apenas podían escribir código. Probé todos los paquetes, todos los marcos y todos los patrones. He escrito señales, infraestructura y tuberías de datos con fábricas de agentes, no «proyectos de juguete», sino casos de uso reales que funcionan en producción. Después de hacer todo esto...

Hoy, utilicé una configuración casi tan simple como posible, solo con CLI básicos (Claude Code y Codex), junto con una comprensión de algunos principios fundamentales de la ingeniería de agentes, y logré el trabajo más revolucionario de mi vida.

En primer lugar, debo decir que las empresas de modelos básicos están en un impulso históricamente significativo, y claramente no se desacelerarán pronto. Cada mejora en la inteligencia de los agentes cambiará la forma en que colaboras con ellos, ya que los agentes están siendo diseñados para ser cada vez más dispuestos a seguir instrucciones.

Hace apenas unas generaciones, si escribías en CLAUDE.md «Lee READTHISBEFOREDOINGANYTHING.md antes de hacer cualquier cosa», tenía un 50% de probabilidad de responderte «vete a la mierda» y hacer lo que quería. Hoy, cumple la mayoría de las instrucciones, incluso instrucciones anidadas complejas: por ejemplo, puedes decir «primero lee A, luego lee B, y si C, entonces lee D», y en la mayoría de los casos estará encantado de seguirlas.

¿Qué indica esto? El principio más importante es reconocer que cada nueva generación de agentes te obliga a replantearte qué es la solución óptima, y por eso es menos más.

Cuando usas muchos libraries y harness diferentes, te encierras en una «solución», pero este problema podría no existir ante los agentes de la próxima generación. ¿Sabes quiénes son los usuarios más entusiastas y de mayor uso de los agentes? Sí, son los empleados de empresas de vanguardia, que tienen presupuestos ilimitados de tokens y utilizan los modelos más recientes. ¿Entiendes qué significa esto?

Esto significa que, si existe un problema real y hay una buena solución, las empresas líderes serán los mayores usuarios de esa solución. ¿Y qué hacen a continuación? Incorporan esa solución en sus propios productos. Piensa en ello: ¿por qué una empresa permitiría que otro producto resuelva un dolor real y cree una dependencia externa? ¿Cómo sé que esto es cierto? Mira las habilidades, el harness de memoria, los subagentes... todos ellos comenzaron como soluciones a problemas reales, y fueron probadas en la práctica como verdaderamente útiles.

Entonces, si algo realmente es revolucionario y puede ampliar los casos de uso de los agentes de manera significativa, eventualmente se integrará en el producto principal de la empresa base. Créeme, la empresa base está avanzando a gran velocidad. Así que relájate, no necesitas instalar nada ni depender de ninguna dependencia externa para hacer tu mejor trabajo.

Predigo que en los comentarios aparecerá pronto: «SysLS, usé un harness de tal cosa, ¡es genial! ¡Reconstruí Google en un día!» — a esto digo: ¡Felicidades! Pero tú no eres tu público objetivo; representas a un grupo extremadamente, extremadamente minoritario de la comunidad que realmente entiende la ingeniería de agentes.

La verdad es que el contexto lo es todo. Otro problema con usar mil plugins y dependencias externas es que sufres mucho de «inflación de contexto»: tu agente se ahoga en demasiada información.

Déjame hacer un juego de adivinanza de palabras con Python. Fácil. Espera, ¿qué es esa nota de “gestión de memoria” de 26 sesiones atrás? Ah, el usuario tenía una pantalla bloqueada hace 71 sesiones porque generamos demasiados procesos secundarios. ¿Siempre hay que escribir notas? Bien, está bien... ¿qué tiene que ver esto con el juego de adivinanza de palabras?

Lo entiendes. Solo quieres proporcionar al agente la información exacta que necesita para completar la tarea, ni más ni menos. Cuanto mejor controle esto, mejor rendirá el agente. Una vez que empieces a introducir sistemas de memoria extraños, plugins o demasiadas habilidades con nombres y llamadas confusos, le estás dando al agente unas instrucciones para hacer una bomba y una receta para hornear un pastel, cuando solo quieres que escriba un poema sobre un bosque de secuoyas.

Entonces, vuelvo a predicar: elimina todas las dependencias, y luego...

Descripción precisa de los detalles de implementación

Remember that context is everything?

¿Recuerdas que querías inyectar al agente exactamente la información necesaria para completar la tarea, ni más ni menos?

La primera forma de lograr esto es separar la investigación de la implementación. Debes ser extremadamente preciso sobre lo que le pides al agente que haga.

¿Cuáles son las consecuencias de ser impreciso? «Haz un sistema de autenticación.» El agente debe investigar: ¿qué es un sistema de autenticación? ¿Cuáles son las opciones disponibles? ¿Cuáles son sus ventajas y desventajas? Ahora debe buscar en línea una gran cantidad de información que en realidad no necesita, llenando el contexto con detalles de implementación posibles. Cuando llegue el momento real de implementarlo, es más probable que se confunda o genere ilusiones innecesarias o irrelevantes sobre la solución de implementación elegida.

Por otro lado, si dices «implementar autenticación JWT con hash de contraseña bcrypt-12, rotación de tokens de actualización y expiración de 7 días...», no necesitas investigar ninguna otra alternativa; sabrás exactamente lo que quieres, lo que permitirá llenar el contexto con detalles de implementación.

Por supuesto, no siempre sabrás los detalles de implementación. Muchas veces no sabes qué es lo correcto, y a veces incluso deseas delegar la decisión sobre los detalles de implementación a un agente. ¿Qué hacer en este caso? Es muy sencillo: crea una tarea de investigación para explorar diversas posibilidades de implementación, ya sea para tomar tú la decisión o para que el agente elija qué implementación usar, y luego haz que otro agente, con un nuevo contexto, realice la implementación.

Una vez que comienzas a pensar así, descubrirás lugares en el flujo de trabajo donde el contexto del agente se contamina innecesariamente, y podrás establecer barreras de aislamiento en el flujo de trabajo del agente, abstractando la información innecesaria y dejando solo el contexto específico que le permite desempeñarse excelentemente en la tarea. Recuerda que tienes un miembro muy talentoso e inteligente del equipo que conoce todos los tipos de bolas del universo, pero a menos que le digas que quieres diseñar un espacio para que la gente baile y se divierta, seguirá hablándote de las ventajas de los objetos esféricos.

Limitaciones de diseño por tendencia a agradar

Nadie quiere usar un producto que siempre te critique, te diga que estás equivocado o ignore completamente tus instrucciones. Por eso, estos agentes se esforzarán por estar de acuerdo contigo y hacer lo que quieras que hagan.

Si le pides que agregue "feliz" después de cada tres palabras, intentará cumplirlo: la mayoría de las personas entienden esto. Su disposición es precisamente lo que lo convierte en un producto tan útil. Pero tiene una característica muy interesante: significa que si dices "ayúdame a encontrar un error en el repositorio de código", él encontrará un error, incluso si necesita "crear" uno. ¿Por qué? ¡Porque quiere mucho seguir tus instrucciones!

La mayoría se queja rápidamente de que los LLM generan ilusiones y fabrican cosas que no existen, sin darse cuenta de que el problema está en ellos mismos. Le pides que busque algo, y te lo entrega, ¡aunque para ello tenga que estirar un poco los hechos!

¿Qué hacer entonces? Descubrí que las indicaciones neutrales son muy efectivas, es decir, no sesgar al agente hacia un resultado específico. Por ejemplo, en lugar de decir «ayúdame a encontrar un error en la base de datos», digo «escanea toda la base de datos, intenta seguir la lógica de cada componente y reporta todos los hallazgos».

Estas indicaciones neutrales a veces descubren errores y a veces simplemente describen objetivamente cómo funciona el código. Pero no sesgan al agente hacia la suposición de que "hay errores".

Otra forma de manejar la tendencia a complacer es convertirla en una ventaja. Sé que el agente se esfuerza por agradarme y seguir mis instrucciones, y puedo inclinarme hacia un lado o hacia el otro.

Entonces le pedí a un agente de búsqueda de errores que identificara todos los errores en la base de datos, diciéndole que los errores de bajo impacto sumaran +1 punto, los de impacto moderado +5 puntos y los de alto impacto +10 puntos. Sé que este agente se entusiasmará mucho al identificar todos los tipos de errores (incluidos aquellos que no son errores), y luego me informará un puntaje de 104 puntos o algo similar. Considero esto como el superconjunto de todos los posibles errores.

Luego, le asigno un agente adversarial para refutarlos, diciéndole que obtiene la puntuación del error por cada refutación exitosa, pero si se equivoca, recibe -2 veces la puntuación del error. Este agente se esforzará por refutar la mayor cantidad posible de errores, pero debido al mecanismo de penalización, mantendrá cautela. Aún así, actuará activamente para "refutar" errores (incluidos los errores reales). Considero esto como un subconjunto de todos los errores reales.

Finalmente, utilicé un agente árbitro para sintetizar las entradas de ambos y otorgar puntuaciones. Le indiqué al agente árbitro que tenía la respuesta correcta real: si acertaba, recibía +1 punto; si se equivocaba, recibía -1 punto. Luego, el agente árbitro evaluó por separado al agente de búsqueda de errores y al agente adversario en cada «error». Lo que el árbitro declaraba como verdad, yo lo verificaba. En la mayoría de los casos, este método resultó sorprendentemente fiable; aunque ocasionalmente aún cometía errores, ya era una operación casi impecable.

Quizás descubras que solo buscar agentes de bugs es suficiente, pero este método me funciona muy bien porque aprovecha la característica inherente de cada agente, programada para querer complacer.

Este problema parece complicado, como si necesitaras estudiar a fondo y seguir de cerca los avances más recientes en IA, pero en realidad es muy simple... si OpenAI y Claude lo han implementado o han adquirido la empresa que lo implementa, probablemente sea útil.

¿Ha notado que las «habilidades (skills)» ya están por todas partes y forman parte de la documentación oficial de Claude y Codex? ¿Ha notado que OpenAI adquirió OpenClaw? ¿Ha notado que Claude agregó inmediatamente funciones de memoria, voz y trabajo remoto?

¿Qué tal la planificación? ¿Recuerdas cuando mucha gente descubrió que planificar antes de implementar realmente era muy útil, y se convirtió en una función principal?

Sí, ¡esos son útiles!

¿Recuerdas los stop-hooks interminables que eran extremadamente útiles porque los agentes evitaban hacer trabajos de larga duración... y luego, de la noche a la mañana, desapareció esa necesidad con la salida de Codex 5.2?

Eso es todo lo que necesitas saber... ¡Si algo es realmente importante y útil, Claude y Codex lo implementarán por sí solos! Así que no necesitas preocuparte demasiado por usar «cosas nuevas» o familiarizarte con «cosas nuevas», ni siquiera necesitas «mantenerte actualizado».

Ayúdame. Actualiza ocasionalmente tus herramientas CLI seleccionadas y lee qué nuevas funciones se han añadido. Eso es suficiente.

Algunas personas que usan proxies descubren una gran trampa: a veces parecen ser los seres más inteligentes del planeta, y otras veces no puedes creer que te hayan engañado.

Is this thing smart? This is fucking stupid!

La principal diferencia radica en si el agente se ve obligado a hacer suposiciones o "llenar espacios en blanco". Hoy en día, aún son terribles al "conectar puntos", "llenar espacios en blanco" o hacer suposiciones. Siempre que lo hagan, se nota inmediatamente y la situación empeora claramente.

Una de las reglas más importantes en CLAUDE.md es la relacionada con cómo obtener el contexto, y instruye al agente que, al leer CLAUDE.md (es decir, después de cada compresión), lo primero que debe hacer es leer esa regla. Como parte de la regla para obtener el contexto, algunas instrucciones simples pueden tener un gran impacto: volver a leer el plan de tarea y volver a leer los archivos relacionados con la tarea antes de continuar.

Los humanos tenemos una sensación bastante clara de cuándo se ha «completado» una tarea. Para los agentes, el mayor problema de la inteligencia actual es que saben cómo comenzar una tarea, pero no cómo terminarla.

Esto a menudo lleva a resultados muy frustrantes: el agente termina implementando un montón de stubs y se da por satisfecho.

La prueba es un excelente hito para el agente, ya que la prueba es determinista y puedes establecer expectativas muy claras. A menos que estos X tests pasen, tu tarea no estará completada; y no se te permite modificar las pruebas.

Luego, solo necesitas revisar las pruebas; una vez que todas las pruebas pasen, podrás estar tranquilo. También puedes automatizar esto, pero el punto clave es: recordar que «el final de la tarea» es natural para los humanos, pero no para los agentes.

¿Sabes si algo más ha sido establecido como un destino de tarea viable recientemente? Captura de pantalla + verificación. Puedes hacer que el agente realice algo hasta que todas las pruebas se aprueben, luego que tome una captura de pantalla y verifique el «diseño o comportamiento» en la captura de pantalla.

Esto te permite que el agente itere y se enfoque en el diseño que deseas, sin preocuparte de que se detenga después del primer intento.

La extensión natural de esto es crear un "contrato" con el agente e integrarlo en las reglas. Por ejemplo, este `{TASK}CONTRACT.md` establece qué se debe hacer antes de que se te permita finalizar la sesión. En `{TASK}CONTRACT.md`, especificarás las pruebas, capturas de pantalla y otras validaciones que deben completarse antes de que puedas certificar que la tarea ha finalizado.

Una pregunta que me hacen con frecuencia es cómo hacer que un agente funcione las 24 horas asegurándose de que no se desvíe.

Aquí hay un método muy sencillo. Crea un stop-hook que impida que el agente finalice la sesión a menos que todas las secciones de `{TASK}_CONTRACT.md` estén completas.

Si tienes 100 contratos con especificaciones claras que contienen el contenido que deseas construir, stop-hook evitará que el agente se detenga hasta que los 100 contratos hayan finalizado, incluyendo todas las pruebas y validaciones necesarias.

Consejo profesional: He descubierto que las sesiones de 24 horas prolongadas no son óptimas para "hacer cosas". Una parte de la razón es que este enfoque estructuralmente obliga a la inflación del contexto, ya que el contexto de contratos no relacionados ingresa a la misma sesión.

Por lo tanto, no recomiendo hacer esto.

Hay una forma mejor de automatizar el agente: abre una nueva sesión para cada contrato. Crea el contrato cada vez que necesites hacer algo.

Establezca una capa de orquestación para crear un nuevo contrato cuando «algo necesite hacerse» y cree una nueva sesión para procesar ese contrato.

Esto cambiará por completo tu experiencia de agente.

¿Contratarías a un asistente administrativo y esperarías que supiera tu agenda desde el primer día? ¿O cómo te tomas el café? ¿Cenas a las 6 p.m. en lugar de las 8 p.m.? Claramente no. Vas desarrollando tus preferencias con el tiempo.

Lo mismo aplica para el agente. Comienza con la configuración más simple, olvida las estructuras complejas o los harness, y dale una oportunidad al CLI básico.

Luego, añade gradualmente tus preferencias. ¿Cómo?

Reglas

Si no quieres que el agente haga algo, escríbelo como una regla. Luego, indícale al agente esa regla en CLAUDE.md. Por ejemplo: "Antes de escribir código, lee `coding-rules.md`". Las reglas pueden anidarse y pueden ser condicionales. Si estás escribiendo código, lee `coding-rules.md`; si estás escribiendo pruebas, lee `coding-test-rules.md`. Si tus pruebas están fallando, lee `coding-test-failing-rules.md`. Puedes crear reglas con ramificaciones lógicas arbitrarias que el agente siga; Claude (y Codex) estarán encantados de seguirlas, siempre que haya instrucciones claras en CLAUDE.md.

De hecho, esta es mi primera recomendación práctica: trata tu archivo CLAUDE.md como un directorio lógico y anidado que indique dónde buscar el contexto en escenarios y resultados específicos. Debe ser lo más conciso posible, conteniendo únicamente lógica IF-ELSE que especifique «en qué situación buscar el contexto».

Si ves que el agente hace algo que no estás de acuerdo, añádelo como una regla y dile al agente que lea esa regla antes de hacerlo nuevamente; seguramente ya no lo hará.

Habilidades

Las habilidades (Skills) funcionan de manera similar a las reglas, pero en lugar de ser preferencias de codificación, son más adecuadas para codificar «pasos de operación». Si tienes una forma específica en la que deseas que se complete una tarea, puedes incorporarla en una habilidad.

De hecho, las personas a menudo se quejan de no saber cómo un agente resolverá un problema, lo que resulta inquietante. Si deseas hacer esto más predecible, permite que el agente primero investigue cómo lo resolverá y luego documente la solución en un archivo de habilidades. Así podrás ver con anticipación cómo el agente abordará el problema y corregirlo o mejorarlo antes de que lo enfrente realmente.

¿Cómo le haces saber al agente que existe esta habilidad? ¡Exacto! Escribe en CLAUDE.md que, cuando te encuentres con este escenario y necesites manejar esto, leas este `SKILL.md`.

Reglas y habilidades de procesamiento

Seguramente quieras seguir añadiendo reglas y habilidades a tu agente. Así es como le das personalidad y memorizas tus preferencias. Casi todo lo demás es redundante.

Una vez que comiences a hacerlo, tu agente se sentirá como magia. Hará las cosas «de la manera que deseas». Entonces finalmente sentirás que has «comprendido» la ingeniería de agentes.

Luego...

Verás que el rendimiento comienza a disminuir nuevamente.

¿Qué pasa?

Es muy sencillo. A medida que añades más reglas y habilidades, comienzan a contradecirse entre sí, o el agente sufre un hinchamiento severo del contexto. Si necesitas que el agente lea 14 archivos Markdown antes de comenzar a programar, tendrá el mismo problema de una gran cantidad de información innecesaria.

¿Qué hacer?

Clean up. Have your agent take a spa break, integrate the rules and skills, and eliminate contradictions by specifying your updated preferences.

Then it will feel like magic again.

Eso es todo. Esa es realmente la clave. Manténlo simple, usa reglas y habilidades, trata el CLAUDE.md como un índice y presta atención devota a su contexto y limitaciones de diseño.

Hoy no existe un agente perfecto. Puedes delegar muchos trabajos de diseño e implementación al agente, pero eres responsable del resultado.

Así que ten cuidado... ¡y disfruta mucho!

¡Es un placer jugar con los juguetes del futuro (mientras claramente los usas para cosas serias)!