This article is published in English.
Practical notes: Google Just Quietly Released the Missing Piece for AI Agents.
Operable walkthrough of Practical notes: Google Just Quietly Released the Missing Piece for AI Agents.: contracts, checks, and drop-in code slots for teams shipping this pattern.
Use this as an operator-facing rebuild of the ideas in “Google Just Quietly Released the Missing Piece for AI Agents. It’s Called OKF.”: clear stages, ordered code slots, and recovery notes that survive a handoff. The Overview stage works best when treated as a measurable surface. Capture one golden transcript, one failure case, and the rollback note before expanding scope. Prefer small, testable units over sprawling scripts. When a step fails, the failure should point at a single responsibility rather than a tangled pipeline.
The Problem It Solves
For the The Problem It Solves stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Treat this stage as a contract between inputs and validated outputs. Name the artifacts, define success checks, and refuse silent partial completion. Put human approval on edges that spend money or change production data. Compile-time wiring does not equal business completeness.
+-----------------------+--------------------------------------------+
| WHERE IT LIVES | WHAT'S THERE |
+-----------------------+--------------------------------------------+
| Metadata catalogs | Table schemas (but vendor-locked APIs) |
| Wiki / Notion | Runbooks, metric definitions |
| Code comments | Docstrings, inline notes |
| People's heads | Join paths, deprecation warnings |
+-----------------------+--------------------------------------------+
What OKF Actually Is
For the What OKF Actually Is stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Record timings and token or query cost next to functional results. Cost visibility early prevents surprise bills when the path moves from demo to shared environments. Put human approval on edges that spend money or change production data. Compile-time wiring does not equal business completeness.
The Structure: A Directory Is a Knowledge Graph
For the The Structure A Directory stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Keep configuration outside application code. Environment files, secret stores, and feature flags belong in one place operators can audit without reading the whole graph. Put human approval on edges that spend money or change production data. Compile-time wiring does not equal business completeness. For the The Structure A Directory stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Prefer small, testable units over sprawling scripts. When a step fails, the failure should point at a single responsibility rather than a tangled pipeline.
.okf/
+-- index.md <- progressive entry point
+-- log.md <- dated change history, newest first
+-- services/
| +-- index.md
| +-- auth-api.md <- one concept = one file
| +-- payments-service.md
+-- datasets/
| +-- index.md
| +-- orders-db.md
+-- metrics/
| +-- index.md
| +-- weekly-active-users.md
+-- decisions/
+-- index.md
+-- why-we-use-postgres.md
Anatomy of an OKF Concept File
When working through the Anatomy of an OKF stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Treat this stage as a contract between inputs and validated outputs. Name the artifacts, define success checks, and refuse silent partial completion. Checkpoint after expensive steps. Resume should not re-bill the same LLM call when an operator retries a later node.
---
type: Service
title: "Auth API"
description: "Issues and verifies short-lived access tokens."
resource: https://github.com/acme/auth
tags: [auth, platform]
timestamp: 2026-06-14T10:00:00Z
---
## Endpoints| Method | Path | Description |
|--------|----------|---------------------------|
| POST | /token | Exchange creds for a JWT. |
| GET | /verify | Validate a token. |## Why This ExistsSee the decision at [decisions/why-we-separated-auth.md](../decisions/why-we-separated-auth.md).
Joins with [datasets/orders-db.md](../datasets/orders-db.md) for user scoping.
[auth-api.md]
/ \
links links
/ \
[decisions/why-separated-auth.md] [datasets/orders-db.md]
|
links
|
[datasets/customers-db.md]
The Three Design Principles
When working through the The Three Design Principles stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Record timings and token or query cost next to functional results. Cost visibility early prevents surprise bills when the path moves from demo to shared environments. Checkpoint after expensive steps. Resume should not re-bill the same LLM call when an operator retries a later node.
1. Minimally opinionated
When working through the 1 Minimally opinionated stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Keep configuration outside application code. Environment files, secret stores, and feature flags belong in one place operators can audit without reading the whole graph. Checkpoint after expensive steps. Resume should not re-bill the same LLM call when an operator retries a later node. When working through the 1 Minimally opinionated stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Prefer small, testable units over sprawling scripts. When a step fails, the failure should point at a single responsibility rather than a tangled pipeline.
2. Producer and consumer independence
The 2 Producer and consumer stage works best when treated as a measurable surface. Capture one golden transcript, one failure case, and the rollback note before expanding scope. Treat this stage as a contract between inputs and validated outputs. Name the artifacts, define success checks, and refuse silent partial completion. Keep graph state flat and typed. Nested blobs hide which node wrote which field and break resume after interrupts.
PRODUCERS CONSUMERS
--------- ---------
Human authors ----> AI agents
BigQuery pipelines ----> HTML visualizers
LLM-generated ----> Search indexes
Wiki exports ----> Other agents / tools
3. Format, not platform
The 3 Format not platform stage works best when treated as a measurable surface. Capture one golden transcript, one failure case, and the rollback note before expanding scope. Record timings and token or query cost next to functional results. Cost visibility early prevents surprise bills when the path moves from demo to shared environments. Keep graph state flat and typed. Nested blobs hide which node wrote which field and break resume after interrupts.
OKF vs Everything Else You’re Already Using
The OKF vs Everything Else stage works best when treated as a measurable surface. Capture one golden transcript, one failure case, and the rollback note before expanding scope. Keep configuration outside application code. Environment files, secret stores, and feature flags belong in one place operators can audit without reading the whole graph. Keep graph state flat and typed. Nested blobs hide which node wrote which field and break resume after interrupts. The OKF vs Everything Else stage works best when treated as a measurable surface. Capture one golden transcript, one failure case, and the rollback note before expanding scope. Prefer small, testable units over sprawling scripts. When a step fails, the failure should point at a single responsibility rather than a tangled pipeline.
+---------------------+---------------------------+---------------------------+
| TOOL | PURPOSE | SCOPE |
+---------------------+---------------------------+---------------------------+
| CLAUDE.md | How the agent behaves | Per-project, one agent |
| AGENTS.md | Repo instructions | Per-repo, tool-specific |
| Karpathy LLM wiki | Agent-maintained notes | Pattern, not a spec |
| MCP | Live tool access | Runtime connections |
| OKF | What the team knows | Cross-project, any agent |
+---------------------+---------------------------+---------------------------+
The Karpathy Connection
For the The Karpathy Connection stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Treat this stage as a contract between inputs and validated outputs. Name the artifacts, define success checks, and refuse silent partial completion. Put human approval on edges that spend money or change production data. Compile-time wiring does not equal business completeness.
KARPATHY LAYER OKF EQUIVALENT
-------------- --------------
Raw sources (immutable) --> External datasets, docs, APIs
(OKF bundles are the compiled layer)
Wiki (LLM-maintained) --> OKF bundle (*.md + frontmatter)
(OKF adds type, resource, tags, timestamp)Schema (CLAUDE.md) --> Producer/consumer conventions + okf/SPEC.md
(org-wide spec replaces per-vault bespoke rules)
What Google Actually Shipped
For the What Google Actually Shipped stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Record timings and token or query cost next to functional results. Cost visibility early prevents surprise bills when the path moves from demo to shared environments. Put human approval on edges that spend money or change production data. Compile-time wiring does not equal business completeness.
+--------------------+----------------------------------+
| BUNDLE | WHAT IT DOCUMENTS |
+--------------------+----------------------------------+
| GA4 e-commerce | Analytics tables and metrics |
| Stack Overflow | Public dataset concepts |
| Bitcoin | Blockchain dataset structure |
+--------------------+----------------------------------+
When to Use OKF
For the When to Use OKF stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Keep configuration outside application code. Environment files, secret stores, and feature flags belong in one place operators can audit without reading the whole graph. Put human approval on edges that spend money or change production data. Compile-time wiring does not equal business completeness. For the When to Use OKF stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Prefer small, testable units over sprawling scripts. When a step fails, the failure should point at a single responsibility rather than a tangled pipeline.
How to Get Started
When working through the How to Get Started stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Treat this stage as a contract between inputs and validated outputs. Name the artifacts, define success checks, and refuse silent partial completion. Checkpoint after expensive steps. Resume should not re-bill the same LLM call when an operator retries a later node.
/plugin marketplace add scaccogatto/okf-skills
/plugin install okf@scaccogatto
npx skills add scaccogatto/okf-skills
/okf:okf produce .okf # create your first bundle
/okf:validate .okf --strict # check conformance
/okf:visualize .okf # generate viz.html
---
type: Decision
title: "Why we use Postgres over MySQL"
description: "JSONB support and row-level security were decisive."
timestamp: 2026-03-01T00:00:00Z
tags: [infrastructure, database]
---
## ContextIn early 2026 we evaluated both options. MySQL's JSON support was insufficient for our metadata schema...## DecisionPostgres 16. See [datasets/primary-db.md](../datasets/primary-db.md) for schema docs.
The Layered Memory Stack
When working through the The Layered Memory Stack stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Record timings and token or query cost next to functional results. Cost visibility early prevents surprise bills when the path moves from demo to shared environments. Checkpoint after expensive steps. Resume should not re-bill the same LLM call when an operator retries a later node.
+--------------------------------------------------+
| AGENT SESSION |
+--------------------------------------------------+
| CLAUDE.md / AGENTS.md |
| (behavioral rules - how agent acts) |
+--------------------------------------------------+
| OKF BUNDLE (.okf/) |
| (curated team knowledge - what we know) |
| - index.md: entry points per domain |
| - concepts/*.md: services, datasets, decisions |
| - log.md: change history |
+--------------------------------------------------+
| AUTO-MEMORY (memory.md) |
| (what the agent picked up implicitly) |
+--------------------------------------------------+
| MCP CONNECTIONS |
| (live tool access - what the agent can do) |
+--------------------------------------------------+
| SKILLS (.claude/skills/) |
| (reusable SOPs - how to do specific tasks) |
+--------------------------------------------------+
What’s Still Open
When working through the What s Still Open stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Keep configuration outside application code. Environment files, secret stores, and feature flags belong in one place operators can audit without reading the whole graph. Checkpoint after expensive steps. Resume should not re-bill the same LLM call when an operator retries a later node. When working through the What s Still Open stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Prefer small, testable units over sprawling scripts. When a step fails, the failure should point at a single responsibility rather than a tangled pipeline.
Why This Is a Bigger Deal Than It Looks
The Why This Is a stage works best when treated as a measurable surface. Capture one golden transcript, one failure case, and the rollback note before expanding scope. Treat this stage as a contract between inputs and validated outputs. Name the artifacts, define success checks, and refuse silent partial completion. Keep graph state flat and typed. Nested blobs hide which node wrote which field and break resume after interrupts.
Operational checklist
When working through the Operational checklist stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest.
Document the happy path and the recovery path together. Retries, human gates, and dead-letter handling are part of the product, not later polish.
Checkpoint after expensive steps. Resume should not re-bill the same LLM call when an operator retries a later node.
Pin dependency versions and record the image digest that ran the demo. Reproducibility beats tribal knowledge.
Prefer small, testable units over sprawling scripts. When a step fails, the failure should point at a single responsibility rather than a tangled pipeline.
Checkpoint after expensive steps. Resume should not re-bill the same LLM call when an operator retries a later node.
Before promoting the stack, freeze versions, capture a golden transcript for the critical path, and confirm rollback steps. Shared environments need rate limits, tenancy checks, and a clear owner for secret rotation. Prefer boring reliability over clever one-off demos.
Batch note for 7e96a33898ce: keep provider keys out of the repo, set a per-session token ceiling, and store transcripts next to the eval fixtures so later model swaps stay comparable.