HCS en pratique : le guide complet, avec des cas d'usage

En bref

• HCS est un format ouvert et un outil gratuit qui rend un fichier de contexte pour l'IA vérifiable : chaque affirmation cite sa source avec une empreinte, et hcs check signale ce qui a changé. Si vous ne le connaissez pas encore, commencez par la page du projet et l'article de lancement.
• Vous pouvez l'essayer sans rien installer avec HCS en direct : modifiez le code d'une boutique d'exemple et regardez les affirmations passer au rouge.
• Trois façons de créer un fichier HCS : à la main, sans IA et gratuitement ; avec une IA gratuite ou locale ; avec une IA payante pour les gros projets.
• Le vérifier ne demande jamais d'IA : check, seal, render, audit et impact tournent sur votre machine, sans réseau.
• Six cas d'usage détaillés : agent de code, équipe, agence, boutique avec assistant IA, documents non techniques, passage de relais entre conversations.
• HCS est encore expérimental (version 0.3) et ne convient pas à tout : je dis aussi quand ne pas l'utiliser.

Prendre en main l'outil en ligne

Le plus rapide pour comprendre HCS, c'est de le voir réagir. J'ai mis en ligne HCS en direct : le vrai moteur de HCS, celui de la version publiée, tourne dans votre navigateur. Rien n'est envoyé nulle part et aucune IA n'est utilisée.

L'onglet « Démonstration »

Il charge « Boutique Atlas », une boutique marocaine fictive : des tarifs de livraison en dirhams, le paiement à la livraison, des retours sous 7 jours et des codes promo, écrits en TypeScript, en Python et en Markdown. Son fichier de contexte compte 15 affirmations et 6 questions-tests, chacune reliée à sa source.

À gauche, le code, modifiable. À droite, chaque affirmation avec son statut, recalculé à chaque frappe. Trois scénarios se lancent en un clic :

1. 💰 Changer un prix. Les frais de livraison de base passent de 25 à 30 DH dans le code. L'affirmation l1, « La livraison coûte 25 DH plus 4 DH par kilo entamé », devient périmée : la ligne qu'elle cite a changé. Les 14 autres restent à jour.
2. 🧹 Reformater le code. On change les espaces et l'indentation de la fonction fraisLivraison, sans toucher à sa logique. Tout reste à jour : HCS calcule l'empreinte d'un symbole sans tenir compte des espaces.
3. ↪️ Déplacer une fonction. appliquerCode part dans un nouveau fichier, src/remises.ts. Les deux affirmations qui la citent deviennent déplacées : HCS a retrouvé la même fonction, avec la même empreinte, dans un autre fichier. Elles restent valides.

Sous la liste, le curseur de budget (de 250 à 4 000 tokens) montre le texte exact qu'une IA recevrait, dans le profil compact. Les affirmations périmées n'y figurent jamais.

L'onglet « Vérifier mon projet »

Si vous avez déjà un fichier .hcs, choisissez le dossier de votre projet : l'outil lit les fichiers dans votre navigateur et affiche le même rapport que la commande hcs check. Les dossiers node_modules et .git sont ignorés, et la limite est de 5 000 fichiers et 20 Mo.

Les statuts, tels que HCS les définit

Une affirmation prend le pire statut de ses ancres, dans l'ordre ok < moved < review < unsealed < stale < missing. Enfin, une affirmation marquée suspect est un texte qui ressemble à une instruction adressée à une IA (« ignore les consignes précédentes ») : HCS ne l'envoie pas au modèle.

Créer un fichier HCS : trois façons

D'abord, installez l'outil (il faut Node.js 18.17 ou plus récent) :

npm install -g @oufrid/hcs-cli
hcs --version

1. À la main, sans IA et gratuitement

C'est la méthode que je recommande pour commencer, et pour tout ce qu'aucune IA ne devinerait : les règles métier, les interdits, les engagements envers les clients.

Prenons un petit programme de fidélité : un fichier src/fidelite.ts qui calcule les points, et un règlement docs/reglement.md.

hcs init -o fidelite.hcs --title "Programme de fidélité"

La commande crée un fichier vide avec un mode d'emploi en commentaire. J'y écris deux affirmations, chacune reliée à ses sources :

HCS/0.2
@title Programme de fidélité
@root .

