how-claude-code-works : lire 500 000 lignes de TypeScript par procuration

Un dépôt de documentation, pas un framework

Le titre induit en erreur. how-claude-code-works ne contient pas d'agent à installer, pas de bibliothèque à importer, pas de CLI. C'est un corpus de notes d'architecture sur Claude Code, l'agent de codage d'Anthropic, publié sous licence MIT. Le README annonce 21 chapitres et un site de lecture en ligne hébergé sur GitHub Pages. Le problème visé est concret : un snapshot d'environ 500 000 lignes de TypeScript a circulé dans la communauté, et personne ne sait par où commencer la lecture. La réponse de l'auteur est méthodologique. Il a lu le code avec Claude Code, fait écrire de la documentation par l'outil pendant la lecture, puis documenté ce processus. Le public visé est donc double : ceux qui veulent construire leur propre agent de codage, et ceux qui veulent comprendre les arbitrages internes de Claude Code pour mieux s'en servir. Un projet compagnon, claude-code-from-scratch, propose environ 4300 lignes de TypeScript et de Python en 13 chapitres, présenté comme une implémentation éducative clean-room. Les deux dépôts sont distincts : celui-ci documente, l'autre construit.

La chaîne de traitement décrite dans le schéma d'architecture

Le README fournit un diagramme Mermaid qui vaut d'être lu comme une spécification, pas comme une illustration. L'entrée utilisateur passe par un QueryEngine qui gère la session, puis par une boucle principale nommée query, qui appelle l'API Claude. La réponse est analysée : soit du texte, qui part en sortie en flux, soit des appels d'outils, qui partent vers le moteur d'exécution. Ce moteur regroupe la lecture de fichiers, l'édition, l'exécution shell, la recherche et les outils MCP. Les résultats sont réinjectés dans la boucle query. En parallèle, un bloc d'ingénierie de contexte alimente la boucle : prompt système, statut Git, fichier CLAUDE.md, pipeline de compression. Un système de permissions se branche sur le moteur d'outils, avec une couche de règles, une analyse AST des commandes Bash et une confirmation utilisateur. Deux points méritent l'attention. D'abord, les outils MCP empruntent le même chemin que les outils internes, ce qui signifie qu'un serveur tiers hérite des mêmes contrôles. Ensuite, la compression n'est pas un module de nettoyage périphérique : elle est représentée comme une entrée de la boucle, au même titre que le prompt système. C'est cohérent avec le fait que la fenêtre de contexte est la ressource rare de tout le système.

Compression en quatre niveaux et reprise silencieuse

Le chapitre 3 décrit un pipeline de compression à quatre niveaux appliqués progressivement. Le premier tronque les gros blocs des messages historiques, typiquement les anciennes sorties d'outils. Le deuxième déduplique, présenté comme quasi gratuit. Le troisième replie les segments de conversation inactifs sans modifier le contenu d'origine, ce qui laisse la possibilité de les déplier. Le quatrième, décrit comme le dernier recours, lance un sous-agent pour résumer l'ensemble de la conversation. La documentation indique que chaque niveau peut libérer suffisamment d'espace pour rendre les suivants inutiles, et qu'après compression le système restaure automatiquement le contenu des cinq fichiers les plus récemment édités, avec réactivation des compétences. Ce dernier détail est le plus intéressant et le plus discutable. Restaurer cinq fichiers est un choix arbitraire : rien dans le README n'explique pourquoi cinq, ni comment ce nombre se comporte sur une session où l'agent a touché trente fichiers. À mettre en regard, le chapitre 2 annonce sept « Continue Sites », c'est-à-dire sept stratégies de reprise selon le type de panne, et le README cite deux exemples : un dépassement de fenêtre déclenche une compression et une nouvelle tentative sans message d'erreur, un plafond de tokens atteint passe automatiquement de 8K à 64K avant nouvelle tentative. La conséquence pratique est que l'absence d'erreur visible n'est pas une preuve d'absence d'erreur.

Sept couches de défense et une analyse AST des commandes

Le chapitre 11 détaille une défense en profondeur à sept niveaux. Confiance dans l'espace de travail d'abord : à la première entrée dans un répertoire, l'utilisateur confirme la confiance, et en l'absence de confiance les hooks personnalisés du projet sont désactivés, ce qui bloque les scripts préplacés dans un dépôt hostile. Puis les modes de permission, qui restreignent l'étendue des opérations selon le niveau de confiance. Puis les règles allow/deny/ask fondées sur des motifs de commandes. Puis l'analyse approfondie des commandes Bash : le README précise qu'il s'agit d'une analyse par arbre syntaxique et non par expression régulière, avec 23 contrôles statiques couvrant l'injection de commandes, la fuite de variables d'environnement et les attaques par caractères spéciaux. Viennent ensuite la validation propre à chaque outil, un bac à sable au niveau du processus (Seatbelt sur macOS, espaces de noms Linux) doublé d'une isolation par Git Worktree, et enfin la confirmation utilisateur, qui entre en course avec les hooks et un classificateur LLM, avec un anti-rebond de 200 ms et une priorité accordée à l'intention humaine. Le choix de tree-sitter plutôt que du regex est le point techniquement le plus solide du dépôt : une expression régulière sur une ligne de shell est structurellement incapable de suivre les substitutions, les pipes et les redirections imbriquées. Reste que 23 contrôles statiques ne couvrent pas un shell complet, et la documentation elle-même ne revendique pas l'exhaustivité.

