Delphi AI Skills: codice Delphi corretto dagli agenti AI

Il codice è diventato economico da scrivere. Quello che costa, adesso, è farlo scrivere bene: delphi-ai-skills insegna agli agenti AI (Claude Code, Codex, Cursor, Gemini) l'API vera di DelphiMVCFramework, con direttive, stile, sicurezza e test incorporati.

Da oggi è pubblico delphi-ai-skills: un insieme di skill open source (Apache-2.0) che insegnano agli agenti AI di coding a scrivere codice DelphiMVCFramework che compila, che segue le convenzioni giuste e che nasce già sicuro. Funziona con Claude Code, Codex, Cursor, Gemini CLI, Windsurf, Continue e con qualunque altro strumento capace di leggere istruzioni in Markdown.

In breve

• Cos’è: sette skill open source (Apache-2.0) che insegnano a un agente AI l’API reale di DelphiMVCFramework 3.5.0, invece di lasciargliela indovinare.
• Per chi: chi scrive REST API, Minimal API o web app in Delphi con l’aiuto di un agente AI.
• Agenti supportati: Claude Code, Codex, Cursor, Gemini CLI, Windsurf, Continue, e qualunque agente che legga Markdown.
• Installazione: git clone, poi install_in_claude.bat (o _codex, _cursor, _gemini).
• Cosa cambia: niente più MapGroup al posto di Prefix, niente ToFree che libera due volte l’oggetto restituito, endpoint filtrati sull’utente autenticato e test di integrazione DUnitX veri.
• Repository: github.com/danieleteti/delphi-ai-skills

Il codice è diventato economico. La direzione no.

Per trent’anni la parte cara del mestiere è stata digitare. Il progetto lo avevi in testa, e il collo di bottiglia era trasformarlo in righe: scrivere il controller, il DTO, i test, il boilerplate, il CRUD. Chi produceva più righe corrette per ora valeva di più.

Quella scarsità è finita. Oggi un agente AI mi scrive in trenta secondi un controller CRUD completo di test. Non è più una novità da conferenza: è la giornata normale di chi programma nel 2026. E quando qualcosa diventa abbondante, il valore si sposta altrove.

Si sposta sulla direzione. Se il codice costa poco a produrre, allora la domanda interessante non è più “quanto ci metti a scriverlo”, ma:

• segue le nostre convenzioni, o ne inventa di nuove a ogni sessione?
• usa l’API che il framework ha davvero, o quella che l’agente immagina che il framework abbia?
• l’endpoint che ha appena generato è filtrato sull’utente autenticato, o legge l’ordine di chiunque passi un ID nell’URL?
• il codice che ho appena accettato con un colpo di Tab, chi lo mantiene tra due anni?

Il rischio del codice economico è esattamente questo: produrre in fretta molto codice mediocre, plausibile in lettura e sbagliato nei dettagli, ognuno con il suo piccolo stile personale. Un agente lasciato libero è velocissimo a costruire debito tecnico.

La risposta non è rallentare l’agente. È guidarlo: dargli direttive, modalità operative, uno stile di casa e regole di sicurezza incorporate, così che la strada giusta sia anche la strada di default. È esattamente il lavoro che fanno le skill.

Che cos’è una skill per un agente AI

Una skill è un file Markdown che l’agente carica su richiesta, solo quando la tua richiesta corrisponde alla sua descrizione. Nel contesto dell’agente stanno sempre e solo il nome e una riga di descrizione, per ogni skill installata. Quando chiedi “crea un controller DMVCFramework”, l’agente riconosce la corrispondenza e a quel punto apre il file, che gli spiega l’API reale del framework: i nomi esatti delle unit, gli attributi, le regole di ownership degli oggetti, gli idiomi, le trappole già note.

Caricamento su richiesta: la documentazione pesante entra in gioco solo quando il compito la richiede.

