thebeardedbearsas/architect

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 :

• [ ] Pas de cycle (A → B → A)
• [ ] DIP respecté (domain ne dépend pas de l'infra)
• [ ] Pas plus de 3 niveaux d'appel entre entrée et côté métier

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 :

1. Diagramme dépendances (1 page max)
2. Contrats des frontières (signatures + DTO)
3. ADR court trade-offs principaux
4. Liste de tests d'architecture
5. Découpage en tâches atomiques (voir skill atomic-tasks)

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 @tech-lead |

Intégration Claude Craft

• /workflow:design — utilise ce skill par défaut
• Agent @tech-lead — 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 (ADR)
• Skill atomic-tasks

---

Date de dernière mise à jour : 2026-04-15 Version : 1.0.0