IA et documentation technique : les cas d'usage qui marchent vraiment

Je construis crmcoaching seul : un CRM SaaS pour coachs professionnels, avec une quarantaine de use cases répartis en une dizaine de bounded contexts (lead, client, offre, mentoring, calendar, notification, audit...). La base de code grossit vite. Sans documentation, je perds du temps à me réorienter dans mon propre code entre deux sessions. J'ai donc intégré Claude directement dans mon workflow de documentation : READMEs de bounded contexts, docstrings sur les use cases NestJS, résumés de PR, ADRs. Le gain est réel, et les limites le sont aussi.

Claude Code génère les READMEs des modules en quelques minutes. La révision humaine prend 15 à 30 minutes par bounded context. L'onboarding dans une partie du code que je n'ai pas touchée depuis trois semaines passe de 45 minutes de relecture à 10 minutes avec un README à jour.

L'IA peut automatiser 60% de la documentation technique. Mais pas les 60% auxquels on pense en premier. Ceux qui espèrent que l'IA va écrire leurs ADRs et leur documentation d'architecture sont déçus. Ceux qui l'utilisent pour les bons cas d'usage gagnent des heures par semaine.

Ce que l'IA documente bien, et ce qu'elle documente mal

Après plusieurs mois à documenter crmcoaching avec Claude, une règle simple s'est dégagée :

L'IA documente bien le "quoi" : ce que le code fait, comment appeler un endpoint, quels paramètres un use case accepte, quelle est la structure d'un DTO. Ces informations sont dans le code, Claude les extrait et les formate.

L'IA documente mal le "pourquoi" : pourquoi ce découpage hexagonal, pourquoi ce timeout, pourquoi cette contrainte métier sur le slot-hold. Ces informations ne sont pas dans le code, elles sont dans ma tête au moment où j'ai pris la décision.

La règle d'usage : utiliser Claude pour documenter le "quoi" ; investir le temps humain sur le "pourquoi".

Cas d'usage 1 : Génération de documentation d'API (ROI élevé)

Le problème : les controllers NestJS ne sont souvent pas documentés. Chaque fois que je reprends un bounded context après quelques semaines, je perds du temps à relire les endpoints, les paramètres et les formats de réponse.

Ce que Claude fait : à partir du code d'un controller NestJS et de ses DTOs Zod/class-validator, Claude génère une documentation structurée (Markdown ou OpenAPI) avec les endpoints, les paramètres, les types, et des exemples de requête/réponse.

Prompt pour Claude :

Voici le controller NestJS du module "mentoring" et les DTOs associés.
Génère une documentation OpenAPI complète avec description de chaque endpoint,
paramètres, types de retour, et exemples de requête/réponse.
Mentionne les guards d'authentification et les scopes de permission quand ils
sont présents dans les décorateurs.

[coller le code du controller + DTOs]

Avec NestJS, les décorateurs @ApiProperty() (Swagger) et les schémas Zod servent de source de vérité pour la génération : Claude les lit et produit une doc cohérente avec le contrat de l'API réelle. Résultat typique : une documentation utilisable en 5 minutes de génération + 15 minutes de révision pour vérifier l'exactitude et ajouter le contexte métier (quel flux business appelle cet endpoint, quelles sont les contraintes de rate limiting).

Gain : 3 à 4 heures de documentation manuelle ramenées à 20 minutes.

Cas d'usage 2 : Commentaires et docstrings dans le code (ROI moyen)

Le problème : le code existant n'a pas de commentaires. Les use cases complexes sont difficiles à comprendre sans connaître le contexte de leur création.

Ce que Claude fait : il génère des docstrings TSDoc pour les classes et méthodes existantes en TypeScript.

// Avant
@Injectable()
export class CreateSlotHoldUseCase {
  constructor(
    private readonly slotHoldRepository: ISlotHoldRepository,
    private readonly offerRepository: IOfferRepository,
  ) {}

  async execute(command: CreateSlotHoldCommand): Promise<SlotHold> {
    const offer = await this.offerRepository.findById(command.offerId);
    if (!offer) throw new OfferNotFoundException(command.offerId);
    if (offer.userId !== command.userId)
      throw new UnauthorizedSlotHoldException();
    return this.slotHoldRepository.create({
      offerId: command.offerId,
      userId: command.userId,
      expiresAt: new Date(Date.now() + 15 * 60 * 1000),
    });
  }
}

// Après génération par Claude
/**
 * Use case : réserver temporairement un slot d'offre pour un utilisateur.
 *
 * Vérifie que l'offre existe et appartient bien à l'utilisateur demandeur,
 * puis crée un slot-hold avec une expiration de 15 minutes.
 * Ce hold est libéré automatiquement si le paiement n'aboutit pas.
 *
 * @throws {OfferNotFoundException} si l'offre n'existe pas en base
 * @throws {UnauthorizedSlotHoldException} si l'offre appartient à un autre userId
 */
@Injectable()
export class CreateSlotHoldUseCase {
  constructor(
    private readonly slotHoldRepository: ISlotHoldRepository,
    private readonly offerRepository: IOfferRepository,
  ) {}

  /**
   * Exécute la réservation temporaire du slot.
   *
   * @param command - Commande contenant `offerId` et `userId`
   * @returns Le slot-hold créé avec sa date d'expiration
   */
  async execute(command: CreateSlotHoldCommand): Promise<SlotHold> {
    const offer = await this.offerRepository.findById(command.offerId);
    if (!offer) throw new OfferNotFoundException(command.offerId);
    if (offer.userId !== command.userId)
      throw new UnauthorizedSlotHoldException();
    return this.slotHoldRepository.create({
      offerId: command.offerId,
      userId: command.userId,
      expiresAt: new Date(Date.now() + 15 * 60 * 1000),
    });
  }
}

