Seu time deveria adotar o OKF?

Você não está avaliando uma ferramenta. Você está decidindo se uma prática vira padrão para pessoas que não a escolheram, o que é uma pergunta mais lenta e de maior risco do que "isso roda na minha máquina". Então aqui está a versão honesta, nos termos que um líder de engenharia de fato pergunta: quanto custa, o que sobrevive, e a única coisa que ele não faz.

O Open Knowledge Format é um formato aberto e neutro publicado pelo Google Cloud em 2026: o conhecimento do seu projeto como um diretório de arquivos Markdown com um pouco de YAML cada, um arquivo por ideia, versionado ao lado do código. O okf é a gem Ruby que o lê, o verifica e o serve. A pergunta abaixo é se a prática vale a padronização, não se a gem instala.

Quanto custa adotar

O medo é uma migração. Não é. O migrate prepende frontmatter e deixa cada corpo idêntico byte a byte, então um time que já tem uma pasta docs/, um export de wiki ou uma pilha de ADRs a transforma num bundle sem reescrever uma palavra. O validador é a lista de trabalho, e a passada acaba quando ele reporta zero. Adoção se mede em horas, não numa reescrita.

O custo contínuo é o real, e vale nomear: um bundle apodrece no momento em que ninguém o mantém em dia, exatamente como todo wiki que o seu time abandonou. A diferença é onde a checagem mora. O okf validate e o okf lint retornam exit codes, então a checagem de frescor fica na CI ao lado dos seus testes, e no Claude Code o plugin a roda após cada edição. O hábito de curadoria deixa de depender da disciplina de alguém e passa a depender de uma checagem que falha em alto e bom som.

O que acontece quando o autor sai

Essa é a pergunta que de fato decide a adoção, porque a pessoa que escreveu o conhecimento é a pessoa que um dia vai sair. Um bundle OKF é Markdown simples no repositório, versionado ao lado do código e revisado nos mesmos pull requests, então quando o autor sai, o raciocínio fica no histórico em vez de ir embora com ele.

Pese isso contra as duas coisas que os times costumam usar. Um wiki não é versionado com o código e ninguém roda um linter contra ele, então o seu apodrecimento é silencioso até queimar alguém. A memória automática de agente degrada em silêncio: como um engenheiro colocou, "muitas das ferramentas de auto-aprendizado que estão ficando populares agora degradam os agentes com o tempo... elas apodrecem muito rápido, e é por isso que a curadoria humana é essencial." Conhecimento deliberado e revisado é o que sobrevive a uma saída. A captura automática é o que envenena devagar.

Por que isto em vez do wiki que você já ignora

Seja honesto sobre o wiki. O seu time tem um, ele está velho, e está velho porque nada faz o desatualizar custar algo. E estar velho é pior que estar ausente: agentes confiam num arquivo escrito mais do que na própria busca no código, então, como um desenvolvedor observou, um doc "só precisa estar um pouco atrás do código" para causar dano de verdade.

Três coisas separam um bundle desse wiki:

• Ele mora no repositório, então se move no mesmo commit que o código que descreve.
• Ele é lido pelos mesmos agentes que o seu time já roda, do mesmo arquivo, então não há uma segunda cópia para manter em dia.
• O seu desatualizar é uma checagem que falha, não um ato de fé.

Ele sobrevive a uma troca de ferramenta?

O medo sob toda decisão de adoção nesse espaço é o aprisionamento: você padroniza no formato de um fornecedor e o fornecedor muda de rumo. O OKF foi desenhado contra exatamente isso. Um bundle não é nada além de Markdown e YAML no seu repositório, e o formato é aberto e neutro, então os seus bundles sobrevivem ao okf-gem e a qualquer agente em que o seu time padronize este ano. Toda ferramenta que qualquer pessoa constrói para o formato torna os bundles que você já tem mais valiosos, não menos. O formato é o ativo; a gem é um leitor dele, e um leitor que você pode trocar.

O número que o seu orçamento e os seus engenheiros leem

Custo de tokens é o único eixo em que quem aprova o gasto e quem escreve o código se importam com o mesmo número. A medição é esta: um agente que recupera de um bundle, um mapa depois uma busca depois um arquivo, responde em menos de um quarto dos bytes de entregar o projeto inteiro, e num projeto real uma pergunta cai a um quarenta avos. Isso não é um benchmark rodado uma vez para um post. É uma linha na suíte de testes da gem que quebra o build se ela algum dia deixar de ser verdade, verde desde a versão 1.5.0. Menos bytes por pergunta é menos gasto por pergunta, e é o mesmo número que os seus engenheiros leem como menos contexto por pergunta.

A única coisa que ele não faz

Toda avaliação honesta precisa do limite, e esse leitor já foi alvo de venda antes, então aqui está ele antes de você ter que pedir. O OKF não faz um agente obedecer a uma regra que ele leu. Um agente pode carregar um conceito, citá-lo de volta com precisão, e violá-lo no turno seguinte. Isso não é um problema de conhecimento, e nenhum formato de documento o resolve, este incluído.

O que um contexto mais enxuto e recuperado faz é encher a janela mais devagar, e o seguir-instruções decai conforme a janela enche, então um contexto menor te mantém no lado bom dessa curva por mais tempo. Isso é um fator que contribui, dito no tamanho exato e nada maior. Se uma ferramenta dessa categoria te diz que o arquivo dela faz o modelo se comportar, essa é a alegação para desconfiar, e a razão para confiar no resto desta.

Então, você deveria?

Adote se o seu time carrega o tipo de conhecimento que um arquivo de regras trata mal: não as convenções, mas o porquê por trás das decisões, o que foi rejeitado e o tradeoff que caiu onde caiu. Adote se você vai colocar as checagens na CI, porque um bundle que ninguém guarda apodrece como qualquer outro doc. Não adote se a sua documentação é puramente convenções que um CLAUDE.md já cobre, ou se você já sabe que não vai mantê-la, porque aí você está trocando um artefato velho por outro com mais passos.

Se você adotar, o raciocínio que o seu time pagou para desenvolver deixa de ir embora com quem o desenvolveu. Aponte um bundle para o seu repositório, e a próxima contratação começa de onde a última aprendeu.