Project Resources en Kaddo: conectar el contexto real del sistema

Cuando hablamos de contexto para agentes de IA en desarrollo de software, es normal pensar primero en código, documentación, arquitectura o Work Items. Sin embargo, un sistema real no vive únicamente dentro del repositorio. Depende de bases de datos, APIs, colas, servicios externos, almacenamiento, componentes compartidos y otros recursos que condicionan cómo funciona y cómo puede evolucionar.

Ese contexto muchas veces existe, pero está distribuido entre variables de entorno, infraestructura, documentación, conocimiento del equipo y relaciones que nadie dejó explícitas. Podemos entender qué hace un módulo y aun así no tener claro de qué depende para operar. Ese vacío se vuelve importante cuando una persona o un agente necesita modificar el sistema con una visión completa, ahí es donde entran los Project Resources de Kaddo.

 

Decir que un proyecto utiliza PostgreSQL, Redis, Kafka o S3 nos ayuda a entender el stack, pero no necesariamente nos dice cómo esas tecnologías participan dentro del sistema. Saber que existe PostgreSQL es distinto de saber qué base de datos utiliza un módulo, para qué la utiliza, qué otras partes dependen de ella y qué podría verse afectado si cambia.

Imaginemos un sistema de órdenes dividido entre checkout, orders y notifications. Desde arquitectura podemos entender cómo se comunican esos módulos, mientras que desde producto podemos identificar la capacidad de crear una orden. Aun así, el flujo real puede depender también de una base de datos, una cola de eventos, almacenamiento de comprobantes y un proveedor externo de pagos.

Todos esos elementos forman parte de la arquitectura real del sistema, aunque no vivan como código dentro del mismo repositorio. Si no los hacemos visibles, el contexto con el que trabaja el agente sigue siendo parcial.

 

La intención de Project Resources no es convertir Kaddo en una herramienta para administrar infraestructura. El objetivo es mucho más concreto: representar los recursos que son importantes para entender cómo funciona el sistema y conectarlos con el resto del conocimiento del proyecto.

Una base de datos puede vivir en AWS, Azure, GCP o infraestructura propia. Para Kaddo, lo relevante es saber que existe, cuál es su propósito, qué alcance tiene y qué módulos dependen de ella. Lo mismo aplica para una API externa, una cola, un bucket, un servicio compartido o cualquier dependencia que afecte la forma en que una capacidad funciona.

Esto permite empezar a responder preguntas que normalmente quedan separadas: qué hace un módulo, de qué depende, qué recursos utiliza y qué trabajo puede verse afectado cuando uno de esos elementos cambia. En ese punto, el recurso deja de ser un inventario aislado y se convierte en parte del modelo de conocimiento del sistema.

Un recurso por sí solo aporta información limitada. Lo realmente útil aparece cuando podemos relacionarlo con capacidades, módulos y Work Items. Si sabemos que el módulo de pagos depende de un proveedor externo y que un Work Item modifica el flujo de reintentos, esa relación cambia la forma en que deberíamos refinar e implementar el trabajo.

También permite que el grafo del sistema sea más cercano a la realidad. Ya no vemos solamente módulos conectados entre sí, sino módulos que dependen de recursos compartidos y capacidades que atraviesan varias partes de la solución. Eso ayuda a detectar impacto antes de empezar a modificar código.

Para mí, esa es una de las partes más interesantes de Project Resources: convierte dependencias que normalmente están escondidas en información que puede formar parte explícita del contexto del proyecto.

 

Sin este tipo de conocimiento, cada vez que un agente entra a una parte del sistema tiene que volver a descubrir muchas de sus dependencias. Puede encontrar una variable como ORDERS_DATABASE_URL, una llamada a una API o un productor de eventos, pero todavía necesita interpretar qué significa y qué impacto puede tener.

Ese proceso de exploración se repite constantemente y depende demasiado de inferencias. Algunas serán correctas, pero otras pueden llevar a decisiones incompletas porque el agente conoce la implementación local sin entender la relación con el resto del sistema.

