Guide de Méthodologie : Développement par Tranches Verticales (Vertical Slice Workflow)

Documentation technique

1. Contexte et Fondements : Les 3 Approches Majeures1/3

L’industrie du logiciel s’articule aujourd’hui autour de trois paradigmes principaux pour structurer le travail des équipes :

Spec-Driven Development (SDD) (Ex: Microsoft, Azure, équipes Platform)
- Flux : spec → contract → tasks → code → tests
- Principe : La spécification reste la source de vérité, pas le code. Le workflow est itératif par domaine fonctionnel (ex: “Orders”) et non par couche technique.

1. Contexte et Fondements : Les 3 Approches Majeures2/3

Documentation-as-Code (Docs-as-Code) (Ex: GitLab, Stripe, équipes Infra)
- Principe : La documentation est versionnée, testée et intégrée au CI/CD. Chaque Pull Request (PR) exige la mise à jour de la documentation associée.
- Règle des ADR : Les Architecture Decision Records sont append-only (on n’édite jamais une décision acceptée, on en rédige une nouvelle qui la supplante).

1. Contexte et Fondements : Les 3 Approches Majeures3/3

Contract-First / API-First (Ex: équipes Microservices)
- Principe : Définition préalable des contrats (OpenAPI, schémas, types) avant l’implémentation. Les tests de contrat garantissent l’alignement de l’implémentation avec la spécification.

2. Le Cœur de la Méthodologie : Le Vertical Slice Workflow

Pour une architecture à trois couches présentant de fortes dépendances, l’approche par couches techniques (ex: faire toute la couche 1, puis la 2, puis la 3) est proscrite.

La méthodologie retenue est le Workflow par Tranches Verticales (Vertical Slice). Le développement s’effectue par flux fonctionnel vertical de bout en bout (end-to-end), intégrant simultanément le schéma de données, la route frontend, le worker backend et les tests associés.

Plan de Déploiement par Tranches (Slices)1/2

L’implémentation suit un ordre strict, du plus fondamental au plus dépendant :

Ordre	Slice (Tranche Verticale)	Composants clés
1	Schéma Sanity “page” (vitrine)	Route Astro `index.astro` + Middleware (preview)
2	Schéma Sanity “post” (blog)	Routes `blog/` + Indexation Pagefind
3	Schéma Sanity “project” (portfolio)	Route `portfolio/`
4	Formulaire de contact	Worker `form-handler` + Turnstile

Plan de Déploiement par Tranches (Slices)2/2

Ordre	Slice (Tranche Verticale)	Composants clés
5	Upload de médias	Worker `media-upload` + R2
6	Webhook Sanity	Worker `cms-webhook-receiver` + CI/CD
7	Backup & Cleanup	Workers cron + Alerting
8	Documentation & Recherche	Starlight + Intégration recherche unifiée

3. Cycle de Vie d’un Objet (Phase 1)

Pour chaque objet composant une tranche, le cycle strict suivant doit être appliqué : DOC → SPEC → CODE → TEST → INTÉG.

Étape 1 — DOC : La Fiche d’Objet

Action : Transformer le template générique en fiche d’objet concrète (ex: post-schema.md) en remplaçant tous les placeholders par les valeurs réelles.
Règle d’or : La fiche d’objet est la source de vérité absolue. Le code ne doit jamais diverger de la fiche. Tout changement de code exige une mise à jour préalable de la fiche.

Étape 2 — SPEC : Contrats d’Entrée/Sortie

Avant toute ligne de code, le contrat est documenté :

Inputs : Paramètres, headers, body.
Outputs : Status codes, headers de réponse, body.
Side effects : Écritures KV, Queues, R2, Webhooks.
Erreurs : Cas d’erreur et codes HTTP associés.
Note : Un test de contrat peut être rédigé avant le code.

Étape 3 — CODE : Implémentation

Action : Développement strictement guidé par la fiche d’objet. Aucune supposition n’est permise ; la fiche dicte l’implémentation.

Étape 4 — TEST : Validation à 3 Niveaux

