Guida SPRIX e skill Claude Code auto-aggiornata per sviluppo su Mexal/Passepartout

Contesto

SPRIX è il linguaggio di scripting proprietario di Mexal/Passepartout, gestionale diffusissimo nelle PMI italiane. Due dialetti da padroneggiare — SPRIX "puro" per generare report, procedure batch e automazioni stand-alone, e SPRIX Collage per eventi dentro Mexal (apertura documento, salvataggio, navigazione tra anagrafiche) con accesso all'archivio aperto nella sessione — più le WebAPI per integrazioni esterne. Chi ci sviluppa ha tre scomode realtà con cui confrontarsi: manuali ufficiali enormi (683 pagine solo per il Manuale SPRIX, 123 per le WebAPI), campi che cambiano nome tra una release e l'altra senza che la documentazione si aggiorni subito, e una community italiana molto ristretta che condivide poco. Il risultato è che ogni volta che si entra in un progetto Mexal — dopo mesi passati su altro — si perde una giornata a riorientarsi.

Nota di posizionamento: questa guida nasce come appunti personali dal campo per il mio uso quotidiano come sviluppatore interno su Mexal. Non sono un partner certificato Passepartout né un implementor commerciale — quello che trovate qui e nella skill Claude Code associata è competenza maturata sviluppando sul gestionale in licenza delle aziende per cui lavoro.

Sfida

Costruire un riferimento che fosse consultabile in minuti, non in ore, scritto dal campo (con le trappole reali del linguaggio e delle API), e che non invecchiasse a ogni release Passepartout. Ma soprattutto: che fosse integrato nel mio flusso di lavoro quotidiano con Claude Code, non un PDF da aprire a parte o un sito esterno da consultare.

Approccio

Il progetto ha due facce complementari: la guida markdown (guida_sprix/) e la skill Claude Code (mexal-webapi/) che la rende richiamabile in automatico. Cinque feature che fanno di questo un asset diverso dal classico "blog tecnico".

Skill Claude Code auto-caricata su ogni progetto Mexal

Ho installato la skill in ~/.claude/skills/mexal-webapi/, con un SKILL.md che dichiara scopo, trigger e istruzioni, e una cartella references/ di circa 1.400 righe su sei file (endpoints.md, filtri-e-campi.md, errori-comuni.md, logica-gestionale.md, sprix-callwebsvc.md, changelog-skill.md). Il mio CLAUDE.md globale ha una regola esplicita: quando Claude Code riconosce un progetto che tocca Mexal (WebAPI, SPRIX, CALLWEBSVC), deve leggere SKILL.md prima di rispondere. Significa che ogni volta che apro un progetto gestionale — mio, di un cliente, o un nuovo — Claude ha in contesto il catalogo endpoint, i pattern, gli errori noti e le configurazioni aziendali, senza che io debba incollare nulla. La conoscenza è già nel sedile del conducente.

/mexal-discover: discovery live delle WebAPI che scrive sulla skill

Uno slash command (/mexal-discover [azienda] [--endpoint risorse/clienti] [--all]) che si connette alle WebAPI Mexal dell'installazione reale (via curl -k per gestire il certificato self-signed), chiama /risorse/help per elencare gli endpoint disponibili, poi interroga ciascuno con ?info=true per estrarne lo schema dei campi. I file references/filtri-e-campi.md, references/endpoints.md e references/discovery-log.md vengono aggiornati automaticamente, con segnalazione esplicita di novità e rimozioni rispetto allo stato precedente. Il comando riconcilia la documentazione con la realtà: dove il manuale ufficiale e il comportamento effettivo divergono, vince il live.

/mexal-changelog: parsing dei PDF di release Passepartout

Secondo slash command (/mexal-changelog [path/al/ManWebAPI_vX.XX.pdf]) che legge il PDF di changelog ufficiale in blocchi da 20 pagine, estrae nuovi endpoint, campi aggiunti, servizi introdotti, rinominazioni e deprecazioni, e aggiorna SKILL.md, endpoints.md, filtri-e-campi.md, errori-comuni.md, più un changelog-skill.md che tiene lo storico delle versioni della skill agganciato alle versioni del manuale. Quando Passepartout rilascia la v2.33, non devo rileggermi 60 pagine di novità: lancio il comando e la skill si allinea.

Mappa relazioni campi-tabelle costruita a mano

Nel file webapi/mexal_api_helper.py ho codificato una mappa manuale dei campi foreign-key dentro Mexal — quale campo di quale endpoint punta a quale altro endpoint (es. cod_conto su un documento → /risorse/clienti). È informazione che le API live non espongono: va ricavata leggendo il gestionale in produzione e annotando i collegamenti. Questa mappa è la parte che un altro consulente non può estrarre da nessuna documentazione — è esperienza compressa.

Trappole SPRIX documentate come prima cosa

La guida privilegia i bug-trap reali del linguaggio rispetto alla teoria: il limite di 12 caratteri sui nomi variabile, l'assenza del costrutto WHILE (serve FOR con uscita esplicita), la differenza sostanziale tra SPRIX e COLLAGE (due dialetti con semantica diversa), le condizioni case-sensitive nei filtri WebAPI (contiene sì, Contiene no), i campi rinominati tra versioni (nota vs note). Dodici errori documentati in 06_errori_comuni.md sono quelli in cui ho visto perdere ore a me stesso e ad altri.

Copertura quantificata

Trentadue endpoint WebAPI documentati in cinque categorie (risorse anagrafiche, documenti, servizi, dati generali, DocuVision). Ventotto servizi speciali invocabili via POST /webapi/servizi. Diciotto esempi SPRIX completi copiabili. I 683 PDF del manuale SPRIX convertiti in testo e indicizzati. Quattro linguaggi di esempio nelle chiamate: SPRIX nativo, TypeScript, PHP, Python.

Risultato

La guida è alla versione 1.2 (ottobre 2025), la skill alla 2.0 — generate in parte dai miei stessi comandi /mexal-changelog e /mexal-discover. Uso questo sistema ogni giorno: ogni volta che riprendo un progetto Mexal, Claude Code ha in contesto le informazioni giuste prima di scrivere la prima riga, e quando Passepartout aggiorna il gestionale lancio un comando e mi allineo.

Il valore non è tecnico, è di posizionamento. Nella nicchia italiana dello sviluppo su Mexal la documentazione condivisa è scarsa, in inglese ancora meno. Avere un asset vivo, pubblicamente leggibile, agganciato al workflow di Claude Code, è il tipo di prova tangibile di competenza che fa la differenza quando un potenziale cliente cerca "qualcuno che capisce SPRIX e AI-assisted development" — intersezione dove in Italia siamo davvero in pochi.