Pourquoi planifier avant de laisser l’IA écrire du code?

Si vous tapez « crée-moi une page de réservation » dans un agent de programmation, il construira une page de réservation en quelques minutes. Que ce soit votre page de réservation dépend de dizaines de choix qu’il aura faits à votre place : qui peut réserver, comment fonctionnent les annulations, ce qui se passe quand deux personnes choisissent la même plage horaire. Quand ces suppositions sont fausses, vous le découvrez tard, une fois le code écrit, et la correction coûte bien plus de prompts qu’un plan ne l’aurait fait.

Le développement piloté par les spécifications (spec-driven development) consiste à écrire ce que vous voulez avant que le moindre code existe, puis à faire construire l’agent à partir de ce document. L’idée est ancienne dans les équipes de logiciel. Ce qui a changé en 2025 et 2026, c’est que les outils l’ont intégrée à leur fonctionnement : l’éditeur Kiro d’Amazon est conçu autour des specs, et la plupart des agents offrent maintenant un mode plan qui propose des étapes avant de toucher aux fichiers.

À quoi ressemble une spec?

La documentation de Kiro décrit un déroulement en trois phases qui fonctionne avec n’importe quel outil, même si vous écrivez les fichiers vous-même :

1. Exigences (requirements.md) : des récits utilisateurs et des critères d’acceptation, c’est-à-dire des énoncés vérifiables de ce que « terminé » veut dire.
2. Conception (design.md) : l’approche technique, les données en jeu et la façon dont les parties communiquent entre elles.
3. Tâches (tasks.md) : de petites étapes de réalisation numérotées, que l’agent peut accomplir et cocher une à une.

Kiro génère ces fichiers avec vous, vous laisse commenter des passages précis avant de passer à la suite, puis peut exécuter en parallèle les tâches indépendantes. Pour une fonctionnalité bien comprise, il offre aussi une spec rapide qui écrit les trois fichiers sans s’arrêter pour obtenir votre approbation. Vous pouvez reprendre la même structure dans Claude Code, Codex ou Cursor en demandant à l’agent d’écrire les trois fichiers et d’attendre votre révision.

Un exemple concret : une fonctionnalité, trois courts fichiers

Disons que vous voulez une liste d’attente dans une application de cours de yoga. Commencez par demander uniquement le plan :

Avant d’écrire du code, rédige une spec pour cette fonctionnalité en trois fichiers dans specs/waitlist/ :
- requirements.md : des récits utilisateurs avec des critères d’acceptation écrits sous forme de lignes « QUAND ... ALORS ... ».
- design.md : les données que tu vas stocker, les écrans et routes d’API qui changent, et les risques.
- tasks.md : des tâches numérotées assez petites pour être terminées et testées une à une.
Fonctionnalité : quand un cours est complet, les élèves peuvent s’inscrire sur une liste d’attente. Si quelqu’un annule, la première personne sur la liste obtient la place et reçoit un courriel.
Pose-moi des questions sur tout ce qui n’est pas clair au lieu de deviner. N’écris pas de code avant que j’approuve la spec.

Un bon requirements.md pour ce cas pourrait contenir :

Lire ce tableau prend deux minutes, et c’est là que vous remarquez le cas oublié (« Et si la première personne ne veut plus la place? »). Changer une ligne maintenant coûte bien moins cher que changer la base de données plus tard. Une fois la spec approuvée, dites à l’agent de suivre tasks.md une tâche à la fois, en lançant les tests après chacune.

Planifier ou fixer des règles : deux fichiers différents

Une spec appartient à une fonctionnalité et est terminée quand cette fonctionnalité est livrée. Les fichiers d’instructions sont autre chose : ils contiennent les règles permanentes qui s’appliquent à chaque tâche du projet, comme la façon de lancer les tests, les dossiers interdits ou le style de code à suivre. Gardez les deux séparés pour qu’aucun ne devienne un mur de texte.

Comment écrire des fichiers d’instructions que l’IA respecte (AGENTS.md, CLAUDE.md, fichiers de règles)?

La plupart des agents chargent un fichier Markdown de règles de projet au début de chaque session. AGENTS.md est un format ouvert que, selon le projet AGENTS.md, plus de 60 000 dépôts à code source ouvert utilisent. Parmi les outils qui le lisent, on compte Codex d’OpenAI, Jules de Google, l’agent de programmation de GitHub Copilot, Cursor, Zed, Aider, Devin et Kilo Code. Claude Code lit plutôt CLAUDE.md; la documentation d’Anthropic suggère un CLAUDE.md qui contient la ligne @AGENTS.md, pour que les deux fichiers partagent un seul ensemble de règles. D’autres éditeurs ont leurs propres fichiers de règles, mais la plupart savent aussi lire AGENTS.md : commencez par là.

Ce qui fait qu’un agent suit vraiment le fichier :

• Soyez précis et vérifiable. « Lancer npm test avant chaque commit » fonctionne; « écrire du bon code », non. Anthropic note que des instructions concises et vérifiables sont suivies plus régulièrement.
• Restez bref. Anthropic suggère de ne pas dépasser environ 200 lignes par CLAUDE.md. Retirez les règles qui se contredisent, puisque l’agent pourrait suivre l’une ou l’autre.
• Couvrez ce dont une nouvelle recrue aurait besoin. Le site AGENTS.md suggère de décrire le projet, les commandes pour le construire et le tester, les conventions de style, le fonctionnement des tests et les points de sécurité.
• Placez les règles locales près du code. Dans un gros projet, un AGENTS.md placé dans un sous-dossier s’applique à ce dossier, et le fichier le plus proche l’emporte. Une instruction directe dans votre conversation a priorité sur le fichier.
• Rappelez-vous que c’est un guide, pas un verrou. Claude Code traite CLAUDE.md comme du contexte, et non comme une configuration imposée. Tout ce qui ne doit jamais arriver, comme lire des secrets ou pousser vers main, doit aussi figurer dans les paramètres de permission.

Un exemple minimal :

# AGENTS.md
### Project
Application de réservation de cours de yoga. Interface Next.js dans web/, API dans api/.
### Commands
- Installer : npm install
- Tester : npm test (doit réussir avant chaque commit)
### Rules
- Pour toute nouvelle fonctionnalité, écrire une spec dans specs/<feature>/ et attendre l'approbation.
- Ne jamais modifier les fichiers de api/payments/ sans demander.
- Demander avant d'ajouter une dépendance.

Traitez le fichier comme une documentation vivante : quand l’agent fait deux fois la même erreur, ajoutez une ligne claire qui l’empêche.