# osmani-how-write-good-spec-ai-agents-2026-01-13

## Veille

Addy Osmani - scrivere spec per agenti AI, 5 principi, Plan Mode, PRD strutturato, modularità

## Titre Article

How to write a good spec for AI agents

## Date

2026-01-13

## URL

https://addyosmani.com/blog/good-spec/

## Keywords

spec, specifiche, agenti AI, Claude Code, Plan Mode, PRD, modularità, finestra di contesto, sub-agenti, testing, vibe coding, prompt engineering, SPEC.md

## Authors

Addy Osmani

## Ton

Profilo: articolo di blog tecnico, registro pedagogico e prescrittivo, prospettiva da engineering leader (Google Chrome).
Stile: strutturato attorno a 5 principi numerati con sottosezioni dettagliate. Utilizza esempi di codice concreti e tabelle comparative. Bilancia teoria e pratica. Fa riferimento a studi GitHub (oltre 2.500 agenti analizzati). Mette in guardia contro insidie comuni. Pubblico di riferimento: sviluppatori che usano agenti di codifica AI, tech lead, architetti.

## Pense-betes

- **Problema centrale**: specifiche enormi causano sovraccarico di contesto e degrado delle prestazioni del modello
- **5 principi** per specifiche efficaci: 1. **Visione di alto livello prima di tutto**: brief conciso, lasciare che l'AI elabori i dettagli 2. **Struttura PRD professionale**: 6 aree essenziali 3. **Divisione modulare**: evitare prompt monolitici 4. **Auto-verifica integrata**: vincoli e competenza di dominio 5. **Testare, iterare, evolvere**: specifiche come documenti viventi
- **Plan Mode** (Shift+Tab Claude Code): esplorazione in sola lettura prima della generazione del codice
- **SPEC.md**: file persistente per la coerenza tra sessioni
- **6 aree del PRD**: Comandi, Test, Struttura del progetto, Stile di codice, Workflow git, Confini
- **Sistema a 3 livelli**: ✅ Always do, ⚠️ Ask first, 🚫 Never do
- **"Maledizione delle istruzioni"**: prestazioni AI degradate con troppe istruzioni simultanee
- **Soluzione modularità**: file separati SPEC_backend.md, SPEC_frontend.md
- **Sub-agenti/skill**: agenti specializzati per dominio
- **LLM-as-a-Judge**: revisione da parte di un secondo agente per stile/architettura
- **Test di conformità**: suite YAML come contratti
- **Insidie comuni**: specifiche eccessivamente vaghe (dominante), saltare la revisione umana, confondere vibe coding con produzione
- **"Tripletta letale"**: velocità (difficile da revisionare) + non-determinismo + costo (incoraggia scorciatoie)
- **Metafora**: trattare gli agenti come "stagisti competenti" - istruzioni chiare, contesto pertinente, feedback praticabile
- **Strumenti citati**: Claude Code, GitHub Spec Kit, Cursor, LangGraph, OpenAI Swarm, Chroma, Context7, MCP

## RésuméDe400mots

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.

## GrapheDeConnaissance

- Addy Osmani —publie→ guide specs agents IA (DOCUMENT, 0.98)
- Addy Osmani —travaille_chez→ Google (ORGANISATION, 0.95)
- specs massives —réduit→ performance du modèle (surcharge de contexte) (CONCEPT, 0.95)
- Plan Mode —permet→ exploration read-only avant code (CONCEPT, 0.93)
- spec.md —permet→ cohérence cross-sessions (CONCEPT, 0.9)
- malédiction des instructions —réduit→ adhérence modèle (CONCEPT, 0.92)
- modularité specs —résout→ surcharge contexte (CONCEPT, 0.9)
- LLM-as-a-Judge —permet→ vérification de l'adhérence style et architecture (CONCEPT, 0.88)
- vitesse, non-déterminisme et coût —fait_partie_de→ triade létale (CONCEPT, 0.85)
- vibe coding —s_oppose_à→ ingénierie production (METHODOLOGIE, 0.83)
- Addy Osmani —recommande→ traiter les agents IA comme des stagiaires compétents (AFFIRMATION, 0.88)

---
Canonical: https://www.thekb.eu/it/fiches/osmani-how-write-good-spec-ai-agents-2026-01-13/