O que é o Open Knowledge Format?

Todo time tem uma segunda base de código. Não a que está em src/, mas a que vive na cabeça das pessoas: por que o serviço de billing existe, o que "usuário ativo" conta de verdade, qual decisão de schema parece errada mas foi tomada de propósito.

E não é só um arquivo de engenharia: ela guarda o que a empresa sabe sobre os concorrentes, o guia de sobrevivência que carrega o plantão por um incidente, o catálogo de features que vive na cabeça do PM. Essa segunda base de código decide a velocidade com que uma pessoa nova entrega, o quão bem um agente de IA trabalha no seu repositório e quantas vezes a mesma pergunta é respondida no chat. Na maioria dos times, ela não tem casa.

O Open Knowledge Format (OKF) é uma especificação para dar uma casa a ela.

O formato do problema

Hoje o conhecimento de um projeto vive em quatro lugares ao mesmo tempo. Uma wiki que estava correta oito meses atrás. Um CLAUDE.md ou AGENTS.md que mistura instruções permanentes com pedaços de contexto. A memória privada de um agente, que nenhum colega consegue ler ou revisar. E as pessoas, que saem de férias, trocam de time e vão embora.

O resultado é o mesmo em todo lugar: um agente re-deriva a sua arquitetura do zero a cada sessão, e alguém pergunta no chat o que uma métrica significa pela terceira vez no trimestre. O conhecimento existe. Ele só não está em nenhum lugar onde uma ferramenta ou um colega consiga encontrá-lo com confiança.

O que o OKF é, de fato

OKF é um formato aberto e neutro, publicado pelo Google Cloud em 2026. A ideia inteira cabe em uma frase: uma base de conhecimento é um diretório de arquivos Markdown com frontmatter YAML, e cada arquivo é um conceito.

Esse diretório se chama bundle. Não tem banco de dados, não tem editor proprietário, não tem etapa de exportação. Um bundle mora no seu repositório como qualquer outra pasta, o que significa que ele é versionado junto do código que descreve, revisado em pull requests e diffável quando muda.

Aqui está um bundle inteiro, sem nada escondido:

docs/
├── index.md                  # o mapa: o que vive aqui, uma linha por entrada
├── log.md                    # histórico datado do que mudou no conhecimento
├── services/
│   ├── index.md
│   └── billing.md            # um conceito = um arquivo Markdown
├── tables/
│   ├── orders.md
│   └── customers.md
└── decisions/
    └── payment-id-dedup.md

Esse é o truque todo: arquivos Markdown dentro de pastas, mais um conjunto pequeno de regras de estrutura que tornam essas pastas autodescritivas. A própria especificação resume: "se você consegue dar cat num arquivo, consegue ler OKF; se consegue dar git clone num repositório, consegue distribuí-lo". O caminho do arquivo é a identidade dele (tables/orders.md é o conceito tables/orders), as pastas agrupam conceitos do jeito que fizer sentido para o seu domínio, e um bundle viaja como repositório git, zip ou só uma pasta dentro do repositório que você já tem.

Se você já usou Obsidian, ou as convenções de wiki que as pessoas hoje escrevem para LLMs, isso vai parecer familiar de propósito. A diferença é que o OKF é especificado: uma lista curta e escrita de regras em vez de um estilo da casa, e é exatamente isso que permite uma ferramenta validar o bundle e um agente consumir sem chutar.

Um conceito tem esta cara:

---
type: BigQuery Table
title: Orders
description: Uma linha por pedido confirmado, deduplicado por payment id.
tags: [billing, core]
---

Faz join com [customers](/tables/customers.md) nos relatórios de receita.
O incidente de dedup de 2023 é o motivo de a chave ser payment_id, e não order_id.

A única exigência dura é esse bloco de frontmatter com um type não vazio. Todo o resto, título, descrição, tags, timestamp, é recomendado em vez de obrigatório, e um consumidor precisa tolerar o que estiver faltando. A especificação é pequena de propósito: dá para ler inteira de uma sentada.

Pense no frontmatter como a lombada e a contracapa de um livro. Dá para percorrer a estante, ler as lombadas (type, título, uma descrição de uma linha, tags) e decidir quais livros tirar da prateleira, sem abrir nenhum. É isso que torna um bundle barato para uma IA usar: a maioria das perguntas se responde com as lombadas mais dois ou três arquivos abertos, não lendo a biblioteca inteira.

O grafo que você nunca declara

Essa é a parte que eu acho elegante. Conceitos apontam uns para os outros com links Markdown comuns: [customers](/tables/customers.md). Arquivos são nós. Links são arestas. Então um bundle é um grafo de conhecimento, sem uma linha de configuração de grafo. Você nunca declara relacionamentos em um arquivo à parte; o grafo emerge de como o texto já se refere a si mesmo.

