CodeBuddy: Recuperación de contexto más inteligente para agentes de programación por IA

El problema subestimado en la programación por agentes

La emoción generada por los agentes de programación basados en IA es más que justificada: Claude, Codex, Cursor y los demás se han convertido en herramientas realmente útiles. Pero si pasas más de una semana utilizando uno con un gran conjunto de código del mundo real, suele surgir un problema conocido.

El propio agente no es el factor limitante. No es la capacidad del modelo lo que falla; lo que falla es el contexto.

Hay dos patrones de fallo recurrentes que aparecen una y otra vez:

1. Faltarle contexto al agente — le asignas una tarea y él no tiene idea de las convenciones que sigue tu proyecto, no recuerda ningún error similar que ya se corrigió y luego se anuló, ni sabe qué archivos dependen del que está a punto de modificar. El resultado es una edición que parece razonable por separado, pero que es incorrecta para el sistema en su conjunto.

Saturar al agente con contexto — para eludir ese primer problema, se le proporciona todo el repositorio o se le permite buscar entre todo indiscriminadamente. Ahora cada tarea lleva más tiempo, cuesta más, y la instrucción está llena de ruido. El modelo gasta su presupuesto de atención en archivos que no son importantes en lugar de aquellos pocos que sí lo son.

Ninguno de estos problemas se refiere realmente a la inteligencia del modelo. Ambos son síntomas de una mala ingeniería de contexto. Ese es el problema real que CodeBuddy se propone solucionar.

Nacido como solución temporal, no como producto planificado

Mucho antes de que CodeBuddy existiera como herramienta, su idea central ya se estaba aplicando manualmente.

Cada vez que era necesario realizar un cambio real en un proyecto con Claude, la rutina siempre era la misma: localizar las funciones relevantes, encontrar las pruebas que cubrían esa parte del código, consultar cualquier nota que explicara por qué se había estructurado todo de esa manera y pegar todo ello en la conversación antes incluso de describir el cambio. Funcionaba, pero era tedioso, repetitivo y dependía por completo de recordar la base de código; una memoria que inevitablemente empeora a medida que el proyecto crece.

Con el tiempo surgió la pregunta obvia: ¿por qué una persona tenía que actuar como mecanismo de recuperación de contexto? Se trata de una tarea mecánica y repetible que debería realizarse mediante automatización, no en la mente de alguien.

De ahí surgió realmente CodeBuddy: no fue una decisión de crear “una herramienta para desarrolladores con IA”, sino la decisión de dejar de realizar esas búsquedas manualmente.

El atajo falso: evitar Graphify

Automatizar ese paso de recuperación significaba decidir cómo CodeBuddy entendería la estructura de un proyecto: qué archivos dependen de cuáles, qué funciones llaman a cuáles y dónde se encuentran los verdaderos límites arquitectónicos.

Un proyecto separado, Graphify, ya abordó este problema al crear un gráfico de dependencias real de una base de código, mapeando las relaciones reales entre archivos en lugar de inferirlas a partir de patrones de nombres o proximidad. Incorporarlo como dependencia parecía una complejidad innecesaria: un componente más, un paso de instalación adicional y un punto potencial de fallo más. El plan inicial era omitirlo por completo y hacer que CodeBuddy creara su propio índice arquitectónico ligero, utilizando extracción de símbolos, coocurrencia de archivos y unas pocas heurísticas, lo suficiente como para orientar al agente en una dirección razonable.

Ese enfoque resultó insuficiente.

El índice ligero podía mostrar qué se encontraba cerca de qué, pero no podía explicar con fiabilidad por qué dos archivos estaban realmente conectados, ni rastrear una cadena de dependencias de tres o cuatro niveles de profundidad; precisamente el tipo de información que es más importante antes de modificar código con un amplio alcance de impacto. Repetidamente, el agente realizaba cambios que a simple vista parecían seguros pero rompían algo en un nivel intermedio, simplemente porque el índice no había capturado esa relación con la precisión suficiente.

