Principes : pourquoi OKF reste lisible, portable et volontairement minimal ?

Le principe central : faire simple pour rester portable

OKF part d'un choix très pragmatique: la connaissance utile aux agents doit être représentée dans des formats déjà compris par les humains et par les machines. La spec v0.1 se limite donc à un dossier de fichiers Markdown, avec un frontmatter YAML et des liens Markdown.

Ce minimalisme évite de créer une nouvelle plateforme à apprendre, déployer et maintenir. Si une équipe sait ouvrir un fichier, lire du Markdown, versionner un dossier dans Git et suivre des liens, elle possède déjà l'essentiel de l'infrastructure nécessaire pour commencer.

Le principe central est donc simple: standardiser le moins possible, mais assez pour que des agents et des outils différents puissent reconnaître, parcourir et réutiliser le même contexte.

Human-readable : un humain doit pouvoir relire le contexte

Le premier principe est presque culturel: un bundle OKF doit rester lisible par une personne sans outil spécialisé. La connaissance ne doit pas être enfermée dans une interface, un export opaque ou une base de métadonnées que seuls quelques systèmes savent interroger.

Markdown joue ici un rôle important. Il permet d'écrire des titres, listes, tableaux, exemples, citations et blocs de code dans une forme que les humains comprennent immédiatement. Un développeur peut lire le fichier dans GitHub. Un expert métier peut le relire dans un éditeur. Un agent peut l'ingérer sans transformation lourde.

Cette lisibilité humaine est aussi une protection contre les bundles mal entretenus. Si personne ne peut relire facilement le contexte, personne ne le corrige. Si personne ne le corrige, l'agent finit par consommer une connaissance périmée avec beaucoup d'assurance.

Agent-readable : un agent doit pouvoir parser sans SDK propriétaire

OKF n'est pas seulement du Markdown libre. Chaque concept possède un frontmatter YAML qui expose les informations structurées utiles aux agents: le type du concept, son titre, sa description, sa ressource source, ses tags ou son timestamp quand ils existent.

La spec rend le champ `type` obligatoire, parce qu'un consommateur doit pouvoir router, filtrer ou présenter un concept même s'il ne comprend pas tout son contenu. En revanche, les autres champs restent souples: le format donne une structure, mais il n'impose pas une taxonomie globale.

Ce principe est précieux pour les builders. Un agent peut scanner un dossier, identifier les concepts, filtrer les métriques, repérer les playbooks, suivre les liens, puis décider quoi charger en contexte. Il n'a pas besoin d'un SDK propriétaire pour commencer à lire.

Versionnable : la connaissance doit devenir diffable

Une grande partie de la connaissance d'entreprise change sans laisser de trace claire: une définition de métrique évolue, une règle commerciale est ajustée, un playbook support est corrigé, une source devient obsolète. Quand tout cela vit dans des notes dispersées, il devient difficile de savoir ce qui a changé et pourquoi.

OKF s'aligne avec une logique metadata-as-code. Un bundle peut vivre dans Git. Les modifications deviennent visibles dans des diffs. Les équipes peuvent relire une pull request, commenter une définition, restaurer une ancienne version ou comprendre qui a modifié un playbook.

Ce principe ne transforme pas automatiquement toute l'entreprise en équipe software, mais il apporte une pratique très saine: traiter les connaissances critiques comme des artefacts qui méritent historique, review et ownership.

Portable : un bundle doit survivre aux outils

La portabilité est l'un des grands intérêts d'OKF. Un bundle est un dossier. Il peut être zippé, versionné, copié, synchronisé, publié dans un repo, monté dans un système de fichiers ou servi depuis un serveur statique.

Cette portabilité réduit le risque de lock-in. Une entreprise peut changer de modèle, de framework agent, d'outil documentaire ou de cloud sans devoir abandonner toute sa couche de contexte. Les consommateurs changent, mais le bundle reste lisible.

La portabilité est aussi organisationnelle. Un bundle peut être transmis à une équipe, un prestataire, un agent spécialisé ou un outil de visualisation. Cela transforme le contexte en actif partageable plutôt qu'en accumulation de notes locales.

Minimalement opinionated : standardiser le minimum utile

OKF v0.1 ne cherche pas à définir une ontologie universelle. Il ne dit pas à toutes les entreprises comment nommer leurs métriques, leurs assets, leurs workflows ou leurs règles métier. Cette liberté est volontaire: les domaines sont trop différents pour être capturés par une taxonomie unique dès la première version.

Le format standardise donc le minimum utile: fichiers Markdown, frontmatter YAML, champ `type`, liens Markdown, fichiers réservés comme `index.md` et `log.md`, et règles de conformité suffisamment claires pour qu'un consommateur sache quoi attendre.

Cette approche laisse respirer le domaine. Une équipe data peut créer des types `Metric`, `BigQuery Table` ou `Dataset`. Une équipe support peut créer `Playbook`, `Objection`, `FAQ` ou `Policy`. L'interopérabilité vient du contenant commun, pas d'une uniformisation forcée de tous les métiers.

Tolérant : un consommateur ne doit pas casser sur l'inconnu

La tolérance est un principe essentiel de la spec. Les consommateurs doivent accepter les types inconnus, les champs supplémentaires inconnus, les champs optionnels manquants, les index absents et même les liens cassés. Cela peut surprendre, mais c'est une condition de robustesse.

Un bundle de connaissance vit, se réorganise et se complète progressivement. Si un agent refuse de lire un bundle parce qu'un lien n'existe pas encore ou parce qu'un producteur a ajouté un champ métier, le format devient fragile. OKF préfère une consommation best-effort à une validation trop cassante.

En pratique, cela signifie qu'un outil peut afficher un concept générique quand il ne connaît pas son type, préserver les champs qu'il ne comprend pas, signaler un lien cassé sans rejeter tout le bundle, et continuer à aider l'utilisateur malgré l'imperfection du corpus.

Ce que ces principes changent en pratique

Ces principes changent la façon de penser la connaissance. Au lieu d'imaginer un grand projet de documentation centralisé, OKF permet de commencer par un périmètre utile: quelques concepts critiques, des sources fiables, des liens explicites, un `index.md` simple et un historique de changements.

Ils changent aussi la relation entre humains et agents. L'humain ne rédige pas seulement pour un autre humain. Il structure une matière que l'agent peut relire, traverser et citer. L'agent ne remplace pas l'expertise: il bénéficie d'un contexte mieux préparé.

Enfin, ces principes donnent une grille de qualité. Un bon bundle OKF n'est pas celui qui contient tout. C'est celui qui reste lisible, navigable, maintenu, portable et tolérant au changement.

Lire ensuite

Après les principes, il devient plus simple de comprendre les pages techniques: comment un bundle est structuré, comment un concept est écrit, comment les liens forment un graphe et quelles règles minimales rendent un bundle conforme à OKF v0.1.

Sources officielles et lectures utiles