Développement Orienté par le Contexte

Guide pour implémenter et maintenir le contexte en tant qu'artefact géré aux côtés du code, permettant des interactions IA cohérentes et l'alignement d'équipe par une documentation de projet structurée.

Quand Utiliser Cette Compétence

• Mettre en place de nouveaux projets avec Conductor
• Comprendre les relations entre artefacts de contexte
• Maintenir la cohérence entre sessions de développement assistées par IA
• Intégrer des membres d'équipe à un projet Conductor existant
• Décider quand mettre à jour les documents de contexte
• Gérer les contextes de projets greenfield vs brownfield

Philosophie Fondamentale

Le Développement Orienté par le Contexte traite le contexte du projet comme un artefact de première classe géré aux côtés du code. Au lieu de s'appuyer sur des prompts ad hoc ou une documentation dispersée, établissez une fondation persistante et structurée qui informe toutes les interactions IA.

Principes clés :

1. Le contexte précède le code : Définissez ce que vous construisez et comment avant l'implémentation
2. Documentation vivante : Les artefacts de contexte évoluent avec le projet
3. Source unique de vérité : Un emplacement canonique pour chaque type d'information
4. Alignement IA : Un contexte cohérent produit un comportement IA cohérent

Le Flux de Travail

Suivez le flux de travail Contexte → Spécification et Plan → Implémentation :

1. Phase Contexte : Établir ou vérifier que les artefacts de contexte du projet existent et sont à jour
2. Phase Spécification : Définir les exigences et critères d'acceptation pour les unités de travail
3. Phase Planification : Décomposer les spécifications en tâches phasées et actionnables
4. Phase Implémentation : Exécuter les tâches en suivant les modèles de flux de travail établis

Relations entre Artefacts

product.md - Définit QUOI et POURQUOI

Objectif : Capture la vision produit, les objectifs, les utilisateurs cibles et le contexte commercial.

Contenu :

• Nom du produit et description en une ligne
• Énoncé du problème et approche de solution
• Personas d'utilisateurs cibles
• Fonctionnalités et capacités principales
• Métriques de succès et KPIs
• Roadmap produit (haut niveau)

Mettre à jour quand :

• La vision ou les objectifs produit changent
• De nouvelles fonctionnalités majeures sont planifiées
• L'audience cible change
• Les priorités commerciales évoluent

product-guidelines.md - Définit COMMENT Communiquer

Objectif : Établit la voix de marque, les standards de messaging et les modèles de communication.

Contenu :

• Directives de voix et de ton de marque
• Terminologie et glossaire
• Conventions de messages d'erreur
• Standards de contenu orienté utilisateur
• Style de documentation

Mettre à jour quand :

• Les directives de marque changent
• Une nouvelle terminologie est introduite
• Les modèles de communication nécessitent un affinage

tech-stack.md - Définit AVEC QUOI

Objectif : Documente les choix technologiques, les dépendances et les décisions architecturales.

Contenu :

• Langages primaires et frameworks
• Dépendances clés avec versions
• Infrastructure et cibles de déploiement
• Outils de développement et environnement
• Frameworks de test
• Outils de qualité de code

Mettre à jour quand :

• Vous ajoutez de nouvelles dépendances
• Vous mettez à niveau des versions majeures
• Vous changez d'infrastructure
• Vous adoptez de nouveaux outils ou modèles

workflow.md - Définit COMMENT Travailler

Objectif : Établit les pratiques de développement, les portes de contrôle qualité et les flux de travail d'équipe.

Contenu :

• Méthodologie de développement (TDD, etc.)
• Flux Git et conventions de commit
• Exigences de révision de code
• Exigences de test et cibles de couverture
• Portes d'assurance qualité
• Procédures de déploiement

Mettre à jour quand :

• Les pratiques d'équipe évoluent
• Les standards de qualité changent
• De nouveaux modèles de flux de travail sont adoptés

tracks.md - Suit CE QUI SE PASSE

Objectif : Registre de toutes les unités de travail avec statut et métadonnées.

Contenu :

• Tracks actives avec statut actuel
• Tracks complétées avec dates de fin
• Métadonnées de track (type, priorité, assigné)
• Liens vers les répertoires de tracks individuels

Mettre à jour quand :

• De nouvelles tracks sont créées
• Le statut d'une track change
• Les tracks sont complétées ou archivées

Voir references/artifact-templates.md pour les modèles de démarrage à copier-coller.

