05 - Anatomie d'un bundle
Anatomie d'un bundle : le dossier portable qui contient votre contexte OKF
Le bundle est l'objet central d'OKF. C'est le paquet de contexte que vous pouvez créer, relire, versionner, envoyer, visualiser ou faire consommer par un agent. S'il faut retenir une image simple: un bundle OKF est un dossier de concepts, pas un document géant.
Définir le bundle simplement
Dans la spec OKF, un knowledge bundle est une collection hiérarchique et autonome de documents de connaissance. C'est l'unité de distribution: ce que l'on peut publier dans un repo Git, zipper, archiver, partager avec une équipe ou brancher à un agent.
Un bundle n'est pas une base de données. Il ne contient pas forcément les données elles-mêmes. Il contient surtout le contexte autour des données, systèmes, décisions et workflows: définitions, liens, sources, règles de calcul, exemples, citations, playbooks et chemins vers les ressources réelles.
Cette distinction est importante. Le bundle ne remplace pas votre CRM, votre warehouse ou votre outil support. Il décrit ce qu'un humain ou un agent doit comprendre pour utiliser ces systèmes correctement.
Pourquoi un dossier plutôt qu'un document géant ?
Un document géant devient vite illisible. Il mélange définitions, sources, règles, exemples, historiques, décisions et procédures dans une même masse. Un agent peut y retrouver des passages, mais il a plus de mal à comprendre les frontières entre concepts.
Un dossier impose une granularité plus saine. Chaque fichier décrit une unité de connaissance: une table, une métrique, un playbook, une API, une source ou une décision. Cette séparation rend le contexte plus facile à relire, à modifier, à citer et à relier.
La structure en dossier permet aussi la progressive disclosure. Un humain ou un agent peut commencer par `index.md`, voir les grandes zones disponibles, puis ouvrir seulement les concepts nécessaires à la tâche. On évite de charger toute la connaissance d'un coup.
Ce que contient un bundle OKF
Un bundle OKF contient principalement des fichiers `.md`. Les fichiers réservés `index.md` et `log.md` ont un rôle particulier. Tous les autres fichiers Markdown sont des concept files, c'est-à-dire des unités de connaissance avec frontmatter YAML et body Markdown.
Les sous-dossiers sont libres. Vous pouvez organiser un bundle par domaine (`sales`, `support`, `data`), par type (`tables`, `metrics`, `playbooks`), par produit, par équipe ou par système. La spec ne force pas une taxonomie universelle: elle laisse le producteur organiser le contexte selon ce qui rend la connaissance navigable.
Voici un point de départ concret. Cette arborescence n'est pas une architecture obligatoire, mais un modèle simple pour comprendre comment découper un premier bundle.
okf-bundle/
├── index.md
├── log.md
├── datasets/
│ ├── index.md
│ └── sales.md
├── tables/
│ ├── orders.md
│ └── customers.md
├── metrics/
│ └── weekly_active_users.md
├── playbooks/
│ └── relance-devis.md
└── sources/
└── crm-export-q2.md
index.md : la carte d'entrée du bundle
`index.md` sert de point d'entrée. Il peut apparaître à la racine du bundle ou dans un sous-dossier. Son rôle est de lister ce qui existe à ce niveau, avec des liens vers les concepts ou sous-dossiers pertinents.
Dans un bundle sales, l'index racine peut pointer vers `metrics/`, `playbooks/`, `sources/` et `templates/`. Dans un bundle data, il peut pointer vers `datasets/`, `tables/`, `metrics/` et `joins/`. L'idée n'est pas d'écrire toute la documentation dans l'index, mais d'offrir une carte progressive.
Pour un agent, cette carte est très utile: elle lui évite de scanner tout le bundle immédiatement. Il peut d'abord comprendre les zones disponibles, puis ouvrir les fichiers utiles selon l'intention de la tâche.
log.md : l'historique qui évite le contexte fantôme
`log.md` est optionnel, mais il devient vite précieux. Il documente les changements importants: création d'un concept, mise à jour d'une définition, dépréciation d'une source, ajout d'un playbook, clarification d'une règle métier.
Le contexte fantôme apparaît quand un agent ou une équipe continue d'utiliser une information sans savoir qu'elle a changé. Un `log.md` simple, daté et lisible réduit ce risque. Il donne aux consommateurs une trace des évolutions, même avant d'avoir une gouvernance plus avancée.
Dans une équipe data, le log peut indiquer qu'une métrique de revenu a changé de définition. Dans une équipe support, il peut signaler qu'un playbook d'escalade a été remplacé. Dans une équipe marketing, il peut tracer la mise à jour d'un positionnement ou d'une preuve client.
Concept files : les unités réellement consommées par les agents
Les concept files sont les fichiers les plus importants du bundle. Chaque fichier représente une unité de connaissance. Dans OKF v0.1, chaque concept file doit être un fichier Markdown UTF-8 avec un frontmatter YAML parseable et un champ `type` non vide.
Un concept peut être très concret, comme une table BigQuery, un endpoint API ou un template d'email. Il peut aussi être plus abstrait, comme une métrique, une règle métier, un persona, une décision produit ou un processus support.
Le bon découpage consiste à créer un fichier dès qu'une notion mérite d'être reliée, citée, maintenue ou consommée séparément. Si une section devient trop longue, si elle a ses propres sources, ou si elle est utilisée dans plusieurs workflows, elle mérite probablement son propre concept file.
Comment organiser les sous-dossiers
La spec laisse les producteurs organiser les sous-dossiers comme ils le souhaitent. C'est une force, mais cela demande un peu de discipline. Le meilleur découpage est celui qui aide un humain ou un agent à deviner où chercher.
Pour un bundle data, une structure naturelle peut être `datasets/`, `tables/`, `metrics/`, `joins/` et `sources/`. Pour un bundle sales, on peut préférer `offers/`, `personas/`, `objections/`, `playbooks/` et `templates/`. Pour un bundle support, `policies/`, `faq/`, `macros/`, `escalation/` et `sources/` peuvent être plus utiles.
Le piège est de copier l'organigramme interne plutôt que la logique de consommation. Un agent ne se demande pas toujours quelle équipe possède l'information. Il se demande quel concept utiliser pour accomplir une tâche.
Comment distribuer un bundle
Un bundle OKF peut être distribué de plusieurs façons. Le repo Git est recommandé parce qu'il apporte historique, attribution, diffs et workflows de review. C'est le choix naturel si le bundle doit être maintenu dans le temps.
Une archive zip ou tarball peut suffire pour partager un snapshot: audit client, passation projet, documentation d'un agent, export de contexte pour un prestataire. Un bundle peut aussi vivre comme sous-dossier dans un repo plus large, par exemple à côté d'une application ou d'un data product.
Le point important est que le bundle reste un dossier portable. Il ne dépend pas d'une API propriétaire pour être lu. Un outil peut le visualiser, un agent peut le parcourir, un humain peut le relire, et une équipe peut le versionner.
Exemple concret : un premier bundle sales/data
Imaginons une entreprise SaaS qui veut aider ses agents à répondre correctement aux questions commerciales. Un premier bundle peut contenir `offers/` pour les offres, `personas/` pour les segments clients, `objections/` pour les objections fréquentes, `playbooks/` pour les méthodes de relance, et `sources/` pour les preuves utilisées.
Si cette même entreprise veut brancher un agent sur les métriques, elle peut ajouter `datasets/`, `tables/` et `metrics/`. La métrique `weekly_active_users.md` peut pointer vers les tables qui la composent, citer le dashboard officiel et expliquer les exclusions de calcul.
Le résultat n'est pas une documentation exhaustive. C'est un paquet de contexte actionnable: l'agent sait où lire la définition d'une métrique, quelle source fait foi, quel playbook appliquer, et quels liens suivre pour vérifier une affirmation.
`offers/`, `personas/`, `objections/`, `playbooks/`, `templates/`
Réponses commerciales plus cohérentes et relances mieux contextualisées.
`datasets/`, `tables/`, `metrics/`, `joins/`, `sources/`
Moins de confusion sur les métriques, les tables et les définitions qui font foi.
`faq/`, `policies/`, `macros/`, `escalation/`, `sources/`
Agents support mieux guidés et moins de promesses incorrectes aux clients.
`decisions/`, `features/`, `research/`, `personas/`, `roadmap/`
Meilleure continuité entre décisions, besoins utilisateurs et specs produit.
Les erreurs fréquentes à éviter
La première erreur est de vouloir tout mettre dans le premier bundle. Un bundle trop large devient vite lent à produire, difficile à relire et peu fiable. Il vaut mieux commencer par un périmètre à ROI visible: une métrique critique, un workflow support, une offre commerciale ou un data product.
La deuxième erreur est de créer un document géant nommé `knowledge.md`. Cela rassure au départ, mais cela empêche la granularité qui rend OKF utile. Les concepts doivent pouvoir être reliés, cités et maintenus séparément.
La troisième erreur est de copier des contenus sans source. Un bundle OKF doit aider à savoir ce qui fait foi. Quand une affirmation dépend d'un dashboard, d'une doc officielle ou d'une décision interne, elle doit pointer vers une citation ou une ressource claire.
Lire ensuite
Une fois la structure du bundle comprise, la prochaine étape est de regarder l'unité de base: le concept file. C'est là que se jouent le frontmatter YAML, le champ `type`, le body Markdown, les exemples et les citations.
Revenir à la définition d'OKF avant de structurer un premier bundle.
Anatomie d'un conceptComprendre comment écrire chaque fichier Markdown du bundle.
Liens et grapheVoir comment les concept files se relient entre eux.
ConformitéIdentifier les règles minimales pour qu'un bundle soit conforme à OKF v0.1.
WorkflowPasser de l'audit des sources à la production d'un bundle maintenable.
Premier bundleDémarrer sur un périmètre réduit plutôt que sur toute l'entreprise.
Sources officielles et lectures utiles
Source primaire: annonce d'OKF et mise en contexte du besoin de bundles portables.
OKF SPEC.mdSpécification v0.1: terminologie, bundle structure, fichiers réservés, distribution et conformité.
OKF README.mdPrésentation officielle des bundles, samples, reference agent et visualizer.
Knowledge Catalog repoRepo GoogleCloudPlatform contenant les outils, exemples, samples et bundles produits.
Les points à retenir
Un bundle OKF est l'unité portable de contexte: un dossier de concepts Markdown, organisé selon le domaine, avec une carte d'entrée, un historique possible, des liens, des citations et plusieurs modes de distribution. Le bon premier bundle n'est pas exhaustif: il couvre un périmètre utile, fiable et maintenable.
