Vos fichiers de contexte pour l'IA mentent en silence : j'ai construit HCS pour le mesurer

En bref

• Le problème : les fichiers de contexte pour l'IA (AGENTS.md, CLAUDE.md, résumés de projet) vieillissent sans prévenir, ne disent pas d'où vient ce qu'ils affirment, et personne ne sait ce qu'ils ont perdu.
• HCS (Holographic Context Standard) est un format ouvert, un outil en ligne de commande et un serveur MCP, sous licence MIT. Chaque affirmation cite sa source avec une empreinte, hcs check détecte sans IA ce qui a changé, et hcs score mesure ce qu'un modèle retrouve vraiment.
• Mesuré, pas promis : sur trois dépôts publics choisis à l'avance, un contexte HCS de 2 000 tokens a répondu à 46,7 % des questions, contre 27,8 % pour un résumé classique de même taille et 10 % pour le README du projet. Un second modèle d'une autre famille confirme l'écart.
• Ce qui n'a pas marché est publié aussi : l'auto-amélioration (refine) n'aide pas, l'alerte sur les dépendances donne surtout de fausses alertes, la détection d'injection laisse passer environ la moitié des attaques nouvelles.
• Disponible depuis le 23 octobre 2026 : npm install -g @oufrid/hcs-cli, et pip install hcs-format pour la version Python. Le format est stable (SPEC 1.0), l'outil reste expérimental (0.3).

Le constat : des fichiers qui ont l'air justes

Je travaille tous les jours avec des agents de code, sur mes sites et sur mes applications Android. Comme tout le monde, je leur donne des fichiers de contexte : un CLAUDE.md qui décrit le projet, ses règles, ses commandes, ses pièges. C'est le levier le plus rentable que je connaisse, je l'explique dans le guide sur l'optimisation du contexte et l'outil fichier d'instructions pour agent aide à en écrire un.

Mais ces fichiers ont trois défauts que j'ai fini par trouver gênants :

1. Ils vieillissent en silence. Le code change, une commande est renommée, une règle évolue. Le fichier, lui, ne bouge pas. L'agent continue de croire quelque chose de faux, avec assurance. Rien ne l'a signalé.
2. On ne sait pas d'où vient une affirmation. Quand le fichier dit « les remboursements sont acceptés sous 14 jours », rien n'indique quel fichier ou quelle fonction le prouve. Impossible de vérifier vite.
3. Personne ne sait ce qu'un résumé a perdu. Un résumé est fait pour être lisible. Il garde la structure et perd les exceptions, les valeurs précises, les distinctions. Le relire ne suffit pas : on le compare à ce dont on se souvient, pas à la source.

Ce n'est pas une impression isolée : les études de fichiers AGENTS.md publics, citées dans le dossier de comparaison du projet (PRIOR_ART.md), rapportent que la dérive est fréquente.

L'idée : trois propriétés dans un seul fichier

HCS repose sur une idée simple : un fichier de contexte devrait pouvoir prouver ce qu'il dit, remarquer quand il devient faux et mesurer ce qu'il perd.

• Traçable : chaque affirmation cite sa source, une fonction, une classe, un titre ou une plage de lignes. Un modèle sait où lire au lieu de deviner.
• Vérifiable : chaque citation porte une empreinte du texte cité. hcs check détecte, sans appeler d'IA, les affirmations dont la source a changé. Il ignore le simple reformatage, suit le code qui a seulement été déplacé, même vers un autre fichier, et échoue quand le sens a pu changer. Il peut donc bloquer une intégration continue.
• Mesuré : le fichier embarque des questions-tests dont la réponse est prouvée mot pour mot dans la source. hcs score calcule un score de fidélité pour un modèle donné, avec un intervalle de confiance, une comparaison sans contexte et le taux de réponses où le contexte a induit le modèle en erreur.

Un serveur MCP intégré complète le tout : le modèle lit d'abord quelques centaines de tokens d'affirmations, puis ouvre la source exacte d'une affirmation seulement quand il a besoin d'un détail. Si MCP est nouveau pour vous, le guide connecter une IA à vos outils l'explique.

Ce qui existait déjà

Avant d'écrire une ligne, j'ai cherché si quelqu'un l'avait déjà fait. Les briques existent séparément : des linters de fichiers AGENTS.md, des outils qui épinglent la documentation au code avec une empreinte, des méthodes d'évaluation de résumés par questions, des compresseurs de prompts, des cartes de dépôt.

Aucune idée de HCS n'est nouvelle prise seule, et le dossier de comparaison le dit clairement. Ce que je n'ai pas trouvé ailleurs, c'est la combinaison dans un format portable : une citation avec empreinte exigée sur chaque affirmation, une génération qui vérifie chaque citation mot pour mot, un commentaire automatique de pull request listant les affirmations touchées, et l'ouverture de la source exacte par MCP. C'est une impression tirée d'un recensement, pas une preuve d'absence.

Comment je l'ai testé, honnêtement