Cuando los recursos ya forman parte del conocimiento estructurado, el punto de partida cambia. El agente puede concentrarse en entender cómo el cambio interactúa con esas dependencias, en lugar de tener que descubrir primero que existen.

 

Esta conexión se vuelve especialmente útil cuando refinamos un Work Item. Pensemos en una necesidad aparentemente sencilla, permitir que una orden pueda reintentarse cuando falle el pago. Si miramos únicamente el código del módulo de órdenes, probablemente encontremos una solución local, pero cuando aparecen los recursos relacionados, también aparecen preguntas que antes no eran tan evidentes. Necesitamos saber si el proveedor de pagos soporta idempotencia, si existe una cola entre los componentes, dónde se persiste el estado del intento y si otros módulos consumen los eventos que vamos a modificar.

El Work Item empieza entonces a representar mejor el cambio real. Ya no describe solamente qué código tocar, sino qué parte del sistema estamos alterando y qué dependencias deberíamos considerar antes de construir.

 

Cuando una solución está distribuida entre varios repositorios, entender las dependencias deja de ser opcional. Un repositorio puede conocer muy bien su implementación y aun así desconocer que comparte una base de datos, una cola o un servicio externo con otros módulos del sistema.

Kaddo ya permite mantener una visión global desde un core mientras cada módulo conserva su propio contexto técnico. Project Resources encaja naturalmente en ese modelo porque permite conectar esos módulos mediante las dependencias que realmente comparten.

Esto puede revelar algo importante antes de implementar un Work Item: dos repositorios que parecían independientes en realidad dependen del mismo recurso. Esa información cambia la evaluación del impacto y ayuda a evitar soluciones correctas de manera local, pero incompletas a nivel de sistema.

 

Con Project Resources, el modelo de conocimiento de Kaddo empieza a conectar mejor las distintas partes del proyecto. Business ayuda a entender por qué existe el sistema, Product explica qué capacidades entrega, Tech describe cómo está construido y Delivery organiza cómo queremos evolucionarlo.

Los módulos permiten entender dónde viven las responsabilidades, mientras que los Project Resources hacen visibles las dependencias que conectan esas partes con servicios, datos e infraestructura. Los Work Items utilizan ese contexto para convertir una necesidad en trabajo concreto y el lifecycle permite acompañar el cambio hasta su verificación y aprendizaje.

Para mí, el valor no está en agregar otra categoría de documentación. Está en construir mejores conexiones entre lo que ya sabemos del sistema.

 

También hay una frontera importante. Representar un recurso dentro del conocimiento del proyecto no significa guardar secretos, credenciales o información sensible. Saber que un módulo utiliza una base de datos es conocimiento; tener su contraseña es acceso.

Kaddo necesita suficiente información para que una persona o un agente pueda razonar sobre la dependencia, entender su propósito y evaluar su impacto. Las credenciales y secretos deben seguir viviendo en las herramientas diseñadas específicamente para protegerlos.

Mantener esa separación permite enriquecer el contexto sin convertir el conocimiento del proyecto en un nuevo lugar donde almacenar información sensible.

Esta evolución refleja bastante bien hacia dónde estoy llevando Kaddo. Al principio, el problema principal era cómo mantener contexto útil cerca del código. Después aparecieron capacidades, arquitectura, Work Items, ownership, multirepo, lifecycle y otras piezas que fueron ampliando esa visión.

Project Resources agrega otra conexión importante porque permite representar elementos que siempre estuvieron presentes en el sistema, pero que no necesariamente tenían una relación explícita con el resto del conocimiento.

El objetivo no es tener más archivos ni más documentación. Es poder responder mejor preguntas como qué parte del producto estamos cambiando, dónde vive, de qué depende, qué recursos están involucrados y qué otras partes podrían verse afectadas.

Cuando podemos responder eso de manera consistente, el conocimiento deja de ser un conjunto de documentos y empieza a comportarse como un modelo vivo del sistema. Ahí es donde Project Resources se vuelve realmente interesante, no agrega simplemente más contexto, conecta el contexto que ya existía con las dependencias reales que hacen funcionar el software.

 

Leer documentación: https://kaddo.org/project-resources/