La meilleure explication de votre code est enfouie dans un journal de chat

Vous avez passé quarante-cinq minutes avec Claude à concevoir un circuit de réessai. Vous avez expliqué les modes de défaillance, rejeté le backoff exponentiel parce qu’il masque la pression en cascade, décidé d’un rate limiting de type token bucket avec jitter, et généré une implémentation fonctionnelle. L’explication était claire, le raisonnement était solide, et le code a réellement passé les tests.

Puis vous avez fermé l’onglet.

Deux semaines plus tard, un collègue demande pourquoi la logique de réessai utilise du jitter au lieu d’un backoff exponentiel. Vous ouvrez une nouvelle session Claude et reconstruisez l’argument de mémoire. La nouvelle explication est proche, mais pas identique. Vous avez créé une deuxième tradition orale légèrement différente. Aucune n’est trouvable par recherche. Aucune n’est révisable dans une pull request. Les deux disparaîtront quand vous quitterez l’entreprise.

Ce n’est pas un problème d’outillage. C’est une erreur de catégorie. Nous traitons les conversations avec les LLM comme des brouillons privés alors qu’elles sont en fait ce qui se rapproche le plus de la programmation littéraire que la plupart des ingénieurs aient jamais connu.

Ce que Knuth voulait dire, et pourquoi les LLM l’ont accidentellement réalisé

Donald Knuth a défini la programmation littéraire en 1984 comme l’acte d’écrire des programmes comme des œuvres littéraires. Le code et la documentation sont tissés ensemble dans une seule narration. Le lecteur suit le raisonnement de l’auteur, voit les alternatives envisagées, et comprend pourquoi la forme finale existe.

Pendant quarante ans, la programmation littéraire est restée une pratique de niche. Des outils comme WEB et CWEB exigeaient de la discipline. La plupart des développeurs écrivaient le code dans un fichier et la documentation dans un autre, et les deux dérivaient immédiatement.

Une conversation avec un LLM est de la programmation littéraire par accident. Vous énoncez le problème en prose. Le modèle pose des questions clarificatrices. Vous affinez les contraintes. Il propose du code. Vous rejetez la proposition et expliquez pourquoi. Il révise. L’artefact final n’est pas seulement le bloc de code. C’est tout le fil : les approches écartées, les trade-offs, les hypothèses métier.

Le problème est que le médium est éphémère. Les interfaces de chat sont conçues pour l’achèvement de tâches, pas pour la préservation des connaissances. Une fois la session terminée, la narration est figée dans l’ambre, non consultable, non versionnée, et propriété d’un fournisseur.

Pourquoi les journaux de chat battent la documentation traditionnelle pour les décisions complexes

La documentation traditionnelle décrit l’état final. Elle répond à “quoi.” Un bon journal de chat répond à “pourquoi,” qui est la question la plus difficile et celle qui se dégrade le plus vite.

Considérez un registre de décision d’architecture typique. Il pourrait dire : “Nous avons choisi PostgreSQL plutôt que DynamoDB pour le service d’inventaire à cause des exigences de cohérence forte.” C’est une conclusion. Il ne vous dit rien sur les requêtes qui étaient trop lentes, le décalage de réplication qui était acceptable, ou le verrouillage fournisseur qui a été débattu et écarté.

Un fil Claude contient tout cela. Il contient les itérations de schéma qui ont échoué, les plans de requête qui vous ont surpris, et le moment où vous avez réalisé que l’index composite devait couvrir le filtre de statut. C’est un registre de décision avec le contexte complet.

L’obstacle est que le contexte est piégé dans un format conversationnel. Faire défiler un fil de cent tours pour trouver la seule idée sur la conception d’index est pénible. Le savoir est là, mais il n’est pas accessible.

Les trois modes de défaillance du chat-en-tant-que-docs

Traiter les journaux de chat bruts comme de la documentation échoue de manières prévisibles. Chaque mode de défaillance a une solution, mais vous devez être intentionnel.

Hallucination drift. Claude invente des API, cite des papiers inexistants, et propose avec assurance des conceptions qui ignorent vos contraintes réelles. Un journal de chat préservé comme documentation préserve les hallucinations aux côtés de la sagesse. Si vous ne marquez pas quelles parties ont été vérifiées et lesquelles étaient spéculatives, le prochain lecteur traite tout comme évangile.

Narrative sprawl. Une bonne conversation divague. Vous explorez des impasses, vous laissez distraire par des cas limites, et vous revenez en arrière. Cette divagation est précieuse pour la compréhension, mais terrible pour la référence. Un nouvel ingénieur qui a besoin de la politique de réessai n’a pas besoin de lire la digression de vingt minutes sur le contrôle de congestion TCP.