Dans l'IA, il est facile de publier un chiffre flatteur. Je voulais l'inverse : des résultats qu'un lecteur sceptique puisse vérifier. Toutes les mesures sont dans le rapport du projet (bench/REPORT.md), chaque chiffre renvoie à ses résultats bruts.

Les règles que je me suis imposées :

• Pas de citation inventée : quand un modèle compile un fichier HCS, chaque affirmation et chaque question doivent citer la source mot pour mot, sinon elles sont jetées. Sur les premiers essais réels, cette vérification gardait 85 à 89 % de ce que proposaient les modèles.
• Des questions écrites à part : les questions du test ont été rédigées à partir de la source seule, sans voir le contexte compilé. Sinon, le test favorise HCS.
• Des intervalles de confiance : avec 24 à 30 questions par dépôt, les écarts sont incertains. Chaque différence est donnée avec son intervalle à 95 %.
• Un juge d'une autre famille que le modèle qui répond.
• Une confirmation pré-enregistrée : le protocole et le critère de réussite ont été publiés dans le dépôt avant le premier appel aux modèles sur les nouveaux dépôts.

Le premier résultat m'a déçu

Sur cinq dépôts publics (kilo, itsdangerous, anyhow, cobra, ky), avec des questions indépendantes, le premier verdict était net : HCS n'était pas mesurablement meilleur qu'un résumé classique de même taille (+6,3 points, avec un intervalle qui contenait zéro). Il battait largement le README des projets, mais pas un simple résumé.

En cherchant pourquoi, le diagnostic est venu des chiffres eux-mêmes : dans un contexte de 2 000 tokens, les références aux sources occupaient 31 à 39 % de la place, et des fichiers entiers n'avaient aucune affirmation. J'ai donc ajouté un mode de rendu compact : les affirmations seules, et une affirmation par fichier source à tour de rôle.

Avec ce mode, sur ces cinq dépôts :

La confirmation sur trois dépôts nouveaux

Le problème est évident : j'avais conçu le mode compact après avoir vu ces cinq dépôts. Un résultat obtenu ainsi peut être un ajustement aux données. D'où la confirmation pré-enregistrée sur trois dépôts jamais utilisés : express, requests et logrus.

Le critère fixé à l'avance, HCS compact moins résumé, donne +18,9 points, avec un intervalle de +7,2 à +30,6 : entièrement au-dessus de zéro, donc confirmé. Avec un second modèle, plus petit et d'une autre famille (ministral-14b de Mistral), l'écart tient : +16,1 points sur les nouveaux dépôts et +18,8 sur les cinq premiers.

Un dernier résultat m'a appris quelque chose : quand le modèle peut aller lire la source une fois avant de répondre, il gagne environ 20 points, quel que soit le contexte de départ. Lire la bonne source compte plus que la forme du résumé. HCS y arrive avec moins de lectures, parce que ses références pointent vers le code exact, mais l'avantage n'est pas significatif dans ce mode.

Les limites de ces chiffres

• Un seul modèle (Gemini 3.8 Flash) a compilé les fichiers, écrit les questions et les résumés. Il peut favoriser ce qui est écrit dans ses propres mots.
• Les questions sont générées, 24 à 30 par dépôt, et un seul budget a été testé (2 000 tokens).
• Sur des projets très connus, un modèle sans contexte répond parfois mieux grâce à sa mémoire du code public. Un code privé n'aurait pas cet avantage, mais ce cas n'a pas été mesuré.
• Les taux de réussite restent modestes : les questions portent sur des détails précis (noms, valeurs, messages), et 2 000 tokens ne couvrent qu'une petite partie de la source.

Ce qui n'a pas marché

Je publie ces échecs avec le même soin que les réussites, parce qu'ils disent où sont les limites.

• L'auto-amélioration ne généralise pas. La commande hcs refine ajoute des affirmations pour combler les questions ratées. Elle fait monter le score sur les questions qu'elle optimise, jusqu'à 100 % sur le dépôt de HCS lui-même. Mais sur les questions mises de côté, le score est passé de 50,0 % à 40,9 %, avec davantage de réponses fausses, et il n'a pas bougé sur un second dépôt (44,4 %). La fonction reste disponible comme expérience, et le README dit qu'elle n'a pas aidé.
• L'alerte sur les dépendances crie souvent au loup. Une affirmation sur une fonction peut devenir fausse quand une fonction qu'elle appelle change. HCS sait le signaler, mais sur l'historique du projet, 17 alertes sur 18 étaient inutiles.
• La détection d'injection de prompt est un filtre, pas une garantie. Après réglage, elle attrape 35 attaques sur 39 du corpus de test. Sur un jeu d'attaques gardé à part et jamais utilisé pour le réglage, elle n'en attrape que 7 sur 15. Il faut s'attendre à ce qu'environ la moitié des attaques nouvelles passent. Le message envoyé au modèle, qui précise que les affirmations ne sont jamais des instructions, est la seconde ligne de défense.
• Les petits modèles locaux mesurent mal. Un modèle de 7 milliards de paramètres sur processeur répondait « je ne sais pas » même quand la réponse était dans son contexte. Ils servent à faire tourner la chaîne sans quota, pas à produire des chiffres.
• Les offres gratuites ne suffisent pas pour tout. Les premiers essais ont tourné sur les offres gratuites de Gemini et de Groq, et HCS gère leurs quotas : il reprend là où il s'est arrêté. Mais l'offre gratuite de Gemini autorise environ 20 requêtes par jour et par modèle, et le benchmark principal a utilisé une clé payante. Le second modèle de la confirmation a tourné sur Mistral.

