Introduzione all’Agentic Coding con IA
L’Intelligenza Artificiale (IA) ha cambiato il modo in cui concepiamo lo sviluppo software. Non si tratta più solo di chiedere a un sistema di completare una riga di codice: oggi possiamo lavorare con agenti che comprendono obiettivi, seguono convenzioni, mantengono documentazione viva e collaborano con noi in modo simile a un altro membro del team. Questo approccio lo chiameremo “Agentic Coding”. Questa guida, ampia e pratica, ti spiegherà come passare dall’idea a un flusso professionale in cui l’IA si integra nella tua vita quotidiana come sviluppatore, concentrandoci su WordPress e su un processo reale che potrai replicare nei tuoi progetti.
Troverai, da un lato, la base concettuale necessaria per comprendere l’IA moderna e il ruolo dei LLM (Large Language Models). Dall’altro, vedrai come organizzare il lavoro con file chiave che articolano tutto il processo: AGENTS.md (regole e ambito), TODO.md (tabellone che gestisce l’agente) e Documents.md (documentazione viva). Inoltre, includiamo buone pratiche, limitazioni reali e una sezione di esempio pratico che fungerà da scheletro di progetto, con spazi chiaramente contrassegnati affinché in seguito possiamo incorporare contenuti tecnici concreti (codice, strutture, ecc.) in collaborazione con il tuo agente di implementazione.
1. Introduzione
1.1. Cos’è l’Intelligenza Artificiale (IA) nello sviluppo?
L’IA è una disciplina ampia che mira a far sì che le macchine svolgano compiti che associamo all’intelligenza umana: comprendere il linguaggio naturale, ragionare a partire da descrizioni, apprendere dai dati o pianificare azioni. Dopo decenni di progressi, il recente salto qualitativo arriva con i Large Language Models (LLM). Questi modelli vengono addestrati con volumi massicci di testo, apprendono schemi di linguaggio e acquisiscono la capacità di generare istruzioni, spiegazioni e, per estensione, codice coerente con un contesto dato.
Nel campo dello sviluppo, ciò implica che non dipendiamo più da strumenti che suggeriscono token al volo. Possiamo descrivere obiettivi di alto livello, imporre standard di stile, richiedere documentazione coerente e coordinare compiti. Il valore non sta solo nell’“autocompletare”, ma nel strutturare un lavoro tecnico sostenuto nel tempo con l’aiuto di un agente che comprende il progetto.
1.2. Dagli assistenti puntuali agli agenti
Il primo contatto di molti programmatori con l’IA è avvenuto tramite assistenti puntuali: motori di suggerimento nell’IDE, chatbot in grado di rispondere a domande o generare funzioni isolate. Utili, sì, ma limitati quando vogliamo costruire sistemi con coerenza nel tempo di settimane o mesi. Al contrario, l’approccio di Agentic Coding sfrutta la capacità dei modelli di seguire processi, mantenere memoria operativa (attraverso file e convenzioni) e muoversi in un backlog in modo pianificato. In altre parole, passiamo da un’assistenza reattiva a una collaborazione proattiva guidata da artefatti di progetto.
1.3. Perché l’IA non è “solo chatbot”?
L’immagine del “chatbot che risponde a domande” è riduttiva. Per lo sviluppo, l’IA moderna può:
- Generare e rifattorizzare codice seguendo schemi di architettura, convenzioni di denominazione e standard (PHPCS, ESLint, ecc.).
- Progettare e implementare test (unitari e di integrazione) e proporre casi limite.
- Scrivere e mantenere documentazione tecnica e per l’utente mentre sviluppa, non alla fine.
- Automatizzare compiti ripetitivi di integrazione, migrazione di API, traduzioni e commenti nel codice.
- Esplorare opzioni tecniche con comparazioni argomentate (prestazioni, sicurezza, manutenzione).
1.4. Definizione operativa di Agentic Coding
Chiameremo Agentic Coding un flusso di lavoro in cui lo sviluppatore umano definisce regole, obiettivi e standard, e un agente (es. Codex) opera all’interno di quel quadro per eseguire compiti, proporre sottocompiti, aprire Pull Requests, mantenere un tabellone di lavoro vivo e documentare ciò che è stato costruito. Il tuo ruolo cambia: passi dal codificare ogni riga a guidare il sistema, specificare criteri di accettazione, rivedere PRs e risolvere blocchi o ambiguità con l’aiuto di un copilota di idee (ad esempio, ChatGPT per affinare il design del processo o redigere artefatti come AGENTS.md).
2. Ecosistema di lavoro con IA per sviluppatori
2.1. Cloud, locale e ibrido
Esistono tre grandi modi per consumare modelli:
- Cloud (OpenAI, Anthropic, Google): facilità d’uso, scalabilità automatica, latenza ragionevole e modelli di ultima generazione utilizzando CLI se si desidera in locale. Svantaggi: costo variabile e politiche sui dati. Esiste anche la possibilità di utilizzare, ad esempio, Codex di OpenAI, che ha un costo fisso che dipende da ciò che contratti, con Plus ($20/mese) di solito è sufficiente. Qui parlerò di Codex.
- Locale (Llama.cpp, Ollama, vLLM): controllo e privacy, dipendenza minima da terzi e costi per utilizzo molto bassi. Svantaggi: hai bisogno di GPU/CPU potenti e manutenzione dei modelli.
- Ibrido: cloud per produzione e modelli locali per sperimentazione, test interni o dati sensibili. Di solito è l’equilibrio più pratico.
2.2. Criteri di scelta
La tua decisione dipenderà da:
- Privacy: tratti dati sensibili? Locale o ibrido possono essere preferibili, anche se in teoria ora si assicura la privacy nel cloud se così lo configuri.
- Costo: il progetto crescerà in utilizzo? Il costo per token nel cloud può aumentare; in locale paghi l’infrastruttura.
- Velocità di avvio: il cloud vince se vuoi iniziare oggi con minima frizione.
- Operazione e manutenzione: locale richiede più DevOps; il cloud esternalizza complessità.
2.3. Strumenti complementari
- Repository: GitHub/GitLab/Bitbucket per PRs, issues, revisioni.
- Editor: VSCode, con estensioni per standard (PHPCS, ESLint), formattatori (Prettier) e assistenti.
- CI/CD: test automatici, linters e distribuzione controllata.
- Gestione delle attività: anche se TODO.md sarà mantenuto dall’agente, è utile integrare segnali con issues etichettate per audit.
3. Preparare la base del flusso di lavoro
3.1. Il trio che articola il sistema
In questo approccio, il tuo processo si basa su tre artefatti sincronizzati:
- AGENTS.md: regole del gioco. Definisce scopo, ambito, standard, struttura, convenzioni, criteri di sicurezza, requisiti di qualità e aspettative di documentazione. Se desideri ulteriori informazioni su AGENTS.md, puoi ottenerle qui.
- TODO.md: tabellone vivo delle attività. Lo crea e mantiene l’agente. In esso si vede cosa farà, cosa è in corso e cosa è stato completato. Aggiunge anche nuove attività emergenti.
- Documents.md: documentazione viva di ciò che è già stato costruito: API pubblica, funzioni, classi, hooks, schemi di dati, flussi e ricette d’uso. Anche questo viene mantenuto dall’agente man mano che avanza.
3.2. Ruoli chiari
- Tu: architetto e responsabile della qualità. Fissi regole e obiettivi in AGENTS.md, rivedi PRs, risolvi ambiguità, richiedi correzioni e nuove attività se rilevi lacune.
- Agente di implementazione (Codex): esegue, decide il dettaglio operativo in TODO.md, fa PRs incrementali e registra documentazione in Documents.md.
- Copilota di idee (ChatGPT): ti aiuta ad affinare AGENTS.md, a ragionare alternative, a redigere criteri di accettazione e a sbloccare problemi complessi rivedendo il codice quando necessario.
3.3. Iterazione disciplinata
Il successo non dipende da “l’IA che genera molto codice”, ma da una iterazione disciplinata con cicli di: pianificare (tu), eseguire (agente), rivedere (tu), documentare (agente) e tornare a pianificare. Più piccolo e verificabile è ogni passo, meglio risponde il sistema, minore è il rischio di debito tecnico e più facile è auditare il lavoro.
4. AGENTS.md: contratto e linea editoriale del progetto
4.1. Funzione strategica di AGENTS.md
AGENTS.md è la bussola del progetto. Qui fissi l’intenzione, l’ambito e le limitazioni. Inoltre, stabilisci la linea editoriale del codice: stile, nomi, struttura, sicurezza e documentazione. È il documento che evita che l’agente improvvisi al di fuori dei tuoi standard. Pensalo come il “Guide for contributors” adattato a un collaboratore che è IA.
4.2. Contenuto raccomandato
- Obiettivo e ambito: quale problema risolvi, cosa non farà il progetto e il risultato atteso.
- Standard: WordPress Coding Standards, PHPCS, traduzioni con dominio concreto, docblocks obbligatori.
- Sicurezza: sanitizzazione, escaping, nonces, ruoli e capacità minime, gestione dei dati personali.
- Struttura dei file: albero delle directory e responsabilità per file/classe.
- Convenzioni di nomi: prefissi di funzioni, classi, “handles” di script e stili.
- Criteri di accettazione: cosa consideri “fatto” in ogni attività, come si prova e quali evidenze sono valide.
- Aspettative di documentazione: come si mantiene Documents.md e quando deve essere aggiornato.
4.3. Beneficio diretto
Con un buon AGENTS.md, le PRs del tuo agente mostrano coerenza estrema: stesse convenzioni, stessa struttura, stesse pratiche sicure. La tua revisione è più rapida, il progetto è più manutenibile e l’inserimento di terzi è più semplice.
5. TODO.md: il tabellone che gestisce l’agente
5.1. Un cambiamento di controllo fondamentale
In questo flusso, NON scrivi tu il TODO.md. Lo crea e mantiene l’agente fin dal primo commit. Ciò significa che l’agente:
- Definisce il dettaglio delle attività e l’ordine di esecuzione.
- Sposta elementi tra stati: in attesa, in corso, completato.
- Aggiunge attività emergenti quando rileva nuove necessità o rischi.
Cosa fai tu allora? Segni la direzione in AGENTS.md, rivedi PRs e, se rilevi lacune, chiedi a Codex di aggiungere attività al TODO.md. In questo modo, il tabellone riflette come l’agente stesso comprende e pianifica il lavoro, senza che tu debba microgestirlo.
5.2.
Vantaggi di questo approccio
- Autonomia operativa: deleghi l’orchestrazione delle attività, mantenendo il controllo strategico.
- Trasparenza: TODO.md diventa un registro auditabile delle decisioni dell’agente.
- Agilità: nuove attività vengono incorporate immediatamente man mano che emergono durante lo sviluppo.
6. Documents.md: memoria tecnica viva
6.1. Cos’è e perché è importante
Documents.md non è un manuale scritto alla fine. È una base di conoscenza viva che l’agente aggiorna mentre sviluppa. Deve registrare la superficie pubblica del progetto: classi e metodi, funzioni, shortcodes, hooks (azioni/filtri), schemi di dati, flussi chiave e ricette pratiche. Il principio è semplice: se non è in Documents.md, è come se non esistesse per terzi.
6.2. Uso quotidiano
Quando torni al progetto dopo giorni o settimane, non hai bisogno di rintracciare codice. Apri Documents.md e trovi:
- Come si chiama la funzione di cui hai bisogno e quali parametri accetta.
- Quale filtro devi agganciare per modificare un comportamento.
- Quali colonne ci sono in una tabella e quali indici sono definiti.
- Come estendere o riutilizzare un flusso con un esempio minimo praticabile.
6.3. Politica di aggiornamento
- Tutti i PR che cambiano la superficie pubblica devono includere l’aggiornamento di Documents.md.
- Se viene aggiunta un’API, deve essere aggiunto un esempio di utilizzo riproducibile.
- Se viene modificato lo schema dei dati, deve essere annotata la migrazione e la sua giustificazione.
7. Buone pratiche di Agentic Coding
7.1. Scrupolosità con gli standard
Mantieni coerenza: WordPress Coding Standards con PHPCS, docblocks chiari, i18n in inglese (e traduzioni dove necessario), e nomenclatura prevedibile. Un agente rende meglio quando le regole sono chiare e vengono applicate in modo uniforme.
7.2. Sicurezza per impostazione predefinita
- Sanitizza le entrate con funzioni appropriate (
sanitize_text_field,sanitize_email, ecc.). - Escape le uscite in HTML (
esc_html,esc_attr,wp_ksesse c’è HTML consentito). - Nonces nei moduli e verifica lato server.
- Principio di privilegio minimo in ruoli/capacità.
7.3. Compiti piccoli e verificabili
Suddividi i lavori in unità di consegna che puoi rivedere in pochi minuti. Chiedi all’agente PR piccoli con un’unica intenzione. In questo modo riduci gli errori, acceleri le revisioni e favorisci l’apprendimento incrementale del sistema.
7.4. Criteri di accettazione chiari
In AGENTS.md, definisci “Definition of Done” per tipi di compiti: ad esempio, “una funzionalità è pronta quando:
- Quando passa PHPCS.
- Include test di base o passaggi manuali di verifica.
- Aggiorna Documents.md.
- Ha i18n corretto.
7.5. Documentazione parallela
Richiedi che l’agente aggiorni Documents.md nello stesso PR che introduce cambiamenti funzionali. Eviti la disincronizzazione e riduci la frizione.
7.6. Audit continuo
Ogni tot numero di PR, fai “traguardi” di revisione trasversale: struttura del repo, dipendenze, prestazioni, sicurezza, copertura della documentazione. Se rilevi degrado, rafforza AGENTS.md e apri compiti correttivi (che l’agente trasferirà in TODO.md).
8. Limitazioni e realismo operativo
8.1. Dipendenza dal contesto
Gli LLM hanno limiti contestuali. L’agente non “vede” tutto il repo contemporaneamente; le sue prestazioni migliorano quando lavori in iterazioni limitate, con artefatti che fissano la memoria (AGENTS.md, Documents.md) e con PR piccoli.
8.2. Ambiguità e il suo costo
Se i tuoi requisiti sono vaghi, l’agente tenderà a riempire i vuoti con supposizioni. Risultato: reworks. Soluzione: definisci obiettivi, restrizioni ed esempi. La chiarezza iniziale risparmia cicli interi.
8.3. Errori plausibili
L’IA può generare codice “verosimile ma errato”. Riduci questo rischio con linters, test di base e revisioni umane. Ricorda: il ruolo dell’umano non scompare, si eleva a curatore e architetto.
8.4. Cambiamenti di portata
I progetti vivi evolvono. L’agente lo gestisce meglio se lo alleni a proporre nuove attività in TODO.md quando rileva impatti collaterali, e tu convalidi quella proposta prima di eseguire.
9. Esempio pratico: scheletro del progetto “Simple Contact Shortcode & Block”
Per collegare la teoria a un’implementazione reale, ancoriamo un progetto semplice in WordPress che servirà da dimostrazione del flusso Agentic Coding. A questo punto non includeremo il codice finale (lo lavoreremo più avanti con il tuo agente). Lasceremo, al suo posto, i contenitori strutturali e gli spazi ben visibili dove inseriremo gli artefatti e i pezzi tecnici quando saranno pronti. In questo modo potrai pubblicare la guida oggi e, passo dopo passo, completare l’esempio senza riscrivere l’input.
9.1. Obiettivo del plugin
Il plugin “Simple Contact Shortcode & Block” fornirà un modulo di contatto molto basilare (Nome e Email) che può essere aggiunto a qualsiasi pagina in due modi: tramite uno shortcode e tramite un blocco di Gutenberg. Inviando il modulo, salverà i dati in una tabella personalizzata nel database e notificherà via email l’amministratore del sito.
9.2. Struttura delle directory prevista
/simple-contact/
├─ simple-contact.php # Bootstrap del plugin
├─ uninstall.php # Pulizia a disinstallare
├─ includes/
│ ├─ class-sc-database.php # Schema e CRUD
│ ├─ class-sc-form.php # Render + submission
│ └─ class-sc-block.php # Registrazione del blocco
├─ assets/
│ ├─ css/style.css # Stili frontend
│ └─ js/block.js # Logica del blocco
└─ languages/
└─ simple-contact.pot # Modello di traduzioni
9.3. Artefatti del flusso Agentic
- AGENTS.md stabilirà le regole e le aspettative di implementazione.
- TODO.md sarà creato e mantenuto da Codex. Qui apparirà il backlog e la priorizzazione che l’agente stesso deciderà.
- Documents.md crescerà con il catalogo di API, hooks e flussi man mano che verranno implementati.
9.4. File
Come abbiamo commentato, dovremo creare un file AGENTS.md che sarà ciò che seguirà Codex.
Ciò che bisogna fare è avere un’idea chiara di ciò che si desidera, una volta che si ha chiaro tutto e si è stati «parlando» con ChatGPT di tutto il progetto, si richiede che crei un AGENTS.md con tutte le regole e definendo il progetto.
Va bene, ora andiamo a creare l’AGENTS.md con tutto ciò di cui abbiamo parlato affinché Codex abbia una guida esatta su ciò che deve fare e come.
Ho bisogno che tu mi crei in modo corretto e completo tutto l’AGENTS.md per il progetto.
Devi aggiungere tutto lo schema dei file, che segua tutti gli standard di sicurezza di WordPress, tutte le misure di sicurezza, nomi dei file, prefissi nei file, classi, funzioni, ecc. standardizzati, intestazioni e commenti in tutti i file, funzioni, strade e metodi come specificato da WordPress. Tutte le stringhe devono essere in inglese e traducibili. È molto importante che si passi sempre il PHPCS mantenendo tutte le allineazioni con le loro tabulazioni e spazi.
Devi anche menzionare e spiegare esattamente l’uso di TODO.md e Documents.md affinché fin dall’inizio li utilizzi e non debba farlo più tardi. Specificagli che se un file è molto grande, come può succedere in un file ad esempio po di traduzione, deve crearli in diversi PR affinché possa sempre creare PR e non si trovi nell’impossibilità di farlo a causa delle dimensioni.
Il repository deve anche avere i file .gitignore` (development junk and OS files) .gitignore e
.gitattributes affinché arrivi solo ciò che deve essere nel pacchetto finale e non arrivino al repo file che non sono necessari del proprio OS su cui si sta lavorando.Crea l’AGENTS.md in inglese.
Dopo questo prompt, ChatGPT mi restituisce il contenuto che dovrò incollare in AGENTS.md
# AGENTS.md — Simple Contact Shortcode & Block
## Project Objective
Create a WordPress plugin named **Simple Contact Shortcode & Block** that exposes a simple contact form as:
- A shortcode: `[simple_contact]`
- A Gutenberg block: `simple-contact/form`
The form collects **Name** and **Email**, saves submissions into a custom database table, and sends a notification email to the site administrator. The plugin must strictly follow WordPress Coding Standards and security best practices. All code and documentation must be in **English**, and all user-facing strings must be **translatable** using the **text domain `simple-contact`**.
---
## Non-Negotiable Standards
1. **Coding Standards & PHPCS**
- Must pass **PHPCS** with the official WordPress Coding Standards ruleset.
- **Tabs for indentation**, **spaces for alignment**. No trailing whitespace.
- Consistent array formatting, parameter alignment, and inline documentation.
- No unused imports, dead code, or commented-out blocks left behind.
2. **Documentation Discipline**
- Every PHP file: header PHPDoc describing purpose, package, since, and author.
- Every class, method, and function: full docblocks (summary, `@param`, `@return`, `@since`, `@see` when relevant).
- Inline comments for non-obvious logic and security-relevant branches.
- All docs and comments in **English**.
3. **Security**
- **Input sanitization**: use the correct sanitizers (`sanitize_text_field`, `sanitize_email`, `absint`, `sanitize_key`, `wp_unslash`, etc.).
- **Output escaping**: use `esc_html`, `esc_attr`, `esc_url`, or `wp_kses` (with strict allowed HTML) right before rendering.
- **Nonces**: all form submissions must include a nonce and be verified server-side with `check_admin_referer`.
- **SQL safety**: use `$wpdb->prepare()` for all SQL with untrusted input.
- **Capabilities**: any admin action or page must check appropriate capabilities (e.g., `manage_options` or a custom capability).
- **No secrets in repo**: no API keys or secrets committed.
- **No PII leaks**: never echo raw user input; log carefully (avoid sensitive data).
4. **Internationalization (i18n)**
- All user-facing strings must be wrapped with translation functions: `__()`, `_e()`, `esc_html__()`, `esc_attr__()`, etc.
- Text domain: **`simple-contact`**.
- Provide `/languages/simple-contact.pot` and keep it updated.
5. **Pull Request (PR) Policy**
- PRs must be **small, focused, and self-contained**.
- If a change involves **very large files** (e.g., `.pot`, vendor bundles, generated assets), **split into multiple PRs** so PRs remain reviewable and pass size limits.
- Every PR must:
- Pass **PHPCS**.
- Update **Documents.md** if it touches public surfaceAPIs, hooks, schema, UI strings).
- Aggiorna **TODO.md** (manutenzione da Codex) per riflettere ciò che è passato a "Completato" e eventuali nuovi compiti scoperti.
- Includere note chiare di test/verifica.
---
## Igiene del Repository: .gitignore e .gitattributes
Per garantire un controllo sorgente pulito e pacchetti di rilascio puliti:
### 1) `.gitignore` (spazzatura di sviluppo e file OS)
Codex deve creare un `.gitignore` nella radice del repo includendo (al minimo):
File OS
.DS_Store
.DS_Store?
Thumbs.db
ehthumbs.db
Icon?
._*
IDE/editor
.vscode/
.idea/
*.iml
Node / build frontend
node_modules/
npm-debug.log*
yarn-error.log
dist/
build/
PHP / tooling
vendor/
composer.lock
Log & temp
*.log
*.tmp
*.cache
Coverage / report
coverage/
.clover
.phpunit.result.cache
Se il progetto adotta in seguito Composer o un passaggio di build, estendere di conseguenza.
### 2) `.gitattributes` (controlla cosa va nei pacchetti di rilascio)
Codex deve creare un `.gitattributes` nella radice del repo per **escludere file non di distribuzione** dagli archivi esportati (GitHub "Download ZIP", composer dist, ecc.). Usa le regole `export-ignore`. Al minimo:
/.gitattributes export-ignore
/.gitignore export-ignore
/.github/ export-ignore
/.vscode/ export-ignore
/.idea/ export-ignore
/tests/ export-ignore
/docs/ export-ignore
/.editorconfig export-ignore
/phpcs.xml* export-ignore
/phpmd.xml* export-ignore
/phpunit.xml* export-ignore
/CHANGELOG.md export-ignore
/README.md export-ignore
/CONTRIBUTING.md export-ignore
/package.json export-ignore
/package-lock.json export-ignore
/yarn.lock export-ignore
/webpack.* export-ignore
/rollup.* export-ignore
/vite.* export-ignore
/node_modules/ export-ignore
/src/ export-ignore
Regola l'elenco man mano che la toolchain evolve. L'obiettivo: **il ZIP di rilascio deve includere solo ciò di cui WordPress ha bisogno per eseguire il plugin** (PHP in `includes/`, bootstrap principale, risorse costruite per l'esecuzione, lingue). I file OS come `.DS_Store` e i metadati di Windows non devono mai apparire nei pacchetti.
---
## Convenzioni di File & Nomenclatura
### Struttura della Directory
/simple-contact/
├─ simple-contact.php # Bootstrap principale del plugin (hooks, costanti, loader)
├─ uninstall.php # Pulizia alla disinstallazione
├─ includes/
│ ├─ class-sc-database.php # Schema DB + CRUD
│ ├─ class-sc-form.php # Rendering del modulo + gestore delle submission + shortcode
│ └─ class-sc-block.php # Registrazione del blocco Gutenberg + logica delle risorse
├─ assets/
│ ├─ css/style.css # Stili frontend (limitati alle classi del plugin)
│ └─ js/block.js # Script dell'editor del blocco (registrato tramite block.json)
├─ languages/
│ └─ simple-contact.pot # Modello di traduzione (esportato per i traduttori)
### Nomi delle Classi
- Prefisso: `SC_`
- Esempi: `SC_Database`, `SC_Form`, `SC_Block`
### Nomi delle Funzioni Globali
- Prefisso: `sc_`
- Esempio: `sc_render_form()`
### Handle di Script & Stile
- Prefisso: `sc-`
- Esempi: `sc-frontend`, `sc-block-editor`, `sc-block-style`
### Intestazioni dei File PHP
Ogni file PHP deve iniziare con un blocco di intestazione PHPDoc:
- Riga di riepilogo (cosa fa questo file).
- `@package` slug del plugin (es. `simple-contact`).
- `@since` stringa di versione.
- Facoltativamente `@author`.
### Docblocks per Metodi & Funzioni
- Riepilogo di una riga, una riga vuota, quindi descrizione dettagliata se necessario.
- `@param` per ogni parametro con tipo e descrizione.
- `@return` con tipo e descrizione.
- Tag `@since`.
---
## File Richiesti: Responsabilità & Contenuto
### 1) `simple-contact.php`
- **Intestazione del plugin**: Nome, Descrizione, Versione, Autore, Licenza, Dominio Testo, Percorso Dominio.
- **Costanti**: `SC_PLUGIN_VERSION`, `SC_PLUGIN_FILE`, `SC_PLUGIN_DIR`, `SC_PLUGIN_URL`.
- **Carica il dominio di testo** in `plugins_loaded`.
- **Include**: richiedi `includes/class-sc-database.php`, `includes/class-sc-form.php`, `includes/class-sc-block.php`.
- **Hook di attivazione**: crea la tabella DB tramite `SC_Database`.
- **Hook di disattivazione**: nessuna azione distruttiva; mantieni i dati a meno che non venga disinstallato.
- **Bootstrap**: istanzia singleton o inizializza hook.
### 2) `uninstall.php`
- Verifica `defined( 'WP_UNINSTALL_PLUGIN' )`.
- Elimina la tabella personalizzata.
- Elimina le opzioni del plugin (se presenti).
- Non lascia dati orfani creati dal plugin (a parte post/utenti non di proprietà del plugin).
### 3) `includes/class-sc-database.php`
- Modello singleton (`SC_Database::instance()`).
- `create_table()` con `dbDelta()` per lo schema iniziale.
- Migrazioni versionate (se lo schema evolve) con un'opzione `sc_db_version`.
- CRUD:
- `insert_contact( array $data ): int|WP_Error`
- `get_contacts( array $args = [] ): array`
- Sanitizzazione rigorosa ai confini e `$wpdb->prepare()` ovunque.
- Memorizza i timestamp in **UTC**.
### 4) `includes/class-sc-form.php`
- Modello singleton (`SC_Form::instance()`).
- Metodo di rendering: `render_form( array $atts = [] ): string`
- Attributi: `success_message` (string), `css_class` (string).
- Output sfuggito e HTML ben formato.
- Gestore delle submission: `handle_submission(): int|WP_Error`
- Verifica nonce.
- Sanitizza gli input.
- Valida l'email con `is_email()`.
- Inserisci tramite `SC_Database`.
- Invia email all'amministratore (filtrabile).
- Registrazione shortcode: `[simple_contact]` mappato al metodo di rendering.
- Hook:
- Azioni: `sc_before_insert_contact`, `sc_after_insert_contact`
- Filtri: `sc_email_to`, `sc_email_subject`, `sc_email_headers`, `sc_success_message`
### 5) `includes/class-sc-block.php`
- Registra il blocco tramite `block.json`.
- Assicura che gli attributi rispecchino gli attributi dello shortcode:
- `successMessage` (string)
- `cssClass` (string)
- Registra/enqueue lo script dell'editor (`assets/js/block.js`) e lo stile frontend (`assets/css/style.css`) utilizzando handle versionati.
- Il rendering lato server può chiamare `SC_Form::render_form()` per parità con lo shortcode.
### 6) `assets/css/style.css`
- CSS minimale e amichevole per il tema.
- Ambito sotto un wrapper unico (es. `.sc-form`) per evitare conflitti.
### 7) `assets/js/block.js`
- Registrazione del blocco (modifica + salvataggio).
- Controlli dell'ispettore per `successMessage` e `cssClass`.
- Anteprima dell'editor leggera e coerente.
### 8) `languages/simple-contact.pot`
- Esportato da fonti, include tutte le stringhe traducibili.
- Se il `.pot` è molto grande, suddividi le PR per mantenere la revisione (non saltare aggiornamenti).
---
## Schema del Database
Tabella: `{$wpdb->prefix}sc_contacts`
| Colonna | Tipo | Note |
|-------------|-----------------------------------|------------------------------------------------|
| id | BIGINT UNSIGNED AUTO_INCREMENT | Chiave primaria |
| name | VARCHAR(120) | Sanitizzato tramite `sanitize_text_field()` |
| email | VARCHAR(190) | Valida con `is_email()` |
| created_at | DATETIME | Memorizzato in UTC |
| consent_ip | VARBINARY(16) NULL | Facoltativo (IPv4/IPv6 memorizzato come binario) |
| user_agent | VARCHAR(255) NULL | Facoltativo |
Indici:
- `PRIMARY (id)`
- `INDEX (email)`
- `INDEX (created_at)`
Migrazioni:
- Implementa `maybe_upgrade_schema()` con opzione di versione per gestire futuri cambiamenti.
---
## Specifica dello Shortcode
- **Tag**: `[simple_contact]`
- **Attributi**:
- `success_message` (stringa, facoltativa; stringa localizzata predefinita)
- `css_class` (stringa, facoltativa)
- **Esempio**:
[simple_contact success_message=“Grazie, ti contatteremo presto.” css_class=“is-style-card”]
---
## Specifica del Blocco
- **Nome**: `simple-contact/form`
- **Categoria**: `widgets`
- **Attributi**:
- `successMessage` (string)
- `cssClass` (string)
- I controlli dell'ispettore devono consentire la configurazione di entrambi.
- Salva gli attributi e assicurati che il frontend rispecchi il comportamento dello shortcode.
---
## Azioni & Filtri (Superficie Pubblica)
**Azioni**
- `sc_before_insert_contact( array $sanitized_data )`
- `sc_after_insert_contact( int $contact_id, array $data )`
**Filtri**
- `sc_email_to( string $recipient, array $data )`
- `sc_email_subject( string $subject, array $data )`
- `sc_email_headers( array $headers, array $data )`
- `sc_success_message( string $message, array $data )`
Ogni volta che viene aggiunta o modificata una nuova azione/filtro, aggiorna **Documents.md** con firma, tempistica e esempio di utilizzo.
---
## Il Ruolo di TODO.md (Manutenzione da Codex)
- `TODO.md` è **di proprietà e mantenuto da Codex** dal primo commit.
- Deve includere, al minimo, sezioni per **In Attesa**, **In Corso**, **Completato**.
- Codex decide la suddivisione e l'ordine dei compiti, sposta gli elementi tra gli stati e **aggiunge nuovi compiti proattivamente** quando necessario.
- I collaboratori umani **non devono** modificare direttamente `TODO.md`; devono richiedere modifiche e Codex lo aggiorna.
---
## Il Ruolo di Documents.md (Manutenzione da Codex)
- `Documents.md` è una **base di conoscenza vivente** di ciò che esiste ora:
- Navigazione rapida
- Architettura (moduli e responsabilità)
- Schema dati e migrazioni
- API pubblica (classi, metodi, funzioni)
- Catalogo di Azioni & Filtri
- Utilizzo di Shortcode e Blocco
- Flussi di lavoro (submission, disinstallazione)
- Come fare (estendere/personalizzare)
- Test & QA
- Note di rilascio (brevi); dettagli completi in `CHANGELOG.md`
- Glossario (prefissi, nomenclatura, termini)
- **Ogni PR** che modifica la superficie pubblica o il comportamento deve aggiornare `Documents.md`. Le PR prive di aggiornamenti necessari ai documenti devono essere rifiutate.
---
## Test & QA
- I passaggi di verifica manuale devono essere descritti nelle PR (il modulo viene renderizzato, nonce verificato, email non valida rifiutata, il percorso di successo memorizza la riga e invia email, la disinstallazione pulisce).
- Dove applicabile, includere test automatizzati di base o passaggi riproducibili.
- Accessibilità: etichette/id dei moduli, testo dei pulsanti, messaggi di errore leggibili e localizzati.
- Prestazioni: evitare query non necessarie; enqueue solo quando necessario.
---
## Politica di Imballaggio per il Rilascio
- Il **ZIP distribuito** (pacchetto plugin WordPress) deve contenere solo le necessità di runtime:
- `simple-contact.php`, `uninstall.php`, `/includes/`, `/assets/` costruiti per runtime, `/languages/`.
- **Escludere** artefatti di sviluppo (test, CI, configurazioni editor, node_modules, src, docs) tramite `.gitattributes` `export-ignore`.
- I file spazzatura OS (es. `.DS_Store`, `Thumbs.db`) non devono mai apparire.
- Se viene introdotto un pipeline di build, assicurati che le risorse costruite siano incluse e le fonti escluse secondo la politica.
---
## Regole Operative Finali (per Codex)
- Scrivi sempre commenti e documenti del codice in **inglese**.
- Avvolgi sempre le stringhe utente con funzioni i18n utilizzando il dominio di testo `simple-contact`.
- Sanitizza sempre l'input e sfuggi l'output al momento giusto.
- Passa sempre **PHPCS** e rispetta le convenzioni di tab/spazio (i tab indentano, gli spazi allineano).
- Mantieni **PR piccole**; dividi grandi risorse/cambiamenti su più PR.
- Aggiorna **TODO.md** e **Documents.md** in sincronia con le modifiche al codice.
- Mantieni `.gitignore` e `.gitattributes` in modo che il repo rimanga pulito e il ZIP di rilascio sia minimo e conforme.
Il mancato rispetto di una qualsiasi delle regole in questo AGENTS.md è motivo per richiedere modifiche o rifiutare la PR.
E una volta selezionato, basta fare un prompt semplice come questo
Sviluppa tutto ciò che c’è in AGENTS.md e ricorda di utilizzare il TODO.md e il Documents.md
E premeremo su Programma, e inizierà a lavorare sul codice.
Dopo un po’, questo dipende da tutto ciò che ha fatto, ci mostrerà tutte le modifiche che ha effettuato, che in questo caso, tutto è codice da aggiungere.
Premendo sulla task, accederemo ad essa e potremo vedere tutto ciò che ha fatto, rivederlo e creare il PR o chiedere modifiche.
In questo caso non andrò a rivedere nulla perché questa è una demo, quindi premo prima su «Crea richiesta di estrazione» e poi su «Visualizza PR» una volta che appare il pulsante.
Questo ci porterà su Github, dove potremo anche rivedere le modifiche e accettarle.
Premiamo su «Unisci richiesta di estrazione» e avremo tutto il nuovo codice aggiunto al plugin.
Ora possiamo vedere il TODO.md e il Documents.md dove potremo tenere traccia di tutto e ottenere una documentazione per il futuro.
Se guardiamo il TODO.md, a questo punto possiamo vedere che ci sono ancora molte cose in Progress e in Pending, quindi Codex deve continuare. Dobbiamo solo dirgli a Codex di continuare con il lavoro.
Questo lo ripeteremo fino a quando non ci saranno più task nel TODO.md e sarà tutto fatto. Arriverà un momento in cui in Pending e Progress non ci sarà più nulla, e potremo testare il risultato finale in un ambiente di sviluppo. Soprattutto SEMPRE in sviluppo.
Una volta installato, potrebbe funzionare al primo colpo o no, nel mio caso è comparso un errore fatale
Quindi quello che faccio è copiare l’errore affinché Codex lo corregga dandogli contesto.
Dopo aver finito, crea un nuovo PR per sistemarlo e il plugin può già essere attivato
Se ora creiamo un nuovo post/pagina, vedremo nei blocchi che ce n’è uno chiamato «Simple Contact Form», e che si può specificare il messaggio di successo dell’invio. In questo caso, poiché non abbiamo specificato in AGENTS.md che dobbiamo poter configurare l’email a cui deve essere inviato, lo invierà sempre all’email dell’amministratore di WordPress.
Nel front vedremo questo (ricorda che avevamo specificato che il modulo avesse solo nome e email)
Se ora volessi aggiungere più campi, ad esempio Oggetto e Commenti, dovremmo solo chiedere a Codex e dirgli di aggiornare AGENTS.md, TODO.md e Documents.md.
Se compilo i campi e premo su Invia, ricevo questo all’email
Cioè, abbiamo avuto solo un errore fatale nel plugin che ci ha sviluppato Codex, e che ha corretto al primo colpo indicandogli quale fosse.
Questo è un plugin molto semplice, ma è un plugin che incorpora un blocco per Gutenberg che non è poco.
Se ripassiamo tutto ciò che gli abbiamo richiesto in un primo momento, vedremo che manca qualche tema, sia perché c’è un bug e non viene mostrato, o perché direttamente non lo ha fatto, quindi da questo momento in poi, è continuare a fare richieste di correzioni fino ad arrivare dove desideriamo.
10. Futuro del Coding Agentico
10.1. Maggiore autonomia, maggiore tracciabilità
Man mano che i modelli evolveranno, vedremo agenti in grado di pianificare iterazioni più lunghe, rilevare dipendenze e coordinare cambiamenti più significativi. La chiave non sarà solo la potenza bruta, ma la tracciabilità: conservare una cronologia di decisioni, assunzioni e criteri di accettazione che rendano auditabili i PR generati dall’IA.
10.2. Testing e CI/CD integrati nel flusso dell’agente
Il futuro immediato passa per agenti che integrano generazione di test e pipeline di CI/CD: linters, test, copertura di base, preview deploys e report di prestazioni. Il tuo ruolo si concentrerà sul progettare le politiche: cosa è accettabile, quali rischi non tolleri e come devono essere riportate le regressioni.
10.3. Specializzazione per domini
Vedremo agenti “affinati” per ecosistemi concreti (WordPress, WooCommerce, plugin di pagamento, frontend con React/Blocks) con convenzioni preimparate e cataloghi di migliori pratiche. Questo ridurrà ulteriormente il tempo di avvio e lo sforzo di revisione.
10.4. Documentazione come prodotto
La documentazione smetterà di essere un appendice per diventare un prodotto parallelo mantenuto dall’agente. Documents.md evolverà in portali di conoscenza navigabili, con snippets eseguibili, schemi visivi, diagrammi e ricette versionate.
11. Conclusione
Il Coding Agentico non è chiedere a un’IA di “fare un plugin”, ma costruire una relazione di lavoro dove tu segni il nord e l’IA esegue con disciplina. L’ecosistema moderno —cloud, locale, ibrido— ti consente di scegliere la base tecnica; ma il vero differenziale sta in come organizzi il processo: AGENTS.md per fissare regole, TODO.md gestito dall’agente per orchestrare compiti, e Documents.md per catturare conoscenza reale del progetto mentre viene creato.
Questo approccio ti dà velocità senza sacrificare qualità: riduci il tempo in compiti ripetitivi, ti concentri su architettura e decisioni importanti, e mantieni a bada il debito tecnico. Qual è il risultato? Progetti più coerenti, facili da mantenere e con una rampa di incorporazione morbida per qualsiasi collaboratore futuro.
Hai visto, inoltre, come preparare un esempio pratico che potrai completare con il tuo agente: “Simple Contact”.
Il futuro dello sviluppo è collaborativo: umani e agenti che lavorano fianco a fianco con processi chiari, standard solidi e evidenza costante. Inizia oggi con il tuo flusso e le tue regole; l’IA farà il resto sotto la tua direzione.
