El conocimiento tribal es un punto único de fallo

Todo equipo tiene una. La persona a la que le escribes por Slack cuando algo en el módulo de pagos pinta mal, porque es la única que recuerda por qué se construyó así y qué parte no debes tocar jamás. Funciona. Funciona hasta el día en que está de vacaciones durante un incidente, o acepta otro trabajo, y descubres que el módulo era portante y que su documentación era un ser humano.

A esto lo llamamos conocimiento tribal y lo tratamos como un activo blando, la señal de un equipo con oficio. También es un riesgo que valoramos en cero exacto hasta el día en que detona. El conocimiento tribal es un punto único de fallo con un nombre simpático.

El conocimiento tribal es el “porqué” sin copia externa

El código ya te dice qué hace. Lo puedes leer. Lo que el código no te puede decir es por qué hace eso en vez de la alternativa obvia, por qué existe esta rama fea, por qué se separó este servicio, por qué nadie ha borrado eso que parece muerto.

Ese “porqué” es el conocimiento tribal. Es real, es portante, y existe en exactamente un sitio: una cabeza. No en el repo, no en un doc, no en un ticket. Quien lo tiene normalmente ni lo vive como conocimiento. Para esa persona es obvio, así que nunca lo escribió, porque lo obvio no se documenta. Y por eso mismo es peligroso. El contexto más crítico de tu sistema es el que nadie pensó que valía la pena registrar.

El fallo no es que la persona se vaya. Es que falta la redundancia.

La ingeniería de fiabilidad tiene una regla que ya aplicas a la infraestructura. Si al caer un nodo se cae el sistema entero, ese nodo es un punto único de fallo y le añades redundancia. Nadie corre producción sobre una sola base de datos sin réplica y se queda tan tranquilo.

Con el conocimiento lo hacemos constantemente. Una persona entiende el flujo de auth. Una persona sabe por qué la migración no se puede correr un lunes. Una persona recuerda al cliente que causó esa restricción rara. Cero réplicas. En cuanto ese nodo no está disponible, de vacaciones, distraído, ido, el conocimiento no está y el código se queda diciendo el qué sin el porqué.

El arreglo no es “contrata gente que no se vaya nunca”. Es el mismo arreglo que para la base de datos. Redundancia. El conocimiento tiene que existir en más de un sitio, y al menos uno de esos sitios tiene que ser un sistema, no un segundo humano frágil. Es lo que la investigación sobre rendimiento de equipos no para de mostrar: la documentación interna de calidad es una de las prácticas que mejor predice si un equipo aguanta el cambio, y es justo la práctica que el conocimiento tribal sustituye en silencio.

Ahora los nuevos fichajes son agentes, y nunca aprenden las reglas de la tribu

Esto es lo que cambió, y por qué dejó de ser un problema lento de RRHH para volverse uno operativo este año.

Un junior humano absorbe el conocimiento tribal por ósmosis. Se sienta cerca del senior, escucha el incidente, le dicen “ah, eso no lo despliegues nunca un viernes”, y a los seis meses las reglas no escritas han calado. Es lento, pierde cosas, pero funciona porque la tribu se transmite sola.

Los agentes no se sientan en ningún sitio. Un agente de código hace onboarding desde cero cada sesión. Lee el código, no el pasillo. Nunca estuvo en la sala cuando alguien explicó por qué la lógica de reintentos no es idempotente a propósito. Así que hace lo razonable que el código parece invitar, y pisa de lleno la mina que la tribu entera aprendió a esquivar hace años.

Esto no lo arreglas escribiendo un prompt mejor. El conocimiento no está en el modelo y no está en el repo, así que ninguna cantidad de ventana de contexto ayuda. Un agente reconstruirá con total seguridad el mismo bug que la tribu ya sufrió, porque la cicatriz que enseñó a los humanos nunca se escribió en ningún sitio que el agente pueda leer. La parte del equipo que más rápido crece es estructuralmente ciega a tu contexto más importante.

Externaliza la tribu, no solo la documentes

