Addy Osmani publie un guide complet sur la rédaction de spécifications efficaces pour agents de codage IA, adressant le problème central que les specs massives causent une surcharge de contexte et dégradent les performances des modèles.
Le premier principe préconise de commencer par une vision haut niveau plutôt que de sur-ingénierer d'emblée. Utiliser le Plan Mode (Shift+Tab dans Claude Code) permet une exploration en lecture seule avant génération de code. L'agent élabore ensuite les détails dans un fichier SPEC.md persistant pour la cohérence entre sessions.
Le second principe structure les specs comme des PRD professionnels couvrant six domaines essentiels : commandes exécutables avec flags, procédures de test, structure projet explicite, exemples de code style, workflow git, et limites claires. Osmani propose un système de contraintes à trois niveaux : "Always do" (actions sûres), "Ask first" (changements à fort impact), "Never do" (arrêts durs comme commiter des secrets).
Le troisième principe divise le travail en tâches modulaires. La recherche révèle une "malédiction des instructions" où trop de consignes simultanées réduisent significativement l'adhérence du modèle. Les solutions incluent des fichiers spec séparés (SPEC_backend.md, SPEC_frontend.md), des sub-agents spécialisés, et des agents parallèles pour travaux non-chevauchants.
Le quatrième principe intègre des auto-vérifications. Le pattern "LLM-as-a-Judge" utilise un second agent pour vérifier l'adhérence au style et à l'architecture. Les tests de conformance en YAML servent de contrats indépendants du langage. L'expertise domaine doit être explicitement incluse : préférences, pièges spécifiques aux bibliothèques, formats attendus.
Le cinquième principe traite les specs comme documents vivants versionnés avec le code. Le cycle continu teste après chaque milestone, réinjecte les échecs dans le prompt suivant, et met à jour le document quand les hypothèses s'avèrent incomplètes.
Osmani met en garde contre les pièges fréquents : specs trop vagues (échec dominant selon l'étude GitHub), skip de la review humaine parce que les tests passent, et confusion entre "vibe coding" rapide et ingénierie de production. Il identifie une "triade létale" : vitesse (difficile à reviewer), non-déterminisme (outputs inconsistants), et coût (encourage les raccourcis).
La métaphore centrale compare les agents IA à des "stagiaires compétents" nécessitant instructions claires, contexte pertinent et feedback actionnable. Le succès dépend de l'équilibre entre specs complètes et fenêtres de contexte focalisées.