Modèles de Workflow

Guide pour implémenter des tâches en utilisant le workflow TDD de Conductor, gérer les checkpoints de phase, gérer les commits git, et exécuter le protocole de vérification qui assure la qualité tout au long de l'implémentation.

Quand utiliser cette compétence

Implémenter des tâches à partir du plan.md d'une track
Suivre le cycle TDD red-green-refactor
Compléter les checkpoints de phase
Gérer les commits git et les notes
Comprendre les portes d'assurance qualité
Gérer les protocoles de vérification
Enregistrer la progression dans les fichiers plan

Cycle de vie des tâches TDD

Suivez ces 11 étapes pour chaque tâche :

Étape 1 : Sélectionner la tâche suivante

Lisez plan.md et identifiez la prochaine tâche [ ] en attente. Sélectionnez les tâches dans l'ordre au sein de la phase actuelle. Ne sautez pas aux phases suivantes.

Étape 2 : Marquer comme en cours

Mettez à jour plan.md pour marquer la tâche comme [~] :

- [~] **Task 2.1**: Implement user validation

Committez ce changement de statut séparément de l'implémentation.

Étape 3 : RED - Écrire les tests qui échouent

Écrivez les tests qui définissent le comportement attendu avant d'écrire l'implémentation :

Créez le fichier de test si nécessaire
Écrivez des cas de test couvrant le cas nominal
Écrivez des cas de test couvrant les cas limites
Écrivez des cas de test couvrant les conditions d'erreur
Exécutez les tests - ils doivent ÉCHOUER

Exemple :

def test_validate_user_email_valid():
    user = User(email="test@example.com")
    assert user.validate_email() is True

def test_validate_user_email_invalid():
    user = User(email="invalid")
    assert user.validate_email() is False

Étape 4 : GREEN - Implémenter le code minimum

Écrivez le code minimum nécessaire pour faire passer les tests :

Concentrez-vous sur le vert, pas la perfection
Évitez l'optimisation prématurée
Gardez l'implémentation simple
Exécutez les tests - ils doivent PASSER

Étape 5 : REFACTOR - Améliorer la clarté

Avec les tests au vert, améliorez le code :

Extrayez les motifs communs
Améliorez la dénomination
Supprimez la duplication
Simplifiez la logique
Exécutez les tests après chaque changement - ils doivent rester VERTS

Étape 6 : Vérifier la couverture

Vérifiez que la couverture de test atteint l'objectif de 80% :

pytest --cov=module --cov-report=term-missing

Si la couverture est inférieure à 80% :

Identifiez les lignes non couvertes
Ajoutez des tests pour les chemins manquants
Réexécutez la vérification de couverture

Étape 7 : Documenter les déviations

Si l'implémentation s'écarte du plan ou a introduit de nouvelles dépendances :

Mettez à jour tech-stack.md avec les nouvelles dépendances
Notez les déviations dans les commentaires de tâche du plan.md
Mettez à jour spec.md si les exigences ont changé

Étape 8 : Committer l'implémentation

Créez un commit focalisé pour la tâche :

git add -A
git commit -m "feat(user): implement email validation

- Add validate_email method to User class
- Handle empty and malformed emails
- Add comprehensive test coverage

Task: 2.1
Track: user-auth_20250115"

Format du message de commit :

Type : feat, fix, refactor, test, docs, chore
Portée : module ou composant affecté
Résumé : impératif, temps présent
Corps : points à puces des changements
Pied de page : références de tâche et track

Étape 9 : Ajouter des notes Git

Ajoutez un résumé de tâche riche comme note git :

git notes add -m "Task 2.1: Implement user validation

Summary:
- Added email validation using regex pattern
- Handles edge cases: empty, no @, no domain
- Coverage: 94% on validation module

Files changed:
- src/models/user.py (modified)
- tests/test_user.py (modified)

Decisions:
- Used simple regex over email-validator library
- Reason: No external dependency for basic validation"

