Il Task Contract

Un Task Contract è il confine operativo approvato per una singola unità di lavoro. Non è soltanto un riepilogo della richiesta e non è un prompt molto lungo destinato a controllare ogni riga di codice.

Serve a rendere esplicite, prima dell’implementazione, le parti sostanziali del task:

• quale risultato è autorizzato;
• quali evidenze di progetto e assunzioni sostengono il lavoro;
• cosa può essere modificato;
• cosa deve restare invariato;
• quali comportamenti dimostrano il completamento;
• quali controlli sono richiesti;
• quando l’agente deve fermarsi e chiedere una decisione.

Il Task Contract autorizza il lavoro. La sua generazione non autorizza l’implementazione finché il developer non lo ha revisionato e approvato.

Perché una richiesta non è sufficiente

Una richiesta in linguaggio naturale può essere chiara sul risultato desiderato e lasciare comunque aperte domande implementative importanti. Il modello AI potrebbe riempire questi vuoti con assunzioni, ampliare il perimetro o scegliere un’architettura mai richiesta.

Il Task Contract converte la richiesta e lo stato pertinente del progetto in una superficie decisionale revisionabile. Espone le assunzioni prima che diventino codice e fornisce al developer un oggetto concreto da correggere.

Cosa contiene un contratto utile

La rappresentazione esatta può variare, ma un contratto completo dovrebbe rendere visibili gli elementi seguenti.

Fonte del task

Indica da dove nasce il lavoro: richiesta diretta del developer, elemento del backlog, GitHub Issue, analisi, bug report o un’altra fonte dichiarata. Quando esiste, conserva l’identificativo originale.

Obiettivo

Descrive il risultato osservabile, non soltanto l’implementazione preferita. Un buon obiettivo specifica cosa dovrà essere vero dopo il task.

Analisi pertinente

Registra soltanto i fatti di progetto necessari ad autorizzare il lavoro: comportamento corrente, architettura rilevante, funzioni esistenti, vincoli, dipendenze e incertezze.

Superficie di modifica consentita

Identifica file, moduli o aree comportamentali che si prevede di modificare. La superficie deve essere abbastanza ampia da consentire un’implementazione coerente, ma non così generica da permettere ristrutturazioni estranee.

Aree da preservare ed esclusioni

Dichiara ciò che non deve cambiare. Le esclusioni tipiche comprendono feature non coinvolte, dipendenze, interfacce condivise, validazioni esistenti, formattazione dell’intero repository, infrastruttura, cronologia Git e documentazione esterna al task.

Criteri di accettazione

Definiscono condizioni osservabili che dimostrano l’esistenza del comportamento richiesto. Devono essere abbastanza specifici da permettere la review senza imporre dettagli implementativi non necessari.

Verifica

Dichiara i comandi automatici e i controlli manuali minimi pertinenti. Il contratto dovrebbe distinguere i controlli eseguibili dall’agente da quelli affidati al developer.

Condizioni di arresto

Spiega quando l’agente deve fermarsi invece di improvvisare. Esempi: evidenze contraddittorie, dipendenza necessaria ma assente, espansione del perimetro, operazione distruttiva non autorizzata o decisione architetturale non coperta dal task.

Come revisionare un Task Contract

Prima di approvarlo, verifica:

• L’obiettivo corrisponde alla richiesta reale?
• Le assunzioni sono sostenute dal repository o dichiarate come incerte?
• La superficie di modifica è coerente e proporzionata?
• I comportamenti funzionanti e le modifiche del developer sono protetti?
• I criteri di accettazione sono osservabili?
• I controlli sono realistici per il progetto corrente?
• Le operazioni vietate sono visibili?
• Una nuova decisione sostanziale richiederebbe un emendamento o un task separato?

Correggi o rifiuta il contratto quando nasconde incertezze, include refactoring estranei, nomina file senza aver ispezionato il repository o descrive una capability proposta come se fosse già implementata.

Approvazione e implementazione

L’approvazione deve essere esplicita. Dopo l’approvazione, l’agente può implementare soltanto il lavoro autorizzato, rispettando lo stato corrente del repository.

L’approvazione non limita la libertà del developer. Il developer può continuare a modificare qualsiasi codice, cambiare direzione o svolgere direttamente parte del lavoro. Queste modifiche diventano stato corrente e l’agente deve integrarsi con esse.

Quando cambia il contratto

Un chiarimento che non modifica il risultato autorizzato può essere registrato senza sostituire il contratto. Anche un adattamento tecnico locale può essere accettabile quando resta dentro obiettivo, superficie di modifica e criteri di accettazione.

Una modifica sostanziale richiede un emendamento quando cambia perimetro, comportamento, file, controlli o esclusioni. Un obiettivo principale differente dovrebbe normalmente diventare un task separato.

Il contratto aggiornato dovrebbe mostrare:

• cosa è cambiato;
• cosa resta valido;
• lavoro già completato;
• controlli da ripetere;
• nuovo stato di approvazione.

Dimensione del contratto

Il contratto dovrebbe essere il più piccolo possibile, ma sufficiente per una review e un’implementazione autonome. Piccolo non significa vago.

Una modifica di una riga può richiedere un contratto compatto. Una feature trasversale può richiedere file coordinati, vincoli comportamentali e più controlli. La dimensione corretta segue rischio e superficie decisionale, non una lunghezza fissa del template.

Relazione con preservation-first

Il Task Contract definisce la modifica autorizzata. Preservation-first definisce come quella modifica deve essere integrata nel software esistente.

Insieme evitano due errori opposti:

• modificare troppo perché il confine del task è vago;
• modificare troppo poco o in modo incoerente perché è stata ignorata l’architettura locale.

Il contratto può quindi indicare metodi, utility, guard, interfacce pubbliche o pattern locali che l’implementazione deve riusare o preservare.