Skill Claude HADS

Version 1.0.0 · Human-AI Document Standard · 2026 · HADS 1.0.0

AI READING INSTRUCTION

Ce skill enseigne à Claude comment lire, générer et valider les documents HADS. Lisez tous les blocs [SPEC] avant de répondre à toute demande liée à HADS. Lisez les blocs [NOTE] si vous avez besoin de contexte sur l'intention ou les cas limites.

1. QU'EST-CE QUE HADS

[SPEC]

• HADS = Human-AI Document Standard
• Convention pour la documentation technique en Markdown
• Quatre types de blocs : **[SPEC]**, **[NOTE]**, **[BUG]**, **[?]**
• Tout document HADS requiert : titre H1, déclaration de version, manifeste IA
• Le manifeste IA apparaît avant la première section de contenu, indique à l'IA quoi lire/sauter
• Extension de fichier : .md — Markdown standard, aucun outil requis

2. TYPES DE BLOCS

[SPEC]

**[SPEC]**   Fait autorisé. Concis. Listes à puces, tableaux, code. L'IA lit toujours.
**[NOTE]**   Contexte humain, historique, exemples. L'IA peut sauter.
**[BUG]**    Défaillance vérifiée + correction. Champs requis : symptôme, cause, correction. À lire toujours.
**[?]**      Non vérifié / déduit. Confiance plus faible. Toujours signalé.

Règles des balises de bloc :

• Gras, sur sa propre ligne : **[SPEC]**
• Le contenu suit immédiatement (pas de ligne vide entre la balise et le contenu)
• Plusieurs blocs de types différents autorisés par section
• Blocs BUG titrés autorisés : **[BUG] Description courte**
• Pas d'imbrication de blocs dans des blocs

3. STRUCTURE REQUISE DU DOCUMENT

[SPEC]

# Titre du Document
**Version X.Y.Z** · Auteur · Date · [métadonnées]

---

## AI READING INSTRUCTION

Lisez les blocs `[SPEC]` et `[BUG]` pour les faits autorisés.
Lisez `[NOTE]` uniquement si un contexte supplémentaire est nécessaire.
Les blocs `[?]` ne sont pas vérifiés — traitez avec une confiance plus faible.

---

## 1. Première section

**[SPEC]**
...

Éléments requis dans l'ordre :

1. Titre H1
2. **Version X.Y.Z** dans l'en-tête (20 premières lignes)
3. Section manifeste IA avant la première section de contenu
4. Sections de contenu (H2), sous-sections (H3)

4. COMMENT CLAUDE LIT HADS

[SPEC] Quand vous rencontrez un document HADS :

1. Trouvez et lisez le manifeste IA en premier
2. Lisez tous les blocs [SPEC] — c'est la vérité de référence
3. Lisez tous les blocs [BUG] — toujours, avant de générer du code ou de la config
4. Lisez les blocs [NOTE] uniquement si [SPEC] est insuffisant pour répondre à la requête
5. Traitez le contenu [?] comme une hypothèse — notez l'incertitude dans la réponse

Optimisation des tokens : pour les grands documents, scannez d'abord les en-têtes de section, puis lisez uniquement les blocs [SPEC] et [BUG] dans les sections pertinentes.

5. COMMENT CLAUDE GÉNÈRE HADS

[SPEC] Quand on vous demande d'écrire de la documentation au format HADS :

1. Commencez par le bloc d'en-tête (titre, version, métadonnées)
2. Ajoutez le manifeste IA — incluez toujours, ne sautez jamais
3. Organisez le contenu en sections H2 numérotées
4. Pour chaque fait : écrivez comme [SPEC] — concis, à puces ou tableau ou code
5. Pour chaque « pourquoi » ou contexte : écrivez comme [NOTE]
6. Pour chaque mode de défaillance connu avec correction confirmée : écrivez comme [BUG]
7. Pour chaque affirmation non vérifiée : écrivez comme [?]
8. Terminez par une section changelog

Règles de contenu pour [SPEC] :

• Privilégiez les listes à puces par rapport à la prose
• Privilégiez les tableaux pour les faits multi-champs
• Privilégiez les blocs de code pour la syntaxe, les formats, les exemples
• Maximum 2 phrases de prose — si plus nécessaire, déplacez vers [NOTE]

Règles de contenu pour [BUG] :

• Toujours inclure : symptôme, cause, correction
• Optionnel : versions affectées, contournement
• Titre sur la même ligne : **[BUG] Description courte**

[NOTE] Lors de la conversion de documentation existante en HADS : extrayez les faits dans [SPEC], déplacez le narratif et l'historique vers [NOTE], mettez en avant tous les problèmes connus comme [BUG]. Ne dupliquez pas le contenu entre les types de bloc.

6. RÈGLES DE VALIDATION

[SPEC] Un document HADS valide doit avoir :

• Titre H1
• **Version X.Y.Z** dans les 20 premières lignes
• Manifeste IA avant la première section de contenu
• Toutes les balises de bloc en gras : **[SPEC]** pas [SPEC] pas [SPEC]
• Les blocs [BUG] contiennent au minimum symptôme + correction

Validateur : (prévu — pas encore inclus dans cette version)

7. EXEMPLES D'INTERACTIONS

[SPEC]

Utilisateur : « Écrivez la documentation HADS pour cette API REST » → Générez un document HADS complet : en-tête, manifeste, sections avec blocs [SPEC]/[NOTE]/[BUG]

Utilisateur : « Convertissez ce README au format HADS » → Restructurez le contenu existant en blocs HADS, préservez tous les faits, ajoutez le manifeste

Utilisateur : « Ce document est-il un HADS valide ? » → Vérifiez : titre H1, version, manifeste, formatage des balises de bloc, complétude du bloc BUG

Utilisateur : « Résumez ce document HADS » → Lisez uniquement les blocs [SPEC] et [BUG], retournez un résumé structuré

Utilisateur : « Que fait cette API ? » (document HADS fourni) → Lisez le manifeste, lisez les blocs [SPEC] dans les sections pertinentes, répondez directement

8. INTENTION DE CONCEPTION

[NOTE] HADS existe parce que les modèles IA lisent de plus en plus la documentation avant les humains. Le format optimise cette réalité sans sacrifier la lisibilité humaine.

Insight clé : le manifeste IA est l'innovation centrale. Il permet même aux petits modèles (7B) de savoir quoi lire et quoi sauter — sans les obliger à raisonner sur la structure du document. L'explicite est meilleur que l'implicite pour la consommation par les modèles.

Lors de la génération de HADS, pensez à [SPEC] comme la surface API et à [NOTE] comme les commentaires. Les blocs [BUG] sont le contenu le plus précieux — ils représentent des connaissances durement acquises qui épargnent aux autres de heurter le même mur.

9. RÉFÉRENCE RAPIDE

[SPEC]

Balise    | Format gras    | Lecteur | Contenu requis
----------|----------------|---------|------------------
[SPEC]    | **[SPEC]**     | IA      | Faits, concis
[NOTE]    | **[NOTE]**     | Humain  | Contexte, narratif
[BUG]     | **[BUG] ...**  | Les deux| Symptôme + correction
[?]       | **[?]**        | Les deux| Affirmations non vérifiées

Manifeste minimum :

## AI READING INSTRUCTION
Lisez les blocs `[SPEC]` et `[BUG]` pour les faits autorisés.
Lisez `[NOTE]` uniquement si un contexte supplémentaire est nécessaire.
Les blocs `[?]` ne sont pas vérifiés.