Comment il a été construit

J'ai conçu HCS, fixé ses règles et décidé de ce qui était publié. Le code, lui, a été écrit avec un agent de code, Claude Code, du premier commit le 21 octobre 2026 à la publication le 23 octobre.

La leçon que j'en retiens vaut pour tout travail avec un agent : la vitesse ne vaut rien sans règles écrites. Le dépôt contient un fichier CLAUDE.md qui impose, entre autres, que chaque chiffre publié renvoie à des résultats bruts, qu'un essai non fait soit marqué comme tel, et que les biais soient écrits à côté des résultats. C'est cette discipline qui a fait remonter le premier résultat décevant au lieu de le cacher, et qui a conduit à la confirmation pré-enregistrée. Un agent produit ce qu'on lui demande. Si on lui demande des preuves, il en produit, et elles peuvent contredire ce qu'on espérait.

Le projet applique d'ailleurs sa propre méthode : son dépôt contient un fichier project.hcs qui se décrit lui-même, vérifié automatiquement à chaque modification.

L'essayer en 5 minutes

Il faut Node.js 18.17 ou plus récent. L'outil n'a aucune dépendance.

1. Installer :

``bash npm install -g @oufrid/hcs-cli ``

1. Voir la vérification en action, sans clé d'IA, sur le dépôt de HCS lui-même :

``bash git clone https://github.com/Oufrid/HCS.git && cd HCS hcs check project.hcs ``

1. Compiler le contexte de votre propre projet, avec une clé d'API gratuite (Gemini, Groq) ou un modèle local via Ollama :

``bash export GEMINI_API_KEY=... hcs models gemini hcs compile --model gemini:<modèle> --rpm 8 -o project.hcs ``

1. Le brancher à votre agent par MCP, par exemple dans Claude Code :

``bash claude mcp add hcs -- hcs serve project.hcs ``

Attention : la compilation et la mesure envoient votre code au fournisseur choisi, et certaines offres gratuites peuvent utiliser les données envoyées. N'envoyez que du code que vous avez le droit de partager, ou utilisez un modèle local. La vérification (check), le rendu et le serveur MCP, eux, ne contactent aucune IA.

Le détail des commandes, des réglages et des intégrations est sur la page du projet HCS.

La suite, et comment aider

Le format est figé en version 1.0 : les fichiers écrits aujourd'hui resteront lisibles, et toute évolution passe par une proposition publique (RFC). L'outil, lui, reste expérimental et va encore changer.

Ce qui m'aiderait le plus :

• Des résultats sur de vrais projets, surtout privés, là où un modèle ne peut pas s'appuyer sur sa mémoire du code public.
• Des cas pour d'autres langages : la localisation des fonctions est heuristique et ne couvre pas toutes les syntaxes.
• Des retours sur le format, et des corrections du dossier de comparaison si un outil fait déjà mieux.

Tout se passe sur le dépôt : github.com/Oufrid/HCS. Si vous voulez appliquer cette approche à un projet d'entreprise, vous pouvez aussi me contacter.

FAQ

HCS remplace-t-il AGENTS.md ou CLAUDE.md ?

Non, il les complète. Vous pouvez garder vos fichiers et ajouter un fichier .hcs à côté. La commande hcs audit vérifie même un AGENTS.md existant : elle signale les références cassées, et peut mesurer ce qu'il transmet vraiment avec les questions d'un fichier HCS.

Un fichier HCS valide garantit-il que tout est vrai ?

Non. Il garantit que chaque citation a été trouvée dans la source au moment de la compilation, et que la source citée n'a pas changé depuis. Une paraphrase infidèle d'une citation exacte, une source elle-même fausse, ou un changement ailleurs dans le code qui rend une affirmation fausse ne sont pas détectés.

Mon code quitte-t-il ma machine ?

Pas pour la vérification, le rendu, les statistiques ou le serveur MCP, qui n'appellent aucun modèle. La compilation et la mesure envoient le code ou le contexte au fournisseur que vous choisissez. Avec un modèle local via Ollama, rien ne sort, mais les petits modèles donnent des résultats faibles.

Est-ce prêt pour la production ?

Le format, oui : il est stable en version 1.0. L'outil est en version 0.3 et expérimental : la vérification sans IA et le serveur MCP sont complets et testés, et une seconde implémentation en Python passe la même suite de tests de conformité. Les fonctions qui utilisent une IA marchent, mais leurs résultats dépendent du modèle, et certaines, comme refine, n'ont pas fait leurs preuves.