Eso llevó a un cambio de enfoque. En lugar de tratar a Graphify como una carga adicional opcional alrededor de la cual diseñar el sistema, pasó a ser una parte esencial del mismo: CodeBuddy sigue funcionando por sí solo, utilizando su índice interno, para quienes prefieren no añadir configuraciones adicionales. Pero si está instalado Graphify, CodeBuddy se basa en su gráfico como fuente autorizada de las relaciones arquitectónicas, en lugar de confiar en conjeturas.

Ese cambio de dirección es la verdadera historia detrás del flujo de trabajo actual: no se trata de una nueva función añadida al azar, sino del reconocimiento de que un diseño más simple resultaba en realidad peor, lo que llevó a reconstruir todo alrededor de esa misma dependencia que originalmente se había evitado.

Así es CodeBuddy en la práctica hoy en día

1. Configuración inicial

npm install -g @ayushkumar320/codebuddy
codebuddy

Ejecutar codebuddy dentro de un proyecto se encarga de los pasos de configuración poco atractivos pero esenciales:

• Se conecta a una base de datos PostgreSQL local
• Aplica el esquema y la configuración necesarios para ese proyecto específico
• Genera un archivo de configuración privado exclusivo para ese proyecto
• Se integra con Claude y Codex, añadiendo instrucciones que indican al agente cómo utilizar las herramientas de CodeBuddy
• Pide confirmación para decidir si activar Graphify

Al elegir habilitar Graphify, se conecta su servidor MCP; posteriormente, al ejecutar /graphify . una vez, se crea el mapa arquitectónico inicial del proyecto. Si se rechaza esta opción, CodeBuddy recurre a su propio índice ligero: la herramienta sigue funcionando plenamente, pero la imagen arquitectónica resultante es menos precisa.

2. El bucle principal: context_pack

Aquí es donde tiene lugar el trabajo real. Cuando le asignas una tarea al agente —por ejemplo, “añadir inicio de sesión con OAuth”— este no comienza a buscar archivos al azar ni a analizar todo el repositorio. En su lugar, llama a la herramienta context_pack de CodeBuddy, que elabora un paquete bien delimitado que contiene:

• Los archivos que realmente son relevantes para la tarea
• Las funciones y clases específicas involucradas, en lugar de archivos completos siempre que sea posible evitarlo

Pruebas que ya prueban esa área del código

Convenciones o reglas específicas del proyecto que se aplican aquí

Bugues o regresiones anteriores relacionados con esa sección del código

Cualquier archivo que se vería afectado una vez cambien los archivos objetivo

Planes o decisiones existentes relevantes para la tarea

Las relaciones arquitectónicas que rodean esos archivos, obtenidas de Graphify cuando está activo o del índice interno cuando no lo está

El resultado es un paquete pequeño, denso y relacionado con el tema en cuestión, en lugar de uno extenso y poco detallado. Esa distinción es lo que separa un comportamiento verdaderamente consciente del contexto de algo que solo parece serlo.

3. El agente implementa el cambio

Con ese paquete en mano, Claude o Codex cuenta con suficiente información para analizar los efectos a largo plazo y no solo las diferencias inmediatas: cosas como qué llamadas dependen de esta función, qué pruebas deben seguir funcionando y si ya se intentó este mismo enfoque anteriormente y se deshizo.

4. CodeBuddy recuerda

Una vez finalizada la tarea, el agente puede escribir en CodeBuddy todo lo que aprendió: las decisiones que tomó, las reglas que descubrió en el proceso, las regresiones con las que se topó y los enfoques que resultaron efectivos. Ese conocimiento permanece localmente, distribuido entre la memoria de Postgres y Markdown, y se integra en el paquete de contexto para la siguiente tarea relacionada. En lugar de reiniciarse a cero en cada sesión, el sistema se vuelve cada vez más preciso.

5. Las PRs se revisan automáticamente

Un flujo de trabajo de GitHub puede informar automáticamente sobre cada solicitud de pull request, abarcando:

• Qué tan arriesgada parece ser la cambio
• Dónde falta cobertura de pruebas
• Qué afecta el cambio desde el punto de vista arquitectónico
• Si la implementación se desvió del plan original
• Si la verificación realmente tuvo éxito