La respuesta refleja es “escribe más docs”, y falla por la razón de siempre. Docs en prosa escritos una vez, apartados a un lado, se pudren más rápido de lo que se mueve el código y nadie se fía de ellos en un trimestre. Acabas con conocimiento tribal más un cementerio de wikis obsoletas, que es peor.

Lo que sí ayuda es convertir el “porqué” en algo estructurado y pegado a lo que explica. No una página de wiki sobre el módulo de pagos, sino una decisión registrada contra el módulo de pagos: esto es idempotente a propósito, aquí está el incidente que lo forzó, no lo cambies sin leer eso. Con procedencia incluida, para que el siguiente lector sepa si es una restricción probada o la memoria de una persona.

Hecho así, el conocimiento deja de ser tribal. Se vuelve consultable, por un humano en su primer día y por un agente a las 2 de la mañana, desde la misma fuente. Ese es todo el sentido de hacer onboarding contra un grafo de conocimiento en vez de contra el conocimiento tribal: el recién llegado, de carbono o de silicio, aprende del sistema, no de quien esté despierto. Y es la misma apuesta que un cerebro de producto que se mantiene solo, donde el contexto se actualiza según se mueve el código en vez de decaer en un doc que nadie abre.

La factura llega toda de golpe

La razón de que el conocimiento tribal siga sin valorarse es que no cuesta nada casi cualquier día normal. El senior está disponible, la pregunta se contesta en un hilo, el sistema pinta sano. El riesgo es invisible porque está dormido.

Luego vence todo en un momento, normalmente el peor. El incidente entra mientras la única persona que entiende el subsistema que falla está en un avión. La reescritura se atasca porque nadie de los que quedan sabe decir por qué existía la restricción vieja, así que el equipo o mantiene una regla que no entiende o la quita y reintroduce el bug original. La estimación que asumía un cambio de dos días se dispara, porque los dos días solo eran dos días para quien llevaba el mapa en la cabeza.

Nada de esto aparece en una reunión de planificación. Aparece como un pico en un canal de incidentes, y para entonces el momento más barato para haber externalizado el conocimiento, que era cualquier tarde tranquila del año anterior, ya pasó.

Dónde encaja PaellaDoc

PaellaDoc existe en parte porque me cansé de ser el punto único de fallo de mis propios proyectos. Lee un repo y su historial en decisiones y restricciones atadas al código que explican, cada una etiquetada con de dónde viene, y lo mantiene en tu máquina como un registro vivo. El “porqué” del senior deja de ser algo que tienes que pillarle con el humor adecuado para que te lo cuente. Se vuelve algo que tanto tus compañeros como tus agentes pueden consultar directamente, para que la tribu sobreviva a la tribu.

Local-first y gratis, sin nube y sin cuenta, contra el repo que ya tienes.

↓ Descargar PaellaDoc · macOS

¿Qué parte de tu sistema depende de que una sola persona esté disponible? Cuéntame en el foro.

Preguntas frecuentes

¿Qué es el conocimiento tribal en un equipo de software?

El porqué sin documentar que vive en las cabezas: la razón de que un módulo esté estructurado raro, la mina que nadie toca, la restricción que es obvia para quien la construyó e invisible para el resto. Es conocimiento real sin representación externa, así que desaparece cuando desaparece la persona.

¿Por qué el conocimiento tribal es un punto único de fallo?

Porque todo el sistema depende de que una cabeza esté disponible. Cuando esa persona está de vacaciones, se va o simplemente lo olvida, el conocimiento desaparece y el código se queda diciendo qué hace pero no por qué. No hay redundancia ni backup, que es la definición exacta de un punto único de fallo.

¿Por qué los agentes de IA empeoran el conocimiento tribal?

Porque hacen onboarding desde cero cada sesión y no pueden absorber contexto de pasillo. Un junior humano va pillando las reglas no escritas a lo largo de meses. Un agente nunca. Ve el código, no el porqué detrás, así que cualquier conocimiento que solo vive en cabezas es permanentemente invisible para la parte del equipo que más crece.