Principes de Maintenance du Contexte

Garder les Artefacts Synchronisés

Assurez-vous que les changements dans un artefact se reflètent dans les documents associés :

• Nouvelle fonctionnalité dans product.md → Mettre à jour tech-stack.md si nouvelles dépendances nécessaires
• Track complétée → Mettre à jour product.md pour refléter les nouvelles capacités
• Changement de flux de travail → Mettre à jour tous les plans de tracks affectés

Mettre à Jour tech-stack.md Lors de l'Ajout de Dépendances

Avant d'ajouter une nouvelle dépendance :

1. Vérifier si les dépendances existantes résolvaient le besoin
2. Documenter la justification des nouvelles dépendances
3. Ajouter les contraintes de version
4. Noter tout exigence de configuration

Mettre à Jour product.md Quand les Fonctionnalités sont Complètes

Après la fin d'une track de fonctionnalité :

1. Déplacer la fonctionnalité de « planifiée » à « implémentée » dans product.md
2. Mettre à jour toutes les métriques de succès affectées
3. Documenter les changements de portée du plan original

Vérifier le Contexte Avant l'Implémentation

Avant de commencer une track :

1. Lire tous les artefacts de contexte
2. Signaler toute information obsolète
3. Proposer des mises à jour avant de procéder
4. Confirmer la précision du contexte avec les parties prenantes

Gestion Greenfield vs Brownfield

Projets Greenfield (Nouveaux)

Pour les nouveaux projets :

1. Exécuter /conductor:setup pour créer tous les artefacts de manière interactive
2. Répondre aux questions sur la vision produit, les préférences technologiques et le flux de travail
3. Générer les guides de style initiaux pour les langages choisis
4. Créer un registre de tracks vide

Caractéristiques :

• Contrôle complet sur la structure du contexte
• Définir les standards avant que le code n'existe
• Établir les modèles tôt

Projets Brownfield (Existants)

Pour les codebases existantes :

1. Exécuter /conductor:setup avec détection de codebase existante
2. Le système analyse le code existant, les configs et la documentation
3. Pré-remplir les artefacts en fonction des modèles découverts
4. Réviser et affiner le contexte généré

Caractéristiques :

• Extraire le contexte implicite du code existant
• Concilier les modèles existants avec les modèles souhaités
• Documenter la dette technique et les plans de modernisation
• Préserver les modèles fonctionnels tout en établissant les standards

Avantages

Alignement d'Équipe

• Les nouveaux membres d'équipe intègrent plus rapidement avec un contexte explicite
• Terminologie et conventions cohérentes dans l'équipe
• Compréhension partagée des objectifs produit et des décisions techniques

Cohérence IA

• Les assistants IA produisent des résultats alignés entre les sessions
• Besoin réduit de réexpliquer le contexte dans chaque interaction
• Comportement prévisible basé sur les standards documentés

Mémoire Institutionnelle

• Les décisions et justifications sont préservées
• Le contexte survit aux changements d'équipe
• Le contexte historique informe les décisions futures

Assurance Qualité

• Les standards sont explicites et vérifiables
• Les écarts par rapport au contexte sont détectables
• Les portes de qualité sont documentées et applicables

Structure de Répertoire

conductor/
├── index.md              # Hub de navigation liant tous les artefacts
├── product.md            # Vision et objectifs produit
├── product-guidelines.md # Standards de communication
├── tech-stack.md         # Préférences technologiques
├── workflow.md           # Pratiques de développement
├── tracks.md             # Registre d'unités de travail
├── setup_state.json      # État de setup reprendre
├── code_styleguides/     # Conventions spécifiques au langage
│   ├── python.md
│   ├── typescript.md
│   └── ...
└── tracks/
    └── <track-id>/
        ├── spec.md
        ├── plan.md
        ├── metadata.json
        └── index.md

Cycle de Vie du Contexte

1. Création : Configuration initiale via /conductor:setup
2. Validation : Vérifier avant chaque track
3. Évolution : Mettre à jour au fur et à mesure que le projet grandit
4. Synchronisation : Garder les artefacts alignés
5. Archivage : Documenter les décisions historiques

Liste de Contrôle de Validation du Contexte

Avant de commencer l'implémentation sur une track, validez le contexte :

Contexte Produit

• [ ] product.md reflète la vision produit actuelle
• [ ] Les utilisateurs cibles sont décrits avec précision
• [ ] La liste des fonctionnalités est à jour
• [ ] Les métriques de succès sont définies

