Appearance

Mission : construire la base de connaissance persistante du projet ​

Je veux que tu génères la documentation persistante (CLAUDE.md hiérarchiques + dossier .claude/) de ce projet .NET, pour qu'à chaque future session tu aies immédiatement le contexte métier et technique sans avoir à réanalyser le repo.

Tu vas procéder en 5 phases. Tu t'arrêtes après chaque phase pour validation. Tu n'inventes JAMAIS d'information métier : si tu ne peux pas le déduire du code avec certitude, tu me poses la question.

Phase 1 — Découverte technique (autonome) ​

Explore le repo et établis :

  • La stack précise (version .NET, framework web, ORM, base de données, libs notables type MediatR/FluentValidation/AutoMapper)
  • Le pattern d'architecture (Clean Architecture, N-tier, Vertical Slices, modulaire, monolithe classique...)
  • La structure des dossiers/projets et leur rôle
  • Les points d'entrée (API, jobs, workers, front)
  • Comment on build, test, lance en local, fait les migrations
  • Les conventions de code visibles (nommage, organisation des fichiers, style de tests)

Restitue-moi un résumé structuré et demande-moi confirmation/correction avant de continuer.

Phase 2 — Cartographie des modules métier ​

Identifie les bounded contexts / modules / domaines fonctionnels présents dans le code (ex: Facturation, Contrats, Utilisateurs, Reporting...). Pour chacun :

  • Son rôle apparent
  • Son emplacement dans le repo
  • Ses entités/aggregates principaux
  • Ses dépendances vers d'autres modules

Présente-moi la carte. Je vais corriger les noms, regrouper, splitter, te dire ce qui est legacy, etc.

Phase 3 — Plan de documentation ​

Propose-moi une arborescence cible du type :

CLAUDE.md                              (racine, court, ~150 lignes max)
.claude/
  domain/
    glossary.md                        (langage métier)
    business-rules.md                  (règles de gestion non-triviales)
    workflows.md                       (parcours utilisateurs principaux)
  architecture/
    overview.md
    patterns.md
    adr/                               (décisions architecturales)
src/Modules/<Module>/CLAUDE.md         (un par bounded context)

Adapte la structure à ce que tu as trouvé. Liste les fichiers que tu prévois de créer et ce qu'il y aura dans chacun. Attends mon GO.

Phase 4 — Interview métier ciblée ​

