Une spécification suffisamment détaillée, c’est du code

• À propos de l’affirmation selon laquelle, avec le codage agentique, « la documentation de spécification peut remplacer le code », une limite fondamentale est soulignée : si une spécification devient suffisamment précise, elle finit inévitablement par converger vers la même forme que le code
• Le projet Symphony d’OpenAI montre que le fichier SPEC.md concerné n’est pas une spécification, mais en pratique un pseudocode au format Markdown
• En tentant réellement une implémentation en Haskell à partir de la spécification de Symphony, de nombreux bugs et des problèmes de fiabilité sont apparus, notamment une attente infinie de l’agent
• Le travail de spécification exige à l’origine une réflexion plus profonde que le codage, mais dans le climat actuel d’optimisation de la vitesse dans l’industrie, cela conduit à la production en masse de spécifications médiocres générées par l’IA
• Le principe « garbage in, garbage out » s’applique tel quel aussi aux agents de codage, et avec des documents dépourvus de clarté et de détail, il est impossible de générer du code fiable

---

Deux malentendus sur le codage agentique

• Les défenseurs du codage agentique s’appuient sur deux malentendus centraux
  • Malentendu 1 : un document de spécification est plus simple que le code correspondant — une vision de type externalisation, selon laquelle on pourrait transformer les ingénieurs en gestionnaires rédigeant des spécifications et déléguer le travail à une équipe d’agents
  • Malentendu 2 : le travail de spécification est nécessairement plus réfléchi que le travail de codage — l’idée qu’en passant par un document de spécification, on améliorerait la qualité et on encouragerait de meilleures pratiques d’ingénierie

Du code déguisé en spécification : analyse du cas Symphony

• Le projet Symphony d’OpenAI est présenté comme un orchestrateur d’agents généré à partir d’un document de spécification (SPEC.md), mais en réalité le contenu de ce SPEC.md se rapproche davantage d’un pseudocode au format Markdown que d’une spécification
• Types de contenu inclus dans SPEC.md :
  • Dump rédigé en prose du schéma de base de données — énumération de champs comme session_id, thread_id, codex_input_tokens, etc.
  • Transformation en prose de code — formules comme available_slots = max(max_concurrent_agents - running_count, 0) pour le contrôle de concurrence, ou la formule de backoff de nouvelle tentative (delay = min(10000 * 2^(attempt-1), agent.max_retry_backoff_ms))
  • Sections redondantes comme « Config Fields Summary (Cheat Sheet) », explicitement ajoutées pour aider le modèle à générer du code
  • Sections « Reference Algorithms » qui sont en pratique du code à l’état pur, comme la fonction start_service()
• Affirmer qu’un document de spécification remplace le code alors que ce document se lit lui-même comme du code est trompeur
• Pour rendre un document de spécification suffisamment précis, il faut inévitablement le transformer sous une forme proche du code, ou l’écrire dans un anglais formel hautement structuré

L’argument de « l’interface étroite » chez Dijkstra

• En citant Dijkstra, le texte rappelle que le choix d’une interface n’est pas une simple répartition du travail, et qu’il ajoute un coût de collaboration et de communication à travers cette interface
• Exemples historiques à l’appui : les mathématiques grecques ont stagné en restant dans des activités langagières et visuelles, l’algèbre islamique a décliné en revenant à un style rhétorique, et l’Europe occidentale a progressé en s’éloignant des « vaines tentatives de précision verbale » du scolasticisme médiéval grâce aux systèmes symboliques formels de Vieta, Descartes, Leibniz, Boole et d’autres
• Les codeurs agentiques ne peuvent pas éviter le « narrow interface » (= le code) qu’exige le travail d’ingénierie ; ils ne peuvent que transformer ce travail en une forme qui paraît différente en surface mais exige la même précision

Instabilité : les problèmes de fiabilité de la génération de code à partir d’une spécification

• En demandant à Claude Code une implémentation en Haskell comme le recommande le README de Symphony, le résultat ne fonctionne pas
  • De nombreux bugs apparaissent, nécessitant des corrections via les prompts (vérifiables dans l’historique des commits)
  • Même dans les cas où cela « fonctionne » sans message d’erreur, l’agent codex reste bloqué en attente infinie sans aucun progrès sur un ticket Linear simple (« créer un dépôt git vide »)
• Pour reprendre l’expression de Dijkstra, cela confirme que les « vaines tentatives de précision verbale » de Symphony échouent toujours à produire une implémentation fiable
• Le problème ne se limite pas à Symphony — même des spécifications comme YAML, extrêmement détaillées, largement utilisées et dotées de suites de tests de conformité, voient la majorité des implémentations YAML ne pas respecter complètement la spec
• La spécification de Symphony représente déjà un sixième de la taille de l’implémentation Elixir incluse ; en l’étendant davantage, on finirait dans une situation comparable à « De la rigueur de la science » de Borges — la fable d’une carte de l’empire à l’échelle de l’empire lui-même, devenue finalement inutile
• À l’objection selon laquelle « le résultat serait meilleur dans un langage plus mainstream », l’auteur répond que si les agents peinent à générer du code Haskell, cela suggère un manque de capacité de généralisation au-delà des données d’entraînement

Slop : le problème de qualité des spécifications générées par l’IA

• Le travail de spécification devrait à l’origine être plus difficile que le codage ; son but est d’amener à considérer un projet avec un regard réfléchi et critique avant de commencer à coder
• Mais dans la tendance actuelle du secteur tech à réduire et dévaloriser le travail, partir de l’hypothèse que « le travail de spécification est plus facile que le codage » mène à un échec programmé
• Il est impossible d’accomplir le travail difficile et inconfortable qu’exige la rédaction de spécifications tout en poursuivant l’optimisation de la vitesse de livraison
• La section 10.5 du SPEC.md de Symphony (contrat d’extension linear_graphql) est un exemple représentatif de slop — une production d’agent faite de phrases qui ressemblent à une spécification mais manquent de cohérence, de finalité et de compréhension d’ensemble
  • Des règles individuelles sont listées, comme le fait que query doit être une chaîne non vide et contenir exactement une opération GraphQL, mais le contexte global manque
• Même lorsqu’ils sont écrits par des humains, de tels documents de spécification sont inévitablement du slop — parce qu’ils sont optimisés pour le délai de livraison plutôt que pour la cohérence ou la clarté
• Le fait que des snippets de code soient annotés comme text sans coloration syntaxique est aussi un signe de document généré par l’IA — vraisemblablement parce que le modèle a suivi la lettre de la demande plutôt que son intention

Conclusion

• Les spécifications n’ont pas été conçues à l’origine comme un mécanisme de gain de temps
• Si l’objectif est l’optimisation du délai de livraison, il est plus avantageux d’écrire directement le code que de passer par un document de spécification intermédiaire
• Le principe « garbage in, garbage out » s’applique ici sans changement — si l’entrée est un document manquant de clarté et de détail, il n’existe pas de monde dans lequel un agent de codage pourra combler ce manque de manière fiable
• Les agents de codage ne lisent pas dans les pensées ; et même s’ils le pouvaient, si la pensée elle-même est confuse, ils ne peuvent rien y faire