Architecture relationnelle Claude Code : pourquoi votre projet devient une bombe à retardement (et comment l'éviter)

Le problème réel : semaine 1 vs semaine 6

À la semaine 1 d'un projet, vous avez 12 fichiers. Tout est clair, vous savez ce qui fait quoi, vous avancez vite. À la semaine 6, vous avez 87 fichiers, un CLAUDE.md trop léger, et vous cassez X en touchant Y à tous les coups.

Le problème n'est pas Claude Code. Le problème, c'est que Claude Code n'a pas de carte du territoire. Il ne sait pas que le fichier d'authentification est appelé par le dashboard, qui est lui-même appelé par les notifications. Sans cette information, chaque modification devient un pari.

Résultat : plus de 3 heures par feature, des bugs en cascade, et parfois l'abandon pur et simple du projet. Alors que la solution tient dans un fichier Markdown.

Ce qu'est une architecture relationnelle

Une architecture relationnelle, c'est un arbre indenté qui mappe chaque fonctionnalité de votre projet avec ses dépendances. Chaque élément sait deux choses : de qui il dépend, et qui dépend de lui.

Visuellement, ça ressemble à ça : un dossier authentification au niveau 1, un login-flow au niveau 1.1, un session-manager au niveau 1.1.1. L'indentation montre les niveaux, et les relations montrent les connexions entre branches.

C'est le principe d'une mémoire conversationnelle appliqué au code. Comme vous donnez du contexte global à une IA dans une conversation pour qu'elle ne perde pas le fil, vous donnez ici à Claude Code une vision globale de l'environnement dans lequel il travaille, pour qu'il arrête de tout casser. C'est exactement ce que le protocole LMP fait pour la mémoire conversationnelle, mais appliqué au code source.

Les 5 niveaux de classification

Chaque fonctionnalité de votre projet appartient à l'un de ces 5 types :

• Core : les fonctions fondamentales sans lesquelles rien ne tourne. L'authentification, la base de données, le routage.
• Feature : les fonctionnalités visibles par l'utilisateur. Le dashboard, les paiements, les notifications.
• Sub : les sous-fonctions rattachées à une feature. Le filtre d'une liste, le formulaire d'un écran.
• Hook : les déclencheurs et listeners. Ce qui s'active quand un événement se produit.
• Utility : les fonctions transversales réutilisées partout. Formatage de dates, gestion d'erreurs, helpers.

Pas besoin de les mémoriser. Vous les donnez à Claude Code dans le prompt et il classe lui-même chaque fonctionnalité.

Les 4 types de relations

Ce qui rend cette méthode utile, ce ne sont pas les niveaux mais les relations explicites entre les nœuds. Il y en a 4 :

• utilise : A appelle B pour fonctionner. Le login-flow utilise l'authentification.
• déclenche : A provoque l'activation de B. Le onAuthChange déclenche le dashboard et les notifications.
• dépend de : A ne peut pas fonctionner sans B. Le dashboard dépend de l'authentification.
• persiste dans : A stocke ses données dans B. L'éditeur de notes persiste dans la base de données.

Ces quatre balises suffisent à décrire 95 % des connexions dans un projet SaaS. Zéro ambiguïté, zéro interprétation possible. C'est volontairement froid et précis, parce que c'est une IA qui le lit.

La méthode en 4 étapes

Étape 1 : lister

Listez toutes les fonctionnalités de votre projet sans les trier. Génération de résumé IA, paiements Stripe, export PDF, dashboard, notifications, authentification. Tout ce que fait votre application.

Étape 2 : classifier

Attribuez à chaque fonctionnalité son type parmi les 5 niveaux : core, feature, sub, hook, utility. C'est Claude Code qui fait ce travail une fois que vous lui avez donné le prompt.

Étape 3 : relier

Mappez les dépendances entre fonctionnalités en utilisant les 4 types de relations. Qui appelle qui, qui déclenche quoi, qui ne peut pas vivre sans quoi.

Étape 4 : documenter

Générez le fichier architecture.md avec l'arbre indenté complet et la table des relations. Ce fichier devient la référence que Claude Code consulte avant chaque modification.

Le prompt à utiliser

Passez Claude Code en mode plan avant d'envoyer ce prompt. Le mot "analyse" est important : si vous dites juste "crée une architecture", Claude Code peut se baser sur votre documentation existante, même si elle est mauvaise. Forcez-lui la main.

Analyse l'intégralité de ce projet.
Pour chaque fonctionnalité, identifie :
- Son type : core, feature, sub, hook ou utility
- Ses dépendances (ce qu'elle utilise)
- Ses dépendants (ce qui l'utilise)
- Ses relations : utilise / déclenche / dépend de / persiste dans

Génère ensuite un fichier architecture.md contenant :
1. Un arbre indenté de toutes les fonctionnalités avec les relations
2. Une table des relations (source / type / destination)
3. La liste des fichiers critiques par fonctionnalité
4. Le schéma de base de données
5. Le flux des données (pipeline textuel)

Format de l'arbre :
CORE authentification
  FEATURE dashboard (dépend de: authentification)
    SUB client-list
      SUB filters

Sur un projet de taille moyenne (15 à 20 fonctionnalités), ce prompt consomme entre 150 000 et 200 000 tokens. Avec la fenêtre de contexte à 1 million de tokens disponible depuis mars 2026, ce n'est plus un frein.

Une fois l'architecture générée, ajoutez une deuxième instruction : demandez à Claude Code de mettre à jour votre CLAUDE.md pour qu'il pointe vers docs/architecture.md. Comme ça, à chaque session, il sait où aller chercher la carte du projet.

Splitter la documentation en fichiers ciblés

Un seul fichier architecture.md de 500 lignes, c'est mieux que rien, mais c'est encore un monolithe. Claude Code va tout charger à chaque question, même quand il n'a besoin que des routes API.

La meilleure approche : demandez à Claude Code de splitter le dossier docs en fichiers thématiques. Par exemple :

• architecture.md : l'arbre des fonctionnalités et les relations
• database.md : le schéma des tables
• api-routes.md : toutes les routes API
• hooks.md : les déclencheurs et listeners
• decisions.md : le journal des choix techniques

Résultat concret sur un projet réel : passage de 2 fichiers à 8 fichiers, score de clarté de 5/10 à 8/10. Claude Code lit uniquement ce qui est utile pour la tâche en cours, consomme moins de tokens par requête, et fait moins d'erreurs.

Un point d'attention : évitez d'avoir deux fichiers README.md dans votre projet. Si Claude Code voit deux README, il peut se mélanger quand vous lui demandez de le mettre à jour.

Ce que ça change concrètement

Les modifications vont 5 à 10 fois plus vite. Claude Code n'a plus besoin d'analyser tout le projet à chaque question, il consulte directement le bon fichier de documentation.

Les bugs en cascade disparaissent presque entièrement. Claude Code sait maintenant que modifier le fichier d'authentification impacte le dashboard et les notifications. Il prend ces dépendances en compte avant d'agir.

N'importe quelle IA peut reprendre le projet sans vous. Que vous changiez d'outil dans six mois ou que vous passiez le projet à quelqu'un d'autre, la documentation est là. La même architecture relationnelle fonctionne avec Claude Code, avec un modèle concurrent, ou avec un développeur humain.

La valorisation du projet augmente. Une société avec des SOP documentées vaut plus qu'une société dont tout est dans la tête d'une seule personne. C'est vrai pour les entreprises, c'est vrai pour les SaaS. Un projet bien documenté se revend, se délègue, et se fait racheter. C'est d'ailleurs la logique derrière un audit SEO complet : rendre visible et mesurable ce qui était implicite.

Un point sur la sécurité

Dans vos fichiers d'architecture, ne mettez jamais de clés API, d'URLs de webhooks, de secrets ou de variables d'environnement. Donnez des noms fonctionnels aux intégrations : "API analyse batch via LLM" plutôt que l'URL réelle ou la clé Stripe.

Tout ce qui se trouve dans votre .env ou .env.local n'a rien à faire dans la documentation. Si vous partagez votre écran, si vous publiez une vidéo, si quelqu'un accède à votre dépôt, ces fichiers sont lisibles. Gardez les secrets dans les variables d'environnement, pas dans la documentation.

L'architecture relationnelle ne demande pas d'être développeur. Elle demande de comprendre ce que fait votre projet et de le transmettre à Claude Code de façon structurée. Un prompt, un fichier Markdown, et votre projet cesse d'être une bombe à retardement.