# Guida Pratica: Programmazione Agentica Consapevole > Per sviluppatori che vogliono **comandare** l'agente, non subirlo. --- ## Principio Zero: Tu Guidi, l'Agente Esegue L'agente è uno strumento potente e spesso **sa già quali skill e server MCP usare**: gli hooks di routing e le regole in `AGENTS.md` lo guidano automaticamente verso gli strumenti giusti. Nella maggior parte dei casi, funziona. Ma "nella maggior parte dei casi" non basta quando sviluppi in produzione. Senza istruzioni esplicite l'agente **può**: - scegliere un percorso generico invece di quello ottimale - saltare un passaggio che per te è importante - perdere contesto tra un turno e l'altro - interpretare l'ambiguità a modo suo **Regola d'oro**: l'agente sa fare molto da solo, ma **tu** devi avere il controllo consapevole. Citare esplicitamente skill e server nel prompt non è ridondante: è la differenza tra "sperare che vada bene" e "sapere cosa sta facendo". --- ## 1. La Tua Cassetta degli Attrezzi ### Server MCP (i motori) Ogni server è un motore specializzato. Citarli nel prompt forza l'agente ad usarli. | Server | Cosa fa | Quando citarlo | | ------------------ | -------------------------------------------------- | -------------------------------------------------------- | | `docs-mcp` | Cerca e naviga documentazione indicizzata | Cerchi procedure, analisi tecniche, specifiche | | `git-mcp` | Legge history, diff, blame, export delta | Investighi commit, confronti branch, esporti pacchetti | | `mantis-mcp` | Legge/scrive ticket e allegati MantisBT | Lavori su ticket, alleghi report, scrivi note | | `sql-mcp` | Query, schema, explain plan | Interroghi DB, verifichi dati, analizzi tabelle | | `linter-mcp` | Lint CFML, JS, SQL, PHP | Verifichi qualità codice prima di committare | | `cf-mcp` | Bridge ColdFusion per ispezione runtime | Debug CFML, verifica valori a runtime | | `office-mcp` | Legge/crea Word, Excel, PDF + conversioni Pandoc | Leggi allegati, crei report, esporti documenti | | `playwright-mcp` | Browser automation, screenshot, DOM | Testi UI, fai screenshot di verifica, debug frontend | | `memory-mcp` | Memoria operativa persistente tra sessioni | Salvi decisioni, recuperi contesto, fai handoff | | `projectfs-mcp` | Lettura file fuori workspace | Accedi a file su path condivisi o fuori progetto | ### Skill (le competenze) Le skill sono **istruzioni strutturate** che guidano l'agente in workflow complessi. Citarle esplicitamente attiva il comportamento corretto. | Skill | Quando usarla | Prompt trigger | | ---------------------------- | --------------------------------------------------------- | ---------------------------------------------- | | `mcp-technical-analyst` | Analisi multi-sorgente (ticket + docs + commit + DB) | *"Usa la skill mcp-technical-analyst..."* | | `mcp-code-reviewer` | Review codice, diff, commit, branch | *"Usa la skill mcp-code-reviewer..."* | | `mcp-master-orchestrator` | Task multi-fase (analisi → sviluppo → review → test) | *"Usa la skill mcp-master-orchestrator..."* | | `mcp-git-mantis-workflow` | Correlazione ticket ↔ commit, rebase, allegati | *"Usa la skill mcp-git-mantis-workflow..."* | | `mcp-docs-navigator` | Ricerca e manutenzione corpus documentale | *"Usa la skill mcp-docs-navigator..."* | | `mcp-database-expert` | Query, schema, confronti ambienti | *"Usa la skill mcp-database-expert..."* | | `mcp-coldfusion-developer` | Sviluppo/debug CFML | *"Usa la skill mcp-coldfusion-developer..."* | | `mcp-sophia-yii-developer` | Sviluppo/debug PHP/Yii (Sophia Framework) | *"Usa la skill mcp-sophia-yii-developer..."* | | `mcp-browser-automation` | Test UI, flussi utente, screenshot | *"Usa la skill mcp-browser-automation..."* | | `mcp-mantis-ticket-writer` | Scrittura/refinement ticket Mantis | *"Usa la skill mcp-mantis-ticket-writer..."* | | `mcp-office-expert` | Documenti Office, PDF, conversioni | *"Usa la skill mcp-office-expert..."* | | `mcp-memory-operator` | Persistenza decisioni, handoff, contesto | *"Usa la skill mcp-memory-operator..."* | ### Subagent portabili vs skill I **subagent portabili** sono ruoli operativi (persona/missione), mentre le **skill** sono workflow e procedure specialistiche legate al contesto MCP. | Nome | Tipo | Uso tipico | | --- | --- | --- | | `explorer` | Subagent portabile | Raccolta contesto tecnico e ricognizione rapida | | `implementer` | Subagent portabile | Implementazione mirata con delta minimo | | `technical_analyst` | Subagent portabile | Analisi tecnica strutturata con evidenze/inferenze | | `code_reviewer` | Subagent portabile | Review focalizzata su bug/rischi/regressioni | | `test_writer` | Subagent portabile | Stesura piano di test e casi verificabili | | `mcp-technical-analyst` | Skill | Workflow multi-sorgente ticket/docs/commit/DB | | `mcp-code-reviewer` | Skill | Checklist e metodo di review per diff/commit/branch | > Nota operativa: i subagent **non** si attivano da soli come le skill di routing. Vanno richiesti/delegati in modo esplicito quando serve quel ruolo (es. "delega review a `code_reviewer`", "delega piano test a `test_writer`"). ### Hooks (pilota automatico parziale) Gli hooks intercettano il tuo prompt e suggeriscono all'agente gli strumenti giusti **automaticamente**. Ma non sono sufficienti da soli: servono come rete di sicurezza, non come sostituto delle tue istruzioni esplicite. Cosa fanno: - **SessionStart**: carica contesto bootstrap all'avvio - **UserPromptSubmit**: analizza il tuo prompt e suggerisce routing verso skill/server pertinenti - **PreToolUse**: prima di usare SQL o ColdFusion, ricorda vincoli di sicurezza > **Tip**: gli hooks aiutano, ma **non sostituiscono** il citare esplicitamente skill e server nel prompt. Un prompt esplicito batte sempre un hint automatico. --- ## 2. Workflow Completo: Dal Ticket alla Chiusura Questo è il flusso standard. Ogni fase ha il suo prompt-tipo. ``` 📋 Fase 1: Analisi ↓ 📝 Fase 2: Pianificazione ↓ ⚙️ Fase 3: Sviluppo ↓ 🔍 Fase 4: Review ↓ Evidenze? ── Sì ──→ Torna a Fase 3 │ No ↓ 📎 Fase 5: Report su Ticket ↓ 🧪 Fase 6: Piano di Test ↓ ✅ Fase 7: Esecuzione Test ↓ 📌 Fase 8: Chiusura Ticket ``` --- ### Fase 1: Analisi del Materiale **Obiettivo**: capire cosa fare prima di scrivere una riga di codice. **Quando**: hai un ticket Mantis, un'analisi funzionale, un documento tecnico, o un mix di tutto questo. #### Prompt per analisi da ticket ``` Usa la skill mcp-technical-analyst in modalità ticket-first. Parti dal ticket {NUMERO_TICKET}. 1. Leggi il ticket con tutte le note e gli allegati 2. Cerca nei documenti indicizzati (docs-mcp) materiale correlato 3. Se ci sono allegati PDF o Word, leggili con office-mcp 4. Controlla se ci sono commit correlati nel repository 5. Produci un report con: contesto, evidenze osservate, inferenze, punti aperti ``` #### Prompt per analisi da documento ``` Usa la skill mcp-technical-analyst in modalità document-first. 1. Leggi il documento "E:\docs\analisi-funzionale-xyz.pdf" con office-mcp (pdf_document export_text) 2. Cerca nei documenti indicizzati materiale correlato a [argomento] 3. Se il documento cita ticket, leggili con mantis-mcp 4. Produci un report con: requisiti estratti, vincoli, punti aperti, dipendenze ``` #### Prompt per analisi rapida (quando il ticket è semplice) ``` Usa la skill mcp-technical-analyst in modalità ticket-first-light. Ticket {NUMERO_TICKET}. Fornisci contesto, evidenze, inferenze e punti aperti prioritari. Se rilevi complessità multi-sorgente, indicami l'escalation. ``` > **Importante**: non saltare mai la fase di analisi. Anche per un bug semplice, un'analisi rapida (`ticket-first-light`) ti evita di partire con assunzioni sbagliate. --- ### Fase 2: Pianificazione dello Sviluppo **Obiettivo**: avere un piano chiaro prima di far scrivere codice all'agente. ``` Basandoti sull'analisi appena prodotta, prepara un piano di implementazione. Per ogni modifica indica: - file da modificare (puoi citarli in chat con @) - cosa cambiare e perché - impatto su altri file/componenti - rischi e punti di attenzione NON implementare nulla. Produci solo il piano. ``` > **Attenzione**: mai far implementare senza piano. L'agente senza piano fa quello che gli sembra logico, non quello che serve a te. --- ### Fase 3: Sviluppo **Obiettivo**: implementare seguendo il piano approvato. #### Se lo sviluppo lo fai tu Semplicemente sviluppi tu, usando l'agente come consulente: ``` Sto implementando il punto 2 del piano: modifica a fan_plant_fornitori_ele.cfc. Devo aggiungere il campo PIVA alla grid. Mostrami come farlo seguendo il pattern già usato per il campo CurrencyCode nello stesso file. ``` #### Se lo sviluppo lo delega all'agente Usa **sempre** la modalità di pianificazione e implementazione controllata: ``` Implementa il punto 1 del piano approvato. Cita i file se necessario: @fan_plant_fornitori_ele.cfc Vincoli: - segui il pattern esistente nel file per colonne grid - non toccare altri file - linta il file con linter-mcp dopo la modifica - mostrami il diff prima di procedere al punto successivo ``` > **Tip**: un punto alla volta. Non chiedere mai "implementa tutto il piano". L'agente perderà contesto e farà errori. Procedi punto per punto e verifica ogni step. --- ### Fase 4: Verifica Sviluppi Effettuati (Review Sviluppatore) **Obiettivo**: Al completamento dello sviluppo indicato nel Ticket, validare il codice prodotto per accertarsi che rispetti le richieste e non presenti anomalie, prima di consegnare il lavoro. ```text Usa la skill mcp-code-reviewer. Delega la review al subagent `code_reviewer`. Esegui un prompt di verifica sui file modificati per il ticket {NUMERO_TICKET}: (puoi citare hash della commit o riferirti a "sviluppo in corso") Controlla: - coerenza con le indicazioni del ticket e l'analisi iniziale - correttezza funzionale e assenza di regressioni - aderenza alle convenzioni di progetto Output: Esito della verifica. Se ci sono anomalie, elenca i finding con severità e fix suggerito. ``` #### Eventuale Correzione (Finché Esito non è OK) Se la verifica fallisce, fai correggere all'agente le evidenze trovate: ```text Correggi il finding #2 nel file fan_plant_fornitori_ele.cfc. Applica il fix suggerito nella review e linta il file dopo la correzione. ``` Ripeti il prompt di verifica (Fase 4) finché l'esito non è "OK". --- ### Fase 5: Report, Aggiornamento Ticket e Chiusura Sviluppo **Obiettivo**: Quando l'esito della verifica è OK, generare un report, incollarlo nel ticket e passarlo in stato completato (pronto per il Valutatore). ```text Usa la skill mcp-git-mantis-workflow. project_path: "E:\mio-progetto" 1. Prepara una nota di completamento sviluppo per il ticket {NUMERO_TICKET} con: - riepilogo delle modifiche effettuate seguendo le indicazioni - file modificati - conferma che la verifica/review del codice ha dato esito OK 2. Aggiungi la nota al ticket con mantis_add_note. Se c'è un report esteso di review, allegalo con mantis_files. ``` **Azione dello Sviluppatore**: Una volta incollato il report nel ticket, lo sviluppatore **passa il ticket in stato COMPLETATO (es. RESOLVED)** per sottoporlo al Valutatore (Senior). --- ### Fase 6: Piano di Test **Obiettivo**: avere un piano di test strutturato prima di testare. ``` Basandoti sull'analisi iniziale e sulle modifiche implementate, prepara un piano di test. Delega la stesura al subagent `test_writer`. Per ogni test indica: - ID test (es. T01, T02) - scenario e precondizioni - passi da eseguire - risultato atteso - tipo: funzionale / regressione / edge case Considera sia i casi positivi che negativi. NON eseguire i test, prepara solo il piano. ``` --- ### Fase 7: Esecuzione dei Test I test **li esegui tu** (o li fai eseguire all'agente via browser se applicabile). #### Test manuali Esegui i test dal piano e documenta i risultati. #### Test via browser (se l'applicazione è web) ``` Usa la skill mcp-browser-automation. Esegui il test T01 dal piano di test: 1. Naviga a http://localhost/app/fornitori/edit?id=123 2. Verifica che il tab "Sites" sia visibile 3. Apri il tab e verifica che il campo PIVA sia presente 4. Fai screenshot della pagina Riporta esito: PASS o FAIL con evidenza. ``` #### Documentazione risultati ``` Usa la skill mcp-git-mantis-workflow. Prepara un riepilogo dei risultati di test: | Test | Esito | Note | |------|-------|------| | T01 | PASS | Tab visibile, campo presente | | T02 | PASS | Salvataggio OK | | T03 | FAIL | Validazione PIVA non attiva | Allega questo riepilogo al ticket {NUMERO_TICKET} come nota. ``` --- ### Fase 8: Chiusura ``` Usa la skill mcp-git-mantis-workflow. Aggiungi una nota di chiusura al ticket {NUMERO_TICKET}: - sviluppo completato - review superata - test eseguiti con esito (riferimento ai risultati allegati) - eventuali note per il deploy ``` --- ## 3. Ricette Veloci ### Cercare documentazione prima di sviluppare ``` Usa docs-mcp. Cerca nei documenti indicizzati tutto quello che riguarda "[argomento]". Prova sia in italiano che in inglese. Se non trovi nulla, elenca i tag disponibili e riprova filtrando per tag. ``` ### Verificare lo schema DB prima di una query ``` Usa sql-mcp. Mostrami lo schema della tabella T960RICHJOB. ``` ### Leggere un allegato PDF da un ticket ``` Usa mantis-mcp per scaricare l'allegato {FILE_ID} dal ticket {NUMERO_TICKET}. Salvalo in E:\tmp\allegato.pdf. Poi leggilo con office-mcp (pdf_document read_all). ``` ### Confrontare due branch ``` Usa git-mcp. Confronta il branch feature/sites con develop. Mostrami stat e diff dei file modificati. ``` ### Salvare una decisione tecnica per sessioni future ``` Usa la skill mcp-memory-operator. Salva questa decisione nel progetto: - scope: architettura - topic: gestione-sites - source_type: decision - contenuto: "I siti fornitore usano PIVA come identificativo univoco, non il codice fiscale, per compatibilità con il flusso SEAS." ``` ### Scrivere un ticket nuovo ``` Usa la skill mcp-mantis-ticket-writer. Scrivi un ticket bug-standard con queste informazioni: - Argomento: Gestione Fornitori - Argomento2: Tab Sites - Problema: il campo PIVA non viene validato al salvataggio - Impatto: dati potenzialmente errati in produzione - Riproduzione: confermata in ambiente dev ``` --- ## 4. Anti-Pattern: Cosa NON Fare | ❌ Non fare | ✅ Fai invece | | -------------------------------------------------------- | ---------------------------------------------------------------------------- | | "Sistemami questo bug" (zero contesto) | "Analizza il ticket 12345 con mcp-technical-analyst, poi proponi un piano" | | "Implementa tutto" (in un colpo) | Implementa un punto alla volta, verifica, procedi | | "Fai review" (senza specificare cosa) | "Usa mcp-code-reviewer su questi file specifici: ..." | | Dare per scontato che l'agente usi lo strumento giusto | Citare esplicitamente server e skill nel prompt | | Lasciare che l'agente decida la struttura del codice | Indicare pattern e file di riferimento da seguire | | Non verificare mai l'output dell'agente | Review + lint + test sempre prima di committare | | Far scrivere codice senza aver letto il contesto | Analisi prima, sviluppo dopo. Sempre | | "Cerca nella documentazione" (generico) | "Cerca con docs-mcp, prova IT/EN, se vuoto elenca i tag e riprova" | --- ## 5. Prompt Engineering: Struttura Vincente Un buon prompt per l'agente ha questa struttura: ``` 1. SKILL/SERVER da usare (esplicito) 2. CONTESTO: project_path, file, ticket 3. COSA FARE: azione precisa, non generica 4. VINCOLI: pattern da seguire, file da non toccare, limiti 5. OUTPUT ATTESO: formato, dove salvarlo, cosa farne dopo ``` ### Esempio completo (ColdFusion) ``` Usa la skill mcp-coldfusion-developer. Modifica il file client/cflib/cfc/fan_plant_fornitori_ele.cfc: - Aggiungi una colonna "PIVA" alla grid, dopo la colonna "CurrencyCode" - Segui lo stesso pattern usato per CurrencyCode (stessa larghezza, stesso tipo) - Non modificare il controller o il gestionale, solo la vista Dopo la modifica: - Linta il file con linter-mcp - Mostrami il diff delle modifiche ``` ### Esempio completo (Sophia/Yii) ``` Usa la skill mcp-sophia-yii-developer. Devo aggiungere un campo "codice_fiscale" alla griglia fornitori. - Identifica il layer corretto (FRM/APP/CLI-client) - Controlla il controllerMap per capire quale controller gestisce la vista - Segui il pattern RenderSettings già usato per le altre colonne - Non toccare il model, solo la configurazione griglia Dopo la modifica: - Linta i file PHP con linter-mcp - Mostrami il diff delle modifiche ``` --- ## 6. Quando Serve Quale Skill: Decision Tree ``` Il mio task riguarda... ├─ Un ticket con docs/commit/DB da correlare? │ └─ mcp-technical-analyst (ticket-first o document-first) │ ├─ Solo codice da scrivere/fixare? │ ├─ CFML → mcp-coldfusion-developer │ ├─ PHP/Yii (Sophia) → mcp-sophia-yii-developer │ ├─ SQL → mcp-database-expert │ └─ Altro → prompt diretto + lint │ ├─ Solo review codice? │ └─ mcp-code-reviewer │ ├─ Test UI / verifica visiva? │ └─ mcp-browser-automation │ ├─ Scrivere/leggere ticket? │ ├─ Scrivere testo ticket → mcp-mantis-ticket-writer │ └─ Correlare ticket ↔ codice → mcp-git-mantis-workflow │ ├─ Cercare documentazione? │ └─ mcp-docs-navigator │ ├─ Leggere/creare documenti Office/PDF? │ └─ mcp-office-expert │ ├─ Task multi-fase (analisi + sviluppo + review + test)? │ └─ mcp-master-orchestrator │ └─ Salvare/recuperare decisioni tra sessioni? └─ mcp-memory-operator ``` --- ## 7. Cheat Sheet | Azione | Prompt minimo | | ------------------ | --------------------------------------------------------------------------------- | | Analisi ticket | `Usa mcp-technical-analyst ticket-first. Ticket {ID}` | | Analisi rapida | `Usa mcp-technical-analyst ticket-first-light. Ticket {ID}` | | Cerca docs | `Usa docs-mcp, cerca "{query}" nel progetto, prova IT/EN` | | Review codice | `Usa mcp-code-reviewer su {files}` | | Lint file | `Linta {file} con linter-mcp` | | Schema DB | `Usa sql-mcp, schema della tabella {nome}` | | Query DB | `Usa sql-mcp, esegui: SELECT ... FROM ...` | | Nota ticket | `Usa mantis-mcp, aggiungi nota al ticket {ID}: "..."` | | Allega file | `Usa mantis-mcp, allega {file} al ticket {ID}` | | Screenshot UI | `Usa playwright-mcp, naviga a {URL}, screenshot` | | Leggi PDF | `Usa office-mcp, leggi il PDF "{path}"` | | Salva decisione | `Usa mcp-memory-operator, salva decisione scope:{s} topic:{t}` | | Piano di test | `Prepara piano di test basandoti su analisi e modifiche fatte` | | Export delta git | `Usa git-mcp, export_zip tra {branch1} e {branch2}, save_path "..."` | | Fix Sophia/Yii | `Usa mcp-sophia-yii-developer, identifica layer e controllerMap per {action}` | --- ## 8. Guida per il Valutatore (Senior) Il Valutatore (Senior) interviene quando lo sviluppo è completato e documentato. L'obiettivo è validare il lavoro svolto e definire i test necessari prima del passaggio alla validazione. **Flusso operativo:** 1. **Verifica Report:** Controlla la nota riepilogativa inserita dallo sviluppatore nel ticket. 2. **Verifica Indipendente:** Usa l'agente per una review autonoma (double-check) del codice. 3. **Generazione Casi di Test:** Se il report e il codice sono OK, chiedi all'agente di generare i casi di test. 4. **Avanzamento e Assegnazione:** Passa il ticket nello stato "READY to TEST" e assegna l'esecuzione dei test allo sviluppatore (o a un tester designato). ### Prompt per la verifica indipendente (Double-check) Simile a quello dello sviluppatore, ma focalizzato sulla validazione complessiva: ```text Usa la skill mcp-code-reviewer. Agisci come Senior Reviewer per il ticket {NUMERO_TICKET}. 1. Leggi il contesto del ticket e il report inserito dallo sviluppatore (tramite mantis-mcp). 2. Identifica e analizza le modifiche al codice (hash commit o file). 3. Verifica: correttezza funzionale, assenza di regressioni e aderenza alle logiche di progetto. 4. Produci un verdetto sintetico: APPROVATO o DA CORREGGERE (con lista dei finding). ``` ### Prompt per la generazione dei casi di TEST Una volta approvata la review, genera il piano di test per l'assegnatario: ```text Usa la skill mcp-mantis-ticket-writer. Delega la generazione al subagent `test_writer`. Basandoti sull'analisi del ticket {NUMERO_TICKET} e sulle relative modifiche, genera un Piano di Test completo per lo stato READY to TEST. Per ogni test indica: - ID test (es. T01, T02) - Scenario e precondizioni - Passi dettagliati da eseguire - Risultato atteso Aggiungi il piano di test generato come nota al ticket, specificando che i test sono pronti per essere assegnati ed eseguiti. ``` --- > **Nota**: questa guida si affianca al [README.md](../README.md) (installazione e configurazione) e all'[AGENTS.md](../AGENTS.md) (governance e regole permanenti). Per dettagli tecnici sui server e le skill, consulta i file `SKILL.md` nella directory `skills/`.