Étape 10 : Mettre à jour le plan avec le SHA

Mettez à jour plan.md pour marquer la tâche complète avec le SHA du commit :

- [x] **Task 2.1**: Implement user validation `abc1234`

Étape 11 : Committer la mise à jour du plan

Committez la mise à jour du statut du plan :

git add conductor/tracks/*/plan.md
git commit -m "docs: update plan - task 2.1 complete

Track: user-auth_20250115"

Protocole de fin de phase

Quand toutes les tâches d'une phase sont complètes, exécutez le protocole de vérification :

Identifier les fichiers modifiés

Listez tous les fichiers modifiés depuis le dernier checkpoint :

git diff --name-only <last-checkpoint-sha>..HEAD

Assurer la couverture de test

Pour chaque fichier modifié :

Identifiez le fichier de test correspondant
Vérifiez que des tests existent pour le code nouveau/modifié
Exécutez la couverture pour les modules modifiés
Ajoutez des tests si la couverture < 80%

Exécuter la suite de tests complète

Exécutez la suite de tests complète :

pytest -v --tb=short

Tous les tests doivent passer avant de continuer.

Générer les étapes de vérification manuelle

Créez une liste de contrôle des vérifications manuelles :

## Checklist de vérification Phase 1

- [ ] L'utilisateur peut s'enregistrer avec un email valide
- [ ] Un email invalide affiche l'erreur appropriée
- [ ] La base de données stocke l'utilisateur correctement
- [ ] L'API retourne les codes de réponse attendus

ATTENDRE l'approbation de l'utilisateur

Présentez la liste de contrôle de vérification à l'utilisateur :

Phase 1 complète. Veuillez vérifier :
1. [ ] La suite de tests passe (automatisé)
2. [ ] La couverture atteint l'objectif (automatisé)
3. [ ] Les éléments de vérification manuelle (nécessite l'intervention humaine)

Répondez avec 'approved' pour continuer, ou notez les problèmes.

Ne procédez PAS sans approbation explicite.

Créer un commit de checkpoint

Après approbation, créez un commit de checkpoint :

git add -A
git commit -m "checkpoint: phase 1 complete - user-auth_20250115

Verified:
- All tests passing
- Coverage: 87%
- Manual verification approved

Phase 1 tasks:
- [x] Task 1.1: Setup database schema
- [x] Task 1.2: Implement user model
- [x] Task 1.3: Add validation logic"

Enregistrer le SHA du checkpoint

Mettez à jour la table de checkpoints dans plan.md :

## Checkpoints

| Phase   | Checkpoint SHA | Date       | Status   |
| ------- | -------------- | ---------- | -------- |
| Phase 1 | def5678        | 2025-01-15 | verified |
| Phase 2 |                |            | pending  |

Portes d'assurance qualité

Avant de marquer une tâche comme complète, vérifiez ces portes :

Tests réussis

Tous les tests existants passent
Les nouveaux tests passent
Aucune régression de test

Couverture >= 80%

Le nouveau code a 80%+ de couverture
La couverture globale du projet est maintenue
Les chemins critiques sont entièrement couverts

Conformité au style

Le code suit les guides de style
Le linting passe
Le formatage est correct

Documentation

Les APIs publiques sont documentées
La logique complexe est expliquée
Le README est mis à jour si nécessaire

Sécurité des types

Les indications de type sont présentes (le cas échéant)
Le vérificateur de type passe
Aucun type: ignore sans raison

Aucune erreur de linting

Zéro erreur de linter
Les avertissements sont traités ou justifiés
L'analyse statique est propre

Compatibilité mobile

Le cas échéant :

La conception réactive est vérifiée
Les interactions tactiles fonctionnent
Les performances sont acceptables

Audit de sécurité

Pas de secrets dans le code
La validation des entrées est présente
L'authentification/autorisation est correcte
Les dépendances sont sans vulnérabilités

Intégration Git

Format du message de commit

<type>(<scope>): <subject>

<body>

<footer>

Types :

feat : Nouvelle fonctionnalité
fix : Correction de bogue
refactor : Changement de code sans fonctionnalité/correction
test : Ajout de tests
docs : Documentation
chore : Maintenance

Notes Git pour les résumés enrichis

Attachez des notes détaillées aux commits :

git notes add -m "<detailed summary>"

Consultez les notes :

git log --show-notes

Avantages :

Préserve le contexte sans encombrer le message de commit
Permet les requêtes sémantiques sur les commits
Supporte les opérations basées sur les tracks

Enregistrement du SHA dans plan.md

Enregistrez toujours le SHA du commit lors de la complétude des tâches :

- [x] **Task 1.1**: Setup schema `abc1234`
- [x] **Task 1.2**: Add model `def5678`

Cela permet :

La traçabilité du plan au code
Les opérations de revert sémantique
L'audit de la progression

Checkpoints de vérification

Pourquoi les checkpoints sont importants

Les checkpoints créent des points de restauration pour la reversion sémantique :

Revert à la fin de n'importe quelle phase
Maintenir l'état du code logique
Permettre l'expérimentation sûre

Quand créer des checkpoints

Créez un checkpoint après :

Toutes les tâches de la phase sont complètes
Toutes les vérifications de la phase passent
L'approbation de l'utilisateur est reçue

Contenu du commit de checkpoint

Incluez dans le commit de checkpoint :

Tous les changements non committés
plan.md mis à jour
metadata.json mis à jour
Toutes les mises à jour de documentation

Comment utiliser les checkpoints

Pour reverter :

# Revert à la fin de Phase 1
git revert --no-commit <phase-2-commits>...
git commit -m "revert: rollback to phase 1 checkpoint"

Pour la revue :

# Voir ce qui a changé en Phase 2
git diff <phase-1-sha>..<phase-2-sha>

Gérer les déviations

Pendant l'implémentation, des déviations du plan peuvent survenir. Gérez-les systématiquement :

Types de déviations

Ajout de portée Exigence découverte non dans la spécification d'origine.

Documentez dans spec.md comme nouvelle exigence
Ajoutez des tâches à plan.md
Notez l'ajout dans les commentaires de tâche

Réduction de portée Fonctionnalité jugée inutile pendant l'implémentation.

Marquez les tâches comme [-] (ignorées) avec raison
Mettez à jour la section portée de spec.md
Documentez la rationale de la décision

Déviation technique Approche d'implémentation différente de celle planifiée.

Notez la déviation dans le commentaire de fin de tâche
Mettez à jour tech-stack.md si les dépendances changent
Documentez pourquoi l'approche d'origine n'était pas appropriée

Changement d'exigence La compréhension de l'exigence change pendant le travail.

Mettez à jour spec.md avec l'exigence corrigée
Ajustez les tâches de plan.md si nécessaire
Re-vérifiez les critères d'acceptation

Format de documentation des déviations

Lors de la complétude d'une tâche avec déviation :

- [x] **Task 2.1**: Implement validation `abc1234`
  - DEVIATION: Used library instead of custom code
  - Reason: Better edge case handling
  - Impact: Added email-validator to dependencies

Récupération d'erreurs

Tests échoués après GREEN

Si les tests échouent après atteinte du GREEN :

NE procédez PAS au REFACTOR
Identifiez quel test a commencé à échouer
Vérifiez si le refactoring a cassé quelque chose
Revenez au dernier état GREEN connu
Réabordez l'implémentation

Rejet du checkpoint

Si l'utilisateur rejette un checkpoint :

Notez la raison du rejet dans plan.md
Créez des tâches pour traiter les problèmes
Complétez les tâches de correction
Demandez à nouveau l'approbation du checkpoint

Bloqué par une dépendance

Si la tâche ne peut pas progresser :

Marquez la tâche comme [!] avec la description du bloqueur
Vérifiez si d'autres tâches peuvent progresser
Documentez la chronologie de résolution attendue
Envisagez de créer une track de résolution de dépendance

Variations TDD par type de tâche

Tâches de modèle de données

RED: Écrivez un test pour la création et la validation du modèle
GREEN: Implémentez la classe de modèle avec les champs
REFACTOR: Ajoutez les propriétés calculées, améliorez les types

Tâches de point de terminaison API

RED: Écrivez un test pour le contrat request/response
GREEN: Implémentez le gestionnaire de point de terminaison
REFACTOR: Extrayez la validation, améliorez la gestion des erreurs

Tâches d'intégration

RED: Écrivez un test pour l'interaction des composants
GREEN: Reliez les composants ensemble
REFACTOR: Améliorez la propagation des erreurs, ajoutez la journalisation

Tâches de refactoring

RED: Ajoutez des tests de caractérisation du comportement actuel
GREEN: Appliquez le refactoring (les tests doivent rester verts)
REFACTOR: Nettoyez toute complexité introduite

Travailler avec des tests existants

Lors de la modification de code avec des tests existants :

Étendre, ne pas remplacer

Gardez les tests existants passant
Ajoutez de nouveaux tests pour le nouveau comportement
Mettez à jour les tests uniquement quand les exigences changent

Migration de tests

Lors du refactoring qui change la structure de test :

Exécutez les tests existants (doivent passer)
Ajoutez de nouveaux tests pour le code refactorisé
Migrez les cas de test vers la nouvelle structure
Supprimez les anciens tests uniquement après que les nouveaux tests passent

Prévention de régression

Après tout changement :

Exécutez la suite de tests complète
Vérifiez les défaillances inattendues
Enquêtez sur les nouvelles défaillances
Corrigez les régressions avant de continuer

Détails de vérification du checkpoint

Vérification automatisée

Exécutez avant de demander l'approbation :

# Suite de tests
pytest -v --tb=short

# Couverture
pytest --cov=src --cov-report=term-missing

# Linting
ruff check src/ tests/

# Vérification de type (le cas échéant)
mypy src/

Orientation pour la vérification manuelle

Pour les éléments manuels, fournissez des instructions spécifiques :

## Étapes de vérification manuelle

### Enregistrement utilisateur

1. Accédez à /register
2. Entrez un email valide : test@example.com
3. Entrez un mot de passe répondant aux exigences
4. Cliquez sur Soumettre
5. Vérifiez que le message de succès s'affiche
6. Vérifiez que l'utilisateur apparaît dans la base de données

### Gestion des erreurs

1. Entrez un email invalide : "notanemail"
2. Vérifiez que le message d'erreur s'affiche
3. Vérifiez que le formulaire conserve les autres données saisies

Considérations de performance

Performance de la suite de tests

Gardez la suite de tests rapide :

Utilisez les fixtures pour éviter la configuration redondante
Mockez les appels externes lents
Exécutez le sous-ensemble pendant le développement, la suite complète aux checkpoints

Performance du commit

Gardez les commits atomiques :

Un changement logique par commit
Pensée complète, pas travail en cours
Les tests doivent passer après chaque commit

Meilleures pratiques

Ne jamais sauter RED : Écrivez toujours les tests défaillants en premier
Petits commits : Un changement logique par commit
Mises à jour immédiates : Mettez à jour plan.md immédiatement après la complétude de la tâche
Attendre l'approbation : Ne sautez jamais la vérification du checkpoint
Notes git enrichies : Incluez le contexte qui aide à la compréhension future
Discipline de couverture : N'acceptez pas une couverture inférieure à l'objectif
Portes qualité : Vérifiez toutes les portes avant de marquer comme complète
Phases séquentielles : Complétez les phases dans l'ordre
Documenter les déviations : Notez tout changement du plan d'origine
État propre : Chaque commit doit laisser le code dans un état de fonctionnement
Feedback rapide : Exécutez les tests pertinents fréquemment pendant le développement
Blocages clairs : Traitez les blocages rapidement, ne les contournez pas