Développement piloté par les specs avec des agents IA

Le développement piloté par les spécifications (spec-driven development) est une façon de travailler avec des agents de code IA où une spec écrite précède tout code. Vous décrivez quoi construire, pourquoi, et comment vous saurez que c’est terminé. L’agent transforme cette spec en plan technique, découpe le plan en petites tâches, les implémente une par une, et le résultat est vérifié par rapport aux critères d’acceptation de la spec. La spec, le plan et les tâches sont des fichiers de votre dépôt, pas des messages noyés dans un chat : ils survivent à la session et se relisent comme du code.

Ce guide explique la boucle, compare les outils qui la prennent en charge en octobre 2026 (GitHub Spec Kit, les specs de Kiro, OpenSpec et les plan modes de Claude Code et de Codex), déroule un petit exemple avec un vrai fichier de spec et ses prompts, puis liste les pièges. Les informations sur les outils ont été vérifiées en octobre 2026 dans la documentation officielle et le dépôt de chaque projet.

Pourquoi la spec compte davantage avec des agents

Un développeur qui reçoit un ticket flou pose des questions. Un agent qui reçoit un prompt flou devine le plus souvent, écrit du code plausible et vous annonce que c’est fini. L’écart entre « le code est écrit » et « la fonctionnalité marche comme vous l’entendiez » est la source de l’essentiel des reprises.

Une spec réduit cet écart de trois façons :

• Elle impose les décisions en amont. Cas limites, états d’erreur et non-objectifs sont écrits avant que l’agent ne tranche à votre place.
• Elle donne à chaque étape la même source de vérité. Le plan, les tâches et la revue renvoient à un seul fichier, pas à votre souvenir d’une conversation.
• Elle rend « terminé » vérifiable. Les critères d’acceptation font passer la revue de « ça a l’air bon » à « le critère 3 passe, voici le test ».

Rien de tout cela n’est nouveau : cahiers des charges et tests d’acceptation sont de vieilles idées. Ce qui change, c’est que les agents vont si vite qu’écrire la spec est désormais la partie lente et précieuse, et le code la partie bon marché.

La boucle : spec, plan, tâches, implémentation, vérification

Deux règles font fonctionner la boucle. D’abord, la spec parle de comportement, le plan d’implémentation. « Les utilisateurs peuvent réinitialiser leur mot de passe par e-mail » va dans la spec ; « ajouter une table reset_tokens » va dans le plan. Ensuite, arrêtez-vous et relisez à chaque étape. Tous les outils ci-dessous sont construits autour de cette pause ; la sauter ramène le développement piloté par les spécifications à un long prompt.

Les outils du développement piloté par les spécifications

GitHub Spec Kit

Spec Kit est la boîte à outils de GitHub pour le développement piloté par les spécifications. Il est passé en 1.0 cette année et la dernière version en octobre 2026 est la v1.2.4. Il ne remplace pas votre agent : la CLI specify installe des modèles et des commandes dans le projet, et vous lancez les étapes dans le chat de votre agent. Il faut Python 3.11 ou plus récent, uv et un agent pris en charge sous macOS, Linux ou Windows.

uv tool install specify-cli
specify init my-project --integration claude
# dans un dépôt existant :
specify integration install claude

La liste des intégrations couvre plus de 40 agents, dont Claude Code (claude), Codex CLI (codex), Gemini CLI (gemini), GitHub Copilot (copilot), Cursor (cursor-agent), Kiro CLI (kiro-cli), opencode, Qwen Code et Amp. La documentation écrit les commandes sous la forme /speckit.specify ; la façon de les taper dépend de l’agent. Dans Claude Code, elles sont installées comme skills dans .claude/skills/ et s’appellent avec /speckit-specify ; dans Codex, c’est $speckit-specify.

Le chemin court est specify → plan → tasks → implement → converge. Pour les fonctionnalités destinées à la production, la documentation recommande le chemin complet :

1. /speckit-constitution, une fois par projet, pour des principes comme les règles de test.
2. /speckit-specify rédige la spec de la fonctionnalité à partir d’une simple description.
3. /speckit-clarify pose jusqu’à cinq questions ciblées et inscrit les réponses dans la spec.
4. /speckit-plan rédige le plan technique selon votre stack et vos contraintes.
5. /speckit-checklist génère des « tests unitaires pour vos exigences ».
6. /speckit-tasks produit un tasks.md ordonné selon les dépendances.
7. /speckit-analyze est un contrôle de cohérence en lecture seule entre spec, plan et tâches.
8. /speckit-implement traite les tâches dans l’ordre.
9. /speckit-converge compare le code à la spec et ajoute à tasks.md le travail oublié.

On répète implement et converge jusqu’à ce que converge réponde Converged. La documentation conseille de lancer chaque commande séparément et d’en relire le résultat avant la suivante.

Les specs de Kiro

