Should your team adopt OKF?

You are not really evaluating a tool. You are deciding whether a practice becomes standard for people who did not choose it, which is a slower and higher-stakes question than "does this run on my machine". So here is the honest version, in the terms an engineering lead actually asks: what it costs, what it survives, and the one thing it does not do.

The Open Knowledge Format is an open, vendor-neutral format published by Google Cloud in 2026: your project's knowledge as a directory of Markdown files with a little YAML each, one file per idea, versioned next to the code. okf is the Ruby gem that reads, checks, and serves it. The question below is whether the practice is worth standardizing, not whether the gem installs.

What it costs to adopt

The fear is a migration. It is not one. migrate prepends frontmatter and leaves every body byte-identical, so a team that already has a docs/ folder, a wiki export, or a pile of ADRs turns it into a bundle without rewriting a word. The validator is the worklist, and the pass is done when it reports zero. Adoption is measured in hours, not in a rewrite.

The ongoing cost is the real one, and it is worth naming: a bundle rots the moment nobody keeps it current, exactly like every wiki your team has abandoned. The difference is where the check lives. okf validate and okf lint return exit codes, so the freshness gate sits in CI next to your tests, and in Claude Code the plugin runs it after every edit. The curation habit stops depending on anyone's discipline and starts depending on a check that fails loudly.

What happens when the author leaves

This is the question that actually decides adoption, because the person who wrote the knowledge is the person who will eventually leave. An OKF bundle is plain Markdown in the repo, versioned next to the code and reviewed in the same pull requests, so when the author leaves, the reasoning stays in the history rather than walking out with them.

Weigh that against the two things teams usually reach for. A wiki is not versioned with the code and nobody reruns a linter against it, so its drift is silent until it burns someone. Agent auto-memory quietly degrades: as one engineer put it, "a lot of the self-learning tools that are becoming popular now degrade agents over time... they rot very quickly, which is why human curation is essential." Deliberate, reviewed knowledge is the thing that survives a departure. Automatic capture is the thing that poisons slowly.

Why this over the wiki you already ignore

Be honest about the wiki. Your team has one, it is stale, and it is stale because nothing makes staleness cost anything. And staleness is worse than absence: agents trust a written file more than their own search of the code, so, as one developer noted, a doc "just has to be slightly behind the code" to do real damage.

Three things separate a bundle from that wiki:

• It lives in the repo, so it moves in the same commit as the code it describes.
• It is read by the same agents your team already runs, from the same file, so there is no second copy to keep in sync.
• Its drift is a failing check, not an act of faith.

Does it survive a tool change?

The fear under every adoption decision in this space is lock-in: you standardize on one vendor's format and the vendor pivots. OKF is designed against exactly that. A bundle is nothing but Markdown and YAML in your repo, and the format is open and vendor-neutral, so your bundles outlive okf-gem and whatever agent your team standardizes on this year. Every tool anyone builds for the format makes the bundles you already have more valuable, not less. The format is the asset; the gem is one reader of it, and a reader you can replace.

The number your budget and your engineers both read

Token cost is the one axis where the person approving the spend and the person writing the code care about the same figure. The measurement is this: an agent that retrieves from a bundle, a map then a search then one file, answers in under a quarter of the bytes of handing the whole project over, and on a real project a question lands at a fortieth. That is not a benchmark run once for a blog post. It is a line in the gem's test suite that fails the build if it ever stops being true, green since version 1.5.0. Lower bytes per question is lower spend per question, and it is the same number your engineers read as lower context per question.

The one thing it does not do

Every honest evaluation needs the boundary, and this reader has been sold to before, so here it is before you have to ask. OKF does not make an agent obey a rule it has read. An agent can load a concept, quote it back to you accurately, and violate it on the next turn. That is not a knowledge problem, and no document format fixes it, this one included.

What a leaner, retrieved context does is fill the window more slowly, and instruction-following decays as the window fills, so a smaller context keeps you on the good end of that curve for longer. That is a contributing factor, stated at exactly its size and nothing larger. If a tool in this category tells you its file makes the model behave, that is the claim to distrust, and the reason to trust the rest of this one.

So, should you?

Adopt it if your team carries the kind of knowledge a rules file handles badly: not the conventions, but the why behind decisions, what was rejected and the tradeoff that landed where it did. Adopt it if you will put the checks in CI, because a bundle nobody gates rots like any other doc. Do not adopt it if your documentation is purely conventions a CLAUDE.md already covers, or if you already know you will not maintain it, because then you are trading one stale artifact for another with more steps.

If you do adopt it, the reasoning your team paid to develop stops leaving with whoever developed it. Point a bundle at your repo, and the next hire starts from what the last one learned.