rtaffe28/arch-plan

Plan architecture-first

Le plan répond avant tout à deux questions : quels sont les composants et comment se connectent-ils (diagrammes), et quels sont les contrats exacts entre eux (interfaces). Les listes de tâches sont secondaires ; un implémenteur compétent peut les dériver à partir de bonnes interfaces.

Les plans sont locaux et personnels : ~/plans/<AAAA-MM-JJ>-<slug>/. Le fichier markdown est la source de vérité. L'Artifact en est une vue.

1. Comprendre la demande

• Reformuler l'objectif en une ou deux phrases, plus ce qui est explicitement hors périmètre.
• Si les exigences sont ambiguës, demander (voir Poser des questions ci-dessous). Ne demander que ce qui changerait la conception. Faire un autre tour si les réponses ouvrent de nouvelles embranchements.
• Lorsqu'un bon défaut dépend de ce que le code fait déjà, faire d'abord un rapide passage de l'étape 2, afin que vos recommandations soient ancrées dans le dépôt plutôt que devinées.

Poser des questions

Chaque question à l'utilisateur, à cette étape, après le débat, et en itérant, passe par l'outil AskUserQuestion, jamais sous forme de liste dans le chat. L'utilisateur doit pouvoir répondre à la plupart d'entre elles en un clic :

• Préremplir une recommandation. Faire de l'option que vous choisiriez la première, avec (Recommandé) à la fin de son libellé. Se baser sur les motifs existants du code, AGENTS.md, et ce qui garde la conception la plus simple.
• 2 à 4 options concrètes par question, chacune un vrai choix, avec une description qui dit ce que cela signifie pour la conception (par exemple « ajoute une migration », « réutilise useCursorFeed »). Ne pas ajouter d'option « Autre » : l'outil en ajoute une pour le texte libre.
• Autonome. L'utilisateur peut ne voir que la boîte de dialogue, donc chaque question nomme la fonctionnalité et l'élément à décider, et dit brièvement ce que vous avez trouvé si c'est ce qui motive la question.
• Jusqu'à 4 questions par appel, avec un court header (≤12 caractères, par ex. « Stockage », « Auth », « Périm »). Regrouper les questions connexes ; faire un autre appel pour le reste.
• Utiliser multiSelect seulement lorsque les options ne sont pas exclusives (par ex. « quelles surfaces obtiennent ceci ? »). Utiliser preview lors de la comparaison d'artefacts concrets : une esquisse d'interface, un schéma, une disposition ASCII.
• Si vous avez une réponse claire et que le choix est peu coûteux à inverser, ne pas demander : décider, et l'enregistrer dans le tableau des décisions.

2. Rassembler le contexte