[claims]
## Points
#f1[manual] Chaque dirham dépensé rapporte 1 point, arrondi à l'entier inférieur.
  > src/fidelite.ts::pointsGagnes
  > docs/reglement.md::"Gagner des points"
#f2[manual] À partir de 500 points, le client reçoit un bon d'achat de 50 DH.
  > docs/reglement.md::"Utiliser ses points"
  > src/fidelite.ts:4

Trois formes d'ancre sont possibles :

• chemin::Nom : une fonction, une classe, une constante (ici pointsGagnes) ;
• chemin::"Titre" : une section Markdown, désignée par son titre, entre guillemets s'il contient des espaces ;
• chemin:10-20 : une plage de lignes (ici la ligne 4, où est défini le seuil de 500 points).

Le tag [manual] dit que l'affirmation a été écrite par un humain : les mises à jour automatiques ne la supprimeront jamais. Ensuite, on scelle, puis on vérifie :

$ hcs seal fidelite.hcs
fidelite.hcs: 4 sealed, 0 relocated, 0 re-hashed
$ hcs check fidelite.hcs
fidelite.hcs: 2 claims, 0 probes
  claims: 2 ok
OK: every claim still matches its sources.

Chaque ancre porte désormais son empreinte, par exemple > src/fidelite.ts::pointsGagnes #59e39d976b0c.

Maintenant, la boutique change sa règle : le bon d'achat est accordé dès 400 points. Je modifie le règlement et le code, mais j'oublie le fichier de contexte. HCS le remarque :

$ hcs check fidelite.hcs
fidelite.hcs: 2 claims, 0 probes
  claims: 1 ok, 1 stale
  STALE    f2     docs/reglement.md::"Utiliser ses points"  symbol changed (lines 7-9)
  STALE    f2     src/fidelite.ts:4  anchored text changed
FAIL: 1 item(s) no longer match their sources. Review them, then fix or `hcs seal --rehash --ids ...`, or recompile with --update.

La commande sort avec le code 1, ce qui suffit à bloquer une intégration continue. Et surtout, le texte envoyé à l'IA ne contient plus l'affirmation fausse :

$ hcs render fidelite.hcs
<hcs-context title="Programme de fidélité">
[Points]
f1: Chaque dirham dépensé rapporte 1 point, arrondi à l'entier inférieur. (src/fidelite.ts::pointsGagnes; docs/reglement.md::"Gagner des points")
</hcs-context>

Pour la retrouver malgré tout, il faut le demander explicitement avec --keep-stale, et elle est alors marquée (unverified). Je corrige le texte de l'affirmation (500 devient 400), puis j'indique à HCS que j'ai relu :

$ hcs seal fidelite.hcs --rehash --ids f2
fidelite.hcs: 0 sealed, 0 relocated, 2 re-hashed
$ hcs check fidelite.hcs
  claims: 2 ok
OK: every claim still matches its sources.

--rehash est une déclaration humaine : « j'ai relu, c'est toujours vrai ». HCS ne le fait jamais tout seul.

Les sorties ci-dessus sont celles que j'ai obtenues en exécutant ces commandes avec la version 0.3.0. La même démarche fonctionne en arabe, avec des titres Markdown en arabe comme ancres : je l'ai testé, le changement est détecté de la même façon.

2. Avec une IA gratuite ou locale

Pour un projet existant de plusieurs dizaines de fichiers, écrire toutes les affirmations à la main serait long. hcs compile lit vos fichiers et demande à un modèle de proposer des affirmations et des questions-tests, puis jette toutes celles dont la citation ne se trouve pas mot pour mot dans la source. C'est un garde-fou mécanique contre les résumés inventés.

export GEMINI_API_KEY=...        # ou GROQ_API_KEY
hcs models gemini                # la liste des modèles accessibles avec votre clé
hcs compile --model gemini:<modèle> --rpm 8 -o project.hcs

--rpm 8 espace les requêtes pour rester dans les limites des offres gratuites. Si le quota s'épuise en route, rien n'est perdu : relancez plus tard avec --update, et seuls les morceaux manquants sont traités.

Pour que rien ne quitte votre machine, utilisez un modèle local avec Ollama (préfixe ollama:). Deux mises en garde, tirées de la documentation du projet :

