Addy Osmani pubblica una guida completa sulla scrittura di specifiche efficaci per agenti di codifica AI, affrontando il problema centrale per cui specifiche enormi causano sovraccarico di contesto e degradano le prestazioni del modello.
Il primo principio sostiene di partire da una visione di alto livello piuttosto che sovra-ingegnerizzare fin dall'inizio. L'uso della Plan Mode (Shift+Tab in Claude Code) consente un'esplorazione in sola lettura prima della generazione del codice. L'agente elabora quindi i dettagli in un file SPEC.md persistente per garantire coerenza tra le sessioni.
Il secondo principio struttura le specifiche come PRD professionali che coprono sei aree essenziali: comandi eseguibili con i relativi flag, procedure di test, struttura esplicita del progetto, esempi di stile di codice, workflow git e confini chiari. Osmani propone un sistema di vincoli a tre livelli: "Always do" (azioni sicure), "Ask first" (modifiche ad alto impatto), "Never do" (blocchi assoluti come il commit di segreti).
Il terzo principio divide il lavoro in task modulari. La ricerca rivela una "maledizione delle istruzioni" per cui troppe istruzioni simultanee riducono significativamente l'aderenza del modello. Le soluzioni includono file di specifica separati (SPEC_backend.md, SPEC_frontend.md), sub-agenti specializzati e agenti paralleli per lavori non sovrapposti.
Il quarto principio integra l'auto-verifica. Il pattern "LLM-as-a-Judge" utilizza un secondo agente per verificare l'aderenza a stile e architettura. I test di conformità YAML fungono da contratti indipendenti dal linguaggio. La competenza di dominio deve essere inclusa esplicitamente: preferenze, insidie specifiche delle librerie, formati attesi.
Il quinto principio tratta le specifiche come documenti viventi versionati insieme al codice. Il ciclo continuo testa dopo ogni milestone, reimmette i fallimenti nel prompt successivo e aggiorna il documento quando le assunzioni si rivelano incomplete.
Osmani mette in guardia contro insidie comuni: specifiche eccessivamente vaghe (la modalità di fallimento dominante secondo lo studio GitHub), saltare la revisione umana perché i test passano, e confondere il "vibe coding" rapido con l'ingegneria di produzione. Identifica una "tripletta letale": velocità (difficile da revisionare), non-determinismo (output incoerenti) e costo (incoraggia scorciatoie).
La metafora centrale paragona gli agenti AI a "stagisti competenti" che richiedono istruzioni chiare, contesto pertinente e feedback praticabile. Il successo dipende dall'equilibrio tra specifiche complete e finestre di contesto mirate.