È un meccanismo semplice ma con una proprietà preziosa: la finestra di contesto resta libera. La skill principale, dmvcframework, tiene nel suo SKILL.md il nucleo operativo (bootstrap, controller, risposte, ownership, middleware, errori tipici) e sposta il materiale pesante in file reference/ che l’agente apre solo se il compito lo richiede: l’ORM ActiveRecord, la validazione, il container di dependency injection, i server backend, dotEnv, le SSE.

Il problema concreto: codice Delphi plausibile e non compilabile

Chiedete a un agente senza skill una Minimal API con DelphiMVCFramework. Riceverete codice ben scritto, ben indentato, ben commentato, e che non compila.

Stessa richiesta, stesso modello. A sinistra i nomi che il framework avrebbe se fosse ASP.NET, a destra quelli che ha davvero.

I nomi sbagliati non sono casuali: sono quelli che il framework avrebbe se fosse ASP.NET Core, perché di ASP.NET Core il modello ha letto milioni di righe e di DelphiMVCFramework molte meno. Così esce MapGroup al posto di Prefix, OkResponse al posto di Ok, classi middleware che non esistono, e un ToFree intorno all’oggetto restituito che lo libera due volte, perché a liberarlo ci pensa già il framework.

C’è una domanda che smaschera un agente non istruito in dieci secondi:

In una functional action di DelphiMVCFramework, devo usare ToFree sull’oggetto che restituisco?

La risposta giusta è no: il framework libera l’oggetto restituito, e ToFree lo libererebbe una seconda volta. Un agente senza skill di solito risponde di sì, e il suo codice fa una doppia free.

Ogni skill del progetto è nata proprio riproducendo prima l’errore: si fa fallire l’agente, si documenta l’API che il framework ha veramente, si rilancia lo stesso compito e si verifica che adesso lo azzecchi. Nessun nome di API scritto a memoria: tutto verificato sui sorgenti e sui samples di DelphiMVCFramework 3.5.0 (silicon).

Le sette skill per DelphiMVCFramework

Sono complementari: le skill Minimal API e web app danno per assodato il nucleo per entità, validazione e DI, la skill web app delega il markup a dmvcframework-ui e la sintassi htmx a htmx-skill invece di duplicarle. Installatele tutte: è l’agente a scegliere quelle giuste.

Se non conoscete gli argomenti che le skill insegnano all’agente, qui trovate il punto di partenza umano: le Minimal API di DMVCFramework, le web app Delphi con TemplatePro e, sul versante AI, il server MCP per DMVCFramework con il suo agente. Le skill sono il tassello che mancava: non danno all’agente nuovi strumenti, gli danno il sapere per usare bene quelli che ha.

Sicurezza: non un controllo finale, ma una precondizione del codice generato

Questa è la parte che mi sta più a cuore, e il motivo per cui dmvcframework-security non è una skill che si invoca a fine lavoro, ma una dipendenza obbligatoria delle altre skill server: qualunque endpoint riceva input da un client la tira dentro.

Il codice generato in fretta sbaglia sempre gli stessi punti. Il più comune, e il più grave, è l’IDOR: l’endpoint che si fida dell’ID nell’URL.

// SBAGLIATO: qualunque utente autenticato può leggere gli ordini di chiunque
function TOrdersController.GetOrder(const ID: Integer): IMVCResponse;
begin
  Result := OKResponse(TMVCActiveRecord.GetByPK<TOrder>(ID));
end;

L’ID arriva dalla URL. Niente lo lega a chi sta chiamando. La regola che la skill impone all’agente è che il controllo di proprietà sia la query stessa, non un if messo dopo:

function TOrdersController.GetOrder(const ID: Integer): IMVCResponse;
var
  lOrder: TOrder;
begin
  // the ownership check IS the query
  lOrder := TMVCActiveRecord.GetOneByWhere<TOrder>(
    'id = ? and customer_id = ?', [ID, CurrentUserID], False);
  if lOrder = nil then
    Exit(NotFoundResponse);      // same answer as "not yours": do not leak existence
  Result := OKResponse(lOrder);
end;