Dois arquivos reservados dão estrutura ao bundle quando ele cresce. Um index.md por diretório funciona como mapa, para um leitor (humano ou agente) descer do panorama ao detalhe em vez de carregar tudo de uma vez. A especificação chama isso de divulgação progressiva, e é o que permite um bundle crescer além de uma janela de contexto sem virar inútil para um agente. E um log.md mantém um histórico datado do que mudou no próprio conhecimento.

Comparando com os lugares onde o conhecimento vive hoje

Cada casa existente guarda algo real. Nenhuma delas foi construída para conhecimento de time curado e durável:

A última linha é a interessante. Uma wiki não tem detector para o próprio apodrecimento. Um bundle tem: como o formato é estruturado, uma ferramenta consegue dizer que um conceito está órfão, que três arquivos apontam para uma página que ninguém escreveu ainda, ou que um documento "atual" não é tocado desde que o schema mudou. A deriva vira findings que você pode usar de gate no CI, em vez de uma surpresa durante o onboarding.

Não é só para código

A árvore de pastas lá em cima deve deixar uma coisa óbvia: nada no formato é específico de código, e alguns dos maiores ganhos vivem fora da base de código. Um arquivo de concorrentes em que vendas e produto confiam. Um guia de sobrevivência de incidentes que o plantão encontra de verdade às 3 da manhã. Um catálogo de features que diz ao PM o que existe, por quê e para quem. Notas de onboarding, racional de preço, o checklist de compliance. A empresa inteira se beneficia de conteúdo bem curado, e cada um desses é só um arquivo de conceito numa pasta.

E alcança além das empresas também: os playbooks de um escritório de advocacia, a pesquisa de uma consultoria de SEO, os procedimentos de fechamento de um contador. Se o conhecimento cabe em Markdown, ele cabe num bundle, e qualquer agente que entenda OKF consegue trabalhar com ele.

E isso corta para o outro lado também. Um bundle bem curado é um ativo por si só: expertise, empacotada num formato que qualquer ferramenta consome, portável para qualquer agente que o seu time use ano que vem. Curar um bem dá trabalho de verdade, e é o tipo de trabalho que se acumula.

Onde entra a ferramenta

Um formato sozinho é só uma promessa. Eu mantenho o okf-gem, um kit OKF completo que vem em uma única gem Ruby e roda 100% local. São três ferramentas em um casaco só:

• Uma agent skill que ensina um agente de código (Claude Code, ou qualquer harness que leia skills) a criar, curar e consumir bundles. A skill carrega o julgamento; ela conhece a especificação, então o seu agente se comporta como um especialista em OKF em vez de chutar.
• Uma CLI que faz a mecânica. okf validate responde "este bundle é legal?" exatamente como a especificação define conformidade. okf lint responde a pergunta mais suave, "ele está bem curado?": alcançabilidade, completude, frescor, proveniência. Legal e bem curado são perguntas diferentes, então são comandos diferentes.
• Um servidor de grafo ao vivo. okf server docs/ serve o seu bundle como um grafo de conhecimento interativo no navegador: clique em um conceito, leia o Markdown dele, siga os links. Tem uma demo pública se você quiser clicar em um agora mesmo.

Nada sai da sua máquina. Não existe SaaS por trás, não tem telemetria, não tem conta. Seu conhecimento fica no seu repositório, onde ele deveria estar. Se você usa Claude Code, um plugin instala o pacote inteiro mais um hook que re-checa o bundle depois de cada edição.

Comece pequeno, e mais esperto

Você não precisa fazer o trabalho pesado sozinho. É para isso que o tooling existe: a skill do okf-gem cria e cura bundles com o agente fazendo a escrita enquanto você continua sendo o editor. Dá até para apontá-la para um documento que já existe (/okf produce no seu coding agent, ou pedindo em palavras) e deixar a skill OKF-ificar o texto pronto, em vez de começar do arquivo em branco.

Use a skill para potencializar essa atividade, seja para adaptar a documentação que você já tem, seja para criar conceitos novos a partir do código e das conversas. Comece com um documento ou um punhado de conceitos, rode o okf lint para ver o que o bundle pede em seguida, e deixe o ciclo continuar dali.

O formato é aberto, a especificação viaja com a gem e o conjunto inteiro é arquivo puro. Se o OKF sumir amanhã, você fica com um diretório de Markdown bem organizado nas mãos. Esse é o pior caso. Eu acho que isso diz muito sobre a ideia.