Kiro intègre les specs au produit. Chaque spec comporte trois fichiers dans .kiro/specs/<nom>/ : requirements.md (ou bugfix.md pour un bug), design.md et tasks.md. Les exigences s’écrivent en notation EARS, sous la forme « WHEN [condition] THE SYSTEM SHALL [comportement] ». Les specs de fonctionnalité peuvent commencer par les exigences ou par la conception, et Quick Spec génère les trois fichiers d’un coup, sans les arrêts de validation intermédiaires.

Dans la CLI Kiro, vous commencez avec /spec new <nom> et lancez les tâches avec /spec run <nom>. Quand vous lancez toutes les tâches, Kiro construit un graphe de dépendances à partir de tasks.md et exécute les tâches indépendantes par vagues parallèles. En octobre 2026, Kiro propose une offre gratuite avec 50 crédits et des offres payantes à partir de 20 $ par utilisateur et par mois.

Kiro est le meilleur choix si vous voulez le workflow de specs avec une interface de revue intégrée et que travailler dans Kiro vous convient. Si vous voulez rester dans Claude Code ou Codex, Spec Kit ou OpenSpec conviennent mieux.

OpenSpec

OpenSpec est une alternative plus légère, sous licence MIT, organisée autour des changements. /opsx:propose add-dark-mode crée openspec/changes/add-dark-mode/ avec proposal.md, un dossier specs/ d’exigences et de scénarios, design.md et tasks.md. /opsx:apply traite les tâches, et /opsx:archive archive le changement et met les specs à jour. /opsx:explore est une étape de réflexion avant de vous engager sur une proposition.

npm install -g @fission-ai/openspec@latest   # demande Node.js 20.19.0+
cd your-project
openspec init

Il existe aussi un binaire autonome et une formule Homebrew. L’écriture des commandes varie selon l’agent, par exemple $openspec-propose dans Codex ; openspec init affiche la bonne forme pour les outils choisis. La dernière version en octobre 2026 est la v1.15.0.

Le plan mode dans Claude Code et Codex

Les plan modes couvrent une étape de la boucle : le plan. Dans le plan mode de Claude Code, l’agent lit les fichiers, explore, puis propose un plan ; les modifications restent bloquées jusqu’à votre accord. On l’active avec Shift+Tab, avec /plan devant un prompt ou avec claude --permission-mode plan.

La CLI Codex dispose de /plan, qui passe le chat en plan mode et accepte la première demande sur la même ligne, par exemple /plan Propose a migration plan for this service. Codex propose aussi /goal, qui fixe un objectif durable pour une tâche plus large et peut être mis en pause, repris ou effacé.

Les plan modes se prêtent bien à un workflow piloté par les specs sans outil supplémentaire. Il leur manque la persistance : demandez à l’agent d’écrire le plan validé et les tâches dans des fichiers, pour que la session suivante reparte de là et non de zéro.

Un exemple concret : un fichier de spec et quatre prompts

Voici la version artisanale, qui fonctionne avec Claude Code, Codex ou tout agent capable de lire des fichiers. La fonctionnalité : limiter les connexions échouées dans une petite application web.

1. Écrire la spec

Enregistrez ceci sous specs/login-rate-limit/spec.md :

# Login rate limiting

## Goal
Slow down password guessing on POST /login without bothering normal users.

## Non-goals
- No CAPTCHA.
- No change to how passwords are stored.

## Acceptance criteria
1. WHEN an IP has 5 failed logins within 15 minutes,
   THE SYSTEM SHALL answer further attempts with HTTP 429 for 15 minutes.
2. WHEN a login succeeds, THE SYSTEM SHALL reset that IP's failure count.
3. The 429 response SHALL include a Retry-After header in seconds.
4. Limits SHALL be configurable through LOGIN_MAX_FAILS and LOGIN_WINDOW_MIN.
5. Existing login tests SHALL still pass, and new tests SHALL cover 1–4.

## Constraints
- Use the existing Redis connection; no new services.

## Open questions
- Should the limit be per IP, per account, or both?

Tenez-vous-en à un écran. La section des questions ouvertes est là exprès : elle donne à l’agent un endroit pour objecter avant de planifier. Vous pouvez aussi écrire la spec en français ; les agents lisent les deux.

2. Clarifier et planifier

Commencez en plan mode et indiquez le fichier à l’agent :

Read specs/login-rate-limit/spec.md and the auth code.
First, ask me about anything ambiguous, starting with the open questions.
Then write a plan to specs/login-rate-limit/plan.md: files to change,
data stored in Redis and its expiry, how each acceptance criterion
will be tested, and risks. Don't edit any source files.

Répondez aux questions, puis lisez le plan. Contestez tout ce qui ignore une contrainte.

3. Découper en tâches

Turn plan.md into specs/login-rate-limit/tasks.md: a numbered checklist
of tasks small enough to review in one diff. For each task, list the
files it touches and the test that proves it. Order them by dependency.

4. Implémenter une tâche à la fois

Do task 1 from specs/login-rate-limit/tasks.md only. Run the tests,
tick the task in tasks.md, and stop. Tell me if the spec or plan
turned out to be wrong.

