06 - Anatomie d'un concept
Anatomie d'un concept : le fichier Markdown qui rend une connaissance actionnable
Le concept file est l'unité de base d'OKF. Si le bundle est le dossier portable, le concept est la fiche qui rend une connaissance précise lisible, typée, reliée et vérifiable.
Définir un concept simplement
Dans OKF, un concept est une unité de connaissance représentée par un document Markdown. Il peut décrire un actif tangible, comme une table BigQuery, un endpoint API ou un dashboard. Il peut aussi décrire une notion abstraite, comme une métrique, une règle métier, un persona, une décision ou un playbook.
Chaque concept file a deux parties: un frontmatter YAML en haut du fichier, puis un body Markdown. Le frontmatter donne aux agents des métadonnées structurées. Le body explique le contenu dans un format que les humains peuvent relire.
Le concept ID est simplement le chemin du fichier dans le bundle, sans le suffixe `.md`. Par exemple, `tables/orders.md` devient `tables/orders`. Ce chemin sert d'identifiant stable dans le bundle et facilite les liens entre concepts.
Quand créer un concept file ?
Il faut créer un concept file quand une connaissance mérite d'être maintenue, reliée ou consommée séparément. Si une notion a ses propres sources, ses propres exemples, ses propres règles ou ses propres dépendances, elle mérite probablement un fichier dédié.
Une table importante peut devenir `tables/orders.md`. Une métrique critique peut devenir `metrics/monthly_recurring_revenue.md`. Un playbook de support peut devenir `playbooks/refund-request.md`. Une décision produit peut devenir `decisions/pricing-v2.md`.
À l'inverse, il ne faut pas transformer chaque phrase en concept. Un bon concept file correspond à une unité utile pour une tâche: répondre à un client, calculer une métrique, appeler une API, analyser un dossier, suivre une procédure ou justifier une décision.
Frontmatter YAML : la couche lisible par les agents
Le frontmatter YAML est le bloc situé tout en haut du fichier, entre deux lignes `---`. Il donne au concept une petite couche structurée: type, titre, description, ressource, tags, timestamp et champs métiers éventuels.
Cette couche est importante parce qu'elle permet aux consommateurs de filtrer, router, afficher ou indexer les concepts sans devoir interpréter tout le body Markdown. Un agent peut chercher tous les concepts de type `Metric`, tous les fichiers tagués `sales`, ou tous les concepts reliés à une ressource donnée.
La spec autorise aussi les champs additionnels. Une équipe peut ajouter `owner`, `status`, `system`, `confidence`, `source_quality`, `team` ou tout autre champ utile. Les consommateurs doivent préserver et tolérer ces champs inconnus plutôt que rejeter le document.
Le champ type : le seul obligatoire en OKF v0.1
`type` est le seul champ requis dans le frontmatter d'un concept file OKF v0.1. Il indique la nature du concept: `BigQuery Table`, `Metric`, `Playbook`, `API Endpoint`, `Decision`, `Persona`, `Reference`, ou un type propre à votre domaine.
Les types ne sont pas enregistrés dans un registre central. La spec recommande de choisir des valeurs descriptives et auto-explicatives. Un consommateur qui ne connaît pas un type doit le traiter comme un concept générique plutôt que casser la lecture du bundle.
En pratique, le bon type doit aider un agent à comprendre comment utiliser le fichier. `Metric` indique qu'il faut chercher définition, grain, formule et exclusions. `Playbook` indique qu'il faut chercher déclencheur, étapes, limites et escalade. `API Endpoint` indique qu'il faut chercher contrat, exemples et contraintes d'usage.
Les champs recommandés : title, description, resource, tags, timestamp
`title` donne un nom lisible au concept. `description` résume son rôle en une phrase. Ces deux champs aident les humains, les index générés, les résultats de recherche et les previews dans un visualizer.
`resource` pointe vers l'actif sous-jacent quand il existe: table BigQuery, dashboard, endpoint API, ticket, page produit, document source. Pour une notion abstraite comme une règle métier ou une décision, ce champ peut être absent.
`tags` permet de catégoriser transversalement les concepts, et `timestamp` indique la dernière modification significative. Ces champs ne sont pas obligatoires, mais ils augmentent fortement la valeur opérationnelle d'un bundle maintenu dans le temps.
Body Markdown : la partie que les humains lisent vraiment
Le body est tout ce qui vient après le frontmatter. C'est là que le concept devient réellement utile: définition, contexte, schéma, exemples, étapes, règles, limites, citations et liens vers d'autres concepts.
La spec recommande de favoriser le Markdown structuré: headings, listes, tableaux, blocs de code et sections explicites. Cette structure aide les humains à scanner le fichier et aide les agents à récupérer les passages utiles avec moins d'ambiguïté.
Un concept `Metric` peut contenir `# Definition`, `# Formula`, `# Grain`, `# Exclusions`, `# Examples` et `# Citations`. Un concept `Playbook` peut contenir `# Trigger`, `# Steps`, `# Escalation`, `# Limits` et `# Citations`. Il n'y a pas de sections obligatoires, mais les conventions réduisent les frictions.
Liens : relier le concept au reste du bundle
Les liens Markdown relient un concept au reste du bundle. Un concept `orders.md` peut pointer vers `customers.md` pour expliquer une jointure. Une métrique peut pointer vers les tables qui la composent. Un playbook peut pointer vers une politique ou un template.
La spec recommande les liens absolus, relatifs à la racine du bundle, comme `/tables/customers.md`, parce qu'ils restent plus stables quand un fichier est déplacé dans son sous-dossier. Les liens relatifs restent possibles pour les concepts voisins.
Le sens de la relation n'est pas porté par un type d'arête formel. Il vit dans la phrase autour du lien: dépend de, rejoint, cite, remplace, explique, utilise, escalade vers. C'est simple, mais très efficace pour produire un graphe navigable.
Citations : prouver ce que le concept affirme
Les citations sont essentielles dès qu'un concept affirme quelque chose qui doit être vérifiable. Une définition de métrique, une règle de calcul, une décision produit, une procédure support ou une preuve marketing doit indiquer d'où elle vient.
La spec recommande une section `# Citations` en bas du document, avec des liens numérotés. Ces citations peuvent pointer vers des URLs externes, des chemins internes au bundle, ou des concepts `references/` qui représentent des sources importantes.
Pour une entreprise, cette discipline change beaucoup de choses. Elle permet à un humain de vérifier une réponse, à un agent de citer ses sources, et à une équipe de distinguer une connaissance validée d'une note approximative.
Exemple complet : playbook de relance commerciale
L'exemple ci-dessous montre un concept abstrait: un playbook commercial. Il n'est pas directement lié à une table ou une API, mais il décrit une procédure que l'entreprise veut rendre actionnable.
On y retrouve le frontmatter YAML, le champ `type`, quelques champs recommandés, puis un body Markdown structuré avec objectif, étapes et citations. C'est exactement le type de fichier qu'un agent peut utiliser pour guider une action sans improviser.
---
type: Playbook
title: Relance des devis B2B
description: Méthode de relance pour les devis ouverts.
resource: https://crm.example.com/views/open-quotes
tags: [sales, pme, relance]
timestamp: 2026-07-08T09:00:00Z
owner: equipe-commerciale
---
# Objectif
Relancer les devis ouverts avec le bon timing, la bonne preuve
et le bon niveau de personnalisation.
# Étapes
1. Vérifier le statut dans [CRM export Q2](/sources/crm-export-q2.md).
2. Identifier l'objection dominante dans [objections](/sales/objections.md).
3. Utiliser le template adapté dans [email relance](/templates/email-relance.md).
# Citations
[1] [Export CRM Q2](https://crm.example.com/reports/q2)`tables/orders.md`
Schéma, colonnes, grain, clés de jointure, ressource console, citations.
`metrics/mrr.md`
Définition, formule, exclusions, source de vérité, dashboards reliés.
`playbooks/refund-request.md`
Déclencheur, étapes, limites, escalade, templates et preuves.
`apis/create-ticket.md`
Contrat, exemples d'appel, erreurs, quotas, politique d'usage.
`decisions/pricing-v2.md`
Contexte, options, décision, tradeoffs, date et sources.
`personas/ops-manager.md`
Contexte, besoins, objections, critères de décision et messages utiles.
Erreurs fréquentes à éviter
La première erreur est d'écrire un concept trop vague. Un fichier nommé `strategy.md` ou `knowledge.md` devient vite inutilisable. Préférez un concept nommé, situé et actionnable: `metrics/mrr.md`, `playbooks/refund-request.md`, `decisions/pricing-v2.md`.
La deuxième erreur est de remplir le body sans structure. Un agent comme un humain comprend mieux un fichier avec des titres, listes, tableaux, exemples et citations. Le Markdown libre est puissant, mais il doit rester organisé.
La troisième erreur est d'oublier les sources. Sans citations ou ressources, un concept ressemble à une opinion. Avec des sources, il devient vérifiable et beaucoup plus utile dans un workflow agentique.
Lire ensuite
Après avoir compris le concept file, la suite logique est de regarder plusieurs types de fichiers OKF en situation: table, métrique, playbook, API, décision, source ou template.
Revoir l'unité de distribution qui contient les concept files.
Exemples de fichiersExplorer plusieurs types de concepts OKF concrets.
Liens et grapheComprendre comment les liens entre concepts créent une carte navigable.
ConformitéVérifier les règles minimales d'un concept conforme à OKF v0.1.
WorkflowSavoir comment produire, relire et maintenir des concepts dans le temps.
Premier bundleChoisir les premiers concepts à créer sans cartographier toute l'entreprise.
Sources officielles et lectures utiles
Source primaire: règles des concept documents, frontmatter, body, liens, citations et conformité.
OKF README.mdPrésentation officielle du format et du rôle des fichiers Markdown avec YAML frontmatter.
Google Cloud - Introducing OKFAnnonce officielle qui positionne OKF comme format ouvert de contexte pour agents et humains.
Knowledge Catalog repoRepo GoogleCloudPlatform contenant samples, reference agent, visualizer et bundles produits.
Les points à retenir
Un concept file OKF est une unité de connaissance actionnable: un fichier Markdown UTF-8 avec frontmatter YAML, champ `type` requis, body structuré, liens et citations. Sa qualité dépend moins de sa longueur que de sa précision: un bon concept est nommé, typé, sourcé, relié et utile pour une tâche réelle.