La differenza tra le due versioni sono tre righe. Ma la prima è una violazione dei dati che aspetta solo di succedere, e in un mondo in cui il codice si accetta a colpi di Tab, è la versione che finisce in produzione. Una regola scritta in una skill vale molto più di una regola scritta in una checklist che nessuno rilegge: la skill viene applicata mentre il codice nasce, non dopo.

Lo stesso vale per lo stile e per le direttive di progetto. Le skill non insegnano solo “come si chiama questa funzione”: insegnano come si lavora qui. Per esempio impongono di partire da un progetto creato con il wizard dell’IDE, invece di inventarsi un bootstrap mezzo corretto da zero, e di rispettare il backend server che il progetto già ha: se state girando in WebBroker sotto ISAPI o Apache, le skill lo riconoscono, lo mantengono e non vi propongono mai di migrare.

I test: il contrappeso al codice economico (DUnitX e IMVCRESTClient)

Se c’è una cosa che l’era del codice abbondante rende più importante, non meno, sono i test.

Il ragionamento è semplice. Prima, il codice lo scrivevi tu: lo avevi in testa riga per riga, e potevi permetterti (a torto, ma potevi) di fidarti di quella comprensione. Oggi il codice arriva da un agente, in quantità, e tu lo leggi in diagonale. L’unica cosa che ti dice se quel codice fa davvero quello che credi non è più la tua lettura: è un test che fallisce. Il test è diventato il posto in cui vive la tua intenzione, e il codice è solo il modo, ormai economico, di soddisfarla.

E c’è un secondo motivo, ancora più pratico: il test è l’unico linguaggio in cui l’agente può verificarsi da solo. Un agente che ha una suite da lanciare chiude il ciclo (scrivo, compilo, eseguo i test, correggo) senza che tu debba fare da compilatore umano a ogni giro. Senza test, l’agente ha una sola fonte di verità: te.

Per questo dmvcframework-testing non è una skill di contorno. Insegna all’agente lo stack di test vero di DelphiMVCFramework: DUnitX come runner, un IMVCServer in-process (Indy Direct) e IMVCRESTClient come client HTTP fluente. Niente server esterno da avviare, niente WebModule: il server nasce e muore dentro il test.

function StartTestServer(APort: Integer; out AEngine: TMVCEngine): IMVCServer;
begin
  AEngine := TMVCEngine.Create(
    procedure(Config: TMVCConfig)
    begin
      Config[TMVCConfigKey.DefaultContentType] := TMVCMediaType.APPLICATION_JSON;
    end);
  AEngine.AddController(TCustomersController);

  Result := TMVCServerFactory.CreateIndyDirect(AEngine);
  Result.Listen(APort);
end;

Notate un dettaglio che vale da solo l’installazione della skill: questo funziona anche se l’applicazione in produzione gira come ISAPI sotto IIS o come modulo Apache. L’host non è ciò che state testando, lo sono l’engine, i controller e i middleware. Un agente non istruito, a chi gli chiede test per un progetto WebBroker, risponde tentando di avviare IIS.

I test di integrazione sono HTTP vero contro il server in-process, e la skill impone di asserire sullo status code e sul body, non sul fatto che la chiamata non sia esplosa:

procedure TCustomersTests.Create_Returns201_And_Location;
var
  lResp: IMVCRESTResponse;
begin
  lResp := FClient.Post('/api/customers',
    '{"firstName":"Daniele","lastName":"Teti","email":"d.teti@example.com"}');

  Assert.AreEqual(HTTP_STATUS.Created, lResp.StatusCode);
  Assert.IsNotEmpty(lResp.HeaderValue('Location'));
end;

procedure TCustomersTests.Post_Invalid_Email_Returns422;
var
  lResp: IMVCRESTResponse;
begin
  lResp := FClient.Post('/api/customers',
    '{"firstName":"Bob","lastName":"X","email":"not-an-email"}');
  // validation failed => 422, and the action never ran
  Assert.AreEqual(HTTP_STATUS.UnprocessableEntity, lResp.StatusCode);