Ce que le dépôt ne permet pas de vérifier

La limite principale est énoncée par l'auteur dans un avertissement en tête de README : le contenu est une analyse éducative indépendante, il ne représente pas la conception officielle d'Anthropic et ne garantit pas de correspondre à l'implémentation interne réelle. Cette phrase change la nature du document. Vous lisez une reconstruction plausible, pas une spécification. Le README contient par ailleurs des chiffres précis : démarrage en 9 phases parallèles avec un chemin critique annoncé autour de 235 ms, fenêtre de génération de 5 à 30 secondes pendant laquelle la latence d'outil d'environ 1 seconde serait masquée par pré-exécution, bascule de 8K à 64K tokens. Aucun de ces chiffres n'est accompagné d'une méthode de mesure, d'un environnement de test ou d'un protocole reproductible dans le matériel fourni. Il faut les traiter comme des ordres de grandeur rapportés, pas comme des résultats. Autre point : le dépôt ne publie aucune release, et la seule date exploitable est celle du dernier push, le 17 août 2026. La licence MIT couvre le texte et les schémas du dépôt. Elle ne couvre évidemment pas Claude Code lui-même, et le README précise qu'aucun code source d'Anthropic n'est redistribué. Si vous réutilisez des schémas ou des extraits, la mention de licence du dépôt suffit pour le contenu original ; pour tout ce qui relève de l'implémentation décrite, la question ne se pose pas dans les mêmes termes puisque rien n'est distribué.

Chapitre 17 : de la lecture de code à la rétro-ingénierie de boîte noire

Les chapitres 17 et 18 portent un marqueur distinct dans la table des matières. Le chapitre 17 est sous-titré « après le snapshot, rétro-ingénierie en boîte noire » et traite deux mécanismes d'autonomie, /goal et /loop. La documentation y oppose deux paradigmes : un évaluateur garde-fou d'un côté, une alarme auto-planifiée de l'autre. Elle annonce le prompt système complet de l'évaluateur /goal, un frein contre les boucles infinies sur objectif impossible, les règles d'analyse de /loop, et trois chemins d'exécution (cron, ScheduleWakeup). Le chapitre se termine par une méthode de rétro-ingénierie présentée comme reproductible : chaînes statiques et capture de trafic via un proxy en clair. C'est un changement de méthode notable. Jusque-là l'auteur lisait un snapshot ; ici il observe un binaire en fonctionnement. La valeur probante n'est pas la même, et le dépôt le signale par un icône de recherche dans la table des matières. Le chapitre 18 poursuit sur Auto Mode, où la permission passe d'un couple règles plus confirmation à un classificateur ML qui arbitre action par action, avec quatre compartiments de règles en langage naturel et un filtrage en deux temps, grossier puis fin. Ces deux chapitres sont ceux qui vieilliront le plus vite, puisqu'ils décrivent des fonctionnalités apparues après le snapshot et évoluent avec le produit.

Alternatives et coût de suivi

L'alternative naturelle n'est pas un autre projet d'analyse mais la source primaire : lire le snapshot TypeScript directement, ou lire la documentation publique d'Anthropic. La différence d'approche est nette. Lire la source vous donne la vérité du code au moment du snapshot, sans intermédiaire, mais vous coûte le problème initial, à savoir 500 000 lignes sans plan de lecture. La documentation publique d'Anthropic décrit le comportement attendu du produit, pas ses mécanismes internes. Ce dépôt se place entre les deux : il fournit un plan de lecture et des hypothèses de mécanisme, au prix d'une couche d'interprétation non vérifiable. Le projet compagnon claude-code-from-scratch répond à un autre besoin : il produit du code exécutable plutôt que des explications. Sur le coût de maintenance, le README est explicite : l'auteur indique continuer à rétro-analyser les nouvelles fonctionnalités et à mettre le dépôt à jour, en citant loop engineering et dynamic workflow. Concrètement, cela signifie que la valeur du dépôt dépend d'un travail de suivi continu sur un produit qui bouge, sans release ni versionnement visible pour figer un état de référence. Si vous citez ce dépôt dans un document interne, citez aussi la date du dernier push, sinon la référence se périmera sans que rien ne le signale.

Conclusion éditoriale

Ce dépôt convient à celles et ceux qui conçoivent un agent de codage et veulent une carte des décisions d'ingénierie à prendre, pas un tutoriel d'utilisation de Claude Code. Il ne convient pas si vous cherchez du code exécutable, des mesures reproductibles ou une garantie de conformité avec l'implémentation réelle : l'auteur écrit lui-même que le contenu est une étude indépendante et non la conception officielle d'Anthropic. Avant de vous appuyer dessus, ouvrez docs/13-minimal-components.md et docs/17-autonomy-goal-loop.md, et vérifiez si le niveau de détail annoncé correspond à ce que vous devez réellement implémenter.

Sources officielles

1. Issues
2. License: MIT
3. Project website
4. README
5. Windy3f3f3f3f/how-claude-code-works on GitHub