Addy Osmani pubblica una guida completa alla scrittura di specifiche efficaci per agenti di coding IA, affrontando il problema centrale per cui specifiche eccessivamente voluminose causano sovraccarico di contesto e degradano le prestazioni del modello.
Il primo principio raccomanda di partire da una visione di alto livello piuttosto che ingegnerizzare eccessivamente 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 ambiti essenziali: comandi eseguibili con relativi flag, procedure di test, struttura esplicita del progetto, esempi di stile del codice, workflow git e limiti 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 suddivide il lavoro in task modulari. La ricerca rivela una "maledizione delle istruzioni" per cui troppe direttive 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 esplicitamente inclusa: preferenze, insidie specifiche delle librerie, formati attesi.
Il quinto principio tratta le specifiche come documenti vivi versionati insieme al codice. Il ciclo continuo effettua test dopo ogni milestone, reinserisce i fallimenti nel prompt successivo e aggiorna il documento quando le ipotesi si rivelano incomplete.
Osmani mette in guardia contro insidie comuni: specifiche eccessivamente vaghe (la modalità di fallimento dominante secondo lo studio GitHub), l'omissione della revisione umana perché i test passano, e la confusione tra il rapido "vibe coding" e l'ingegneria di produzione. Identifica una "trifecta letale": velocità (difficile da revisionare), non-determinismo (output incoerenti) e costo (incoraggia scorciatoie).
La metafora centrale paragona gli agenti IA a "stagisti competenti" che richiedono istruzioni chiare, contesto pertinente e feedback attuabile. Il successo dipende dall'equilibrio tra specifiche complete e finestre di contesto mirate.