Por que criei o okf-gem

Me perguntam por que eu construí um toolkit inteiro em volta de um formato de Markdown. A razão é simples: padrões. Padrões são o que permite escala, para um time, para uma base de código e agora para agentes.

De dirigir agentes a dar limites a eles

Trabalho com agentes de código há tempo suficiente para ver meu próprio workflow mudar de forma. No passado, usei frameworks como o Superpowers para criar specs e artefatos que direcionavam o agente, e que de quebra me davam documentação do progresso do projeto. Funcionava. Mas o centro de gravidade estava no lugar errado: eu escrevia cada vez mais instruções para conseguir o comportamento que queria.

Hoje a minha preocupação é outra. Quero um bom harness, apenas o suficiente de instruções, e um conteúdo de suporte bem documentado que defina os limites. Constraints escritas são o que dá liberdade de verdade a um agente: ele pode trabalhar à vontade dentro do que foi estabelecido, em vez de chutar o que eu quis dizer. Nesse arranjo, as instruções encurtam e o conhecimento vira a parte que sustenta o peso.

Estrutura é o problema que o OKF resolve de fato

E aí vem o problema: organizar conhecimento de forma eficiente, e que continue organizada, não é trivial. Todo time inventa uma convenção de pastas, e toda convenção vira gaveta de bagunça com o tempo.

É esse o problema que a especificação do OKF resolve. Ela responde a pergunta "como eu estruturo isso?" uma única vez, com pastas, frontmatter, links, um índice e um log, e essa resposta cria liberdade do outro lado: eu posso documentar qualquer informação que seja importante, técnica ou não, sem redesenhar a estrutura a cada vez. O formato decide; eu escrevo.

Tooling e processo eram a outra metade

Estrutura sem ferramenta e sem processo também apodrece. Eu queria uma skill que usasse ferramental para consumir bundles com eficiência de tokens, e uma forma interativa de consultar e navegar por tudo isso. Essa busca me levou ao okf-skills do Marco Boffo, um toolkit de OKF em Python. Encontrar aquilo foi bacana, e eu precisava de mais recursos do que ele oferecia.

Então resolvi criar o okf-gem: um pacote completo, replicável em qualquer projeto, que estabelece um padrão e um processo de como os bundles são mantidos (a skill e o plugin de Claude Code) mais todo o tooling para agentes e humanos (a CLI e o grafo ao vivo).

Objetos Ruby, MCPs e um grafo que você monta onde quiser

Desde janeiro venho criando tooling de AI para organizar e consumir diferentes fontes de dados e dar contexto a agentes. Trabalhar contra um formato especificado deixou uma coisa óbvia: representar bundles e conceitos como objetos Ruby é extremamente versátil e poderoso. Os mesmos objetos podem sustentar um servidor MCP, alimentar a implementação de um agente ou rodar num script qualquer.

Eu também queria o grafo como um app Rack, não só como um comando. Ele serve a minha documentação local hoje, e o mesmo app monta dentro de uma aplicação Rails, onde eu posso colocar a minha própria autenticação na frente.

Local, privado e portável

Dada essa necessidade de processo, padronização e facilidade com agentes, o toolkit inteiro roda 100% local, com total privacidade. Sem conta, sem telemetria, sem upload. A base de conhecimento é o artefato mais sensível que um time possui, e ela não deveria precisar sair da máquina para ser útil.

E o padrão corta de mais um jeito, que é a parte que eu mais gosto: na medida em que o OKF se popularizar, o meu tooling consegue interagir com qualquer bundle por aí, porque o formato é portável. Ferramenta construída sobre um padrão ganha valor com cada bundle que qualquer pessoa criar.

Resolvendo o meu próprio problema primeiro

Tenho procurado empreender, e isso significa lidar com diversas coisas além do código. Ter uma forma padronizada de organizar conhecimento, para mim e para as pessoas do meu time, não é um luxo; é o que mantém o resto administrável. E como aprendi há mais de uma década com o Getting Real da 37signals: ao resolver um problema para você mesmo, é provável que esteja resolvendo para várias outras pessoas.

Essa é a aposta. É Apache-2.0; experimente num repositório real e me diga onde falha.