• Certaines offres gratuites peuvent utiliser vos requêtes pour améliorer leurs produits. N'y envoyez que du code que vous avez le droit de partager.
• Les petits modèles locaux (7 milliards de paramètres, sur processeur) ont donné des résultats faibles : ils s'abstiennent trop souvent.

Je n'ai pas exécuté compile pour ce guide : la commande demande un modèle. Ce qui précède vient de la documentation officielle.

3. Avec une IA payante, pour les gros projets

Le fonctionnement est le même, avec un modèle plus capable (openai:, anthropic:, mistral:…). Chaque commande qui utilise une IA affiche à la fin le nombre de requêtes et de tokens consommés. Pour estimer le coût à l'avance, utilisez mon calculateur de coût d'API.

Le garder vrai au quotidien

Un fichier de contexte n'a de valeur que s'il reste juste. Voici la routine que j'utilise.

Vérifier à chaque modification. hcs check sort avec le code 0 si tout est à jour, 1 si quelque chose ne correspond plus, et 2 en cas d'erreur de syntaxe. Sur GitHub, l'action officielle le fait à chaque envoi, sans IA et sans secret :

- uses: actions/checkout@v4
- uses: Oufrid/HCS@main
  with:
    file: project.hcs
    strict: "false"      # "true" also fails on unsealed anchors and suspect claims

Prévenir avant la fusion. Le mode impact publie sur chaque pull request un commentaire qui liste les affirmations dont le code cité a changé :

on: pull_request
permissions:
  contents: read
  pull-requests: write
jobs:
  impact:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: Oufrid/HCS@main
        with:
          file: project.hcs
          mode: impact

En local, la même information s'obtient avec hcs impact project.hcs --base origin/main. Sur mon exemple de fidélité, après avoir remplacé un arrondi inférieur par un arrondi normal :

$ hcs impact fidelite.hcs --base HEAD
fidelite.hcs: 1 item(s) cite code changed since HEAD (1 file(s) changed)
  f1     [stale] Chaque dirham dépensé rapporte 1 point, arrondi à l'entier inférieur.
         src/fidelite.ts::pointsGagnes: changed lines 8

Suivre les déplacements. Après une réorganisation, hcs seal project.hcs met à jour les ancres des affirmations déplacées, sans rien relire d'autre.

Accepter un changement relu. hcs seal project.hcs --rehash --ids f2 pour une affirmation précise, après l'avoir relue et corrigée.

Mettre à jour un fichier compilé. hcs compile --model … --update relit seulement les fichiers modifiés et garde tout ce qui est encore vérifié, y compris vos affirmations manual.

Brancher votre agent IA. hcs serve transforme le fichier en serveur MCP : l'agent lit d'abord les affirmations vérifiées, puis ouvre la source exacte quand il a besoin d'un détail. Avec Claude Code, dans le dossier du projet :

claude mcp add hcs -- hcs serve project.hcs

Pour Cursor ou un autre client, la configuration ressemble à ceci (chemins absolus conseillés) :

{
  "mcpServers": {
    "hcs": {
      "command": "hcs",
      "args": ["serve", "/absolute/path/to/project/project.hcs", "--root", "/absolute/path/to/project"]
    }
  }
}

Seul Claude Code a été testé à ce jour. Pour comprendre MCP en général, lisez mon guide Connecter une IA à vos outils.

Six cas d'usage détaillés

1. Le développeur qui travaille avec un agent IA

La situation. Vous utilisez Claude Code, Cursor ou un autre agent, avec un CLAUDE.md ou un AGENTS.md qui décrit le projet. Trois mois plus tard, la moitié de ses informations sont fausses, et l'agent les applique avec confiance.

Ce qu'on met dans le fichier HCS. Les règles importantes, écrites à la main et reliées au code qui les applique (« les montants sont stockés en centimes », « aucune route admin sans authentification »), plus, si le projet est gros, un fichier compilé pour le reste.

Les commandes. Commencez par auditer votre fichier actuel, sans IA :

$ hcs audit AGENTS.md
AGENTS.md: ~92 tokens, 4 file references, 2 broken, 0 unresolved names
  BROKEN line 5: src/bons.ts
  BROKEN line 6: tests/fidelite.test.ts

