Contratto progetto AI: tenere il controllo dello sviluppo

Ogni sviluppatore che ha usato un agente AI su un progetto vero lo ha visto: il codice che funziona al primo colpo, elegante e veloce, e poi la scoperta due settimane dopo che quel pezzo ha saltato i test, ignorato la convenzione del progetto e — nel caso peggio — inoltrato una chiave API in un log. L'AI non è un collega indisciplinato: è un motore potentissimo senza memoria del contesto, e se non le dai regole esplicite, se le inventa. La risposta di Chris Reynolds a questo problema ha un nome che mi è piaciuto subito: project contract, e la ha presentata a WordCamp US nel talk Parenting Claude: Guardrails for AI Assisted Development. L'episodio 233 del podcast WP Tavern lo intervista, e l'idea merita un riadattamento con la mia ottica: come applicarla ai progetti WordPress di mandato — tema custom, plugin, migrazioni — senza trasformare il workflow in burocrazia.

Reynolds non è un teorico: vent'anni di WordPress, agenzie (WebDevStudios, Human Made), poi Pantheon dove oggi guida il team developer relations. Quando una persona con questo percorso dice che lo sviluppo è passato da processi deterministici a modelli non deterministici, la conseguenza operativa è precisa: se non metti tu le regole, il modello ne mette di sue.

Cos'è un project contract nei fatti

Non è un contratto legale: è un documento vivo, brevissimo, che vive nella repository e che l'agente AI legge ad ogni sessione. Nel suo contenuto minimo: standard di test (cosa va testato, come), standard di accessibilità (WCAG dove serve), convenzioni di codice del progetto, cosa è vietato (secrets nel codice, dipendenze non approvate, refactoring fuori perimetro) e la definizione di "fatto" — che non è "il codice gira", ma "il codice gira, i test passano, l'audit ARIA non segnala errori, la review umana è fatta". La forza del metodo è che l'agente rilegge il contratto a ogni sessione: la deriva non può accumularsi nel silenzio.

Nel mio flusso il contratto vive in tre file: CLAUDE.md (o AGENTS.md) per le regole generali, una checklist nel pull request template per la parte umana, e i pre-commit hooks per la parte che non deve dipendere da nessuno che si ricordi. La differenza con la documentazione classica è sostanziale: la doc era per le persone e veniva saltata; il contract è per la macchina e viene letto ogni volta. Questo ribalta l'economia dello standard: prima il costo del rispetto era la memoria umana, ora è un file che il tool consuma da solo.

Le guardrail che valgono: hooks, reviewer, secrets

Reynolds insiste su tre difese concrete che condivido in pieno, e che nei miei progetti diventano tre strati: il pre-commit hook che gira lint e test prima che il codice entri, l'agente reviewer che rilegge il diff con una checklist scritta (accessibilità, sicurezza, performance) e rilascia un parere separato, e la regola del secrets: le credenziali non transitano mai nel contesto del modello — vanno nel vault, non nel prompt. La terza sembra ovvia finché non scopri che è la violazione più frequente: un errore interno che incolla una config, un log che finisce in un test, e la chiave è nel repository.

C'è anche un aspetto economico che nel podcast affiora in trasparenza e vi conviene fissare: il costo di un agente senza guardrail non è il prezzo dell'abbonamento, è il refactor che serve due mesi dopo. Il contratto si paga da solo la prima volta che impedisce un accesso diretto al database in un tema, o un filter rimosso che qualcun altro hookava. Le guardrail non sono un freno alla velocità: sono ciò che permette di continuare ad andare veloce senza accatastare debito.

Il caso: tema custom in 3 settimane, con numeri

A luglio ho guidato un progetto con queste regole: tema block custom per un'agenzia, due sviluppatori junior più me come supervisor, Claude Code come strumento primario. Il contratto scritto in mezza giornata: convenzioni PHP/JS del team, WPCS, standard di test con Playwright sui template chiave, WCAG sui componenti interattivi, divieto di dipendenze non approvate. Risultati misurati a fine progetto: 3 settimane contro le 5 stimate senza contratto, 4 respinte di review per problemi di accessibilità invece di 11 — e soprattutto zero segreti nel codice, cosa che ad agosto con lo skimmer del checkout ho imparato a non dare per scontata. Il numero più interessante è un altro: il team junior ha prodotto 60% del codice con la supervisione giusta, ed è la demo concreta di quello che Reynolds chiama "parenting": l'AI non ti sostituisce il senior, ti moltiplica quello che un junior riesce a fare sotto traino.

Non tutto è semplice: i falsi positivi del reviewer agent hanno mangiato tempo iniziale, e il contratto va revisionato a ogni sprint, altrimenti invecchia in fretta. Prezzo alto? No: è il costo del controllo, e pagarlo a rate costa meno di pagarlo in incidente.

Perché ai progetti WordPress serve più che altrove

I progetti WordPress hanno una peculiarità che altri stack non hanno: vivono di hook, filtri e convenzioni implicite che un modello non conosce con la profondità necessaria. Un agente AI può scrivere un filtro su `save_post` impeccabile in astratto, ma solo il contratto del singolo progetto sa che quell'hook è già usato da un altro plugin del cliente, che la priorità deve stare tra 10 e 20, e che certe capacità non si possono togliere perché l'RSS aziendale dipende da lì. Il modello non può indovinare la storia del codice: il contratto è il modo per raccontargliela in una forma che consuma senza doverla dedurre.

C'è poi la questione della convivenza: i progetti WordPress raramente partono da zero. Si opera su installazioni con dieci anni di plugin, temi figlio e campi personalizzati strategici. In questo contesto un divieto che vale oro è quello di non toccare file del core o di plugin di terzi direttamente: il contratto lo scrive, l'agente lo rispetta, e il giorno dell'aggiornamento del plugin nessuno scopre patch inventate.

Come partire da domani, in 4 mosse

• Scrivi il contratto minimo: una pagina. Test obbligatori, accessibilità, convenzioni, divieto secrets, definizione di "fatto". Più di una pagina non serve: è un vincolo, non un romanzo.
• Collegalo al tool: mettilo nel file che il tuo agente legge a ogni sessione (CLAUDE.md, AGENTS.md, .cursorrules). Un contratto non letto è un contratto inesistente.
• Automatizza il controllo: pre-commit con lint e test, checklist nel template di pull request. La memoria umana non è un guardrail affidabile.
• Rivedilo a ogni sprint: le regole che non tengono dietro al progetto diventano un rifiuto formale; quelle che cambiano a ogni sprint erano troppe.

Chi lavora con clienti su siti che generano reddito ha un ulteriore livello: la parte di gestione — aggiornamenti, monitoraggio, backup — non la deve scrivere un contratto, la deve fare chi ha il protocollo già rodato: è il senso del servizio di assistenza WordPress che proponiamo, e la routine mensile ne è il motore quotidiano. L'AI accelera il sviluppo; l'assistenza WordPress è quello che tiene in piedi il resto.

Riferimenti utili

• WP Tavern #233: Chris Reynolds, building trust with project contracts for reliable AI development
• Pantheon: piattaforma e developer relations
• Creare plugin WordPress con l'AI: il metodo completo
• AI tools per sviluppatori WordPress: workflow 2026
• Manutenzione WordPress: la routine mensile
• Assistenza WordPress: piani e interventi