end;

Ma la parte che mi interessa davvero è un’altra, ed è il punto in cui la skill dei test e quella della sicurezza si danno la mano. Testate la serratura, non solo la chiave. Per ogni risorsa protetta, il test che conta non è quello che verifica che il proprietario riceva 200: è quello che verifica che chiunque altro non ci arrivi.

procedure TSecureTests.NoToken_Returns401;
begin
  // the test that catches the [MVCRequiresAuthentication] you forgot
  Assert.AreEqual(HTTP_STATUS.Unauthorized, FClient.Get('/api/admin/stats').StatusCode);
end;

procedure TOrdersTests.User_Cannot_Read_Another_Users_Order;
begin
  // order 1 belongs to user1
  FClient.SetBearerAuthorization(TokenFor('user2'));
  // 404, not 403: a 403 would confirm the order exists
  Assert.AreEqual(HTTP_STATUS.NotFound, FClient.Get('/api/orders/1').StatusCode);
end;

Questo è il test IDOR, cioè esattamente la falla del paragrafo precedente, catturata in tre righe. È anche il test che quasi nessuno scrive, perché un 200 per il proprietario dà la sensazione rassicurante che l’endpoint “funzioni”. La regola che la skill impone all’agente è netta: per ogni verbo di ogni risorsa che ha un proprietario, ci vuole il test che dimostra che un altro utente viene respinto. Una GET filtrata bene e una DELETE lasciata aperta sono comunque una violazione dei dati.

Il senso è tutto qui: chiedendo “scrivi i test di integrazione per gli endpoint Customers, compresi i casi di autorizzazione”, l’agente non produce solo dei test, produce i test che voi non avreste avuto voglia di scrivere. Ed è il tipo di lavoro in cui il codice economico è una benedizione vera, invece che un modo elegante per accumulare debito. La skill porta con sé anche scripts/run-tests.bat, così l’agente compila ed esegue la suite da solo, e vede il rosso prima di dirvi che ha finito.

Come installare le skill Delphi in Claude Code, Codex, Cursor e Gemini

Clonate il repository e lanciate lo script del vostro agente (Windows):

git clone https://github.com/danieleteti/delphi-ai-skills.git
cd delphi-ai-skills
install_in_claude.bat