Contexte Technique

• [ ] tech-stack.md liste toutes les dépendances actuelles
• [ ] Les numéros de version sont exacts
• [ ] Les cibles d'infrastructure sont correctes
• [ ] Les outils de développement sont documentés

Contexte de Flux de Travail

• [ ] workflow.md décrit les pratiques actuelles
• [ ] Les portes de qualité sont définies
• [ ] Les cibles de couverture sont spécifiées
• [ ] Les conventions de commit sont documentées

Contexte de Track

• [ ] tracks.md affiche tous les travaux actifs
• [ ] Pas de tracks obsolètes ou abandonnées
• [ ] Les dépendances entre tracks sont notées

Anti-Modèles Courants

Évitez ces erreurs de gestion du contexte :

Contexte Obsolète

Problème : Les documents de contexte deviennent obsolètes et trompeurs. Solution : Mettre à jour le contexte dans le cadre du processus de fin de chaque track.

Éparpillement du Contexte

Problème : L'information est dispersée sur plusieurs emplacements. Solution : Utiliser la structure d'artefacts définie ; résister à la création de nouveaux types de documents.

Contexte Implicite

Problème : S'appuyer sur des connaissances non capturées dans les artefacts. Solution : Si vous référencez quelque chose à répétition, l'ajouter à l'artefact approprié.

Accumulation de Contexte

Problème : Une personne maintient le contexte sans apport d'équipe. Solution : Réviser les artefacts de contexte dans les pull requests ; rendre les mises à jour collaboratives.

Sur-Spécification

Problème : Le contexte devient tellement détaillé qu'il est impossible à maintenir. Solution : Garder les artefacts focalisés sur les décisions qui affectent le comportement IA et l'alignement d'équipe.

Intégration avec les Outils de Développement

Intégration IDE

Configurer votre IDE pour afficher les fichiers de contexte de manière visible :

• Épingler conductor/product.md pour référence rapide
• Ajouter tech-stack.md aux notes du projet
• Créer des snippets pour les modèles courants à partir des guides de style

Hooks Git

Considérer les hooks de pré-commit qui :

• Avertissent quand les dépendances changent sans mise à jour de tech-stack.md
• Rappellent de mettre à jour product.md quand les branches de fonctionnalité fusionnent
• Valident la syntaxe des artefacts de contexte

Intégration CI/CD

Inclure la validation du contexte dans les pipelines :

• Vérifier que tech-stack.md correspond aux dépendances réelles
• Vérifier que les liens dans les documents de contexte sont valides
• S'assurer que le statut tracks.md correspond à l'état des branches git

Continuité de Session

Conductor supporte le développement multi-session par la persistance du contexte :

Commencer une Nouvelle Session

1. Lire index.md pour vous orienter
2. Vérifier tracks.md pour les travaux actifs
3. Réviser le plan.md de la track pertinente pour la tâche actuelle
4. Vérifier que les artefacts de contexte sont à jour

Terminer une Session

1. Mettre à jour plan.md avec la progression actuelle
2. Noter tout blocage ou décision prise
3. Commiter le travail en cours avec un statut clair
4. Mettre à jour tracks.md si le statut a changé

Gestion des Interruptions

Si interrompu au milieu d'une tâche :

1. Marquer la tâche comme [~] avec une note sur le point d'arrêt
2. Commiter le travail en cours vers la branche de fonctionnalité
3. Documenter les décisions non commitées dans plan.md

Bonnes Pratiques

1. Lire le contexte en premier : Toujours lire les artefacts pertinents avant de commencer le travail
2. Petites mises à jour : Faire des changements de contexte incrémentiels, pas des rédactions massives
3. Lier les décisions : Référencer le contexte quand vous prenez des choix d'implémentation
4. Versioner le contexte : Commiter les changements de contexte aux côtés des changements de code
5. Réviser le contexte : Inclure les révisions d'artefacts de contexte dans les révisions de code
6. Valider régulièrement : Exécuter la liste de contrôle de validation du contexte avant les travaux importants
7. Communiquer les changements : Notifier l'équipe quand les artefacts de contexte changent significativement
8. Préserver l'historique : Utiliser git pour suivre l'évolution du contexte au fil du temps
9. Remettre en question l'obsolescence : Si le contexte semble incorrect, enquêter et mettre à jour
10. Garder l'aspect actionnable : Chaque élément de contexte doit informer une décision ou un comportement