Qué es el Nuevo Formato de Conocimiento Abierto de Google

Apunta un agente de programación a un repositorio real y observa lo que ocurre antes de que escriba una sola línea: lee archivos, busca llamadores con grep, abre un puñado de módulos relacionados y reconstruye — desde cero, en cada tarea — un modelo mental de cómo encaja tu base de código. Ese trabajo no es gratis. Son tokens y, en un repo de cualquier tamaño real, son muchos, gastados en volver a derivar los mismos hechos estructurales que tu equipo ya conoce y podría haber documentado una sola vez.

La mayoría de los equipos tratan esto como un problema de recuperación y recurren a RAG. Ese es el error común contra el que argumenta esta publicación. El nuevo Open Knowledge Format de Google Cloud, lanzado en junio de 2026, se basa en una premisa completamente distinta: parte del conocimiento sobre tu sistema — qué hace un servicio, de qué depende, quién es su responsable — es lo bastante estable como para no tener que re-derivarse en cada consulta. Debería compilarse una sola vez, como el código fuente, y reutilizarse. La especificación en sí es casi nada: un campo obligatorio, Markdown plano, sin SDK. El verdadero problema de ingeniería, el que toda explicación del formato omite, es cómo mantener honesto ese conocimiento compilado mientras un equipo sigue enviando decenas de commits al día. Eso es lo que realmente recorre esta publicación.

Aprenderás:

• Qué estandariza realmente OKF y lo deliberadamente mínima que es la especificación
• Por qué el contexto compilado supera a RAG para la parte estable y curada de una base de código — y dónde RAG sigue ganando
• Cómo un archivo de “concepto” de OKF se mapea a código real en lugar del caso de uso original de Google con tablas de BigQuery
• Cómo construir un pipeline de enriquecimiento activado por git hooks que evite que el grafo se desincronice con tu repo
• Cómo la divulgación progresiva convierte un paquete de conocimiento en un control real del presupuesto de tokens para flujos de trabajo con múltiples agentes
• Las limitaciones reales de una especificación tan nueva y cómo decidir si ya vale la pena adoptarla

Tabla de contenidos

1. Lo básico
2. La arquitectura completa
3. Explicación de las capas principales
4. Recorrido de extremo a extremo
5. Casos especiales
6. Desafíos de escalado y producción
7. Ejemplos de código
8. Errores comunes
9. Mejores prácticas de producción

Lo básico

Qué cubre realmente OKF

Open Knowledge Format es una especificación para representar conocimiento curado como un directorio de archivos Markdown planos con frontmatter YAML, publicada por el equipo de datos de Google Cloud en junio de 2026. Formaliza un patrón que ya había surgido de forma orgánica en todo el ecosistema: la idea del “LLM wiki” ampliamente compartida por Andrej Karpathy, la convención AGENTS.md usada ahora en decenas de miles de proyectos open-source, y desarrolladores conectando bóvedas estilo Obsidian directamente a agentes de programación. OKF no inventa un nuevo sustrato; estandariza el que ya ganó: Markdown, frontmatter y Git.

Un “concepto” es la unidad atómica: un archivo, una pieza de conocimiento, y la ruta del archivo es su identidad, sin un sistema de ID separado que mantener sincronizado. De los pocos campos de frontmatter recomendados, exactamente uno es obligatorio: type. Todo lo demás — título, descripción, un enlace a recurso, etiquetas, una marca de tiempo — es opcional. Ese minimalismo no es un descuido; es toda la filosofía de diseño. Este es un formato de intercambio, no una plataforma, y la especificación es deliberadamente flexible con lo que tolera: tipos no reconocidos, campos opcionales faltantes e incluso enlaces rotos son cosas que un consumidor conforme debe aceptar en lugar de rechazar.

Por qué este es un problema de alto valor para resolver

