Il est dix heures du matin. Vous êtes depuis quinze minutes en train d'affiner un prompt pour que votre AI tool génère un service Angular respectant les conventions de l'équipe. Le résultat utilise BehaviorSubject alors que vous utilisez des signals. Il place le fichier dans src/services/ alors que votre monorepo a une structure complètement différente. Le nommage est générique — NotificationService — alors que votre convention est UserNotificationFacadeService.
Vous effacez. Vous réécrivez le prompt. Troisième essai. Quatrième.
Dans une autre équipe — ou dans la même équipe trois mois plus tard — la même requête produit un résultat qui passe la revue de code sans modifications. Même modèle. Même type de prompt. La différence ? Ce n'était pas le prompt.
Le problème n'est pas la façon dont vous demandez. C'est ce que l'IA sait de votre projet avant que vous ne lui posiez la question.
Le vrai problème
Il existe une déconnexion fondamentale entre la façon dont fonctionnent les AI tools et la façon dont fonctionnent les projets enterprise réels.
Dans une équipe de huit personnes travaillant sur un monorepo Angular avec douze microfrontends, il y a des dizaines de décisions architecturales qui vivent dans la tête des gens. Le pattern des services facade, la convention des dossiers par domaine, les patterns interdits, les raisons pour lesquelles NgRx global a été écarté au profit de SignalStore local. Rien de tout cela n'est écrit. Tout le monde le sait. Les nouveaux l'apprennent par osmose en quelques semaines.
L'IA n'a pas des semaines. L'IA ne pose pas de questions. L'IA n'apprend pas par osmose.
Ce qui n'est pas écrit n'existe pas pour l'IA.
Cela explique pourquoi les démonstrations sont spectaculaires et votre quotidien ne l'est pas. Les démos utilisent des projets vides sans histoire, sans conventions accumulées, sans décisions antérieures. Là, il n'est pas nécessaire d'avoir du contexte car il n'y a pas de contexte spécifique. Votre projet de trois ans avec 200K lignes et des conventions d'une équipe de quinze personnes est un animal différent.
Et c'est ici que se trouve le piège du prompt engineering.
L'industrie a généré un marché énorme de "prompt libraries", "mega prompts" et de cours sur "comment mieux interroger l'IA". Tous supposent implicitement que le contexte du projet est déjà disponible. En enterprise, il est rarement disponible. Vous pouvez rédiger le prompt le plus élaboré du monde — si l'IA ne sait pas que votre équipe utilise des facade services, elle ne générera pas de facade services.
L'asymétrie est brutale : un meilleur prompt améliore un résultat une fois. Un contexte documenté améliore tous les résultats toutes les fois.
La thèse : le contexte est plus important que les prompts
Si le goulot d'étranglement n'est pas le prompt mais l'absence de contexte, la solution n'est pas d'écrire des prompts plus créatifs. C'est de fournir un contexte structuré. Et la façon la plus directe de le faire est un fichier que j'appelle architecture.md.
Ce n'est pas de la documentation générique. Ce n'est pas un README d'installation. C'est un fichier conçu pour que n'importe quel LLM — Copilot, Cursor, Claude, ChatGPT — comprenne votre projet sans que vous ayez à l'expliquer à chaque fois. Il contient ce qu'un senior de votre équipe a en tête : stack, conventions, structure, patterns, décisions clés.
Pourquoi ça marche ? Parce que les LLM génèrent en se basant sur des motifs statistiques plus le contexte que vous leur fournissez. Si le contexte indique "dans ce projet nous utilisons des signals, pas des BehaviorSubject", la sortie utilisera des signals. Sans cette information, il utilisera ce qui est statistiquement le plus courant — ce qui, dans le cas d'Angular antérieur à 2024, signifie BehaviorSubject. Et votre équipe utilise exclusivement des signals depuis un an.
Pensez-y ainsi : un prompt sans contexte de projet, c'est comme dire à un chauffeur de taxi "emmène-moi au bureau" sans lui donner l'adresse. Le chauffeur peut être excellent, la voiture peut être performante, mais sans adresse il n'ira nulle part d'utile. Un architecture.md, c'est donner l'adresse, indiquer quelles rues éviter pour travaux, et pourquoi entrer par la porte du parking. Même requête. Résultat radicalement différent.
Et il y a un effet composé que les prompts n'ont pas. Écrire un architecture.md prend quelques heures. Mais ce fichier améliore des milliers d'interactions futures, avec n'importe quel outil, pour n'importe quel membre de l'équipe. C'est un véritable levier — pas l'optimisation d'un prompt individuel qui résout un seul problème une fois.
Un cas pratique
Pour que cela cesse d'être abstrait, voyons un cas réel.
Projet : application Angular enterprise pour un client du secteur financier. Monorepo Nx avec huit libraries. Équipe de huit personnes. Conventions propres développées sur deux ans.
Requête au LLM : "Génère un service Angular pour gérer l'état des notifications de l'utilisateur."
Sans architecture.md
Le modèle génère quelque chose comme :
@Injectable({ providedIn: 'root' })
export class NotificationService {
private notifications$ = new BehaviorSubject<Notification[]>([]);
getNotifications(): Observable<Notification[]> {
return this.notifications$.asObservable();
}
addNotification(notification: Notification): void {
const current = this.notifications$.value;
this.notifications$.next([...current, notification]);
}
}
Techniquement fonctionnel. Et complètement inutilisable dans notre projet. Le nommage est incorrect. Il utilise BehaviorSubject alors que nous utilisons des signals. Il ne respecte pas le pattern facade. Le fichier serait créé dans un path incorrect. Il ne passerait pas la revue de code.
L'extrait pertinent du architecture.md
## Convenciones de servicios
- Patrón: Facade services como interfaz pública. Domain services internos.
- Naming: {Feature}{Tipo}Service (ej: UserNotificationFacadeService)
- Estado: signals (WritableSignal) para estado reactivo. No BehaviorSubject.
- Ubicación: libs/{domain}/{feature}/services/
- Tests: describe por método público, mocks con ng-mocks.
## Patterns prohibidos
- No subscribe() manual. Usar toSignal() o async pipe.
- No servicios god (>300 líneas). Dividir en facade + domain services.
Nota: le bloc ci‑dessus contient du texte en espagnol original (conventions/patterns). Conformément aux contraintes, ces fragments techniques et exemples de conventions ne doivent pas être modifiés ni traduits si ce sont des noms de conventions internes ou snippets voulus tels quels. Les extraits de code et chemins doivent rester intacts.
Avec architecture.md en contexte
Même prompt exact. Le modèle génère :
@Injectable({ providedIn: 'root' })
export class UserNotificationFacadeService {
private readonly notificationDomainService = inject(UserNotificationDomainService);
readonly notifications = this.notificationDomainService.notifications;
readonly unreadCount = computed(() =>
this.notifications().filter(n => !n.read).length
);
markAsRead(id: string): void {
this.notificationDomainService.markAsRead(id);
}
}
Nommage correct. Signals. Pattern facade. Injection avec inject(). Séparation facade/domain. Prêt pour commit.
Le prompt était identique. La seule différence était le contexte.
Ce n'est pas exclusif à Angular. Je l'ai observé de la même façon avec des pipelines Azure DevOps où, sans documentation des conventions de stages et du nommage des templates, le YAML généré ne passe jamais la validation. Je l'ai vu avec les APIM policies où le XML généré utilise des patterns génériques qui n'entrent pas en cohérence avec la structure réelle des backends. Je l'ai vu avec des configs Nginx pour le reverse proxy de microfrontends où les location blocks ne reflètent pas le routing réel de l'application.
Dans tous les cas, même pattern : sans contexte explicite, résultat générique et inutilisable. Avec contexte, résultat adapté et fonctionnel.
Objections légitimes
Il serait intellectuallement malhonnête de ne pas aborder les objections évidentes.
"Un bon prompt compte."
Oui. Un prompt bien rédigé sur un bon contexte est la combinaison idéale. Mais la priorité est claire : d'abord le contexte, puis le prompt. Un excellent prompt sur un contexte vide a un plafond bien plus bas qu'un prompt médiocre sur un contexte riche. Si vous ne pouvez investir que dans une seule chose, investissez dans le contexte.
"Documenter prend du temps que nous n'avons pas."
Un architecture.md basique s'écrit en deux heures. Si un développeur interagit avec des AI tools vingt fois par jour et que chaque interaction sans contexte nécessite trois minutes supplémentaires de correction, ce sont soixante minutes perdues par jour. Dans une équipe de huit, ce sont huit heures par jour. L'investissement est récupéré la première semaine. Et cette documentation ne sert pas seulement pour l'IA — elle sert pour l'onboarding, pour les décisions futures, pour les revues de code.
"Les modèles vont s'améliorer et cela deviendra inutile."
On le dit depuis trois ans. Les modèles se sont énormément améliorés et continuent d'évoluer, mais ils ne peuvent pas deviner que votre équipe a choisi des facade services plutôt que des services plats, ou que votre pipeline utilise des templates réutilisables avec un nommage spécifique. Les modèles s'améliorent pour la généralisation. Votre projet n'est pas général. Le contexte explicite l'emportera toujours sur le contexte inféré parce que les décisions DE VOTRE équipe n'existent pas dans les données d'entraînement de n'importe quel modèle.
"Notre projet est trop complexe."
Vous n'avez pas besoin de tout documenter. Trente lignes avec cinq conventions principales et trois patterns interdits font déjà une différence mesurable. Le principe 80/20 s'applique parfaitement ici. Un architecture.md n'est pas un livre — c'est une page.
Un point important : le prompting et le context engineering ne sont pas des ennemis. Ce sont des couches. Le contexte est la base. Le prompt est la finition. Mais sans base solide, aucune finition ne sauvera le résultat.
Conclusion
Sur un marché où tout le monde a accès aux mêmes modèles, l'avantage compétitif de votre équipe avec l'IA ne tient pas à l'outil que vous utilisez ni à qui écrit les meilleurs prompts. Il tient à qui fournit le meilleur contexte.
Un architecture.md n'est pas de la bureaucratie. Ce n'est pas de la documentation pour la documentation. C'est de l'infrastructure — comme votre pipeline CI, comme votre linter, comme vos tests. On l'écrit une fois, on le maintient avec un effort minimum, et il multiplie la qualité de toutes les interactions futures avec n'importe quel AI tool qui apparaîtra.
L'IA n'a pas créé un nouveau problème. Elle a rendu visible un problème qui a toujours existé : le savoir implicite qui vit dans la tête des personnes ne scale pas. Avant, le coût était un onboarding lent et des décisions inconsistantes. Maintenant, le coût est des outputs d'IA inutilisables et du temps perdu à les corriger. Même problème, manifestation différente. Et même solution : rendre explicite l'implicite.
Les équipes qui investissent aujourd'hui dans un contexte structuré auront un avantage composé pendant des années. Chaque nouveau modèle leur profitera davantage. Chaque nouvel outil sera plus utile. Chaque nouveau membre de l'équipe sera productif plus tôt.
Collectionner cent prompts magiques optimise cent questions.
Un architecture.md optimise toutes les réponses.
Prochaine étape
Si cet article vous a été utile, chaque semaine je publie des analyses pratiques sur l'architecture enterprise et l'IA appliquée. Pragmatique. Sans hype. Pour des seniors qui construisent des systèmes réels.
J'ai créé un template d'architecture.md que vous pouvez adapter à votre projet en trente minutes. Il inclut des sections pour le stack, les conventions, les décisions et des règles spécifiques pour les AI tools.
Publié : Mai 2026