Su come ho usato due diversi Agenti AI come collaboratori durante la realizzazione di un plugin per WordPress e delle impressioni su questo nuovo modo di condurre un progetto di sviluppo software.

Introduzione

Da qualche settimana, nei weekend o dopo cena, sto lavorando allo sviluppo di un plugin chiamato Asset Lending Manager (ALM) per l’associazione di astrofili di cui faccio parte. Poiché ho già descritto in dettaglio le sue funzionalità in un post precedente [1], qui mi limiterò a dire che il suo scopo è quello di gestire e facilitare il prestito di dispositivi e oggetti di varia natura all’interno di una organizzazione e poi mi soffermerò sul metodo di sviluppo usato.

Già dalle prime fasi ho notato che procedevo a fatica, senza entusiasmo, e mi sembrava l’ennesimo progetto da portare a termine con il solito approccio e le classiche problematiche; insomma le prospettive non erano delle migliori perché mi ero accollatto questo lavoro e mi toccava occuparmene da solo.

A un certo punto però, dopo aver letto alcuni post entusiasti sui social, ho deciso di provare a fare qualcosa di nuovo: chiedere aiuto a dei collaboratori, ChatCPT e Claude.

Sono ormai arrivato alla fine del primo mese di abbonamento a queste due piattaforme e devo anticipare che non rimpiango di averlo fatto, sia perché è stata una esperienza stimolante e interessante, sia perché alla fine, proprio qualche giorno fa, ho rilasciato la prima versione di questo prodotto.

Metodo di sviluppo

Non so se ciò ho fatto si possa chiamare “Vibe coding” o abbia un altro nome, e sono pronto ad accettare critiche e suggerimenti; intanto condivido la modalità con cui ho approcciato questa situazione e come ho creato un “contesto” per le AI che penso di riutilizzare, con le opportune modifiche, anche in altri progetti.

Innanzitutto, dopo aver aperto i terminali degli agenti all’interno del prompt di Visual Studio code (VSC), ho scoperto che andavano alla ricerca di file ben precisi nella directory corrente: ChatGPT codex cerca un file chiamato AGENTS.md, mentre Claude Code cerca un file chiamato CLAUDE.md.

È evidente che lo scopo di questi file sia quello di fornire direttive e delle spiegazioni all’agente in modo automatico, per evitare di doverle riscriverle ogni volta e per fare in modo che siano sempre le stesse.

Così ho pensato allora di creare un “contesto” un po’ più articolato, che comprendesse vari aspetti del progetto: descrizione, funzionalità, regole di sviluppo, ecc.

Ho creato una sorta di procedura d’avvio (bootstrap), ovvero una sequenza di file con uno scopo preciso, da far leggere all’AI in un ordine definito a partire da quello letto di default da ognuno di essi.

Prima di passare a descrivere i file va precisato che il progetto di cui parlo:

• si trovava in un repository GIT che ho clonato localmente,
• era già configurato per essere gestito opportunamente con VSC,
• era già configurato per usare PHPCS come linter e xdebug per il debug,
• avevo già attivato un abbonamento mensile a ChatGPT e Claude (allo stato attuale per provare ChatGPT Codex basta l’abbonamento gratuito, mentre per provare Claude Code ci vuole almeno l’abbonamento Pro) [4].

C’è anche da dire che ora ci sono dei plugin integrati all’interno di VSC e non c’è bisogno di invocare l’agente dal prompt, il funzionamento della procedura di bootstrap resta identico.

Detto questo i file aggiunti al progetto sono i seguenti:

1. AGENTS.md: File letto automaticamente da ChatGPT Codex, in pratica serve solo a redirigere l’attenzione dell’agent verso il file AI_RULES_CHATGPT.md.
2. CLAUDE.md: File letto automaticamente da Claude Code , in pratica serve solo a redirigere l’attenzione dell’agent verso il file AI_RULES_CLAUDE.md.
3. AGENTS/AI_RULES_CHATGPT.md: Punto di igresso nella fase di bootstrap per ChatGPT. In questo file è definita la sequenza di bootstrap e ci sono delle regole di lavoro che valgono solo per ChatGPT.
4. AGENTS/AI_RULES_CLAUDE.md: Stessa cosa del file precedente ma valida solo per Claude.
5. AGENTS/AGENTS_README.md: Indica il motivo per cui è stata realizzata la cartella AGENTS e descrive sinteticamente qual è il contenuto e lo scopo di ciascun file in essa presente.
6. AGENTS/PROJECT.md:  Descrizione del progetto, ambito del prodotto, funzionalità principali e ruoli. È la vista funzionale del plugin: cosa fa, per chi è pensato, e quali parti sono già disponibili. È utile per capire rapidamente obiettivi e confini del prodotto.
7. AGENTS/ARCHITECTURE.md: Descrizione dell’architettura, moduli principali, directory chiave, hook/endpoint pubblici, modello dati, stack tecnologico e riferimenti. È la mappa tecnica del sistema. Aiuta a capire dove intervenire nel codice e come i componenti si collegano tra loro.
8. AGENTS/AI_BEHAVIOR.md: E’ il file che specifica come si deve comportare l’agente e come deve operare durante lo sviluppo, la ricerca e la risoluzione di issue. Include trigger operativi, Definition of Done e gestione backlog.
9. AGENTS/CODING_STANDARDS.md: Vincoli di codifica e standard di qualità. Assicura l’aderenza alle WordPress Coding Rules in ambito PHP/HTML/CSS/JS e i18n, inoltre definisce delle regole pratiche su sicurezza e stile. È il riferimento da seguire durante sviluppo e refactor.

