Tus herramientas de IA son tan buenas como lo sean tus documentos

Todos los equipos de ingeniería utilizan ahora herramientas de IA de alguna forma: asistentes de código que autocompletan, agentes que pueden buscar y modificar bases de código, herramientas internas que responden a preguntas sobre sistemas y procesos. La promesa es que estas herramientas aceleran la ingeniería al proporcionar acceso instantáneo al conocimiento relevante.

La realidad, para la mayoría de los equipos, es que las herramientas son útiles para tareas de codificación genéricas y sorprendentemente débiles en cualquier cosa específica de los propios sistemas del equipo. El asistente de código puede escribir una función en Python pero no conoce las convenciones del equipo. El agente puede buscar en la base de código pero no puede explicar por qué el servicio de pagos está estructurado de la forma en que lo está. El chatbot interno alucina con sistemas específicos de la empresa porque el conocimiento que necesita está en la cabeza de las personas y en los hilos de Slack más que en la documentación de búsqueda.

Esto no es una limitación de los modelos de IA. Es una limitación del contexto al que tienen acceso.

El problema del contexto

Las herramientas de IA razonan a partir del contexto. Un asistente de código que puede ver el archivo actual y sus importaciones produce sugerencias de autocompletado razonables. Un asistente de código que también puede ver los documentos de arquitectura del proyecto, las convenciones de codificación y el historial de decisiones produce resultados drásticamente mejores, porque comprende los patrones que el equipo ha elegido y el porqué.

Lo mismo se aplica a cada herramienta de IA en el flujo de trabajo de ingeniería. Un agente interno al que se le pregunta "¿cómo maneja el sistema de facturación los reembolsos?" solo puede producir una respuesta útil si esta existe en algún lugar en el que el agente pueda buscar. Si la respuesta está en un hilo de Slack de hace ocho meses, en la grabación de una reunión que nunca se transcribió o en la memoria de un ingeniero senior, el agente no tiene nada con qué trabajar y admitirá su ignorancia o, lo que es peor, inventará una respuesta plausible que es incorrecta.

La calidad del resultado de una herramienta de IA está limitada por la calidad del contexto documentado disponible para la herramienta. Los equipos con documentación completa y actualizada obtienen significativamente más valor de su inversión en IA que los equipos que no la tienen.

La documentación como infraestructura de IA

Esto replantea la cuestión de la documentación de una manera que a los líderes de ingeniería les suele resultar más convincente que los argumentos tradicionales.

La documentación ya no es solo para humanos. Es el terreno de entrenamiento para cada herramienta de IA en su pila tecnológica. Los documentos de auto-escritura que capturan las decisiones de arquitectura, el comportamiento del sistema, el historial de incidentes y las convenciones del equipo crean una base de conocimiento que tanto los humanos como los agentes de IA pueden consultar.

Cuando su wiki de ingeniería se escribe sola a partir de la actividad de GitHub, las conversaciones de Slack y las transcripciones de reuniones, la documentación resultante cumple una doble función: es el recurso de incorporación para las nuevas contrataciones y la capa de contexto para las herramientas de IA. Los mismos documentos que ayudan a un nuevo ingeniero a comprender el servicio de pagos también ayudan al agente de IA a responder preguntas al respecto de manera precisa.

A través de MCP (Model Context Protocol), el conocimiento de ingeniería documentado se vuelve accesible para cualquier agente de IA sin necesidad de una integración personalizada. La documentación sirve como una capa de contexto compartida de la que cualquier herramienta compatible puede leer, lo que significa que su inversión en documentación multiplica el valor de cada herramienta de IA en su flujo de trabajo.

El ciclo de retroalimentación

Existe un ciclo virtuoso que vale la pena detallar. Una mejor documentación hace que las herramientas de IA sean más útiles. Herramientas de IA más útiles hacen que la ingeniería sea más rápida. Una ingeniería más rápida genera más actividad que el sistema de documentos de auto-escritura captura. Más actividad capturada hace que la documentación sea más rica. Una documentación más rica hace que las herramientas de IA sean aún más útiles.

Los equipos que entren temprano en este ciclo tendrán una ventaja acumulativa: sus herramientas de IA mejoran a medida que mejora su documentación, y su documentación mejora automáticamente a medida que su actividad de ingeniería genera más contexto documentado. Los equipos que no documentan se quedan estancados con herramientas de IA que son genéricamente capaces pero específicamente inútiles para su base de código.

Preguntas frecuentes

¿Qué herramientas de IA se benefician más de la documentación? Los agentes internos que responden a preguntas sobre sistemas específicos de la empresa experimentan la mayor mejora, porque su valor depende enteramente de disponer de un contexto específico de la empresa. Los asistentes de código experimentan una mejora significativa en las sugerencias con conocimiento de arquitectura y en el cumplimiento de convenciones. Los agentes de codificación que modifican código se benefician al comprender el razonamiento que hay detrás de las estructuras existentes.

¿Cómo funciona esto con MCP? MCP es un protocolo abierto que permite a los agentes de IA leer de su base de conocimientos bajo sus propios términos. Su conocimiento de ingeniería documentado se convierte en la capa de contexto para cualquier herramienta compatible con MCP, sin que el conocimiento sea absorbido por los datos de entrenamiento de la herramienta. La documentación sigue siendo suya; la IA lee de ella.

Ya tenemos una base de conocimientos. ¿Por qué no funciona para nuestras herramientas de IA? La mayoría de las bases de conocimientos están desactualizadas, incompletas o estructuradas de forma que dificultan la recuperación. Las herramientas de IA necesitan documentación actual, completa y de búsqueda semántica. Los documentos de auto-escritura que se actualizan automáticamente y se pueden buscar por significado abordan estos tres problemas.

Lectura relacionada: Por qué es importante la documentación de ingeniería, Explicación de los documentos de auto-escritura, La memoria es el foso. Páginas relacionadas: Documentos de auto-escritura, MCP, Para equipos de ingeniería.