Architect — Phase d'architecture avant TDD
Skill inspiré de
obra/superpowers.
Objectif : produire une spec d'architecture avant d'écrire le moindre test ou ligne de code.
Règle d'or : si tu ne peux pas dessiner le diagramme, tu ne peux pas coder la feature.
Quand utiliser
| Situation | Architect phase ? |
|---|
| Bug 1 fichier | ❌ Non (go direct TDD) |
| Nouvelle feature < 3 fichiers | ⚠️ Court (10 min) |
| Nouvelle feature > 3 fichiers | ✅ Obligatoire |
| Nouveau module/bounded context | ✅ Obligatoire |
| Migration technique | ✅ Obligatoire |
| Intégration externe (API, MQ, DB) | ✅ Obligatoire |
Processus en 5 étapes
1. Identifier les boundaries
Quelles frontières la feature touche-t-elle ?
- Domain boundaries — quels bounded contexts impliqués ?
- Layer boundaries — Presentation / Application / Domain / Infrastructure ?
- Process boundaries — sync HTTP / async queue / event-driven ?
- Data boundaries — quelles bases de données, quelles tables ?
- Ownership boundaries — quelle équipe owne quel morceau ?
Output : liste des frontières traversées.
2. Définir les contrats
Pour chaque frontière traversée, définir le contrat :
- Inputs : format, types, invariants, nullabilité
- Outputs : format, codes d'erreur, latence cible
- Side effects : écritures DB, events émis, appels externes
- Idempotence : le contrat est-il idempotent ?
- Transactions : atomique ? eventually consistent ?
Output : signatures de fonctions/endpoints + DTO.
3. Dessiner les dépendances
Qui dépend de quoi ? Dans quel sens ?
[HTTP Controller] ──▶ [Use Case] ──▶ [Domain Service]
│
▼
[Repository] (interface)
│
▼
[Postgres Adapter] ─implements─▶
Vérifier :
Output : diagramme (Mermaid, ASCII, ou texte structuré).
4. Lister les trade-offs
Pour chaque décision non évidente, documenter pourquoi ce choix :
| Décision | Alternative envisagée | Pourquoi ce choix |
|---|
| Async via queue | Sync HTTP | Latence >500ms, pas critique immédiat |
| CQRS | CRUD simple | Ratio 20:1 lecture/écriture |
| Event sourcing | Store état | Besoin audit légal |
Output : ADR léger (3-5 bullets) — voir
.claude/rules/10-documentation.md
pour ADR formel si décision majeure.
5. Définir les tests d'architecture
Avant TDD sur le comportement, définir les tests d'architecture :
- Tests de dépendances (ArchUnit, Dephpend, deptrac)
- Tests de contrats (OpenAPI validation, contract tests)
- Tests de performance cibles (latence p99, throughput)
- Tests d'isolation multitenant si applicable
Output : liste de tests d'architecture à écrire en Phase TDD.
Livrables
À la fin de la phase Architect, produire :
- Diagramme dépendances (1 page max)
- Contrats des frontières (signatures + DTO)
- ADR court trade-offs principaux
- Liste de tests d'architecture
- Découpage en tâches atomiques (voir skill )
Ce n'est qu'après qu'on rentre dans le TDD (Red/Green/Refactor).
Anti-patterns
| Anti-pattern | Solution |
|---|
| Coder directement sans diagramme | Dessiner AVANT, même 5 min suffisent |
| Architect phase > 2h sur feature simple | YAGNI — couper court |
| Contrats flous ("objet User") | Types stricts, tous les champs |
| Ignorer les trade-offs | ADR court obligatoire |
| Architecture en vase clos | Review par un pair ou subagent |
Intégration Claude Craft
- — utilise ce skill par défaut
- Agent — peut produire l'output Architect
- ADR formel : voir
/common:architecture-decision
- Rule 04 SOLID + Rule 17 CQRS + Rule 14 Multitenant — consulter selon contexte
Ressources
- obra/superpowers
- Rule
.claude/rules/04-solid-principles.md
- Rule
.claude/rules/10-documentation.md
- Skill
Date de dernière mise à jour : 2026-04-15
Version : 1.0.0