Spec-driven development : la spécification comme constitution de vos agents

Plus un agent est puissant, plus une consigne floue produit de dégâts. C’est le constat qui fait monter en 2026 le spec-driven development (SDD) : au lieu de lancer un agent sur un vague « ajoute cette fonctionnalité », on écrit d’abord une spécification claire, et l’agent s’y conforme. La bonne nouvelle : les outils modernes ont largement absorbé cette pratique, au point qu’elle est devenue native. Voici ce que ça change concrètement.

Le fichier d’instructions comme constitution

Le socle du SDD, c’est le fichier d’instructions projet : CLAUDE.md chez Anthropic, AGENTS.md ailleurs. Il joue le rôle de constitution du projet : conventions d’architecture, règles de qualité, commandes de test, interdits explicites. Chaque agent le lit avant d’agir. Un fichier bien tenu transforme un agent générique en agent qui connaît vos règles — et c’est souvent la différence entre une proposition à jeter et une proposition mergeable. Nous avons détaillé cet art dans notre série sur la maîtrise de CLAUDE.md.

# CLAUDE.md — la constitution du projet

## Architecture
- Couches strictes : Controller → Service → Repository
- Aucune logique métier dans les contrôleurs
- DTO en entrée/sortie, jamais d’entités exposées

## Qualité (non négociable)
- PHPStan niveau max, zéro erreur
- Test qui reproduit le bug AVANT tout correctif (TDD)
- Couverture des nouveaux services : 100 %

## Commandes
- Tests : `docker compose run --rm php bin/phpunit`
- Analyse : `docker compose run --rm php vendor/bin/phpstan`

Ce que Claude Code a absorbé nativement

Le SDD n’est plus un outillage externe à bricoler : les agents modernes l’intègrent. Concrètement, quatre briques travaillent ensemble.

• Le fichier d’instructions sert de constitution — les règles que tout agent respecte.
• Les sous-agents mènent la recherche en parallèle — explorer le code, cartographier l’existant avant d’écrire.
• Le pattern d’interview affine la spec — l’agent pose des questions pour lever les ambiguïtés avant de coder.
• Le système de Tasks natif gère l’implémentation — délégation avec ordre des dépendances et commits atomiques.

Spécifier d’abord, coder ensuite

L’inversion est le cœur du SDD : on investit en amont dans une spécification précise, ce qui réduit drastiquement les allers-retours en aval. Le pattern d’interview illustre bien la logique — plutôt que de deviner et de produire du code à jeter, l’agent clarifie l’intention, les cas limites et les contraintes, puis implémente. Ce temps de cadrage n’est pas du temps perdu : c’est ce qui évite le churn, cette réécriture de code fraîchement produit qui plombe la vélocité réelle des équipes qui adoptent les agents sans méthode.

SDD et sous-agents : un couple naturel

Le spec-driven development et le subagent-driven development se complètent parfaitement. Une spécification claire fournit aux sous-agents les contrats bornés dont ils ont besoin pour travailler en parallèle sans dériver. Sans spec, chaque sous-agent interprète à sa façon et les résultats divergent. Avec une spec, le découpage en tâches devient mécanique, et l’orchestration gagne en fiabilité. La spec est la source de vérité partagée par tous les agents.

Les erreurs classiques

Deux écueils reviennent. Le premier : un fichier d’instructions bavard et jamais mis à jour, que l’agent finit par mal exploiter. Un bon CLAUDE.md est concis, précis et vivant — il encode des règles applicables, pas un roman. Le second : sauter l’étape de spécification pour les tâches complexes, sous prétexte que l’agent « comprendra ». Plus la tâche est ambiguë, plus le cadrage rapporte. La discipline paie exactement là où on est tenté de la contourner.

Le spec-driven development est moins une technologie qu’une culture d’ingénierie appliquée aux agents : dire clairement ce qu’on veut avant de le faire faire. C’est ce que nous installons en atelier — construire une constitution de projet solide, maîtriser le pattern d’interview, articuler spec, sous-agents et Tasks. Les outils sont prêts et natifs ; l’enjeu est d’adopter la discipline qui les rend fiables plutôt que de lancer des agents à l’aveugle.

Sources : Spec-Driven Development with Claude Code (AI Agent Factory), Claude Code Subagents and Orchestration Guide.