Une tâche par prompt garde les diffs petits et vous offre un point de relecture naturel. Si une tâche révèle que la spec était fausse, corrigez d’abord la spec, puis continuez.

5. Vérifier par rapport à la spec

Une fois les tâches terminées, vérifiez le résultat par rapport à la spec, de préférence dans une nouvelle session ou avec un autre agent, pour que le relecteur ne soit pas l’auteur du code :

Read specs/login-rate-limit/spec.md. For each acceptance criterion,
find the code and the test that cover it, run the tests, and report
PASS or FAIL with evidence. Don't change any code.

C’est toute la boucle. Commitez le dossier specs/ avec le code, pour que la personne suivante, ou l’agent suivant, comprenne pourquoi le code est ainsi. Pour bien rédiger les prompts eux-mêmes, voyez les prompts pour agents de code IA.

Les pièges

• Des specs qui sont en fait des plans. Si la spec nomme des tables et des fonctions, l’agent ne peut pas proposer une meilleure conception et le relecteur ne distingue plus comportement et implémentation. Gardez le « comment » dans plan.md.
• Des specs trop longues. Une spec de dix pages dévore le contexte et personne ne la lit, l’agent compris. Un écran par fonctionnalité est une bonne limite ; découpez les plus grosses.
• Valider sans lire. Une spec ou un plan non lu n’est qu’un prompt plus lent. La pause de relecture est tout l’intérêt.
• Des tâches trop grosses. Si une tâche produit un diff que vous ne pouvez pas relire d’une traite, découpez-la.
• Laisser la spec dériver. Quand le code vous apprend quelque chose, mettez la spec à jour. Une spec qui contredit le code est pire que pas de spec du tout.
• Faire vérifier par l’auteur. L’agent qui a écrit le code a tendance à valider son propre travail. Utilisez une nouvelle session, un second modèle ou un humain pour le contrôle final.
• L’appliquer à tout. Une correction d’une ligne n’a pas besoin de spec. Réservez la démarche aux fonctionnalités avec des cas limites ou plusieurs fichiers.
• Mêler les règles du projet à chaque spec. Les règles permanentes, comme les commandes de test et le style de code, vont dans CLAUDE.md ou AGENTS.md ou dans une constitution Spec Kit, pas dans chaque spec de fonctionnalité.

Le développement piloté par les spécifications dans AgentVera

AgentVera est une application de bureau pour macOS, Windows et Linux qui fait tourner Claude Code, Codex, Kiro et d’autres CLI de code côte à côte. Chaque panneau est la vraie CLI : les commandes Spec Kit, les commandes OpenSpec, le /spec de Kiro et le plan mode y fonctionnent comme en dehors. Plusieurs fonctionnalités d’AgentVera suivent le même schéma spec, plan, construction, vérification :

• Ligne de tâches : une ligne permanente d’agents Analyse, Plan, Construction et Revue. Chaque tâche reçoit des critères d’acceptation, l’Analyse écrit 01-analiz.md, le Plan écrit 02-plan.md, et le relecteur coche chaque critère avec une preuve. Une tâche rejetée repart en Construction avec les constats.
• AgentVera Verify : extrait les critères d’acceptation du message que vous envoyez à un agent ; à la fin de son tour, un vérificateur distinct lit le diff, lance les commandes de test autorisées et marque chaque critère réussi ou échoué. Le vérificateur ne peut pas modifier de fichiers.
• Équipe parallèle : un agent découpe un gros travail en 8 parties au maximum, chacune avec son prompt, ses critères d’acceptation, ses fichiers attendus et ses dépendances, les exécute dans des worktrees séparés et les fusionne en une branche et une PR.
• Kanban d’équipe : une carte peut être envoyée à un agent de code comme tâche, et sa réponse revient en commentaire. Voir le kanban pour agents IA.
• Revue de code automatique : à la fin d’un tour, le modèle Claude de votre choix relit le code et liste les constats avec des liens fichier:ligne.

La ligne de tâches, Verify, l’équipe parallèle et le kanban d’équipe sont inclus dans les offres Pro et Team. Si vous n’avez besoin que des fichiers de spec et des commandes, Spec Kit et OpenSpec sont gratuits et fonctionnent dans n’importe quel terminal ; AgentVera devient utile quand plusieurs agents travaillent sur des specs en même temps.

En résumé

Le développement piloté par les spécifications consiste à écrire le « quoi » et le « comment saurai-je que c’est bon » avant que l’agent n’écrive du code, puis à rattacher chaque étape suivante à ce fichier. Commencez avec un spec.md d’un écran et le plan mode. Passez à Spec Kit ou à OpenSpec quand vous voulez des modèles et des contrôles de cohérence, ou à Kiro si vous voulez le workflow intégré à l’éditeur. Quel que soit votre choix, relisez à chaque étape et vérifiez par rapport aux critères, pas au résumé de l’agent.

Pour aller plus loin :

• Plan mode de Claude Code
• Prompts pour agents de code IA
• Ligne de tâches

Pour essayer AgentVera, téléchargez-le.