Prompt Claude pour l'architecture de code : concevoir des systèmes maintenables

Les développeurs qui demandent à Claude “comment structurer mon projet” obtiennent un arbre de dossiers générique copié-collé de la documentation du framework. L’architecture logicielle ne se résume pas à l’organisation des fichiers — c’est un ensemble de décisions sur la séparation des responsabilités, les flux de données et les frontières entre modules. Ce prompt exploite la capacité de Claude à analyser du code complexe pour produire un diagnostic architectural précis et un plan de refactoring séquencé.

Le prompt

You are a principal software architect with deep expertise in [TECH_STACK]. I need you to analyze my current codebase architecture and propose improvements.

**Project type**: [PROJECT_TYPE — API backend, web app, CLI tool, monorepo, microservices, etc.]
**Tech stack**: [LANGUAGE, FRAMEWORK, DATABASE, KEY_LIBRARIES]
**Team size**: [NUMBER_OF_DEVELOPERS]
**Project age**: [HOW_OLD — months/years]
**Current pain points**: [DESCRIBE_2-3_ARCHITECTURAL_PROBLEMS_YOU_FACE]

**Current structure**:
[PASTE_YOUR_DIRECTORY_TREE — use `tree -L 3` or `find . -type f | head -50`]

**Key code sample** (the area you're most concerned about):
[PASTE_THE_MOST_PROBLEMATIC_CODE — a controller, service, or module that feels wrong]

**Scale expectations**: [EXPECTED_GROWTH — users, data volume, team size, feature velocity]

Perform this architectural analysis:

1. **Current state assessment** — Identify the architectural pattern currently in use (even if implicit). List what's working well and what's creating friction. Be specific: "the UserService handles authentication, authorization, profile management, and email sending" is useful; "code is tightly coupled" is not.

2. **Dependency analysis** — Map the key dependencies between modules. Identify circular dependencies, god objects, and modules with too many responsibilities. Visualize with a simple ASCII dependency graph if helpful.

3. **Proposed architecture** — Design the target architecture:
   - Which architectural pattern fits this project and why (layered, hexagonal, CQRS, modular monolith, etc.)
   - Module boundaries with clear responsibilities
   - Data flow for the 2-3 most critical operations
   - Directory structure (concrete, not abstract)

4. **Migration plan** — A phased plan to get from current to target:
   - Phase 1 (quick wins, no breaking changes): what to move/rename/extract
   - Phase 2 (structural changes): new modules, interface definitions
   - Phase 3 (deep refactoring): the hard changes that require coordination
   - For each phase: estimated effort, risk level, what breaks if you stop here

5. **Decision records** — For the 2-3 most impactful architectural decisions, provide a mini-ADR:
   - Decision
   - Context (why this decision matters)
   - Alternatives considered
   - Consequences (trade-offs accepted)

Prioritize pragmatism over purity. A messy but working monolith is better than a perfect hexagonal architecture that takes 6 months to implement.

Comment utiliser ce prompt

Copiez le prompt ci-dessus
Remplacez les variables :
- [TECH_STACK] : ex. “TypeScript, Node.js, NestJS”
- [PROJECT_TYPE] : ex. “API REST monolithique pour une app SaaS”
- [LANGUAGE, FRAMEWORK, DATABASE, KEY_LIBRARIES] : votre stack complet
- [NUMBER_OF_DEVELOPERS] : taille de l’équipe de dev
- [HOW_OLD] : âge du projet
- [CURRENT_PAIN_POINTS] : ce qui vous fait mal au quotidien
- [DIRECTORY_TREE] : résultat de tree -L 3 ou find . -type f | head -50
- [PROBLEMATIC_CODE] : le code qui vous semble le plus problématique
- [EXPECTED_GROWTH] : projections de croissance (utilisateurs, données, équipe)
Collez dans Claude avec un maximum de contexte (fichiers joints si possible)
Itérez : demandez à Claude de détailler une phase spécifique ou de montrer le code de migration

Exemple de résultat

Entrée

Project type: API backend pour app SaaS de gestion de projet
Tech stack: Python 3.12, FastAPI, PostgreSQL, SQLAlchemy 2.0, Redis
Team size: 4 développeurs
Project age: 14 mois
Current pain points:
- Les routes FastAPI contiennent toute la logique métier (200+ lignes par endpoint)
- Impossible de tester la logique sans démarrer le serveur complet
- Les modèles SQLAlchemy sont utilisés directement dans les réponses API

Current structure:
app/
├── main.py
├── routes/
│   ├── users.py (450 lines)
│   ├── projects.py (680 lines)
│   ├── tasks.py (520 lines)
│   └── billing.py (390 lines)
├── models/
│   ├── user.py
│   ├── project.py
│   └── task.py
├── utils/
│   ├── auth.py
│   ├── email.py
│   └── helpers.py (800 lines)
└── config.py

Scale expectations: de 4 à 8 devs dans 6 mois, 10K utilisateurs → 50K

Sortie (extrait)

État actuel : Smart UI anti-pattern

Votre codebase utilise implicitement le pattern “Smart UI” — toute la logique vit dans les routes (contrôleurs). Ce n’est pas un choix architectural, c’est l’accumulation de 14 mois de features ajoutées au plus court chemin. Trois problèmes concrets :

routes/projects.py (680 lignes) fait de la validation, de la logique métier, des requêtes SQL et de la sérialisation dans les mêmes fonctions. Impossible de réutiliser la logique “créer un projet” ailleurs (ex: import batch).
utils/helpers.py (800 lignes) est un fourre-tout. Il contient probablement des fonctions qui devraient être des méthodes de service, des validateurs et des transformateurs de données mélangés.
Pas de couche de service = pas de tests unitaires. Vous ne pouvez tester la logique qu’en passant par les endpoints HTTP, ce qui rend les tests lents et fragiles.

Architecture cible : Layered Architecture (3 couches)

app/
├── api/                    # Couche présentation (routes FastAPI)
│   ├── routes/
│   │   ├── users.py        # Validation input, appel service, sérialisation
│   │   ├── projects.py
│   │   ├── tasks.py
│   │   └── billing.py
│   ├── schemas/             # Pydantic models (request/response)
│   │   ├── user.py
│   │   ├── project.py
│   │   └── task.py
│   └── dependencies.py     # Injection de dépendances FastAPI
├── services/                # Couche logique métier
│   ├── user_service.py      # Toute la logique user
│   ├── project_service.py   # Toute la logique projet
│   ├── task_service.py
│   └── billing_service.py
├── repositories/            # Couche accès données
│   ├── user_repo.py         # Requêtes SQLAlchemy uniquement
│   ├── project_repo.py
│   └── task_repo.py
├── models/                  # Modèles SQLAlchemy (inchangés)
├── core/                    # Config, auth, email, shared utilities
└── main.py

Plan de migration :

Phase	Actions	Effort	Risque
1 — Quick wins	Créer `schémas/` (Pydantic models séparés des SQLAlchemy models). Extraire les schemas depuis les routes existantes.	2-3 jours	Faible
2 — Services	Extraire la logique métier de chaque route dans un service dédié. Les routes ne font plus que : valider → appeler service → sérialiser.	1-2 semaines	Moyen
3 — Repositories	Extraire les requêtes SQLAlchemy des services vers des repositories. Les services ne dépendent plus directement de SQLAlchemy.	1 semaine	Faible

Si vous vous arrêtez après la phase 2, vous avez déjà 80% du bénéfice : tests unitaires possibles, logique réutilisable, routes lisibles. La phase 3 est un bonus pour l’isolement de la couche données.

Pourquoi ce prompt fonctionne

Le code réel en entrée change tout. Claude ne peut pas diagnostiquer une architecture sans voir la structure et le code. Le tree montre l’organisation, le code sample montre les anti-patterns concrets. Sans ces éléments, vous obtenez des recommandations théoriques.

La contrainte “pragmatisme > pureté” empêche Claude de proposer une architecture hexagonale complète avec event sourcing et CQRS pour un projet de 4 développeurs. Elle force des recommandations proportionnées à la taille de l’équipe et au stade du projet.

Le plan de migration phasé est la pièce manquante de la plupart des revues d’architecture. Savoir où aller est facile ; savoir comment y arriver sans tout casser est le vrai défi. Les phases avec “si vous vous arrêtez ici” permettent de prioriser selon le temps disponible.

Variantes

Pour une revue d’architecture existante (audit)

You are a software architect conducting a code architecture audit. Review the following codebase and provide a health assessment.

**Repository**: [PASTE_DIRECTORY_TREE]
**Key files to review**: [PASTE_2-3_CRITICAL_FILES]
**Tech stack**: [STACK]

Score each dimension (1-5):
1. Separation of concerns
2. Testability
3. Scalability readiness
4. Code organization and discoverability
5. Dependency management

For each score below 4: explain what's wrong, show one concrete example from the code, and suggest the minimal fix.

Pour choisir entre monolithe et microservices

You are a distributed systems architect. I need to decide whether to break my monolith into microservices.

**Current monolith**: [SIZE — lines of code, number of modules, team size]
**Pain points**: [WHAT_HURTS — deploy speed, team conflicts, scaling bottlenecks]
**Team**: [SIZE_AND_EXPERIENCE_LEVEL]
**Infrastructure**: [CURRENT_INFRA — Kubernetes? Docker? VMs?]

Analyze:
1. Are the pain points caused by the monolith, or by poor code organization within it?
2. If microservices: which 2-3 services should be extracted first, and why?
3. If modular monolith: how to restructure for team autonomy without distribution overhead?
4. Decision framework: what metrics should trigger the microservices migration?

Default to the simplest option that solves the actual problem.

Conseils pour de meilleurs résultats

Partagez le tree complet et 2-3 fichiers critiques. Claude peut analyser l’arbre de fichiers pour détecter les patterns d’organisation, et le code pour identifier les anti-patterns concrets. Ne résumez pas — collez le vrai code.
Décrivez les douleurs en termes concrets. “Le code est difficile à maintenir” ne dit rien. “Ajouter un champ au modèle User nécessite de modifier 7 fichiers” est un symptôme diagnosticable.
Précisez la taille de l’équipe et les contraintes de temps. L’architecture idéale pour une équipe de 4 n’est pas la même que pour une équipe de 20. Claude adapté ses recommandations à la capacité réelle de l’équipe.