Développement Piloté par Spécifications

Les spécifications vivent dans .claude/specs/. Elles sont la source de vérité pour les décisions architecturales, les contrats API et la portée de l'implémentation. L'implémentation et les spécifications doivent rester synchronisées — aucune n'est exclusive.

Boucle Principale

Lire spec → Implémenter → Vérifier l'alignement → Mettre à jour spec ou code → Recommencer

Avant de Commencer le Travail

1. Trouvez la spec. Cherchez dans .claude/specs/ des fichiers correspondant à la fonctionnalité :

ls .claude/specs/

2. Lisez la spec complète. Comprenez la portée, les décisions, les contrats API et les questions ouvertes avant d'écrire du code.

3. Si aucune spec n'existe et la tâche est non triviale (nouveau module, nouvel API, changement architectural), demandez à l'utilisateur s'il faut en créer une d'abord.

Pendant l'Implémentation

• Référencez les décisions de la spec — ne redécidez pas ce que la spec a déjà établi.
• Quand vous divergez de la spec (meilleure approche trouvée, changement demandé par l'utilisateur, contrainte découverte), mettez à jour la spec immédiatement dans la même session. Ne laissez pas la spec et le code désynchronisés.
• Cochez les cases TODO (- [ ] → - [x]) au fur et à mesure que les éléments sont complétés.
• Barrez ou annotez les éléments volontairement ignorés ou remplacés, avec une brève raison :

  - [x] ~~Proxy OpenRouter~~ → Exécution directe : les nœuds appellent OpenRouter directement

Après Avoir Complété le Travail

Exécutez un passage de vérification de spec :

1. Relisez la spec aux côtés de l'implémentation.
2. Vérifiez chaque section :
   • Les endpoints API de la spec correspondent-ils au contrôleur ?
   • Les variables config/env de la spec correspondent-elles à la classe de configuration ?
   • La structure du module de la spec correspond-elle à l'arborescence réelle ?
   • Les définitions de type de la spec correspondent-elles à @n8n/api-types ?
   • Tous les éléments TODO sont-ils correctement cochés/décochés ?
3. Mettez à jour la spec pour toute divergence trouvée. Divergences courantes :
   • Nouveaux fichiers ajoutés qui ne sont pas listés dans la section structure
   • Formes de réponse API modifiées pendant l'implémentation
   • Valeurs par défaut de config ajustées
   • Décisions architecturales affinées
4. Signalez les lacunes non résolues à l'utilisateur — des choses que la spec promet mais que l'implémentation ne livre pas encore (acceptable pour MVP, mais devrait être noté).

Conventions des Fichiers de Spécification

• Un ou plusieurs fichiers markdown par fonctionnalité dans .claude/specs/.
• Gardez les specs concises. Utilisez des tableaux pour les mappages, des blocs de code pour les formes.
• Utilisez ## Implementation TODO avec des cases à cocher pour suivre la progression.
• Divisez en plusieurs fichiers quand cela aide (par exemple backend/frontend séparés), mais n'imposez pas de schéma de nommage rigide.

Quand l'Utilisateur Demande une « Auto-Révision » ou une « Vérification Contre la Spec »

1. Lisez toutes les specs pertinentes.
2. Lisez tous les fichiers d'implémentation.
3. Produisez une comparaison structurée :
   • Alignés : éléments où spec et code correspondent
   • Divergence : éléments où ils divergent (corriger immédiatement)
   • Lacunes : éléments de la spec pas encore implémentés (noter comme travail futur)
4. Corrigez la divergence, mettez à jour les specs, rapportez les lacunes à l'utilisateur.