Ici, deux fichiers cités par l'AGENTS.md n'existent plus. Ensuite, branchez hcs serve à votre agent. Si vous voulez savoir lequel transmet le plus d'information, hcs compare AGENTS.md project.hcs --model M compare les deux sur les mêmes questions-tests, mais cette comparaison utilise une IA.

Ce qu'on y gagne. Un agent qui ne travaille plus sur des informations périmées, et qui va lire la source exacte quand il a un doute. Pour bien rédiger le fichier d'instructions lui-même, mon générateur de fichier d'instructions pour agent vous aide.

La limite. HCS ne vérifie que ce qui est relié à une source. Une consigne générale sans ancre (« sois concis ») reste à votre charge.

2. L'équipe de développement

La situation. Plusieurs personnes modifient le code. Personne ne pense à mettre la documentation à jour, et l'écart se creuse.

Ce qu'on met dans le fichier HCS. L'architecture, les conventions et les règles métier, avec les ancres vers le code qui les applique.

Les commandes. L'action GitHub en mode check sur la branche principale, et en mode impact sur les pull requests (voir les deux blocs YAML plus haut).

Ce qu'on y gagne. La revue de code montre noir sur blanc quelles affirmations la modification touche. L'auteur corrige l'affirmation, ou confirme qu'elle tient avec --rehash.

La limite. Les pull requests venant d'un fork reçoivent un jeton en lecture seule : le commentaire ne peut pas y être publié. Et l'option --deps, qui signale les affirmations dont le code utilisé a changé, donne surtout de fausses alertes : sur l'historique du projet, seule 1 alerte sur 18 désignait une affirmation réellement devenue fausse.

3. L'agence ou le freelance

La situation. Vous livrez un site ou une application à un client, avec une documentation. Six mois plus tard, un autre prestataire reprend le projet et ne sait pas ce qui est encore vrai.

Ce qu'on met dans le fichier HCS. Le fonctionnement du projet, ses règles et ses engagements (« les commandes ne partent qu'après confirmation »), reliés au code livré.

Les commandes. Livrez le fichier .hcs avec le code, et l'action GitHub si le client a un dépôt. Pour aller plus loin, un certificat de fidélité peut être signé : hcs keygen crée une paire de clés, hcs score … --write --sign signe le certificat, et hcs badge produit un badge pour le README. Ces trois étapes demandent une mesure de fidélité, donc une IA.

Ce qu'on y gagne. Une documentation dont n'importe qui peut vérifier, en une commande, qu'elle correspond encore au code. C'est un vrai argument commercial.

La limite. Le client doit avoir quelqu'un capable de lancer la vérification, ou une intégration continue qui le fait pour lui.

4. La boutique en ligne avec un assistant IA

La situation. Votre boutique utilise un assistant IA pour répondre aux clients, sur le site ou sur WhatsApp. Ses réponses s'appuient sur vos conditions : prix de livraison, délais de retour, codes promo. Le jour où une condition change et que la base de l'assistant n'est pas mise à jour, il annonce un tarif ou un délai faux, et c'est vous qui en payez le prix au moment du refus du colis.

Ce qu'on met dans le fichier HCS. Une affirmation par condition, reliée à la page ou au fichier qui fait foi : la section « Livraison » de vos conditions de vente, la constante du code qui calcule les frais. C'est exactement ce que fait l'exemple « Boutique Atlas » de HCS en direct.

Les commandes. hcs check chaque jour ou à chaque modification, et hcs render --budget N pour produire le texte donné à l'assistant.

Ce qu'on y gagne. Une garantie mécanique : si une condition change, check échoue, et l'affirmation périmée disparaît du texte donné à l'assistant. Je l'ai vérifié plus haut : après le changement de seuil, render ne contient plus que l'affirmation encore vraie. L'assistant ne peut plus annoncer l'ancienne règle comme si de rien n'était.

La limite. HCS ne rédige pas la nouvelle réponse à votre place : il signale l'écart et retire l'information douteuse. Et il faut que vos conditions existent dans un fichier texte (Markdown, code), pas seulement dans une image ou un PDF. Pour l'usage de l'IA en e-commerce plus largement, lisez mon guide sur l'IA au service de votre boutique.

5. Les documents non techniques

La situation. Un règlement intérieur, une procédure qualité, des notes de recherche : des textes longs, souvent résumés pour une IA ou pour un nouvel arrivant, et qui évoluent.