Limite importante : Claude génère des docstrings corrects sur la forme, mais peut se tromper sur la sémantique métier. Toujours réviser pour vérifier que la description correspond au comportement réel. La génération réduit le temps d'écriture de 80%, elle ne remplace pas la révision humaine. Voir comment intégrer l'IA dans la code review pour un workflow cohérent.

Cas d'usage 3 : README de bounded context et onboarding (ROI élevé)

Le problème : chaque bounded context d'un système hexagonal devrait avoir un README qui explique son rôle, ses use cases exposés, ses ports, et comment le tester. En pratique, ces READMEs sont absents ou obsolètes dès la deuxième itération.

Ce que Claude fait : à partir du code source (structure de dossiers, index de use cases, ports et adapters), Claude Code génère un README structuré.

Prompt type :

Voici la structure du bounded context "mentoring" de mon API NestJS hexagonale :
- les fichiers de domain/ (entités, value objects, ports)
- les fichiers d'application/ (use cases)
- le module NestJS racine

Génère un README.md complet incluant :
- Rôle du bounded context et responsabilité métier
- Liste des use cases exposés avec leur commande/query d'entrée
- Ports principaux (interfaces repository, services externes)
- Variables d'environnement spécifiques à ce contexte
- Comment lancer les tests unitaires et d'intégration de ce module

Ce que j'ajoute manuellement : les décisions d'architecture propres au contexte (pourquoi ce bounded context est isolé, quelles contraintes de données sont imposées par le métier), les dépendances avec les autres contextes (ex : mentoring dépend de slot-hold via un port explicite).

Gain pour la reprise de contexte : avec des READMEs à jour, reprendre un bounded context non touché depuis 3 semaines prend 10 minutes au lieu de 45.

Cas d'usage 4 : Résumés de PR et commit messages (ROI élevé)

Le problème : les commit messages et descriptions de PR sont soit vides ("fix bug", "update"), soit trop longs pour être lus. L'historique git devient inutilisable comme journal de bord du projet.

Ce que Claude fait : à partir du diff d'une PR, Claude génère un résumé structuré (ce qui a changé, pourquoi, les impacts potentiels, le plan de test).

Un script pre-commit qui appelle l'API Claude avec le diff en cours :

# Script pre-commit simplifié (hooks/prepare-commit-msg)
#!/bin/bash
DIFF=$(git diff --cached)
if [ -z "$DIFF" ]; then
  exit 0
fi
SUGGESTION=$(echo "$DIFF" | claude -p "Génère un commit message Conventional Commits
en anglais pour ce diff. Format : type(scope): description courte.
Types valides : feat / fix / refactor / test / docs / chore.
Réponds uniquement avec le message, sans explication.")
echo "# Suggestion Claude : $SUGGESTION" >> "$1"

Bénéfice secondaire : des descriptions de PR de qualité améliorent le processus de relecture, le reviewer comprend rapidement l'intention du changement avant de lire le code.

Cas d'usage 5 : Mise à jour de documentation existante (ROI moyen)

Le problème : la documentation existante se désynchronise du code. Un endpoint change, la documentation ne change pas. On suit la doc et on se retrouve avec des erreurs incompréhensibles.

Ce que Claude fait : comparer la documentation existante avec le code actuel et identifier les divergences.

Prompt type :

Voici la documentation actuelle de l'endpoint POST /mentoring/checkout-intent :
[documentation]

Voici le code actuel du controller et du use case correspondant :
[code]

Identifie les divergences entre la documentation et le code, et propose
une documentation mise à jour.

Limite : Claude identifie les divergences techniques (paramètres manquants, types incorrects) mais pas les divergences de logique métier. La révision humaine reste nécessaire.

Ce que l'IA ne peut pas documenter

Décisions d'architecture : pourquoi l'architecture hexagonale plutôt que MVC classique, pourquoi PostgreSQL avec Prisma plutôt qu'un ORM plus léger, pourquoi ce découpage en bounded contexts. Ces décisions ont un contexte (contraintes techniques, état du projet, urgence du moment) que Claude ne peut pas reconstruire. Les ADRs restent un exercice humain.

Contraintes non-exprimées dans le code : un timeout à 3 secondes dans une config qui existe parce qu'un service tiers SLA garantit 99% de réponses en moins de 2,5 secondes. Sans commentaire humain, Claude ne peut pas savoir que cette valeur ne doit pas changer.

Le "pourquoi ça ne marche pas" : les runbooks de debugging, les solutions aux problèmes connus, les workarounds pour les bugs connus des dépendances. Ces informations viennent de l'expérience terrain, pas du code.

Comment intégrer Claude dans le workflow de documentation

Option A : Documentation as part of PR : ajouter à la Definition of Done que toute nouvelle API ou bounded context doit avoir sa documentation générée par Claude et révisée par l'auteur. La doc est vérifiée en même temps que le code.

Option B : Session de documentation dédiée : une fois par mois, une session de 2 à 3 heures consacrée à la mise à jour de la documentation avec Claude. On génère, on révise, on merge.

Option C : Automatisation continue : un pipeline CI qui génère automatiquement la documentation OpenAPI à partir des décorateurs NestJS (Swagger module) et la déploie dans un portail de documentation. La doc est toujours synchronisée avec le code.

La séquence que je recommande : commencer par les READMEs des bounded contexts critiques (impact reprise de contexte immédiat), puis la documentation des endpoints internes (impact developer experience), puis les résumés de PR (impact qualité de l'historique git).

FAQ sur l'IA et la documentation technique