Le spec contract en 3 parties : quoi écrire avant de laisser l'agent tourner

Tu prompt Claude Code avec « ajoute Google OAuth à l'app ». Quarante-cinq minutes plus tard, tu as une implémentation techniquement correcte qui utilise une librairie que tu ne veux pas, crée une table de base de données que tu as déjà, et ignore complètement ton flow d'auth existant.

Le modèle a fait ce que tu as demandé. Le problème, c'est ce que tu n'as pas demandé. Le spec contract agentic existe pour combler ce fossé entre ton intent et l'interprétation de l'agent.

Pourquoi les prompts cassent en agentic coding

Un prompt, c'est une requête. Une spec, c'est un contrat. La différence compte quand l'agent a un accès en écriture à ta codebase et peut lancer des commandes sans demander.

Tu décris la destination. L'agent décide comment y arriver. Parfois il décide bien. Souvent non, et tu passes plus de temps à corriger que ce que tu as économisé.

J'ai vu des sessions où chaque correction engendrait un nouveau problème. L'agent résolvait le mauvais problème avec une conviction croissante. Pas parce que le modèle était mauvais. Parce que l'input était maigre. L'agent ne savait pas que j'avais déjà un utilitaire d'auth. Ne savait pas que le schéma de base de données était gelé ce sprint. Ne savait pas que la dernière personne qui avait touché ce module avait passé une semaine à régler les edge cases.

Un prompt ne peut pas porter tout ça. Le spec contract en 3 parties, si.

Le spec contract agentic : contexte, intent, contraintes

Le spec contract donne trois choses à l'agent avant qu'il n'écrive une ligne de code. Chacune ferme un failure mode spécifique.

Contexte : ce que l'agent a besoin de savoir

Le contexte dit à l'agent ce qui existe déjà et où chercher.

Claude Code lit ton arbre de fichiers, ton CLAUDE.md, et les fichiers qu'il décide d'explorer. Mais « décide d'explorer », c'est le problème. Sans direction, il lit trop ou trop peu. Il trouve un vieux pattern dans un module deprecated et le copie. Il rate la fonction utilitaire qui fait déjà la moitié du travail.

Le contexte dans la spec, ça veut dire pointer l'agent vers le bon code avant qu'il ne commence à explorer par lui-même.

Context:
- Auth lives in src/auth/. Session management uses iron-session.
- User model in src/models/user.ts already has an oauthProvider field.
- Existing flow to follow: src/auth/github-oauth.ts.

Trois lignes. L'agent sait où chercher et quel pattern suivre. Sans ça, il aurait dépensé des tokens à explorer, possiblement atterri sur le mauvais pattern, et tu l'aurais corrigé deux fois avant d'arriver là.

Intent : à quoi ressemble « fini »

L'intent définit l'état final vérifiable. Pas le nom de la feature. Ce qui doit exister quand le travail est fini et comment tu sauras que c'est correct.

La plupart des prompts décrivent la feature : « ajoute Google OAuth ». Une spec décrit le résultat.

Intent:
- Google OAuth as a login option alongside GitHub OAuth.
- New Google users get an account. Existing users with matching
  email get linked automatically.
- Existing tests pass. New test covers the Google callback handler.

L'intent a deux jobs. Il dit à l'agent quoi construire, et il donne à l'agent une cible qu'il peut vérifier. Cette dernière ligne, celle sur les tests, transforme une requête vague en quelque chose sur lequel l'agent peut converger. Claude Code lance les tests et itère jusqu'à ce qu'ils passent. Donne-lui cette boucle et il clôt sans toi.

Les best practices officielles de Claude Code le disent directement : les specs les plus utiles nomment les fichiers et interfaces impliqués, indiquent ce qui est out of scope, et se terminent par une étape de vérification qui prouve que la feature marche.

Contraintes : ce qui reste off limits

Les contraintes définissent ce que l'agent ne doit pas toucher. La plupart des gens zappent cette partie. C'est elle qui prévient le plus de rework.

Sans contraintes, l'agent optimise pour le chemin le plus court vers ton intent énoncé. Ce chemin peut inclure l'installation d'une dépendance que tu ne veux pas ou la modification d'un schéma de base de données alors que tu n'avais besoin que d'un changement au niveau application.

Constraints:
- No new npm dependencies. Use the existing next-auth setup.
- No database schema changes.
- Do not modify src/auth/session.ts.
- Scope: Google OAuth only. No refactoring existing flows.

Chaque contrainte est une correction que tu ne feras pas en plein milieu de la session. Contrairement aux corrections en plein milieu de session, celles-ci ne consomment pas de tokens de contexte et ne laissent pas d'approches ratées encombrer l'historique de la conversation.

La spec assemblée

Voici le contrat complet pour l'exemple OAuth :

## Context
- Auth: src/auth/. Sessions: iron-session.
- Pattern to follow: src/auth/github-oauth.ts.
- User model: src/models/user.ts (oauthProvider field exists).
 
## Intent
- Add Google OAuth alongside GitHub.
- New users via Google get a new account. Matching email auto-links.
- Existing tests pass. New test covers Google callback.
 
## Constraints
- No new npm deps. Use existing next-auth.
- No DB schema changes.
- Don't touch session config (src/auth/session.ts).
- PR scoped to Google OAuth only.

Colle ça directement dans Claude Code, ou écris-le dans un fichier SPEC.md et démarre une nouvelle session avec « implémente la spec dans SPEC.md ». La nouvelle session récupère un contexte propre focalisé sur l'exécution. La spec survit à travers les sessions même si le contexte se fait compacter.

Je vais plus loin sur le spec contract et sur la façon dont il s'intègre dans la boucle explore-plan-implement dans le Chapitre 3 : L'humain dans la boucle du cours d'agentic coding.

Quand zapper la spec

Toutes les tâches n'en ont pas besoin. Si tu peux décrire le diff en une phrase, prompt directement. Le spec contract, c'est pour les tâches où l'agent a une vraie latitude de décision : des changements multi-fichiers, du travail de feature, des refactors qui touchent du code partagé.

L'heuristique : si la mauvaise implémentation te coûterait plus de cinq minutes à corriger, passe deux minutes à écrire une spec. Si tu as déjà prompté le même type de tâche avant et que tu as dû recadrer, c'est la spec que tu aurais dû écrire.

Le plan mode n'est pas une spec

Claude Code a un plan mode intégré (Shift+Tab deux fois, ou tape /plan). Le plan mode produit un plan à l'intérieur d'un seul tour de conversation. Le plan vit en mémoire. Il ne survit pas à la compaction. Il ne survit pas à /clear.

Une spec, c'est un fichier sur disque. Il se fait review avant le début de l'exécution. Il persiste à travers les sessions. Le plan mode, c'est un tool que tu utilises dans la boucle. Le spec contract, c'est l'input que tu prépares avant que la boucle ne commence.

Les deux ont de la valeur. Pour le travail complexe, j'écris la spec d'abord, puis j'utilise le plan mode pour laisser Claude la valider contre la codebase avant que l'implémentation ne commence. La spec définit le contrat. Le plan mode laisse l'agent trouver comment le remplir.

Le spec contract a changé ma façon de penser la frontière entre l'intent humain et l'exécution de l'agent. Les frameworks du cours d'agentic coding sont construits à partir de mois de ce workflow exact. Commencer le cours.