diff --git a/docs/ORGANISATION.md b/docs/ORGANISATION.md new file mode 100644 index 0000000..4dc32a5 --- /dev/null +++ b/docs/ORGANISATION.md @@ -0,0 +1,92 @@ +# FabNum v2 — Organisation du travail + +## Principes + +Le contexte du projet va croître significativement (12 points d'évolution × specs + plans + code + tests). +Pour maintenir la cohérence dans le temps, le travail repose sur des **agents indépendants** orchestrés +depuis la conversation principale. + +## Rôles + +### Stéphan (humain) +- Vision produit, arbitrage, validation des spécifications +- Expertise métier (chaînes d'approvisionnement, minerais critiques, risques géopolitiques) +- Décision finale sur tous les choix + +### Conversation principale (Claude Code) +- **Orchestrateur** — maintient la vision d'ensemble, briefe les agents, vérifie la cohérence entre les points +- Présente les résultats à Stéphan pour validation +- Ne fait PAS l'implémentation directement sauf cas trivial + +### Agents indépendants +- **Exécutants spécialisés** — recherche, implémentation, revue, tests +- Reçoivent un brief ciblé avec uniquement le contexte nécessaire +- Lisent les fichiers de specs au moment de l'exécution (pas de contexte périmé) +- Leurs résultats sont toujours validés par Stéphan avant intégration + +## Source de vérité + +Les **documents écrits** (docs/) sont la source de vérité, pas les conversations. + +| Document | Rôle | +| --- | --- | +| `docs/EVOLUTIONS.md` | Vision, quoi/pourquoi de chaque point | +| `docs/EVOLUTIONS-PLANIFICATION.md` | Macro-planification, phases, MVP | +| `docs/specs/point-XX-*.md` | Spécifications formelles par point | +| `docs/plans/point-XX-*.md` | Plans d'implémentation par point | +| `docs/architecture-globale.dot` | Architecture des modules | +| `CLAUDE.md` | Conventions de code et workflow | + +## Cycle de travail par point + +Chaque point d'évolution suit le cycle : + +``` +1. Brainstorming ciblé → Stéphan + orchestrateur + (approfondir le quoi, cas limites, choix à trancher) + +2. Spécification formelle → Agent rédacteur + validation Stéphan + (spec précise dans docs/specs/) + +3. Plan d'implémentation → Agent planificateur + validation Stéphan + (étapes techniques dans docs/plans/) + +4. Implémentation → Agent(s) développeur(s) + (code, en worktree isolé si pertinent) + +5. Revue indépendante → Agent revieweur (n'a PAS participé à l'implémentation) + (qualité, cohérence avec la spec, sécurité) + +6. Validation → Stéphan + (résultat final, merge si OK) +``` + +## Règles de briefing des agents + +Un agent indépendant doit recevoir : + +1. **L'objectif** — ce qu'on attend de lui (recherche, code, revue...) +2. **Les fichiers à lire** — les specs pertinentes, pas tout le projet +3. **Les contraintes** — budget zéro, open source, conventions de code +4. **Le périmètre** — ce qu'il doit faire ET ce qu'il ne doit pas toucher +5. **Le format de sortie** — rapport, code, plan, diff... + +Un agent ne doit **jamais** : +- Modifier des fichiers hors de son périmètre +- Prendre des décisions architecturales sans que Stéphan ait validé +- Commiter directement (sauf instruction explicite) + +## Parallélisation + +Les agents peuvent travailler en parallèle sur des points indépendants. +Exemple pour la phase 1 : +- Agent A : revue de littérature pour le point 7 (niveaux) +- Agent B : spike technique sur les bases de données (point 6) + +Les résultats sont consolidés par l'orchestrateur avant de passer à la phase suivante. + +## Cohérence + +- Après chaque implémentation significative, un **agent de cohérence** relit les specs des points adjacents pour vérifier qu'aucune décision ne les invalide. +- Les specs sont mises à jour si des découvertes en implémentation imposent des ajustements (avec validation Stéphan). +- Le fichier `EVOLUTIONS.md` reste le document de référence global et est mis à jour en conséquence.