Pour tout ce que le code ne te permet pas de comprendre seul, tu me poses des questions, par lots de 5-7 max, en commençant par les plus importantes :

  • Le métier en 2 phrases (qui utilise l'app, pour quoi faire)
  • Les termes du jargon que tu vois dans le code mais dont le sens t'échappe
  • Les règles de gestion bizarres ou non-évidentes que tu as repérées (if étranges, comportements conditionnels, etc.)
  • Les décisions historiques visibles ("pourquoi ce truc est fait comme ça ?")
  • Les pièges connus / zones fragiles
  • Les workflows critiques de bout en bout

Tu n'enchaînes pas les questions à l'aveugle : tu lis d'abord le code, tu formules des hypothèses, et tu me demandes de confirmer ou corriger plutôt que de demander à zéro.

Phase 5 — Génération ​

Une fois mes réponses obtenues, génère tous les fichiers en respectant ces règles.

CLAUDE.md racine (~150 lignes max) ​

À structurer dans cet ordre :

1. Protocole de travail (OBLIGATOIRE — tout en haut du fichier)

Section explicite avec ces règles formulées comme des instructions permanentes pour les sessions futures :

Protocole de travail — À LIRE ET APPLIQUER À CHAQUE SESSION ​

Avant toute tâche (analyse, dev, debug, review) :

  1. Identifie le ou les modules concernés par la demande
  2. Lis systématiquement et sans qu'on te le demande :
    • Ce CLAUDE.md racine (déjà fait au démarrage)
    • Le CLAUDE.md du/des module(s) concerné(s)
    • Les fichiers pertinents dans .claude/docs/domain/ (glossary, business-rules, workflows) si la tâche touche au métier
    • Les fichiers pertinents dans .claude/docs/architecture/ si la tâche touche à la structure ou aux patterns
    • Les ADR liés s'il y en a
  3. Si une info te manque dans la doc, dis-le et propose une question avant de coder

Après toute modification de code significative, tu mets à jour la doc sans qu'on te le demande, dans le même commit logique :

  • Nouveau terme métier introduit ou renommé → glossary.md
  • Nouvelle règle de gestion ou modification d'une règle existante → business-rules.md
  • Nouveau workflow ou changement de parcours → workflows.md
  • Changement structurel dans un module (entité ajoutée, invariant modifié, dépendance changée) → CLAUDE.md du module
  • Décision architecturale (choix de lib, pattern, structure) → nouvel ADR dans .claude/docs/architecture/adr/
  • Nouveau pattern récurrent ou convention → patterns.md
  • Nouvelle commande build/test/run → CLAUDE.md racine

Critère de "modification significative" : tout ce qu'un nouveau dev devrait savoir pour ne pas se planter. Renommer une variable locale = non. Ajouter un champ à une entité = oui. Changer la logique d'un calcul métier = oui. Ajouter un endpoint = oui.

Ce qui ne se logue PAS : corriger une faute d'orthographe, reformater/réindenter, renommer une variable locale, ou modifier du code sans aucun impact sur la logique métier ne nécessitent aucune mise à jour de la doc. La doc ne se met à jour que pour les changements significatifs ci-dessus — pas de bruit inutile.

Commentaires dans le code : par défaut, ne pas commenter. N'ajoute un commentaire que lorsqu'il apporte une info que le code ne dit pas déjà (un pourquoi, jamais un quoi). Quand tu en mets : 1 ligne, 2 grand maximum, toujours en anglais, le plus succinct possible. Ne commente jamais ligne par ligne, ni les évidences — utilise ta jugeote.

À la fin de chaque tâche de dev, tu listes explicitement les fichiers .md mis à jour, ou tu indiques "aucune mise à jour de doc nécessaire" en justifiant.

Si tu détectes une incohérence entre le code et la doc pendant une session, signale-la immédiatement et propose la correction.

2. Vue d'ensemble métier (3-5 lignes) 3. Stack et architecture (en bref) 4. Carte du repo (où trouver quoi) 5. Commandes utiles (build/test/run/migrations) 6. Conventions clés (inclure la règle de commentaires : par défaut aucun commentaire ; si nécessaire, 1-2 lignes max, en anglais, succinct, le pourquoi pas le quoi) 7. Règles immuables ("ne jamais X") 8. Imports @.claude/docs/... vers les docs détaillées 9. Imports @src/Modules/.../CLAUDE.md pour pointer les modules

Fichiers .claude/domain/ ​

  • glossary.md : chaque terme métier avec définition + exemple + où c'est dans le code
  • business-rules.md : les règles de gestion avec leur "pourquoi"
  • workflows.md : les parcours principaux en pseudo-séquence

Fichiers .claude/architecture/ ​

  • overview.md : pattern général, flux d'une requête typique, couches
  • patterns.md : les patterns récurrents (ex: comment on ajoute une feature, comment on gère les erreurs, comment on teste, convention de commentaires)
  • adr/ : un ADR par décision structurante identifiée, format court (Contexte / Décision / Conséquences)

CLAUDE.md par module ​

  • Court (~80 lignes)
  • Rôle du module
  • Entités principales et invariants
  • Règles métier spécifiques au module
  • Points d'attention / pièges
  • Conventions locales si différentes de la racine
  • Rappel en haut du fichier : "Ce fichier doit rester synchronisé avec le code du module. À mettre à jour à chaque changement structurel."

Règles de rédaction ​

  • Pas de blabla, pas de paraphrase du code, pas de "ce projet est moderne et performant"
  • Du concret : noms réels, chemins réels, exemples réels
  • Si tu n'es pas sûr d'un fait, écris [À CONFIRMER] plutôt qu'inventer
  • Pas de secrets, pas de connection strings, pas de clés API

À la fin, fais-moi un récap des fichiers créés et liste les [À CONFIRMER] que je dois reprendre.

Démarre la Phase 1 maintenant.

Contributors

The avatar of contributor named as Clément Favre Clément Favre

Changelog