Piensa en cómo arranca de verdad alguien en un codebase. No la wiki que le dijeron que leyera. El mecanismo real: le pregunta al que tiene al lado. “¿Dónde pasa la auth?” “¿Por qué está partido en dos este servicio?” “¿Puedo tocar esto o va a explotar?” Las respuestas salen de la memoria de alguien, y la persona nueva va copiando esa memoria a su propia cabeza. Seis semanas después ya trabaja sin preguntar, y el bucle se repite con el siguiente fichaje.
Ese mecanismo tiene un nombre que la gente rara vez dice en voz alta cuando lo elogia: onboarding contra el conocimiento tribal. El mapa del sistema vive en unas pocas cabezas senior, y volverse productivo es transferirlo, pregunta a pregunta, de sus cabezas a la tuya.
Funciona, justo hasta que deja de funcionar. La persona está ocupada. La persona se fue, y se llevó el mapa. La persona lo recordó mal, y ahora los dos creéis algo falso. Y hay un tipo nuevo de fichaje en el equipo que no puede usar este mecanismo en absoluto: el agente.
El agente es el fichaje más nuevo, y no puede preguntar
En cada sesión, un agente de código llega a tu codebase como un ingeniero de primer día sin memoria de ayer. No sabe dónde pasa la auth ni por qué está partido el servicio. A diferencia del humano de primer día, no puede girarse y preguntar. No tiene a nadie de quien absorber el mapa tribal. Así que hace lo único disponible: hace grep, lee unos ficheros, e infiere.
Esa inferencia es el origen de la mayoría de los problemas que la gente le echa al modelo. El agente rompe un llamador que nunca vio, se salta una convención que nadie escribió, reimplementa algo que ya existía un directorio más allá. No son fallos de razonamiento. Son fallos de onboarding. Al agente lo soltaron en un sistema cuyo mapa vive en cabezas que no puede leer, y le pidieron rendir como si hubiera arrancado.
Esto lo sientes más cuando corres varios agentes a la vez. Cada uno es un fichaje nuevo, en cada sesión, sin mapa compartido entre ellos. El conocimiento tribal aquí ni siquiera tiene un cuerpo donde vivir. No hay un agente senior que se acuerde. Si el conocimiento no está escrito en algo que todos puedan consultar, no existe para ellos, y cada uno redescubrirá el codebase mal, en paralelo.
El conocimiento tribal también falla con las personas, solo que más despacio
Es tentador tratar esto como un problema de agentes con un apaño humano. No lo es. El conocimiento tribal siempre fue un punto único de fallo. Los agentes solo hacen que el fallo sea rápido y evidente en vez de lento y negable.
Cuando la única copia de “por qué está construido así” vive en la cabeza de un ingeniero, ese ingeniero es un cuello de botella y un riesgo. Cada arranque grava su tiempo. Cada marcha es una lobotomía parcial del equipo. El bus factor es el chiste que hace la gente porque la alternativa es admitir cuánto del sistema nadie escribió de verdad. La razón de que nunca pareciera urgente es que el onboarding humano es lo bastante lento como para taparlo. Pierdes el mapa poco a poco, fichaje a fichaje, y le echas la culpa del tiempo de arranque a la complejidad en vez de al hecho de que el mapa nunca se externalizó.
Así que el objetivo no es “haz que los agentes onboardeen como humanos”. Los humanos también onboardean mal. El objetivo es darles a ambos algo mejor contra lo que onboardear.
Onboardea contra el grafo
La alternativa a un mapa atrapado en cabezas es un mapa que el sistema mantiene fuera de las cabezas: un grafo de conocimiento del código construido desde el código real. Las relaciones que un senior recitaría de memoria, esto llama a aquello, esto depende de aquello, esto existe por aquella decisión, se leen del código y se hacen consultables.
Ahora el onboarding cambia de forma para los dos tipos de fichaje.
El ingeniero nuevo deja de enrutar cada pregunta por un senior ocupado. “Qué llama a esto” y “qué se rompe si lo cambio” los responde el grafo, cuando quiera, bien, a las 2 de la mañana, sin interrumpir a nadie. El tiempo del senior se va a las preguntas que de verdad necesitan criterio en vez de a las cien que solo necesitaban el mapa. El humano sigue aprendiendo, más rápido, y contra algo que no recuerda mal.
El agente nuevo consigue, por primera vez, algo contra lo que onboardear. Antes de cambiar el middleware de auth, consulta al grafo qué depende de él, la misma consulta que el humano le haría al senior, y obtiene la respuesta real en vez de un grep-y-adivina. El mapa que siempre le faltó ahora existe en una forma que puede leer. Cada sesión, cada agente, el mismo mapa verdadero.
Esa es la línea que merece la pena guardar: onboarding contra el grafo, no contra el conocimiento tribal. Es una frase que resulta que resuelve el impuesto del onboarding humano y el problema de fiabilidad de los agentes a la vez, porque siempre fueron el mismo problema con distinta ropa.
Sobre qué te puede onboardear el grafo, y sobre qué no
Sé claro con el límite, porque sobrevenderlo es como pierdes la confianza de la gente. El grafo es excelente en la mitad estructural del onboarding: qué existe, qué llama a qué, qué depende de qué, dónde están las fronteras, qué se rompe si tocas esto. Esa mitad es enorme, es la mayoría de las preguntas que de verdad hace una persona nueva en la primera semana, y es la mitad que antes quemaba la tarde de un senior.
lo responde el grafo
- qué existe
- qué llama a qué
- qué se rompe al cambiar
- dónde están las fronteras
solo lo tiene el humano
- por qué esta arquitectura
- la historia política
- decisiones bajo deadline
El grafo es más flojo en el porqué, al menos la parte que nunca llegó a ningún artefacto. Por qué los fundadores eligieron esta arquitectura en vez de la obvia, cuál fue la razón política de partir la propiedad de un equipo por una línea rara, qué decisiones se tomaron bajo un deadline que todos sabían que estaba mal. Parte de eso se puede capturar, si las razones detrás de las decisiones se registran en el momento en que se toman y se enlazan al código que gobiernan, que es justo lo que convierte una estructura pelada en algo que puede responder al “por qué”. Pero parte es genuinamente tribal en el sentido humano, lo que la gente aprendió por estar en la sala, y ningún grafo se inventa lo que nunca se escribió.
Así que el objetivo no es echar al senior. Es dejar de gastar al senior en las cien preguntas estructurales que el grafo responde mejor de todos modos, y reservar su atención escasa para el criterio y la historia sin registrar que solo lleva un humano. El ingeniero nuevo onboardea contra el grafo para el mapa y contra el senior para la sabiduría, y el agente onboardea contra el grafo para todo lo que se le permite, que es la mayor parte de lo que necesita para dejar de romper cosas.
El grafo tiene que ser verdad, o solo has movido la tribu
Un aviso, porque es la forma en que esto sale mal. Un grafo que alguien mantiene a mano es conocimiento tribal con pasos extra. Se desfasa, y entonces le miente al fichaje nuevo y al agente nuevo con la autoridad añadida de parecer oficial. El mapa de onboarding solo es de fiar si se deriva del sistema y se mantiene al día según el sistema se mueve, que es el argumento entero de la documentación que se mantiene sola. Si mantener el mapa verdadero depende de que alguien se acuerde de actualizarlo, no has escapado del conocimiento tribal. Lo has escrito y lo has dejado pudrirse.
Dónde encaja PaellaDoc
Por esto PaellaDoc construye el grafo desde tu repo y lo mantiene aguas abajo del código. Los agentes nuevos lo consultan antes de actuar, así que dejan de onboardear por inferencia. Y el mismo mapa está disponible para los humanos, así que el arranque deja de depender de pillar a un senior entre reuniones. El conocimiento que antes vivía en unas pocas cabezas, y se iba cuando ellas se iban, vive en algo contra lo que todo el equipo, personas y agentes, puede onboardear.
¿Quién de tu equipo es la única cabeza donde vive el mapa de tu codebase, y qué pasa la semana que está de vacaciones? Cuéntame en el foro.
Preguntas frecuentes
¿Por qué los agentes rompen código que nunca han visto?
Porque en cada sesión llegan como un ingeniero de primer día sin memoria y, a diferencia de un humano, sin nadie a quien preguntar. Así que hacen grep, leen unos ficheros e infieren. La mayoría de lo que la gente le echa al modelo es un fallo de onboarding: al agente lo soltaron en un sistema cuyo mapa vive en cabezas que no puede leer.
¿Qué significa hacer onboarding contra el grafo?
En vez de transferir el mapa del sistema desde cabezas senior pregunta a pregunta, tanto los ingenieros nuevos como los agentes nuevos consultan un grafo de conocimiento del código construido desde el código real. «Qué llama a esto» y «qué se rompe si lo cambio» se responden cuando quieras, bien, sin interrumpir a nadie, desde un mapa que no recuerda mal.
¿Puede un grafo de conocimiento sustituir a un senior en el onboarding?
No. Cubre la mitad estructural del onboarding, que es casi toda la primera semana: qué existe, qué llama a qué, qué se rompe si tocas esto. Es más flojo en el porqué que nunca llegó a un artefacto, la historia política y las decisiones bajo deadline. Reserva la atención escasa del senior para eso, no para las cien preguntas estructurales.
¿Cómo se hace onboarding de agentes de IA en un codebase grande?
Dales algo contra lo que onboardear que no sea conocimiento tribal. Construye el grafo desde el repo, mantenlo aguas abajo del código para que siga siendo verdad, y haz que los agentes lo consulten antes de actuar. Un mapa mantenido a mano es conocimiento tribal con pasos extra; se desfasa y miente con autoridad de aspecto oficial.