Por qué esto es más importante de lo que parece

Es tentador clasificarlo como “otra herramienta de desarrollo basada en Claude”. Esa forma de verlo pasa por alto varios aspectos:

Aborda el verdadero cuello de botella. Los modelos siguen ganando capacidad a un ritmo acelerado. La calidad del contexto que se les proporciona no ha avanzado al mismo ritmo en el ámbito de las herramientas; la mayoría de las configuraciones siguen leyendo archivos completos o utilizando búsquedas simples con la esperanza de obtener buenos resultados. CodeBuddy se basa en la premisa de que los próximos avances significativos en el código agente provendrán de mejorar lo que se alimenta al modelo, y no del propio modelo.

Con el tiempo, se va mejorando por sí mismo. Por defecto, una ventana de contexto no tiene memoria: cada sesión comienza desde cero a menos que el sistema circundante preserve deliberadamente el estado. Dado que CodeBuddy lleva un registro de las decisiones, reglas y retrocesos, la décima tarea en una base de código determinada debería realizarse más fluidamente que la primera, sin necesidad de volver a explicar las mismas cosas.

Son transparentes respecto a los compromisos, en lugar de ocultarlos. Hacer que Graphify sea opcional es una respuesta directa a un intento anterior de eliminar por completo ese compromiso, lo cual no funcionó. Puedes elegir: sin configuración adicional y un índice ligero funcional, o un grafo de arquitectura verdaderamente preciso si estás dispuesto a añadir un componente más.

Todo permanece en su máquina. PostgreSQL, el almacenamiento en memoria de Markdown, el índice interno y el grafo de Graphify se ejecutan localmente. Las credenciales se encuentran en un archivo de configuración privado. Mejorar el contexto del agente no requiere enviar su código a ningún lugar nuevo.

Se integra con las herramientas que la gente ya utiliza. No se trata de un editor nuevo ni de un agente nuevo que aprender: se conecta directamente a Claude y Codex, acompañándolo donde ya trabaja y haciendo que sean más eficaces a la hora de comprender el códigobase que tienen ante sí.

Hacia dónde va esto a partir de ahora

Se trata aún de un proyecto en una fase inicial y en constante iteración; el sistema de memoria, en particular, es donde más se nota la necesidad de mejoras: por ahora funciona más como notas estructuradas que como un sistema de memoria con capacidad de recuperación jerarquizada. Si estás utilizando agentes de programación basados en IA en un repositorio real y te encuentras con el problema de “no entiende mi proyecto”, agradecemos sinceramente tus comentarios:

npm install -g @ayushkumar320/codebuddy

Si lo pruebas o has abordado este problema de otra manera en tu propio entorno, compartir esa experiencia sería muy útil.

CodeBuddy es una capa de gestión de contexto para agentes de programación basados en IA como Claude y Codex. Prepara un contexto enfocado y relevante en lugar de forzar la lectura de todo el repositorio, y opcionalmente puede integrarse con Graphify para obtener un mapa de arquitectura más detallado. Está disponible en npm como @ayushkumar320/codebuddy.

Lecturas relacionadas

• Comprendiendo los agentes de IA: objetivos, herramientas, memoria y el bucle del agente — Una explicación adecuada para principiantes sobre cómo los agentes de IA difieren de los chatbots, que abarca sus componentes esenciales, el bucle de toma de decisiones, los niveles de autonomía y casos de uso en el mundo real.
• Comparando los agentes de IA Frontier: Astra, Flash, Fable y Mythos — Un análisis de cómo las últimas versiones de los modelos GPT, Gemini y Claude rinden en tareas reales de agencia como la programación, el navegación y el uso de herramientas, más allá de las pruebas de rendimiento estándar.

Cómo el Protocolo de Contexto del Modelo permite a los agentes de IA descubrir y llamar herramientas — Una explicación clara de MCP: cómo los hosts, clientes y servidores permiten que una aplicación de IA descubra herramientas, las llame con entradas estructuradas y cuáles son sus limitaciones.