Niveau	Moment d’exécution	Méthodologie
Unitaire	Immédiatement après le code	Vitest / Testing Library (composants) ; tests isolés pour Workers (`wrangler dev` + `curl`).
Intégration	Avant de passer à l’objet suivant du même slice	Test de l’objet avec ses dépendances directes (ex: schéma Sanity + requête GROQ + rendu Astro).
End-to-End (E2E)	À la fin du slice complet	Playwright : parcours utilisateur réel (ex: publier un article → webhook → rebuild → recherche Pagefind).

Étape 5 — INTÉG : Vérification de Cohérence

Action : “Integration check” pour s’assurer que le nouvel objet ne casse aucun objet existant. Relance des tests E2E des slices précédents.

4. Critères d’Acceptation : Definition of Done (Phase 2)

Une tranche (slice) n’est considérée comme terminée que lorsque tous les critères suivants sont validés :

Toutes les fiches d’objets sont complètes et cohérentes.
Tous les objets sont codés et typés (TypeScript strict, aucun any).
Les tests unitaires passent (couverture > 80% sur la logique métier).
Les tests d’intégration du slice passent.
Les tests E2E du parcours complet passent.
La documentation est à jour (fiches + README si nécessaire).
Un ADR (Architecture Decision Record) est rédigé si une décision technique a été prise ou modifiée.

5. Stratégie de Lancement : Le “Golden Path” (Phase 3)1/2

Pour optimiser les ressources (équipe restreinte ou développeur seul), il est impératif de définir et stabiliser un “Golden Path” (parcours minimal viable) avant d’aborder les fonctionnalités secondaires.

5. Stratégie de Lancement : Le “Golden Path” (Phase 3)2/2

Le Golden Path à implémenter en priorité :

Page d’accueil (vitrine) : SSG, contenu Sanity.
Article de blog : SSG, contenu Sanity, rendu Portable Text.
Recherche Pagefind : Indexation d’au moins ces 2 pages.
Mode Preview : Prévisualisation pour les contributeurs.
Webhook de rebuild : Déclenchement automatique du build à la publication.

Les fonctionnalités annexes (portfolio, contact, médias, backups, etc.) ne sont abordées qu’une fois le Golden Path stable.

6. Routine Quotidienne et Outillage

Workflow Quotidien Type1/2

Matin :
1. Sélection de l’objet du jour (dans le slice en cours).
2. Ouverture de la fiche d’objet associée.
3. Vérification du statut des dépendances en amont.
Phase DOC (30-60 min) : 4. Complétion de la fiche avec les valeurs réelles. 5. Définition des contrats d’entrée/sortie. 6. Rédaction des cas de test attendus.

Workflow Quotidien Type2/2

Phase CODE (2-4h) : 7. Implémentation guidée par la fiche. 8. Tests unitaires itératifs.
Phase INTÉG (30-60 min) : 9. Tests d’intégration avec les objets liés du même slice. 10. Mise à jour de la fiche si la réalité technique a divergé.
Fin de journée : 11. Commit formaté : slice[X]-objet[Y]: implémentation + fiche à jour. 12. Vérification du statut du CI.

Stack d’Outils Recommandée1/2

Besoin	Outil	Justification
Suivi (Slices/Objets)	GitHub Projects / Notion / Linear	Kanban avec colonnes : Backlog → Doc → Code → Test → Intégré.
Fiches d’objets	Markdown dans Git (`docs/`)	Versionné, diffable, reviewable via PR.
Tests	Vitest + Playwright + `wrangler dev`	Tests Unitaires + E2E + environnement local pour Workers.
CI/CD	GitHub Actions	Build, tests et déploiement automatique.
ADR	`docs/adr/YYYY-MM-DD-titre.md`	Historique append-only, avec liens croisés entre décisions.

Stack d’Outils Recommandée2/2

Conclusion La réussite d’un projet ne repose pas sur la perfection théorique de son architecture, mais sur la capacité à livrer des flux verticaux complets et fonctionnels, puis à itérer. L’architecture doit être découpée en morceaux livrables de manière incrémentale, slice par slice, objet par objet.