Ce qu'on met dans le fichier HCS. Les points clés, chacun relié à la section qui l'énonce, avec une ancre sur le titre : docs/procedure.md::"Validation des congés". Les titres en arabe fonctionnent aussi comme ancres.

Les commandes. Les mêmes : init, seal, check, render.

Ce qu'on y gagne. Le jour où une section est modifiée, le résumé correspondant est signalé, au lieu de rester faux en silence.

La limite. L'ancre suit la section entière : la moindre retouche dans la section, même une virgule, la marque comme périmée. C'est voulu (mieux vaut relire pour rien que rater un changement), mais il faut le savoir.

6. Le passage de relais entre deux conversations

La situation. Une longue conversation avec une IA a abouti à des décisions. Vous voulez continuer dans une nouvelle conversation, ou avec un autre modèle, sans tout recopier ni rien perdre.

Les commandes. hcs snapshot conversation.json --model M -o session.hcs transforme la conversation (export ChatGPT, tableau de messages, ou simple fichier .md ou .txt) en affirmations reliées chacune au message dont elle vient. Ensuite, hcs render session.hcs --decoder produit le texte à coller dans la nouvelle conversation.

Ce qu'on y gagne. Les décisions, contraintes et prochaines étapes, chacune traçable jusqu'au message d'origine.

La limite. snapshot utilise une IA, et la qualité dépend du modèle. Je ne l'ai pas exécuté pour ce guide.

Quand ne pas l'utiliser, et les limites

• Un petit projet : si le code tient en quelques fichiers, le donner directement à l'IA est plus simple, et parfois plus court que son fichier de contexte.
• Des mesures faites sur des projets en anglais : les gains publiés (46,7 % de bonnes réponses contre 27,8 % pour un résumé classique) viennent de dépôts en anglais. Le fonctionnement en français et en arabe est vérifié, mais pas encore mesuré.
• Un outil expérimental : le format est stable (SPEC 1.0), mais l'outil en est à la version 0.3.
• La détection d'injection est imparfaite : sur des attaques jamais vues pendant son réglage, elle en a repéré environ la moitié. C'est une protection en plus, pas une garantie.
• Les alertes de dépendances (--deps) donnent surtout de fausses alertes.
• HCS ne rend pas un mauvais résumé bon : il dit s'il est encore vrai et mesure ce qu'il transmet. La qualité des affirmations reste votre affaire, ou celle du modèle qui les compile.

FAQ

Faut-il une clé d'API pour utiliser HCS ?

Non, pas pour l'essentiel. Écrire des affirmations à la main, les sceller, les vérifier, produire le contexte, auditer un AGENTS.md et lister l'impact d'une modification fonctionnent sans IA et sans réseau. Seules la création automatique (compile), la mesure (score, curve, compare) et snapshot en demandent une, et elles acceptent les offres gratuites et les modèles locaux.

HCS fonctionne-t-il avec du texte en français ou en arabe ?

Oui. Le format est en UTF-8, et l'empreinte est calculée sur le texte, quelle que soit la langue. J'ai testé des affirmations en français et en arabe, avec des titres Markdown en arabe comme ancres : le changement d'une seule valeur est bien détecté. Les mesures de fidélité publiées, elles, ont été faites sur des projets en anglais.

Mon code est-il envoyé quelque part ?

Pas par check, seal, render, stats, impact, audit sans --probes, ni par le serveur MCP. Les commandes qui utilisent une IA envoient le texte au fournisseur que vous choisissez. L'outil en ligne HCS en direct fonctionne entièrement dans votre navigateur.

Que faire quand une affirmation devient périmée ?

La relire. Si elle est devenue fausse, corrigez son texte. Si elle est toujours vraie (le changement ne la concerne pas), confirmez avec hcs seal fichier.hcs --rehash --ids <id>. Et si le fichier a été compilé, compile --update peut la régénérer.

Par quoi commencer sur un vrai projet ?

Par cinq à dix affirmations écrites à la main, sur les règles qui coûteraient cher si l'IA les oubliait, puis hcs seal et l'action GitHub. Vous verrez vite si l'habitude vous convient, avant de compiler le reste.

Besoin d'aide pour mettre HCS en place dans votre équipe, ou pour fiabiliser un assistant IA ? C'est le cœur de mon service IA et automatisation.