Créez trois fichiers de spécifications avant d'utiliser Claude Code et Codex

Après presque un an à utiliser des agents de codage IA au quotidien, ce qui me perturbait le plus n’était pas les hallucinations ni les appels d’API incorrects. C’était l’incohérence. La même tâche, formulée légèrement différemment, produisait un résultat propre un jour et un désastre le lendemain. Les sessions longues aggravaient les choses : l’agent oubliait des décisions prises vingt messages plus tôt.

La cause était structurelle. Je n’avais aucun cadre pour communiquer mes intentions à l’agent d’une session à l’autre. Chaque conversation repartait de zéro et dérivait dans des directions imprévisibles.

Trois couches qui ont changé le résultat

Répartir les instructions en trois fichiers, chacun avec un rôle distinct, a réglé le problème d’incohérence presque du jour au lendemain.

Couche 1, CLAUDE.md se charge automatiquement à chaque session. Il contient les constantes du projet : commandes de build, versions de la stack, structure des dossiers, conventions de code, et limites comportementales (faire toujours X, demander avant Y, ne jamais faire Z).

Couche 2, SPEC.md capture le quoi et le pourquoi d’une fonctionnalité précise. Objectif, exigences, critères de succès, contraintes techniques et limites de périmètre. Rien sur les détails d’implémentation.

Couche 3, plan.md décompose une spec en tâches exécutables de deux à cinq minutes, avec des chemins de fichiers explicites, un ordre TDD, et des points de commit.

Pourquoi tout entasser dans un seul fichier ne fonctionne pas

La recherche sur le suivi d’instructions par les LLM décrit ce phénomène comme la « Malédiction des Instructions ». Plus le nombre de directives dans un seul contexte augmente, plus le taux de respect de chaque directive individuelle chute. Je l’ai vérifié directement : un fichier unique contenant règles du projet, specs de fonctionnalités et listes de tâches amenait l’agent à ignorer environ la moitié des instructions vers le bas du document.

La séparation par rôle a résolu le problème. L’agent lit les règles universelles depuis la couche 1, l’intention de la fonctionnalité depuis la couche 2, et les étapes d’exécution depuis la couche 3. Chaque fichier reste suffisamment court pour que le modèle lui accorde toute son attention.

CLAUDE.md fonctionne mieux quand il reste concis

Ce fichier étant chargé à chaque session, il ne doit contenir que ce qui s’applique universellement. Commandes de build, versions de la stack, organisation des dossiers, conventions de nommage. Ajoutez une limite à trois niveaux : ce qu’il faut toujours faire, ce qui nécessite une validation, ce qu’il ne faut jamais faire.

L’approche la plus efficace a été de partir minimal et d’ajouter des règles progressivement, chaque fois que je remarquais l’agent répéter une erreur. Tenter d’écrire un CLAUDE.md exhaustif d’emblée menait à un gonflement qui déclenchait exactement la baisse de conformité que je cherchais à éviter.

Quelques pièges à éviter : ne mettez pas de clés API ni de fragments de code ici, ils deviennent vite obsolètes. Ne dupliquez pas les règles que votre linter applique déjà. Et déplacez tout ce qui concerne une seule fonctionnalité vers la couche 2.

Les fichiers de spec se concentrent sur le quoi et le pourquoi, pas sur le comment

La différence avec un PRD traditionnel est que ces specs sont structurées pour être consommées par un agent. Cinq sections suffisent : objectif, exigences, critères de succès, contraintes techniques, et périmètre.

Laissez les décisions d’implémentation à l’agent. Il peut analyser le code existant et choisir la bonne approche. Quand j’essayais de dicter le comment, l’agent soit le suivait aveuglément en entrant en conflit avec les patterns existants, soit l’ignorait complètement.

Une alternative à la rédaction manuelle des specs : demandez à l’agent de vous interviewer. Posez deux règles : une question à la fois, et des choix multiples autant que possible. Les specs produites avaient moins de lacunes que celles que j’écrivais seul.

Sauvegardez les specs finalisées dans docs/specs/YYYY-MM-DD-sujet.md et commitez-les dans Git. Cela donne à l’agent accès à l’historique des specs via git diff, et fournit aux réviseurs une trace des intentions derrière les changements de code.

La séparation des sessions est la pratique la plus négligée

Les échanges de brainstorming et de questions-réponses lors de l’écriture d’une spec consomment une part importante de la fenêtre de contexte. Passer directement à l’implémentation dans la même session signifie que l’agent perd progressivement accès au contexte antérieur.

J’ai restructuré en trois sessions : la session 1 produit SPEC.md, la session 2 crée plan.md, la session 3 et suivantes exécutent les tâches une par une. L’amélioration de précision était perceptible dès la première semaine.

Trois habitudes qui ont consolidé ce fonctionnement : écrire des chemins de fichiers explicites dans chaque tâche pour que l’agent cesse de deviner, ancrer l’ordre TDD (test en premier, implémentation, vérification, commit) dans plan.md, et démarrer une nouvelle session quand l’utilisation du contexte atteint environ 50 %.

Le modèle de maturité pointe vers la spec comme source de vérité

L’équipe de Martin Fowler a récemment défini un modèle de maturité pour le développement logiciel basé sur des agents, avec trois niveaux. Niveau 1 : écrire une spec, implémenter, abandonner la spec. Niveau 2 : maintenir la spec comme document vivant aux côtés du code. Niveau 3 : la spec devient la source de vérité unique, et le code est un artefact généré.

La plupart des équipes et des individus que je connais n’ont pas encore atteint le niveau 1. Ils envoient des prompts ponctuels en espérant le meilleur, et quand ça échoue, il n’y a aucun moyen de diagnostiquer pourquoi.

Passer du niveau 1 au niveau 2 demande une seule habitude : commiter vos fichiers de specs dans Git. Passer du niveau 2 au niveau 3 signifie mettre à jour la spec avant de modifier le code. Le plus petit pas que vous pouvez faire aujourd’hui est de créer un CLAUDE.md pour votre projet et d’écrire un SPEC.md avant votre prochaine fonctionnalité.