Vendor lock-in. Votre documentation vit dans la base de données d’Anthropic, derrière leur interface de recherche, soumise à leur politique de rétention. Si le compte expire ou l’interface change, vos docs disparaissent. Une documentation que vous ne pouvez pas greper n’est pas de la documentation.

Comment extraire un document durable d’un chat éphémère

La solution est de traiter le chat comme un premier jet, pas comme un artefact final. Vous extrayez, vérifiez et publiez. Le workflow est simple et prend environ dix minutes par décision significative.

Étape une : marquez les tours. Pendant la conversation, marquez les décisions clés. J’utilise une convention simple. Quand Claude produit un bloc de code que j’ai l’intention de garder, je réponds avec KEEP: <one-line reason>. Quand il propose quelque chose que je rejette, je réponds avec REJECT: <reason>. Ces tags rendent l’extraction triviale.

Étape deux : extrayez en markdown. Après la session, copiez le fil dans un fichier markdown et éliminez le bruit. Supprimez les salutations, les remplissages de “laissez-moi réfléchir,” et les tours où vous étiez tous les deux confus. Conservez l’énoncé du problème, les alternatives envisagées, la décision finale et le code vérifié. Le résultat devrait se lire comme une note technique, pas comme une transcription.

Voici un script qui automatise l’extraction si vous utilisez l’API Claude ou exportez votre conversation en JSON :

#!/usr/bin/env python3
"""
Extract a readable technical note from a Claude conversation export.
Expects Anthropic's conversation JSON format.
"""

import json
import argparse
from pathlib import Path


def extract_note(conversation_path: Path, output_path: Path) -> None:
    with open(conversation_path) as f:
        data = json.load(f)

    turns = data.get("chat_messages", [])
    lines = []

    for turn in turns:
        sender = turn.get("sender", "unknown")
        text = turn.get("text", "").strip()

        if not text:
            continue

        # Skip pleasantries and meta-turns
        if any(phrase in text.lower() for phrase in [
            "hello", "how can i help", "you're welcome", "glad i could help"
        ]):
            continue

        if sender == "human":
            lines.append(f"**Q:** {text}\n")
        else:
            lines.append(f"**A:** {text}\n")

    with open(output_path, "w") as f:
        f.write("# Technical Note: Extracted from Claude Session\n\n")
        f.write("\n".join(lines))


if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    parser.add_argument("--input", type=Path, required=True)
    parser.add_argument("--output", type=Path, required=True)
    args = parser.parse_args()
    extract_note(args.input, args.output)

Étape trois : vérifiez chaque bloc de code. Exécutez le code extrait. S’il ne compile pas ou ne passe pas les tests, corrigez-le dans le markdown et notez la correction. Le document extrait doit être une source de vérité, pas une transcription d’une conversation qui a pu contenir des erreurs.

Étape quatre : commitez dans le dépôt. Stockez le markdown dans docs/decisions/ ou docs/notes/ à côté du code qu’il décrit. Donnez-lui un nom de fichier significatif : retry-circuit-jitter-over-exponential.md, pas claude-chat-july-19.md. Ajoutez-le à la même pull request que le changement de code, ou ouvrez une PR de suivi immédiatement. Si la documentation n’est pas sous contrôle de version, elle n’existe pas.

Quand cela fonctionne et quand ce n’est pas le cas

Cette approche excelle pour les décisions complexes et ambiguës où le raisonnement compte autant que le résultat. La conception de circuits, les stratégies de migration de schéma, les politiques de versionnage d’API et les trade-offs de performance sont tous de bons candidats.

Ça ne marche pas pour la documentation de référence. Un journal de chat sur la façon de s’authentifier avec l’API interne est un terrible substitut à une spec OpenAPI structurée et un exemple cURL. Utilisez le bon outil pour le bon travail.

Ça ne marche pas non plus sans curation. Déverser des journaux de chat bruts dans un wiki n’est pas de la documentation. C’est de l’accumulation. Les dix minutes d’extraction et d’édition sont non négociables. Si vous les sautez, vous produisez des ordures consultables.

Un point de départ pratique

Vous n’avez pas besoin d’un nouvel outil. Vous avez besoin d’une habitude.

La prochaine fois que vous aurez une longue session productive avec Claude sur une décision de conception non triviale, exportez le fil avant de fermer l’onglet. Passez dix minutes à l’éditer en une note markdown qui répond à trois questions : Quel problème résolvions-nous ? Quelles alternatives avons-nous envisagées et rejetées ? Sur quoi nous sommes-nous décidés et pourquoi ?

Commitez cette note dans votre dépôt. Liez-y depuis le commentaire de code au-dessus de la fonction qu’elle décrit. Le prochain ingénieur qui touchera ce code vous remerciera, et il n’aura pas besoin d’ouvrir Claude pour reconstruire votre raisonnement.

Votre chat avec Claude peut devenir de la documentation. Il suffit que vous le traitiez comme du code : extrait, vérifié, versionné et maintenu.