Dans phave-ng (le checkout principal ou l'arborescence de travail de la stack) :

• Lire d'abord CLAUDE.md, AGENTS.md et .claude/rules/*. Ils codifient des décisions que vous ne devez pas contredire.
• Trouver ce qui existe : les types, services, routes, tables, jobs et composants que la fonctionnalité touche ou pourrait réutiliser. Pour un balayage large, lancer des agents Explore en parallèle, un par domaine, et ne garder que leurs conclusions.
• Noter chaque interface existante que vous allez étendre, avec son chemin:ligne.

3. Taille

	Petit	Grand
Signaux	Un seul domaine du code, environ une PR (moins de ~400 lignes), pas de migration ou une migration triviale	Plusieurs domaines, changements de schéma, nouveaux jobs d'arrière-plan, plus d'une PR, ou plusieurs personnes ou sessions
Sortie	plan.md seulement	plan.md plus slices/01-<nom>.md, slices/02-<nom>.md, ...

Ne pas découper les petits travaux. La cérémonie pour un changement d'une seule PR est du gaspillage.

Pour les gros travaux, couper des tranches verticales : chaque tranche est fusionnable indépendamment, laisse la branche principale fonctionnelle, et livre quelque chose de testable. Une « tranche » uniquement schéma ou une « tranche frontend » n'en est pas une. Ordonner les tranches par dépendance et garder chacune environ une PR.

4. Rédiger le plan

~/plans/<date>-<slug>/plan.md :

# <Titre>

**Statut :** Brouillon | Approuvé | En cours | Terminé
**Taille :** Petit | Grand (N tranches)
**Dépôt / base :** phave-ng @ <commit>

## Objectif
<2-3 phrases> · **Hors périmètre :** <puces>

## Architecture
### Composants
<Diagramme de flux Mermaid : pièces existantes en style simple, nouvelles pièces en surbrillance, pièces modifiées marquées>
### Flux clés
<Diagramme de séquence Mermaid pour chaque flux important, incluant le chemin d'erreur principal>
### Modèle de données
<Diagramme ER Mermaid si des tables ou colonnes changent ; diagramme d'état si quelque chose a un cycle de vie>

## Interfaces
<Chaque contrat que la fonctionnalité ajoute ou modifie, sous forme de code réel dans le langage du dépôt.
 Marquer chacun comme NOUVEAU ou MODIFIÉ, avec son chemin de fichier cible.>
- Types / modèles de domaine
- Fonctions et services : signatures complètes, plus ce qu'ils lèvent
- HTTP / actions serveur : méthode, chemin, types de requête et réponse, auth, codes d'erreur
- Base de données : tables, colonnes, index, politique RLS, nom de migration
- Jobs / événements : nom, type de payload, idempotence, tentatives
- Composants UI : props, et quelle page les rend

## Décisions clés de conception
| Décision | Options considérées | Choisie | Pourquoi |

## Questions ouvertes
- [ ] <question> — qui peut y répondre, et ce qui change selon la réponse

## Tranches        (grand seulement)
| # | Tranche | Livre | Dépend de | Statut |

## Plan (petit seulement)
<Étapes ordonnées ; pour chacune : les interfaces qu'elle implémente, fichiers, et comment elle est testée>

## Stratégie de test
<Ce qui est testé unitairement et ce qui est testé contre une stack (voir `ai-test` / `manual-test`)>

## Risques

Chaque slices/0N-<nom>.md contient : objectif, les interfaces de plan.md qu'il implémente (y faire un lien, ne pas copier), fichiers, étapes ordonnées, critères d'acceptation, tests, et Notes d'implémentation (laissées vides, remplies par implement-plan).

Règles :

• Les diagrammes sont en Mermaid, avec une idée par diagramme. Si un diagramme a besoin de plus de ~12 nœuds, le diviser.
• Les interfaces sont du code, pas de la prose. Nommer des fichiers réels. Réutiliser les types existants quand c'est possible, et le dire.
• Chaque décision qu'un ingénieur raisonnable pourrait prendre différemment va dans le tableau des décisions.
• Les inconnues vont dans les Questions ouvertes, chacune avec la réponse que vous recommanderiez. Ne pas deviner en silence.

5. Débat critique / défenseur

Lancer deux agents en parallèle avec l'outil Agent. Donner à chacun le chemin du plan et les fichiers clés du dépôt à lire, pas vos conclusions :

• Critique : « Trouve ce qui ne va pas. Est-ce que la conception atteint l'objectif ? Les interfaces sont-elles manquantes, fuyantes ou incohérentes avec les motifs du code ? Les tranches sont-elles vraiment verticales ? Y a-t-il une partie sur-ingénierée ou sous-spécifiée, une réutilisation manquée, un mode de défaillance, un risque de migration, un écart de permissions ? Signale chaque problème avec un correctif concret. »
• Défenseur : « Fais la défense la plus solide des choix du plan, surtout là où l'alternative évidente a été rejetée. Nomme ce que le critique est susceptible d'attaquer et pourquoi la conception actuelle tient. »

Puis un tour de réplique : envoyer à chaque agent la sortie de l'autre (SendMessage) et lui demander de concéder ou de maintenir chaque point, avec des raisons.

Vous êtes le juge. Pour chaque point de contention :

• Changement convenu : l'appliquer à plan.md / aux fichiers de tranches.
• Non résolu, et besoin de l'utilisateur : le déplacer dans Questions ouvertes, avec l'option que vous recommanderiez.
• Rejeté : garder la décision, et enregistrer pourquoi dans le tableau des décisions.

Ajouter un ## Résumé du débat à plan.md : point → critique → défenseur → résolution.

6. Présenter comme un Artifact

Charger artifact-design, et artifact-diagramming pour les diagrammes. Publier une page pour révision, dans cet ordre :

1. Titre, statut, taille, et un résumé d'un paragraphe
2. Décisions clés de conception (le tableau)
3. Questions ouvertes : ce dont vous avez besoin de l'utilisateur, en évidence et faciles à trouver
4. Diagrammes d'architecture, rendus, pas de texte Mermaid brut
5. Interfaces, sous forme de code surligné, groupé par couche, avec des badges NOUVEAU / MODIFIÉ
6. Tranches (grand) ou étapes (petit)
7. Faits saillants du débat : seulement les points qui ont changé le plan ou sont encore ouverts
8. Le chemin local de plan.md

Dans le chat, donner le lien. Puis poser les questions ouvertes avec AskUserQuestion (voir Poser des questions), chacune avec les positions du critique et du défenseur comme options et votre recommandation en premier.

7. Itérer jusqu'à approbation

Les réponses et commentaires de l'utilisateur vont d'abord dans plan.md : les questions répondues passent des Questions ouvertes dans le tableau des décisions. Les nouvelles questions soulevées en itérant sont posées de la même manière, avec AskUserQuestion et une option recommandée. Puis republier le même Artifact (même chemin de fichier, donc l'URL reste la même). Quand l'utilisateur approuve, mettre Statut : Approuvé et le diriger vers implement-plan.

Ne pas écrire de code de production dans cette compétence.