I primi due file si trovano nella root del progetto, mentre gli altri li ho raccolti in una directory chiamata AGENTS, tranne i file PROJECT.md ed ARCHITECTURE.md, che ovviamente cambiano da progetto a progetto, gli altri possono essere riutilizzati (e in realtà già l’ho fatto) in altri progetti con poche modifiche.

Sempre in AGENTS, ci sono altri tre file che sono letti solo in alcuni casi con le modalità specificate nei file precedenti:

1. AGENTS/GIT_WORKFLOW.md: Serve per specificare come deve essere usato il repository GIT, come fare i commit e che controlli effettuare prima di un commit.
2. AGENTS/ISSUES_TODO.md: Elenco dei problemi aperti e delle attività da affrontare. Permette di prioritizzare il lavoro per criticità e categoria.
3. AGENTS/ISSUES_RESOLVED.md: Archivio delle issue risolte.

Trigger commands

Una cosa molto utile e che uso spesso in questi giorni sono i trigger commands, in pratica ho definito delle frasi che comportano l’esecuzione di tutta una serie di attività da parte dell’agente e alla produzione di report di un certo tipo:

• “Fai una review completa del file X“: esegue una revisione completa del file (bug, sicurezza, stile, compliance, lint e controlli HTML dove applicabile) e presenta un report a video.

• “Controlla URL X”: avvia un audit della pagina per qualità HTML/JS, efficienza di caricamento, responsività, accessibilità e performance.

• “Controlla se ci sono nuove issue“: rilegge il backlog aperto e individua eventuali problemi da affrontare in base a priorità e impatto.

• “Dammi un riepilogo tabellare delle issue“: produce una tabella per categoria/severità con totali e raccomandazioni iniziali e suggerisce da 4 a 5 issue da cui partire

Sono molti utili per riprendere il lavoro, per fare un riassunto dello stato del progetto, per fare controlli e verifiche complesse.

Configurazione del sistema

Configurare il sistema su Windows è molto semplice. Basta avere una versione recente di Node.js sul proprio pc e poi eseguire i seguenti comandi:

npm i -g @openai/codex
npm install -g @anthropic-ai/claude-cod

Per Claude Code, in realtà, in questo momento l’installazione con npm è deprecata e sono consigliati altri due metodi di installazione tramite l’installer nativo.

Il primo prevede prima l’installazione di Git per Windows (Git.scm)  e poi l’installazione con uno di questi due comandi a seconda della shell che si usa:

#Con POWERSHELL:
irm https://claude.ai/install.ps1 | iex

#Con Prompr DOS:
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Il secondo pevede l’utilizzo di WSL2 (Windows Subsystem for Linux):

curl -fsSL https://claude.ai/install.sh | bash

Io li ho installati entrambi con npm perché all’epoca era l’unica possibilità che avevo, nei prossimi giorni proverò a usare WSL2.

Considerazioni

Dopo un mese di lavoro con i miei due collaborati credo sia venuto il momento di fare alcune riflessioni.

Questo nuovo metodo di programmazione mi ha reso più veloce e produttivo, riesco a implementare da solo un gran numero di funzionalità e a tenere sotto controllo bug e segnalazioni più facilmente. E’ inutile ormai credo che non si possa più tornare indietro, i miglioramenti e i risultati del lavoro quotidiano sono così superiori che è impensabile tornare indietro e fare meno e peggio.

Durante ogni sessione cerco sempre di dividere il lavoro in piccoli task e di implementarli o correggerli uno alla volta; in questo modo il numero dei file e delle linee di codice modificate o aggiunte è sempre basso e prima di ogni commit posso controllare facilemente quello che è stato fatto.

Gli agenti potrebbero anche implementare interi programmi con un unico prompt, ma ciò produrrebbe codice completamente sconosciuto al programmatore.

Quindi il concetto che mi sento di affermare è che gli agenti sono ottimi copiloti, ma non si deve mai correre il rischio che per prigrizia o fretta si deleghi tutto il lavoro a loro e non si monitori passo passo l’avanzamento di un progetto. Se lo si facesse i risultati sarebbero disastrosi perché si avrebbe un prodotto di cui non si sa niente, non si comprende il funzionamento e non si è più ingrado di gestire.

Fonti e riferimenti

1. Progetto Asset Lending Manager (ALM) su GitHub.com.
2. OpenAI ChatGPT Codex.
3. Claude Code.
4. Tariffe abbonamenti: ChatGPT di OpenAI – Anthropic Claude.