Per Claude Code non serve altro: le skill vengono scoperte da sole. Per Codex, Cursor e Gemini CLI ci sono install_in_codex.bat, install_in_cursor.bat e install_in_gemini.bat, che copiano le skill e scrivono il puntatore nel file di istruzioni dell’agente (AGENTS.md, .cursor/rules/*.mdc, GEMINI.md), perché quegli agenti non le scoprono da soli.

Ogni script accetta un percorso di progetto, se preferite installare le skill dentro il repository e versionarle per tutto il team:

install_in_claude.bat C:\DEV\mio-progetto

Poi si crea il progetto con il wizard dell’IDE (File → New → Other → Delphi Projects → DelphiMVCFramework), lo si compila una volta, si lancia l’agente dentro quella cartella e si chiede quello che serve:

Aggiungi un controller Customers con CRUD completo, appoggiato a un’entità ActiveRecord sulla tabella customers

Un ultimo consiglio che fa una differenza notevole: se avete i sorgenti di DelphiMVCFramework su disco, ditelo all’agente (“i sorgenti DMVCFramework sono in C:\DEV\dmvcframework”). Le skill sanno di poter essere incomplete o superate, e in quel caso sono istruite a verificare invece di indovinare: leggono i sorgenti e i samples, e se ancora non sono sicure lo dicono, invece di inventare.

Una sessione vera, dall’inizio alla fine

La teoria è finita. Ecco com’è una sessione reale dentro un progetto generato dal wizard, con Claude Code. Non “chiamate” mai una skill: descrivete il compito, e la skill si carica da sola.

$ cd C:\DEV\OrdersAPI
$ claude

> aggiungi un controller Customers con CRUD completo, appoggiato a
  un'entità ActiveRecord sulla tabella customers

● Skill(dmvcframework)
  ⎿  SKILL.md caricata
  ⎿  reference/activerecord.md aperta (entità + mapping)
● Skill(dmvcframework-security)
  ⎿  SKILL.md caricata (l'endpoint accetta input dal client)

● Read(EngineConfigU.pas)    progetto wizard rilevato, backend Indy Direct
● Read(Controllers.Base.pas) stile di casa: functional action, IMVCResponse

● Write(Entities.Customer.pas)
● Write(Controllers.Customers.pas)
● Edit(EngineConfigU.pas)     +1 riga: AddController(TCustomersController)

  Fatto. Note:
  - GET /api/customers/($id) è filtrato sul cliente autenticato, non
    sul solo ID: un utente non può leggere la riga di un altro.
  - L'oggetto restituito da OKResponse è liberato dal framework:
    niente ToFree, sarebbe una doppia free.
  - Il campo "id" è escluso dalla deserializzazione (mass assignment).

Le tre note finali non sono cortesia: sono le regole delle skill che hanno lavorato mentre il codice nasceva. Un agente senza skill, sullo stesso prompt, vi avrebbe consegnato un GetByPK(ID) non filtrato, un ToFree di troppo e un DTO che si fa scrivere l’id dal client.

Si continua nella stessa conversazione, e la skill dei test entra in scena da sola:

> ora scrivi i test di integrazione, compresi i casi di autorizzazione

● Skill(dmvcframework-testing)
  ⎿  SKILL.md caricata

● Write(Tests.Server.pas)      IMVCServer in-process, niente WebModule
● Write(Tests.Customers.pas)   9 test: CRUD, 404, 422, 401, IDOR
● Bash(scripts\run-tests.bat)
  ⎿  Running... 9 tests, 8 passed, 1 FAILED
     [FAIL] User_Cannot_Read_Another_Users_Order
            expected 404, got 200

  Il test IDOR fallisce: OrdersController.GetOrder cerca ancora per
  sola PK. Lo correggo (era fuori dal perimetro che mi avevi dato,
  confermi?)

Questo è il punto in cui il giro si chiude: un test scritto dall’agente ha trovato una falla nel codice che l’agente non aveva scritto. Con la sola generazione di codice quel bug restava lì. È il motivo per cui, in un mondo di codice economico, le direttive e i test valgono più della velocità.

Lo stesso lavoro con Codex, Cursor, Gemini o qualunque altro agente

Le skill sono Markdown puro, senza sintassi proprietaria: il contenuto è identico su tutti gli agenti, cambia solo il modo in cui l’agente scopre che quei file esistono.

Con Codex la stessa sessione di prima ha la forma seguente: la richiesta è identica, e cambia solo la traccia con cui l’agente dichiara di aver letto la skill.

$ codex
> aggiungi un controller Customers con CRUD completo (DMVCFramework)

  Leggo skills/dmvcframework/SKILL.md, come richiesto da AGENTS.md.
  Questo endpoint riceve input dal client: leggo anche
  skills/dmvcframework-security/SKILL.md.
  ...

Attenzione a un dettaglio: negli agenti diversi da Claude Code il caricamento non è garantito, dipende da quanto quell’agente rispetta il proprio file di istruzioni. Per questo, con Codex, Cursor o Gemini, conviene nominare il framework nel prompt (“crea un controller DMVCFramework”, non “crea un controller”): è il trigger più forte. E se sospettate che la skill non sia stata caricata, ditelo esplicitamente:

Usa la skill dmvcframework. Poi crea il controller per Orders.

C’è anche un modo, di dieci secondi, per capire se l’agente che avete davanti è istruito oppure no. Chiedetegli:

In una functional action di DelphiMVCFramework, devo usare ToFree sull’oggetto che restituisco?

Se risponde no, perché il framework libera già l’oggetto restituito e ToFree lo libererebbe due volte, la skill è attiva. Se risponde di sì, il suo codice sta facendo una doppia free e voi lo scoprirete in produzione.

Domande frequenti su delphi-ai-skills

Che cos’è delphi-ai-skills? È un progetto open source (Apache-2.0) che raccoglie sette skill per agenti AI di coding, dedicate a DelphiMVCFramework. Una skill è un file Markdown che l’agente carica su richiesta e che gli insegna l’API reale del framework: unit, attributi, regole di ownership degli oggetti, idiomi e trappole note.

Con quali agenti AI funzionano? Claude Code, Codex, Cursor, Gemini CLI, Windsurf, Continue e qualunque agente in grado di leggere istruzioni in Markdown. Il repository include gli script di installazione per i primi quattro.

Perché un agente AI senza skill scrive codice Delphi che non compila? Perché scrive a memoria, e ricade sui pattern dei framework che ha visto molto di più, tipicamente ASP.NET Core. Genera così nomi plausibili ma inesistenti, per esempio MapGroup invece di Prefix o OkResponse invece di Ok, e un ToFree sull’oggetto restituito che causa una doppia free, dato che a liberarlo pensa già il framework.

Le skill si occupano anche di sicurezza? Sì, ed è la parte più importante. dmvcframework-security è una dipendenza obbligatoria di tutte le skill server: si applica a qualunque endpoint riceva input da un client. Copre access control e IDOR, mass assignment, SQL injection, XSS in TemplatePro, CSRF, path traversal, upload, SSRF e open redirect, header di sicurezza, hardening del JWT e gestione dei segreti.

Le skill sanno scrivere i test? Sì, con lo stack di test reale del framework: DUnitX come runner, un IMVCServer in-process con Indy Direct e IMVCRESTClient come client HTTP, senza server esterni e senza WebModule, anche quando in produzione l’applicazione gira come ISAPI o come modulo Apache. Coprono i test CRUD, quelli di autenticazione e i test di autorizzazione (IDOR).

Le skill creano il progetto Delphi da zero? No, ed è una scelta. Il progetto va creato con il wizard dell’IDE, compilato una volta, e solo allora si lancia l’agente dentro quella cartella. Le skill riconoscono il layout del wizard e aggiungono funzionalità dentro di esso, invece di inventare un bootstrap mezzo corretto.

Funzionano su un progetto WebBroker o ISAPI esistente? Sì. Il backend di default per un progetto nuovo è Indy Direct, ma un progetto WebBroker esistente (ISAPI sotto IIS, modulo Apache) è pienamente supportato: le skill riconoscono l’host, lo mantengono e non propongono mai una migrazione. Tutto ciò che sta sopra l’host, cioè controller, routing, ActiveRecord, validazione, DI e middleware, è identico su ogni backend.

Versione 0.1.0 delle Delphi AI Skills, e la strada davanti

È una prima release. Le skill sono scritte e verificate su DelphiMVCFramework 3.5.0, ma non hanno ancora attraversato decine di progetti reali: aspettatevi qualche spigolo, e per favore segnalatelo. Finché siamo in 0.x la forma stessa dell’insieme è da considerarsi instabile: le skill potranno essere divise, unite, rinominate o rimosse man mano che l’uso vero mostrerà cosa serve davvero.

Il criterio per contribuire è uno solo, e non è negoziabile: ogni affermazione deve essere verificabile sui sorgenti o su un sample di DelphiMVCFramework, citando il file. Nessun nome di API scritto a memoria, mai. È esattamente la disciplina che chiediamo agli agenti, e sarebbe curioso non applicarla a noi.

Il progetto è qui: github.com/danieleteti/delphi-ai-skills. Issue e pull request sono benvenute.

Scrivere codice, ormai, è la parte facile. Decidere che codice si vuole, e far sì che sia quello che esce anche quando a scriverlo è una macchina, è il mestiere che resta. Le Delphi AI Skills servono a questo: dare a un agente AI le direttive, lo stile, la sicurezza e i test con cui vogliamo che il codice Delphi nasca.