Créez trois fichiers de spécifications avant de confier du travail à Claude Code ou Codex

La même tâche. Le même modèle. Des résultats radicalement différents d’une session à l’autre.

Si vous travaillez régulièrement avec Claude Code ou Codex, vous avez sûrement vécu cette frustration : vous décrivez ce que vous voulez, l’agent produit quelque chose d’acceptable, puis lors de la session suivante, il fait des choix incompatibles avec ce qu’il avait fait la veille. Pas parce que le modèle est capricieux, mais parce que vous n’avez jamais documenté vos décisions de manière structurée. Chaque session repart de zéro.

Le problème n’est pas le prompt. C’est l’absence d’une façon stable de communiquer vos intentions.

Ce qui se passe réellement dans la fenêtre de contexte

Les agents de code modernes ont des fenêtres de contexte larges, mais cela ne signifie pas qu’ils traitent tout avec la même attention. Il existe ce qu’on pourrait appeler la Malédiction des Instructions : plus vous entassez d’informations dans un seul fichier de contexte, moins l’agent peut en tenir compte de façon fiable. L’attention se dilue. Les sections importantes se noient dans les détails.

Un fichier CLAUDE.md de 800 lignes qui mélange les conventions de nommage, les décisions d’architecture, les règles de style et les notes de débogage se comportera moins bien qu’une structure à trois couches clairement séparée. Ce n’est pas une limitation que les prochaines versions vont résoudre, c’est une propriété fondamentale des systèmes d’attention.

La solution : distribuer l’information sur trois fichiers aux rôles distincts, chacun activé au bon moment.

Couche 1 : CLAUDE.md, la constitution du projet

CLAUDE.md est le fichier que l’agent lit en premier, à chaque session. Son rôle est d’établir les contraintes non négociables du projet.

Ce fichier doit rester court, idéalement sous 150 lignes. Il contient les commandes de build essentielles (bun run dev, bun run build, la commande de test), les conventions fondamentales (où vivent les composants, comment s’appellent les hooks, quel système de style est utilisé), et trois listes explicites :

Toujours faire : ce que l’agent doit systématiquement respecter. Mettre à jour les traductions dans tous les fichiers de langue quand on modifie du texte visible, par exemple.

Demander avant de faire : ce qui nécessite une validation humaine. Modifier le schéma de la base de données, changer une dépendance majeure, refactoriser une interface publique.

Ne jamais faire : les interdits absolus. Commiter CLAUDE.md ou AGENTS.md, supprimer des migrations, exposer des secrets dans le code.

Ces trois tiers font toute la différence. Un agent qui sait explicitement ce qui est interdit commet beaucoup moins d’erreurs irréversibles qu’un agent à qui on a simplement décrit ce qu’on voulait.

Couche 2 : SPEC.md, le quoi et le pourquoi

SPEC.md décrit ce que vous construisez et pourquoi. Pas comment. Le comment appartient à l’agent.

Un SPEC.md efficace contient cinq sections : le contexte du projet (qui l’utilise, dans quel environnement), l’objectif de la fonctionnalité en une phrase, les critères d’acceptance formulés comme des comportements observables, les contraintes explicites (performances, accessibilité, compatibilité navigateurs), et les décisions déjà prises avec leur justification.

La partie la plus utile, et la moins pratiquée, est la méthode de l’interview avec l’agent. Avant d’écrire votre SPEC.md, demandez à l’agent de vous poser des questions sur la fonctionnalité. Posez-lui simplement : « Quelles informations te manquent pour implémenter ça correctement ? » Les questions qu’il génère révèlent exactement les ambiguïtés que vous n’avez pas encore résolues. Répondez-y dans le document.

Ce fichier appartient au dossier docs/specs/ et doit être commité dans git. C’est une décision technique comme une autre, elle mérite un historique.

Couche 3 : plan.md, les tâches atomiques

Le plan.md est éphémère. Il vit dans la racine du projet pendant la durée d’une session de travail et disparaît une fois la fonctionnalité mergée.

Chaque tâche dans ce fichier doit prendre entre deux et cinq minutes à exécuter. Si une tâche dépasse cinq minutes, c’est qu’elle cache plusieurs tâches. Chaque entrée spécifie les chemins de fichiers exacts concernés, pas des descriptions vagues comme « modifier le composant de navigation ».

Le plan suit un cycle TDD naturel : d’abord écrire le test qui décrit le comportement attendu, ensuite implémenter le minimum qui fait passer ce test, enfin refactoriser si nécessaire. L’agent qui reçoit un plan structuré de cette façon travaille de façon beaucoup plus prévisible, car il ne doit pas interpréter vos intentions en même temps qu’il code.

La règle des deux sessions

Il y a une discipline organisationnelle qui change tout : ne jamais mélanger l’écriture des spécifications et l’implémentation dans la même session.

La première session sert à construire SPEC.md et plan.md. L’agent pose des questions, vous répondez, vous affinez. À la fin, vous avez un document précis et un plan détaillé. Vous fermez la session sans avoir écrit une seule ligne de code.

La deuxième session commence avec un contexte propre. L’agent reçoit CLAUDE.md, SPEC.md et plan.md au démarrage. Il implémente en suivant le plan, tâche par tâche.

La raison pratique : à 50% d’utilisation de la fenêtre de contexte, la qualité du raisonnement commence à décliner. Si vous avez passé la première moitié de votre contexte à discuter de l’architecture, l’agent implémentera avec moitié moins de capacité d’attention disponible. Séparer les sessions élimine ce problème structurellement.

Les trois niveaux de maturité

La plupart des équipes traversent trois phases dans leur relation avec ces fichiers.

Au niveau 1, les specs sont écrites pour la session en cours et abandonnées. C’est déjà bien mieux que de n’avoir rien, mais les bénéfices disparaissent dès la session suivante.

Au niveau 2, les specs deviennent des documents vivants. SPEC.md est mis à jour quand les décisions changent, CLAUDE.md évolue avec le projet. Les nouvelles personnes rejoignant l’équipe (humaines ou agents) peuvent se mettre à niveau en lisant ces fichiers.

Au niveau 3, la spec devient la source de vérité. Avant de toucher au code, on met à jour la spec. Le code est l’expression de la spec, pas l’inverse. Les revues de code vérifient d’abord que l’implémentation correspond aux intentions documentées.

La plupart des équipes qui adoptent cette approche atteignent le niveau 2 en quelques semaines. Le niveau 3 demande une discipline d’équipe plus forte, mais les gains en cohérence sur les projets longs sont substantiels.

Par où commencer

Prenez votre projet actuel. Ouvrez un éditeur. Écrivez un CLAUDE.md en vous posant trois questions : quelles sont les commandes essentielles, quelles conventions ne doivent jamais être violées, qu’est-ce qui nécessite mon accord avant d’être fait ?

Ensuite, pour la prochaine fonctionnalité que vous planifiez, créez un SPEC.md avant de confier quoi que ce soit à un agent. Décrivez l’objectif, les critères d’acceptance, les contraintes. Puis demandez à l’agent ce qu’il ne comprend pas encore.

Ces deux fichiers seuls transformeront la façon dont vos sessions d’agent coding se déroulent. Le plan.md viendra naturellement une fois que vous aurez pris l’habitude de spécifier avant d’implémenter.

Les agents de code sont devenus remarquablement capables. Ce qui limite leur efficacité n’est plus leur capacité à coder, c’est la qualité du contexte qu’on leur fournit.