Documentation d'architecture
Produire en 2-4 heures une documentation d'architecture (C4, schémas, README) qui prendrait 1-2 jours.
La documentation d'architecture est notoirement négligée — souvent parce qu'elle prend trop de temps relativement à sa perception de valeur immédiate. L'IA peut produire rapidement des docs solides (C4 model, schémas Mermaid, README structurés) qui restent à jour si bien intégrées au workflow. Ce guide présente le workflow qui rend la doc vivante.
Workflow étape par étape
Décrire l'architecture existante
Composants, interactions, technologies utilisées, flux de données. À partir du code : Claude Code peut explorer le repo et produire la doc en partant du réel.
Choisir le niveau de granularité
C4 model (Context / Container / Component / Code) selon l'audience : Context pour business, Component pour devs onboarding. Adapter le grain au lecteur.
Générer schémas Mermaid
Diagrammes textuels versionnables dans le repo. L'IA produit du Mermaid valide en quelques secondes : séquence, flowchart, ER, C4.
Rédiger README et runbooks
Pour chaque service : README avec quickstart, déploiement, monitoring. Pour les opérations critiques : runbooks (que faire si X tombe). L'IA accélère drastiquement.
Intégrer à la CI/CD
Idéalement : doc générée à partir du code (OpenAPI, ASTs). Sinon : revue automatique régulière ("cette doc est-elle encore à jour ?"). Sinon dette doc s'accumule.
Prompts copiables
3 prompts testés et optimisés. Adaptez les variables entre crochets [VARIABLE] à votre contexte.
C4 Container Diagram en Mermaid
Tu es architecte logiciel. Pour cette architecture :
**Système** : [DESCRIPTION]
**Containers principaux** : [LISTE — apps, services, BDD, queues]
**Personas** : [UTILISATEURS, SYSTÈMES EXTERNES]
**Communications** : [QUI APPELLE QUOI]
Produis un diagramme C4 Container en Mermaid (C4-PlantUML compatible) :
```mermaid
C4Container
title Container Diagram - [NOM SYSTÈME]
Person(user, "User", "Description")
System_Ext(external, "External System", "Description")
Container(web, "Web App", "React", "Description")
Container(api, "API", "Node.js", "Description")
ContainerDb(db, "Database", "PostgreSQL", "Description")
Rel(user, web, "Uses", "HTTPS")
Rel(web, api, "Calls", "REST")
Rel(api, db, "Reads/Writes", "SQL")
```
Plus une note explicative de 5-10 lignes sous le schéma (architecture en mots, flux principaux). Marque [À COMPLÉTER] tout container ou flux non fourni.README de service
Génère un README pour ce service : **Service** : [NOM] **Rôle** : [DESCRIPTION] **Stack** : [LANGAGE / FRAMEWORK / DB] **Dépendances** : [SERVICES APPELÉS] **Owners** : [ÉQUIPE] Format README standard : ```markdown # [NOM SERVICE] ## What it does [3-5 lignes] ## Architecture [Schéma Mermaid C4 Component] ## Quickstart ### Prerequisites ### Install ### Run locally ### Run tests ## Configuration [Variables d'environnement requises avec descriptions] ## Deployment [Comment c'est déployé : CI/CD, environnements, rollback] ## Monitoring & Alerting [Dashboards, alertes, SLO] ## Common issues [Top 3 problèmes connus + workarounds] ## Owners & Contact ``` Long, dense, actionable. Marque [À COMPLÉTER] tout ce qui demande input équipe.
Runbook d'incident
Génère un runbook pour cette situation : **Incident type** : [DESCRIPTION — ex : DB primary down, queue saturée, certificat expiré] **Service impacté** : [SERVICE] **Symptômes observables** : [SIGNAUX] Format runbook actionnable : ## When to use this runbook [Conditions de déclenchement] ## Severity & Impact [Sev 1/2/3 + qui est impacté + revenue impact] ## Detection [Alerts qui se déclenchent, dashboards à consulter] ## Diagnosis [Commandes/queries à lancer pour confirmer le diagnostic, dans l'ordre] ## Mitigation (workaround rapide) [Étape par étape pour stabiliser, même imparfaitement] ## Resolution (fix de fond) [Étape par étape pour résoudre proprement] ## Post-incident [Communication, post-mortem, améliorations] ## Escalation [Quand escalader, à qui] Objectif : utilisable à 3h du matin par quelqu'un qui n'a jamais vu cet incident.
Top outils pour ce cas d'usage
Sélection commentée des 3 meilleurs outils IA pour documentation d'architecture.
Pourquoi pour ce cas d'usage : Le meilleur pour produire de la doc à partir du code réel : explore le repo, comprend la structure, produit C4 et README cohérents.
Pourquoi pour ce cas d'usage : Excellence sur la rédaction structurée de longs documents d'architecture en français ou anglais.
Pourquoi pour ce cas d'usage : Pour les architectures complexes nécessitant un raisonnement multi-niveaux et la cohérence sur de gros volumes de doc.
ROI estimé
Temps gagné
60-70% sur la production (2-4h vs 1-2j)
Gain qualité
Doc systématiquement à jour, schémas versionnables, runbooks actionnables
Coût stack
20-50€/mois
Estimations basées sur des benchmarks 2026 et retours d'utilisateurs. Le ROI réel dépend de votre contexte.
Questions fréquentes
Comment éviter que la doc devienne obsolète ?
Trois leviers : (1) générer depuis le code chaque fois que possible (OpenAPI, ASTs), (2) revue mensuelle automatique avec l'IA ("cette doc est-elle cohérente avec le code actuel ?"), (3) ownership clair : chaque doc a un owner responsable.
Quel format pour la doc d'architecture ?
Markdown dans le repo : versionnable, lisible, simple. Mermaid pour les schémas (versionnable aussi). Pour la lecture : MkDocs / Docusaurus / Notion. Éviter les schémas binaires (PNG) qui dérivent du code.
L'IA peut-elle générer de la doc à partir d'une codebase legacy ?
Oui, c'est même l'un des cas d'usage où elle a le plus de valeur. Claude Code peut explorer un repo, comprendre la structure, et produire C4 + README en quelques heures pour ce qui prendrait des semaines manuellement.
OpenAPI : génération automatique avec l'IA ?
Pour générer des spec OpenAPI à partir d'un code : excellent (Claude Code analyse les routes, types, et produit la spec). Pour maintenir la cohérence code/spec : préférer des outils qui génèrent automatiquement (ex: ts-rest, tRPC) plutôt que de la doc manuelle.