• Los costos de tokens se acumulan con cada agente, cada tarea y cada compañero de equipo que use uno. Volver a derivar los mismos hechos estructurales sobre una base de código no es un costo único: es un impuesto recurrente en cada interacción.
• Las alternativas tienen fallas para este tipo específico de conocimiento. Un volcado ingenuo de todo el repo no escala más allá de una base de código pequeña, y RAG vuelve a derivar relaciones a partir de documentos en bruto en tiempo de consulta, cada vez, para conocimiento que en realidad no cambia tan seguido.
• El contexto desactualizado no solo es lento: está activamente equivocado. Un agente que actúa sobre un modelo mental obsoleto de las dependencias de un servicio no solo desperdicia tokens; puede hacer cambios que rompan algo que no sabía que estaba conectado.

La arquitectura completa

Commit Pushed
      │
      ▼
Diff-Scoped Scan  (which services/modules actually changed?)
      │
      ▼
Draft / Update Concept Docs  (two-pass enrichment agent)
      │
      ▼
Re-link Cross-References  (update dependency/responsibility links)
      │
      ▼
Lint  (spec-compliance rules)
      │
      ▼
Publish  (commit the bundle, push to CI, or register to a catalog)

El principio rector: compilar una vez el conocimiento estable para que los agentes dejen de volver a derivarlo en cada tarea. OKF en sí no opina sobre cómo ocurre esa compilación ni cómo se mantiene actualizada — esa parte depende por completo de quien lo adopte, y es el verdadero trabajo de ingeniería en el que se centra esta publicación.

Explicación de las capas principales

1. El archivo de concepto

Qué es: Un único archivo Markdown que representa una unidad de conocimiento — un servicio, una API, una tabla, un runbook — con un pequeño bloque de frontmatter YAML arriba y un cuerpo Markdown de forma libre debajo.

Por qué importa: Como la ruta del archivo es la identidad, no hay nada que reconciliar entre un sistema de ID separado y la ubicación real del conocimiento: el propio sistema de archivos es el índice.

---
type: Service
title: billing-service
description: Handles subscription billing, invoicing, and payment webhooks.
resource: https://github.com/yourorg/monorepo/tree/main/services/billing
tags: [billing, payments, python]
timestamp: 2026-08-01T10:00:00Z
---
# Responsibilities
Owns the Invoice and PaymentEvent domain models.

# Dependencies
- Calls customer-service to resolve account state.
- Publishes events consumed by notifications-service.

Consejo de producción: Refleja deliberadamente la estructura del caso de uso original: cambia una URL de consola de BigQuery por una ruta del repo en resource, y cambia una sección de datos # Schema por una estructura orientada al código de # Responsibilities / # Dependencies. La consistencia en la estructura del cuerpo entre archivos de concepto importa más para el consumo por agentes que cualquier campo individual.

2. index.md y divulgación progresiva

Qué es: Un nombre de archivo reservado que actúa como listado de directorio en cualquier nivel del paquete: el punto de entrada que un agente lee antes de tocar cualquier otra cosa.

Por qué importa: Este es un control real del presupuesto de tokens, no un archivo de conveniencia. Un agente orquestador lee index.md, decide qué archivos de concepto necesita realmente una subtarea dada y carga solo esos — nadie mete todo el paquete en contexto para un cambio que toca un solo servicio.

Consejo de producción: Mantén las entradas del índice limitadas a un título y una descripción de una sola línea extraída directamente del frontmatter de cada concepto. Un índice hinchado de detalles anula el propósito de tenerlo.

3. log.md y el historial de cambios

Qué es: Otro nombre de archivo reservado: un registro cronológico, agrupado por fecha, de lo que cambió en lo que el paquete sabe, distinto de git log, que solo registra lo que cambió en el código.

Por qué importa: “Qué cambió en este archivo” y “qué cambió en nuestra comprensión de este sistema” son preguntas distintas. El código de un servicio puede cambiar sin que cambien sus responsabilidades documentadas, y viceversa — un log.md permite que un agente (o una persona) responda directamente a la segunda pregunta en lugar de inferirla a partir del historial de commits.

