Souvenez-vous du deuxième symptôme du chapitre 1 : tout le site de Talia dans un seul app.js de 1 240 lignes, réécrit en entier à chaque retouche. J'ai présenté ça comme un défaut du code. C'était en réalité le plus grave des quatre, et il mérite son propre chapitre.
Parce qu'avec une IA, l'architecture cesse d'être une affaire de goût entre développeurs. Elle décide de ce que Claude doit lire pour comprendre, de ce qu'il doit réécrire pour modifier, et de ce qu'il peut casser sans s'en apercevoir. Elle décide donc de votre facture, de vos régressions, de votre capacité à tester, de vos performances, de votre exposition et de votre capacité à grandir.
Et surtout, elle décide de ce que vous pourrez faire en parallèle : c'est elle qui autorise plusieurs chantiers simultanés, ou qui vous condamne à la file indienne. Ce chapitre n'est pas une préférence personnelle déguisée en conseil. C'est, de tout le guide, la décision qui a le plus d'effet sur les mois qui suivent.
Six dégâts, pas un seul
Un projet humain mal structuré ralentit une équipe. Un projet mal structuré confié à une IA fait six dégâts simultanés, et il faut les nommer un par un.
- 01 · Le coûtVous le savez depuis le chapitre 2 : ce qui n'est pas dans le contexte n'existe pas. Pour changer une ligne dans un fichier fourre-tout, Claude doit lire le fichier entier, et souvent le réécrire entier. Multipliez par le nombre de retouches d'une journée, puis par une équipe : la structure du code est devenue une ligne de votre budget.
- 02 · Les régressionsPlus la surface touchée est large, plus le risque est grand. Quand la logique de facturation, l'envoi des e-mails et l'affichage du calendrier partagent le même fichier, une correction de calendrier peut casser une facture, et rien ne l'annonce.
- 03 · La testabilitéDu code où tout se mélange ne se teste pas unitairement, parce qu'il n'y a pas d'unité : impossible de vérifier la règle des 24 h sans lancer une interface et une base de données. Or sans vérification exécutable (chapitre 6), tout le reste s'effondre : une architecture non testable rend le levier numéro un du guide inopérant.
- 04 · La performanceUn bloc unique se charge en bloc, se compile en bloc, se teste en bloc. Impossible de ne livrer au navigateur que la fonctionnalité affichée, impossible de profiler une partie isolément, impossible d'optimiser sans risquer le reste. Et les temps de build et de test, qui s'allongent à chaque ajout, taxent chaque itération, la vôtre comme celles de l'agent.
- 05 · La sécuritéUne frontière de module est aussi une frontière de sécurité. Chez Talia, les données de santé restent dans leur module, avec un seul point de passage à contrôler. Dans un fourre-tout, les données sensibles, les secrets et les règles d'accès circulent partout : l'audit du chapitre 8 doit tout survoler au lieu de tout inspecter, et une retouche anodine peut ouvrir une porte.
- 06 · La scalabilitéSans frontières, chaque fonctionnalité ajoutée peut interagir avec toutes les autres : la complexité ne grandit pas, elle explose. Le projet devient plus lent à faire évoluer à mesure qu'il grossit, exactement au moment où il faudrait accélérer. Et cela vaut pour le code comme pour l'équipe : à plusieurs sur un bloc unique, on se marche dessus.
Faites auditer votre architecture
Bonne nouvelle : Claude est excellent à ce poste, à condition de l'y installer explicitement. Avant d'écrire la moindre ligne d'un nouveau projet, ou avant de reprendre un projet existant, ouvrez une session dédiée et demandez un audit d'architecture. Pas « quelle stack choisir » : quelle structure, avec quels compromis, et pourquoi.
❯ claude ❯ Avant de coder : audit d'architecture. Projet de prise de ❯ rendez-vous, un praticien, forfaits, annulation, rappels. ❯ Propose 2 ou 3 structures, compare-les sur la scalabilité, ❯ la testabilité et le coût de modification. Argumente. · Claude compare les options... A. Monolithe par couches (ui/, api/, db/) : rapide à démarrer, mais toute évolution traverse les trois. B. Modules par feature, clean architecture interne : plus de fichiers, chaque changement reste local. Recommandation : B. ADR rédigé, avec les conséquences.
Notez le critère que j'ai ajouté à la demande, et qu'on oublie presque toujours : le coût de modification. Une architecture ne se juge pas à sa beauté sur un schéma, elle se juge à ce qu'elle coûte quand il faut la changer, six mois plus tard, un vendredi soir. C'est vrai avec une équipe humaine. C'est mesurable, en euros, avec un agent.
Et comme au chapitre 8, exigez un ADR : la décision écrite, avec ce qui a été écarté et pourquoi. C'est ce document qui empêchera une session neuve, dans six mois, de « simplifier » ce que vous avez pesé.
Celle qui tient : clean architecture, MVVM, modules par feature
Après quinze ans de développement mobile et une quarantaine de projets, chez Mappy, WeMoms, Accor, Voodoo ou le Programme alimentaire mondial, une combinaison sort du lot, et elle s'est révélée encore meilleure depuis que je travaille avec des agents. Trois idées, empilées.
- La clean architectureElle sépare le projet en couches qui ne se parlent que dans un sens : le domaine au centre (vos règles métier pures, la règle des 24 h, le calcul d'un forfait), les données autour (base, API, stockage), la présentation à l'extérieur (les écrans). Le cœur ne connaît ni la base de données ni l'interface. Conséquence directe : vos règles métier se testent en quelques millisecondes, sans lancer quoi que ce soit.
- Le MVVM côté présentationIl prolonge l'idée dans les écrans : la vue affiche et ne décide rien, un modèle de vue porte l'état et les décisions. Là encore, la partie qui décide se teste sans écran.
- Le découpage par module fonctionnelC'est le point que la plupart des projets ratent. Beaucoup découpent par couche technique, avec un grand dossier pour les écrans, un autre pour les services, un autre pour les modèles. Résultat : ajouter l'annulation oblige à toucher cinq dossiers éloignés. L'inverse est bien meilleur : un dossier par fonctionnalité, reservation/, forfaits/, annulation/, rappels/, chacun contenant ses propres couches. Une fonctionnalité, un dossier, une frontière.
Deux façons de découper un projet
Découper par couche technique
- Un dossier par nature de fichier, tous les modules mélangés dedans
- Une modification traverse quatre ou cinq dossiers éloignés
- Impossible de savoir ce qu'une fonctionnalité englobe
- Claude doit ouvrir tout le projet pour comprendre une règle
Découper par module fonctionnel
- Un dossier par fonctionnalité, avec ses couches à l'intérieur
- Une modification reste, le plus souvent, dans un seul dossier
- La frontière du module dit ce qui peut casser, et ce qui ne peut pas
- Claude ouvre un module, travaille, et ne touche à rien d'autre
Le geste qui change tout : un brief par module
Voici pourquoi je dis que ce chapitre n'est pas une préférence esthétique. Reprenez le chapitre 3 : nous avons donné à Claude un CLAUDE.md à la racine, sa mémoire de projet. Sur un projet qui grandit, ce fichier unique se heurte au budget d'instructions dont nous avons parlé : il gonfle, il mélange les conventions de tous les domaines, et il finit par n'être suivi nulle part.
Un projet découpé en modules permet le geste suivant, et il est décisif : chaque module porte son propre CLAUDE.md et son propre PRODUCT.md.
À la racine, on garde ce qui vaut pour tout le monde : les commandes, les conventions générales, les interdits transverses. Dans annulation/, on écrit ce qui ne concerne que l'annulation : la règle des 24 h et son emplacement, les cas limites déjà rencontrés, le PRODUCT.md qui explique pourquoi un créneau annulé garde son historique. Vingt lignes par module, chacune utile à cent pour cent quand elle se charge.
L'effet est double, et les deux moitiés comptent. Claude trouve le bon fichier immédiatement, parce que le nom du module lui dit où chercher avant même de lire quoi que ce soit. Et il ne charge que le brief pertinent : le contexte qu'il dépense sur votre projet devient proportionnel à la fonctionnalité, pas à la taille du dépôt. Petit contexte, précision maximale, coût minimal.
❯ Le forfait 10 séances ne se recrédite pas à l'annulation. · Claude ouvre le module concerné... Lu : annulation/CLAUDE.md (18 lignes) + 3 fichiers du module. Le reste du dépôt n'a pas été ouvert. Règle trouvée dans annulation/domain/RegleForfait.kt Corrigé, test unitaire ajouté. ✓ 12/12 verts. Rien d'autre que le module n'a été touché.
Comparez avec la même demande sur l'app.js de 1 240 lignes du chapitre 1 : lecture intégrale, réécriture intégrale, et l'espoir que rien d'autre n'ait bougé. Même modèle, même prompt, même développeur derrière le clavier. Seule l'architecture a changé.
Plusieurs chantiers en même temps
Jusqu'ici, nous avons parlé de ce que la modularité évite. Venons-en à ce qu'elle permet, et c'est là que le gain devient spectaculaire pour quelqu'un d'expérimenté.
Un module indépendant, c'est un chantier isolé. Rien n'empêche d'en ouvrir plusieurs à la fois : une session Claude sur les rappels pendant qu'une autre travaille sur les forfaits, une troisième sur l'export comptable. Les sessions ne se marchent pas dessus, parce que leurs fichiers ne se croisent jamais. Vous n'êtes plus limité par la machine, mais par votre capacité à relire ce qui revient.
Précisons ce qui rend ce parallélisme possible, car ce n'est pas le nombre d'agents : c'est la frontière. Lancez trois sessions sur un app.js unique et vous obtiendrez trois versions concurrentes du même fichier, un conflit à chaque enregistrement, et une soirée à démêler. Le découpage est ce qui transforme « plusieurs agents » en « plusieurs chantiers ». Le chapitre 11 donne l'outillage, avec un checkout git par session ; l'architecture, elle, donne le droit de s'en servir.
- ParalléliserUn module par session, autant de sessions que de modules ouverts. Pour un développeur expérimenté, c'est le levier qui décuple réellement la production : ce n'est plus une fonctionnalité à la fois, c'est un portefeuille de chantiers qu'on relit et qu'on livre.
- ExtraireUn module autonome part vers un autre projet tel quel : il emporte ses couches, ses tests et son CLAUDE.md, donc son mode d'emploi. L'authentification, la facturation ou les rappels deviennent un capital réutilisable au lieu d'un code à réécrire.
- SupprimerUne fonctionnalité abandonnée se retire en supprimant son dossier, et les tests confirment que le reste tient. Dans un bloc unique, retirer une fonctionnalité est une chirurgie ; ici, c'est une décision produit qui prend cinq minutes.
- AjouterUne nouvelle fonctionnalité naît dans son propre dossier, sans toucher à l'existant : elle ne peut donc pas le casser. Le rythme d'ajout cesse de ralentir avec la taille du projet, ce qui est très exactement la définition d'un projet qui passe à l'échelle.
Un module se branche, se débranche et se déménage. C'est ce qui sépare un projet qu'on fait grandir d'un projet qu'on subit.
Ce n'est pas une astuce, c'est une fondation
Il faut le dire nettement, parce que c'est le message du chapitre : ce découpage n'est pas une optimisation qu'on ajoute après coup pour économiser des tokens. C'est la fondation qui rend possible tout ce que le guide enseigne ensuite.
Une architecture modulaire et testable, c'est ce qui permet aux tests du chapitre 6 d'exister vraiment. C'est ce qui permet aux rôles du chapitre 8 de travailler chacun sur un périmètre net, au testeur de savoir ce qu'il attaque, au réviseur de savoir ce qu'il relit. C'est ce qui permet aux subagents du chapitre 9 d'explorer un module sans avaler le dépôt. C'est ce qui rend réaliste le travail en parallèle du chapitre 11.
Et le meilleur argument est peut-être celui-ci : rien de tout cela n'a été inventé pour les IA. C'est exactement l'architecture qu'une bonne équipe humaine voudrait avoir. Les agents n'ont pas changé les règles du métier, ils ont rendu la facture des mauvaises structures immédiate et chiffrable.
Ce qui était une dette diffuse est devenu une ligne sur une facture.
Et si le projet existe déjà ?
La plupart des projets que je reprends ne partent pas d'une page blanche : ils arrivent avec leur fichier de 1 240 lignes. Réécrire tout d'un coup est rarement la bonne réponse. La méthode qui marche est progressive, et Claude l'exécute très bien.
C'est exactement la démarche du chapitre 5 appliquée à la structure : explorer, planifier, exécuter par petits pas vérifiables. La différence, c'est qu'ici chaque module extrait rend le suivant moins cher, parce que le contexte nécessaire diminue à chaque étape.
- Cartographier l'existantOn fait d'abord repérer par Claude quelles fonctionnalités cohabitent réellement dans ce code, et où sont leurs frontières naturelles.
- Extraire un moduleUn seul, le plus autonome, avec ses tests et son CLAUDE.md.
- Vérifier et livrerOn vérifie que tout tourne encore, et on livre avant d'aller plus loin.
- RecommencerUne fonctionnalité à la fois, sans jamais réécrire tout d'un bloc.
Questions fréquentes sur l'architecture
Quelle architecture choisir pour un projet développé avec l'IA ?
Une architecture en couches où les règles métier sont isolées de l'interface et de la base de données (clean architecture), un modèle de vue qui porte les décisions côté écrans (MVVM), et surtout un découpage par module fonctionnel : un dossier par fonctionnalité, contenant ses propres couches. Ce découpage rend chaque modification locale, donc moins coûteuse en tokens, moins risquée en régressions et réellement testable unitairement.
Pourquoi l'architecture influence-t-elle le coût en tokens ?
Parce qu'un agent doit lire pour comprendre et réécrire pour modifier. Dans un fichier fourre-tout, la moindre retouche implique de lire et de réécrire l'ensemble, et cette dépense se répète à chaque demande. Dans un projet modulaire, Claude n'ouvre que le module concerné : le contexte consommé devient proportionnel à la fonctionnalité et non à la taille du dépôt, ce qui divise la facture tout en réduisant le risque de régression.
Faut-il un CLAUDE.md par module ?
Oui, dès que le projet dépasse quelques fonctionnalités. Le fichier racine garde les commandes et les conventions transverses ; chaque module porte un CLAUDE.md court sur ses règles métier, ses pièges et ses cas limites, et un PRODUCT.md sur ses intentions. Claude charge alors le brief pertinent au lieu d'un document général devenu trop gros pour être suivi, et il localise immédiatement le bon fichier.
Comment restructurer un projet existant sans tout casser ?
Progressivement, jamais d'un bloc. Faites d'abord cartographier l'existant par Claude pour repérer les frontières naturelles entre fonctionnalités. Extrayez ensuite un seul module, le plus autonome, avec ses tests et son CLAUDE.md, puis vérifiez que l'application tourne toujours avant de livrer. Recommencez une fonctionnalité à la fois : chaque module extrait réduit le contexte nécessaire et rend le suivant moins coûteux.
La suiteLe projet a sa mémoire et son plan. Reste à apprendre à travailler dedans, car même dans une belle maison, un développeur qui code avant de réfléchir produit du code plausible et faux. Au chapitre 5, le geste qui évite l'essentiel des dégâts : explorer, planifier, et seulement ensuite coder.
David Silvera
Développeur mobile & web freelance · 15 ans · Android, iOS, React Native, Next.js
Ce guide est tiré de ma pratique quotidienne : ce site lui-même est développé avec Claude, selon la méthode qu'il enseigne. J'accompagne aussi les équipes qui veulent monter en compétence : audit de pratique, formation, mise en place d'outillage.
Discutons de votre équipe