Aggiungere una funzionalità a un progetto esistente è il caso d’uso più comune — e quello in cui gli errori costano di più. L’agente non conosce i tuoi pattern interni, le tue convenzioni non scritte, i tuoi compromessi architetturali. Se non glieli spieghi, li inventa. E quando li inventa, il risultato sembra corretto ma è fuori sync con il resto del codice.

La sfida non è far scrivere codice all’agente: è far scrivere codice che sembra scritto dal tuo team.

Quando usare l’agente per questo caso 🎯

• Nuova feature in un modulo esistente — API endpoint, funzionalità UI, logica di business.
• Estensione di un’interfaccia — aggiungere campi, metodi, parametri a un’interfaccia esistente.
• Integrazione tra moduli — collegare due subsystem con un flusso nuovo.
• Bug fix contestuale — il fix richiede di capire il contesto architetturale prima di intervenire.

Quando NON usare l’agente ⛔

• Il progetto non ha test — senza rete di sicurezza, ogni modifica è un azzardo. Prima aggiungi test, poi deleghi.
• Non conosci i pattern — se non sai come gestisce gli errori il modulo target, non puoi vincolare l’agente. Studia prima, delega dopo.
• Task che toccano più di 5 moduli — frammenta in sotto-task indipendenti, ognuno con il suo contesto.

Prompt di apertura 📝

“Aggiungi [funzionalità] al modulo [x]. VINCOLI: usa lo stesso pattern di [file di riferimento], non modificare [confini/y]. FILE TARGET: [elenco]. CRITERI: [test da far passare].”

Esempio concreto:

“Aggiungi un endpoint POST /api/v2/orders nel modulo orders/. VINCOLI: usa lo stesso pattern di gestione errori di payments/handler.go, non modificare il contratto API esistente. FILE TARGET: orders/handler.go, orders/service.go, orders/model.go. CRITERI: tutti i test esistenti passano + nuovo test per l’endpoint.”

Setup del contesto 🔧

1. Apri i file di riferimento — il modulo simile esistente, le interfacce da rispettare, i test di riferimento.
2. Indica esplicitamente i pattern — “usa lo stesso pattern di gestione errori di payment.service.ts”, “segui la struttura a livelli degli altri handler Go”.
3. Definisci i confini — cosa NON deve essere toccato. L’agente è un esecutore preciso, non un architetto autonomo.

Ciclo di lavoro 💡

1. Pianifica: l’agente analizza i file di riferimento e propone un piano (moduli coinvolti, importazioni da aggiornare, test da eseguire).
2. Approva: revisiona il piano prima che l’agente scriva codice. Questo passaggio impedisce scritture affrettate o errate.
3. Esegui per micro-incrementi: dopo ogni modulo modificato, verifica build e test intermedii.
4. Resetta il contesto tra un task e il successivo — non portare il residuo di un refactoring in un bugfix.
5. Review finale: il codice generato va revisionato come ogni PR.

L’approvazione del piano è il momento più prezioso del ciclo.è qui che previeni il 90% degli errori.

Criteri di accettazione ✅

• Test esistenti ancora verdi dopo ogni incremento.
• Nuovi test per la funzionalità aggiunta.
• Nessun file fuori scope toccato.
• Aderenza ai pattern del repository (nomi, struttura, gestione errori).

Approfondimenti 📚

• Comprendere una codebase esistente — prima di aggiungere, capisci cosa c’è già. Per repository ampi, vedi la sezione su indicizzazione e scoped exploration.
• Test e TDD — la rete di sicurezza prima di ogni modifica.
• Blog: Question-driven specification — come trasformare domande in specifiche eseguibili.