4. Enlaces cruzados como grafo de dependencias

Qué es: Enlaces Markdown relativos normales entre archivos de concepto, cuyo significado de relación lo aporta el texto circundante en lugar de un esquema formal.

Por qué importa: Estos enlaces convierten un directorio plano en algo más parecido a un grafo de dependencias que a una simple jerarquía de carpetas — billing-service puede apuntar a todo lo que llama y a todo aquello a lo que publica, independientemente de dónde estén realmente esos servicios en el árbol del repo.

Consejo de producción: Como los enlaces son solo Markdown y la especificación exige que los consumidores toleren los rotos, no trates esto como un sustituto del análisis estático real de tu grafo de llamadas. Es un resumen curado, legible por humanos y agentes, del grafo de dependencias, no uno verificado formalmente.

5. El pipeline del agente de enriquecimiento

Qué es: La parte que OKF deja deliberadamente sin especificar: el proceso que realmente redacta y mantiene los archivos de concepto a medida que cambia el código. El patrón de referencia son dos pasadas: una que recorre los servicios modificados y redacta o actualiza un archivo de concepto a partir de sus interfaces y estructura, y una segunda que añade citas de vuelta a documentación existente, runbooks y PRs.

Por qué importa: Este es el verdadero trabajo de ingeniería detrás de adoptar OKF. El formato en sí es casi gratis de prototipar — un campo obligatorio, sin SDK. Mantener preciso un paquete de mil archivos mientras un equipo envía decenas de commits al día es el verdadero problema de sistemas, y te corresponde totalmente resolverlo a ti, no a la especificación.

Consejo de producción: Limita cada pasada de enriquecimiento al diff de git, no a todo el repositorio. Un reescaneo completo del repo en cada commit es lo que hace que esto sea caro; un escaneo limitado al diff de solo los servicios modificados es lo que lo hace lo bastante barato como para ejecutarlo en cada push.

6. Herramientas: init, hooks, search y lint

Qué es: Un CLI open-source (independiente de Google, escrito en Go) que genera la estructura de un paquete, instala un git hook para mantenerlo actualizado automáticamente, soporta búsqueda por palabras clave sobre conceptos y aplica un conjunto de reglas integradas de cumplimiento de la especificación.

Por qué importa: No tienes que construir la capa de automatización desde cero: la forma de “escanear en cada commit, refrescar lo que cambió, aplicar lint antes de confiar en ello” ya está validada por herramientas existentes, incluso en esta etapa tan temprana del ecosistema.

Consejo de producción: Ejecuta lint como una barrera estricta antes de que tu CI confíe lo suficiente en un paquete como para permitir que los agentes actúen sobre él. Dado lo flexible que es la especificación respecto a campos faltantes y enlaces rotos, lint es lo único que separa “técnicamente conforme” de “realmente útil”.

Recorrido de extremo a extremo

Sigue un commit a través de todo el pipeline:

1. Un desarrollador hace push de un cambio en billing-service, añadiendo una nueva dependencia de un servicio de verificación de fraude.
2. Se dispara el git hook y activa un escaneo limitado al diff: solo se vuelven a examinar billing-service y cualquier cosa tocada directamente por el diff, no todo el repositorio.
3. La primera pasada del agente de enriquecimiento redacta la actualización, leyendo la nueva interfaz del servicio y sus call sites, y reescribe la sección # Dependencies de billing-service.md para incluir el servicio de verificación de fraude.
4. La segunda pasada añade citas, cruzando el cambio con cualquier runbook o descripción de PR existente que explique por qué se añadió la dependencia, y los enlaza.
5. Las referencias cruzadas se actualizan en ambos lados — billing-service.md ahora enlaza al archivo de concepto de verificación de fraude, y si la sección # Dependents de ese archivo existe, se actualiza para apuntar de vuelta.
6. Se ejecuta lint sobre el paquete actualizado, comprobando la validez del frontmatter y detectando cualquier cosa estructuralmente incorrecta que haya producido la pasada de enriquecimiento.
7. Se publica el paquete — confirmado junto con el cambio de código o enviado por CI a una ubicación servida.
8. Al día siguiente, un agente orquestador recoge una tarea no relacionada que toca el servicio de verificación de fraude. Lee index.md, ve el archivo de concepto, carga solo ese archivo — incluyendo su enlace ya actualizado de vuelta a billing-service — y nunca tiene que reescanear desde cero ninguna de las dos bases de código para entender la relación.

