Si vous avez déjà hérité d'une documentation incomplète, incohérente et obsolète, vous connaissez le problème : les équipes créent des documents avec de bonnes intentions, mais sans examen rigoureux, la clarté s'érode. Les paramètres d'API ne sont pas documentés. Les réponses d'erreur manquent de directives. Les exemples se brisent silencieusement. La terminologie dérive d'un fichier à l'autre.
Les compétences de Claude Code résolvent ce problème systématiquement. Ces flux de travail basés sur l'IA examinent l'ensemble de votre référentiel de documentation, identifient les lacunes et les incohérences, et appliquent les corrections directement. Vous décrivez ce qui doit être révisé, et Claude génère un audit structuré, applique des améliorations et valide l'exhaustivité, le tout depuis votre terminal.
La documentation technique couvre les spécifications d'API, les guides d'utilisation, les guides de déploiement et les notes de version. Claude Code automatise la révision de tout cela. Pour la documentation d'API spécifiquement, combinez-le avec Apidog pour la validation visuelle et le calcul du score d'exhaustivité.
Comprendre les Compétences de Claude Code pour la Documentation
Que sont les Compétences de Documentation ?
Les Compétences de Claude Code sont des flux de travail IA personnalisés et réutilisables qui étendent les capacités de documentation de Claude Code. Considérez-les comme des auditeurs de documentation intelligents capables de :
- Lire l'intégralité de votre référentiel de documentation et comprendre le contexte
- Comparer les spécifications avec les implémentations et les guides
- Identifier les sections manquantes, le langage imprécis et les incohérences
- Suggérer des améliorations spécifiques avec les emplacements de fichiers et les numéros de ligne
- Appliquer des corrections directement à vos fichiers et valider les modifications
Contrairement aux linters traditionnels qui vérifient la syntaxe, les compétences utilisent le raisonnement de Claude pour comprendre les problèmes sémantiques : descriptions vagues, documentation d'erreurs manquante, exemples incohérents.
Comment Fonctionnent les Compétences
Les compétences fonctionnent via plusieurs mécanismes :
1. Commandes Invocables par l'Utilisateur
# Exécuter une compétence avec une commande slash
/review-docs --completeness
/check-consistency --terminology
/validate-api-specs
/update-broken-examples
2. Outils Autorisés
Les compétences spécifient les outils qu'elles peuvent utiliser :
Bash: Exécuter des commandes de validationRead,Write,Edit: Gérer les fichiers de documentationGlob,Grep: Rechercher dans les documentsWebFetch: Récupérer des références externesTask: Générer des sous-tâches pour des révisions complexes
3. Fichiers de Planification
Les compétences maintiennent leur état en utilisant des fichiers Markdown pour suivre la progression de la révision, les problèmes identifiés et les corrections appliquées.
Pourquoi les Compétences Excellent dans la Révision de Documentation
La révision traditionnelle de la documentation est manuelle et incohérente. Les compétences apportent intelligence et échelle :
- Compréhension Holistique : Examine tous les fichiers, capture les schémas inter-fichiers
- Normes Cohérentes : Applique les mêmes critères de qualité à chaque fichier
- Suggestions Contextuelles : Comprend pourquoi quelque chose ne va pas, pas seulement que ça ne va pas
- Automatisation : Peut réviser continuellement à mesure que la documentation évolue
- Vitesse : Analyse des centaines de pages en quelques minutes contre des heures de révision manuelle
Capacités Clés de Révision de Documentation
1. Analyse d'Exhaustivité
Invite : "Auditez la documentation de l'API pour son exhaustivité. Vérifiez chaque point de terminaison pour : les paramètres, les exemples de requête, toutes les réponses d'erreur et la limitation de débit."
Claude génère :
Manquant pour le point de terminaison POST /users :
- [ ] Descriptions des paramètres du corps de la requête
- [ ] Documentation des réponses d'erreur (400, 401, 409)
- [ ] Informations sur la limitation de débit
- [ ] Exigences de sécurité/authentification
2. Détection d'Incohérences
Invite : "Révisez /docs/ pour la cohérence terminologique. Signalez tous les termes qui apparaissent plusieurs fois avec des significations différentes."
Claude identifie :Terminologie incohérente trouvée : - "API key" vs "access token" vs "auth token" (utilisez-en un seul) - "endpoint" vs "route" vs "method" (utilisez-en un seul) - "user object" vs "user resource" (utilisez-en un seul)
3. Validation de Références Croisées
Invite : "Comparez la spécification OpenAPI dans /api/openapi.yaml avec la documentation dans /docs/api/. Signalez tous les points de terminaison dans le code non documentés ou documentés mais non présents dans le code."
Claude détecte :
Discrepances trouvées :
- POST /api/webhooks documenté mais pas dans openapi.yaml
- PATCH /api/users existe dans le code mais est manquant dans les docs
- Le schéma de réponse a changé mais l'exemple n'est pas mis à jour
4. Évaluation de la Clarté
Invite : "Révisez pour la clarté. Signalez les descriptions vagues, les termes non définis et les instructions ambiguës."
Claude identifie :
Problèmes de clarté :
- Ligne 45 : "Définir la configuration à des valeurs appropriées" - quelles valeurs ?
- Ligne 120 : "user object" utilisé sans définition de schéma
- Ligne 200 : "champs obligatoires" - lesquels ?
5. Validation d'Exemples
Invite : "Révisez tous les exemples de code. Testez-les par rapport au schéma d'API actuel. Signalez les exemples cassés ou obsolètes."
Claude met à jour :
Exemples mis à jour :
- Exemple curl : Format de réponse modifié, charge utile mise à jour
- Exemple Python : Utilise un paramètre obsolète, corrigé
- Exemple JavaScript : Gestion des erreurs manquante, ajoutée
Anatomie d'une Compétence de Documentation
Structure de Répertoire
Les compétences de documentation vivent dans .claude/skills/ avec cette structure :
.claude/
├── skills/
│ ├── docs-completeness/
│ │ ├── SKILL.md # Manifeste de compétence
│ │ ├── planning.md # Progression de la révision
│ │ └── criteria.md # Liste de contrôle qualité
│ ├── api-validation/
│ │ ├── SKILL.md
│ │ └── schemas/ # Schémas API
│ └── consistency-check/
│ └── SKILL.md
└── skills.md # Index de toutes les compétences
Le Manifeste SKILL.md
Chaque compétence de documentation commence par un frontmatter YAML :
---
name: docs-completeness
version: "1.0.0"
description: Révise la documentation pour son exhaustivité et sa clarté
user-invocable: true
allowed-tools:
- Read
- Write
- Grep
- Glob
- Edit
hooks:
SessionStart:
- matcher: command
command: "echo '[Revue de Docs] Démarrage de l\'audit de documentation...'"
Stop:
- matcher: command
command: "echo '[Revue de Docs] Audit terminé. Examinez les résultats ci-dessus.'"
---
# Compétence d'Exhaustivité de Documentation
Révise la documentation technique pour son exhaustivité et sa clarté.
## Utilisation
```bash
/docs-completeness # Audit complet du référentiel
/docs-completeness --api-only # Docs API seulement
/docs-completeness --section api/endpoints.md # Fichier spécifique
Instructions pour Claude
Lorsqu'invoqué :
- Détection de la portée → Déterminer les fichiers cibles ou le référentiel complet
- Analyse d'exhaustivité → Vérifier chaque section par rapport à la liste de contrôle
- Collecte des problèmes → Rassembler tous les problèmes avec leurs emplacements
- Priorisation → Trier par impact (manquant vs. peu clair vs. incohérent)
- Génération de rapport → Produire des résultats structurés
- Suggestions de corrections → Proposer des améliorations spécifiques
- Validation → Vérifier les corrections avant de les appliquer
Concevoir Votre Première Compétence de Documentation
Passez à la pratique : Nous allons construire un outil pratique pour auditer la documentation d'API à la recherche de lacunes, en nous assurant qu'elle est complète et prête pour les développeurs. Considérez-le comme votre gendarme personnel de la documentation.
Étape 1 : Mettre en Place le Dossier de Compétences
Initialisez la structure avec une commande simple, les compétences de Claude résident dans un endroit dédié pour une découverte facile.
Bash
mkdir -p .claude/skills/api-docs-reviewÉtape 2 : Écrire le Manifeste de Compétence
Créez .claude/skills/api-docs-review/SKILL.md :
---
name: api-docs-review
version: "1.0.0"
description: Révise la documentation de l'API pour son exhaustivité
user-invocable: true
allowed-tools:
- Read
- Write
- Grep
- Edit
---
# Compétence de Révision de Documentation d'API
Audite la documentation d'API pour son exhaustivité, sa clarté et sa précision.
## Critères de Révision
Chaque point de terminaison doit avoir :
**Informations de Base**
* Description claire de ce que fait le point de terminaison
* Méthode HTTP et chemin
* Exigences d'authentification
**Documentation de la Requête**
* Tous les paramètres de chemin avec types et descriptions
* Tous les paramètres de requête avec valeurs par défaut et contraintes
* Schéma du corps de la requête (pour POST/PUT/PATCH)
* Exigences d'en-tête Content-Type
* Exemple de requête (curl ou spécifique à un langage)
**Documentation de la Réponse**
* Réponse de succès (200/201) avec schéma et exemple
* Toutes les réponses d'erreur (400, 401, 403, 404, 409, 429, 500) avec exemples
* Informations sur la limitation de débit
* En-têtes de réponse (si pertinents)
**Supplémentaire**
* Points de terminaison ou guides associés
* Historique des versions si applicable
* Avertissements d'obsolescence (si obsolète)
## Instructions
Lorsqu'invoqué :
1. **Scanner les fichiers de point de terminaison** dans /docs/api/
2. **Vérifier chaque point de terminaison** par rapport aux critères de révision
3. **Enregistrer les éléments manquants** avec des références spécifiques de fichier/ligne
4. **Identifier les problèmes de clarté** (descriptions vagues, termes non définis)
5. **Signaler les problèmes de cohérence** (dérive terminologique, différences de format)
6. **Générer une liste de contrôle** des corrections nécessaires
7. **Proposer d'appliquer les corrections** avec des exemples
Format du rapport :
POINT DE TERMINAISON : POST /api/users Fichier : docs/api/users.md Statut : 65 % Complet
Manquant :
- [ ] Documentation des réponses d'erreur (400, 401, 409)
- [ ] Informations sur la limitation de débit
- [ ] Définition du schéma du corps de la requête
Problèmes :
- Ligne 45 : "objet utilisateur" non défini - ajouter un lien vers le schéma
- Ligne 60 : Exemple obsolète - le format de réponse a changé
Corrections disponibles : Oui (demander à appliquer)
Étape 3 : Enregistrer la Compétence
Ajoutez à .claude/skills.md :
# Compétences de Documentation Disponibles
## Documentation d'API
### /api-docs-review
Auditer la documentation d'API pour son exhaustivité par rapport aux critères standard.
- **Version** : 1.0.0
- **Utilisation** : `/api-docs-review [--file CHEMIN] [--endpoint NOM]`
- **Quand l'utiliser** : Avant la publication de l'API, après des modifications de code
- **Temps** : 5-10 minutes pour une API de taille moyenne
Étape 4 : Tester la Compétence
# Dans Claude Code
/api-docs-review
Claude va maintenant auditer votre documentation d'API systématiquement.
Modèles de Documentation Avancés
Modèle 1 : Suivi de la Documentation Versionnée
Les compétences peuvent suivre la qualité de la documentation à travers les versions :
## Historique des Versions
### v2.0.0 [2026-01-22]
Exhaustivité : 95% ✅
- Tous les points de terminaison documentés
- Réponses d'erreur complètes
- Exemples mis à jour
- Les points de terminaison /v1 obsolètes sont marqués
### v1.0.0 [2025-12-01]
Exhaustivité : 70%
- Documentation d'erreurs manquante
- Exemples obsolètes
- Pas d'avertissements d'obsolescence
Claude détecte les améliorations au fil du temps.
Modèle 2 : Validation des Spécifications d'API par Rapport au Code
Les compétences peuvent valider que les spécifications OpenAPI correspondent à l'implémentation :
## Validation des Spécifications
Comparer /api/openapi.yaml par rapport au code :
1. **Scanner l'implémentation** pour toutes les routes
2. **Vérifier la spécification OpenAPI** pour chaque route
3. **Signaler les points de terminaison manquants**
4. **Vérifier que les paramètres** correspondent à l'implémentation
5. **Mettre à jour les exemples** pour correspondre au schéma actuel
Résultat : Spécification 100% synchronisée avec le code
Automatisation avec CI/CD
Pipeline de Validation de Documentation
Mettez en place des vérifications automatisées à chaque mise à jour de la documentation :
# .github/workflows/docs-check.yml
name: Vérification de la Documentation
on:
push:
paths:
- 'docs/**'
- 'api/openapi.yaml'
pull_request:
paths:
- 'docs/**'
- 'api/openapi.yaml'
jobs:
validate-docs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'npm'
- name: Installer Apidog CLI
run: npm install -g apidog-cli
- name: Valider les Spécifications OpenAPI
run: |
apidog lint api/openapi.yaml
apidog check-completeness api/openapi.yaml --min-score 85
- name: Vérifier les liens cassés
run: |
npm install -g markdown-link-check
find docs -name "*.md" -exec markdown-link-check {} \;
- name: Vérifier que les exemples sont valides
run: |
# Tester si les exemples curl fonctionnent
bash scripts/test-curl-examples.sh
- name: Commenter la PR
if: failure()
uses: actions/github-script@v7
with:
script: |
github.rest.issues.createComment({
issue_number: context.issue.number,
owner: context.repo.owner,
repo: context.repo.repo,
body: '❌ La validation de la documentation a échoué. Vérifiez les logs du workflow.'
})
Scénario Réel : Exhaustivité de la Documentation d'API
Auditions un ensemble de documentation d'API réaliste pour son exhaustivité et appliquons des améliorations.
Le Scénario
Vous avez une documentation d'API REST datant de 6 mois. Elle est partiellement complète mais manque de documentation d'erreurs, est peu claire par endroits et contient des exemples obsolètes.
L'Audit
Invite à Claude : "Auditez la documentation dans /docs/api/. Pour chaque point de terminaison, vérifiez : description, paramètres de requête, exemple de réponse et toutes les réponses d'erreur. Priorisez les corrections par impact."
RÉSULTATS DE L'AUDIT
=============
CRITIQUE (Documentation d'erreurs manquante) :
├── POST /api/users - Réponses d'erreur 400, 401, 409 manquantes
├── POST /api/auth/login - Réponse 429 (limite de débit) manquante
└── DELETE /api/resources/{id} - Réponse 403 (interdit) manquante
ÉLEVÉ (Problèmes de clarté) :
├── users.md:45 - "objet utilisateur" non défini
├── auth.md:60 - "Définir l'expiration à une valeur appropriée" - trop vague
└── resources.md:30 - Description manquante du format du curseur de pagination
MOYEN (Exemples obsolètes) :
├── products.md:120 - Exemple cURL renvoie un ancien format
├── orders.md:80 - L'exemple du SDK Python utilise un paramètre obsolète
└── webhooks.md:60 - L'exemple Node.js manque de gestion des erreurs
COHÉRENCE :
├── "API key" vs "access token" - 5 instances incohérentes
├── Format du corps de la requête - 3 styles différents sur les points de terminaison
└── Schéma de réponse d'erreur - 2 variations au lieu de 1
Corrections prioritaires : 15 au total
Effort estimé : 2-3 heures manuelles, 15 minutes avec Claude Code
Les Améliorations
Application systématique des corrections :
Avant - POST /api/users (Incomplet) :
## Créer un Utilisateur
POST /api/users
Crée un nouvel utilisateur.
**Paramètres :**
- name : Nom de l'utilisateur
- email : Email de l'utilisateur
**Réponse :**
```json
{
"id": "usr_123",
"name": "Alice",
"email": "alice@example.com"
}
**Après - POST /api/users (Complet) :**
```markdown
## Créer un Utilisateur
`POST /api/users`
Crée un nouveau compte utilisateur avec les détails fournis. L'e-mail doit être unique.
### Authentification
Nécessite une clé API dans l'en-tête `Authorization` : `Bearer VOTRE_CLE_API`
### Paramètres de Requête
| Paramètre | Type | Obligatoire | Description |
|-----------|------|-------------|-------------|
| `name` | string | Oui | Nom complet (2-100 caractères) |
| `email` | string | Oui | E-mail valide (doit être unique) |
| `role` | string | Non | Rôle : `admin`, `developer`, `viewer`. Par défaut : `viewer` |
### Exemple de Requête
```bash
curl -X POST https://api.example.com/v1/users \
-H "Authorization: Bearer sk_live_abc123" \
-H "Content-Type: application/json" \
-d '{
"name": "Alice Smith",
"email": "alice@example.com",
"role": "developer"
}'
Réponse (201 Créé)
{
"id": "usr_abc123",
"name": "Alice Smith",
"email": "alice@example.com",
"role": "developer",
"created_at": "2026-01-22T10:30:00Z"
}
Réponses d'Erreur
400 Mauvaise Requête - Entrée invalide
{
"error": "validation_error",
"message": "Format d'e-mail invalide",
"field": "email",
"request_id": "req_xyz789"
}
401 Non Autorisé - Clé API manquante/invalide
{
"error": "unauthorized",
"message": "Clé API invalide",
"request_id": "req_xyz789"
}
409 Conflit - L'e-mail existe déjà
{
"error": "conflict",
"message": "Un utilisateur avec cet e-mail existe déjà",
"request_id": "req_xyz789"
}
429 Trop de Requêtes - Limite de débit atteinte
{
"error": "rate_limited",
"message": "Trop de requêtes. Réessayez dans 60 secondes.",
"retry_after": 60,
"request_id": "req_xyz789"
}
Limitation de Débit
100 requêtes par minute par clé API. Voir Limites de Débit.
**Améliorations appliquées :**
- Ajout des exigences d'authentification
- Documentation de tous les paramètres avec contraintes
- Réponse de succès complète + toutes les réponses d'erreur
- Exemple cURL prêt pour la production
- Informations sur la limitation de débit
- Formatage cohérent
Intégrer Claude avec Apidog pour une Documentation d'API Supérieure
💡 Conseil de Pro : Tirez parti de Claude pour des revues perspicaces de documents narratifs, tandis qu'Apidog assure la solidité de vos spécifications d'API et comble automatiquement les lacunes avec des exemples pratiques.
Invite suggérée pour Claude :"Examinez /docs/api/ pour la clarté et l'engagement global. Ensuite, vérifiez l'exhaustivité du fichier /api/openapi.yaml en utilisant Apidog. Mettez en évidence les incohérences ou les éléments manquants, afin que je puisse les résoudre directement dans Apidog avant de continuer."
Bash
# Étape 1 : Revue Initiale du Texte via Claude
> /docs-completeness # Génère des suggestions pour un langage et une structure plus clairs
# Étape 2 : Validation des Spécifications d'API dans Apidog
apidog check-completeness api/openapi.yaml # Signale les problèmes comme des schémas incomplets ou des réponses manquantes
# Étape 3 : Génération Automatique de Contenu avec l'IA d'Apidog
# (Via l'interface utilisateur d'Apidog : Paramètres → IA → Générer automatiquement descriptions, exemples et résumés)
# Étape 4 : Vérification Finale d'Harmonie avec Claude
> /consistency-check # S'assure que les documents et les spécifications sont parfaitement alignésCela crée un flux de travail où Apidog gère la validation structurée des spécifications et Claude Code gère la qualité du texte.
Meilleures Pratiques pour la Révision de Documentation
Connaissez Votre Public
Adaptez la profondeur de la documentation aux lecteurs :
| Public | Style | Exemple |
|---|---|---|
| Développeurs | Exemples de code dans plusieurs langages | cURL, Python, JS |
| DevOps | Étapes de déploiement, configuration | Exemples YAML Kubernetes |
| Équipes Produit | Flux de travail de haut niveau, diagrammes | Flux de fonctionnalités avec captures d'écran |
| Support | Dépannage, problèmes courants | "L'erreur 429 signifie..." |
Priorisez la Clarté
Écrivez à la voix active, structurez pour un balayage rapide :
❌ Avant : "La requête est soumise via POST. La réponse contiendra l'utilisateur."
✅ Après : "Soumettez une requête POST pour créer un utilisateur. L'API retourne le nouvel utilisateur."
Incluez Toujours des Exemples
Les concepts abstraits ont besoin d'ancrage. Chaque point de terminaison d'API nécessite :
# ✅ Prêt à copier-coller
curl -X GET https://api.example.com/v1/users/usr_123 \
-H "Authorization: Bearer VOTRE_CLE_API"
Pièges Courants
| Piège | Solution |
|---|---|
| Surcharge de jargon | Définir les termes à la première utilisation |
| Exemples obsolètes | Tester en CI/CD |
| Documentation d'erreurs manquante | Documenter tous les codes d'erreur |
| Formatage incohérent | Utiliser des modèles |
| Liens cassés | Vérifier en CI/CD |
Conclusion
Les Compétences de Claude Code transforment la révision de documentation technique d'un processus manuel fastidieux en un flux de travail intelligent et automatisé. Vous décrivez ce qui doit être révisé, et Claude audite l'ensemble de votre référentiel de documentation, identifie les lacunes et les incohérences, et applique les corrections, tout en maintenant les normes de qualité.
Combiné avec Apidog pour la validation des spécifications d'API, vous obtenez une couverture complète de la documentation.