Casos especiales

Dónde termina OKF y empieza RAG. OKF es para la parte estable y curada del conocimiento de una base de código: servicios, límites de propiedad, grafos de dependencias, los runbooks que alguien realmente se tomó el trabajo de escribir. RAG sigue siendo la herramienta correcta para la larga cola: documentos de diseño puntuales, hilos de Slack, tickets antiguos — cualquier cosa demasiado desestructurada o demasiado poco consultada como para justificar curarla en un archivo de concepto. Tratar OKF como un reemplazo de RAG es el marco equivocado; tratarlo como una caché compilada que evita que RAG tenga que volver a derivar hechos estables es el correcto.

Monorepos de múltiples equipos y deriva de tipos. Como type lo define el productor y no existe un registro externo, distintos equipos que contribuyan al mismo paquete tenderán naturalmente a derivar: lo que para un equipo es “API Endpoint” para otro es “Route”. Nada en la especificación lo impide; solo tus propias reglas de lint y convenciones pueden mantener la coherencia.

Métricas gobernadas y cómputos certificados. La especificación incluye un tipo de concepto para lo que llama un “attested computation”: una forma autorizada y verificable de calcular un valor, distinta de simplemente documentar qué significa ese valor. Para equipos con métricas que necesitan una única fuente de verdad sobre cómo se calculan, y no solo qué representan, esto merece un archivo de concepto dedicado en lugar de integrar la lógica de cálculo dentro de una descripción general.

Desafíos de escalado y producción

Los reescaneos completos del repo no escalan; los limitados al diff sí. Todo el modelo de costos de este pipeline depende de limitar las pasadas de enriquecimiento a lo que realmente cambió. Un equipo que reescanea todo en cada commit encontrará el pipeline demasiado caro para seguir ejecutándolo mucho antes de que su repo sea lo bastante grande como para necesitarlo realmente.

La divulgación progresiva debe diseñarse dentro de tu capa de orquestación, no darse por sentada. El beneficio sobre el presupuesto de tokens de index.md solo se materializa si tu agente orquestador está realmente construido para leer primero el índice y cargar archivos de concepto de forma selectiva — añadir OKF a un agente que sigue volcando directorios enteros en contexto te da el costo de mantenimiento sin el ahorro.

La deriva y la gobernanza se vuelven más difíciles, no más fáciles, a escala. Sin un registro de tipos ni semántica de enlaces obligatoria, un paquete mantenido por unas pocas personas se mantiene coherente solo por convención; un paquete tocado por decenas de colaboradores necesita reglas de lint deliberadas y disciplina de revisión para evitar degradarse en un caos inconsistente que sea técnicamente conforme a la especificación y prácticamente poco fiable.

Este es un ecosistema muy temprano. La especificación se publicó en junio de 2026, las herramientas fuera de la implementación de referencia de Google están fragmentadas y todavía no hay estudios de caso de producción de larga duración en bases de código grandes y activamente cambiantes. Presupuesta que la propia especificación seguirá evolucionando, no solo tu paquete.

Ejemplos de código

Generar la estructura de un paquete y conectar el hook de actualización automática:

okf init
okf hook install
okf search -q "billing"
okf lint

Un wrapper mínimo en Python para llamar al CLI desde tu propio pipeline de CI:

import subprocess

def okf_lint(bundle_path: str = ".okf/knowledge") -> bool:
    result = subprocess.run(
        ["okf", "lint", bundle_path],
        capture_output=True, text=True,
    )
    if result.returncode != 0:
        print(result.stdout)
    return result.returncode == 0

Las primitivas de carga y búsqueda que tu orquestador llama antes de despachar un subagente, y la comprobación de lint que tu CI llama antes de confiar en un paquete:

bundle, err := okf.LoadBundle(".okf/knowledge", nil)
results := bundle.Search("billing")
report := lint.LintBundle(concepts, lint.DefaultConfig())

Errores comunes

Error: tratar OKF como un reemplazo de RAG. Intentar meter conocimiento desestructurado y consultado rara vez en archivos de concepto curados destruye toda la premisa del formato. Solución: mantén OKF para conocimiento estable y curado y deja RAG para la larga cola.

Error: reescanear todo el repo en cada commit. Esta es la forma más rápida de hacer que el pipeline sea demasiado caro para seguir ejecutándolo. Solución: limita cada pasada de enriquecimiento al diff de git, no a toda la base de código.

Error: omitir lint porque la especificación es flexible por diseño. Ser conforme a la especificación no es lo mismo que ser fiable: un paquete lleno de enlaces rotos y tipos desviados todavía puede pasar técnicamente. Solución: ejecuta lint como una barrera estricta de CI antes de permitir que los agentes actúen sobre el paquete.

Error: adoptar OKF antes de tener agentes que realmente lo consuman. Toda la propuesta de valor depende de que algo lea el paquete. Solución: si nada en tu flujo de trabajo consume aún contexto estructurado, estás manteniendo una wiki que nadie lee — espera hasta tener flujos de trabajo agentic que realmente la usen.

Error: omitir la pasada de citas. Un agente de enriquecimiento de una sola pasada que solo redacta, sin hacer referencias cruzadas a documentación existente, tiende a producir descripciones plausibles pero no verificadas. Solución: mantén la estructura de dos pasadas — redactar y luego citar — en lugar de confiar en una primera pasada como versión final.

Mejores prácticas de producción

• Limita el enriquecimiento al diff, siempre. Esta es la diferencia entre un pipeline que se ejecuta en cada commit y uno que se desactiva después de la primera semana cara.
• Diseña tu orquestador en torno a la divulgación progresiva desde el principio. El ahorro de tokens es real, pero solo si algo realmente lee index.md antes de cargar archivos de concepto.
• Aplica lint antes de confiar. La flexibilidad de la especificación respecto a campos faltantes y enlaces rotos significa que la gobernanza es completamente tu responsabilidad, no la del formato.
• Mantén OKF y RAG como herramientas complementarias, no como competidoras. Encauza el conocimiento estable y curado por OKF y todo lo demás por RAG.
• Empieza con tu servicio que más cambia, no con todo el repo. Un pipeline mínimo — okf init, un git hook, una pasada de enriquecimiento sobre tu servicio de mayor rotación — basta para medir ahorros reales de tokens antes de comprometerte a un despliegue completo.

Para cerrar

La especificación en sí realmente está cerca de no ser nada: un campo obligatorio, Markdown plano, sin SDK que instalar. Precisamente por eso es adoptable, y precisamente por eso no es la parte interesante. El sistema que realmente vale la pena construir es el pipeline de enriquecimiento que mantiene honesto un grafo de conocimiento mientras tu base de código sigue cambiando por debajo, y ese es un problema de ingeniería que ninguna especificación puede entregarte ya resuelto. Si ya estás ejecutando múltiples agentes contra tu propio repo, vale la pena prototiparlo esta semana: apunta un git hook a tu servicio más activo y mide la diferencia de tokens en tu próxima tarea multiagente antes de decidir si el costo de mantenimiento compensa.

Si probaras esto en tu propia base de código, ¿a qué limitarías la primera pasada de enriquecimiento: a tu servicio que más cambia o al que tiene las dependencias más enmarañadas?